Sun Java System Calendar Server 6 2005Q4 Developer's Guide

API: csICalendarLookup

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

Methods

The csICalendarLookup implements the following methods:

Method	Description
Method: DeleteHostnameForCalid	Removes the host name entry from the calendar lookup database for a specific calendar.
Method: FreeCalid	Frees a previously allocated, fully qualified `calid`.
Method: FreeType	Frees a previously allocated type.
Method: GetHostnameForCalid	Gets the hostname from the calendar lookup database associated with the calendar specified by the `calid`
Method: Init	Confirms that the interface was found and registered.
Method: QualifyCalid	Returns the name of the qualified `calid`.
Method: QueryType	Queries the type of plug-in.
Method: SetHostnameForCalid	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

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:

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

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:

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

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:

`aType`	The database plug-in type to free
`aReturnCode`	`NS_OK` if successful. Normal processing does 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.

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:

`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. 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:

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.

Method: 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

Method: 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 does 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 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:

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

Returns

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

Description

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