|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-5B9DE39D-61D0-51FF-948E-15691CD673B5" xml:lang="en"><title>AdvancedClientServerExample: |
|
13 Using Client/Server APIs</title><shortdesc>This example application demonstrates the use of client/server |
|
14 APIs using a logical device driver (LDD) and a physical device driver (PDD).</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section id="GUID-4A6D20D7-F28D-49AD-AF44-96FA26ED867A"><title>Introduction</title> <p> This example implements asynchronous |
|
16 as well as synchronous client requests to the server. This example also demonstrates |
|
17 a client and server running in separate processes and a client and server |
|
18 running in the same process. </p> <p>This example demonstrates the following: </p> <ul> |
|
19 <li id="GUID-D4A42C17-F34C-5745-85A2-8FCCEB7B2EEA"><p> <b>a server running |
|
20 its own process:</b> This is referred to in this document as the <i>process |
|
21 server</i>. The example also implements a DLL that provides an API to allow |
|
22 clients to request services from the process server. This client DLL is referred |
|
23 to as the <i>process client</i>. </p> </li> |
|
24 <li id="GUID-FB3B8745-BF31-5D0F-81AD-E04F23DBA188"><p> <b>a server and client |
|
25 running in a single process:</b> These are referred to as the <i>thread server</i> and <i>thread |
|
26 client</i>. </p> </li> |
|
27 <li id="GUID-7582867D-1D14-5ECC-85B9-59F4A4E9E1EE"><p> <b>a shut down server:</b> This |
|
28 terminates the process or thread server if it has no clients connected to |
|
29 it for 50 seconds. </p> </li> |
|
30 </ul> </section> |
|
31 <section id="GUID-3A1715FE-3F34-44FB-826F-E441FD724D01"><title>Download</title><p><b>Process Client and Server</b></p><p>Click |
|
32 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 |
|
33 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 |
|
34 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 |
|
35 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 |
|
36 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 |
|
37 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 |
|
38 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 |
|
39 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> |
|
40 <section id="GUID-FE0D7810-DBE0-51BC-B0CF-31A6EF605072"><title>Directories</title> <p><b>common</b> </p> <p>This |
|
41 directory contains code that is common to the process and thread servers. |
|
42 It implements the shut down server which checks the number of connected clients |
|
43 to the thread or process server. If this number is zero, then after a time |
|
44 delay, the thread/process server is terminated. The server is not terminated |
|
45 in the following cases: </p> <ul> |
|
46 <li id="GUID-F896C125-5ADA-5514-944C-DD24DA81CD41"><p>if the client tries |
|
47 to connect within the duration of the timer, then the shut down operation |
|
48 is cancelled and the server handles the client's request to connect. </p> </li> |
|
49 <li id="GUID-1A5D651C-50ED-5602-8274-7A73335904D2"><p>if the client tries |
|
50 to connect after the timer has expired but before the server shut down process |
|
51 has begun, then the process or thread server is stopped and restarted to handle |
|
52 the client's request to connect. </p> </li> |
|
53 </ul> <p><b>driver</b> </p> <p>Device drivers are DLLs that allow code to |
|
54 communicate with hardware. For more information about device drivers, see |
|
55 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 |
|
56 directory implements a client DLL that starts the process server and creates |
|
57 a session with it. The client DLL provides an API to allow clients to request |
|
58 the server to load and unload the device driver. </p> <p id="GUID-52EF8BCD-FAD7-5DB8-9D93-2C6D76F0822A"><b>ProcessServer</b> </p> <p>This |
|
59 directory implements the process server class <codeph>CProcessServer</codeph>, |
|
60 which is derived from <xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita"><apiname>CServer2</apiname></xref>. It handles client requests |
|
61 to interact with the device drivers. It can have multiple clients connected |
|
62 at the same time. The device driver, server and client all have the <codeph>MultimediaDD</codeph> capability. |
|
63 Note that this is for demonstration purposes rather than because the code |
|
64 uses any Multimedia APIs. The session class <codeph>CProcessServerSession</codeph> implements |
|
65 a simple message queue to hold asynchronous requests. </p> <p id="GUID-49CB48EE-8614-5595-BD22-4C9E3BCC6495"><b>ThreadClient</b> </p> <p>This |
|
66 directory implements a client DLL that starts the thread server and creates |
|
67 a session within it. The client DLL provides an API to allow clients to request |
|
68 the server to load and unload the device driver. </p> <p id="GUID-7B61D8F8-E3D4-53E3-AC3D-AF0FD4E3E6A7"><b>ThreadServer</b> </p> <p>This |
|
69 directory implements the thread server class <codeph>CThreadServer</codeph>, |
|
70 which is derived from <xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita"><apiname>CServer2</apiname></xref>. An instance of the thread |
|
71 server runs in the same process as the client. The thread server handles client |
|
72 requests to interact with the device drivers. It can have multiple clients |
|
73 connected at the same time. The session class <codeph>CThreadServerSession</codeph> implements |
|
74 a simple message queue to hold asynchronous requests. </p> <p><b>test</b> </p> <p>This |
|
75 example directory contains a comprehensive test suite to test the process |
|
76 client and server and the thread client and server. </p> </section> |
|
77 <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> |
|
78 <section id="GUID-E1571EF9-7E34-400C-A372-BB3D449E4081"><title>Build</title> <p>Build the development and test code using |
|
79 the <codeph>abld build</codeph> command from <filepath>AdvancedClientServerExample\group</filepath> as |
|
80 described in <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">the Symbian |
|
81 OS build process</xref>. </p> <p>The <codeph>AdvancedClientServerExample</codeph> builds |
|
82 the following binaries in the standard location (<filepath>\epoc32\release\winscw\<build_variant></filepath> for |
|
83 CodeWarrior): </p> <ul> |
|
84 <li id="GUID-A78174BF-DBF9-5ED6-944F-FD8216B94567"><p><b><filepath>driver1_ldd.ldd</filepath>.</b> </p> </li> |
|
85 <li id="GUID-797DE4E5-10AE-5E9C-B040-94FAA639DAE3"><p> <b><filepath>driver1_pdd.pdd</filepath>.</b> </p> </li> |
|
86 <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> |
|
87 <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> |
|
88 </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 |
|
89 navigate away from the <b>application launcher/shell</b> screen to view the |
|
90 console. </p> </section> |
|
91 <section id="GUID-B233D2DE-D64F-422B-AB6E-E695B78450BA"><title>Running tests</title> <p>To run the tests, perform the following |
|
92 steps: </p><ul> |
|
93 <li><p>From the command prompt, change directory to <filepath>epoc32\release\winscw\udeb</filepath>.</p></li> |
|
94 <li><p>Run the following command:</p> <p><userinput>epoc</userinput> </p></li> |
|
95 <li><p>On the emulator, go to <codeph>eshell</codeph>. </p></li> |
|
96 <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 |
|
97 results are stored in the <filepath>epoc32\winscw\c\logs\testexecute</filepath> directory: </p></li> |
|
98 <li id="GUID-42BC1D4A-6605-5BCF-BD74-BB153DA2E9BE"><p> <b> Process server |
|
99 tests:</b> Refer to the <filepath>te_processclientservertestsuite.htm</filepath> file. </p> </li> |
|
100 <li id="GUID-AB747CEC-9E1F-5F1C-9682-A2A4F877396D"><p> <b>Thread server tests:</b> Refer |
|
101 to the <filepath>te_threadclientservertestsuite.htm</filepath> file. </p> </li> |
|
102 </ul> </section> |
|
103 </conbody><related-links> |
|
104 <link href="GUID-3786D8E6-17A9-52E4-A8DF-CFCDC3039854.dita"><linktext>Inter Process |
|
105 Communication</linktext></link> |
|
106 <link href="GUID-0437DB4C-FC4E-51DC-BB4C-95C0B26834F5.dita"><linktext> Device Driver |
|
107 Guide</linktext></link> |
|
108 </related-links></concept> |