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.