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