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:

• Library and Header Files

• Demo Program

• Using the Calendar API

• Overview of the CSA API

• Functional Architecture

• Data Structures

• Calendar Attributes

• Entry Attributes

• General Information About Functions

• Administration Functions

• Calendar Management Functions

• Entry Management Functions

• Code Examples

Library and Header Files

To use the Calendar API, you need to link with 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 Table 10-1 . 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.

Table 10-1 Derivation of C Naming Conventions

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 Extensions for more information. The relationship of the CSA interface to a calendar-enabled application and the calendar service is shown in Figure 10-1.

Figure 10-1 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 Figure 10-2.

Figure 10-2 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 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.