Solaris Common Desktop Environment: Programmer's Guide

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.

Add Entry: adds an entry to the specified calendar.

Prototype:

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)

Delete Entry: deletes an entry from the specified calendar.

Prototype:

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

List Entries: lists the calendar entries that match all the attribute search criteria.

Prototype:

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

List Entry Attributes: lists the names of the entry attributes associated with the specified entry.

Prototype:

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

List Entry Sequence: lists the recurring calendar entries that are associated with a calendar entry.

Prototype:

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

Read Entry Attributes: reads and returns the calendar entry attribute values for a specified entry.

Prototype:

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

Read Next Reminder: reads the next reminder of the given type in the specified calendar relative to a given time.

Prototype:

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

Update Entry Attribute: updates the calendar entry attributes.

Prototype:

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

Unsupported Functions

The following functions are not supported in CDE and will return CSA_E_NOT_SUPPORTED only:

csa_add_event 
csa_add_memo  
csa_add_todo  
csa_free_time_search  
csa_look_up  
csa_restore 
csa_save