1442 lines
60 KiB
Plaintext
1442 lines
60 KiB
Plaintext
<!-- $XConsortium: ch10.sgm /main/7 1996/10/30 15:28:15 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. -->
|
|
<Chapter Id="PG.calmg.div.1">
|
|
<Title Id="PG.calmg.mkr.1">Integrating with Calendar</Title>
|
|
<Para>The Calendar application program interface (API) provides a programmatic
|
|
way to access and manage calendar data in a networked environment. The API
|
|
supports inserting, deleting, and modifying of entries as well as browse and
|
|
find capabilities. It also supports calendar administration functions.</Para>
|
|
<Para>The Calendar API is an implementation of the X.400 Application Programming
|
|
Interface Association's (XAPIA) Calendaring and Scheduling API (CSA API).<IndexTerm>
|
|
<Primary>CSA API</Primary>
|
|
</IndexTerm>
|
|
CSA API defines a set of high-level functions so that applications that are
|
|
calendar enabled can access the varied features of the calendaring and
|
|
scheduling service. For more information about the latest XAPIA Specification,
|
|
contact the X.400 API Association, 800 El Camino Real, Mountain View,
|
|
California 94043.</Para>
|
|
<Para>This chapter describes the Calendar API in these sections:</Para>
|
|
<InformalTable Id="PG.calmg.itbl.1" Frame="All">
|
|
<TGroup Cols="1">
|
|
<ColSpec Colname="1" Colwidth="4.0 in">
|
|
<TBody>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Library and Header Files140'--><XRef Role="JumpText" Linkend="PG.dndPG.mkr.3"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Demo Program140'--><XRef Role="JumpText" Linkend="PG.dndPG.mkr.4"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Using the Calendar API140'--><XRef Role="JumpText" Linkend="PG.calmg.mkr.4"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Overview of the CSA API140'--><XRef Role="JumpText" Linkend="PG.calmg.mkr.5"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Functional Architecture142'--><XRef Role="JumpText" Linkend="PG.calmg.mkr.8"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Data Structures149'--><XRef Role="JumpText" Linkend="PG.calmg.mkr.12"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Calendar Attributes150'--><XRef Role="JumpText" Linkend="PG.calmg.mkr.14"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Entry Attributes152'--><XRef Role="JumpText" Linkend="PG.calmg.mkr.16"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'General Information about Functions155'--><XRef Role="JumpText" Linkend="PG.calmg.mkr.19"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Administration Functions157'--><XRef Role="JumpText" Linkend="PG.calmg.mkr.20"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Calendar Management Functions158'--><XRef Role="JumpText" Linkend="PG.calmg.mkr.21"></Para></Entry>
|
|
</Row>
|
|
<Row Rowsep="1">
|
|
<Entry><Para><!--Original XRef content: 'Entry Management Functions160'--><XRef Role="JumpText" Linkend="PG.calmg.mkr.22"></Para></Entry>
|
|
</Row>
|
|
</TBody>
|
|
</TGroup>
|
|
</InformalTable>
|
|
<Sect1 Id="PG.calmg.div.2">
|
|
<Title Id="PG.calmg.mkr.2">Library and Header Files</Title>
|
|
<Para>To use the Calendar API, you need to link to the <Command><IndexTerm>
|
|
<Primary><Filename>libDtCalendar<Default Para Font> library</Primary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>library<Filename>libDtCalendar<Default Para Font></Primary>
|
|
</IndexTerm>libcsa</Command> library. The header
|
|
file is <Filename><IndexTerm>
|
|
<Primary>header file</Primary>
|
|
<Secondary><Filename>Dt/xcsa.h<Default Para Font></Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary><Filename>Dt.Xcsa.h<Default Para Font> header file</Primary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>header file</Secondary>
|
|
</IndexTerm>csa/csa.h</Filename>.</Para>
|
|
</Sect1>
|
|
<Sect1 Id="PG.calmg.div.3">
|
|
<Title Id="PG.calmg.mkr.3">Demo Program<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>demo program</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>demo program</Primary>
|
|
<Secondary>Calendar</Secondary>
|
|
</IndexTerm></Title>
|
|
<Para>A demo program containing an example of how to use the Calendar API is in
|
|
<Filename>/usr/dt/examples/dtcalendar</Filename>.</Para>
|
|
</Sect1>
|
|
<Sect1 Id="PG.calmg.div.4">
|
|
<Title Id="PG.calmg.mkr.4">Using the Calendar API</Title>
|
|
<Sect2 Id="PG.calmg.div.5" Role="Procedure">
|
|
<Title>How to Integrate with Calendar</Title>
|
|
<Para>The Calendar API provides a way to access and manage calendar data in a
|
|
networked environment.</Para>
|
|
<OrderedList>
|
|
<ListItem>
|
|
<Para>Include <Filename>csa/csa.h</Filename> in your application.<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>header file</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>header file, Calendar</Primary>
|
|
</IndexTerm>
|
|
</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Use the calendar API to incorporate the calendar operations you want in
|
|
your application.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Link with <Command>libcsa</Command>.<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>library</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>library</Primary>
|
|
<Secondary>Calendar</Secondary>
|
|
</IndexTerm>
|
|
</Para>
|
|
</ListItem>
|
|
</OrderedList>
|
|
</Sect2>
|
|
</Sect1>
|
|
<Sect1 Id="PG.calmg.div.6">
|
|
<Title Id="PG.calmg.mkr.5">Overview of the CSA API<IndexTerm>
|
|
<Primary>CSA API, overview</Primary>
|
|
</IndexTerm></Title>
|
|
<Para>The CSA interface enables a common interface to a calendaring and scheduling
|
|
service. For each CSA implementation, the view and capabilities presented by
|
|
CSA must be mapped to the view and capabilities of the underlying
|
|
calendaring service. The interface is designed to be independent of the actual
|
|
calendaring and scheduling implementation. The interface is also designed to
|
|
be independent of the operating system and underlying hardware used by the
|
|
calendaring service.</Para>
|
|
<Para>The number of function calls provided is minimal. A single set of functions
|
|
manage multiple types of calendar entries.</Para>
|
|
<Sect2 Id="PG.calmg.div.7">
|
|
<Title Id="PG.calmg.mkr.6">C Naming Conventions<IndexTerm>
|
|
<Primary>CSA</Primary>
|
|
<Secondary>C naming conventions</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>naming conventions, C</Primary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>C naming conventions</Primary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>naming conventions</Secondary>
|
|
</IndexTerm></Title>
|
|
<Para>The identifier for an element of the C interface is derived from the generic
|
|
name of the element and its associated data type, as specified in
|
|
<!--Original XRef content: 'Table 10‐1'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.calmg.mkr.7">. The
|
|
generic name is prefixed with the character string in the second column of the
|
|
table; alphabetic characters are converted to the case in the third column.</Para>
|
|
<Table Id="PG.calmg.tbl.1" Frame="Topbot">
|
|
<Title Id="PG.calmg.mkr.7">Derivation of C Naming Conventions</Title>
|
|
<TGroup Cols="3">
|
|
<ColSpec Colname="1" Colwidth="3.09722 in">
|
|
<ColSpec Colname="2" Colwidth="1.125 in">
|
|
<ColSpec Colname="3" Colwidth="0.75 in">
|
|
<THead>
|
|
<Row>
|
|
<Entry><Para><Literal>Element Type</Literal></Para></Entry>
|
|
<Entry><Para><Literal>Prefix</Literal></Para></Entry>
|
|
<Entry><Para><Literal>Case</Literal></Para></Entry>
|
|
</Row>
|
|
</THead>
|
|
<TBody>
|
|
<Row>
|
|
<Entry><Para>Data type</Para></Entry>
|
|
<Entry><Para><Filename>CSA_</Filename></Para></Entry>
|
|
<Entry><Para>Lower</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Data value</Para></Entry>
|
|
<Entry><Para><Filename>CSA_</Filename></Para></Entry>
|
|
<Entry><Para>Upper</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Function</Para></Entry>
|
|
<Entry><Para><Filename>csa_</Filename></Para></Entry>
|
|
<Entry><Para>Lower</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Function argument</Para></Entry>
|
|
<Entry><Para><Command>none</Command></Para></Entry>
|
|
<Entry><Para>Lower</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Function result</Para></Entry>
|
|
<Entry><Para><Command>none</Command></Para></Entry>
|
|
<Entry><Para>Lower</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Constant</Para></Entry>
|
|
<Entry><Para><Filename>CSA_</Filename></Para></Entry>
|
|
<Entry><Para>Upper</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Error</Para></Entry>
|
|
<Entry><Para><Filename>CSA_E_</Filename></Para></Entry>
|
|
<Entry><Para>Upper</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Macro</Para></Entry>
|
|
<Entry><Para><Filename>CSA_</Filename></Para></Entry>
|
|
<Entry><Para>Upper</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Reserved for extension sets</Para></Entry>
|
|
<Entry><Para><Filename>CSA_XS_</Filename></Para></Entry>
|
|
<Entry><Para>Any</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Reserved for extensions</Para></Entry>
|
|
<Entry><Para><Filename>CSA_X_</Filename></Para></Entry>
|
|
<Entry><Para>Any</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Reserved for use by implementors</Para></Entry>
|
|
<Entry><Para><Command>CSAP</Command></Para></Entry>
|
|
<Entry><Para>Any</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Reserved for vendor function extensions</Para></Entry>
|
|
<Entry><Para>csa_x</Para></Entry>
|
|
<Entry><Para>Lower</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Structure Tag</Para></Entry>
|
|
<Entry><Para><Filename>CSA_TAG_</Filename></Para></Entry>
|
|
<Entry><Para>Upper</Para></Entry>
|
|
</Row>
|
|
</TBody>
|
|
</TGroup>
|
|
</Table>
|
|
<Para>Elements with the prefix <Command>CSAP</Command> (any case) are reserved for internal proprietary
|
|
use by implementors of the CSA service. They are not intended for direct use
|
|
by programs written using the CSA interface.</Para>
|
|
<Para>The prefixes <Filename>CSA_XS_</Filename>, <Filename>CSA_X_</Filename> (in either uppercase or lowercase), and <Filename>csa_x</Filename>
|
|
are reserved for extensions of the interface by vendors or groups. The
|
|
specification defines these interface extensions as extensions to the base set of
|
|
functions.</Para>
|
|
<Para>For constant data values, an additional string is usually appended to <Filename>CSA_</Filename> to
|
|
indicate the data structure or function for the constant data value.</Para>
|
|
</Sect2>
|
|
</Sect1>
|
|
<Sect1 Id="PG.calmg.div.8">
|
|
<Title Id="PG.calmg.mkr.8">Functional Architecture<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>architecture</Secondary>
|
|
</IndexTerm></Title>
|
|
<Para>This section describes the functional architecture of services supporting the
|
|
CSA API. It provides an abstract implementation model, an abstract data
|
|
model, and a functional overview.</Para>
|
|
<Sect2 Id="PG.calmg.div.9">
|
|
<Title>Implementation Model<IndexTerm>
|
|
<Primary>CSA</Primary>
|
|
<Secondary>implementation model</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>implementation model, CSA</Primary>
|
|
</IndexTerm></Title>
|
|
<Para>The abstract implementation model is provided as a reference aid to help you
|
|
understand the scope of the CSA API.</Para>
|
|
<Para>The CSA interface is defined between a calendar-enabled application and a
|
|
calendaring service. All functions in this interface are designed to be
|
|
independent of the calendaring service; however, the API does allow protocol-
|
|
specific extensions to the common functions to be invoked through the use of
|
|
extensions. See
|
|
<!--Original XRef content: '&xd2;Extensions'--><XRef Role="SectionTitle" Linkend="PG.calmg.mkr.11"> for more information. The relationship of the CSA
|
|
interface to a calendar-enabled application and the calendar service is shown in
|
|
<!--Original XRef content: 'Figure 10‐1'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.calmg.mkr.9">.</Para>
|
|
<Figure>
|
|
<Title Id="PG.calmg.mkr.9">Positioning of the Calendaring and Scheduling API</Title>
|
|
<Graphic Entityref="PG.calmg.fig.1" Id="PG.calmg.grph.1"></Graphic>
|
|
</Figure>
|
|
<Para>The model of the CSA interface can be divided into three components:
|
|
administration, calendar management, and entry management. These
|
|
components are shown in
|
|
<!--Original XRef content: 'Figure 10‐2'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.calmg.mkr.10">.</Para>
|
|
<Figure>
|
|
<Title Id="PG.calmg.mkr.10">Components of the Calendaring and Scheduling API<IndexTerm>
|
|
<Primary>Calendar API</Primary>
|
|
<Secondary>components</Secondary>
|
|
</IndexTerm></Title>
|
|
<Graphic Entityref="PG.calmg.fig.2" Id="PG.calmg.grph.2"></Graphic>
|
|
</Figure>
|
|
<Para>Access to the calendaring service is established through a calendaring session.
|
|
The session provides for a valid connection to the calendaring service and
|
|
assists in ensuring the integrity of the calendaring information maintained by
|
|
the service. A calendar-enabled application logs on to an individual calendar
|
|
within the calendaring service to establish a valid session or connection. The
|
|
session is terminated by the calendar-enabled application logging off from the
|
|
calendar.</Para>
|
|
<Para>The calendaring service maintains one or more calendars. The calendar service
|
|
provides some level of administration support for these calendars. A calendar-
|
|
enabled application might access a list of the calendars maintained by a
|
|
particular calendar service. In addition, the calendar service might provide
|
|
support for the archive and restore of calendar information into some
|
|
implementation-specific, persistent format. Where a calendar service provides
|
|
support for maintaining more than one calendar, support functions are defined
|
|
for creating and deleting calendars. In addition, functions are provided to
|
|
support administering the characteristics of the calendar.</Para>
|
|
<Para>The majority of the functions within the CSA interface manage individual
|
|
calendar entries. Calendar entries may be either events, to dos, or memos.
|
|
Entries can be added, deleted, updated, and read from a particular calendar. A
|
|
calendar-enabled application can also add reminders to calendar entries.</Para>
|
|
</Sect2>
|
|
<Sect2 Id="PG.calmg.div.10">
|
|
<Title>Data Model<IndexTerm>
|
|
<Primary>Calendar API</Primary>
|
|
<Secondary>data model</Secondary>
|
|
</IndexTerm></Title>
|
|
<Para>The CSA interface is an access method to a conceptual back-end store of
|
|
calendaring information that is maintained by a calendaring service. A
|
|
common data model is helpful in visualizing the components of the
|
|
calendaring information maintained by a calendaring service.</Para>
|
|
<Sect3 Id="PG.calmg.div.11">
|
|
<Title>Calendar Entities<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>entities</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>entities, Calendar</Primary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>2</Primary>
|
|
</IndexTerm></Title>
|
|
<Para>The data model is based on the concept of a calendar entity. The calendar is
|
|
represented by a named collection of administrative calendar attributes and
|
|
calendar entries. A calendar is owned by an individual user. The user could
|
|
represent a person, a group of people, or a resource.</Para>
|
|
<Para>The calendar attributes are a set of named values that may represent common,
|
|
implementation-specific, or application-specific administrative characteristics
|
|
about the calendar. For example, time zone, name, owner, and access rights to
|
|
the calendar can be specified in individual calendar attributes.</Para>
|
|
<Para>The calendar entries are the primary components of a calendar. The three
|
|
classes of calendar entries follow:</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para>Events</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>To Dos</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Memos</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
<Para>Calendar entries are represented by a uniquely named collection of entry
|
|
attributes. The entry attributes are a set of named values that represent
|
|
common, implementation-specific, or application-specific characteristics of the
|
|
calendar entry. For example, an event might contain a start and end date and
|
|
time, a description, and a subtype. A to do might contain the date it was
|
|
created, the due date, a priority, and a status. A memo might contain the date
|
|
it was created and a text content or description.</Para>
|
|
<Para>The calendar attributes and entry attributes consist of a name, type, and value
|
|
tuple. Common attributes defined by the specification can be extended.
|
|
Implementations can define implementation-specific attributes. In addition,
|
|
some implementations may provide the capability for applications to define
|
|
application-specific attributes. The CDE implementation supports application
|
|
defined attributes.</Para>
|
|
</Sect3>
|
|
<Sect3 Id="PG.calmg.div.12">
|
|
<Title>Access Rights<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>access rights</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>access rights, Calendar</Primary>
|
|
</IndexTerm></Title>
|
|
<Para>The accessibility of a calendar to an individual user can be controlled by the
|
|
access rights given that user. Access rights are paired with a calendar user.
|
|
CSA allows users to be an individual, group, or resource. The CDE
|
|
implementation only supports individual users. The access rights are
|
|
maintained in an access list. The access list is a particular calendar attribute.
|
|
The access rights are individually controlled and can be accumulated to define
|
|
a range of accessibility of a user to a calendar and its entries. The access rights
|
|
can also be specified in terms of the following access roles:</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para>The owner of a calendar</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>The organizer of a particular entry within the calendar</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>The sponsor of a particular entry within the calendar</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
<Para>The owner role enables the user to do anything to the calendar or calendar
|
|
entries that the owner of the calendar can do, including deleting the calendar;
|
|
viewing, inserting, and changing calendar attributes; adding and deleting
|
|
calendar entries; and viewing, inserting, and changing entry attributes.</Para>
|
|
<Para>The organizer role enables the user to delete the entry or view and change
|
|
entry attributes of those calendar entries for which the user is specified as the
|
|
organizer. The organizer defaults to the calendar user who created the entry.</Para>
|
|
<Para>The sponsor role enables the user to delete the entry or view and change entry
|
|
attributes for those calendar entries for which the user is specified as the
|
|
sponsor. The sponsor is the calendar user who effectively owns the calendar
|
|
entry.</Para>
|
|
<Para>In addition to these roles, an access right can be set to limit access to free time
|
|
searches; view, insert, or change calendar attributes; or view, insert or change
|
|
entries, depending on whether they are classified as public, confidential, or
|
|
private. The entry classification acts as a secondary filter on accessibility.</Para>
|
|
</Sect3>
|
|
</Sect2>
|
|
<Sect2 Id="PG.calmg.div.13">
|
|
<Title>Functional Overview</Title>
|
|
<Para>The CSA interface supports three principle types of tasks:</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para>Administration</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Calendar management</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Entry management</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
<Sect3 Id="PG.calmg.div.14">
|
|
<Title>Administration<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>administration</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>administration, Calendar</Primary>
|
|
</IndexTerm></Title>
|
|
<Para>Most of the CSA function calls occur within a calendar session. The calendar
|
|
session is a logical connection between the calendar-enabled application and a
|
|
particular calendar maintained by the calendaring service. A session is
|
|
established with a call to the <Filename>csa_logon()</Filename> function and terminated with a
|
|
call to the <Filename>csa_logoff()</Filename> function. The context of the session is represented
|
|
by a session handle. This handle provides a token in each of the CSA functions
|
|
to distinguish one calendar session from another. The <Filename>csa_logon()</Filename> function
|
|
also authenticates the user to the calendaring service and sets session
|
|
attributes. Currently, there is no support for sharing calendar sessions among
|
|
applications.</Para>
|
|
<Para>The <Filename>csa_list_calendars()</Filename> function is used to list the names of the
|
|
calendars managed by a particular calendar service.</Para>
|
|
<Para>The <Filename>csa_query_configuration()</Filename> function is used to list information about
|
|
the current calendar service configuration. This information can include the
|
|
character set, line terminator characters for text strings, default service name,
|
|
default authorization user identifier for the specified calendar service, an
|
|
indicator of whether a password is needed to authenticate the user identifier,
|
|
an indicator of whether the common extensions for user interface dialogs is
|
|
supported, and the CSA specification supported by the implementation.</Para>
|
|
<Para>The CSA implementation provides support for managing the memory for
|
|
calendar objects and attributes that are returned by the service. The
|
|
<Filename>csa_free()</Filename> function is used to free up this memory after it is no longer
|
|
needed. It is the responsibility of the application to free up the memory
|
|
allocated and managed by the calendar service.</Para>
|
|
</Sect3>
|
|
<Sect3 Id="PG.calmg.div.15">
|
|
<Title>Calendar Management<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>management</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>management, Calendar</Primary>
|
|
</IndexTerm></Title>
|
|
<Para>The CSA interface provides several calendar management functions. The CDE
|
|
implementation supports multiple calendars per calendar service; the calendar-
|
|
enabled application can add or delete calendars. The
|
|
<Filename>csa_delete_calendar()</Filename> function is used to delete calendars. The
|
|
<Filename>csa_add_calendar()</Filename> function is used to add new calendars to the service.</Para>
|
|
<Para>The application can also list, read, and update calendar attributes using the
|
|
<Command>csa</Command>_<Filename>list_calendar_attributes()</Filename>,
|
|
<Filename>csa_read_calendar_attributes()</Filename>, and
|
|
<Filename>csa_update_calendar_attributes()</Filename> functions. The application can
|
|
register callback functions for receiving notification of a calendar logon,
|
|
calendar deletion, update of calendar attributes, addition of a new calendar
|
|
entry, deletion of a calendar entry, and update of a calendar entry. The callback
|
|
function is only registered for the duration of the calendar session. In any case,
|
|
this information may be invaluable for some calendar administration
|
|
applications.</Para>
|
|
</Sect3>
|
|
<Sect3 Id="PG.calmg.div.16">
|
|
<Title>Entry Management<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>entry management</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>entry management, Calendar</Primary>
|
|
</IndexTerm></Title>
|
|
<Para>The CSA interface has a robust set of functions for managing calendar entries.
|
|
The context of a calendar entry in a calendar session is maintained by the entry
|
|
handle. This handle provides a token in the CSA functions to distinguish one
|
|
calendar entry from another. The entry handle is returned by the
|
|
<Filename>csa_add_entry()</Filename> and <Command>csa</Command>_<Filename>list_entries()</Filename> functions. The entry handle is
|
|
valid for the duration of the calendar session or until the entry is deleted or
|
|
updated. The entry handle becomes invalid when it is freed by a call to
|
|
<Filename>csa_free()</Filename>.</Para>
|
|
<Para>The <ComputerOutput>csa_</ComputerOutput><Filename>add_entry()</Filename> function is used to add new entries to a calendar. The
|
|
<Filename>csa_delete_entry()</Filename> function is used to delete an entry in a calendar. The
|
|
<Filename>csa_</Filename> <Filename>list_entries()</Filename> function is used to enumerate the calendar entries
|
|
that match a particular set of entry attribute criteria. The
|
|
<Filename>csa_read_entry_attributes()</Filename> function is used to get either all or a set of
|
|
entry attribute values associated with a particular calendar entry.</Para>
|
|
<Para>To add an entry to a calendar, a calendar-enabled application must first
|
|
establish a session with the calendaring service using the <Filename>csa_logon()</Filename>
|
|
function. Then the application invokes the <Filename>csa_add_entry()</Filename> function to
|
|
specify the new entry. The calendar-enabled application is responsible for
|
|
composing the attributes used in the <Filename>csa_add_entry()</Filename> function. The session
|
|
is terminated using the <Filename>csa_logoff()</Filename> function.</Para>
|
|
<Para>The entry attributes in an individual calendar entry can be enumerated with
|
|
the <Filename>csa_list_entry_attributes()</Filename> function. The values of one or more
|
|
attributes can be read with the <Command>csa_</Command> <Filename>read_entry_attributes()</Filename> function.
|
|
Individual entry attributes can be modified with the
|
|
<Filename>csa_update_entry_attributes()</Filename> function.</Para>
|
|
<Para>Memory allocated by the CSA implementation for retrieved calendar
|
|
information is released by passing the associated memory pointers to the
|
|
<Filename>csa_free()</Filename> function.</Para>
|
|
<Para>Some calendar entries are associated with a recurring activity. The
|
|
<Filename>csa_list_entry_sequence()</Filename> function can be used to enumerate the other
|
|
recurring calendar entries. This function returns a list of entry handles for the
|
|
recurring entries.</Para>
|
|
<Para>The CDE calendar server provides support for alarms or reminders to be
|
|
associated with calendar entries. Reminders can take the form of audio
|
|
reminders from the terminal speaker, flashing reminders presented on the
|
|
terminal screen, mail reminders sent to the calendar user, or pop-up reminders
|
|
presented on the terminal screen. The calendar service manages the reminders,
|
|
but it is the responsibility of the calendar application to retrieve the reminder
|
|
information and act on it. The <Filename>csa_read_next_reminder()</Filename> function is used
|
|
to read the information about the next scheduled type of reminder.</Para>
|
|
</Sect3>
|
|
</Sect2>
|
|
<Sect2 Id="PG.calmg.div.17">
|
|
<Title Id="PG.calmg.mkr.11">Extensions<IndexTerm>
|
|
<Primary>CSA</Primary>
|
|
<Secondary>extensions</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>extensions, CSA</Primary>
|
|
</IndexTerm></Title>
|
|
<Para>The major data structures and functions defined in the CSA specification can
|
|
be extended methodically through extensions. Extensions are used to add
|
|
additional fields to data structures and additional parameters to a function call.
|
|
A standard generic data structure has been defined for these extensions. It
|
|
consists of an item code, identifying the extension; an item data, holding the
|
|
length of extension data or the data itself; an item reference, pointing to where
|
|
the extension value is stored or <Command>NULL</Command> if there is no related item storage; and
|
|
flags for the extension.</Para>
|
|
<Para>Extensions that are additional parameters to a function call may be input or
|
|
output. That is, the extension may be passed as input parameters from the
|
|
application to the CSA service or passed as output parameters from CSA
|
|
service to the application. If an extension is an input parameter, the application
|
|
allocates memory for the extension structure and any other structures
|
|
associated with the extension. If an extension is an output parameter, the CSA
|
|
service allocates the storage for the extension result, if necessary. In this case,
|
|
the application must free the allocated storage with a <Filename>csa_free()</Filename> call.</Para>
|
|
<Para>If an extension that is not supported is requested,
|
|
<Filename>CSA_E_UNSUPPORTED_FUNCTION_EXT</Filename> is returned.</Para>
|
|
</Sect2>
|
|
</Sect1>
|
|
<Sect1 Id="PG.calmg.div.18">
|
|
<Title Id="PG.calmg.mkr.12">Data Structures<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>data structures</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>data structures, Calendar</Primary>
|
|
</IndexTerm></Title>
|
|
<Para><!--Original XRef content: 'Table 10‐2'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.calmg.mkr.13"> lists the CSA data structures. See the relevant man page for
|
|
complete information.</Para>
|
|
<Table Id="PG.calmg.tbl.2" Frame="Topbot">
|
|
<Title Id="PG.calmg.mkr.13">CSA Data Structures</Title>
|
|
<TGroup Cols="2">
|
|
<ColSpec Colname="1" Colwidth="1.44643 in">
|
|
<ColSpec Colname="2" Colwidth="3.28737 in">
|
|
<THead>
|
|
<Row>
|
|
<Entry><Para><Literal>Data Type Name</Literal></Para></Entry>
|
|
<Entry><Para><Literal>Description</Literal></Para></Entry>
|
|
</Row>
|
|
</THead>
|
|
<TBody>
|
|
<Row>
|
|
<Entry><Para>Access List</Para></Entry>
|
|
<Entry><Para>List of access rights structures for calendar users</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Attendee List</Para></Entry>
|
|
<Entry><Para>List of attendee structures</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Attribute</Para></Entry>
|
|
<Entry><Para>Attribute structure</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Attribute Reference</Para></Entry>
|
|
<Entry><Para>Attribute reference structure</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Boolean</Para></Entry>
|
|
<Entry><Para>A value that indicates logical true or false</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Buffer</Para></Entry>
|
|
<Entry><Para>Pointer to a data item</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Calendar User</Para></Entry>
|
|
<Entry><Para>Calendar user structure</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Callback Data
|
|
Structures</Para></Entry>
|
|
<Entry><Para>Callback data structures</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Date and Time</Para></Entry>
|
|
<Entry><Para>Date and time designation</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Date and Time List</Para></Entry>
|
|
<Entry><Para>List of date and time values</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Date and Time Range</Para></Entry>
|
|
<Entry><Para>Range of date and time</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Entry Handle</Para></Entry>
|
|
<Entry><Para>Handle for the calendar entry</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Enumerated</Para></Entry>
|
|
<Entry><Para>Data type containing a value from an enumeration</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Extension</Para></Entry>
|
|
<Entry><Para>Extension structure</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Flags</Para></Entry>
|
|
<Entry><Para>Container for bit masks</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Free Time</Para></Entry>
|
|
<Entry><Para>Free time structure</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Opaque Data</Para></Entry>
|
|
<Entry><Para>Opaque data structure</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Reminder</Para></Entry>
|
|
<Entry><Para>Reminder structure</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Reminder Reference</Para></Entry>
|
|
<Entry><Para>Reminder reference structure</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Return Code</Para></Entry>
|
|
<Entry><Para>Return value indicating either that a function
|
|
succeeded or why it failed</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Service Reference</Para></Entry>
|
|
<Entry><Para>Service reference structure</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Session Handle</Para></Entry>
|
|
<Entry><Para>Handle for the calendar session</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>String</Para></Entry>
|
|
<Entry><Para>Character string pointer</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Time Duration</Para></Entry>
|
|
<Entry><Para>Time duration</Para></Entry>
|
|
</Row>
|
|
</TBody>
|
|
</TGroup>
|
|
</Table>
|
|
</Sect1>
|
|
<Sect1 Id="PG.calmg.div.19">
|
|
<Title Id="PG.calmg.mkr.14">Calendar Attributes<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>attributes</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>attributes, Calendar</Primary>
|
|
</IndexTerm></Title>
|
|
<Para><!--Original XRef content: 'Table 10‐3'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.calmg.mkr.15"> lists the calendar attributes supported in the CDE implementation.
|
|
See the relevant man page for more information. The list of calendar attributes
|
|
is extensible through the extended naming convention.</Para>
|
|
<Table Id="PG.calmg.tbl.3" Frame="Topbot">
|
|
<Title Id="PG.calmg.mkr.15">CSA Calendar Attributes</Title>
|
|
<TGroup Cols="3">
|
|
<ColSpec Colname="1" Colwidth="1.27689 in">
|
|
<ColSpec Colname="2" Colwidth="2.19996 in">
|
|
<ColSpec Colname="3" Colwidth="1.25926 in">
|
|
<THead>
|
|
<Row>
|
|
<Entry><Para><Literal>Attribute Name</Literal></Para></Entry>
|
|
<Entry><Para><Literal>Description</Literal></Para></Entry>
|
|
<Entry><Para><Literal>Read-Only</Literal></Para></Entry>
|
|
</Row>
|
|
</THead>
|
|
<TBody>
|
|
<Row>
|
|
<Entry><Para>Access List</Para></Entry>
|
|
<Entry><Para>Access list attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Calendar Name</Para></Entry>
|
|
<Entry><Para>Calendar name attribute</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Calendar Owner</Para></Entry>
|
|
<Entry><Para>Calendar owner attribute</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Calendar Size</Para></Entry>
|
|
<Entry><Para>Calendar size attribute (computed)</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Character Set</Para></Entry>
|
|
<Entry><Para>Character set attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Date Created</Para></Entry>
|
|
<Entry><Para>Calendar creation date attribute</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Number Entries</Para></Entry>
|
|
<Entry><Para>Number of entries attribute
|
|
(computed)</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Product Identifier</Para></Entry>
|
|
<Entry><Para>Product identifier attribute</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Time Zone</Para></Entry>
|
|
<Entry><Para>Time zone attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Version</Para></Entry>
|
|
<Entry><Para>Product version attribute</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
</TBody>
|
|
</TGroup>
|
|
</Table>
|
|
<Para>The following section provides additional information about the calendar
|
|
attributes listed in
|
|
<!--Original XRef content: 'Table 10‐3'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.calmg.mkr.15">.</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para><Command>Access List</Command></Para>
|
|
<Para>When a new calendar is added and if no access list is specified, the default
|
|
access list contains a special user <Emphasis>world</Emphasis> and its corresponding access right is
|
|
<Filename>CSA_VIEW_PUBLIC_ENTRIES</Filename>, which provides access right to list and read
|
|
calendar entries with public classification. The special user <Emphasis>world</Emphasis> includes all
|
|
users.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Calendar Name</Command></Para>
|
|
<Para>The calendar name is specified when the calendar is created using
|
|
<Filename>csa_add_calendar().</Filename> It becomes read-only and cannot be changed after
|
|
the calendar is created.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Calendar Owner</Command></Para>
|
|
<Para>The calendar owner is set to the user who is running the application that
|
|
calls <Command>csa_add_calendar()</Command> to create the calendar. It becomes read-only
|
|
and cannot be changed after the calendar is created.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Character Set</Command></Para>
|
|
<Para>The CDE common locale name should be used to set this value.</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
<Sect2 Id="PG.calmg.div.20">
|
|
<Title>CDE Calendar Attributes</Title>
|
|
<Para>The followings are CDE-defined calendar attributes:</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para><Command>Server Version</Command></Para>
|
|
<Para>This read-only attribute shows the version number of the server managing
|
|
the calendar. This attribute is a <Filename>CSA_VALUE_UINT32</Filename> type of attribute.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Data Version</Command></Para>
|
|
<Para>This read-only attribute shows the data version of the calendar. This
|
|
attribute is a <Command>CSA_VALUE_UINT32</Command> type of attribute.</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</Sect2>
|
|
</Sect1>
|
|
<Sect1 Id="PG.calmg.div.21">
|
|
<Title Id="PG.calmg.mkr.16">Entry Attributes<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>entry attributes</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>entry attributes, Calendar</Primary>
|
|
</IndexTerm></Title>
|
|
<Para><!--Original XRef content: 'Table 10‐4'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.calmg.mkr.17"> lists the entry attributes supported in the CDE implementation. See
|
|
the relevant man page for more information. The list of entry attributes is
|
|
extensible through the extended naming convention.</Para>
|
|
<Table Id="PG.calmg.tbl.4" Frame="Topbot">
|
|
<Title Id="PG.calmg.mkr.17">CSA Entry Attributes</Title>
|
|
<TGroup Cols="3">
|
|
<ColSpec Colname="1" Colwidth="1.22686 in">
|
|
<ColSpec Colname="2" Colwidth="1.7523 in">
|
|
<ColSpec Colname="3" Colwidth="1.78009 in">
|
|
<THead>
|
|
<Row>
|
|
<Entry><Para><Literal>Attribute Name</Literal></Para></Entry>
|
|
<Entry><Para><Literal>Description</Literal></Para></Entry>
|
|
<Entry><Para><Literal>Read-Only</Literal></Para></Entry>
|
|
</Row>
|
|
</THead>
|
|
<TBody>
|
|
<Row>
|
|
<Entry><Para>Audio Reminder</Para></Entry>
|
|
<Entry><Para>Audio reminder attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Classification</Para></Entry>
|
|
<Entry><Para>Classification attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Date Completed</Para></Entry>
|
|
<Entry><Para>Date completed attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Date Created</Para></Entry>
|
|
<Entry><Para>Entry creation date attribute</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Description</Para></Entry>
|
|
<Entry><Para>Description attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Due Date</Para></Entry>
|
|
<Entry><Para>Due date attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>End Date</Para></Entry>
|
|
<Entry><Para>End date attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Exception Dates</Para></Entry>
|
|
<Entry><Para>Exception dates attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Flashing Reminder</Para></Entry>
|
|
<Entry><Para>Flashing reminder attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Last Update</Para></Entry>
|
|
<Entry><Para>Last update attribute</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Mail Reminder</Para></Entry>
|
|
<Entry><Para>Mail reminder attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Number
|
|
Recurrences</Para></Entry>
|
|
<Entry><Para>Number of recurrences
|
|
attribute (computed)</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Organizer</Para></Entry>
|
|
<Entry><Para>Organizer attribute</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Popup Reminder</Para></Entry>
|
|
<Entry><Para>Pop-up reminder attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Priority</Para></Entry>
|
|
<Entry><Para>Priority attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Recurrence Rule</Para></Entry>
|
|
<Entry><Para>Recurrence rule attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Reference
|
|
Identifier</Para></Entry>
|
|
<Entry><Para>Reference identifier
|
|
attribute</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Sponsor</Para></Entry>
|
|
<Entry><Para>Sponsor attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Start Date</Para></Entry>
|
|
<Entry><Para>Start date attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Status</Para></Entry>
|
|
<Entry><Para>Status attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Subtype</Para></Entry>
|
|
<Entry><Para>Subtype attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Summary</Para></Entry>
|
|
<Entry><Para>Summary attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Transparency</Para></Entry>
|
|
<Entry><Para>Time transparency or
|
|
blocking attribute</Para></Entry>
|
|
<Entry><Para>No</Para></Entry>
|
|
</Row>
|
|
<Row>
|
|
<Entry><Para>Type</Para></Entry>
|
|
<Entry><Para>Type attribute</Para></Entry>
|
|
<Entry><Para>Yes</Para></Entry>
|
|
</Row>
|
|
</TBody>
|
|
</TGroup>
|
|
</Table>
|
|
<Para>The following section provides additional information about the entry
|
|
attributes listed in
|
|
<!--Original XRef content: 'Table 10‐4'--><XRef Role="CodeOrFigureOrTable" Linkend="PG.calmg.mkr.17">.</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para><Command>Organizer</Command></Para>
|
|
<Para>The organizer of an entry is set to the user who is running the application
|
|
that calls <Filename>csa_add_entry()</Filename> to add the entry to the calendar. It becomes
|
|
read-only and cannot be changed after the entry is added.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Reference Identifier</Command></Para>
|
|
<Para>The reference identifier of an entry is a string that contains a unique
|
|
identifier of the entry within the calendar as well as the name and location
|
|
of the calendar. The format is <Filename>n:calendar@location</Filename> where <Command>n</Command> is a
|
|
number that uniquely identifies the entry within the calendar, <Command>calendar</Command> is
|
|
the name of the calendar, and <Command>location</Command> is the name of the machine where
|
|
the calendar is stored.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Status</Command></Para>
|
|
<Para>The CDE implementation defines the following additional status values:</Para>
|
|
<Para><Filename>CSA_X_DT_STATUS_ACTIVE</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_STATUS_DELETE_PENDING</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_STATUS_ADD_PENDING</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_STATUS_COMMITTED</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_STATUS_CANCELLED</Filename></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Type</Command></Para>
|
|
<Para>The value becomes read-only and cannot be changed after the entry is
|
|
added. The CDE implementation defines the following additional type
|
|
value:</Para>
|
|
<Para><Filename>CSA_X_DT_TYPE_OTHER</Filename></Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
<Sect2 Id="PG.calmg.div.22">
|
|
<Title>CDE Entry Attributes</Title>
|
|
<Para>The following are CDE-defined entry attributes:</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para><Command>Show Time</Command></Para>
|
|
<Para>The value of this attribute indicates whether the start and end time of the
|
|
entry should be shown to the user. It can be modified using
|
|
<Filename>csa_update_entry_attributes()</Filename>. This attribute is a
|
|
<Filename>CSA_VALUE_SINT32</Filename> type of attribute.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Repeat Type</Command></Para>
|
|
<Para>The frequency of recurrence of the entry, which indicates how often the
|
|
entry repeats. This is a read-only attribute and is derived from the entry
|
|
attribute <Command>Recurrence Rule</Command>.</Para>
|
|
<Para>This attribute is a <Filename>CSA_VALUE_UINT32</Filename> type of attribute.</Para>
|
|
<Para>The following values are defined:</Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_ONETIME</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_DAILY</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_WEEKLY</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_BIWEEKLY</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_MONTHLY_BY_WEEKDAY</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_MONTHLY_BY_DATE</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_YEARLY</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_EVERY_NDAY</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_EVERY_NWEEK</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_EVERY_NMONTH</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_MON_TO_FRI</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_MONWEDFRI</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_TUETHUR</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_WEEKDAYCOMBO</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_OTHER</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_OTHER_WEEKLY</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_OTHER_MONTHLY</Filename></Para>
|
|
<Para><Filename>CSA_X_DT_REPEAT_OTHER_YEARLY</Filename></Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Repeat Times</Command></Para>
|
|
<Para>This attribute shows the number of times an entry repeats. This is a read-
|
|
only attribute and is derived from the entry attribute <Command>Recurrence Rule</Command>.
|
|
This attribute is a <Command>CSA_VALUE_UINT32</Command> type of attribute.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Repeat Interval</Command></Para>
|
|
<Para>This attribute tells how often an entry with repeat types
|
|
<Command>CSA_X_DT_REPEAT_EVERY_NDAY, CSA_X_DT_REPEAT_EVERY_NWEEK</Command>, or
|
|
<Command>CSA_X_DT_REPEAT_EVERY_NMONTH</Command> repeats. This is a read-only attribute,
|
|
and is derived from the entry attribute <Command>Recurrence Rule.</Command> For example,
|
|
if the value of this attribute is 3 and the repeat type is
|
|
<Filename>CSA_X_DT_REPEAT_EVERY_NWEEK</Filename>, the entry repeats every three weeks.
|
|
This attribute is a <Filename>CSA_VALUE_UINT32</Filename> type of attribute.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Repeat Occurrence Number</Command></Para>
|
|
<Para>If the entry's repeat type is <Filename>CSA_X_DT_REPEAT_MONTHLY_BY_WEEKDAY</Filename>,
|
|
this attribute tells in which week the entry repeats. This is a read-only
|
|
attribute and is derived from the entry attribute <Command>Recurrence Rule</Command>. This
|
|
attribute is a <Filename>CSA_VALUE_SINT32</Filename> type of attribute.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para><Command>Sequence End Date</Command></Para>
|
|
<Para Id="PG.calmg.mkr.18">This entry attribute shows the end date of the sequence. This is a read-only
|
|
attribute and is derived from the entry attribute <Command>Recurrence Rule</Command>. This
|
|
attribute is a <Filename>CSA_VALUE_DATE_TIME</Filename> type of attribute.</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</Sect2>
|
|
</Sect1>
|
|
<Sect1 Id="PG.calmg.div.23">
|
|
<Title Id="PG.calmg.mkr.19">General Information about Functions</Title>
|
|
<Para>The following general information applies to all functions:</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para>Character set restriction</Para>
|
|
<Para>The calendar attribute, <Filename>CSA_CAL_ATTR_CHARACTER_SET</Filename>, is used to store
|
|
the locale information of the calendar.</Para>
|
|
<Note>
|
|
<Para>All data except textual description passed in the library must be in
|
|
ASCII format and the library supports single-byte as well as multibyte
|
|
character strings.</Para>
|
|
</Note>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Type checking for attribute values is provided for the predefined attributes
|
|
only.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>When a function takes both a session handle and an entry handle, the
|
|
session handle is always ignored in the CDE implementation.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Entry attributes <Filename>CSA_ENTRY_ATTR_RECURRENCE_RULE</Filename> and
|
|
<Filename>CSA_ENTRY_ATTR_EXCEPTION_DATES</Filename> are used to specify recurrence
|
|
information of a calendar entry. Information in the
|
|
<Filename>CSA_ENTRY_ATTR_RECURRENCE_RULE</Filename> attribute can be queried using the
|
|
following attributes: <Filename>CSA_X_DT_ENTRY_ATTR_REPEAT_TYPE</Filename>,
|
|
<Filename>CSA_X_DT_ENTRY_ATTR_REPEAT_TIMES</Filename>,
|
|
<Filename>CSA_X_DT_ENTRY_ATTR_REPEAT_INTERVAL</Filename>,
|
|
<Filename>CSA_X_DT_ENTRY_ATTR_REPEAT_OCCURRENCE_NUM</Filename>, and
|
|
<Filename>CSA_X_DT_ENTRY_ATTR_SEQUENCE_END_DATE</Filename>. These computed
|
|
attributes are read-only.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>The <Filename>CSA_calendar_user</Filename> data structure specifies either a user or a
|
|
calendar. In the first case, for example, when specifying a user in an access
|
|
list, only the <Filename>user_name</Filename> field is used and all other fields are ignored. In the
|
|
latter case, for example, when specifying the calendar to log onto, only the
|
|
<Filename>calendar_address</Filename> field is used and all other fields are ignored. The
|
|
format is <Filename>calendar@location</Filename> where <Command>calendar</Command> is the name of the
|
|
calendar and <Command>location</Command> is the name of the machine where the calendar is
|
|
stored.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Attributes of value type <Command>CSA_VALUE_ATTENDEE_LIST</Command> are not supported
|
|
and <Filename>CSA_E_INVALID_ATTRIBUTE_VALUE</Filename> will be returned if they are
|
|
specified.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Although the <Filename>repeat_count</Filename> and <Filename>snooze_time</Filename> fields in the
|
|
<Filename>CSA_reminder</Filename> data structure are stored in the calendar, the calendar
|
|
service does not interpret their values and the associated reminder will be
|
|
returned only once by the server.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>The user interface extension <Filename>CSA_X_UI_ID_EXT</Filename> is not supported.</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</Sect1>
|
|
<Sect1 Id="PG.calmg.div.24">
|
|
<Title Id="PG.calmg.mkr.20">Administration Functions<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>administrative functions</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>administrative functions, Calendar</Primary>
|
|
</IndexTerm></Title>
|
|
<Para>This section contains descriptions for the administration functions supported
|
|
in the CDE implementation. See the relevant man page for more information.</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para>Free – Frees memory allocated by the calendaring service.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_free(
|
|
CSA_buffer memory
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>List Calendars – Lists the calendars supported by a calendar server.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_list_calendars(
|
|
CSA_service_reference calendar_service,
|
|
CSA_uint32 *number_names,
|
|
CSA_calendar_user **calendar_names,
|
|
CSA_extension *list_calendars_extensions
|
|
);</ProgramListing>
|
|
<Para>A host name where the server runs should be passed in
|
|
<Filename>calendar_server</Filename>.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Logon – Logs on to the calendar service and establishes a session with a
|
|
calendar.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_logon(
|
|
CSA_service_reference calendar_service,
|
|
CSA_calendar_user *user,
|
|
CSA_string password,
|
|
CSA_string character_set,
|
|
CSA_string required_csa_version,
|
|
CSA_session_handle *session,
|
|
CSA_extension *logon_extensions
|
|
);</ProgramListing>
|
|
<Para>Arguments <Command>calendar_service, password, character_set,</Command>
|
|
and <Filename>required_csa_version</Filename> are not used.</Para>
|
|
<Para>The <Command>calendar_address</Command> field of the <Filename>CSA_calendar_user</Filename>
|
|
structure pointed to by <Command>user</Command> specifies the calendar to log onto. The
|
|
format is <Filename>calendar@location</Filename> where <Command>calendar</Command> is the name of the
|
|
calendar and <Command>location</Command> is the host name where the calendar is
|
|
stored.</Para>
|
|
<Para>The CDE-defined extension <Command>CSA_X_DT_GET_USER_ACCESS_EXT</Command> is
|
|
supported. This extension can be used to get the access rights the
|
|
calling user has with respect to the calendar. The user's access rights
|
|
is returned in the <Filename>item_data</Filename> field of the extension structure.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Logoff – Terminates a session with a calendar.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_logoff(
|
|
CSA_session_handle session,
|
|
CSA-extension *logoff_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Query Configuration – Determines information about the installed CSA
|
|
configuration.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_query_configuration(
|
|
CSA_session_handle session,
|
|
CSA_enum item,
|
|
CSA_buffer *reference,
|
|
CSA_extension *query_configuration_extensions
|
|
);</ProgramListing>
|
|
<Para>The following items are not supported by this implementation of
|
|
CDE:</Para>
|
|
<Para><Filename>CSA_CONFIG_CHARACTER_SET</Filename></Para>
|
|
<Para><Filename>CSA_CONFIG_LINE_TERM</Filename></Para>
|
|
<Para><Filename>CSA_CONFIG_VER_IMPLEM</Filename></Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</Sect1>
|
|
<Sect1 Id="PG.calmg.div.25">
|
|
<Title Id="PG.calmg.mkr.21">Calendar Management Functions<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>management functions</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>management functions, Calendar</Primary>
|
|
</IndexTerm></Title>
|
|
<Para>This section contains descriptions for the calendar management functions
|
|
supported in the CDE implementation. See the relevant man page for more
|
|
information.</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para>Add calendar – Adds a calendar to the calendar service.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_add_calendar(
|
|
CSA_session_handle session,
|
|
CSA_calendar_user *user,
|
|
CSA_uint32 number_attributes,
|
|
CSA_attribute *calendar_attributes,
|
|
CSA_extension *add_calendar_extensions
|
|
);</ProgramListing>
|
|
<Para>The first argument <Command>session</Command> is ignored.</Para>
|
|
<Para>The <Filename>calendar_address</Filename> field of the <Command>CSA_calendar_user</Command> structure pointed to by <Command>user</Command> specifies the name and the location of
|
|
the calendar to be created. The format is <Filename>calendar@location</Filename>
|
|
where <Command>calendar</Command> is the name of the calendar and <Command>location</Command> is the
|
|
host name where the calendar is to be stored; for example,
|
|
<Filename>my_calendar@my_host</Filename>.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Call Callbacks – Forces the invocation of the callback functions associated
|
|
with the specified callback list(s).</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_call_callbacks(
|
|
CSA_session_handle session,
|
|
CSA_flags reason,
|
|
CSA_extension *call_callbacks_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Delete Calendar – Deletes a calendar from the calendar service.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_delete_calendar(
|
|
CSA_session_handle session,
|
|
csa_extension *delete_calendar_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>List Calendar Attributes – Lists the names of the calendar attributes
|
|
associated with a calendar.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_list_calendar_attributes(
|
|
CSA_session_handle session,
|
|
CSA_uint32 *number_names,
|
|
CSA_attribute_reference **calendar_attributes_names,
|
|
CSA_extension *list_calendar_attributes_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Read Calendar Attributes – Reads and returns the calendar attribute values
|
|
for a calendar.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_read_calendar_attributes(
|
|
CSA_session_handle session,
|
|
CSA_uint32 number_names,
|
|
CSA_attribute_reference *attribute_names,
|
|
CSA_uint32 *number_attributes,
|
|
CSA_attribute **calendar_attributes,
|
|
CSA_extension *read_calendar_attributes_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Register Callback Functions – Registers the callback function to be invoked
|
|
with the specified type of updates in the calendar.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_register_callback(
|
|
CSA_session_handle session,
|
|
CSA_flags reason,
|
|
CSA_callback callback,
|
|
CSA_buffer client_data,
|
|
CSA_extension *register_callback_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Unregister Callback Functions – Unregisters the specified callback function.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_unregister_callback(
|
|
CSA_session_handle session,
|
|
CSA_flags reason,
|
|
CSA_callback callback,
|
|
CSA_buffer client_data,
|
|
CSA_extension *unregister_callback_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Update Calendar Attributes – Updates the calendar attribute values for a
|
|
calendar.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_update_calendar_attributes(
|
|
CSA_session_handle session,
|
|
CSA_uint32 number_attributes,
|
|
CSA_attribute *calendar_attributes,
|
|
CSA_extension *update_calendar_attributes_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</Sect1>
|
|
<Sect1 Id="PG.calmg.div.26">
|
|
<Title Id="PG.calmg.mkr.22">Entry Management Functions<IndexTerm>
|
|
<Primary>Calendar</Primary>
|
|
<Secondary>entry management functions</Secondary>
|
|
</IndexTerm><IndexTerm>
|
|
<Primary>entry management functions, Calendar</Primary>
|
|
</IndexTerm></Title>
|
|
<Para>This section contains descriptions for the entry management functions
|
|
supported in the CDE implementation. See the relevant man page for more
|
|
information.</Para>
|
|
<ItemizedList Remap="Bullet1">
|
|
<ListItem>
|
|
<Para>Add Entry – Adds an entry to the specified calendar.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_add_entry(
|
|
CSA_session_handle session,
|
|
CSA_uint32 number_attributes,
|
|
CSA_attribute *entry_attributes,
|
|
CSA_entry_handle *entry,
|
|
CSA_extension *add_entry_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Delete Entry – Deletes an entry from the specified calendar.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_delete_entry(
|
|
CSA_session_handle session,
|
|
CSA_entry_handle entry,
|
|
CSA_enum delete_scope,
|
|
CSA_extension *delete_entry_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>List Entries – Lists the calendar entries that match all the attribute search
|
|
criteria.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_list_entries(
|
|
CSA_session_handle session,
|
|
CSA_uint32 number_attributes,
|
|
CSA_attribute *entry_attributes,
|
|
CSA_enum *list_operators,
|
|
CSA_uint32 *number_entries,
|
|
CSA_entry_handle **entries,
|
|
CSA_extension *list_entries_extensions
|
|
);</ProgramListing>
|
|
<Para>The following information details more about the operators
|
|
specified in <Filename>list_operators</Filename>:</Para>
|
|
<Para>Only the operators <Filename>CSA_MATCH_ANY</Filename> and <Filename>CSA_MATCH_EQUAL_TO</Filename>
|
|
are supported for the attribute value types <Filename>CSA_VALUE_REMINDER</Filename>,
|
|
<Filename>CSA_VALUE_CALENDAR_USER</Filename>, and
|
|
<Filename>CSA_VALUE_DATE_TIME_RANGE</Filename>.</Para>
|
|
<Para>Only the operators <Filename>CSA_MATCH_ANY</Filename>, <Filename>CSA_MATCH_EQUAL_TO</Filename>,
|
|
<Filename>CSA_MATCH_NOT_EQUAL_TO</Filename>, and <Command>CSA_MATCH_CONTAIN</Command> are
|
|
supported for the attribute value type <Filename>CSA_VALUE_STRING</Filename>. The
|
|
operator <Filename>CSA_MATCH_CONTAIN</Filename> only applies to
|
|
<Filename>CSA_VALUE_STRING</Filename> type of attributes.</Para>
|
|
<Para>Matching of attributes with the value types
|
|
<Filename>CSA_VALUE_OPAQUE_DATA</Filename>, <Command>CSA_VALUE_ACCESS_LIST,
|
|
CSA_VALUE_ATTENDEE_LIST,</Command> and,
|
|
<Filename>CSA_VALUE_DATE_TIME_LIST</Filename> are not supported. The only
|
|
exception is the attribute
|
|
<Filename>CSA_ENTRY_ATTR_REFERENCE_IDENTIFIER</Filename>. The operator
|
|
<Filename>CSA_MATCH_EQUAL_TO</Filename> is supported for this attribute.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>List Entry Attributes – Lists the names of the entry attributes associated
|
|
with the specified entry.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_list_entry_attributes(
|
|
CSA_session_handle session,
|
|
CSA_entry_handle entry,
|
|
CSA_uint32 *number_names,
|
|
CSA_attribute_reference **entry_attribute_names,
|
|
CSA_extension *list_entry_attributes_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>List Entry Sequence – Lists the recurring calendar entries that are associated
|
|
with a calendar entry.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_list_entry_sequence(
|
|
CSA_session_handle session,
|
|
CSA_entry_handle entry,
|
|
CSA_date_time_range time_range,
|
|
CSA_uint32 *number_entries,
|
|
CSA_entry_handle **entry_list,
|
|
CSA_extension *list_entry_sequences_extensions
|
|
);</ProgramListing>
|
|
<Para><Filename>CSA_E_INVALID_PARAMETER</Filename> is returned if the specified entry is a
|
|
one-time entry.</Para>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Read Entry Attributes – Reads and returns the calendar entry attribute
|
|
values for a specified entry.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_read_entry_attributes(
|
|
CSA_session_handle session,
|
|
CSA_entry_handle entry,
|
|
CSA_uint32 number_names,
|
|
CSA_attribute_reference *attribute_names,
|
|
CSA_uint32 *number_attributes,
|
|
CSA_attribute **entry_attributes,
|
|
CSA_extension *read_entry_attributes_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Read Next Reminder – Reads the next reminder of the given type in the
|
|
specified calendar relative to a given time.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_read_next_reminder(
|
|
CSA_session_handle session,
|
|
CSA_uint32 number_names,
|
|
CSA_attribute_reference *reminder_names,
|
|
CSA_date_time given_time,
|
|
CSA_uint32 *number_reminders,
|
|
CSA_remainder_reference **reminder_references,
|
|
CSA_extension *read_next_reminder_extensions
|
|
);</ProgramListing>
|
|
</ListItem>
|
|
<ListItem>
|
|
<Para>Update Entry Attributes – Updates the calendar entry attributes.</Para>
|
|
<ProgramListing>CSA_return_code
|
|
csa_update_entry_attributes(
|
|
CSA_session_handle session,
|
|
CSA_entry_handle entry,
|
|
CSA_enum update_scope,
|
|
CSA_boolean update_propagation,
|
|
CSA_uint32 number_attributes,
|
|
CSA_attribute *entry_attributes,
|
|
CSA_entry_handle *new_entry,
|
|
CSA_extension *update_entry_attributes_extensions
|
|
);</ProgramListing>
|
|
<Para>Update propagation is not supported; the <Command>update_propagation</Command> argument should be set to <Filename>CSA_FALSE</Filename>.</Para>
|
|
</ListItem>
|
|
</ItemizedList>
|
|
</Sect1>
|
|
</Chapter>
|
|
<!--fickle 1.14 mif-to-docbook 1.7 01/02/96 09:54:57-->
|