<?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>. </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>