Chapter 2 CSAPI Reference

This section details the nine CSAPI interfaces each of which is an API. The API's are divided between client and server side.

Client and Server API's

Use the API's shown in the following tables to augment or override Calendar Server’s default behavior:

API: csIAccessControl

Implement the methods in this interface to augment or override the default access control behavior of Calendar Server.

Methods

The csIAccessControl interface implements two methods:

Description

Defines the types of access allowed. You must set the return code to specify whether you are using the default access control or overriding the default.

Method: CheckAccess

Purpose

Sets users’ calendar access.

Syntax

PRUint32 CheckAccess (char* aUser, 
                      char* aCalid, 
                      PRInt32 *aAccessRequest, 
                      PRInt32 *aAccessAllowed, 
                      PRInt32 *aReturnCode)=0;

Parameters

The method has the following five parameters:

Returns

NS_OK on success. A non-zero error code on failure.

Description

Use this method to request access types for this user. You send in the name of the user in the aUser parameter, and the access types requested in the aAccessRequest parameter (bitmask). The system checks for only those access types specified in the aAccessRequest bitmask. The returned bitmask, aAccessAllowed, represents the user’s allowed access for the types you requested.

For anonymous access, the user ID is “anonymous”.

ICS_ACCESSTYPE constants (bitmaps) that define available access types are as follows:

Use this method to specify your own access control procedure. You can augment the native access control mechanism, performing your own processing first, then continuing with the default process, or you can completely replace the native access control mechanism.

Method: Init

Purpose

Confirms that the interface has been registered, and provides a reference to the server.

Syntax

PRUint32 Init (nsISupports *a Server)=0;

Parameters

The method has the following parameter:

Returns

NS_OK on success. A non-zero error code on failure.

Description

The server calls this method, after finding and registering the interface on module load, to confirm that the operation was successful. You can use the pointer returned in aServer to make calls out to the server.

API: csIAuthentication

All plug-ins wanting to augment or override the default authentication behavior of the calendar server must implement this interface.

Methods

The csIAuthentication interface implements five methods:

Description

Allows you to define logon, logoff, verification, and password methods that implement the authentication technique of your choice. You can replace a method and still continue to use the default for the others. Each method uses the return code parameter (aReturnCode) to tell the server whether to continue with the default access control process after executing the method. The return code value must be one of the following constants:

Method: ChangePassword

Purpose

Changes the password for the specified user.

Syntax

PRUint32 Init (char* aUser, 
               char* aOldPassword, 
               char* aNewPassword, 
               PRInt32 *aReturnCode)=0;

Parameters

The method has the following four parameters:

Returns

On success, NS_AUTHENTICATION_CHANGEPASSWORD_SUCCESS.

On failure, NS_AUTHENTICATION_CHANGEPASSWORD_FAILURE.

Description

Changes the password of the specified user.

Method: Init

Purpose

Confirms that the interface has been registered, and provides a reference to the server.

Syntax

PRUint32 Init (nsISupports *aServer)=0;

Parameters

The method has the following parameter:

Returns

NS_OK on success. A non-zero code on failure.

Description

The server calls this method after finding and registering the interface on module load, to confirm that the operation was successful. You can use the pointer returned in aServer to make calls out to the server.

Method: Logon

Purpose

Augment or override the authentication procedure for plain text login.

Syntax

PRUint32 Login (char* aUser, char* aPassword, PRInt32 *aReturnCode)=0;

Parameters

The method has the following three parameters:

Returns

On success, NS_AUTHENTICATION_LOGON_SUCCESS.

On failure, NS_AUTHENTICATION_LOGON_FAILURE.

Description

Use this method to specify your own authentication procedure on login to Calendar Server. You can augment the native authentication mechanism, performing your own processing first, then continuing with the default process, or you can completely replace the native authentication mechanism

Method: Logout

Purpose

Logout a user.

Syntax

PRUint32 Init (char* aUser,PRInt32 *aReturnCode)=0;

Parameters

The method has the following two parameters:

Returns

NS_OK on success. A non-zero error code on failure.

Description

None.

Method: VerifyUserExists

Purpose

Verify that the user ID is in the LDAP directory.

Syntax

PRUint32 Init (char* aUser,PRInt32 *aReturnCode)=0;

Parameters

The method has the following two parameters:

Returns

NS_OK on success. A non-zero error code on failure.

Description

None.

API: csICalendarLookup

Implement the methods in this interface to augment or override the default calendar lookup (LDAP).

Methods

The csICalendarLookup implements the following methods:

Description

Allows you to control calendar lookup by implementing one or more of the methods.

piReturnCode Values

The four possible return codes for the piReturnCode parameter are as follows:

• Cannot connect to LDAP server

• Insufficient privileges to modify LDAP entry

• Invalid credentials to connect to LDAP

• No value for back end host

Method: DeleteHostnameForCalid

Purpose

Removes the hostname in LDAP associated with the specified calid.

Syntax

PRInt32 GetHostnameForCalid(char* psCalid, PRInt32 *piReturnCode)=0;

Parameters

The following are the parameters and definitions for this method:

Returns

Returns zero for success. Returns a non-zero code for failure. See API: csICalendarLookup.

Description

Removes the hostname associated with the specified calendar in the calendar lookup database.

Method: FreeCalid

Purpose

Frees a previously allocated, fully qualified calendar ID (calid).

Syntax

PRUint32 FreeCalid(char** aQualifiedCalid,PRInt32 *aReturnCode)=0;

Parameters

The method has the following parameters:

Returns

NS_OK on success, non-zero error code on failure.

Description

Used by both implementations of lookup.

Method: FreeType

Purpose

Frees a previously allocated database plug-in type.

Syntax

PRUint32 FreeType(char* aType,PRInt32 *aReturnCode)=0;

Parameters

The method has the following parameters:

Returns

NS_OK on success, non-zero error code on failure.

Description

Frees the string allocated in QueryType method. Used by both implementations.

Method: GetHostnameForCalid

Purpose

Retrieves the hostname associated with the specified calid.

Syntax

PRInt32 GetHostnameForCalid(char* psCalid,
                            char** ppsHost,
                            PRInt32 *piReturnCode)=0;

Parameters

The following are the parameters and definitions for this method:

Returns

Returns zero for success. Returns a non-zero code for failure. See API: csICalendarLookup.

Description

Gets the hostname associated with a calendar in the calendar lookup database.

Method: Init

Purpose

Confirms that the interface has been registered, and provides a reference to the server.

Syntax

PRUint32 Init(nsISupports *aServer)=0;

Parameters

The method has the following parameter:

Returns

NS_OK on success, non-zero error code on failure.

Description

The server calls this method after finding and registering the interface on module load, to confirm that the operation was successful. You can use the pointer returned in aServer to make calls out to the server.

Method: QualifyCalid

Purpose

Qualifies the relative calid.

Syntax

PRUint32 QualifyCalid(char* psCalid,
                      char** ppsQualifiedCalid,
                      PRInt32 *piReturnCode)=0;

Parameters

The method has the following parameters:

Returns

Zero on success, non-zero error code on failure.

Description

Returns the name of the qualified calid. The qualified calid format is:

dwp://back-end host[:port]/psCalid

Method: QueryType

Purpose

Query type of database plug-in.

Syntax

PRUint32 QueryType(char* aType,PRInt32 *aReturnCode)=0;

Parameters

The method has the following parameters:

Returns

NS_OK on success, non-zero error code on failure.

Description

This function retrieves a string representing the type of CLD the plug-in implements.

Method: SetHostnameForCalid

Purpose

Not currently used. Sets the host name for a calendar user.

Syntax

PRInt32 SetHostnameForCalid(char* psCalid, 
                            char* ppsHost, 
                            PRInt32 *piReturnCode)=0;

Parameters

This method uses the following parameters:

Returns

Returns zero for success. Returns any non-zero for failure.

Description

Sets the hostname for a calid that is about to be created.

API: csIDataTranslator

This is the interface for data translator plug-ins. All parameters should be allocated by the plug-in.

Methods

The csIDataTranslator interface implements three methods:

Description

This interface allows you to manipulate or change the HTML Body content of calendar data flowing to, or from, the database, or between various data translators. The data translator manipulates the output format (fmt-out) component of a WCAP response.

Calendar Server supports the following MIME-types for translating calendar data:

A CSAPI Data Translation module registers with the server for a specific MIME-type using the GetSupportedContentType method. The translator can request that the incoming data be provided in any of the supported MIME-types.

When incoming data is in the MIME-type that the module takes as input, the server passes the data to the module’s Translate method. The translator converts the data to its supported MIME-type and passes it back to the server, which proceeds to update the database.

Method: GetSupportedContentTypes

Purpose

Gets the content type this database translator supports.

Syntax

PRUint32 GetSupportedContentTypes 
                    (char** aSupportedInContentTypes,
                     char** aSupportedOutContentType,
                     char** aPreferredInContentType,
                     PRInt32 *aReturnCode)=0;

Parameters

The method has the following parameters:

Returns

NS_OK on success. A non-zero on failure.

Description

Get the content type this database translator supports.

Method: Init

Purpose

Confirm that the interface has been registered and obtain a reference to the server.

Syntax

PRUint32 Init (nsISupports *aServer)=0;

Parameters

The method has the following parameter:

Returns

NS_OK on success, non-zero error code on failure.

Description

The server calls this method after finding and registering the interface on module load, to confirm that the operation was successful. You can use the pointer returned in aServer to make calls out to the server.

Method: Translate

Purpose

Implement the translation from one content type to another.

Syntax

PRUint32 Translate (char* aInContentType,
                    char* aOutContentType,
                    char** aInBuffer,
                    char** aOutBuffer,
                    PRInt32 *aInSize,
                    PRInt32 *aOutsize,
                    PRInt32 *aReturncode)=0;

Parameters

The method has the following parameters:

Returns

NS_OK on success, non-zero on failure.

Description

This method retrieves content of the specified input type from the specified buffer, translates the content from its original format to the output format, stores the translated content in the specified output buffer, and stores the size of the output buffer at the specified location.

API: csIPlugin

You should implement the methods in this interface in order to provide the server with information about your plug-in module on startup.

Methods

The csIPlugin interface implements four methods:

Description

This interface is not required, but it is highly recommended that you implement it in each module to provide version information to the server when it loads that module. The methods return descriptive information to the server.

Method: GetDescription

Purpose

Retrieve a text description of the module.

Syntax

PRUint32 GetDescription (nsString& aDescription)=0;

Parameters

The method has the following parameter:

Returns

NS_OK on success, non-zero error code on failure.

Description

Use this method to provide a text description of the module.

Method: GetVendorName

Purpose

Retrieve a text description of the vendor supplying the module.

Syntax

PRInt32 GetVendorName (nsString& aVendorName)=0;

Parameters

The method has the following parameter:

Returns

NS_OK on success, non-zero error code on failure.

Description

Use this method to identify the module’s supplier.

Method: GetVersion

Purpose

Provide server with version information on startup.

Syntax

PRUint32 GetVersion (PRUint32& aMajorValue,PRUint32& aMinorValue)=0;

Parameters

The method has the following two parameters:

Returns

NS_OK on success, non-zero error code on failure.

Description

Use this method to identify the module’s major and minor version number. The number must be greater than or equal to 1.0.

Method: Init

Purpose

Confirm that the interface has been registered and obtains a reference to the server.

Syntax

PRUint32 Init (nsISupports *aServer)=0;

Parameters

The method has the following parameter:

Returns

NS_OK on success, non-zero error code on failure.

Description

The server calls this method, after finding and registering the interface on module load, to confirm that the operation was successful. You can use the pointer returned in aServer to make calls out to the server.

API: csIQualifiedCalidLookup

Implement the methods in this interface to augment or override the default method of retrieving the calendar ID of the qualified URL passed in.

Methods

The csICalendarLookup implements two methods:

Description

Retrieves the calendar ID of the qualified URL passed in to it. If the calid is not found, the command returns an error.

Method: FindCalid

Purpose

Finds the calendar ID for the URL specified.

Syntax

PRUint32 FindCalid (char* pQualifiedURL,
                    char** ppCalidOut,
                    PRInt32 *piCalidSize,
                    PRInt32 *aReturnCode)=0;

Parameters

The method has the following parameters:

Returns

The calid for the qualified URL passed in.

Description

Uses the qualified URL pointer passed to it to perform a search of the calendar ID database. If it finds a match, it returns a pointer to the address of the calid and an integer with the size of the calid

Method: Init

Purpose

Confirms that the interface has been registered, and provides a reference to the server.

Syntax

PRUint32 Init (nsISupports *aServer)=0;

Parameters

The method has the following parameter:

Returns

NS_OK on success, non-zero error code on failure.

Description

The server calls this method after finding and registering the interface on module load, to confirm that the operation was successful. You can use the pointer returned in aServer to make calls out to the server.

API: csIUserAttributes

Implement the methods in this interface to override the procedure for setting or retrieving user attributes.

Methods

The csIUserAttributes interface implements four methods:

Description

The User Attributes interface allows a CSAPI module to maintain or manipulate all requests coming in for setting and retrieving user attribute values. You provide methods that retrieve and set attributes using the technique of your choice.

Method: FreeAttribute

Purpose

Free the memory associated with your local attribute storage.

Syntax

PRint32 FreeAttribute (char* aValue, PRInt32 *aReturnCode)=0;

Parameters

The method has the following two parameters:

Returns

NS_OK on success, non-zero error code on failure.

Description

When you retrieve the value of an attribute using the GetAttribute method, the value is stored at a location that you have allocated, using the memory management technique of your choice. Use the Method: FreeAttribute method to free that memory when it is no longer needed, using the same memory management technique. (See API: csIMalloc.)

Method: GetAttribute

Purpose

Retrieve an attribute value for a user.

Syntax

PRUint32 GetAttribute (char* aUser,
                       char* aKey,
                       char** aValue,
                       PRInt32 *aReturnCode)=0;

Parameters

The method has the following four parameters:

Returns

NS_OK on success, non-zero error code on failure.

Description

Retrieves the value of the specified attribute for the specified user, and stores it at the location pointed to by aValue. You are responsible for allocating storage space for the returned attribute, and for freeing it (using the FreeAttribute method) when it is no longer needed.

Method: Init

Purpose

Confirm that the interface has been registered and obtain a reference to the server.

Syntax

PRUint32 Init (nsISupports *aServer)=0;

Parameters

The method has the following parameter:

Returns

NS_OK on success, non-zero error code on failure.

Description

The server calls this method, after finding and registering the interface on module load, to confirm that the operation was successful. You can use the pointer returned in aServer to make calls out to the server.

Method: SetAttribute

Purpose

Set an attribute value for a user.

Syntax

PRUint32 SetAttribute (char* aUser,
                       char* aKey,
                       char* aValue,
                       PRInt32 *aReturnCode)=0;

Parameters

The method has the following parameters:

Returns

NS_OK on success, non-zero error code on failure.

Description

Sets the specified attribute for the specified user to the specified value.

API: csICalendarServer

Provides server version information to a plug-in module.

Methods

The csICalendarServer interface implements two methods:

Description

Plug-in modules can query the csICalendarServer interface to get version information about the running instance of Calendar Server. The object is valid for the full lifetime of the client, so Init does not return a reference.

Method: GetVersion

Purpose

Provide plug-in module with server version information.

Syntax

PRUint32 GetVersion (PRUint32& aMajorValue, PRUint32& aMinorValue)=0;

Parameters

The method has the following two parameters:

Returns

NS_OK on success, non-zero error code on failure.

Description

Use this method to identify the server’s major and minor version number. The number is always greater than or equal to 1.0.

Method: Init

Purpose

Confirm that the interface has been registered.

Syntax

PRUint32 Init()=0;

Parameters

The method has no parameters.

Returns

NS_OK on success, non-zero error code on failure.

Description

The server calls this method to confirm that the interface was found and registered successfully.

API: csIMalloc

Allocates and frees memory.

Methods

The csIMalloc interface implements six methods:

Description

Plug-in modules can use this object to take advantage of the server’s efficient memory allocation technique. The object is valid for the full lifetime of the client, so Init does not return a reference.

Method: Calloc

Purpose

Allocates, and initializes to zero, memory for a number of objects.

Syntax

void* Calloc (PRUint32 aSize, PPRUint32 aNum)=0;

Parameters

The method has the following two parameters:

Returns

A pointer to the allocated memory on success, or NULL on failure.

Description

This method allocates enough memory for the specified number of objects of the specified size, and initializes the memory to zero.

Method: Free

Purpose

Free memory previously allocated by the Malloc method.

Syntax

PRUint32 Free (void * aPtr)=0;

Parameters

The method has the following parameter:

Returns

NS_OK on success, non-zero error code on failure.

Description

Use this method in the same way as its C or C++ counterpart to free previously allocated memory.

Method: FreeIf

Purpose

Free memory previously allocated by the Malloc method, allowing a NULL pointer.

Syntax

PRUint32 FreeIf (void * aPtr)=0;

Parameters

The method has the following parameter:

Returns

NS_OK on success, non-zero error code on failure.

Description

Frees the memory at the specified location, if aPtr is not NULL.

Init

Purpose

Confirm that the interface has been registered.

Syntax

PRUint32 Init() = 0;

Parameters

The method has no parameters.

Returns

NS_OK on success, non-zero error code on failure.

Description

The server calls this method to confirm that the interface was found and registered successfully.

Method: Malloc

Purpose

Allocate a specified amount of memory.

Syntax

void* Malloc (PRUint32 nBytes)=0;

Parameters

The method has the following parameter:

Returns

A pointer to the allocated memory on success, or NULL on failure.

Description

Use this method in the same way as its C or C++ counterpart.

Method: Realloc

Purpose

Reallocates memory that was previously allocated.

Syntax

void* Realloc (void* aPtr,PRUint32 nBytes)=0;

Parameters

The method has the following parameter:

Returns

A pointer to the allocated memory on success, or NULL on failure.

Description

Use this method in the same way as its C or C++ counterpart to reallocate memory that was previously allocated.