<?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-D0D27AEA-FDDB-5F6F-94F6-ADDF5910DC47" xml:lang="en"><title>Client/Server

Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-CA831E24-1BE6-4D18-889A-CD78364828C9"><title>Purpose</title> <p>Provides the Symbian platform client/server

framework, by which a program can offer services to multiple other programs.

Servers also handle resources on behalf of multiple clients.</p> <p>All Symbian

platform developers should have a general understanding of this API in order

to understand the design of many Symbian platform system APIs. In specialized

circumstances, developers may also create their own server programs.</p> </section>

<section id="GUID-539EF180-E0B7-4931-B1DC-BA7801D54F9F"><title>Architectural relationships</title> <p>Many important Symbian

platform system APIs use the client/server framework to provide services to

client programs: for example, the Windows Server, File Server, and Messaging.

In some cases, such APIs provide extensive client-side classes that hide the

direct use of the client/server interface from the client program.</p> </section>

<section id="GUID-8163FC8D-F044-46D5-8806-13C8F22677A1"><title>Description</title> <p>The API has four key concepts: server

(<codeph>CServer2</codeph>), session (<codeph>CSession2</codeph> and <codeph>RSessionBase</codeph>),

sub-session (<codeph>RSubSessionBase</codeph>), and message (<codeph>RMessage2</codeph>,

and <codeph>RMessagePtr2</codeph>). </p> <p><b>General

properties</b> </p> <p>A server program offers services to other processes

through a client interface API that it defines. Clients and servers use a

message passing protocol to communicate.</p> <p>Client/server is usually chosen,

rather than a conventional shared library, to provide services when one or

more of the following is required:</p> <ul>

<li id="GUID-7083F154-725B-5133-8391-41BBA67341E9"><p>management of shared

system resource</p> </li>

<li id="GUID-5C655C17-036C-50CD-BEE6-45C1A261FEC3"><p>asynchronous services</p> </li>

<li id="GUID-AD3A0E0E-A4EB-5F50-8F9E-A906591839A6"><p>the protection offered

by running in a separate process from clients.</p> </li>

</ul> <p>A client/server implementation supplies a server program executable,

and a <filepath>.DLL</filepath> containing the client-side interface.</p> <p><b>Server</b> </p> <p>The server is the central class of any server program.

It is responsible for handling requests by clients to establish a connection

to the server. </p> <p>The base server interface is provided by <xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita"><apiname>CServer2</apiname></xref>.</p> <p><b>Session</b> </p> <p>The session is the channel of communication between

a client and a server. </p> <p>The base client-side session interface is provided

by <xref href="GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6.dita"><apiname>RSessionBase</apiname></xref>. An implementation derives from this to

define the functions that it wants to expose to clients.</p> <p>The corresponding

server-side session base classes is <xref href="GUID-D5A30C75-E22C-34E8-913B-7D2CA6AD5C51.dita"><apiname>CSession2</apiname></xref>. A session

can be shared between different client threads if the server marks the session

as sharable. An implementation defines in a derived class how client messages

should be handled.</p> <p><b>Sub-session</b> </p> <p>The sub-session presents an efficient refinement of a session where a

client wants multiple simultaneous uses of a server. For example, with the

File Server, each opened file is handled through a separate sub-session.</p> <p>The

base client-side sub-session interface is provided by <xref href="GUID-1BBE1448-1DF8-33C4-BF9E-5A5F427AEE35.dita"><apiname>RSubSessionBase</apiname></xref>.

An implementation derives from this to define the functions that it wants

to expose to clients.</p> <p>A server implements a corresponding sub-session

class based on <xref href="GUID-9230EF62-376A-389C-B720-7C1EDCB7EA97.dita"><apiname>CObject</apiname></xref>, <xref href="GUID-DE901A59-C714-356A-9490-C4E9C9F186DB.dita"><apiname>CObjectCon</apiname></xref> and <xref href="GUID-70824EE4-9E01-3AC0-9318-4B521A1FDD5E.dita"><apiname>CObjectIx</apiname></xref>,

the Reference Counting Objects API.</p> <p><b>Message</b> </p> <p>The message is the information passed between client and server.

It consists of a code that identifies the type of request that the client

is making, and up to four 32-bit data arguments together with information

about each argument's type, width and accessibility. It is also possible to

pass just the code, with no arguments.</p> <p>Clients do not use messages

directly; they use a <xref href="GUID-4AD02F14-1142-372F-9D11-224595932034.dita"><apiname>TIpcArgs</apiname></xref> object to package the message

information that is to be sent to the server.</p> <p>Server-side sessions

and subsessions access this information through an <xref href="GUID-D7D422D3-65E5-378B-8F52-6485BC5603A0.dita"><apiname>RMessage2</apiname></xref> object. </p> </section>

<section id="GUID-74655E18-CC4C-4432-A8F3-BADFCA5CB7D2"><title>See also</title> <p><xref href="GUID-E189B0C0-AAB5-5472-996B-91043DE0B6D4.dita">Package

Buffers Overview</xref> </p> <p><xref href="GUID-BE0C94BE-94F0-54B3-8674-366C09261E5D.dita">Reference

Counting Objects Overview</xref> </p> <p><xref href="GUID-547CF71C-6A62-57C0-A9BE-E76B4286C6D6.dita">Threads

And Processes Overview</xref> </p> </section>