<?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-A30C1204-F130-501E-BD2D-1EE1537BEFC3" xml:lang="en"><title>How

to implement a client interface with subsessions</title><shortdesc>Provides code snippets to help you to implement a

client interface with subsessions.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>A client side subsession is represented by an instance of a class derived

from <codeph>RSubSessionBase</codeph> which provides the behaviour for: </p>

<ul>

<li id="GUID-E82084CE-E5AF-56D8-934C-A183809532A2"><p>creating a subsession

in the server </p> </li>

<li id="GUID-F810EEC0-E0B1-52F1-9587-72BB41AD54C0"><p>sending messages to

the subsession. </p> </li>

</ul>

<p>In the following code fragment, taken from the example that can be found

at <filepath>...\examples\Base\IPC\ClientServer\complex</filepath>, the class <codeph>RCountSubSession</codeph>,

derived from <codeph>RSubSessionBase</codeph>, represents the client side

subsession with a server (in the example the server is also referred to as

the count server). The assumption is made that the client has already established

a session with the server as represented by the <codeph>RCountSession</codeph> class. </p>

<codeblock id="GUID-C9F043AD-A44B-5EC8-9ED4-932747EB6C9B" xml:space="preserve">class RCountSubSession : public RSubSessionBase

    {

public:

    TInt Open(RCountSession& aServer);

    TInt SetFromString(const TDesC& aString);

    void Close();

    void Increase();

    void Decrease();

    void IncreaseBy(TInt anInt);

    void DecreaseBy(TInt anInt);

    void Reset();

    TInt CounterValue();

    };

</codeblock>

<codeblock id="GUID-7CE73750-213F-56EF-AEE5-04125147F934" xml:space="preserve">class RCountSession : public RSessionBase

    {

public:

    RCountSession();

    TInt Connect();

    TVersion Version() const;

    TInt ResourceCount();

    void Close();

private:

    RThread iServerThread;    

    };</codeblock>

<p>The important points in this example are: </p>

<ul>

<li id="GUID-AC212539-94D5-515D-991A-1D9E2D756922"><p> <codeph>Open()</codeph> creates

a subsession within the client-side session. A reference to the client-side

session is specified as the function's single argument. The function calls <codeph>RSubSessionBase::CreateSubSession()</codeph> which,

in turn, causes a server side subsession object to be created and its handle

number to be returned. </p> </li>

<li id="GUID-3762EF2B-D88B-5F8A-A0CD-C9D83ACEC208"><p>Client subsession interface

functions, such as <codeph>CounterValue()</codeph>, send a specific message

to the server. </p> <codeblock id="GUID-ABFAD354-7632-5FF5-A721-C95B0B8D29AD" xml:space="preserve">TInt RCountSubSession::CounterValue()

    {

    TInt res = KErrNotFound;

    TPckgBuf<TInt> pckg;

    if (SubSessionHandle())

        {

          // 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> </li>

</ul>

<ul>

<li id="GUID-64C2EC87-84BF-5892-AD04-40B8DDC0DEA0"><p> <codeph>Close()</codeph> closes

the subsession. </p> </li>

</ul>

<section id="GUID-5E96565F-8D14-43AB-80A0-F6FD558F0073"><title>Notes</title> <ul>

<li id="GUID-49CCA864-57FD-5E28-8890-F2A1CE707428"><p>The operation code passed

to <codeph>RSubSessionBase::CreateSubSession()</codeph> must be interpreted

by the server as a request to create a subsession. </p> </li>

<li id="GUID-8F920E77-7FFF-5591-87A7-40BFE75A7649"><p>When sending a message

to the server with a call to <codeph>RSubSessionBase::SendReceive()</codeph>,

only three arguments can be passed . This function always uses the fourth

argument to hold the client subsession handle number which is used to identify

the corresponding server side subsession object. The message arguments are

subsequently passed to a call to <codeph>RSessionBase::SendReceive()</codeph>. </p> </li>

<li id="GUID-C690D49E-F5F0-5B71-BE11-5461556FF3A0"><p>The operation code passed

to <codeph>RSubSessionBase::CloseSubSession()</codeph> must be interpreted

by the server as a request to close the subsession. </p> </li>

</ul> </section>