This section details the nine CSAPI interfaces each of which is an API. The API's are divided between client and server side.
Use the API's shown in the following tables to augment or override Calendar Server’s default behavior:
Table 2–1 Client API's
Augments or overrides the access control mechanism. |
|
Augments or overrides the login authentication mechanism. |
|
Augments or overrides the default calendar lookup mechanism. |
|
Augments or overrides the format translation of incoming and outgoing data. |
|
Provides version control and descriptive information about the module. |
|
Augments or overrides the mechanism for storing and retrieving user attributes. |
|
Retrieves a calendar ID for the specified qualified URL. |
Table 2–2 Server API's
Provides general server information, including version number. |
|
Allows access to server’s memory allocation mechanism. |
Implement the methods in this interface to augment or override the default access control behavior of Calendar Server.
The csIAccessControl interface implements two methods:
Sets access control criteria for users. |
|
Confirms that the interface was found and registered. |
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.
Sets users’ calendar access.
PRUint32 CheckAccess (char* aUser, char* aCalid, PRInt32 *aAccessRequest, PRInt32 *aAccessAllowed, PRInt32 *aReturnCode)=0;
The method has the following five parameters:
aUser |
The authenticated user making the request. For anonymous access, pUserID is “anonymous”. |
aCalid |
calid for the calendar being accessed. |
aAccessRequest |
A set of bit flags representing the requested access type. |
aAccessAllowed |
Output parameter. A set of bit flags representing the allowed accesses. The method checks only the bits specified in aAccessRequest. |
aReturnCode |
On return, contains a constant that determines whether the server should continue with the default authentication procedure. One of the following constants: NS_CONTINUE_DEFAULT_PROCESSING NS_OVERRIDE_DEFAULT_PROCESSING |
NS_OK on success. A non-zero error code on failure.
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:
Access Types |
Bitmaps |
---|---|
ICS_ACCESSTYPE_NONE |
0x00000000 |
ICS_ACCESSTYPE_READCOMPONENT |
0x00000001 |
ICS_ACCESSTYPE_WRITECOMPONENT |
0x00000002 |
ICS_ACCESSTYPE_CREATECOMPONENT |
0x00000008 |
ICS_ACCESSTYPE_DELETECOMPONENT |
0x00000010 |
ICS_ACCESSTYPE_READCALENDAR |
0x00000020 |
ICS_ACCESSTYPE_WRITECALENDAR |
0x00000040 |
ICS_ACCESSTYPE_CREATECALENDAR |
0x00000080 |
ICS_ACCESSTYPE_DELETECALENDAR |
0x00000100 |
ICS_ACCESSTYPE_SCHEDULE |
0x00000200 |
ICS_ACCESSTYPE_FREEBUSY |
0x00000400 |
ICS_ACCESSTYPE_SELF_ADMIN |
0x00000800 |
ICS_ACCESSTYPE_ALL |
0xFFFFFFFF |
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.
Confirms that the interface has been registered, and provides a reference to the server.
PRUint32 Init (nsISupports *a Server)=0;
The method has the following parameter:
aServer |
On return, this location contains a reference to the server with which the module is registered. |
NS_OK on success. A non-zero error code on failure.
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.
All plug-ins wanting to augment or override the default authentication behavior of the calendar server must implement this interface.
The csIAuthentication interface implements five methods:
Change a user’s password. |
|
Confirms that the interface was found and registered. |
|
Logs in a user. |
|
Logs out a user. |
|
Verify a user’s existence. |
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:
NS_CONTINUE_DEFAULT_PROCESSING |
Indicates that the server is to continue default access control processing. |
NS_OVERRIDE_DEFAULT_PROCESSING |
Indicates that this method overrides the server's native access control mechanism. |
Changes the password for the specified user.
PRUint32 Init (char* aUser, char* aOldPassword, char* aNewPassword, PRInt32 *aReturnCode)=0;
The method has the following four parameters:
On success, NS_AUTHENTICATION_CHANGEPASSWORD_SUCCESS.
On failure, NS_AUTHENTICATION_CHANGEPASSWORD_FAILURE.
Changes the password of the specified user.
Confirms that the interface has been registered, and provides a reference to the server.
PRUint32 Init (nsISupports *aServer)=0;
The method has the following parameter:
aServer |
On return, this location contains a reference to the server with which the module is registered. |
NS_OK on success. A non-zero code on failure.
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.
Augment or override the authentication procedure for plain text login.
PRUint32 Login (char* aUser, char* aPassword, PRInt32 *aReturnCode)=0;
The method has the following three parameters:
On success, NS_AUTHENTICATION_LOGON_SUCCESS.
On failure, NS_AUTHENTICATION_LOGON_FAILURE.
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
Logout a user.
PRUint32 Init (char* aUser,PRInt32 *aReturnCode)=0;
The method has the following two parameters:
NS_OK on success. A non-zero error code on failure.
None.
Verify that the user ID is in the LDAP directory.
PRUint32 Init (char* aUser,PRInt32 *aReturnCode)=0;
The method has the following two parameters:
NS_OK on success. A non-zero error code on failure.
None.
Implement the methods in this interface to augment or override the default calendar lookup (LDAP).
The csICalendarLookup implements the following methods:
Method |
Description |
---|---|
Removes the host name entry from the calendar lookup database for a specific calendar. |
|
Frees a previously allocated, fully qualified calid. |
|
Frees a previously allocated type. |
|
Gets the hostname from the calendar lookup database associated with the calendar specified by the calid |
|
Confirms that the interface was found and registered. |
|
Returns the name of the qualified calid. |
|
Queries the type of plug-in. |
|
Sets the host name for a calendar user associated with a calid being created. |
Allows you to control calendar lookup by implementing one or more of the methods.
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
Removes the hostname in LDAP associated with the specified calid.
PRInt32 GetHostnameForCalid(char* psCalid, PRInt32 *piReturnCode)=0;
The following are the parameters and definitions for this method:
psCalid |
calid for which the hostname is requested. |
piReturnCode |
0= successful, non-zero indicates failure. |
Returns zero for success. Returns a non-zero code for failure. See API: csICalendarLookup.
Removes the hostname associated with the specified calendar in the calendar lookup database.
Frees a previously allocated, fully qualified calendar ID (calid).
PRUint32 FreeCalid(char** aQualifiedCalid,PRInt32 *aReturnCode)=0;
The method has the following parameters:
aQualifiedCalid |
calid to free. |
aReturnCode |
NS_OK if successful. Normal processing does not continue if unsuccessful. |
NS_OK on success, non-zero error code on failure.
Used by both implementations of lookup.
Frees a previously allocated database plug-in type.
PRUint32 FreeType(char* aType,PRInt32 *aReturnCode)=0;
The method has the following parameters:
aType |
The database plug-in type to free |
aReturnCode |
NS_OK if successful. Normal processing does not continue if unsuccessful. |
NS_OK on success, non-zero error code on failure.
Frees the string allocated in QueryType method. Used by both implementations.
Retrieves the hostname associated with the specified calid.
PRInt32 GetHostnameForCalid(char* psCalid, char** ppsHost, PRInt32 *piReturnCode)=0;
The following are the parameters and definitions for this method:
psCalid |
calid for which the hostname is requested. |
ppsHost |
The hostname to be returned. |
piReturnCode |
0= successful, non-zero indicates failure. |
Returns zero for success. Returns a non-zero code for failure. See API: csICalendarLookup.
Gets the hostname associated with a calendar in the calendar lookup database.
Confirms that the interface has been registered, and provides a reference to the server.
PRUint32 Init(nsISupports *aServer)=0;
The method has the following parameter:
aServer |
On return, contains a reference to the server with which the module is registered. |
NS_OK on success, non-zero error code on failure.
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.
Qualifies the relative calid.
PRUint32 QualifyCalid(char* psCalid, char** ppsQualifiedCalid, PRInt32 *piReturnCode)=0;
The method has the following parameters:
psCalid |
The calid to be qualified. |
ppsQualifiedCalid |
On return, contains the URL of the qualified calid. |
piReturnCode |
0= successful, non-zero indicates failure. |
Zero on success, non-zero error code on failure.
Returns the name of the qualified calid. The qualified calid format is:
dwp://back-end host[:port]/psCalid |
Query type of database plug-in.
PRUint32 QueryType(char* aType,PRInt32 *aReturnCode)=0;
The method has the following parameters:
aType |
The type of CLD (Calendar Lookup Database). |
aReturnCode |
NS_OK if successful. Normal processing does not continue if unsuccessful. |
NS_OK on success, non-zero error code on failure.
This function retrieves a string representing the type of CLD the plug-in implements.
Not currently used. Sets the host name for a calendar user.
PRInt32 SetHostnameForCalid(char* psCalid, char* ppsHost, PRInt32 *piReturnCode)=0; |
This method uses the following parameters:
psCalid |
calid for which the hostname is to be set. |
ppsHost |
The hostname to be set. |
piReturnCode |
0= successful, non-zero indicates failure. |
Returns zero for success. Returns any non-zero for failure.
Sets the hostname for a calid that is about to be created.
This is the interface for data translator plug-ins. All parameters should be allocated by the plug-in.
The csIDataTranslator interface implements three methods:
Informs the server about the content types that this database translator supports. |
|
Confirms that the interface was found and registered. |
|
Translates calendar data to the specified MIME format. |
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:
MIME Type |
Description |
---|---|
text/calendar |
iCalendar |
text/xml |
iCalendar in XML |
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.
Gets the content type this database translator supports.
PRUint32 GetSupportedContentTypes (char** aSupportedInContentTypes, char** aSupportedOutContentType, char** aPreferredInContentType, PRInt32 *aReturnCode)=0;
The method has the following parameters:
aSupportedInContentTypes |
A list of content-types that the server can send as input to translator. An array of null-terminated strings. |
aSupportedOutContentType |
The content type the plug-in converts data to. |
aPreferredInContentType |
The content type the plug-in would prefer to receive. It must be one of the supported content types passed in the first parameter. |
aReturnCode |
On return, contains a constant that determines whether the server should continue with the default authentication procedure. One of the following constants: NS_CONTINUE_DEFAULT_PROCESSING NS_OVERRIDE_DEFAULT_PROCESSING |
NS_OK on success. A non-zero on failure.
Get the content type this database translator supports.
Confirm that the interface has been registered and obtain a reference to the server.
PRUint32 Init (nsISupports *aServer)=0;
The method has the following parameter:
aServer |
On return, this location contains a reference to the server with which the module is registered. |
NS_OK on success, non-zero error code on failure.
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.
Implement the translation from one content type to another.
PRUint32 Translate (char* aInContentType, char* aOutContentType, char** aInBuffer, char** aOutBuffer, PRInt32 *aInSize, PRInt32 *aOutsize, PRInt32 *aReturncode)=0;
The method has the following parameters:
aInContentType |
The incoming content type. |
aOutContentType |
The outgoing content type. |
aInBuffer |
The input data buffer. |
aOutBuffer |
The output data buffer. |
aInSize |
The input buffer size. |
aOutSize |
The output buffer size. |
aReturnCode |
On return, contains a constant that determines whether the server should continue with the default authentication procedure. One of the following constants: NS_CONTINUE_DEFAULT_PROCESSING NS_OVERRIDE_DEFAULT_PROCESSING |
NS_OK on success, non-zero on failure.
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.
You should implement the methods in this interface in order to provide the server with information about your plug-in module on startup.
The csIPlugin interface implements four methods:
Gets a textual description of what the plug-in does. |
|
Gets a textual description of the vendor supplying this plug-in. |
|
Gets the major and minor version of the plug-in. This value must be greater than or equal to 1.0. For a list of the current version numbers for each plug-in API, seePlug-in Version Numbers. |
|
Confirms that the interface was found and registered. |
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.
Retrieve a text description of the module.
PRUint32 GetDescription (nsString& aDescription)=0;
The method has the following parameter:
aDescription |
On return, contains the text description of the module. |
NS_OK on success, non-zero error code on failure.
Use this method to provide a text description of the module.
Retrieve a text description of the vendor supplying the module.
PRInt32 GetVendorName (nsString& aVendorName)=0;
The method has the following parameter:
aVendorName |
On return, contains the text description of the vendor. |
NS_OK on success, non-zero error code on failure.
Use this method to identify the module’s supplier.
Provide server with version information on startup.
PRUint32 GetVersion (PRUint32& aMajorValue,PRUint32& aMinorValue)=0;
The method has the following two parameters:
aMajorValue |
On return, contains the major version number. |
aMinorValue |
On return, contains the minor version number. |
NS_OK on success, non-zero error code on failure.
Use this method to identify the module’s major and minor version number. The number must be greater than or equal to 1.0.
Confirm that the interface has been registered and obtains a reference to the server.
PRUint32 Init (nsISupports *aServer)=0;
The method has the following parameter:
aServer |
On return, this location contains a reference to the server with which the module is registered. |
NS_OK on success, non-zero error code on failure.
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.
Implement the methods in this interface to augment or override the default method of retrieving the calendar ID of the qualified URL passed in.
The csICalendarLookup implements two methods:
Returns a calendar ID for the qualified URL. |
|
Confirms that the interface was found and registered. |
Retrieves the calendar ID of the qualified URL passed in to it. If the calid is not found, the command returns an error.
Finds the calendar ID for the URL specified.
PRUint32 FindCalid (char* pQualifiedURL, char** ppCalidOut, PRInt32 *piCalidSize, PRInt32 *aReturnCode)=0;
The method has the following parameters:
pQualifiedURL |
The URL to search on. |
ppCalidOut |
A pointer to the address of the calid found. |
piCalidSize |
Size of the calid returned. |
aReturnCode |
On return, contains a constant that determines whether the server should continue with the default, or with the override processing. One of the following constants: NS_CONTINUE_DEFAULT_PROCESSING NS_OVERRIDE_DEFAULT_PROCESSING |
The calid for the qualified URL passed in.
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
Confirms that the interface has been registered, and provides a reference to the server.
PRUint32 Init (nsISupports *aServer)=0;
The method has the following parameter:
aServer |
On return, contains a reference to the server with which the module is registered. |
NS_OK on success, non-zero error code on failure.
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.
Implement the methods in this interface to override the procedure for setting or retrieving user attributes.
The csIUserAttributes interface implements four methods:
Free the memory used to store a retrieved attribute. |
|
Retrieve an attribute value for a user. |
|
Confirm that the interface was found and registered. |
|
Set an attribute value for a user. |
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.
Free the memory associated with your local attribute storage.
PRint32 FreeAttribute (char* aValue, PRInt32 *aReturnCode)=0;
The method has the following two parameters:
NS_OK on success, non-zero error code on failure.
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.)
Retrieve an attribute value for a user.
PRUint32 GetAttribute (char* aUser, char* aKey, char** aValue, PRInt32 *aReturnCode)=0;
The method has the following four parameters:
NS_OK on success, non-zero error code on failure.
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.
Confirm that the interface has been registered and obtain a reference to the server.
PRUint32 Init (nsISupports *aServer)=0;
The method has the following parameter:
aServer |
On return, this location contains a reference to the server with which the module is registered. |
NS_OK on success, non-zero error code on failure.
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.
Set an attribute value for a user.
PRUint32 SetAttribute (char* aUser, char* aKey, char* aValue, PRInt32 *aReturnCode)=0;
The method has the following parameters:
NS_OK on success, non-zero error code on failure.
Sets the specified attribute for the specified user to the specified value.
Provides server version information to a plug-in module.
The csICalendarServer interface implements two methods:
Get the calendar server version. |
|
Confirms that the interface was found and registered. |
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.
Provide plug-in module with server version information.
PRUint32 GetVersion (PRUint32& aMajorValue, PRUint32& aMinorValue)=0;
The method has the following two parameters:
aMajorValue |
On return, contains the major version number. |
aMinorValue |
On return, contains the minor version number. |
NS_OK on success, non-zero error code on failure.
Use this method to identify the server’s major and minor version number. The number is always greater than or equal to 1.0.
Confirm that the interface has been registered.
PRUint32 Init()=0;
The method has no parameters.
NS_OK on success, non-zero error code on failure.
The server calls this method to confirm that the interface was found and registered successfully.
Allocates and frees memory.
The csIMalloc interface implements six methods:
Allocates and initializes memory for a number of objects. |
|
Frees memory that is no longer in use. |
|
Frees memory, allowing a NULL pointer. |
|
Confirms that the interface was found and registered. |
|
Allocates an amount of memory. |
|
Reallocates previously allocated memory. |
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.
Allocates, and initializes to zero, memory for a number of objects.
void* Calloc (PRUint32 aSize, PPRUint32 aNum)=0;
The method has the following two parameters:
aSize |
The size in bytes of each object. |
nNum |
The number of objects. |
A pointer to the allocated memory on success, or NULL on failure.
This method allocates enough memory for the specified number of objects of the specified size, and initializes the memory to zero.
Free memory previously allocated by the Malloc method.
PRUint32 Free (void * aPtr)=0;
The method has the following parameter:
aPtr |
A pointer to the memory to be freed. |
NS_OK on success, non-zero error code on failure.
Use this method in the same way as its C or C++ counterpart to free previously allocated memory.
Free memory previously allocated by the Malloc method, allowing a NULL pointer.
PRUint32 FreeIf (void * aPtr)=0;
The method has the following parameter:
aPtr |
A pointer to the memory to be freed or NULL. |
NS_OK on success, non-zero error code on failure.
Frees the memory at the specified location, if aPtr is not NULL.
Confirm that the interface has been registered.
PRUint32 Init() = 0;
The method has no parameters.
NS_OK on success, non-zero error code on failure.
The server calls this method to confirm that the interface was found and registered successfully.
Allocate a specified amount of memory.
void* Malloc (PRUint32 nBytes)=0;
The method has the following parameter:
nBytes |
The size in bytes of the memory to be allocated. |
A pointer to the allocated memory on success, or NULL on failure.
Use this method in the same way as its C or C++ counterpart.
Reallocates memory that was previously allocated.
void* Realloc (void* aPtr,PRUint32 nBytes)=0;
The method has the following parameter:
aPtr |
A pointer to previously allocated memory. |
nBytes |
The size in bytes of the memory to be allocated. |
A pointer to the allocated memory on success, or NULL on failure.
Use this method in the same way as its C or C++ counterpart to reallocate memory that was previously allocated.