Home

	Expand Search

e-Adapter Development Kit Programmer's Reference

Chapter 3 Adapter APIs

Chapter 3

Adapter APIs

The Adapter API is the set of functions that are implemented inside an adapter plug-in and are called by the e-ADK during processing. This chapter provides the following information about Adapter APIs:

Understanding Adapter Functions

These Adapter API functions must conform to the naming and argument conventions described for each function. For example, if an adapter plug-in is implementing Acquire mode for buffered data, the adapter must implement the following function:

NNADKStubPlugIn_API bool acquireBuffer
(NNSY_NDO_NAMESPACE NNDataBuffer& dataBuffer,
void* userdata NNSY_ADK_NAMESPACE NNADKOutOfBand& oobInformation)

You must provide the body to the functions that are appropriate for the modes and datatypes that you wish to implement inside your adapter. You provide this information within your adapter plug-in.

The NNADKStubPlugIn.cpp file in the examples directory contains stub implementations of each function that the adapter should implement. The NNADKSTUBPLUGIN_API macro is used to import or export the function on Windows NT.

Only the Adapter APIs and New Era of Networks Data Object APIs that are explicitly documented in this Programmmer Reference are supported by New Era of Networks, Inc. It is recommended that you not build code or applications using undocumented APIs because these will not be supported.

To create an adapter, modify the following functions, depending on the modes and data representation the adapter supports.

Understanding Userdata Parameters

The userdata parameter is used in each of the following functions that you modify to create an adapter. You can create an object and pass it to all the functions. You should allocate memory for the object in the initAdapter() function because userdata is called for in all the functions. The memory should be de-allocated in the shutdownAdapter() function. For the initAdapter() and shutdownAdapter() functions, userdata is a pointer to a void pointer. For the other functions, userdata is a void pointer.

Examples of Userdata

The following example illustrates how userdata is instantiated and cast in the initAdapter() function.

*userdata=new FileObject;

FileObject* pFileObject=(FileObject*)(*userdata);

The following example illustrates how userdata is de-allocated in the shutdownAdapter() function:

if (userdata)

{

    FileObject* pFileObject=(FileObject*)(userdata);

    if(pFileObject)

     {

    delete pFileObject;

     }

 }

The following example illustrates how the userdata parameter is cast in the remaining functions:

if ((FileObject*) userdata)

{

    FileObject* pFileObject=(FileObject*)(userdata);

     if (pfileObject)

     {

         ...

     }

 }

Adapter APIs

Description

The e-ADK provides the following APIs for working with adapters.

Methods

initAdapter

Description

initAdapter() is an optional function for all modes. This function can read configuration information, connect to the user source or target application, and create an object that can be passed to the other functions.

Syntax

NNADKStubPlugIn_API bool initAdapter(

    NNSY_CONFIG_NAMESPACE NNConfig& config

    NNSY_ADK_NAMESPACE e_NNAdapterMode mode,

    void** userdata)

Parameters

Return values

Returns TRUE if the initialization succeeds; returns FALSE if the initialization fails, and the adapter shuts down.

Usage

The Adapter Shell reads the configuration keys from the configuration file.

Based on the value in the mode parameter, the Adapter Shell calls the following functions in a loop. Based on the return values of these functions, the Adapter Shell exits the loop and calls the shutdownAdapter() function. Each of these functions is defined in this chapter.

shutdownAdapter

Description

shutdownAdapter() is called for all modes. shutdownAdapter() should disconnect from the source or target application and destroy the user data.

Syntax

NNADKStubPlugIn_API void shutdownAdapter(void** userdata)

Parameters

acquireSchema

Description

acquireSchema() is called if the mode value for initAdapter() is AM_Schema. acquireSchema() calls the source application to define the structure for data received in Acquire, Deliver, or Process mode. The NNDOObject NNDOSchemaTree must be built in the appropriate structure.

Syntax

NNADKStubPlugIn_API bool acquireSchema(

    const STL_STRING& schemaName,

    NNSY_NDO_NAMESPACE NNDOObject& schemaObject,

    void* userdata,

    int instance)

Parameters

Return values

Returns TRUE if the Adapter Shell should call this function again; returns FALSE if the schema generation is complete.

acquireData

Description

acquireData() is called if the mode value for initAdapter() is AM_Acquire and data is set to NDO. acquireData() retrieves data from the source application and places the data in the NNDOObject NNDODataTree.

Syntax

NNADKStubPlugIn_API bool acquireData(

    NNSY_NDO_NAMESPACE NNDOObject& dataObject,

    void* userdata,

    NNSY_ADK_NAMESPACE NNADKOutOfBand& oobInformation)

Parameters

Return values

Return TRUE if the Adapter Shell should call this function again; returns FALSE if data acquisition is complete.

acquireBuffer

Description

acquireBuffer() is called if the mode value for initAdapter() is AM_AcquireBuffer and data is set to Buffer. acquireBuffer() retrieves data from the source application and places the data in the NNDataBuffer.

Syntax

NNADKStubPlugIn_API bool acquireBuffer(

    NNSY_NDO_NAMESPACE NNDataBuffer& dataBuffer,

    void* userdata

    NNSY_ADK_NAMESPACE NNADKOutOfBand& oobInformation)

Parameters

Return values

Returns TRUE if the Adapter Shell should call this function again; returns FALSE if data acquisition is complete.

acquireCatalog

Description

acquireCatalog() is the adapter entry point for the AM_AcquireCatalog mode. Catalog mode allows the adapter to return an NDO containing a listing of all schemas available and an NDO containing status information about the available schemas. Both NDOs are serialized into an XML format and written to files in the working directory. The file containing the listing of schemas is defined by the configuration key Adapter.catalog.out. The file containing the schema status information is defined by the configuration key Adapter catalog.out.status.

Syntax

NNADKSTUBPLUGIN_API bool acquireCatalog(

NNSY_NDO_NAMESPACE NNDOObject& dataObject,

NNSY_NDO_NAMESPACE NNDOObject& ndoStatus,

void* userdata);

Parameters

Return values

Currently, return value is not used. The adapter initiates shutdown regardless of the return value entered.

processData

Description

processData() is called if the mode value for initAdapter() is AM_Process and data is set to NDO. This function receives data from a transport and should modify the data by working with the application. The data on the transport is a serialized DataTree. The data is deserialized, and the tree is sent to the processData() function. The modified DataTree is put onto the transport.

Syntax

NNADKStubPlugIn_API bool processData(

    NNSY_NDO_NAMESPACE NNDOObject& inputDataObject,

    NNSY_NDO_NAMESPACE NNDOObject& outputDataObject,

    void* userdata

    NNSY_ADK_NAMESPACE NNADKOutOfBand& oobInformation)

Parameters

Return values

Returns TRUE if the Adapter Shell should call this function again; returns FALSE if data processing is complete.

processBuffer

Description

processBuffer() is called if the mode value for initAdapter() is AM_ProcessBuffer and data is set to Buffer. processBuffer() receives data from a transport and modifies the data by working with the application. The processBuffer() function receives raw data and returns raw data.

Syntax

NNADKStubPlugIn_API bool processBuffer(

    NNSY_NDO_NAMESPACE NNDataBuffer& inputBuffer,

    NNSY_NDO_NAMESPACE NNDataBuffer& outputBuffer,

    void* userdata

    NNSY_ADK_NAMESPACE NNADKOutOfBand& oobInformation)

Parameters

Return values

Return TRUE if the Adapter Shell should call this function again; returns FALSE if data processing is complete.

deliverData

Description

deliverData() is called if the mode value for initAdapter() is AM_Deliver and data is set to NDO. deliverData() receives data from a transport and delivers the data to the target application.

Syntax

NNADKStubPlugIn_API bool deliverData(

    NNSY_NDO_NAMESPACE NNDOObject& dataObject,

    void* userdata,

    NNSY_ADK_NAMESPACE NNADKOutOfBand& oobInformation)

Parameters

Return values

Return TRUE if the Adapter Shell should call this function again; returns FALSE if data delivery is complete.

deliverBuffer

Description

deliverBuffer() is called if the mode value for initAdapter() is AM_DeliverBuffer and data is set to Buffer. deliverBuffer() receives data from a transport and writes the data to the target application.

Syntax

NNADKStubPlugIn_API bool deliverBuffer(

    NNSY_NDO_NAMESPACE NNDataBuffer& dataBuffer,

    void* userdata

    NNSY_ADK_NAMESPACE NNADKOutOfBand& oobInformation)

Parameters

Return values

Return TRUE if the Adapter Shell should call this function again; returns FALSE if data delivery is complete.

acknowledgePutData

Description

acknowledgePutData() is an optional call used as a callback function to inform the adapter of the status of outbound NDO messages. It is applicable only to AM_Acquire and AM_Process modes.

The adapter is called back after each outbound message is resolved, which allows the adapter to commit or rollback the transaction. The function is invoked by setting the configuration key Adapter.acknowledge.put to true.

Syntax

NNADKSTUBPLUGIN_API bool acknowledgePutData(

NNSY_NDO_NAMESPACE NNDOObject& inputdataObject,

NNSY_ADK_NAMESPACE NNADKOutOfBand& oobInformation,

void* userdata,

NNSY_ADK_NAMESPACE e_Acknowledge ackStatus);

Parameters

Return values

Return TRUE if the Adapter Shell should continue processing messages. Return FALSE to initiate the shutdown process.

If the e-ADK is unsuccessful in putting a message to the transport and the failure transport, the e-ADK shuts down regardless of the return value from this function.

acknowledgePutBuffer

Description

acknowlwedgePutBuffer() is an optional call used as a callback function to inform the adapter of the status of outbound bugger messages. It is applicable only to Acquire and Process mode when used as AM_AcquireBuffer and AM_ProcessBuffer.

The adapter is called back after each outbound message is resolved, which allows the adapter to commit or rollback the transaction. The function is invoked by setting the configuration key Adapter.acknowledge.put to true.

Syntax

NNADKSTUBPLUGIN_API bool acknowledgePutBuffer(

NNSY_ADK_NAMESPACE NNDataBuffer& dataBuffer,

NNSY_ADK_NAMESPACE NNADKOutOfBand &OB,

void* userdata,

NNSY_ADK_NAMESPACE e_Acknowledge ackStatus);

Parameters

Return values

Return TRUE if the Adapter Shell should continue to process messages. Return FALSE to initial the shutdown process.

If the e-ADK is unsuccessful in putting a message to the transport and the failure transport, the e-ADK shuts down regardless of the return value from this function.

Handle Quiet State

Description

handleQuietState() is an optional call used to maintain or reestablish adapter connectivity to resources during intervals when the Adapter Shell is polling a queue for inbound messages. It is applicable to Process and Deliver modes when used as AM_Process, AM_ProcessBuffer, AM_Deliver, and AM_DeliverBuffer. You must set the following keys:

• Set exit_if_empty to false.

• Set transport.maximum.transport.retries for the desired number of retries.

  0 indicates that the e-ADK will loop infinitely, waiting for data to be placed on the transport.

  A finite value indicates the specific number of retries desired.

• Set enter.quiet.state to greater than 0 but less than maximum.tansport.retries if maximum.tranport.retries is set to a finite value other than 0.

Syntax

NNADKSTUBPLUGIN_API bool handleQuietState(void* userdata);

Return values

Return TRUE to continue to retry. Return FALSE to exit from the retry loop and initiate the shutdown process.

Examples

Example 1

This example shows the configuration key settings for the following: If the transport has no message to process, the adapter handleQuietState() function would be called every 10 seconds.

exit_if_empty=false

maximum.transport.retries=0

enter.quiet.state=2

transport.wait_time=5

commitDeliveredMessages

Description

commitDeliveredMessages() is an optional call used for batch deliver. This call is applicable only to AM_Deliver and AM_DeliverBuffer. Batch Deliver mode is controlled through the configuration key Adapter.batch.size. If Adapter.batch.size is set to an integer greater than 1, then batch deliver mode is invoked and the adapter must provide the commitDelviered Messages() entry point. The Adapter Shell will retrieve the number of messages from the inbound queue as indicated in the configuration key. The Adapter Shell will hold off committing the transaction until commitDeliveredMessages() is called.

Syntax

NNADKSTUBPLUGIN_API NNSY_ADK_NAMESPACE e-BatchDeliverResult commitDeliveredMessages (void* userdata);

Return values

If ADK_Commit, e-ADK commits the batch and proceeds.

If ADK_RollbackProceed, e-ADK rolls back the batch and proceeds.

If ADK_RollbackShutdown, e-ADK rolls back the batch and initiates the shutdown process.