S60 5th Edition SDK Example Applications Guide |
Asynchronous Client/Server Example
1. About this Example
2. Architecture
3. Design and Implementation
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.
- CActive
- CServer2
- CSession2
- RMessagePtr2
- RMessage2
- RSessionBase
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:
- Asynchronous programming, in particular the following topics:
- Inter-process communication overview.
- Client/server overview.
- Using client/server.
- CActive
- Thread and process management, in particular the following topics:
- Thread and process management overview.
- Semaphores overview.
- Threads and processes overview.
- Using semaphores.
The application initially presents a default time to the user, as shown in the following screenshot.
The Options menu presents the following choices:
- Select Start Clock to start updating the displayed time.
- Select Exit at any time, to exit the application.
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:
- Select Stop Clock to stop updating the displayed time.
- Select Exit at any time, to exit the application.
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.
The following component diagram illustrates the split of classes over the client and server components, and their inter-relationships.
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.
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:
- Invokes the application - here, the application establishes communication with the server, creating the server if necessary. This is achieved using the RTimeServerSession class, and is described in the Creating a session section.
- Makes a server request - the application uses the established session to request data from the server. This is described in the Making a server request section.
- Cancels a server request - the user cancels an outstanding request. This is described in the Canceling a server request section.
The Symbian OS client/server architecture uses four key concepts: server (CServer2), session (CSession2 and RSessionBase), sub-session (RSubSessionBase), and message (RMessage2, and RMessagePtr2).
Servers derive from CServer2, and are responsible for handling any requests from clients to establish connections.
The session represents the channel of communication between client and server. Clients use a derivation of RSessionBase, and servers use a derivation from CSession2.
The following class diagram shows the server-session associations for this example.
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.
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.
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.
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.
The RMessage2 and RMessagePtr2 classes are used to transfer information between the client and the server. These classes have several useful methods:
- RMessage2 allows client to specify the required server operation.
- RMessage2 allows four 32-bit words of information to be passed back and forth between the client and server.
- RMessagePtr2 allows the server to signal when a client's request has completed, using the Complete method.
- RMessagePtr2 allows the server to panic its client.
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.
The sequence involved in making an asynchronous server request is shown below.
- RequestTime is called in response to the user selecting Start Clock. This calls CCSAsyncRequestHandler::RequestTime.
- The 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. CCSAsyncRequestHandler::RunL will be called when the server completes the request.
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.
- 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 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, CTimeServer::Beat is called.
- The Beat function calls SendTimeToSessions, which iterates over all established sessions, calling 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.
Once the server has completed the request, the active object which initiated the request will be signalled, and its RunL method called, as shown in the following diagram.
- The active scheduler calls the RunL method in response to the server completing the request.
- The observer is notified and the time is updated to the screen if the status flag indicates successful completion of the request.
- A new request is scheduled, to keep the clock 'running'.
When the user selects Stop Clock, the following sequence is entered.
- CancelRequest is called in response to the user selecting Stop Clock from the Options menu.
- To handle cancelled requests, active objects should call CActive::Cancel and also implement a DoCancel method. This will be called as a result of calling CActive::Cancel.
- DoCancel is called, which instructs the session to cancel the outstanding request by calling RTimeServerSession::CancelRequestTime.
- CancelRequestTime() is called.
- The synchronous request is now sent to the server, instructing it to cancel the outstanding request by calling SendReceive. The framework will call the corresponding server-side session's ServiceL method as shown in the following sequence.
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.
- 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.
The application does not require any capabilities. The program capabilities are defined in both mmp-files as CAPABILITY NONE.
© Nokia 2009 |

|