"iPlanet Calendar Server: Programmer's Reference": Calendar Server API (CSAPI)

Complete Contents
Preface
Chapter 1 Overview of Architecture
Chapter 2 Web Calendar Access Protocol (WCAP)
Chapter 3 Calendar Server API (CSAPI)
Index

iPlanet Calendar Server: Programmer's Reference: Calendar Server API (CSAPI)

Contents

Index

Chapter 3 Calendar Server API (CSAPI)

This chapter describes Calendar Server API (CSAPI), a high performance programmatic interface that enables you to modify or enhance the feature set of iPlanet Calendar Server. CSAPI allows you to create very fast runtime shared objects that outperform both system executables and scripts in any language, with respect to speed, memory footprint, and load. All of these factors contribute to scalability issues in high-end systems.

This chapter has the following sections:

CSAPI Architecture

API Reference

CSAPI Architecture

The CSAPI is a shared-object runtime interface to Calendar Server functions. You can use plug-in CSAPI modules to manipulate server data as requests come in and as responses are made. This architecture allows the server to act as a simple gateway to data it knows nothing about. It also allows for dynamic logging and statistics tracking, external authentication schemes, user attribute manipulation, and a variety of other functions.

Figure 3.1 shows the architecture of CSAPI modules within Calendar Server. Depending on which functional group or groups an CSAPI module supports, it can interact with one or more areas of Calendar Server functionality.

Figure 3.1 CSAPI architecture

A module is a shared object (.so file) on Unix, or dynamic linked library (.dll file) on Windows NT. Each module that you provide implements one or more of the CSAPI interfaces (or pure virtual base classes) defined in this document. Each interface addresses a functional area of Calendar Server. The implementation contained in a module can either augment or override the native Calendar Server functionality in its area.

CSAPI is a C and C++ interface for Unix and Windows NT systems. It uses Netscape Portable Runtime (NSPR), a part of the mozilla.org source code that is a platform independent API to operating system services, and XPCOM for Interface Dispatch.

For documentation on NSPR see the mozilla technical documentation site:

http://www.mozilla.org/docs/refList/refNSPR

For documentation on XPCOM, see:

http://www.mozilla.org/docs/tplist/catFlow/modunote.htm

You must use NSPR for platform-independent C data types and runtime functions in implementations that need to run on different platforms. Calendar Server uses the XPCOM C++ API (QueryInterface) to discover the exact interfaces a specific module implements.

A set of server-side APIs allows CSAPI modules to register for specific events, get the server's version information, and use the server's fast memory allocation mechanism.

CSAPI module plug-ins must be multithread safe, as many thousands of threads can access a module at any time. For those plug-ins that cannot be thread-aware, use simple monitors at the function-call level in the plug-in itself. For more information on NSPR threads, refer to the NSPR reference manual.

Installed Files
The installation contains plug-in shells that you can use as templates for each of the CSAPI interfaces along with all supporting libraries, headers, and build tools for compiling on all systems supported by Calendar Server. It also contains C code sample implementations of CSAPI modules.

Figure 3.2 shows the CSAPI directory structure under the Calendar Server installation directory.

Figure 3.2 CSAPI directory structure

Loading CSAPI Modules
Calendar Server loads CSAPI modules from the server_root/plug-ins directory at startup and unloads them at server shutdown. All plug-in modules must reside in this directory and have filenames that are prefaced with cs_.

The server checks the file config/server.conf for the list of modules to be dynamically loaded at server startup. If the value in this file is an asterisk (*), the server loads all shared objects in the server_root/plug-ins directory whose names begin with the prefix cs_.

Calendar Server uses the NSPR function PR_LoadLibrary() to load the shared object at startup, the function PR_UnloadLibrary() to unload the shared image at shutdown. Once a shared object is loaded into memory, Calendar Server uses the function PR_FindSymbol() to find entry points to known API implementations.

CSAPI Module Structure
All CSAPI shared objects support one and only one exported symbol, NSGetFactory, as required by the XPCOM specification. From this entry point, Calendar Server calls the XPCOM method QueryInterface to find objects that implement the supported interfaces, to find out exactly which CSAPI modules the module supports. When it finds an interface, the server registers it and continues to look for the remaining interfaces.

A module can implement one or more of the following interfaces:

Table 3.1 CSAPI Module Interface


CSAPI Module Interface	Description
csIplug-in	Provides version control and descriptive information about the module.
csIAuthentication	Augments or overrides the login authentication mechanism.
csIUserAttributes	Overrides the mechanism for storing and retrieving user attributes.
csIDataTranslator	Overrides the format translation of incoming and outgoing data.

The interfaces are described in detail in API Reference.

All interfaces have the following initialization method that you must implement:

Init (nsISupports * aServer);

The server invokes this method immediately after it registers the interface in a newly loaded module. In the module, you can bind the parameter that the server returns, aServer, and use it to refer to the server instance. Use this object's QueryInterface method to find the following server interfaces:

Table 3.2 Server Interface


Server Interface	Description
csICalendarServer	Provides general server information, including version number.
csIMalloc	Allows access to server's memory allocation mechanism.

Server Query Example
The following example checks the version of Calendar Server. It demonstrates how to do the following:

Bind the returned reference from the Init method.

Query the server for an interface.

Call a server method in that interface.

Release the server reference.

NS_IMETHODIMP csDataTranslator :: Init(nsISupports * aServer)
{
nsresult res = NS_COMFALSE ;
PRUint32 min, maj;
csICalendarServer * cs;
/* QueryInterface for CalendarServer. If call succeeds, server
increments reference count */
if (aServer)
res = aServer->QueryInterface(kICalendarServerIID,(void**)&cs);
/* If succeeded in getting reference to server, check version */
if (NS_SUCCEEDED(res)) {
cs->GetVersion(maj,min);
if (min > 0 && maj >= 1)
res = NS_OK;
else
res = NS_COMFALSE;
/* Release this reference to the server instance */
cs->Release();
}
return res;
}

Building the CSAPI Samples
The distribution includes sample code for each of the CSAPI interfaces in the csapi/samples directory. You can use these files as templates in building your own CSAPI modules. The following sample modules are provided:

Table 3.3 CSAPI Modlue Sample


CSAPI Module Sample	Description
Authentication	This sample overrides the default login authentication mechanism, using local authentication to validate users. The sample works on Solaris and on Window NT: On Solaris, it uses the pam library to authenticate against the local /etc/passwd file or NIS. On Windows NT, it uses the WIN32 API LogonUser, which authenticates against Microsoft clients. In order for this sample to work properly on NT, the administrator must enable the privilege for users to log on via batch jobs. You can do this from within the UserManager Administrative Tool, under the Policies/User Rights section.
DataTranslator	This sample overrides the default format translation of incoming and outgoing data. It shows how to convert icalendar data into Micrrosoft Outlook CSV format. CSV format is a simple line-oriented file, where each entry has its own line and properties are separated by commas.
UserAttributes	This sample overrides the default mechanism for storing and retrieving user attributes. It shows how to use the Berkeley database to store local user preferences. This code works on all supported platforms. The database is a simple table-driven key/value pair. The key for storing user preferences is a string stored as $user.$pref. The key must be unique.

The samples directory contains a makefile to create the plug-ins that Calendar Server uses. To build the samples, execute the appropriate make command for your operating system:

In a Unix command shell, type the following:

cd server_root/csapi/samples

make -f Makefile

In a DOS command shell, type the following:

cd server_root/csapi/samples

nmake -f makefile.win

API Reference

This section lists the interfaces that a CSAPI module can support, and the methods that can be implemented for each interface, as well as the interfaces on the server side with which modules can communicate.

This section describes the following server and CSAPI interfaces:

Server Interface: csICalendarServer

Server Interface: csIMalloc

CSAPI plug-in Interface: csIplug-in

CSAPI Authentication Interface: csIAuthentication

CSAPI User Attribute Access Interface: csIUserAttributes

CSAPI Data Format Translation Interface: csIDataTranslator

Server Interface: csICalendarServer
Provides server version information to a module.

Methods
The csICalendarServer interface has the following method:


GetVersion	Gets the major and minor version of the server. This value must be greater than or equal to 1.0.

Description
plug-in modules can query the csICalendarServer interface to get version information about the running instance of Calendar Server.

A reference to this object is returned by a module's initialization method, which the server calls when it loads the module. The reference is valid for as long as the plug-in module is loaded.

GetVersion
Purpose
Provide plug-in module with server version information.

Syntax
PRUint32 GetVersion (PRUint32& aMajorValue,
PRUint32& aMinorValue)

Parameters
The method has the following parameters:


aMajorValue	On return, contains the major version number.
aMinorValue	On return, contains the minor version number.

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.

Server Interface: csIMalloc
Allocates and frees memory.

Methods
The csIMalloc interface has the following methods:


Calloc	Allocates and initializes memory for a number of objects.
Free	Frees memory that is no longer in use.
FreeIf	Frees memory, allowing a NULL pointer.
Malloc	Allocates an amount of memory.
Realloc	Reallocates previously allocated memory.

Description
plug-in modules can use this object to take advantage of the server's efficient memory allocation technique.

Calloc
Purpose
Allocate and initialize memory for a number of objects.

Syntax
void* Calloc (PRUint32 aSize,
PPRUint32 aNum)

Parameters
The method has the following parameters:


aSize	The size in bytes of each object.
nNum	The number of objects.

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.

Free
Purpose
Free memory previously allocated by the Malloc method.

Syntax
PRUint32 Free (void * aPtr)

Parameters
The method has the following parameter:


aPtr	A pointer to the memory to be freed.

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

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

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

Syntax
PRUint32 FreeIf (void * aPtr)

Parameters
The method has the following parameter:


aPtr	A pointer to the memory to be freed or NULL.

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

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

Malloc
Purpose
Allocate a specified amount of memory.

Syntax
void* Malloc (PRUint32 nBytes)

Parameters
The method has the following parameter:


nBytes	The size in bytes of the memory to be allocated.

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

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

Realloc
Purpose
Reallocate memory that was previously allocated.

Syntax
void* Realloc (void * aPtr,
PRUint32 nBytes)

Parameters
The method has the following parameter:


aPtr	A pointer to previously allocated memory.
nBytes	The size in bytes of the memory to be allocated.

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

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

CSAPI plug-in Interface: csIplug-in
Implement the methods in this interface to provide server with information about the plug-in module on startup.

Methods
The csIplug-in interface has the following methods:


GetDescription	Gets a textual description of what the plug-in does.
GetVendorName	Gets a textual description of the vendor supplying this plug-in.
GetVersion	Gets the major and minor version of the plug-in. This value must be greater than or equal to 1.0.
Init	Confirms that the interface was found and registered.

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. You provide methods that return descriptive information to the server.

GetDescription
Purpose
Retrieve a text description of the module.

Syntax
PRUint32 GetDescription (NSString& aDescription)

Parameters
The method has the following parameter:


aDescription	On return, contains the text description of the module.

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

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

GetVendorName
Purpose
Retrieve a text description of the vendor supplying the module.

Syntax
PRInt32 GetDescription (NSString& aDescription)

Parameters
The method has the following parameter:


aDescription	On return, contains the text description of the vendor.

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

Description
Use this method to identify the module's supplier.

GetVersion
Purpose
Provide server with version information on startup.

Syntax
PRUint32 getversion (PRUint32& aMajorValue,
PRUint32& aMinorValue)

Parameters
The method has the following parameters:


aMajorValue	On return, contains the major version number.
aMinorValue	On return, contains the minor version number.

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.

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

Syntax
PRUint32 Init (nsISupports * aServer)

Parameters
The method has the following parameter:


aServer	On return, this location contains a reference to the server with which the module is registered.

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.

CSAPI Authentication Interface: csIAuthentication
Implement the methods in this interface to augment or override the default authentication procedures when a user logs in to Calendar Server.

Methods
The csIAuthentication interface has the following methods:


Init	Confirms that the interface was found and registered.
Logon	Augments or overrides the server's native authentication mechanism.

Description
You define a Logon method that implements the authentication technique of your choice, then indicates whether the system should continue with the default authentication procedure.

Init
Purpose
Confirm that the interface has been registered, and provides a reference to the server.

Syntax
PRUint32 Init (nsISupports * aServer)

Parameters
The method has the following parameter:


aServer	On return, this location contains a reference to the server with which the module is registered.

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.

Logon
Purpose
Augment or override the authentication procedure for plain text login.

Syntax
PRUint32 Login (char * aUser,
char * aPassword,
PRInt32 * aReturnCode)

Parameters
The method has the following parameters:


aUser	The user's login name.
aPassword	The plain text password.
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

Returns
NS_AUTHENTICATION_LOGON_SUCCESS on success, NS_AUTHENTICATION_LOGON_FAILURE on 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.

Use the return code (aReturnCode) to tell the server whether to continue with the default authentication process after executing this method. The return code must be one of the following constant values:


NS_CONTINUE_DEFAULT_PROCESSING	Indicates that the server is to continue default authentication processing.
NS_OVERRIDE_DEFAULT_PROCESSING	Indicates that this method overrides the server's native authentication mechanism.

CSAPI User Attribute Access Interface: csIUserAttributes
Implement the methods in this interface to override the procedure for setting or retrieving user attributes.

Methods
The csIUserAttributes interface has the following method listed here with their purposes:


FreeAttribute	Free the memory used to store a retrieved attribute.
GetAttribute	Retrieve an attribute value for a user.
Init	Confirm that the interface was found and registered.
SetAttribute	Set an attribute value for a user.

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

FreeAttribute
Purpose
Free the memory associated with your local attribute storage.

Syntax
PRUint32 FreeAttribute (char * aValue)

Parameters
The method has the following parameter:


aValue	The location you allocated to contain the retrieved attribute value.

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 FreeAttribute method to free that memory when it is no longer needed, using the same memory management technique.

GetAttribute
Purpose
Retrieve an attribute value for a user.

Syntax
PRUint32 GetAttribute (char * aUser,
char * aKey,
char ** aValue)

Parameters
The method has the following parameters:


aUser	The name of the user.
aKey	The attribute key.
aValue	On return, this location contains a pointer to the retrieved attribute value.

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.

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

Syntax
PRUint32 Init (nsISupports * aServer)

Parameters
The method has the following parameter:


aServer	On return, this location contains a reference to the server with which the module is registered.

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

SetAttribute
Purpose
Set an attribute value for a user.

Syntax
PRUint32 GetAttribute (char * aUser,
char * aKey,
char * aValue)

Parameters
The method has the following parameters:


aUser	The name of the user.
aKey	The attribute key.
aValue	The value.

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

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

CSAPI Data Format Translation Interface: csIDataTranslator

Implement the methods in this interface to translate the format of data flowing to or from the database.

Methods
The csIDataTranslator interface has the following methods:


GetSupportedContentType	Informs the server about the content types that this module can translate between.
Init	Confirms that the interface was found and registered.
Translate	Implements the translation from one format to another.

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 "Format-Out" component of a WCAP response.

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


Mimetype	Description
text/calendar	ICAL
text/xml	ICAL in XML
text/sxml	ICAL in SXML
text/vcalendar	VCalendar
text/js	Native javascript

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.

GetSupportedContentType
Purpose
Inform the server of the input and output content types of this translation module.

Syntax
PRUint32 GetSupportedContentType (
char ** aSupportedInContentTypes,
char ** aSupportedOutContentType,
char ** aPreferredInContentType)

Parameters
The method has the following parameters:


aInContentTypes	A list of content-types that the server can send as input to translator. An array of NULL-terminated strings.
aOutContentType	On return, points to the content-type this translator generates. You must allocate memory for this string.
aPreferredInContentType	On return, points to the content-type this translator uses as input.You must allocate memory for this string.

Returns
Zero on success, non-zero on failure.

Description
Use this method to inform the server what content-type the plug-in module takes as input, and what content-type it generates. You are responsible for allocating and freeing memory for all out parameters.

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

Syntax
PRUint32 Init (nsISupports * aServer)

Parameters
The method has the following parameter:


aServer	On return, this location contains a reference to the server with which the module is registered.

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

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)

Parameters
The method has the following parameters:


aInContentType	The content type of the data to be translated.
aOutContentType	The content type that is generated by translator.
aInBuffer	A pointer to the location of the incoming data.
aOutBuffer	On return, a pointer to the location of the translated data. You must allocate memory for this buffer.
aInSize	A pointer to the size of the input buffer in bytes.
aOutSize	On return, a pointer to the size of the output buffer in bytes.

Returns
Zero 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. You are responsible for allocating and freeing memory for all out parameters.