examples/S60CppExamples/ClientServerAsync/doc/index.html
00001 "-//W3C//DTD HTML 4.0 Transitional//EN"> 00002 00003 00004 00005 "Content-Type" content="text/html;charset=iso-8859-1"> 00006Asynchronous Client/Server Example 00007 "style.css" rel="stylesheet" type="text/css"> 00008 00009 00010
| "100%" height="1">"2" color="#000000" face="Arial, Helvetica, sans-serif">
00012 S60 5th Edition SDK Example Applications Guide |
-
00016
- id="current">"index.html">Main Page 00017
- "annotated.html">Classes 00018
- "files.html">Files 00019
Asynchronous Client/Server Example
00021
00022 class="el" href="index.html#Intro_sec">1. About this Example
00023 class="el" href="index.html#Arch_sec">2. Architecture
00024 class="el" href="index.html#Design_sec">3. Design and Implementation
00026
class="anchor" name="Intro_sec"> 00027 1. About this Example
00028 This example demonstrates the architecture of a simple client server application utilising asynchronous calls to the server. The server supplies the current time to its clients.00030
class="anchor" name="Sub11"> 00031 1.1 APIs demonstrated
00032 0003400036
class="anchor" name="Sub12"> 00037 1.2 Prerequisites
00038 This example makes use of the standard Symbian OS application framework, comprising the Application, Document, UI, and View classes. The reader should be aware of this architecture before attempting to understand this example. The example makes use of several other Symbian OS concepts which the reader should be aware of before attempting to understand this example. These are: 00043-
00045
- Thread and process management, in particular the following topics:
-
00046
- Thread and process management overview.
- Semaphores overview.
- Threads and processes overview.
- Using semaphores.
00050
class="anchor" name="Sub13"> 00051 1.3 Running this example
00052 The application initially presents a default time to the user, as shown in the following screenshot. 0005600057 The Options menu presents the following choices:
00061-
00063
- Select Start Clock to start updating the displayed time.
- Select Exit at any time, to exit the application.
00065 On selecting Start Clock, the display will be updated periodically with the current time. While the clock is running, the Options menu presents the following choices:
00069-
00071
- Select Stop Clock to stop updating the displayed time.
- Select Exit at any time, to exit the application.
00074
class="anchor" name="Arch_sec"> 00075 2. Architecture
00076 This example exists as a complete application and has the standard Symbian OS application architecture employing the Application, Document, UI, and View classes. The reader should be familiar with this architecture before proceeding.00078
class="anchor" name="Design_sec"> 00079 3. Design and Implementation
00080 The following component diagram illustrates the split of classes over the client and server components, and their inter-relationships. 0008400085 The client is a standard Symbian OS application, utilising an RSessionBase-derived object to communicate with the server. The server is implemented as an EXE.
00086 In the following description, an overview of this example's design is presented in the Design overview section. This is followed by a description of three use case scenarios, where the user:
00087
00088
00091
00092 3.1 Design overview
00093 The Symbian OS client/server architecture uses four key concepts: server (CServer2), session (CSession2 and RSessionBase), sub-session (RSubSessionBase), and message (RMessage2, and RMessagePtr2).
00094 Servers derive from CServer2, and are responsible for handling any requests from clients to establish connections.
00095 The session represents the channel of communication between client and server. Clients use a derivation of RSessionBase, and servers use a derivation from CSession2.
00096 The following class diagram shows the server-session associations for this example.
00097
00100
00101 A client can create multiple sessions with a server. However, it is more resource-efficient to use sub-sessions. This feature is not employed in this example, for simplicity.
00102 The RMessage2 class is the data structure passed between client and server. The client does not manipulate this directly, as it is encapsulated in the client-side interface. Server side sessions read from, and write to, this structure to receive and send data.
00103 To handle asynchronous services, the client requires the use of an active object. In this case, the active object is an instance of the CCSAsyncRequestHandler class. This is responsible for managing the asynchronous nature of this example. It issues requests (through the RTimeServerSession class) for asynchronous services, and receives notification of completion through its RunL method. It uses an observer, MAsyncTimeObserver, to report the completion of requests to interested parties.
00104
00105
00106 3.2 Creating a session
00107 The sequence involved in creating a session is very similar to that described in the Synchronous Client/Server Example, and hence is not described in this document. The only differences in this case are that the session is created by the CCSAsyncRequestHandler class, and the number of asynchronous message slots specified in the RSessionBase::Connect call is no longer zero.
00108
00109
00110 3.3 Making a server request
00111 The RMessage2 and RMessagePtr2 classes are used to transfer information between the client and the server. These classes have several useful methods:
00112
00113
00115 An instance of an RMessage2 object is automatically created for the session when the client calls one of the RSessionBase::SendReceive or RSessionBase::Send methods. These methods can take a parameter that is a reference to TIpcArgs object, which can have up to four 32-bit arguments.
00116 The sequence involved in making an asynchronous server request is shown below.
00120-
00122
- RequestTime is called in response to the user selecting Start Clock. This calls class="el" href="class_c_c_s_async_request_handler.html#481d63e2f4e33b9cb8ed4680a965da25">CCSAsyncRequestHandler::RequestTime.
- The class="el" href="class_r_time_server_session.html#0e65b7c45b7af042183f1c5525cfcc1b">RTimeServerSession::RequestTime is called and a TTime reference, and the active object's iStatus flag are passed to it.
- A descriptor is now created, representing the supplied TTime object. This descriptor's address is entered into the TIpcArgs object, which is passed to the inherited SendReceive method. SendReceive is an asynchronous method, and returns immediately.
- The SetActive method is called, to indicate that the active object has issued a request that is now outstanding. class="el" href="class_c_c_s_async_request_handler.html#98dcd20e4dd117488a6a90dadd4dfac5">CCSAsyncRequestHandler::RunL will be called when the server completes the request.
00124 As a result of the call to SendReceive, the framework calls the class="el" href="class_c_time_server_session.html#75c0a1442736b57144c9ad541d87d370">CTimeServerSession::ServiceL of the associated server-side session, as shown in the following diagram.
00128-
00130
- class="el" href="class_c_time_server_session.html#75c0a1442736b57144c9ad541d87d370">CTimeServerSession::ServiceL is called by the kernel, and passed an RMessage2 encapsulating the client's request.
- RMessage2::Function is called to determine the request type.
- If the request is for a time update, RequestTimeL is called.
- The received request (RMessage2) is stored. The session now registers its interest in the server's time updates by calling class="el" href="class_c_time_server.html#a8205372b5d379fa4b803e98b0726473">CTimeServer::WaitForTickL.
- The server uses an instance of the CHeartbeat class to notify sessions of a time update. New instance is created here if the heartbeat is not already created.
- The heartbeat is also started, if it was not already created in previous step.
- When the next heartbeat occurs, "el" href="class_c_time_server.html#8bc39d8613772fe04fa5d6a845ede8cd">CTimeServer::Beat is called.
- The Beat function calls SendTimeToSessions, which iterates over all established sessions, calling class="el" href="class_c_time_server_session.html#ecff8e289d914777ae0c503db937cf33">CTimeServerSession::SendTimeToClient.
- SendTimeToClient is called.
- SendTimeToClient calculates the current time and creates a new descriptor representing it (using TPtr8 since it's binary data). RMessage2::WriteL is now called, with the created descriptor as parameter. First parameter of the WriteL is zero identifying the argument index value. The descriptor at the client side was the first argument, so server has to write into the first argument (index 0). If server writes to index 1, in this case, WriteL would return error KErrBadDescriptor. The WriteL function call causes the time to be written to the client's address space.
- The server session then signals the client, using the RMessage2::Complete method. This causes the client's CCSAsyncRequestHandler::RunL method to be called, as shown in the following diagram.
00141
00142 3.4 Canceling a server request 00143 When the user selects Stop Clock, the following sequence is entered. 00144 00147 00148
00151 As a result of the call to SendReceive, the framework calls the CTimeServerSession::ServiceL of the associated server-side session, as shown in the following diagram.
00155-
00157
- ServiceL is called by the framework in response to a request from the client.
- The requested method is checked by examining the returned id from RMessage2::Function. In this case, it indicates that the client has requested cancellation of an outstanding request. The servicing of this request should complete in as short a time as possible, since the client waits for completion.
- If a previous request is pending, the server completes it by calling Complete on the stored request's associated RMessage2.
- The cancellation request is now completed, freeing the client to continue processing.
00160
00161 3.5 Capabilities 00162 The application does not require any capabilities. The program capabilities are defined in both mmp-files as CAPABILITY NONE.
00163 00164 00208 00209