<?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-1CC6FEF0-7D1E-5329-8276-22ACFE3DE362" xml:lang="en"><title>Subsessions

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

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

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

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

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

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

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

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

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

<ul>

<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

to the subsession </p> </li>

<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

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

</ul>

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

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

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

framework. </p>

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

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

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

this. </p>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<p>Subsession within a session</p>

</fig> </section>

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

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

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

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

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

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

</ul> </section>