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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <concept id="GUID-1CC6FEF0-7D1E-5329-8276-22ACFE3DE362" xml:lang="en"><title>Subsessions

    13 within a session</title><shortdesc>Describes subsessions within a session.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>Once a client has established a session with a server, it can then establish

    15 a number of subsessions with that server. Each subsession represents an independent

    16 channel of communication within the current session. </p>

    17 <p>Subsessions are useful if a single client needs to establish many channels

    18 of communication with the server. This is because subsessions have a much

    19 lower overhead than a full session. The main cost of a subsession is slightly

    20 increased programming complexity on the server side. </p>

    21 <p>The main points are: </p>

    22 <ul>

    23 <li id="GUID-66581D72-861A-5F70-B3F3-348C31615EA5"><p>the client has an <xref href="GUID-1BBE1448-1DF8-33C4-BF9E-5A5F427AEE35.dita"><apiname>RSubSessionBase</apiname></xref> handle

    24 to the subsession </p> </li>

    25 <li id="GUID-7EEEB011-CB41-5E20-BF91-C6D01B4F71EE"><p>the server uses a <xref href="GUID-9230EF62-376A-389C-B720-7C1EDCB7EA97.dita"><apiname>CObject</apiname></xref> derived

    26 class to represent the subsession. </p> </li>

    27 </ul>

    28 <p>As a subsession is always referenced by a handle on the client side, the

    29 corresponding subsession object on the server side must generate a handle. </p>

    30 <p>For ordinary sessions, the generation of handles is done by the server

    31 framework. </p>

    32 <p>For subsessions, server side code must be explicitly written to do this.

    33 The <codeph>CObject</codeph> class and its associated container (<codeph>CObjectCon</codeph>)

    34 and index (<codeph>CObjectIx</codeph>) classes provide the behaviour to achieve

    35 this. </p>

    36 <section id="GUID-4F58EC0B-5AC3-4961-B04F-2CE64185ECEF"><title>Server side requirements</title> <p>Each subsession is represented

    37 by an instance of a <codeph>CObject</codeph> derived class. </p> <p>Subsession

    38 objects must be held in an object container, an instance of <codeph>CObjectCon</codeph>.

    39 This means that the server 's <codeph>CServer2</codeph> derived class must

    40 construct and maintain a <codeph>CObjectCon</codeph> object. </p> <p>Object

    41 containers are constructed by and held in an object container index, an instance

    42 of a <codeph>CObjectConIx</codeph>. This means that the server 's <codeph>CServer2</codeph> derived

    43 class must construct and maintain a <codeph>CObjectConIx</codeph> object. </p> <p>A

    44 unique handle number for a subsession object is generated when the subsession

    45 object is added to an object index, an instance of a <codeph>CObjectIx</codeph>.

    46 This means that the server's <codeph>CServer2</codeph> derived class must

    47 construct and maintain a <codeph>CObjectIx</codeph> object. </p> <p>The handle

    48 number is a combination of a unique id assigned to the object's container

    49 and a number generated by the object index. </p> <fig id="GUID-14035881-8AD5-50B5-A285-5DD2D7E68FDA">

    50 <image href="GUID-A10EAF58-6B9F-55A5-B3E4-3D4B91A93C41_d0e240942_href.png" placement="inline"/>

    51 <p>Subsession within a session</p>

    52 </fig> </section>

    53 <section id="GUID-93D80DDA-8E2E-462F-8A67-0982B456A8A6"><title>Note</title> <ul>

    54 <li id="GUID-49B41D98-027F-534F-86D7-3774CAC884F9"><p>Depending on the purpose

    55 of the server, more than one object container (a <codeph>CObjectCon</codeph>)

    56 and more than one object index (a <codeph>CObjectIx</codeph>) may be used.

    57 However, the server must have <i>one and only one</i> object container index

    58 (a <codeph>CObjectConIx</codeph>) from which all object containers are generated. </p> </li>

    59 </ul> </section>

    60 </conbody></concept>