Using CSAPI

The following section describes how the system loads and uses the plug-ins you provide. Default plug-ins ship with the system. You can choose to augment or override any or all of them.

Loading CSAPI Modules

Calendar Server loads CSAPI modules from the cal/bin/plugins 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 ics.conf for the modules to be dynamically loaded at server startup. If the value of the preference csapi.plugin.loadall is y, the server loads all shared objects in the cal/bin/plugins directory whose names begin with the prefix cs_. Otherwise, if the value is n, various parameters exist for the various plug-ins. For more information on the preferences in ics.conf, see the Sun Java System Calendar Server 6 2005Q4 Administration Guide.

To specify the loading of a specific plug-in, csapi.plugin.loadall must be set to n. In addition, two parameters must be used: csapi.plugin.plugin name, with a value of y, and csapi.plugin.plugin name.name, with the value being the name of the plug-in.

For example, to load only the calendar-lookup plug-in, the parameters are:

csapi.plugin.loadall = "n"
csapi.plugin.calendarlookup = "y"
csapi.plugin.calendarlookup.name = "calendarlookup"

Note that the plugin name part of the parameter must match on both parameters, but that it does not have to be the same as the value of the csapi.plugin.calendarlookup.name parameter. Thus, if you wanted to create a plug-in called cs_myown_plugin, you could call the parameters csapi.plugin.anyname, and csapi.plugin.anyname.name. The value of csapi.plugin.anyname.name must be “cs_myown_plugin”.

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.

Plug-in Interfaces

All CSAPI plug-ins 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 an object implementing the csIPlugin interface. This allows the server to query the plug-in for version, description, and vendor information. While this interface is optional, you should implement it so the server can ensure version control.

Plug-in Version Numbers

Each default plug-in interface can have a different version number. Version numbers increment by a whole number when the API is updated by Sun Microsystems, Inc. All custom plug-ins must use the methods in the current version of the default plug-in API.

If you created a custom plug-in based on an earlier default plug-in version, you must update your custom plug-in to use the new version of all updated methods, and you must increment its version number to reflect the current version number of the default plug-in.

The system does not load plug-ins with version numbers earlier than the current default version number. Your plug-in must have a version number greater than the current default plug-in, but less than the next whole number. For example, if you are writing, or have created in the past, a custom plug-in for csIDatabaseLookup, which is currently at version 2.0, your plug-in version number must be greater than 2.0 and less than 3.0.

The following table lists the current version of each plug-in API.

Client and Server Plug-in API's

The CSAPI API's fall into two categories: client and server commands.

The interfaces are described in detail in Chapter 2, CSAPI Reference

Client API's

The following table lists the CSAPI client API's, which can be implemented by one or more plug-ins.

Server API's

The following is a list of the server API's, which can be implemented with one or more plug-ins.

Required Initialization Routine

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. Your custom plug-in can use the QueryInterface method to find the server interfaces.

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