debian/cdesktop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2ebfcd0e8a7427b2d0475fac086c4ecb2ccef8d7
cdesktop/cde/doc/C/guides/man/m3_csa/free_tim.sgm

278 lines
9.3 KiB
Plaintext
Raw Blame History

<!-- $XConsortium: free_tim.sgm /main/4 1996/08/30 15:34:51 rws $ -->
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
<!-- (c) Copyright 1995 International Business Machines Corp. -->
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
<!-- (c) Copyright 1995 Novell, Inc. -->
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
<!-- (c) Copyright 1995 Hitachi. -->
<RefEntry Id="CDEMX.MAN58.rsml.1">
<RefMeta>
<RefEntryTitle>csa_free_time_search</RefEntryTitle>
<ManVolNum>library call</ManVolNum>
</RefMeta>
<RefNameDiv>
<RefName><Function>csa_free_time_search</Function></RefName>
<RefPurpose>searches one or more calendars for available free time
</RefPurpose>
</RefNameDiv>
<!-- CDE Common Source Format, Version 1.0.0-->
<!-- (c) Copyright 1993, 1994, 1995 Hewlett-Packard Company-->
<!-- (c) Copyright 1993, 1994, 1995 International Business Machines Corp.-->
<!-- (c) Copyright 1993, 1994, 1995 Sun Microsystems, Inc.-->
<!-- (c) Copyright 1993, 1994, 1995 Novell, Inc.-->
<!-- (c) Copyright 1994 X.400 API Association-->
<RefSynopsisDiv>
<FuncSynopsis Remap="ANSI">
<FuncSynopsisInfo>#include &lt;xcsa.h>
</FuncSynopsisInfo>
<FuncDef>CSA_return_code <Function>csa_free_time_search</Function></FuncDef>
<ParamDef>CSA_session_handle <Parameter>session</Parameter></ParamDef>
<ParamDef>CSA_date_time_range <Parameter>date_time_range</Parameter></ParamDef>
<ParamDef>CSA_time_duration <Parameter>time_duration</Parameter></ParamDef>
<ParamDef>CSA_uint32 <Parameter>number_users</Parameter></ParamDef>
<ParamDef>CSA_calendar_user *<Parameter>calendar_users</Parameter></ParamDef>
<ParamDef>CSA_free_time **<Parameter>free_time</Parameter></ParamDef>
<ParamDef>CSA_extension *<Parameter>free_time_search_extensions</Parameter></ParamDef>
</FuncSynopsis>
</RefSynopsisDiv>
<RefSect1>
<Title>DESCRIPTION</Title>
<Para>The
<Function>csa_free_time_search</Function> function searches for available free time on one or more
calendars and returns a list of free time intervals found.
Free time is an interval of time that is not currently
scheduled on one or more calendars.
The free time search
is based on a date and time range and the minimum time
duration required of the free time interval.
Only the
owner of the calendar, users with
<SystemItem Class="Constant">CSA_FREE_TIME_SEARCH,</SystemItem> users with
<SystemItem Class="Constant">CSA_VIEW_PUBLIC_ENTRIES,</SystemItem> users with
<SystemItem Class="Constant">CSA_VIEW_CONFIDENTIAL_ENTRIES,</SystemItem> or users with
<SystemItem Class="Constant">CSA_VIEW_PRIVATE_ENTRIES</SystemItem> can search the calendar for free time.
</Para>
</RefSect1>
<RefSect1>
<Title>ARGUMENTS</Title>
<RefSect2>
<Title>Session (Session Handle)</Title>
<Para>Opaque session handle that represents a session with the
calendaring service.
</Para>
<Para>Session handles are created by a logon function call and
invalidated with a logoff function call.
If the session
handle is invalid, then the error
<SystemItem Class="Constant">CSA_E_INVALID_SESSION_HANDLE</SystemItem> is returned.
</Para>
</RefSect2>
<RefSect2>
<Title>Date Time Range (Date Time Range)</Title>
<Para>Specifies the start and stop date and time range for the
free time search.
If the date_time_range is invalid, then
the error
<SystemItem Class="Constant">CSA_E_INVALID_DATE_TIME</SystemItem> is returned.
</Para>
</RefSect2>
<RefSect2>
<Title>Time Duration (Time Duration)</Title>
<Para>Specifies the minimum time range for the free time
intervals to be sought.
If the time duration is invalid,
then the error
<SystemItem Class="Constant">CSA_E_INVALID_DATE_TIME</SystemItem> is returned.
</Para>
</RefSect2>
<RefSect2>
<Title>Number Users (Uint32)</Title>
<Para>The number of elements in the
<Emphasis>calendar_users</Emphasis> argument.
</Para>
</RefSect2>
<RefSect2>
<Title>Calendar Users (Calendar User)</Title>
<Para>A pointer to an array of calendar users.
This specifies
the calendars to be searched for available free time.
If
the user does not have authority to access any of the
attendee's calendars, then the error
<SystemItem Class="Constant">CSA_E_NO_AUTHORITY</SystemItem> is returned.
If an invalid attendee is specified, then the
error
<SystemItem Class="Constant">CSA_E_INVALID_USER</SystemItem> is returned.
It is implementation specific whether the
seach function will proceed in any of these cases.
</Para>
</RefSect2>
<RefSect2>
<Title>Free Time Search Extensions (Extension)</Title>
<Para>A pointer to an array of
<StructName Role="typedef">CSA_extension</StructName> structures for this function.
The array may contain both
input extensions for providing additional information to
the function and output extensions for receiving
information from the function.
A value of
<SystemItem Class="Constant">NULL</SystemItem> indicates that the caller is not using any extensions.
See the extensions structure for more information.
</Para>
</RefSect2>
</RefSect1>
<RefSect1>
<Title>RETURN VALUE</Title>
<RefSect2>
<Title>Free Time (Free Time)</Title>
<Para>A pointer to a free time structure that specifies a set of
free time intervals.
If more free time intervals are found than can be
represented in the available memory, the
<SystemItem Class="Constant">CSA_E_INSUFFICIENT_MEMORY</SystemItem> error message will be returned.
If no available free time
is found, then a
<SystemItem Class="Constant">NULL</SystemItem> pointer will be returned.
This structure is allocated by
the service, and should be freed with a single call to
&cdeman.csa.free;.</Para>
</RefSect2>
<RefSect2>
<Title>Free Time Search Extensions (Extension)</Title>
<Para>If output extensions were passed to the function in the
extensions list, the results from the service will be
available in the extension.
See the extensions structure for more information.
Whether the function succeeded or
not, and, if not, why.
It may be success or one of the
values listed under ERRORS below.
</Para>
</RefSect2>
</RefSect1>
<RefSect1>
<Title>ERRORS</Title>
<Para>The
<Function>csa_free_time_search</Function> function returns the following error values:
</Para>
<VariableList>
<VarListEntry>
<Term>CSA_E_FAILURE</Term>
<ListItem>
<Para>There was a general failure that does not
fit the description of any other error code.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INSUFFICIENT_MEMORY</Term>
<ListItem>
<Para>Insufficient memory was available to complete the requested operation.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_DATA_EXT</Term>
<ListItem>
<Para>The data extension requested is invalid.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_DATE_TIME</Term>
<ListItem>
<Para>An invalid date and time combination was specified.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_FLAG</Term>
<ListItem>
<Para>A flag value in the
<Symbol Role="Variable">flags</Symbol> argument was invalid.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_FUNCTION_EXT</Term>
<ListItem>
<Para>The function extension requested is invalid.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_PARAMETER</Term>
<ListItem>
<Para>A function parameter was invalid.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_SESSION_HANDLE</Term>
<ListItem>
<Para>The specified Session Handle is invalid or no longer valid
(e.g., after logging off).
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_INVALID_USER</Term>
<ListItem>
<Para>The specified calendar user is invalid.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_NO_AUTHORITY</Term>
<ListItem>
<Para>The user has insufficient authority for this function.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_NOT_SUPPORTED</Term>
<ListItem>
<Para>The operation requested is not supported by this implementation.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_SERVICE_UNAVAILABLE</Term>
<ListItem>
<Para>The requested calendar service is unavailable.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_UNSUPPORTED_DATA_EXT</Term>
<ListItem>
<Para>The data extension requested is not supported.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_UNSUPPORTED_FLAG</Term>
<ListItem>
<Para>The flag requested is not supported.
</Para>
</ListItem>
</VarListEntry>
<VarListEntry>
<Term>CSA_E_UNSUPPORTED_FUNCTION_EXT</Term>
<ListItem>
<Para>The specified function extension is not supported or
<SystemItem Class="Constant">CSA_EXT_REQUIRED</SystemItem> is set.
</Para>
</ListItem>
</VarListEntry>
</VariableList>
</RefSect1>
<RefSect1>
<Title>SEE ALSO</Title>
<Para>&cdeman.csa.csa.h;, &cdeman.csa.add.calendar;, &cdeman.csa.add.entry;, &cdeman.csa.call.callbacks;, &cdeman.csa.delete.calendar;, &cdeman.csa.delete.entry;, &cdeman.csa.free;, &cdeman.csa.list.calendar.attributes;, &cdeman.csa.list.calendars;, &cdeman.csa.list.entries;, &cdeman.csa.list.entry.attributes;, &cdeman.csa.list.entry.sequence;, &cdeman.csa.logoff;, &cdeman.csa.logon;, &cdeman.csa.look.up;, &cdeman.csa.query.configuration;, &cdeman.csa.read.calendar.attributes;, &cdeman.csa.read.entry.attributes;, &cdeman.csa.read.next.reminder;, &cdeman.csa.register.callback;, <![ %CDE.C.XO; [&cdeman.csa.restore;, &cdeman.csa.save;, ]]>&cdeman.csa.unregister.callback;, &cdeman.csa.update.calendar.attributes;, &cdeman.csa.update.entry.attributes;.</Para>
</RefSect1>
</RefEntry>
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 01:31:55-->
Reference in New Issue View Git Blame Copy Permalink