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.