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-9169062F-3B6D-544C-847C-BA859DAB33B9" xml:lang="en"><title>Sessions

    13 and requests</title><shortdesc>Describes communication between the client and the server in the

    14 client-server framework.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p>Communication between client and server is represented by a <i>session</i>;

    16 this is initiated by the client. A client thread may have several sessions

    17 with a server. A session can also be shared by all the client threads in a

    18 process, if supported by the server, and also by all threads across all processes,

    19 again if supported by the server. </p>

    20 <p>Sessions are maintained by the Kernel and the important points are: </p>

    21 <ul>

    22 <li id="GUID-C8D3B5F7-6BCE-5AB2-A11D-F0436F8CE20C"><p>The client has an <codeph>RSessionBase</codeph> handle

    23 to the session. </p> </li>

    24 <li id="GUID-80F84FC0-AA11-5C5E-A067-A23D6069DE00"><p>The server uses a <codeph>CSession2</codeph> -derived

    25 class to represent the session. </p> </li>

    26 <li id="GUID-B6405FDE-1ECB-543E-BA11-6280A5CD8DF8"><p>A session may be sharable

    27 between the threads in the client process, between all threads across all

    28 processes, or it can be restricted to the thread connecting to the server. </p> </li>

    29 </ul>

    30 <p>If a call to the client interface requires a service from the server, the

    31 client interface must set up and send a message. The message has a 32-bit

    32 operation code to identify the request, and up to four 32-bit parameters.

    33 The message is encapsulated within a <xref href="GUID-4AD02F14-1142-372F-9D11-224595932034.dita"><apiname>TIpcArgs</apiname></xref> object. The

    34 process can be summarised as follows: </p>

    35 <ul>

    36 <li id="GUID-2810FEA1-D51E-534E-963C-425D9A3B09C0"><p>The client sends the

    37 message to the server using <codeph>RSessionBase::SendReceive()</codeph>.

    38 This call eventually returns with the completion code. </p> </li>

    39 <li id="GUID-785468D3-7D69-5A2C-818D-5961DCCB7FCA"><p>The Kernel packages

    40 the operation code and parameters and delivers an <codeph>RMessage2</codeph> to

    41 the server. </p> </li>

    42 <li id="GUID-7BF7D799-7999-51C8-BEBF-88822703F113"><p>The server delivers

    43 the message to the appropriate <codeph>CSession2</codeph> object, which deals

    44 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>.

    45 This is defined as pure virtual in <codeph>CSession2</codeph>, and is implemented

    46 by the class derived from <codeph>CSession2</codeph>. When the session has

    47 finished dealing with the request, it calls <codeph>RMessage2::Complete()</codeph> to

    48 indicate that the service has been performed and to return a 32-bit result

    49 to the client - this is returned from the <codeph>SendReceive()</codeph>. </p> </li>

    50 </ul>

    51 <p>The client-server framework also supports the sending of requests asynchronously

    52 to the server. </p>

    53 <p>The following diagram illustrates this: </p>

    54 <fig id="GUID-97810C53-3BF6-5ECF-B413-86EEE99E68DA">

    55 <image href="GUID-08E31D57-A84D-5B6B-B16F-3F7025A763E9_d0e240610_href.png" placement="inline"/>

    56 <p>Sending messages asynchronously to the server</p>

    57 </fig>

    58 <p>A server can support multiple connections from a client in a number of

    59 distinct ways: </p>

    60 <ul>

    61 <li id="GUID-DFBDEB83-48DE-5A94-A07B-B9BA1715FDE7"><p>The client may have

    62 a number of concurrent sessions with a particular server. </p> </li>

    63 <li id="GUID-C382BBE4-A94B-593E-9C9E-1E2E4DA60587"><p>Each session is independent

    64 of any other within the client thread; <codeph>Connect()</codeph> must be

    65 called to initialise each new connection. </p> </li>

    66 <li id="GUID-343295A2-AAE6-51AA-AFCF-5CD3CD39A510"><p>The client may create

    67 a number of <i>subsessions</i> within a single session. </p> </li>

    68 <li id="GUID-7228AA13-B73F-5996-8535-0C959B7C7788"><p>Each <i>client subsession </i> corresponds

    69 to a <i>subsession object</i> in the server. The client subsession contains

    70 a handle to this subsession object. All communication is via the owning session;

    71 the handle is used to match up corresponding client subsessions and subsession

    72 objects. </p> </li>

    73 <li id="GUID-8D01708B-CCC3-5B6C-9C26-4A4BE26A3D0C"><p>Subsessions use fewer

    74 Kernel resources than sessions, although they are slightly more complex to

    75 use. </p> </li>

    76 </ul>

    77 <p>A server can support the creation of sharable sessions allowing either

    78 all the threads in a client process to share a single session, or allowing

    79 all threads across all processes to share a single session. The important

    80 points are: </p>

    81 <ul>

    82 <li id="GUID-81929E38-1251-51C9-A3B0-CD82AD519D82"><p>The server must support

    83 the sharing of sessions. </p> </li>

    84 <li id="GUID-AE8DF750-FABF-55CE-A633-41E96A50413B"><p>The connecting thread

    85 can make the session sharable after creation, or it can create the session

    86 as sharable. </p> </li>

    87 <li id="GUID-E1962030-B977-5A90-AC3C-5419C2FAAF68"><p>Up to 255 threads can

    88 be concurrently attached to a session. </p> </li>

    89 </ul>

    90 <section id="GUID-8C971096-BD4A-408A-AF20-15810FAB9D4C"><title>See also</title> <p> <xref href="GUID-1CC6FEF0-7D1E-5329-8276-22ACFE3DE362.dita">Subsessions

    91 within a session</xref>  </p> </section>

    92 </conbody></concept>