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

API: csIUserAttributes

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

Methods

The csIUserAttributes interface implements four methods:

Method: FreeAttribute	Free the memory used to store a retrieved attribute.
Method: GetAttribute	Retrieve an attribute value for a user.
Method: Init	Confirm that the interface was found and registered.
Method: 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.

Method: 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 Method: FreeAttribute method to free that memory when it is no longer needed, using the same memory management technique. (See API: csIMalloc.)

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

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

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