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