<!-- $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>&lt;Filename>libDtCalendar&lt;Default Para Font> library</Primary>
</IndexTerm><IndexTerm>
<Primary>library&lt;Filename>libDtCalendar&lt;Default Para Font></Primary>
</IndexTerm>libcsa</Command> library. The header
file is <Filename><IndexTerm>
<Primary>header file</Primary>
<Secondary>&lt;Filename>Dt/xcsa.h&lt;Default Para Font></Secondary>
</IndexTerm><IndexTerm>
<Primary>&lt;Filename>Dt.Xcsa.h&lt;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&numsp;10&hyphen;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&numsp;10&hyphen;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&numsp;10&hyphen;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&numsp;10&hyphen;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&numsp;10&hyphen;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&numsp;10&hyphen;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&numsp;10&hyphen;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&numsp;10&hyphen;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 &ndash; Frees memory allocated by the calendaring service.</Para>
<ProgramListing>CSA_return_code
csa_free(
  CSA_buffer      memory
);</ProgramListing>
</ListItem>
<ListItem>
<Para>List Calendars &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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 &ndash; 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-->
