Copyright: Copyright Aldea Interactive 1996-1997. All rights reserved.


extensions
Introduction to Active Gateway Server Extensions

Active Gateway has an open architecture. It offers the Active Gateway Server Application Programming Interface to extend Active Gateway Server functionality. AGsAPI is simple and efficient and helps you to rapidly design extensions. An Active Gateway Server Extensions is a dynamic-link library (dll) complying with the programming interface AGsAPI (Active Gateway Server API) and written in C++.

If you want to develop a Client/Server application, the Active Gateway development platform will be a great opportunity. Your extension will serve clients using the Active Gateway data exchange infrastructure.

The purpose of this manual is to study the Fundamentals of Active Gateway Extensions of Active Gateway Server Extensions and to offer a complete description of the AGsAPI functions.


Principles of Active Gateway Extensions
Fundamentals of Active Gateway Server Extensions

An extension of the Active Gateway Server is a dynamic-link library (dll) written in C++ with the Microsoft Visual C++ 4.2b development environment (the compatibility with Visual C++ 5.0 and other development environments will be included with the version 1.3). Extensions are seen by an Active Gateway Server as a client, thus they use some objects of the AGCore DLL (see the documentation of the programming interface AGcAPI). The only difference with a regular client is that they exchange data directly with the server (by function calls) and not via any network connection.

Principles of Sessions

The Active Gateway Server Extensions are loaded at the launch of the Server and unloaded at the shutdown. The AGDLL utility allows you to manually load and unload an extension. The period when the extension is loaded is a session.

When the server loads an extension, it calls AGS_StartSession (if that function is exported by the dll). When it unloads the extension, it AGS_StopSession (if that function is exported by the dll). This mechanism allows you to allocate memory at the start of a session and unload it at the end of the session. When the extension processes requests, it will be able to access this memory.

Principles of Connections

Beginning of a connection

Extensions are passive clients. In the current version of Active Gateway Server, an extension cannot initiate a connection. Only an external client can initiate a connection to an extension. That means that two extensions cannot communicate directly together.

When a client requests a connection to another client, it provides the Server with a peer name. The Server tries to find that name in the loaded extensions list.

•	If the search fails then the Server searches for a standard connected client.

•	If the search is successful (an extension with the given name is loaded), the Server creates a connection with a new instance of this extension and calls AGS_StartConnection (if that function is exported by the dll) to initialise the persistent data of connection.

Data exchange (request processing)

To perform a request, a client sends a frame to the extension. The Server calls AGS_Process to transmit the frame by reference (oFrame parameter) to the extension. When the function exits, the Server send a frame to the client. It also transmits the two pointers initialized respectively by AGS_StartSession and AGS_StartConnection.

Whatever may happen during the function call the frame is sent back to the client. It is the responsability of the extension to modify the frame to transmit a return value to the client.

When the client sends a frame to the extension, the Server calls the function AGS_Process with the frame in parameter as the persistent data pointer of the connection and of the session. In exit of the function AGS_Process, if the return value is aeNoError, the Server sends the frame passed in reference to client. Else, the Server ended the connection. When a client sends a frame to an extension, he is certain that the extension (through the Server) will send him a response frame or the channel will be broken (return of aeChannelBroken in return of Recv). The code of a C++ client is as follows :

AldeaError nError;
CAldeaFrame oFrame;
oFrame[_T("REQUEST"))=_T("TIME")
nError = oProtocolClientPC.Send(oFrame);
if (nError != aeNoError)
return ;
do
{
nError = oProtocolClientPC.Recv(oFrame);
}
while (nError != aeTimeout);

It is certain that the preceding loop will end when the extension terminates the function AGS_Process. Warning: the Server doesn't control the time passed in this function. Thus, if the extension falls into an infinite loop, the client will not be able to exit the preceding loop.

End of a connection

A connection ends when :

•	the connected client decides to close the connection ;

•	the extension decides to close the connection only when processing a request ;

•	the Server kills the extension tasks because an unhandled error occured during the processing of a client request.

•	the Server is being shut down.

At the end of a connection, the Server calls AGS_StopConnection (if that function is exported by the dll) to deallocate the persistent data of the connection.


AGsAPI functions

The current version (1.0) of the programming interface Active Gateway Server API has in six functions. Only two of them are requested (AGS_Info and AGS_Process). If they are not exported, the server will not load the extension.

Information on the Extension
AGS_Info	Query on the extension characteristics.
Processing a Request
AGS_Process	Execution of a request
Sessions Management
AGS_StartSession	Session initialisation
AGS_StopSession	Session end
Connections Management
AGS_StartConnection	Connection initialisation
AGS_StopConnection	Connection end


AGS_Info

Query of the extension characteristics

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_Info(CAldeaFrame& oFrame);

Parameters

oFrame	Input : an empty frame.
Output : the frame containing the needed information for the Server (see below).

Return value

Error code of type AldeaError.

aeNoError (= 0)	If there was no error.

aeChannelBroken	If you want to notify the Server that the extension had a problem to find the needed information. Normally, this should not occur.

Description

When calling this function, the Server question the extension to know the needed information to run. The extension must complete the frame with the following slot :

"DLL_NAME"	Name of the extension.

"DLL_VERSION.NAME"	String for the extension version.

"DLL_VERSION.MAJOR"	Long integer (type long) for the number of major version of the extension.

"DLL_VERSION.MINOR"	Long integer (type long) for the number of minor version of the extension.

Only the name (slot "DLL_NAME") is currently required. The others will be used in future versions of Active Gateway Server.

To avoid possible conflicts with other extensions, we recommend that you respect the very simple normalisation of the name of Active Gateway extensions. If you want to name your extension ‘MyExtension’, add to the end the sign ":" followed by the ID of your company. Then you have the name ‘MyExtension:MySociety’. To be sure that two companies do not  have the same ID, Aldea Interactive keeps an updated ID database. To get a unique, certified ID, send a request to this following electronic address : activegateway@aldea-interactive.com or send a fax at a the following number : +33 (0)1 41 41 46 65 mentioning your name, your company (eventually) and the ID you would like..

Example

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_Info(CAldeaFrame &oFrame)

{

oFrame.Reset();

oFrame[_T("DLL_NAME")]	= _T("AGTime:Aldea");

oFrame[_T("DLL_VERSION.NAME")] = _T("1.0");

oFrame[_T("DLL_VERSION.MAJOR")] = (long)1;

oFrame[_T("DLL_VERSION.MINOR")] = (long)0;

return aeNoError;

}


AGS_Process

Processing of a request

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_Process(	void * pPrivateSession,
void * pPrivateConnection,
CAldeaFrame& oFrame);

Parameters

pPrivateSession	Input : the private data pointer of a session of the extension (see AGS_StartSession).

pPrivateConnection	Input : the private data pointer of a connection of the extension (see AGS_StartConnection).

oFrame	Input : the frame sent by the peer.
Output : the frame sent to the peer after the process.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If there was no error.

aeChannelBroken	If you want to notify the Server that a critical error occurred and the connection must be terminated.

Description

The Server calls this function each time a peer sends a frame to the extension.

The extension must analyse the frame and complete it. At the return of the function, if the extension sends the value of aeNoError, the Server sends the frame to the peer. If the return value is aeChannelBroken, the Server ends the connection without sending the frame.

If, during the process, you want to send an error message to the transmitter of the frame to notify that an error exists, you have to do this through the frame.

Example

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_Process(	void *	pPrivateSession,
void *	pPrivateConnection,
CAldeaFrame&	oFrame)

{

oFrame.Reset();

oFrame[_T("HELLO")] = _T("World");

return aeNoError;

}


AGS_StartSession

Session initialisation

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_StartSession(void *& pPrivateSession);

Parameters

pPrivateSession	Input : A void pointer with NULL value.
Output : A pointer on the data allocated by the function for all the time of the session.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If there was no error.

aeChannelBroken	If you want to notify the Server that a critical error occurred and that the connection must be terminated.

Description

This function is called by the Server to allow the extension to initialise the data used for the time of the session. The pointer passed in reference will be transmitted to the function AGS_Process. It is the responsibility of the extension to deallocate this data at the end of the session by calling AGS_StopSession.

Example

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_StartSession(void *&	pPrivateSession)

{

CAldeaDateTime *& pSessionStartTime = (CAldeaDateTime *&)pPrivateSession;

pSessionStartTime = new CAldeaDateTime;

if (pSessionStartTime == NULL)

return aeChannelBroken;

return aeNoError;

}


AGS_StopSession

Ending a Session

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_StopSession(void *& pPrivateSession);

Parameters

pPrivateSession	Input : the void pointer that was initialised with the call to the function AGS_StartSession.
Output : the pointer will not be used anymore.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If there was no error.

aeChannelBroken	If you want to notify the Server that a critical error occurred and that the connection must be terminated.

Description

It's with the call to this function that the extension must deallocate all the memory that it was able to allocate during the call to AGS_StartSession.

Example

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_StopSession(	void *&	pPrivateSession)

{

CAldeaDateTime *& pSessionStartTime = (CAldeaDateTime *&)pPrivateSession;

delete pSessionStartTime;

return aeNoError;

}


AGS_StartConnection

Starting a Connection

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_StartConnection(void *& pPrivateConnection);

Parameters

pPrivateConnection	Input : a void pointer with the NULL value.
Output : a pointer on the data allocated by the function for all the time of the connection.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If there was no error.

aeChannelBroken	If you want to notify the Server that a critical error occurred and that the connection must be terminated.

Description

This function is called by the Server to allow the extension to initialise its data that will be useable for the whole time of the connection. The pointer passed by reference will be transmitted to the function AGS_Process. It is the responsibility of the extension to deallocate this data at the end of the connection when calling the function AGS_StopConnection.

Example

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_StartConnection(void *& pPrivateConnection)

{

CAldeaDateTime *& pConnectionStartTime = (CAldeaDateTime *&)pPrivateConnection;

pConnectionStartTime = new CAldeaDateTime;

if (pConnectionStartTime == NULL)

return aeChannelBroken;

return aeNoError;

}


AGS_StopConnection

Ending a Connection

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_StopConnection(void *& pPrivateConnection);

Parameters

pPrivateConnection	Input : the void pointer that was initialised with the call to the function AGS_StartConnection.
Output : the pointer will not be used anymore.

Return value

Error code of type AldeaError.

aeNoError (= 0)	If there was no error.

aeChannelBroken	If you want to notify the Server that a critical error occurred and that the connection must be terminated.

Description

It is with the call of this function that the extension must deallocate all the memory that it was allocated during the call to AGS_StartConnection.

Example

extern "C" ALDEA_CLASS_EXPORT AldeaError AGS_StopSession(void *& pPrivateConnection)

{

CAldeaDateTime *& pConnectionStartTime = (CAldeaDateTime *&)pPrivateConnection;

delete pConnectionStartTime;

return aeNoError;

}


A session is the period between the loading of an extension and its unloading. Normally, the loading occurs at the beginning of the Server and the unloading at the end of the Server. It can be possible to load and unload an extension manually using an extensions management utility..


A connection is, like its name indicates, the period between the connection of the client to an extension and its disconnection with the extension. The connection is the period when the extension is the service of the client.