<?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-5B9DE39D-61D0-51FF-948E-15691CD673B5" xml:lang="en"><title>AdvancedClientServerExample:

Using Client/Server APIs</title><shortdesc>This example application demonstrates the use of client/server

APIs using a logical device driver (LDD) and a physical device driver (PDD).</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-4A6D20D7-F28D-49AD-AF44-96FA26ED867A"><title>Introduction</title> <p> This example implements asynchronous

as well as synchronous client requests to the server. This example also demonstrates

a client and server running in separate processes and a client and server

running in the same process. </p> <p>This example demonstrates the following: </p> <ul>

<li id="GUID-D4A42C17-F34C-5745-85A2-8FCCEB7B2EEA"><p> <b>a server running

its own process:</b> This is referred to in this document as the <i>process

server</i>. The example also implements a DLL that provides an API to allow

clients to request services from the process server. This client DLL is referred

to as the <i>process client</i>. </p> </li>

<li id="GUID-FB3B8745-BF31-5D0F-81AD-E04F23DBA188"><p> <b>a server and client

running in a single process:</b> These are referred to as the <i>thread server</i> and <i>thread

client</i>. </p> </li>

<li id="GUID-7582867D-1D14-5ECC-85B9-59F4A4E9E1EE"><p> <b>a shut down server:</b> This

terminates the process or thread server if it has no clients connected to

it for 50 seconds. </p> </li>

</ul> </section>

<section id="GUID-3A1715FE-3F34-44FB-826F-E441FD724D01"><title>Download</title><p><b>Process Client and Server</b></p><p>Click

the following links to download the example:</p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-76d97fc3-887f-495b-841a-3ae9de66dbf2.zip" scope="external"> ProcessClient.zip</xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-4b308120-fd3c-484f-bc1c-36cd2b99cc4e.zip" scope="external"> ProcessServer.zip</xref></p><p>Click the following links

for additional files: </p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-d98c1ba5-ea6d-4c8b-a1fc-a0c1a175d36c.zip" scope="external"> ProcessServerInc.zip</xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-f8dabf02-68a2-40d9-8667-84dfa6dfd2ba.zip" scope="external"> Common.zip</xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-b5fa4b2f-acec-47e3-a0d7-f9187923e7b9.zip" scope="external"> Driver.zip</xref></p><p>Click the following links to view

the example: </p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-76d97fc3-887f-495b-841a-3ae9de66dbf2.html" scope="peer"> browse ProcessClient </xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-4b308120-fd3c-484f-bc1c-36cd2b99cc4e.html" scope="peer"> browse ProcessServer </xref> </p><p>Click the following links

to view additional files: </p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-d98c1ba5-ea6d-4c8b-a1fc-a0c1a175d36c.html" scope="peer"> browse ProcessServerInc </xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-f8dabf02-68a2-40d9-8667-84dfa6dfd2ba.html" scope="peer"> browse Common </xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-b5fa4b2f-acec-47e3-a0d7-f9187923e7b9.html" scope="peer"> browse Driver </xref></p><p><b>Thread Client and Server</b></p><p>Click

the following links to download the example:</p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-fc40328d-eede-4c14-86f3-3691c3db13b7.zip" scope="external"> ThreadClient.zip </xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-81f8a0e6-2a4c-48b2-afeb-b385b4cdbb56.zip" scope="external"> ThreadServer.zip </xref></p><p>Click the following links

to download additional files:</p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-e61faf57-e35c-4951-ac16-d55954810ba1.zip" scope="external">ThreadServerInc.zip</xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-b5fa4b2f-acec-47e3-a0d7-f9187923e7b9.zip" scope="external"> Driver.zip</xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-98e2a1ec-8beb-4a7c-a731-309d28afe815.zip" scope="external"> CommonInc.zip</xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-f8dabf02-68a2-40d9-8667-84dfa6dfd2ba.zip" scope="external"> Common.zip</xref></p><p>Click the following links to view

the example: </p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-fc40328d-eede-4c14-86f3-3691c3db13b7.html" scope="peer">browse ThreadClient</xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-81f8a0e6-2a4c-48b2-afeb-b385b4cdbb56.html" scope="peer">browse ThreadServer</xref></p><p>Click the following links to

view additional files</p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-e61faf57-e35c-4951-ac16-d55954810ba1.html" scope="peer"> browse ThreadServerInc </xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-b5fa4b2f-acec-47e3-a0d7-f9187923e7b9.html" scope="peer"> browse Driver</xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-98e2a1ec-8beb-4a7c-a731-309d28afe815.html" scope="peer"> browse CommonInc</xref></p><p><xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-f8dabf02-68a2-40d9-8667-84dfa6dfd2ba.html" scope="peer"> browse Common</xref></p><p/> </section>

<section id="GUID-FE0D7810-DBE0-51BC-B0CF-31A6EF605072"><title>Directories</title> <p><b>common</b> </p> <p>This

directory contains code that is common to the process and thread servers.

It implements the shut down server which checks the number of connected clients

to the thread or process server. If this number is zero, then after a time

delay, the thread/process server is terminated. The server is not terminated

in the following cases: </p> <ul>

<li id="GUID-F896C125-5ADA-5514-944C-DD24DA81CD41"><p>if the client tries

to connect within the duration of the timer, then the shut down operation

is cancelled and the server handles the client's request to connect. </p> </li>

<li id="GUID-1A5D651C-50ED-5602-8274-7A73335904D2"><p>if the client tries

to connect after the timer has expired but before the server shut down process

has begun, then the process or thread server is stopped and restarted to handle

the client's request to connect. </p> </li>

</ul> <p><b>driver</b> </p> <p>Device drivers are DLLs that allow code to

communicate with hardware. For more information about device drivers, see

the <xref href="GUID-0437DB4C-FC4E-51DC-BB4C-95C0B26834F5.dita">Device Driver Guide</xref>. </p> <p id="GUID-A8A82766-6132-5C2B-A98F-52C016D21D68"><b>ProcessClient</b> </p> <p>This

directory implements a client DLL that starts the process server and creates

a session with it. The client DLL provides an API to allow clients to request

the server to load and unload the device driver. </p> <p id="GUID-52EF8BCD-FAD7-5DB8-9D93-2C6D76F0822A"><b>ProcessServer</b> </p> <p>This

directory implements the process server class <codeph>CProcessServer</codeph>,

which is derived from <xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita"><apiname>CServer2</apiname></xref>. It handles client requests

to interact with the device drivers. It can have multiple clients connected

at the same time. The device driver, server and client all have the <codeph>MultimediaDD</codeph> capability.

Note that this is for demonstration purposes rather than because the code

uses any Multimedia APIs. The session class <codeph>CProcessServerSession</codeph> implements

a simple message queue to hold asynchronous requests. </p> <p id="GUID-49CB48EE-8614-5595-BD22-4C9E3BCC6495"><b>ThreadClient</b> </p> <p>This

directory implements a client DLL that starts the thread server and creates

a session within it. The client DLL provides an API to allow clients to request

the server to load and unload the device driver. </p> <p id="GUID-7B61D8F8-E3D4-53E3-AC3D-AF0FD4E3E6A7"><b>ThreadServer</b> </p> <p>This

directory implements the thread server class <codeph>CThreadServer</codeph>,

which is derived from <xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita"><apiname>CServer2</apiname></xref>. An instance of the thread

server runs in the same process as the client. The thread server handles client

requests to interact with the device drivers. It can have multiple clients

connected at the same time. The session class <codeph>CThreadServerSession</codeph> implements

a simple message queue to hold asynchronous requests. </p> <p><b>test</b> </p> <p>This

example directory contains a comprehensive test suite to test the process

client and server and the thread client and server. </p> </section>

<section id="GUID-44822F1F-BC2C-4B6E-AA86-367A02310F08"><title>Class summary</title><p> <xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita"><apiname>CServer2 </apiname></xref><xref href="GUID-D5A30C75-E22C-34E8-913B-7D2CA6AD5C51.dita"><apiname>CSession2 </apiname></xref> <xref href="GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6.dita"><apiname>RSessionBase </apiname></xref>  <xref href="GUID-D7D422D3-65E5-378B-8F52-6485BC5603A0.dita"><apiname>RMessage2</apiname></xref> <xref href="GUID-78E0DEDD-C020-3174-AD0A-E4C18C4C9213.dita"><apiname>RMessagePtr2 </apiname></xref>  <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita"><apiname>RProcess </apiname></xref> <xref href="GUID-B0E661BC-4058-3256-B9C3-5A4FD52F6DE5.dita"><apiname>RThread </apiname></xref>  <xref href="GUID-6FBFA078-8253-3E24-B1F8-5F75E86C3066.dita"><apiname>RBusLogicalChannel </apiname></xref> <xref href="GUID-7616AA05-83E6-3989-AB9D-11AE01245BEB.dita"><apiname>DLogicalDevice</apiname></xref> <xref href="GUID-A3CC1D95-4681-3349-A67C-F113A614041D.dita"><apiname>DLogicalChannel </apiname></xref><xref href="GUID-A5484A7F-94B9-34C7-9F88-82B1BF516930.dita"><apiname> DPhysicalDevice</apiname></xref> </p></section>

<section id="GUID-E1571EF9-7E34-400C-A372-BB3D449E4081"><title>Build</title> <p>Build the development and test code using

the <codeph>abld build</codeph> command from <filepath>AdvancedClientServerExample\group</filepath> as

described in <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">the Symbian

OS build process</xref>. </p> <p>The <codeph>AdvancedClientServerExample</codeph> builds

the following binaries in the standard location (<filepath>\epoc32\release\winscw\&lt;build_variant&gt;</filepath> for

CodeWarrior): </p> <ul>

<li id="GUID-A78174BF-DBF9-5ED6-944F-FD8216B94567"><p><b><filepath>driver1_ldd.ldd</filepath>.</b>  </p> </li>

<li id="GUID-797DE4E5-10AE-5E9C-B040-94FAA639DAE3"><p> <b><filepath>driver1_pdd.pdd</filepath>.</b> </p> </li>

<li id="GUID-FB3FC150-AF7F-5FA8-84ED-1A51886BBDF3"><p> <b><filepath>processclient.dll</filepath>,<filepath>threadclient.dll</filepath> and <filepath>threadserver.dll</filepath>. </b>,\</p> </li>

<li id="GUID-1082E792-70D0-5656-AA39-696C42D09209"><p><b><filepath>processserver.exe</filepath>, <filepath>Te_ProcessClientServerTestSuite.exe</filepath> and <filepath>Te_ThreadClientServerTestSuite.exe</filepath>.</b> </p> </li>

</ul> <p>After launching the <b><filepath>Te_ProcessClientServerTestSuite.exe</filepath></b> or <b><filepath>Te_ThreadClientServerTestSuite.exe</filepath></b> executable, depending on the emulator you are using, you may have to

navigate away from the <b>application launcher/shell</b> screen to view the

console. </p> </section>

<section id="GUID-B233D2DE-D64F-422B-AB6E-E695B78450BA"><title>Running tests</title> <p>To run the tests, perform the following

steps: </p><ul>

<li><p>From the command prompt, change directory to <filepath>epoc32\release\winscw\udeb</filepath>.</p></li>

<li><p>Run the following command:</p> <p><userinput>epoc</userinput> </p></li>

<li><p>On the emulator, go to <codeph>eshell</codeph>. </p></li>

<li><p>Run the following commands: </p><p><userinput>testexecute c:\testdata\scripts\te_processclientservertestsuite.script</userinput> </p><p><userinput>testexecute c:\testdata\scripts\te_threadclientservertestsuite.script</userinput> </p><p> <b>Note:</b> Test

results are stored in the <filepath>epoc32\winscw\c\logs\testexecute</filepath> directory: </p></li>

<li id="GUID-42BC1D4A-6605-5BCF-BD74-BB153DA2E9BE"><p> <b> Process server

tests:</b> Refer to the <filepath>te_processclientservertestsuite.htm</filepath> file. </p> </li>

<li id="GUID-AB747CEC-9E1F-5F1C-9682-A2A4F877396D"><p> <b>Thread server tests:</b> Refer

to the <filepath>te_threadclientservertestsuite.htm</filepath> file. </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-3786D8E6-17A9-52E4-A8DF-CFCDC3039854.dita"><linktext>Inter Process

Communication</linktext></link>

<link href="GUID-0437DB4C-FC4E-51DC-BB4C-95C0B26834F5.dita"><linktext> Device Driver

Guide</linktext></link>

</related-links></concept>