|
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 reference |
|
11 PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> |
|
12 <reference id="GUID-C1612638-4C5A-5C37-AF1A-16F9EBEF09FD" xml:lang="en"><title>transient: |
|
13 transient server example</title><shortdesc>This example demonstrates the use of transient servers that are |
|
14 started on demand when a client needs to use the server, and exit after the |
|
15 last client has disconnected, sometimes after a short delay. It demonstrates |
|
16 how to handle startup and shutdown situations correctly. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody> |
|
17 <section id="GUID-BF4C4CB4-D495-49D6-8035-F8BA724851B7"><title>Class summary</title><ul> |
|
18 <li><p><xref href="GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6.dita"><apiname>RSessionBase</apiname></xref> - Client-side handle to a session with |
|
19 a server.</p></li> |
|
20 <li><p><xref href="GUID-5733DF34-5B54-3044-BBED-3BFECB7ACE7A.dita"><apiname>CTimer</apiname></xref> - Base class for a timer active object.</p></li> |
|
21 <li><p><xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita"><apiname>CServer2</apiname></xref> - Abstract base class for servers (version |
|
22 2).</p></li> |
|
23 <li><p><xref href="GUID-D5A30C75-E22C-34E8-913B-7D2CA6AD5C51.dita"><apiname>CSession2</apiname></xref> - Represents a session (version 2) for |
|
24 a client thread on the server-side.</p></li> |
|
25 </ul></section> |
|
26 <section id="GUID-E688F8C0-0A4A-4D25-B7B4-779CB6A08157"><title>Download</title> <p>Click |
|
27 on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-cbf7e18e-3788-4ec1-a225-268ce1a22c51.zip" scope="external">transient.zip</xref></p><p>click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-cbf7e18e-3788-4ec1-a225-268ce1a22c51.html" scope="peer">browse</xref> to view the example code.</p> </section> |
|
28 <section id="GUID-87B18963-ACE8-464B-9863-A37ADA57379C"><title>Background</title> <p>The |
|
29 client-server framework is an important part of the Symbian platform. There |
|
30 is a level of complexity in implementing a server for an application, but |
|
31 this example provides client interface code and server code that can be re-used |
|
32 in your own implementations. </p> <p>Symbian platform servers are of three |
|
33 basic types: </p> <ul> |
|
34 <li id="GUID-6D0F8C69-CFEA-5BB1-A0CB-C4D178DFAE25"><p> <b>Transient servers:</b> these |
|
35 are started on demand when a client needs the server, and exit after the last |
|
36 client has disconnected - sometimes after a short delay, for example, the |
|
37 socket server. </p> </li> |
|
38 <li id="GUID-5B824584-C8E6-57F7-A83C-564DA256F622"><p> <b>System servers:</b> these |
|
39 are started as part of the system boot process, for example, the kernel, the |
|
40 file server, the window server etc. </p> </li> |
|
41 <li id="GUID-9BE0FD09-B112-5AF6-A5D1-FBDD6A4EC00B"><p> <b>Local servers:</b> these |
|
42 are "local" to a process to provide multi-threaded access to thread-specific |
|
43 resources, for example, the posix server (in the C Standard Library). </p> </li> |
|
44 </ul> </section> |
|
45 <section id="GUID-EEA0A38B-F8A6-4308-A50D-B3E74B12420A"><title>Description</title> <p>The |
|
46 transient server supplied here runs in a thread in its own process. This gives |
|
47 the server independence from its clients. This is important because if the |
|
48 client were to create the server as a separate thread within its own process, |
|
49 then the server would exit, i.e. terminate, if its owning process terminated. |
|
50 This would be true even if clients in other processes were still connected |
|
51 to it. </p> <p>Equally as important: </p> <ul> |
|
52 <li id="GUID-432FCF7B-2393-5E59-BDE5-0A5B4BAFD155"><p>a client does not explicitly |
|
53 need to start the server prior to connecting; this is done by the client interface. </p> </li> |
|
54 <li id="GUID-D89C8F48-2CA2-5769-8DB9-42FD8FFA5879"><p>the server terminates |
|
55 when not in use shortly after the last client disconnects. </p> </li> |
|
56 <li id="GUID-968AB243-908B-5709-BB82-4213860CBC8A"><p>the code handles concurrency |
|
57 issues, the most common of which is handling the case where the server is |
|
58 closing down or exiting at the same time that another client is trying to |
|
59 connect. </p> </li> |
|
60 </ul> <p>The example consists of four main parts: </p> <ul> |
|
61 <li id="GUID-BC6A15E0-07CB-562C-99E8-0AAF39B0ED26"><p>Client interface: this |
|
62 is a DLL (<filepath>t-client.dll</filepath>) that is used by clients. </p> <p>The |
|
63 client interface effectively forms the gateway to the server. All requests |
|
64 to the server, including requests to connect to it are routed through this. </p> <p>The |
|
65 client interface defines just one class: <codeph>RMySession</codeph>, derived |
|
66 from <xref href="GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6.dita"><apiname>RSessionBase</apiname></xref>. An <codeph>RSessionBase</codeph> (derived) |
|
67 object represents the client side session and forms a channel of communication |
|
68 between the client and the server. Requests to the server, and information |
|
69 received from the server are channelled through this object. Note that the |
|
70 client side session object is mirrored by a server side session object; an |
|
71 instance of a class derived from <xref href="GUID-D5A30C75-E22C-34E8-913B-7D2CA6AD5C51.dita"><apiname>CSession2</apiname></xref>, which in this |
|
72 server is called <codeph>CMySession</codeph>. </p> <p>The client calls <codeph>Connect()</codeph> to |
|
73 set up a connection to the server. This function attempts to start the server |
|
74 if necessary and then issues a request to create a session with the server. |
|
75 If the server fails to start, or a session cannot be created then this is |
|
76 reported back.Simultaneous launching of two server processes is also detected, |
|
77 with the second attempt failing with <xref href="GUID-D1D25122-F2B8-3C78-8599-84905BFD47B8.dita"><apiname>KErrAlreadyExists</apiname></xref>. |
|
78 On successful completion the connection is established, and a session is created |
|
79 with the server. </p> <p>The client uses the <codeph>Send()</codeph> method |
|
80 to send messages to the server and the <codeph>Receive()</codeph> method to |
|
81 request information from the server. <codeph>Send()</codeph> is implemented |
|
82 by calling down to the synchronous variant of <xref href="GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6.dita#GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6/GUID-479FE087-DD9F-31D7-98F7-9F96535F0584"><apiname>RSessionBase::SendReceive()</apiname></xref> in |
|
83 the base class. Synchronous means that it does not return until the server |
|
84 has dealt with the request. </p> <p> <codeph>Send()</codeph> passes an operation |
|
85 code (or function number) identifying the request and a descriptor containing |
|
86 information to the server. The descriptor is wrapped into a <xref href="GUID-4AD02F14-1142-372F-9D11-224595932034.dita"><apiname>TIpcArgs</apiname></xref> object. |
|
87 In practice, your client interface would probably be richer, having variants |
|
88 of the <codeph>Send()</codeph> function that take more than one parameter. |
|
89 You might also choose to have asynchronous variants of <codeph>Send()</codeph>; |
|
90 your client code (not the client interface) would then need to use active |
|
91 objects to deal with this. </p> <p> <codeph>Receive()</codeph> is implemented |
|
92 by calling down to the asynchronous variant of <xref href="GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6.dita#GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6/GUID-479FE087-DD9F-31D7-98F7-9F96535F0584"><apiname>RSessionBase::SendReceive()</apiname></xref> in |
|
93 the base class. Asynchronous means that the call returns immediately, but |
|
94 the request itself may not complete until some time later. </p> <p> <codeph>Receive()</codeph> passes |
|
95 an operation code (or function number) identifying the request, a descriptor |
|
96 into which the server will place the information, and a <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> object, |
|
97 which the server will use to report how the request completes. The descriptor |
|
98 is wrapped into a <xref href="GUID-4AD02F14-1142-372F-9D11-224595932034.dita"><apiname>TIpcArgs</apiname></xref> object. Again, you might want |
|
99 a richer client interface; perhaps different function names to represent different |
|
100 request types. </p> <p> <codeph>CancelReceive()</codeph> allows the client |
|
101 to cancel a pending <codeph>Receive()</codeph> request. It is usual to provide |
|
102 some mechanism to cancel asynchronous requests. This is implemented by calling |
|
103 down into the asynchronous variant of <xref href="GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6.dita#GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6/GUID-479FE087-DD9F-31D7-98F7-9F96535F0584"><apiname>RSessionBase::SendReceive()</apiname></xref> in |
|
104 the base class. Note: the <codeph>Receive()</codeph> method simply passes |
|
105 an operation code (or function number) and no data. </p> <p>The operation |
|
106 codes (or function numbers) are defined by an enum in the header file <filepath>clientserver.h</filepath>. |
|
107 This file is included in both the client interface code and server code as |
|
108 both need access to these common symbols. </p> </li> |
|
109 <li id="GUID-A76A5A09-CB86-5D58-8771-3DE4131E51B9"><p>Server: this is an EXE |
|
110 (<filepath>t-server.exe</filepath>) that runs in its own process, and E32Main() |
|
111 is the entry point. After setting up heap checking (in debug builds only) |
|
112 the implementation creates a cleanup stack and then executes the main body |
|
113 of the code inside a trap harness. </p> <p>The server code implements several |
|
114 classes: </p> <p> <codeph>CMyServer</codeph>: this class derives from the |
|
115 class <xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita"><apiname>CServer2</apiname></xref>. The main role of this class is to handle |
|
116 messages sent by client threads; this includes requests from clients for connection |
|
117 to the server. The connection is established by starting a session with the |
|
118 server. The session is represented by a session object, in this case the <xref href="GUID-8B50E9C7-CA33-3E11-A881-16E230A082CB.dita"><apiname>CMySession</apiname></xref> object. </p> <p>Once |
|
119 the <codeph>CMyServer</codeph> object has been created, the active scheduler |
|
120 can be started by the call to <xref href="GUID-B4C76104-EA1B-3FC3-A31E-86A976598171.dita#GUID-B4C76104-EA1B-3FC3-A31E-86A976598171/GUID-3281C85C-1A45-3049-B711-64CA8BFBC452"><apiname>CActiveScheduler::Start()</apiname></xref>. |
|
121 This call will not return until the active scheduler is stopped by the <codeph>CShutdown</codeph> timer, |
|
122 which is primed after the last client has disconnected. In simple terms, the |
|
123 active scheduler is a wait loop. It sits inactive until it receives a message |
|
124 from (potential) clients (or until the timer completes and stops the active |
|
125 scheduler). Messages that represent requests for connection result in the |
|
126 creation of a session. Other messages are passed to the relevant <codeph>CMySession</codeph> active |
|
127 object. </p> <p> <codeph> CMySession</codeph>: one of these objects is created |
|
128 for each session, i.e. as a result of a request by a client for connection |
|
129 to the server. Once sessions have been created, requests received by <codeph>CMyServer</codeph> are |
|
130 then forwarded to the corresponding session, and specifically to the virtual |
|
131 function <codeph>ServiceL()</codeph>, which handles <codeph>Send()</codeph>, <codeph>Receive()</codeph> and <codeph>CancelReceive()</codeph> requests. </p> <p> <codeph>CShutdown</codeph>: this class represents a timer that is started |
|
132 before the first client has connected, and after the last client has disconnected. |
|
133 The timer is stopped once the server has at least one client attached to it. |
|
134 If the server has no clients, then there is 2 second interval before the server |
|
135 terminates. This is implemented as an active object. </p> </li> |
|
136 <li id="GUID-07B2ACEC-C457-547D-B1FE-78FCF980AEEF"><p>Test code:this corresponds |
|
137 to the client, and uses the client interface to communicate with the server |
|
138 - application developers should make use of the principles applied here and |
|
139 include them into their own client code. </p> </li> |
|
140 <li id="GUID-91B89143-B380-524D-89CF-918FAE5CE055"><p>bld.inf: which is a |
|
141 component description file. </p> </li> |
|
142 </ul><p><b>Related APIs</b></p><ul> |
|
143 <li><p><xref href="GUID-B4C76104-EA1B-3FC3-A31E-86A976598171.dita#GUID-B4C76104-EA1B-3FC3-A31E-86A976598171/GUID-3281C85C-1A45-3049-B711-64CA8BFBC452"><apiname>CActiveScheduler::Start()</apiname></xref></p></li> |
|
144 <li><p><xref href="GUID-8B50E9C7-CA33-3E11-A881-16E230A082CB.dita"><apiname>CMySession</apiname></xref></p></li> |
|
145 <li><p><xref href="GUID-8E316AC4-4676-301A-9A23-659E83AA1D1C.dita"><apiname>CServer2</apiname></xref> - Abstract base class for servers (version |
|
146 2).</p></li> |
|
147 <li><p><xref href="GUID-D5A30C75-E22C-34E8-913B-7D2CA6AD5C51.dita"><apiname>CSession2</apiname></xref> - Represents a session (version 2) for |
|
148 a client thread on the server-side.</p></li> |
|
149 <li><p><xref href="GUID-D1D25122-F2B8-3C78-8599-84905BFD47B8.dita"><apiname>KErrAlreadyExists</apiname></xref> - System wide error code -11 : |
|
150 an object already exists.</p></li> |
|
151 <li><p><xref href="GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6.dita"><apiname>RSessionBase</apiname></xref> - Client-side handle to a session with |
|
152 a server.</p></li> |
|
153 <li><p><xref href="GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6.dita#GUID-6D8A458C-9A39-3000-A3BC-060A2A3663E6/GUID-479FE087-DD9F-31D7-98F7-9F96535F0584"><apiname>RSessionBase::SendReceive()</apiname></xref></p></li> |
|
154 <li><p><xref href="GUID-4AD02F14-1142-372F-9D11-224595932034.dita"><apiname>TIpcArgs</apiname></xref> - A Version 2 client/server class that |
|
155 clients use to package the arguments to be sent to a server.</p></li> |
|
156 <li><p><xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref> - Indicates the completion status |
|
157 of a request made to a service provider.</p></li> |
|
158 </ul> </section> |
|
159 <section id="GUID-86D3479E-216B-4D5D-AF57-C4C9963CD9F0"><title>Building and |
|
160 configuring</title> <p>To build the example: </p> <ul> |
|
161 <li id="GUID-FDC690A6-D68B-58E5-A10D-89220DB9B89E"><p>You can build the example |
|
162 from your IDE or the command line. </p> <p>If you use an IDE, import the <filepath>bld.inf</filepath> file |
|
163 of the example into your IDE, and use the build command of the IDE. </p> <p>If |
|
164 you use the command line, open a command prompt, and set the current directory |
|
165 to the source code directory of the example. You can then build the example |
|
166 with the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake |
|
167 bldfiles</userinput> </p> <p><userinput>abld build</userinput> </p> <p><xref href="GUID-793A5EF9-CC16-5EEB-9011-6431EA76EB15.dita">How to use bldmake</xref> and <xref href="GUID-B6B54E07-3B34-5D5C-8815-93383FA8FB4B.dita">How to use abld</xref> describe |
|
168 how to use the SBSv1 build tools. </p> </li> |
|
169 <li id="GUID-DD18F4AF-6AB1-5E0F-95C3-9EB899BA99C9"><p>For the emulator, the |
|
170 example builds the following executables : </p> <p> <filepath>t-client.dll</filepath> </p> <p> <filepath>t-server.exe</filepath> </p> <p> <filepath>t-test.exe</filepath> (test executable) </p> <p> <filepath>t-testc.dll</filepath> (test |
|
171 client) </p> <p>in the <filepath>epoc32\release\winscw\<udeb or urel>\</filepath> folder. </p> </li> |
|
172 </ul> </section> |
|
173 </refbody><related-links> |
|
174 <link href="GUID-4BFEDD79-9502-526A-BA7B-97550A6F0601.dita"><linktext>Platform |
|
175 security</linktext></link> |
|
176 <link href="GUID-B21141D4-3BFE-59C9-8D5F-147A93BE1C95.dita"><linktext>Build tools |
|
177 guide</linktext></link> |
|
178 <link href="GUID-594488FF-02C9-5066-85DB-5F88A754AE18.dita"><linktext>How |
|
179 to build DLLs</linktext></link> |
|
180 <link href="GUID-BBBB5000-90A2-503A-9521-2FC6DEC69DC8.dita"><linktext>MMP file |
|
181 syntax</linktext></link> |
|
182 </related-links></reference> |