# Integrating with Calendar

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.

The Calendar API is an implementation of the X.400 Application Programming Interface Association's (XAPIA) Calendaring and Scheduling API (CSA API).
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.

This chapter describes the Calendar API in these sections:

PG.dndPG.mkr.3
PG.dndPG.mkr.4
PG.calmg.mkr.4
PG.calmg.mkr.5
PG.calmg.mkr.8
PG.calmg.mkr.12
PG.calmg.mkr.14
PG.calmg.mkr.16
PG.calmg.mkr.19
PG.calmg.mkr.20
PG.calmg.mkr.21
PG.calmg.mkr.22

## Library and Header Files

To use the Calendar API, you need to link to the `
libcsa` library. The header file is `
csa/csa.h`.

## Demo Program

A demo program containing an example of how to use the Calendar API is in `/usr/dt/examples/dtcalendar`.

## Using the Calendar API

### How to Integrate with Calendar

The Calendar API provides a way to access and manage calendar data in a networked environment.

1. Include `csa/csa.h` in your application.

2. Use the calendar API to incorporate the calendar operations you want in your application.

3. Link with `libcsa`.

## Overview of the CSA API

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.

The number of function calls provided is minimal. A single set of functions manage multiple types of calendar entries.

### C Naming Conventions

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 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.

### Derivation of C Naming Conventions

`Element Type` | `Prefix` | `Case`
Data type | `CSA_` | Lower
Data value | `CSA_` | Upper
Function | `csa_` | Lower
Function argument | `none` | Lower
Function result | `none` | Lower
Constant | `CSA_` | Upper
Error | `CSA_E_` | Upper
Macro | `CSA_` | Upper
Reserved for extension sets | `CSA_XS_` | Any
Reserved for extensions | `CSA_X_` | Any
Reserved for use by implementors | `CSAP` | Any
Reserved for vendor function extensions | csa_x | Lower
Structure Tag | `CSA_TAG_` | Upper

Elements with the prefix `CSAP` (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.

The prefixes `CSA_XS_`, `CSA_X_` (in either uppercase or lowercase), and `csa_x` 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.

For constant data values, an additional string is usually appended to `CSA_` to indicate the data structure or function for the constant data value.

## Functional Architecture

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.

### Implementation Model

The abstract implementation model is provided as a reference aid to help you understand the scope of the CSA API.

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 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 PG.calmg.mkr.9.

#### Positioning of the Calendaring and Scheduling API

The model of the CSA interface can be divided into three components: administration, calendar management, and entry management. These components are shown in PG.calmg.mkr.10.

#### Components of the Calendaring and Scheduling API

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.

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.

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.

### Data Model

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.

#### Calendar Entities

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.

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.

The calendar entries are the primary components of a calendar. The three classes of calendar entries follow:

- Events

- To Dos

- Memos

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.

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.

#### Access Rights

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:

- The owner of a calendar

- The organizer of a particular entry within the calendar

- The sponsor of a particular entry within the calendar

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.

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.

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.

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.

### Functional Overview

The CSA interface supports three principle types of tasks:

- Administration

- Calendar management

- Entry management

#### Administration

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 `csa_logon()` function and terminated with a call to the `csa_logoff()` 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 `csa_logon()` function also authenticates the user to the calendaring service and sets session attributes. Currently, there is no support for sharing calendar sessions among applications.

The `csa_list_calendars()` function is used to list the names of the calendars managed by a particular calendar service.

The `csa_query_configuration()` 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.

The CSA implementation provides support for managing the memory for calendar objects and attributes that are returned by the service. The `csa_free()` 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.

#### Calendar Management

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 `csa_delete_calendar()` function is used to delete calendars. The `csa_add_calendar()` function is used to add new calendars to the service.

The application can also list, read, and update calendar attributes using the `csa`_`list_calendar_attributes()`, `csa_read_calendar_attributes()`, and `csa_update_calendar_attributes()` 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.

#### Entry Management

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 `csa_add_entry()` and `csa`_`list_entries()` 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 `csa_free()`.

The `csa_``add_entry()` function is used to add new entries to a calendar. The `csa_delete_entry()` function is used to delete an entry in a calendar. The `csa_` `list_entries()` function is used to enumerate the calendar entries that match a particular set of entry attribute criteria. The `csa_read_entry_attributes()` function is used to get either all or a set of entry attribute values associated with a particular calendar entry.

To add an entry to a calendar, a calendar-enabled application must first establish a session with the calendaring service using the `csa_logon()` function. Then the application invokes the `csa_add_entry()` function to specify the new entry. The calendar-enabled application is responsible for composing the attributes used in the `csa_add_entry()` function. The session is terminated using the `csa_logoff()` function.

The entry attributes in an individual calendar entry can be enumerated with the `csa_list_entry_attributes()` function. The values of one or more attributes can be read with the `csa_` `read_entry_attributes()` function. Individual entry attributes can be modified with the `csa_update_entry_attributes()` function.

Memory allocated by the CSA implementation for retrieved calendar information is released by passing the associated memory pointers to the `csa_free()` function.

Some calendar entries are associated with a recurring activity. The `csa_list_entry_sequence()` function can be used to enumerate the other recurring calendar entries. This function returns a list of entry handles for the recurring entries.

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 `csa_read_next_reminder()` function is used to read the information about the next scheduled type of reminder.

### Extensions

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 `NULL` if there is no related item storage; and flags for the extension.

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 `csa_free()` call.

If an extension that is not supported is requested, `CSA_E_UNSUPPORTED_FUNCTION_EXT` is returned.

## Data Structures

PG.calmg.mkr.13 lists the CSA data structures. See the relevant man page for complete information.

## CSA Data Structures

`Data Type Name` | `Description`
Access List | List of access rights structures for calendar users
Attendee List | List of attendee structures
Attribute | Attribute structure
Attribute Reference | Attribute reference structure
Boolean | A value that indicates logical true or false
Buffer | Pointer to a data item
Calendar User | Calendar user structure
Callback Data Structures | Callback data structures
Date and Time | Date and time designation
Date and Time List | List of date and time values
Date and Time Range | Range of date and time
Entry Handle | Handle for the calendar entry
Enumerated | Data type containing a value from an enumeration
Extension | Extension structure
Flags | Container for bit masks
Free Time | Free time structure
Opaque Data | Opaque data structure
Reminder | Reminder structure
Reminder Reference | Reminder reference structure
Return Code | Return value indicating either that a function succeeded or why it failed
Service Reference | Service reference structure
Session Handle | Handle for the calendar session
String | Character string pointer
Time Duration | Time duration

## Calendar Attributes

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.

## CSA Calendar Attributes

`Attribute Name` | `Description` | `Read-Only`
Access List | Access list attribute | No
Calendar Name | Calendar name attribute | Yes
Calendar Owner | Calendar owner attribute | Yes
Calendar Size | Calendar size attribute (computed) | Yes
Character Set | Character set attribute | No
Date Created | Calendar creation date attribute | Yes
Number Entries | Number of entries attribute (computed) | Yes
Product Identifier | Product identifier attribute | Yes
Time Zone | Time zone attribute | No
Version | Product version attribute | Yes

The following section provides additional information about the calendar attributes listed in PG.calmg.mkr.15.

- `Access List`

  When a new calendar is added and if no access list is specified, the default access list contains a special user world and its corresponding access right is `CSA_VIEW_PUBLIC_ENTRIES`, which provides access right to list and read calendar entries with public classification. The special user world includes all users.

- `Calendar Name`

  The calendar name is specified when the calendar is created using `csa_add_calendar().` It becomes read-only and cannot be changed after the calendar is created.

- `Calendar Owner`

  The calendar owner is set to the user who is running the application that calls `csa_add_calendar()` to create the calendar. It becomes read-only and cannot be changed after the calendar is created.

- `Character Set`

  The CDE common locale name should be used to set this value.

### CDE Calendar Attributes

The followings are CDE-defined calendar attributes:

- `Server Version`

  This read-only attribute shows the version number of the server managing the calendar. This attribute is a `CSA_VALUE_UINT32` type of attribute.

- `Data Version`

  This read-only attribute shows the data version of the calendar. This attribute is a `CSA_VALUE_UINT32` type of attribute.

## Entry Attributes

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.

## CSA Entry Attributes

`Attribute Name` | `Description` | `Read-Only`
Audio Reminder | Audio reminder attribute | No
Classification | Classification attribute | No
Date Completed | Date completed attribute | No
Date Created | Entry creation date attribute | Yes
Description | Description attribute | No
Due Date | Due date attribute | No
End Date | End date attribute | No
Exception Dates | Exception dates attribute | No
Flashing Reminder | Flashing reminder attribute | No
Last Update | Last update attribute | Yes
Mail Reminder | Mail reminder attribute | No
Number Recurrences | Number of recurrences attribute (computed) | Yes
Organizer | Organizer attribute | Yes
Popup Reminder | Pop-up reminder attribute | No
Priority | Priority attribute | No
Recurrence Rule | Recurrence rule attribute | No
Reference Identifier | Reference identifier attribute | Yes
Sponsor | Sponsor attribute | No
Start Date | Start date attribute | No
Status | Status attribute | No
Subtype | Subtype attribute | No
Summary | Summary attribute | No
Transparency | Time transparency or blocking attribute | No
Type | Type attribute | Yes

The following section provides additional information about the entry attributes listed in PG.calmg.mkr.17.

- `Organizer`

  The organizer of an entry is set to the user who is running the application that calls `csa_add_entry()` to add the entry to the calendar. It becomes read-only and cannot be changed after the entry is added.

- `Reference Identifier`

  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 `n:calendar@location` where `n` is a number that uniquely identifies the entry within the calendar, `calendar` is the name of the calendar, and `location` is the name of the machine where the calendar is stored.

- `Status`

  The CDE implementation defines the following additional status values:

  `CSA_X_DT_STATUS_ACTIVE`

  `CSA_X_DT_STATUS_DELETE_PENDING`

  `CSA_X_DT_STATUS_ADD_PENDING`

  `CSA_X_DT_STATUS_COMMITTED`

  `CSA_X_DT_STATUS_CANCELLED`

- `Type`

  The value becomes read-only and cannot be changed after the entry is added. The CDE implementation defines the following additional type value:

  `CSA_X_DT_TYPE_OTHER`

### CDE Entry Attributes

The following are CDE-defined entry attributes:

- `Show Time`

  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 `csa_update_entry_attributes()`. This attribute is a `CSA_VALUE_SINT32` type of attribute.

- `Repeat Type`

  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 `Recurrence Rule`.

  This attribute is a `CSA_VALUE_UINT32` type of attribute.

  The following values are defined:

  `CSA_X_DT_REPEAT_ONETIME`

  `CSA_X_DT_REPEAT_DAILY`

  `CSA_X_DT_REPEAT_WEEKLY`

  `CSA_X_DT_REPEAT_BIWEEKLY`

  `CSA_X_DT_REPEAT_MONTHLY_BY_WEEKDAY`

  `CSA_X_DT_REPEAT_MONTHLY_BY_DATE`

  `CSA_X_DT_REPEAT_YEARLY`

  `CSA_X_DT_REPEAT_EVERY_NDAY`

  `CSA_X_DT_REPEAT_EVERY_NWEEK`

  `CSA_X_DT_REPEAT_EVERY_NMONTH`

  `CSA_X_DT_REPEAT_MON_TO_FRI`

  `CSA_X_DT_REPEAT_MONWEDFRI`

  `CSA_X_DT_REPEAT_TUETHUR`

  `CSA_X_DT_REPEAT_WEEKDAYCOMBO`

  `CSA_X_DT_REPEAT_OTHER`

  `CSA_X_DT_REPEAT_OTHER_WEEKLY`

  `CSA_X_DT_REPEAT_OTHER_MONTHLY`

  `CSA_X_DT_REPEAT_OTHER_YEARLY`

- `Repeat Times`

  This attribute shows the number of times an entry repeats. This is a read- only attribute and is derived from the entry attribute `Recurrence Rule`. This attribute is a `CSA_VALUE_UINT32` type of attribute.

- `Repeat Interval`

  This attribute tells how often an entry with repeat types `CSA_X_DT_REPEAT_EVERY_NDAY, CSA_X_DT_REPEAT_EVERY_NWEEK`, or `CSA_X_DT_REPEAT_EVERY_NMONTH` repeats. This is a read-only attribute, and is derived from the entry attribute `Recurrence Rule.` For example, if the value of this attribute is 3 and the repeat type is `CSA_X_DT_REPEAT_EVERY_NWEEK`, the entry repeats every three weeks. This attribute is a `CSA_VALUE_UINT32` type of attribute.

- `Repeat Occurrence Number`

  If the entry's repeat type is `CSA_X_DT_REPEAT_MONTHLY_BY_WEEKDAY`, this attribute tells in which week the entry repeats. This is a read-only attribute and is derived from the entry attribute `Recurrence Rule`. This attribute is a `CSA_VALUE_SINT32` type of attribute.

- `Sequence End Date`

  This entry attribute shows the end date of the sequence. This is a read-only attribute and is derived from the entry attribute `Recurrence Rule`. This attribute is a `CSA_VALUE_DATE_TIME` type of attribute.

## General Information about Functions

The following general information applies to all functions:

- Character set restriction

  The calendar attribute, `CSA_CAL_ATTR_CHARACTER_SET`, is used to store the locale information of the calendar.

  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.

- Type checking for attribute values is provided for the predefined attributes only.

- When a function takes both a session handle and an entry handle, the session handle is always ignored in the CDE implementation.

- Entry attributes `CSA_ENTRY_ATTR_RECURRENCE_RULE` and `CSA_ENTRY_ATTR_EXCEPTION_DATES` are used to specify recurrence information of a calendar entry. Information in the `CSA_ENTRY_ATTR_RECURRENCE_RULE` attribute can be queried using the following attributes: `CSA_X_DT_ENTRY_ATTR_REPEAT_TYPE`, `CSA_X_DT_ENTRY_ATTR_REPEAT_TIMES`, `CSA_X_DT_ENTRY_ATTR_REPEAT_INTERVAL`, `CSA_X_DT_ENTRY_ATTR_REPEAT_OCCURRENCE_NUM`, and `CSA_X_DT_ENTRY_ATTR_SEQUENCE_END_DATE`. These computed attributes are read-only.

- The `CSA_calendar_user` 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 `user_name` field is used and all other fields are ignored. In the latter case, for example, when specifying the calendar to log onto, only the `calendar_address` field is used and all other fields are ignored. The format is `calendar@location` where `calendar` is the name of the calendar and `location` is the name of the machine where the calendar is stored.

- Attributes of value type `CSA_VALUE_ATTENDEE_LIST` are not supported and `CSA_E_INVALID_ATTRIBUTE_VALUE` will be returned if they are specified.

- Although the `repeat_count` and `snooze_time` fields in the `CSA_reminder` 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.

- The user interface extension `CSA_X_UI_ID_EXT` is not supported.

## Administration Functions

This section contains descriptions for the administration functions supported in the CDE implementation. See the relevant man page for more information.

- Free – Frees memory allocated by the calendaring service.

      CSA_return_code
      csa_free(
        CSA_buffer      memory
      );

- List Calendars – Lists the calendars supported by a calendar server.

      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
      );

  A host name where the server runs should be passed in `calendar_server`.

- Logon – Logs on to the calendar service and establishes a session with a calendar.

      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
      );

  Arguments `calendar_service, password, character_set,` and `required_csa_version` are not used.

  The `calendar_address` field of the `CSA_calendar_user` structure pointed to by `user` specifies the calendar to log onto. The format is `calendar@location` where `calendar` is the name of the calendar and `location` is the host name where the calendar is stored.

  The CDE-defined extension `CSA_X_DT_GET_USER_ACCESS_EXT` 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 `item_data` field of the extension structure.

- Logoff – Terminates a session with a calendar.

      CSA_return_code
      csa_logoff(
        CSA_session_handle     session,
        CSA-extension     *logoff_extensions
      );

- Query Configuration – Determines information about the installed CSA configuration.

      CSA_return_code
      csa_query_configuration(
              CSA_session_handle      session,
              CSA_enum                item,
              CSA_buffer              *reference,
              CSA_extension           *query_configuration_extensions
      );

  The following items are not supported by this implementation of CDE:

  `CSA_CONFIG_CHARACTER_SET`

  `CSA_CONFIG_LINE_TERM`

  `CSA_CONFIG_VER_IMPLEM`

## Calendar Management Functions

This section contains descriptions for the calendar management functions supported in the CDE implementation. See the relevant man page for more information.

- Add calendar – Adds a calendar to the calendar service.

      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
      );

  The first argument `session` is ignored.

  The `calendar_address` field of the `CSA_calendar_user` structure pointed to by `user` specifies the name and the location of the calendar to be created. The format is `calendar@location` where `calendar` is the name of the calendar and `location` is the host name where the calendar is to be stored; for example, `my_calendar@my_host`.

- Call Callbacks – Forces the invocation of the callback functions associated with the specified callback list(s).

      CSA_return_code
      csa_call_callbacks(
        CSA_session_handle      session,
        CSA_flags      reason,
        CSA_extension      *call_callbacks_extensions
      );

- Delete Calendar – Deletes a calendar from the calendar service.

      CSA_return_code
      csa_delete_calendar(
        CSA_session_handle      session,
        csa_extension      *delete_calendar_extensions
      );

- List Calendar Attributes – Lists the names of the calendar attributes associated with a calendar.

      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
      );

- Read Calendar Attributes – Reads and returns the calendar attribute values for a calendar.

      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
      );

- Register Callback Functions – Registers the callback function to be invoked with the specified type of updates in the calendar.

      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
      );

- Unregister Callback Functions – Unregisters the specified callback function.

      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
      );

- Update Calendar Attributes – Updates the calendar attribute values for a calendar.

      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
      );

## Entry Management Functions

This section contains descriptions for the entry management functions supported in the CDE implementation. See the relevant man page for more information.

- Add Entry – Adds an entry to the specified calendar.

      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
      );

- Delete Entry – Deletes an entry from the specified calendar.

      CSA_return_code
      csa_delete_entry(
              CSA_session_handle      session,
              CSA_entry_handle        entry,
              CSA_enum                delete_scope,
              CSA_extension           *delete_entry_extensions
      );

- List Entries – Lists the calendar entries that match all the attribute search criteria.

      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
      );

  The following information details more about the operators specified in `list_operators`:

  Only the operators `CSA_MATCH_ANY` and `CSA_MATCH_EQUAL_TO` are supported for the attribute value types `CSA_VALUE_REMINDER`, `CSA_VALUE_CALENDAR_USER`, and `CSA_VALUE_DATE_TIME_RANGE`.

  Only the operators `CSA_MATCH_ANY`, `CSA_MATCH_EQUAL_TO`, `CSA_MATCH_NOT_EQUAL_TO`, and `CSA_MATCH_CONTAIN` are supported for the attribute value type `CSA_VALUE_STRING`. The operator `CSA_MATCH_CONTAIN` only applies to `CSA_VALUE_STRING` type of attributes.

  Matching of attributes with the value types `CSA_VALUE_OPAQUE_DATA`, `CSA_VALUE_ACCESS_LIST, CSA_VALUE_ATTENDEE_LIST,` and, `CSA_VALUE_DATE_TIME_LIST` are not supported. The only exception is the attribute `CSA_ENTRY_ATTR_REFERENCE_IDENTIFIER`. The operator `CSA_MATCH_EQUAL_TO` is supported for this attribute.

- List Entry Attributes – Lists the names of the entry attributes associated with the specified entry.

      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
      );

- List Entry Sequence – Lists the recurring calendar entries that are associated with a calendar entry.

      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
      );

  `CSA_E_INVALID_PARAMETER` is returned if the specified entry is a one-time entry.

- Read Entry Attributes – Reads and returns the calendar entry attribute values for a specified entry.

      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
      );

- Read Next Reminder – Reads the next reminder of the given type in the specified calendar relative to a given time.

      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
      );

- Update Entry Attributes – Updates the calendar entry attributes.

      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
      );

  Update propagation is not supported; the `update_propagation` argument should be set to `CSA_FALSE`.