How +to implement a simple server interface

Handling asynchronous requests

The implementation +of a server requires a class derived from CServer2. This +is the active object base class responsible for handling the asynchronous +requests from the client program.

Construction and initialisation

An +instance of the CServer2 derived class is, typically, created +by the server's thread function. As an active object, it needs a priority +and this is passed as a parameter to the constructor. The choice of priority +value depends on the server's design. If the server can, ultimately, have +more than one active object, then it may be important for the CServer2 active +object to have the highest priority.

The server can now be started. +This is a code fragment taken from the example that can be found at ...\examples\Base\IPC\ClientServer\complex.

CCountServServer *pS=new CCountServServer(EPriorityStandard); +__ASSERT_ALWAYS(pS!=NULL,CCountServServer::PanicServer(ESvrCreateServer)); +... + + // Start the server +TInt err = pS->Start(KCountServerName); +if (err != KErrNone) + { + CCountServServer::PanicServer(ESvrStartServer); + }

The function CServer2::Start() adds +the CServer2 active object to the active scheduler and issues +the first request for messages. The server is now waiting for messages.

As +with all active objects, the completion of requests for messages is handled +by the CServer2::RunL() protected member function.

Handling requests

A request for a connection by a client thread +results in the creation of a new session. The request for a connection results +in a call by the client/server framework to the CServer2::NewSessionL() function. +A derived class must provide an implementation - creating and initialising +an instance of a CSession2 derived class. The framework +takes this newly created session object to the server's queue.

For +a non sharable session, requests for disconnection by a client thread cause +the relevant CSession2 object to be deleted. The CSession2 destructor +should perform appropriate cleanup.

Any other message is passed to CSession2::ServiceL(). +This function must be implemented by a derived class.

Server side session representation

The base class CSession2 represents +a client's session on the server side. This class provides the standard session +behaviour. A class derived from CSession2 must be defined +and implemented. The following class definition, taken from the example that +can be found at: ...\examples\Base\IPC\ClientServer\simple, +is typical:

class CCountServSession : public CSession2 + { +public: + CCountServSession(); + + //service request + void ServiceL(const RMessage2& aMessage); + void DispatchMessageL(const RMessage2& aMessage); + + // services available to initialize/increase/decrease/reset and + // return the counter value. + void SetFromStringL(const RMessage2& aMessage); + void Increase(); + void Decrease(); + void IncreaseBy(const RMessage2& aMessage); + void DecreaseBy(const RMessage2& aMessage); + void CounterValue(const RMessage2& aMessage); + void Reset(); + +protected: + // panic the client + void PanicClient(const RMessage2& aMessage,TInt aPanic) const; + +private: + TInt iCount; + };

Note the following:

The function ServiceL() is +called by the client/server framework to handle all messages except requests +to connect and disconnect.
ServiceL() calls DispatchMessageL() under +a trap harness.
DispatchMessageL() determines +the appropriate message service function to call by examining the operation +code of the current message. This is simply a mechanism to delegate the handling +of different request types.
The class provides message +service functions: Increase(), IncreaseBy() etc. +to service specific messages from clients.
The function SetFromStringL() needs +a string specified by the client and therefore needs to read data from the +client address space.

ServiceL()

This +is implemented as follows:

void CCountServSession::ServiceL(const RMessage2& aMessage) + { + TRAPD(err,DispatchMessageL(aMessage)); + aMessage.Complete(err); + }

After calling the appropriate service function via DispatchMessageL(), +the asynchronous request is completed with aMessage.Complete() which +passes the completion code back to the client.

DispatchMessageL()

This is implemented as follows:

void CCountServSession::DispatchMessageL(const RMessage2& aMessage) + { + switch (aMessage.Function()) + { + case ECountServSetFromString: + SetFromStringL(aMessage); + return; + case ECountServIncrease: + Increase(); + return; + case ECountServIncreaseBy: + IncreaseBy(aMessage); + return; + ... + case ECountServValue: + CounterValue(aMessage); + return; + ... + default: + PanicClient(aMessage,EBadRequest); + return; + } + }

IncreaseBy()

This message service function is implemented as follows:

void CCountServSession::IncreaseBy(const RMessage2& aMessage) + { + iCount = iCount + aMessage.Int0(); + }

Note that we need to pass the message object to the function. +The Int0() function is used to get the integer specified +in the client call - the '0' on the end of the function name indicates that +the integer is the first parameter in the set passed across from the client.

SetFromStringL()

This message service function is implemented +as follows:

void CCountServSession::SetFromStringL(const RMessage2& aMessage) + { + // length of passed descriptor (1st parameter passed from client) + TInt deslen = aMessage.GetDesLength(0); + + // Passed data will be saved in this descriptor. + RBuf buffer; + + // Max length set to the value of "deslen", but current length is zero + buffer.CreateL(deslen); + + // Do the right cleanup if anything subsequently goes wrong + buffer.CleanupClosePushL(); + + // Copy the client's descriptor data into our buffer. + aMessage.ReadL(0,buffer,0); + + // Now do a validation to make sure that the string only has digits + if (buffer.Length() == 0) + { + User::Leave(ENonNumericString); + } + ... + // Do rest of work to convert from + // string to integer, and assign.

RMessage::ReadL() reads +the descriptor from the client address space as specified by the first argument +in the message, and copies the data into the descriptor specified as its second +argument. A basic test is done to make sure there data is supplied.

CounterValue()

This is implemented as follows:

void CCountServSession::CounterValue(const RMessage2& aMessage) + { + TPckgBuf<TInt> p(iCount); + aMessage.WriteL(0,p); + }

It writes data back to a descriptor in the client address +space. The corresponding client request is:

TInt RCountServSession::CounterValue() + { + TInt res=0; + TckgBuf<TInt> pckg; + + // Note that TPckgBuf is of type TDes8 + TIpcArgs args(&pckg); + SendReceive(ECountServValue, args); + + // Extract the value returned from the server. + res = pckg(); + return res; + }

Notes

The TInt is +packaged into a descriptor before being passed to the server. The packaging +mechanism is known as package buffer.
The write operation +copies the descriptor, i.e. the package buffer containing the integer value, +back to the descriptor in the client address space. Note that the zero specified +in aMessage.WriteL(0,p); means that the argument referred +to is the first in the list passed across from the client side via the TIpcArgs object.