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

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

Method: GetSupportedContentTypes	Informs the server about the content types that this database translator supports.
Method: Init	Confirms that the interface was found and registered.
Method: 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.

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

`MIME Type`	Description
`text/calendar`	iCalendar
`text/xml`	iCalendar in XML

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.

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

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