<?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-9169062F-3B6D-544C-847C-BA859DAB33B9" xml:lang="en"><title>Sessions
and requests</title><shortdesc>Describes communication between the client and the server in the
client-server framework.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>Communication between client and server is represented by a <i>session</i>;
this is initiated by the client. A client thread may have several sessions
with a server. A session can also be shared by all the client threads in a
process, if supported by the server, and also by all threads across all processes,
again if supported by the server. </p>
<p>Sessions are maintained by the Kernel and the important points are: </p>
<ul>
<li id="GUID-C8D3B5F7-6BCE-5AB2-A11D-F0436F8CE20C"><p>The client has an <codeph>RSessionBase</codeph> handle
to the session. </p> </li>
<li id="GUID-80F84FC0-AA11-5C5E-A067-A23D6069DE00"><p>The server uses a <codeph>CSession2</codeph> -derived
class to represent the session. </p> </li>
<li id="GUID-B6405FDE-1ECB-543E-BA11-6280A5CD8DF8"><p>A session may be sharable
between the threads in the client process, between all threads across all
processes, or it can be restricted to the thread connecting to the server. </p> </li>
</ul>
<p>If a call to the client interface requires a service from the server, the
client interface must set up and send a message. The message has a 32-bit
operation code to identify the request, and up to four 32-bit parameters.
The message is encapsulated within a <xref href="GUID-4AD02F14-1142-372F-9D11-224595932034.dita"><apiname>TIpcArgs</apiname></xref> object. The
process can be summarised as follows: </p>
<ul>
<li id="GUID-2810FEA1-D51E-534E-963C-425D9A3B09C0"><p>The client sends the
message to the server using <codeph>RSessionBase::SendReceive()</codeph>.
This call eventually returns with the completion code. </p> </li>
<li id="GUID-785468D3-7D69-5A2C-818D-5961DCCB7FCA"><p>The Kernel packages
the operation code and parameters and delivers an <codeph>RMessage2</codeph> to
the server. </p> </li>
<li id="GUID-7BF7D799-7999-51C8-BEBF-88822703F113"><p>The server delivers
the message to the appropriate <codeph>CSession2</codeph> object, which deals
with the request. The request is handled by <xref href="GUID-D5A30C75-E22C-34E8-913B-7D2CA6AD5C51.dita#GUID-D5A30C75-E22C-34E8-913B-7D2CA6AD5C51/GUID-B37413F7-D8FD-35AD-A037-99023D7CE986"><apiname>CSession2::ServiceL()</apiname></xref>.
This is defined as pure virtual in <codeph>CSession2</codeph>, and is implemented
by the class derived from <codeph>CSession2</codeph>. When the session has
finished dealing with the request, it calls <codeph>RMessage2::Complete()</codeph> to
indicate that the service has been performed and to return a 32-bit result
to the client - this is returned from the <codeph>SendReceive()</codeph>. </p> </li>
</ul>
<p>The client-server framework also supports the sending of requests asynchronously
to the server. </p>
<p>The following diagram illustrates this: </p>
<fig id="GUID-97810C53-3BF6-5ECF-B413-86EEE99E68DA">
<image href="GUID-08E31D57-A84D-5B6B-B16F-3F7025A763E9_d0e241853_href.png" placement="inline"/>
<p>Sending messages asynchronously to the server</p>
</fig>
<p>A server can support multiple connections from a client in a number of
distinct ways: </p>
<ul>
<li id="GUID-DFBDEB83-48DE-5A94-A07B-B9BA1715FDE7"><p>The client may have
a number of concurrent sessions with a particular server. </p> </li>
<li id="GUID-C382BBE4-A94B-593E-9C9E-1E2E4DA60587"><p>Each session is independent
of any other within the client thread; <codeph>Connect()</codeph> must be
called to initialise each new connection. </p> </li>
<li id="GUID-343295A2-AAE6-51AA-AFCF-5CD3CD39A510"><p>The client may create
a number of <i>subsessions</i> within a single session. </p> </li>
<li id="GUID-7228AA13-B73F-5996-8535-0C959B7C7788"><p>Each <i>client subsession </i> corresponds
to a <i>subsession object</i> in the server. The client subsession contains
a handle to this subsession object. All communication is via the owning session;
the handle is used to match up corresponding client subsessions and subsession
objects. </p> </li>
<li id="GUID-8D01708B-CCC3-5B6C-9C26-4A4BE26A3D0C"><p>Subsessions use fewer
Kernel resources than sessions, although they are slightly more complex to
use. </p> </li>
</ul>
<p>A server can support the creation of sharable sessions allowing either
all the threads in a client process to share a single session, or allowing
all threads across all processes to share a single session. The important
points are: </p>
<ul>
<li id="GUID-81929E38-1251-51C9-A3B0-CD82AD519D82"><p>The server must support
the sharing of sessions. </p> </li>
<li id="GUID-AE8DF750-FABF-55CE-A633-41E96A50413B"><p>The connecting thread
can make the session sharable after creation, or it can create the session
as sharable. </p> </li>
<li id="GUID-E1962030-B977-5A90-AC3C-5419C2FAAF68"><p>Up to 255 threads can
be concurrently attached to a session. </p> </li>
</ul>
<section id="GUID-8C971096-BD4A-408A-AF20-15810FAB9D4C"><title>See also</title> <p> <xref href="GUID-1CC6FEF0-7D1E-5329-8276-22ACFE3DE362.dita">Subsessions
within a session</xref>  </p> </section>
</conbody></concept>