Chapter 2   CSAPI Reference


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

Use the APIs listed in Table 2-1 and Table 2-2 to augment or override Sun™ ONE Calendar Server's default behavior:

Table 2-1    Client APIs

csIAccessControl	Augments or overrides the access control mechanism.
csIAuthentication	Augments or overrides the login authentication mechanism.
csICalendarLookup	Augments or overrides the default calendar lookup mechanism.
csIDataTranslator	Augments or overrides the format translation of incoming and outgoing data.
csIPlugin	Provides version control and descriptive information about the module.
csIUserAttributes	Augments or overrides the mechanism for storing and retrieving user attributes.
csIQualifiedCalidLookup	Retrieves a calendar ID for the specified qualified URL.

Table 2-2    Server APIs

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

csIAccessControl

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

Methods
The csIAccessControl interface implements two methods:

CheckAccess	Sets access control criteria for users.
Init	Confirms that the interface was found and registered.

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.

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:

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

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:

Table 2-3    ICS_ACCESSTYPE Constants

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.

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:

aServer

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

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.

csIAuthentication

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

Methods
The csIAuthentication interface implements five methods:

ChangePassword	Change a user's password.
Init	Confirms that the interface was found and registered.
Logon	Logs in a user.
Logout	Logs out a user.
VerifyUserExists	Verify a user's existence.

Description
Allows you to define logon, logoff, verification, and password methods that implement the authentication technique of your choice. You may 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.

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:

aUser	The user's name.
aOldPassword	The old password.
aNewPassword	The new 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
On success, NS_AUTHENTICATION_CHANGEPASSWORD_SUCCESS. On failure, NS_AUTHENTICATION_CHANGEPASSWORD_FAILURE.

Description
Changes the password of the specified user.

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:

aServer

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

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.

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:

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
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 Sun ONE 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

Purpose
Logout a user.

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

Parameters

The method has the following two parameters:

aUser	The user ID of the user to be logged out.
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_OK on success. A non-zero error code on failure.

Description

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:

aUser	The user ID of the user to be logged out.
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_OK on success. A non-zero error code on failure.

Description

csICalendarLookup

Implement the methods in this interface to augment or override the default calendar lookup (LDAP). There are two types of calendar lookup provided in Sun ONE Calendar Server: algorithmic or LDAP. LDAP is the default type. Some of the methods in this plug-in are used only by the LDAP-type lookup.

The table that follows lists the methods for this plug-in, tells which type of lookup it supports: Algorithmic (Alg), or LDAP, and gives a description of the method.

Methods
The csICalendarLookup implements the following methods:

Method	Type	Description
DeleteHostnameForCalid	LDAP only	Removes the host name entry from the calendar lookup database for a specific calendar.
FreeCalid	both Alg and LDAP	Frees a previously allocated, fully qualified calid.
FreeType	both Alg and LDAP	Frees a previously allocated type.
GetHostnameForCalid	LDAP only	Gets the hostname from the calendar lookup database associated with the calendar specified by the calid
Init	both Alg and LDAP	Confirms that the interface was found and registered.
QualifyCalid	both Alg and LDAP	Returns the name of the qualified calid.
QueryType	both Alg and LDAP	Queries the type of plug-in.
SetHostnameForCalid	LDAP only	Sets the host name for a calendar user associated with a calid being created.

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

piReturnCode Values
There are four possible return codes for the piReturnCode parameter:

• Cannot connect to LDAP server

• Insufficient privileges to modify LDAP entry

• Invalid credentials to connect to LDAP

• No value for back end host

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:

psCalid	calid for which the hostname is requested.
piReturnCode	0= successful, non-zero indicates failure.

Returns
Returns zero for success; a non-zero code for failure. See piReturnCode Values.

Description
Removes the hostname associated with the specified calendar in the calendar lookup database. This is a no-op for the algorithmic implementation.

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:

aQualifiedCalid	calid to free.
aReturnCode	NS_OK if successful. Normal processing will not continue if unsuccessful.

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

Description
Used by both implementations of lookup.

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:

aType	The database plug-in type to free
aReturnCode	NS_OK if successful. Normal processing will not continue if unsuccessful.

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

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

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:

psCalid	calid for which the hostname is requested.
ppsHost	The hostname to be returned.
piReturnCode	0= successful, non-zero indicates failure.

Returns
Returns zero for success; a non-zero code for failure. See piReturnCode Values.

Description
Gets the hostname associated with a calendar in the calendar lookup database. This is a no-op for the algorithmic implementation.

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:

aServer

On return, 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.

QualifyCalid

Purpose
Qualifies the relative calid.

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

Parameters
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.

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

QueryType

Purpose
Query type of database plug-in.

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

Parameters
The method has the following parameters:

aType	The type of CLD (Calendar Lookup Database).
aReturnCode	NS_OK if successful. Normal processing will not continue if unsuccessful.

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

Description
This function retrieves a string representing the type of CLD the plugin implements.

The only supported type is "algorithmic", which supports regular expressions.

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:

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; non-zero for failure. See

Description
Sets the hostname for a calid that is about to be created. This is a no-op for the algorithmic implementation.

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:

GetSupportedContentTypes	Informs the server about the content types that this database translator supports.
Init	Confirms that the interface was found and registered.
Translate	Translates calendar data to the specified MIME format.

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.

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

MIME Type	Description
text/calendar	iCalendar
text/xml	iCalendar in XML
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.

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:

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 will convert 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

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

Description
Get the content type this database translator supports.

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:

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.

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:

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

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.

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:

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. For a list of the current version numbers for each plug-in API, see Current Plug-in API Versions in the CSAPI overview chapter.
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. The methods return descriptive information to the server.

GetDescription

Purpose
Retrieve a text description of the module.

Syntax
PRUint32 GetDescription (nsString& aDescription) = 0;

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 GetVendorName (nsString& aVendorName) = 0;

Parameters
The method has the following parameter:

aVendorName

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) = 0;

Parameters
The method has the following two 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) = 0;

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.

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:

FindCalid	Returns a calendar ID for the qualified URL.
Init	Confirms that the interface was found and registered.

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

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:

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

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.

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:

aServer

On return, 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.

csIUserAttributes

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

Methods
The csIUserAttributes interface implements four methods:

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 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
PRint32 FreeAttribute (char* aValue, PRInt32 *aReturnCode) = 0;

Parameters
The method has the following two parameters:

aValue	The location you allocated to contain the retrieved attribute value.
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

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. (See csIMalloc.)

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:

aUser	The name of the user.
aKey	The attribute key.
aValue	On return, this location contains a pointer to the retrieved attribute value.
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

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) = 0;

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.

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:

aUser	The name of the user.
aKey	The attribute key.
aValue	The value.
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

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

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

csICalendarServer

Provides server version information to a plug-in module.

Methods

The csICalendarServer interface implements two methods:

GetVersion	Get the calendar server version.
Init	Confirms that the interface was found and registered.

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

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:

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.

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.

csIMalloc

Allocates and frees memory.

Methods
The csIMalloc interface implements six 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.
Init	Confirms that the interface was found and registered.
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.The object is valid for the full lifetime of the client, so Init does not return a reference.

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:

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) = 0;

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 to free previously allocated memory.

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:

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.

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.

Malloc

Purpose
Allocate a specified amount of memory.

Syntax
void* Malloc (PRUint32 nBytes) = 0;

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
Reallocates memory that was previously allocated.

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

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 to reallocate memory that was previously allocated.