test

Solaris Common Desktop Environment: Programmer's Guide

Chapter 10 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

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

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

Graphic

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

Graphic

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.

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:

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 a user 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 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

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.

About the CDE Implementation

The CDE implementation of the CSA API consists of a library which provides access to the CDE calendar server. ONC RPC is used for communication between the library and the server. The calendar server in the CDE implementation is a version 5 server which supports calendar protocol versions 2 to 5 and data versions 3 and 4. Calendar protocol versions 2 to 4 and data version 3 are for backward compatibility to OpenWindows Calendar Manager. Calendar protocol version 5 and data version 4 support the CSA interface and data extensibility.

Table 10-2 Server Version/Data Version Supported

Server Version 

Data Version Supported 

2 

1 

3 

2 

4 

3 

5 

3, 4 

Access models supported

Two access models are supported by the calendar API. The access model specified in the XAPIA CSA specification is supported for data version 4 only. The OpenWindows Calendar Manager access model is supported for data versions 1 to 3. In the OpenWindows Calendar Manager access model, the accessibility of a calendar is controlled by an access list which specifies who has what access rights. Three access rights are defined: CSA_X_DT_BROWSE_ACCESS (user can list and read calendar entries), CSA_X_DT_INSERT_ACCESS (user can insert calendar entries), and CSA_X_DT_DELETE_ACCESS (user can delete calendar entries). Since the calendar API allows access to calendars of all versions, the programmer should interpret the access rights contained in an access list using the correct access model depending on the data version.

When a calendar is created, unless an access list is specified during creation, the default access list consists of one entry with "world" as the user name; the associated access right is "browse public entries." The user name "world" is a special name which means all users.

By default, a user with the same user name as the owner of the calendar can access the calendar with full owner's access from any machine. To have stricter access control, names of the form "owner-user-name@host" can be added to the access list of the calendar. When such an entry is added to the access list, the corresponding access right has to be CSA_OWNER_RIGHTS for data version 4 and (CSA_X_DT_BROWSE_ACCESS|CSA_X_DT_INSERT_ACCESS|CSA_X_DT_DELETE_ACCESS) for data version 3. After such entries are added to the access list, only users from the specified hosts can access the calendar with full owner's rights.

Data Structures

Table 10-3 lists the CSA data structures. See the relevant man page for complete information.

Table 10-3 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

Table 10-4 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.

Table 10-4 CSA Calendar Attributes

Attribute Name 

Symbolic Name 

Server 

Version 

Data 

Version 

Read 

Only? 

Access List 

CSA_CAL_ATTR_ACCESS_LIST_ 

2-5 

1-4 

No 

Calendar Name 

CSA_CAL_ATTR_CALENDAR_NAME 

2-5 

1-4 

Yes* 

Calendar Owner 

CSA_CAL_ATTR_CALENDAR_OWNER 

2-5 

1-4 

Yes* 

Calendar Size 

CSA_CAL_ATTR_CALENDAR_SIZE 

5 

3,4 

Yes 

Character Set 

CSA_CAL_ATTR_CHARACTER_SET 

5 

4 

Yes 

Data Version** 

CSA_X_DT_CAL_ATTR_DATA_VERSION 

2-5 

1-4 

Yes 

Date Created 

CSA_CAL_ATTR_DATE_CREATED 

5 

4 

Yes 

Number Entries 

CSA_CAL_ATTR_NUMBER_ENTRIES 

2-5 

1-4 

Yes 

Product Identifier 

CSA_CAL_ATTR_PRODUCT_IDENTIFIER 

2-5 

1-4 

Yes 

Server Version** 

CSA_X_DT_CAL_ATTR_SERVER_VERSION 

2-5 

1-4 

Yes 

Time Zone 

CSA_CAL_ATTR_TIME_ZONE 

5 

4 

Yes 

Version 

CSA_CAL_ATTR_VERSION 

2-5 

1-4 

Yes 

*specified when the calendar is created and read-only afterwards

**CDE only

The following Calendar attributes are not supported:

CSA_CAL_ATTR_COUNTRY 
CSA_CAL_ATTR_LANGUAGE  
CSA_CAL_ATTR_WORK_SCHEDULE

The following descriptions provide additional information about some of the calendar attributes listed in Table 10-4 .

The followings are CDE-defined calendar attributes:

Entry Attributes

Table 10-5 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.

Table 10-5 CSA Entry Attibutes

Attribute Name 

Symbolic Name 

Server 

Version 

Data 

Version 

Read 

Only? 

Audio Reminder 

CSA_ENTRY_ATTR_AUDIO_REMINDER 

2-5 

1-4 

No 

Character Set* 

CSA_X_DT_ENTRY_ATTR_CHARACTER_SET 

5 

4 

No 

Classification 

CSA_ENTRY_ATTR_CLASSIFICATION 

5 

2-4 

No 

Date Completed 

CSA_ENTRY_ATTR_DATE_COMPLETED 

5 

4 

No 

Date Created 

CSA_ENTRY_ATTR_DATE_CREATED 

5 

4 

Yes 

Description 

CSA_ENTRY_ATTR_DESCRIPTION 

5 

4 

No 

Due Date 

CSA_ENTRY_ATTR_DUE_DATE 

5 

4 

No 

End Date 

CSA_ENTRY_ATTR_END_DATE 

2-5 

1-4 

No 

Exception Dates 

CSA_ENTRY_ATTR_EXCEPTION_DATES 

5 

4 

No 

Flashing Reminder 

CSA_ENTRY_ATTR_FLASHING_REMINDER 

2-5 

1-4 

No 

Last Update 

CSA_ENTRY_ATTR_LAST_UPDATE 

5 

4 

Yes 

Mail Reminder 

CSA_ENTRY_ATTR_MAIL_REMINDER 

2-5 

1-4 

No 

Number Recurrences 

CSA_ENTRY_ATTR_NUMBER_RECURRENCES 

5 

4 

Yes 

Organizer 

CSA_ENTRY_ATTR_ORGANIZER 

2-5 

1-4 

Yes 

Popup Reminder 

CSA_ENTRY_ATTR_POPUP_REMINDER 

2-5 

1-4 

No 

Priority 

CSA_ENTRY_ATTR_PRIORITY 

5 

4 

No 

Recurrence Rule 

CSA_ENTRY_ATTR_RECURRENCE_RULE 

5 

4 

No 

Reference Identifier 

CSA_ENTRY_ATTR_REFERENCE_IDENTIFIER 

2-5 

1-4 

Yes 

Repeat Interval* 

CSA_X_ENTRY_ATTR_REPEAT_INTERVAL 

2-5 

1-4 

** 

Repeat Occurrence* 

CSA_X_ENTRY_ATTR_REPEAT_OCCURRENCE_NUM 

2-5 

1-4 

** 

Repeat Times* 

CSA_X_ENTRY_ATTR_REPEAT_TIMES 

2-5 

1-4 

** 

Repeat Type* 

CSA_X_DT_ENTRY_ATTR_REPEAT_TYPE 

2-5 

1-4 

** 

Sequence End Date* 

CSA_X_ENTRY_ATTR_SEQUENCE_END_DATE 

2-5 

1-4 

** 

Showtimes* 

CSA_X_ENTRY_ATTR_SHOWTIME 

2-5 

1-4 

No 

Sponsor 

CSA_ENTRY_ATTR_SPONSOR 

5 

4 

No 

Start Date 

CSA_ENTRY_ATTR_START_DATE 

2-5 

1-4 

No 

Status 

CSA_ENTRY_ATTR_STATUS  

2-5 

1-4 

No 

Subtype 

CSA_ENTRY_ATTR_SUBTYPE 

2-5 

1-4 

No 

Summary 

CSA_ENTRY_ATTR_SUMMARY 

2-5 

1-4 

No 

Transparency 

CSA_ENTRY_ATTR_TIME_TRANSPARENCY 

5 

4 

No 

Type 

CSA_ENTRY_ATTR_TYPE 

2-5 

1-4 

Yes*** 

* CDE only

** This attribute can be specified and modified for data version 1 to 3, but is read-only for data version 4; for data version 4, the value is derived from the entry attribute CSA_ENTRY_ATTR_RECURRENCE_RULE

***Specified when the entry is added to the calendar and read-only afterwards

The following Entry attributes are not supported:

CSA_ENTRY_ATTR_ATTENDEE_LIST
CSA_ENTRY_ATTR_EXCEPTION_RULE  
CSA_ENTRY_ATTR_RECURRING_DATES 
CSA_ENTRY_ATTR_SEQUENCE_NUMBER

The following descriptions provide additional information about some of the entry attributes listed in Table 10-5 .

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
	CSA_X_DT_TYPE_OTHER

CDE Entry Attributes

The following are CDE-defined entry attributes:

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

Entry attributes for recurrence information

For data versions 1 to 3, the following entry attributes are used to specify recurrence information for an entry. They are all read/write 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 
CSA_X_DT_ENTRY_ATTR_SEQUENCE_END_DATE

For data version 4, 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 
CSA_X_DT_ENTRY_ATTR_SEQUENCE_END_DATE

These computed attributes are read-only for data version 4.

Supported Values by Data Version

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

Data version 4 supports all status values:

CSA_STATUS_ACCEPTED
CSA_STATUS_NEEDS_ACTION  
CSA_STATUS_SENT  
CSA_STATUS_TENTATIVE 
CSA_STATUS_CONFIRMED  
CSA_STATUS_REJECTED  
CSA_STATUS_COMPLETED 
CSA_STATUS_DELEGATED  
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
CSA_SUBTYPE_APPOINTMENT
CSA_SUBTYPE_HOLIDAY

Data version 4 supports all defined values as well as the following application-defined values:

CSA_SUBTYPE_APPOINTMENT
CSA_SUBTYPE_CLASS  
CSA_SUBTYPE_HOLIDAY  
CSA_SUBTYPE_MEETING 
CSA_SUBTYPE_MISCELLANEOUS  
CSA_SUBTYPE_PHONE_CALL  
CSA_SUBTYPE_SICK_DAY 
CSA_SUBTYPE_SPECIAL_OCCASION  
CSA_SUBTYPE_TRAVEL 
CSA_SUBTYPE_VACATION
CSA_TYPE_EVENT 
CSA_TYPE_TODO  
CSA_X_DT_TYPE_OTHER

Data version 4 supports all defined values:

CSA_TYPE_EVENT 
CSA_TYPE_TODO  
CSA_TYPE_MEMO  
CSA_X_DT_TYPE_OTHER
Note -

Only some combinations of type and subtype values--listed below--are supported in data version 1 to 3.

Combinations supported in data version 1:

CSA_TYPE_EVENT with subtype CSA_SUBTYPE_APPOINTMENT  
CSA_X_DT_TYPE_OTHER with no subtype value

Combinations supported in data versions 2 and 3:

CSA_TYPE_EVENT with subtype CSA_SUBTYPE_APPOINTMENT  
CSA_TYPE_EVENT with subtype CSA_SUBTYPE_HOLIDAY  
CSA_TYPE_TODO with no subtype value  
CSA_X_DT_TYPE_OTHER with no subtype value
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_DATE 
CSA_X_DT_REPEAT_YEARLY

Values supported in data version 3:

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

For data version 4, this is a read-only attribute and the value is derived from the entry attribute CSA_ENTRY_ATTR_RECURRENCE_RULE.

General Information About Functions

The following general information applies to all functions:

Note -

All data except textual description passed in the library must be in ASCII format; the library supports single-byte as well as multibyte character strings.

Function Extensions Supported

Administration Functions

This section contains descriptions for the administration functions supported in the CDE implementation; a function prototype and a list of possible return codes are included for each function. See the relevant man page for more information.

CSA_return_code 
csa_free(CSA_buffer								memory  );

Return Codes for csa_free:

CSA_SUCCESS CSA_E_INVALID_MEMORY 

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.

Return Codes for csa_list_calendars:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_X_DT_E_INVALID_SERVER_LOCATION 
CSA_X_DT_E_SERVICE_NOT_REGISTERED  
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_NOT_SUPPORTED  
CSA_E_SERVICE_UNAVAILABLE
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);

The following arguments are not used: calendar_service, password, character_set, and required_csa_version.

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

Return Codes for csa_logon:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER 
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_CALENDAR_NOT_EXIST  
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_NO_AUTHORITY 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE  
CSA_E_SERVICE_UNAVAILABLE 
CSA_X_DT_E_BACKING_STORE_PROBLEM
CSA_return_code
 csa_logoff(
  CSA_session_handle							session,
  CSA-extension							*logoff_extensions);

Return Codes for csa_logoff:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY 
CSA_E_INVALID_SESSION_HANDLE
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

Return Codes for csa_query_configuration:

CSA_SUCCESS 
CSA_E_INVALID_ENUM  
CSA_E_INVALID_PARAMETER  
CSA_E_INSUFFICIENT_MEMORY 
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_UNSUPPORTED_ENUM 
CSA_E_UNSUPPORTED_FUNCTION_EXT

Calendar Management Functions

This section contains descriptions for the calendar management functions supported in the CDE implementation; a function prototype and a list of possible return codes are included for each function. See the relevant man page for more information.

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.

Return Codes for csa_add_calendar:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_CALENDAR_EXISTS  
CSA_E_NO_AUTHORITY 
CSA_E_READONLY  
CSA_E_INVALID_ATTRIBUTE  
CSA_E_INVALID_ATTRIBUTE_VALUE 
CSA_E_UNSUPPORTED_ATTRIBUTE  
CSA_E_INVALID_DATE_TIME  
CSA_E_DISK_FULL 
CSA_X_DT_E_BACKING_STORE_PROBLEM  
CSA_X_DT_E_INVALID_SERVER_LOCATION 
CSA_X_DT_E_SERVICE_NOT_REGISTERED  
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE
CSA_return_code
 csa_call_callbacks(
   CSA_session_handle								session,
   CSA_flags								reason, 
   CSA_extension								*call_callbacks_extensions);

Return Codes for csa_call_callbacks:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT  
CSA_E_INVALID_FLAG 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE 
CSA_X_DT_E_MT_UNSAFE
CSA_return_code
  csa_delete_calendar(
   CSA_session_handle				session,
   csa_extension				 		*delete_calendar_extensions);

Return Codes for csa_delete_calendar:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_NOT_SUPPORTED 
CSA_E_NO_AUTHORITY  
CSA_X_DT_E_BACKING_STORE_PROBLEM 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE
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);

Return Codes for csa_list_calendar_attributes:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_NOT_SUPPORTED 
CSA_E_NO_AUTHORITY 
CSA_X_DT_E_BACKING_STORE_PROBLEM 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE
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);

Return Codes for csa_read_calendar_attributes:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE
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);

Return Codes for csa_register_callback:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_INVALID_FLAG 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE
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);

Return Codes for csa_unregister_callback:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_INVALID_FLAG 
CSA_E_CALLBACK_NOT_REGISTERED  
CSA_E_FAILURE
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);

Return Codes for csa_update_calendar_attributes:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_NO_AUTHORITY 
CSA_E_INVALID_ATTRIBUTE_VALUE  
CSA_E_INVALID_ATTRIBUTE 
CSA_E_UNSUPPORTED_ATTRIBUTE  
CSA_E_READONLY  
CSA_E_INVALID_DATE_TIME 
CSA_E_DISK_FULL  
CSA_X_E_BACKING_STORE_PROBLEM 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE

Entry Management Functions

This section contains descriptions for the entry management functions supported in the CDE implementation; a function prototype and a list of possible return codes are included for each function. See the relevant man page for more information.

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

Return Codes for csa_add_entry:

CSA_SUCCESS 
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE  
CSA_E_NO_AUTHORITY 
CSA_E_READONLY  
CSA_E_UNSUPPORTED_ATTRIBUTE  
CSA_E_INVALID_ATTRIBUTE 
CSA_E_INVALID_ATTRIBUTE_VALUE  
CSA_E_INVALID_DATE_TIME  
CSA_E_INVALID_RULE 
CSA_E_DISK_FULL  
CSA_X_E_BACKING_STORE_PROBLEM 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE

Minimum set of attributes to be specified when adding an entry:

For data version 1-3:

Must specify:

CSA_ENTRY_ATTR_START_DATE
CSA_ENTRY_ATTR_TYPE

Default will be set if these are not specified:

CSA_ENTRY_ATTR_CLASSIFICATION (CSA_CLASS_PUBLIC)
CSA_ENTRY_ATTR_STATUS (CSA_X_DT_STATUS_ACTIVE) 
CSA_ENTRY_ATTR_SUBTYPE (CSA_SUBTYPE_APPOINTMENT for type
      CSA_TYPE_EVENT;
this attribute is not supported for type
      CSA_TYPE_TODO)
CSA_ENTRY_ATTR_SUMMARY (NULL string)
CSA_X_ENTRY_ATTR_REPEAT_TYPE (CSA_X_REPEAT_ONETIME) 
CSA_X_ENTRY_ATTR_SHOWTIME (1 => true)

For data version 4:

Must specify:

CSA_ENTRY_ATTR_START_DATE
CSA_ENTRY_ATTR_TYPE

Default will be set if these are not specified:

CSA_ENTRY_ATTR_CLASSIFICATION
(CSA_CLASS_PUBLIC)
  CSA_ENTRY_ATTR_STATUS (CSA_X_STATUS_ACTIVE) 
CSA_ENTRY_ATTR_SUBTYPE (CSA_SUBTYPE_APPOINTMENT for type
      CSA_TYPE_EVENT) 
CSA_ENTRY_ATTR_SUMMARY (NULL string)
  CSA_X_ENTRY_ATTR_SHOWTIME (1 =>true)
CSA_return_code
 csa_delete_entry(
  CSA_session_handle     session,
  CSA_entry_handle       entry,
  CSA_enum               delete_scope,
  CSA_extension          *delete_entry_extensions);

Return Codes for csa_delete_entry:

CSA_SUCCESS 
CSA_E_INVALID_ENUM  
CSA_E_INVALID_PARAMETER  
CSA_E_UNSUPPORTED_FUNCTION_EXT 
CSA_E_INSUFFICIENT_MEMORY  
CSA_E_INVALID_SESSION_HANDLE 
CSA_E_INVALID_ENTRY_HANDLE  
CSA_E_NO_AUTHORITY  
CSA_X_DT_E_ENTRY_NOT_FOUND 
CSA_E_DISK_FULL  
CSA_X_E_BACKING_STORE_PROBLEM 
CSA_X_DT_E_INVALID_SERVER_LOCATION  
CSA_X_DT_E_SERVICE_NOT_REGISTERED 
CSA_X_DT_E_SERVER_TIMEOUT  
CSA_E_FAILURE 
CSA_E_SERVICE_UNAVAILABLE
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);

Note the following 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.

Return Codes for csa_list_entries:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER  CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY  CSA_E_INVALID_SESSION_HANDLE  CSA_E_NO_AUTHORITY 

CSA_E_INVALID_ATTRIBUTE_VALUE  CSA_E_INVALID_DATE_TIME  CSA_E_INVALID_ENUM 

CSA_E_UNSUPPORTED_ENUM  CSA_X_E_BACKING_STORE_PROBLEM 

CSA_X_DT_E_INVALID_SERVER_LOCATION  CSA_X_DT_E_SERVICE_NOT_REGISTERED 

CSA_X_DT_E_SERVER_TIMEOUT  CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

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

Return Codes for csa_list_entry_attributes:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER  CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY  CSA_E_INVALID_SESSION_HANDLE 

CSA_E_INVALID_ENTRY_HANDLE  CSA_X_E_ENTRY_NOT_FOUND 

CSA_X_E_BACKING_STORE_PROBLEM  CSA_X_DT_E_INVALID_SERVER_LOCATION 

CSA_X_DT_E_SERVICE_NOT_REGISTERED  CSA_X_DT_E_SERVER_TIMEOUT  CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

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.

Return Codes for csa_list_entry_sequence:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER  CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY  CSA_E_INVALID_SESSION_HANDLE 

CSA_E_INVALID_ENTRY_HANDLE  CSA_E_INVALID_DATE_TIME  CSA_X_E_ENTRY_NOT_FOUND 

CSA_X_E_BACKING_STORE_PROBLEM  CSA_X_DT_E_INVALID_SERVER_LOCATION 

CSA_X_DT_E_SERVICE_NOT_REGISTERED  CSA_X_DT_E_SERVER_TIMEOUT  CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

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

Return Codes for csa_read_entry_attributes:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER  CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY  CSA_E_INVALID_SESSION_HANDLE 

CSA_E_INVALID_ENTRY_HANDLE  CSA_X_E_ENTRY_NOT_FOUND 

CSA_X_E_BACKING_STORE_PROBLEM  CSA_X_DT_E_INVALID_SERVER_LOCATION 

CSA_X_DT_E_SERVICE_NOT_REGISTERED  CSA_X_DT_E_SERVER_TIMEOUT  CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

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_reminder_reference       **reminder_references,
  CSA_extension					  *read_next_reminder_extensions);

Return Codes for csa_read_next_reminder:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER  CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY  CSA_E_INVALID_SESSION_HANDLE 

CSA_E_INVALID_DATE_TIME  CSA_E_NO_AUTHORITY  CSA_X_E_BACKING_STORE_PROBLEM 

CSA_X_DT_E_INVALID_SERVER_LOCATION  CSA_X_DT_E_SERVICE_NOT_REGISTERED 

CSA_X_DT_E_SERVER_TIMEOUT  CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

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.

Return Codes for csa_update_entry_attributes:

CSA_SUCCESS 

CSA_E_INVALID_PARAMETER  CSA_E_UNSUPPORTED_FUNCTION_EXT 

CSA_E_INSUFFICIENT_MEMORY  CSA_E_INVALID_SESSION_HANDLE 

CSA_E_INVALID_ENTRY_HANDLE  CSA_E_NO_AUTHORITY  CSA_E_READONLY 

CSA_E_INVALID_ENUM  CSA_E_UNSUPPORTED_ATTRIBUTE  CSA_E_INVALID_ATTRIBUTE 

CSA_E_INVALID_ATTRIBUTE_VALUE  CSA_E_INVALID_DATE_TIME  CSA_E_INVALID_RULE 

CSA_E_DISK_FULL  CSA_X_E_BACKING_STORE_PROBLEM 

CSA_X_DT_E_INVALID_SERVER_LOCATION  CSA_X_DT_E_SERVICE_NOT_REGISTERED 

CSA_X_DT_E_SERVER_TIMEOUT  CSA_E_FAILURE 

CSA_E_SERVICE_UNAVAILABLE

csa_add_event 
csa_add_memo  
csa_add_todo  
csa_free_time_search  
csa_look_up  
csa_restore 
csa_save

Code Examples

To List and Print Calendars

Example 10-1 Listing and Printing Calendars Supported by Server 

Example:
List and print out the calendars supported by a server.
 	   Free memory returned by a CSA function. 
list_calendar() 
{
 	CSA_return_code		stat;
	CSA_uint32		i, number;
 	CSA_calendar_user	*calendars;
 	char			*host;

  	/*specify some machine in the network */
 	host = "somehost";

  	stat= csa_list_calendars(host, &number, &calendars, NULL);
  	for (i = 0; i< number; i++) {
 		/* the calendar_address field contains the address of the
 		 * the calendar in the format "user@host" 		 */
 	printf("%d: %s\n", i, calendars[i].calendar_address); 	
   }

  	/* Example: free memory returned by a CSA function
 	 * free the memory returned by csa_list_calendars above
 	 */
 	stat = csa_free(calendars); 
}

To Add a Calendar

Example 10-2 Adding a Calendar Named "activity" to Host "host1" 

#include <csa/csa.h>  

CSA_access_rights *setup_access_list() {
 	CSA_access_rights	*ptr1, *ptr2;
  	/* Allow any user to view public and confidential entries and
 	 * user "user1" to view and insert public entries.
 	 * The special user name "world" means any user.
   */

  	ptr2 = (CSA_access_rights *)calloc(1, sizeof(CSA_access_rights));
 	ptr2->user = (CSA_calendar_user *)calloc(1, sizeof(CSA_calendar_user));
 	ptr2->user->user_name = strdup("world");
 	ptr2->user->user_type = CSA_USER_TYPE_INDIVIDUAL;
 	ptr2->flags = CSA_VIEW_PUBLIC_ENTRIES | CSA_VIEW_CONFIDENTIAL_ENTRIES;
  	ptr1 = (CSA_access_rights *)calloc(1, sizeof(CSA_access_rights));
 	ptr1->user = (CSA_calendar_user *)calloc(1, sizeof(CSA_calendar_user));
 	ptr1->user->user_name = strdup("user1");
 	ptr1->user->user_type = CSA_USER_TYPE_INDIVIDUAL;
 	ptr1->flags = CSA_VIEW_PUBLIC_ENTRIES | CSA_INSERT_PUBLIC_ENTRIES;
 	ptr1->next = ptr2; 
} 

void destroy_access_list(CSA_access_rights *list) 
{
 	CSA_access_rights	*ptr;

  	while (list != NULL) {
 		ptr = list->next;

  		if (list->user) {
 			if (list->user->user_name)
 				free(list->user->user_name);
 			free(list->user);
 		} 		free(list);
  		list = ptr;
 	}
} 
add_calendar() 
{
 	CSA_return_code		stat;
 	CSA_calendar_user	caddr;
 	CSA_attribute		attr;
 	CSA_attribute_value	attr_val;

  	/* Specify the calendar to add */

 	caddr.user_name = NULL;
 	caddr.user_type = NULL;
 	caddr.calendar_address = "activity@host1";
 	caddr.calendar_user_extensions = NULL;

  	/* set up the access list */
 	attr_val.type			= CSA_VALUE_ACCESS_LIST;
 	attr_val.item.access_list_value	= setup_access_list();
 	attr.name			= CSA_CAL_ATTR_ACCESS_LIST;
 	attr.value			= &attr_val;
 	attr.attribute_extensions	= NULL;
  	stat = csa_add_calendar(NULL, &caddr, 1, &attr, NULL);
  	destroy_access_list(attr_val.item.access_list_value);
}

To Log on to a Calendar

Example 10-3 Logging on to a Calendar 

CSA_session_handle	cal;

logon() 
{
 	CSA_return_code		stat;
 	CSA_calendar_user	caddr
; 	CSA_flags		access;
 	CSA_extension		logon_exts[2];
 	CSA_X_COM_support	check_support[2];

  	/* Specify the calendar to logon to */
 	caddr.user_name = NULL;
 	caddr.user_type = CSA_USER_TYPE_INDIVIDUAL;
 caddr.calendar_address = "user@host";
 caddr.calendar_user_extensions = NULL;

  	/* Specify the get user access extension (CSA_X_DT_GET_USER_ACCESS_EXT)
 	 * to retrieve the user's access right with respect to the calendar.
 	 */
 	logon_exts[0].item_code		= CSA_X_DT_GET_USER_ACCESS_EXT;
 	logon_exts[0].item_data		= 0;
 logon_exts[0].item_reference	= NULL;
 	logon_exts[0].extension_flags	= NULL;

  /* Specify the CSA_X_COM_SUPPORT_EXT extension to check
 	 * whether the CSA_X_XT_APP_CONTEXT_EXT extension and the
 	 * CSA_X_UI_ID_EXT extension are supported.
 	 */
 	check_support[0].item_code	= CSA_X_XT_APP_CONTEXT_EXT;
 check_support[0].flags		= NULL;
 	check_support[1].item_code	= CSA_X_UI_ID_EXT;
 	check_support[1].flags		= NULL;
  	logon_exts[1].item_code		= CSA_X_COM_SUPPORT_EXT;
 	logon_exts[1].item_data		= 2;
 	logon_exts[1].item_reference	= (CSA_buffer)check_support;
 	logon_exts[0].extension_flags	= CSA_EXT_LAST_ELEMENT;

  	stat = csa_logon(NULL, &caddr, NULL, NULL, NULL, &cal, logon_exts);

  	if (stat == CSA_SUCCESS) {
 		access = (CSA_flags)get_access_ext.item_data;
  		if (check_support[0].flag & CSA_X_COM_SUPPORTED)
 			printf("The CSA_X_XT_APP_CONTEXT_EXT extension is supported\n");
  		if (check_support[1].flag & CSA_X_COM_SUPPORTED)
 			printf("The CSA_X_UI_ID_EXT extension is supported\n");
 	}
 }

To Terminate a Calendar Session

Example 10-4 Terminating a Calendar Session

logoff() 
{
 	CSA_return_code		stat;

  	/* When the session is no longer needed, it can be terminated by
 	 * calling csa_logoff.
 	 * Terminate the session returned by csa_logon in the previous
 	 * example.
 	 */
 	stat = csa_logoff(cal, NULL); 
}

To Delete a Calendar

Example 10-5 Deleting a Calendar

delete_calendar() 
{
 	/* After a calendar session is established by calling csa_logon(),
 	 * a calendar can be deleted using csa_delete_calendar().
 	 */
 	CSA_return_code		stat;
  	stat = csa_delete_calendar(cal, NULL);
}

To Add a Calendar Entry

Example 10-6 Adding a Calendar Entry 

#include <csa/csa.h>  

CSA_return_code		stat;
CSA_session_handle	cal;
CSA_attribute		attrs[9];
CSA_attribute_value	attr_val[9];
CSA_reminder		audio;
CSA_reminder		mail;
CSA_entry_handle	new_entry;
int			i;

i = 0;

/* The start date attribute. This attribute has no default
  * value and must be specified.
  * A CSA_date_time value is a UTC based date and time value
  * expressed in the ISO 8601 standard.
  */
attrs[i].name = CSA_ENTRY_ATTR_START_DATE;
 attrs[i].value = &attr_val[i];
 attrs[i].attribute_extensions = NULL;
 attr_val[i].type = CSA_VALUE_DATE_TIME;
 attr_val[i].item.date_time_value = iso8601time(time(NULL));
 i++;

/* The end date attribute.
  * If not specified, the entry will not have the end date
  * attribute.
  */ 
attrs[i].name = CSA_ENTRY_ATTR_END_DATE;
 attrs[i].value = &attr_val[i];
 attrs[i].attribute_extensions = NULL;
 attr_val[i].type = CSA_VALUE_DATE_TIME;
 attr_val[i].item.date_time_value = iso8601time(time(NULL) + 3600);
 i++;

/* The classification attribute.
  * If not specified, the default value is CSA_CLASS_PUBLIC.
  */ 
attrs[i].name = CSA_ENTRY_ATTR_CLASSIFICATION;
attrs[i].value = &attr_val[i];
attrs[i].attribute_extensions = NULL;
attr_val[i].type = CSA_VALUE_UINT32;
attr_val[i].item.sint32_value = CSA_CLASS_CONFIDENTIAL;
i++;  

/* The type attribute. This attribute has no default value and
  * must be specified.
  */
attrs[i].name = CSA_ENTRY_ATTR_TYPE;
attrs[i].value = &attr_val[i];
attrs[i].attribute_extensions = NULL;
attr_val[i].type = CSA_VALUE_UINT32;
attr_val[i].item.sint32_value = CSA_TYPE_EVENT;
i++;  

/* The sub-type attribute.
  * If not specified, the default value is CSA_SUBTYPE_APPOINTMENT
  */ 
attrs[i].name = CSA_ENTRY_ATTR_SUBTYPE;
attrs[i].value = &attr_val[i];
attrs[i].attribute_extensions = NULL;
attr_val[i].type = CSA_VALUE_STRING; 
attr_val[i].item.string_value = CSA_SUBTYPE_APPOINTMENT; 
i++;  

/* The summary attribute */ 
attrs[i].name = CSA_ENTRY_ATTR_SUMMARY; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_STRING; 
attr_val[i].item.string_value = argv6; 
attrs[i].attribute_extensions = NULL; 
i++;  

/* The recurrence rule attribute.
  * If not specified, the entry is a one time entry.
  * The recurrence rule "D1 #3" specifies that the
  * entry is to be repeated daily for 3 days.
  */ 
attrs[i].name = CSA_ENTRY_ATTR_RECURRENCE_RULE; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_STRING; 
attr_val[i].item.string_value = argv7; 
i++;

/* The audio reminder attribute.
  * The lead time of a reminder is a CSA_time_duration value
  * which is expressed in the ISO 8601 standard.
  * For example, a lead time of 5 minutes is expressed as
  * the string "+PT300S". A negative lead time of 5 minutes
  * is expressed as "-PT300S".
  */ 
attrs[i].name = CSA_ENTRY_ATTR_AUDIO_REMINDER; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_REMINDER; 
attr_val[i].item.reminder_value = &audio; 
memset((void *)&audio, NULL, sizeof(audio)); 
audio.lead_time = "+PT300S"; i++;

/* The mail reminder attribute.
  * The e-mail address is specified in the reminder_data field
  * This reminder has a lead time of one day.
  */ 
attrs[i].name = CSA_ENTRY_ATTR_MAIL_REMINDER; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_REMINDER; 
attr_val[i].item.reminder_value = &mail; 
memset((void *)&mail, NULL, sizeof(mail)); 
mail.lead_time = "+PT86400S"; 
mail.reminder_data.data = "someuser@somehost"; 
mail.reminder_data.size = strlen(mail.reminder_data.data); 
i++;  

/* add an entry with the specified attribute values */ 
stat = csa_add_entry(cal, i, attrs, &newentry, NULL);  
if (stat == CSA_SUCCESS)
 	csa_free((CSA_buffer)newentry);

To Look Up Entries in a Calendar

Example 10-7 Looking up Calendar Entries; Reading Attribute Values 

#include <csa/csa.h>  

CSA_return_code		stat; 
CSA_session_handle	cal;
CSA_attribute		attrs[4]; 
CSA_attribute_value	attr_val[4]; 
CSA_enum		ops[4];
CSA_uint32		i; 
CSA_uint32		num_entries;
 CSA_entry_handle	*entries;
CSA_uint32		num_attributes; 
CSA_attribute		*entry_attrs;  

/* find all entries with the following criteria:
  * (all appointments in the month of August 1996 UTC time)
  * start date equals to or after 00:00:00 Aug 1 1996 UTC time
  * and start date before 00:00:00 Sep 1 1996 UTC time
  * and type equals to CSA_TYPE_EVENT
  * and sub-type equals CSA_SUBTYPE_APPOINTMENT
  */  

i = 0;  

/* start date equals to or after 00:00:00 Aug 1 1996 UTC time */ 
attrs[i].name = CSA_ENTRY_ATTR_START_DATE; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_DATE_TIME;
attr_val[i].item.date_time_value = "19960801T000000Z"; 
ops[i] = CSA_MATCH_GREATER_THAN_OR_EQUAL_TO; 
i++;  

/* start date before 00:00:00 Sep 1 1996 UTC time */ 
attrs[i].name = CSA_ENTRY_ATTR_START_DATE; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_DATE_TIME; 
attr_val[i].item.date_time_value = "19960901T000000Z" 
ops[i] = CSA_MATCH_LESS_THAN; 
i++;  

/* type equals to CSA_TYPE_EVENT */ 
attrs[i].name = CSA_ENTRY_ATTR_TYPE; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_UINT32; 
attr_val[i].item.sint32_value = CSA_TYPE_EVENT; 
ops[i] = CSA_MATCH_EQUAL_TO; 
i++;  

/* sub-type equals CSA_SUBTYPE_APPOINTMENT */ 
attrs[i].name = CSA_ENTRY_ATTR_SUBTYPE; 
attrs[i].value = &attr_val[i]; 
attrs[i].attribute_extensions = NULL; 
attr_val[i].type = CSA_VALUE_STRING; 
attr_val[i].item.string_value = CSA_SUBTYPE_APPOINTMENT; 
ops[i] = CSA_MATCH_EQUAL_TO; 
i++;  

/* do look up */ 
stat = csa_list_entries(csa, i, attrs, ops, &num_entries, &entries, NULL);

  if (stat == CSA_SUCCESS) {
     for (i = 0; i < num_entries; i++) {
 	/* get all attribute values of the entry;
 	 * specifying 0 for number_names and NULL for attribute_names
 	 * will cause all attribute values to be returned
 	 */ 	
   stat = csa_read_entry_attributes(cal, entries[i], 0, NULL,
 					 &num_attributes, &entry_attrs,
 					 NULL); 	if (stat == CSA_SUCCESS) {
 	    /* use the returned attribute values,
 	     * free the memory when done
 	     */
 	    csa_free(entry_attrs);
 	} else {
 	    /* handle error */
 	}
     }
 } else {
     /* handle error */ 
}   

Example: Change the end time of the returned appointments to be
 	 one hour later. 

CSA_attribute_reference	name = CSA_ENTRY_ATTR_END_DATE; 
char			buffer[80]; 
time_t			endtime; 
CSA_entry_handle	new_entry;  

for (i = 0; i < num_entries; i++) {
     /* get the end time of the appointment */
     stat = csa_read_entry_attributes(cal, entries[i], 0, &name,
 				    &num_attributes, &entry_attrs, NULL);
     if (stat == CSA_SUCCESS) {
 	/* change the end time to be one hour later */
 	from_iso8601_time(entry_attrs[0].value->item.date_time_value, &endtime);
 	endtime += 60*60 /* number of second in an hour */
 	to_iso8601_time(endtime, buffer);
  	attrs[0].name = CSA_ENTRY_ATTR_END_DATE;
   attrs[0].value = &attr_val[i];
 	attrs[0].attribute_extensions = NULL;	
   attr_val[0].type = CSA_VALUE_DATE_TIME;
 	attr_val[0].item.date_time_value = buffer;
  	stat = csa_update_entry_attributes(cal, entries[0], CSA_SCOPE_ALL,
 			      	CSA_FALSE, 1, attrs, &new_entry,
 					   NULL);
 	if (stat == CSA_SUCCESS) {
 	    csa_free(new_entry);
 	} else {
 	    /* handle error */
 	}
  	csa_free(entry_attrs);
      } else {
 	    /* handle error */
     } 
}

To Update a Calendar Entry

Example 10-8 Changing End Time of Returned Appointments: One Hour Later 

CSA_attribute_reference	name = CSA_ENTRY_ATTR_END_DATE; 
char			buffer[80]; 
time_t			endtime; 
CSA_entry_handle	new_entry;  

for (i = 0; i < num_entries; i++) {
     /* get the end time of the appointment */
     stat = csa_read_entry_attributes(cal, entries[i], 0, &name,
 				     &num_attributes, &entry_attrs, NULL);
     if (stat == CSA_SUCCESS) {
 	/* change the end time to be one hour later */
 	from_iso8601_time(entry_attrs[0].value->item.date_time_value, &endtime);
 	endtime += 60*60 /* number of second in an hour */
 	to_iso8601_time(endtime, buffer);

  	attrs[0].name = CSA_ENTRY_ATTR_END_DATE;
 	attrs[0].value = &attr_val[i];
 	attrs[0].attribute_extensions = NULL;
 	attr_val[0].type = CSA_VALUE_DATE_TIME;
 	attr_val[0].item.date_time_value = buffer;
  	stat = csa_update_entry_attributes(cal, entries[0], CSA_SCOPE_ALL,
 					   CSA_FALSE, 1, attrs, &new_entry,
 					   NULL); 	if (stat == CSA_SUCCESS) {
 	    csa_free(new_entry);
 	} else {
 	    /* handle error */
 	}
  	csa_free(entry_attrs);
      } else {
 	    /* handle error */ 
    }
}

To Register Callback and Keep Reminders 

/* The example code shows the usage of csa_register_callback,
  * csa_read_next_reminder, and csa_call_callbacks.
  * The skeleton code registers a callback routine for
  * events CSA_CB_ENTRY_ADDED, CSA_CB_ENTRY_DELETED, and
  * CSA_CB_ENTRY_UPDATED; and another callback routine for the
  * CSA_CB_CALENDAR_ATTRIBUTE_UPDATED event.
  * It also shows how to set up a timer for reminder delivery.
  * Two utilities routines for conversion between time representation
  * in the ISO 8601 format and the tick representing time in seconds
  * since 00:00:00 UTC 1/1/70 are also included.
  */ 

 #include <csa/csa.h> 
#include <time.h> 
#include <unistd.h>  

CSA_session_handle	cal;	 /* a calendar session */ 
time_t			run_time; /* the time the reminders is to be run */ 
CSA_uint32		num_rems; /* number of reminders returned */ 
CSA_reminder_reference	*rems;	  /* an array of reminder information */  

void 
set_up_callback_handler() 
{
 	CSA_return_code		stat;
 	CSA_flags		flags;

  	/* Xt based applications can use the CSA_X_XT_APP_CONTEXT_EXT
 	 * extension to specify the Xt application context so that
 	 * callback routines will be invoked asynchronously
 	 *
 	 *	CSA_extension callback_ext;
 	 *	callback_ext.item_code = CSA_X_XT_APP_CONTEXT_EXT;
 	 * 	callback_ext.item_data = (CSA_uint32)application_context;
 	 *	callback_ext.extension_flags = CSA_EXT_LAST_ELEMENT;
 	 *
 	 * Pass the callback_ext as the last parameter to
 	 * csa_register_callback.
 	 */

  	flags = CSA_CB_ENTRY_ADDED|CSA_CB_ENTRY_DELETED|CSA_CB_ENTRY_UPDATED;
 	stat = csa_register_callback(cal, flags, entry_update_callback,
 		NULL, NULL);

  	if (stat != CSA_SUCCESS) {
 		/* error handling code */
 	}

  	stat = csa_register_callback(cal, CSA_CB_CALENDAR_ATTRIBUTE_UPDATED,
 		calendar_update_callback, NULL, NULL);
  	if (stat != CSA_SUCCESS) {
 		/* error handling code */
 	} 
}  

/*  * This routine polls the library and causes the registered
  * callback to be invoked if the interested event has occurred.
  * If an application does not use the CSA_X_XT_APP_CONTEXT_EXT
  * extension to set up asynchronously callback invocation,
  * it needs to call csa_call_callbacks to force the invocation
  * of callbacks.
  */ 

check_events(CSA_flags event)
{
 	csa_call_callbacks(cal, event, NULL); 
}

  /*
  * This is the callback routine for events CSA_CB_ENTRY_ADDED,
  * CSA_CB_ENTRY_ADDED, and CSA_CB_ENTRY_UPDATED.
  */ 
void 
entry_update_callback(
 	CSA_session_handle	cal,
 	CSA_flags		flags,
 	CSA_buffer		call_data,
 	CSA_buffer		client_data,
 	CSA_extension		*ext) 
{
 	/* An entry is either added, deleted or updated.
 	 * Possible things to do in this callback routine:
	 *
 	 * 1. Update the calendar view, or
 	 * 2. If this is your own calendar, update reminder information.
 	 *
 	 * The sample code in this routine updates reminder information
 	 */ 	reset_reminder();
}

  /*
  * This is the callback routine for the CSA_CB_CALENDAR_ATTRIBUTE_UPDATED
  * event
  */ 
void 
calendar_update_callback(
 	CSA_session_handle	cal,
 	CSA_flags		flags,
 	CSA_buffer		call_data,
 	CSA_buffer		client_data,
 	CSA_extension		*ext) 
{
 	/* update calendar attributes */ 
}

   /*
  * This routine updates reminder information:
  *	- get rid of existing information if any
  *	- call csa_read_next_reminder() to get the next
  *	 reminder to deliver
  *	- check the run time and set timer
  */ 
void 
reset_reminder() {
 	CSA_return_code		stat;
 	time_t			current_time;
 	char			isotime[BUFSIZ];
 	CSA_uint32		number_reminders;
 	CSA_reminder_reference	*reminders;
 
  	current_time = time(NULL);

  	/* get rid of existing information */
 	if (rems) {
 		/* this comparison is to make sure that we don't lose
 		 * any reminders whose run time is between the last
 		 * run time and the current time
 		 */
 		if (current_time > run_time)
 			current_time = run_time;

  		csa_free((CSA_buffer)rems);
 	}

 	to_iso8601_time(current_time, isotime);
 	stat = csa_read_next_reminder(cal, 0, NULL, isotime,
 		&number_reminders, &reminders, NULL);

  	if (stat == CSA_SUCCESS && num_rems > 0) {
 		num_rems = number_reminders;
 		rems = reminders;

  		/* Set timer to deliver the reminder.
 		 * sigset() should be used to set up the signal
 		 * disposition for the SIGALRM signal.
 		 */
 		from_iso8601_time(reminders[0].run_time, &run_time);
 		remain = run_time - time(NULL);
 		alarm((remain > 0) ? remain : 1);

  		/* Xt based application can set the timer using
 		 * XtAppAddTimeOut
 		 */
 	}
}
  
/*
  * This routine converts a time value in the iso8601 format to
  * a tick (representing time in seconds since 00:00:00 UTC, 1/1/70).
  * The tick is adjusted to the local time.
  */ int from_iso8601_time(char *buf, time_t *tick_out) 
{
  	int		year, month, day, hour, min, sec;
 	struct tm	time_str;

  	sscanf(buf, "%4d%2d%2dT%2d%2d%2dZ",
 	    &year, &month, &day, &hour, &min, &sec);

  	time_str.tm_year	= year - 1900;
 	time_str.tm_mon		= month - 1;
 	time_str.tm_mday	= day;
 	time_str.tm_hour	= hour;
 	time_str.tm_min		= min;
 	time_str.tm_sec		= sec;
 	time_str.tm_isdst	= -1;
  	*tick_out = mktime(&time_str);

  	if (*tick_out != (long)-1) {

  		/* adjust for local time zone */
 		if (time_str.tm_isdst == 0)
 			*tick_out -= timezone;
 		else
 			*tick_out -= altzone;
  		return(0);
 	} else
 		return(-1); 
}  

/*
  * This routine converts a tick (representing time in seconds
  * since 00:00:00 UTC, 1/1/70) to the iso8601 format.
  */ 
int 
to_iso8601_time(time_t tick, char *buf_out) 
{
 	struct tm	time_str;
  	if (gmtime_r(&tick, &time_str)) {

  		/* format string forces fixed width (zero-padded) fields */
 		sprintf(buf_out, "%04d%02d%02dT%02d%02d%02dZ",
 			time_str.tm_year + 1900,
 			time_str.tm_mon + 1,
 			time_str.tm_mday,
 			time_str.tm_hour,
 			time_str.tm_min,
 			time_str.tm_sec);
  		return (0);
 	} else {
 		return (-1);
 	} 
}