<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-51621C76-17B5-5829-B4EC-86B453442CDC" xml:lang="en"><title>How

to implement a simple server interface</title><shortdesc>Provides code snippets to help you to implement a simple server

interface.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-2720017E-2EDF-4DB5-81E9-2A75E434BDE3"><title>Handling asynchronous requests</title> <p>The implementation

of a server requires a class derived from <codeph>CServer2</codeph>. This

is the <i>active object</i> base class responsible for handling the asynchronous

requests from the client program. </p> <p><b>Construction and initialisation</b> </p> <p>An

instance of the <codeph>CServer2</codeph> 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 <codeph>CServer2</codeph> active

object to have the highest priority. </p> <p>The server can now be started.

This is a code fragment taken from the example that can be found at <filepath>...\examples\Base\IPC\ClientServer\complex</filepath>. </p> <codeblock id="GUID-6D887396-920C-5B5B-B58E-6700371DB31C" xml:space="preserve">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);

    }</codeblock> <p>The function <codeph>CServer2::Start()</codeph> adds

the <codeph>CServer2</codeph> active object to the active scheduler and issues

the first request for messages. The server is now waiting for messages. </p> <p>As

with all active objects, the completion of requests for messages is handled

by the <codeph>CServer2::RunL()</codeph> protected member function. </p> <p><b>Handling requests</b> </p> <p>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 <xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita#GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C/GUID-3260F745-3597-349A-9754-303DC020EF18"><apiname>CServer2::NewSessionL()</apiname></xref> function.

A derived class must provide an implementation - creating and initialising

an instance of a <xref href="GUID-D5A30C75-E22C-34E8-913B-7D2CA6AD5C51.dita"><apiname>CSession2</apiname></xref> derived class. The framework

takes this newly created session object to the server's queue. </p> <p>For

a non sharable session, requests for disconnection by a client thread cause

the relevant <codeph>CSession2</codeph> object to be deleted. The <codeph>CSession2</codeph> destructor

should perform appropriate cleanup. </p> <p>Any other message is passed to <codeph>CSession2::ServiceL()</codeph>.

This function must be implemented by a derived class. </p> </section>

<section id="GUID-2E5EB078-59D7-49B3-A32A-17AF0FBD3492"><title>Server side session representation</title> <p>The base class <codeph>CSession2</codeph> represents

a client's session on the server side. This class provides the standard session

behaviour. A class derived from <codeph>CSession2</codeph> must be defined

and implemented. The following class definition, taken from the example that

can be found at: <filepath>...\examples\Base\IPC\ClientServer\simple</filepath>,

is typical: </p> <codeblock id="GUID-8DCCB062-2630-5C2E-A590-89208928E902" xml:space="preserve">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;

    };</codeblock> <p>Note the following: </p> <ul>

<li id="GUID-D3EE4EBA-47F3-5EC4-8487-A4DBD809D2B3"><p>The function <codeph>ServiceL()</codeph> is

called by the client/server framework to handle all messages except requests

to connect and disconnect. </p> </li>

<li id="GUID-C4980BE1-D852-5AAE-8782-8C98D95BA102"><p> <codeph>ServiceL()</codeph> calls <codeph>DispatchMessageL()</codeph> under

a trap harness. </p> </li>

<li id="GUID-19A78104-9C7C-53C7-8328-F34E2CBCF857"><p> <codeph>DispatchMessageL()</codeph> 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. </p> </li>

<li id="GUID-9A3F4396-8561-540D-BE0B-C674A14704AE"><p>The class provides message

service functions: <codeph>Increase()</codeph>, <codeph>IncreaseBy()</codeph> etc.

to service specific messages from clients. </p> </li>

<li id="GUID-023BAF14-7588-5F25-B75C-8F1126D7749F"><p>The function <codeph>SetFromStringL()</codeph> needs

a string specified by the client and therefore needs to read data from the

client address space. </p> </li>

</ul> <p><b>ServiceL()</b> </p> <p>This

is implemented as follows: </p> <codeblock id="GUID-293D2833-3C1C-5B6E-AACF-B8EC20E0F7F9" xml:space="preserve">void CCountServSession::ServiceL(const RMessage2&amp; aMessage)

    {

    TRAPD(err,DispatchMessageL(aMessage));

    aMessage.Complete(err);

    }</codeblock> <p>After calling the appropriate service function via <codeph>DispatchMessageL()</codeph>,

the asynchronous request is completed with <codeph>aMessage.Complete()</codeph> which

passes the completion code back to the client. </p> <p><b>DispatchMessageL()</b> </p> <p>This is implemented as follows: </p> <codeblock id="GUID-14C3190C-921F-5C69-B0D0-7932C71B5ACF" xml:space="preserve">void CCountServSession::DispatchMessageL(const RMessage2&amp; 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;

        }

    }</codeblock> <p><b>IncreaseBy()</b> </p> <p>This message service function is implemented as follows: </p> <codeblock id="GUID-4516B089-F1D8-56BD-82CB-B7A1B0E98F0D" xml:space="preserve">void CCountServSession::IncreaseBy(const RMessage2&amp; aMessage)

    {

    iCount = iCount + aMessage.Int0(); 

    }</codeblock> <p>Note that we need to pass the message object to the function.

The <codeph>Int0()</codeph> 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. </p> <p><b>SetFromStringL()</b> </p> <p>This message service function is implemented

as follows: </p> <codeblock id="GUID-2BC55BC9-6AE1-5462-A6EE-6767F8EE19C7" xml:space="preserve">void CCountServSession::SetFromStringL(const RMessage2&amp; 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.</codeblock> <p> <codeph>RMessage::ReadL()</codeph> 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. </p> <p><b>CounterValue()</b> </p> <p>This is implemented as follows: </p> <codeblock id="GUID-9EE6666F-A4A7-5437-8AF1-CB0F8E2D6F0F" xml:space="preserve">void CCountServSession::CounterValue(const RMessage2&amp; aMessage)

    {

    TPckgBuf<TInt> p(iCount);

    aMessage.WriteL(0,p);

    }</codeblock> <p>It writes data back to a descriptor in the client address

space. The corresponding client request is: </p> <codeblock id="GUID-A772B781-18E8-5109-BB6F-8871F829A8B5" xml:space="preserve">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;

    }</codeblock> <p><b>Notes</b> </p> <ul>

<li id="GUID-EC003B28-3695-5B19-8074-54DB06B720B8"><p>The <codeph>TInt</codeph> is

packaged into a descriptor before being passed to the server. The packaging

mechanism is known as package buffer. </p> </li>

<li id="GUID-BB34EFC9-D238-509C-98C1-66BC64AA6EE2"><p>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 <codeph>aMessage.WriteL(0,p);</codeph> means that the argument referred

to is the first in the list passed across from the client side via the <codeph>TIpcArgs</codeph> object. </p> </li>

</ul> </section>