186	THE CLIENT–SERVER FRAMEWORK IN THEORY

11.15How Many Outstanding Requests Can a Client Make to a Server?

A client session with a server can only ever have a single synchronous request outstanding. However, it can have up to 255 outstanding asynchronous requests. The message slots which hold these requests are either allocated to a single session or acquired dynamically from a systemwide pool, according to the overload of RSessionBase::CreateSession() used to start the session. See the discussion on RSessionBase in Section 11.4 for more details.

11.16Can Server Functionality Be Extended?

Server code can be extended by the use of plug-ins to offer different types of service. A good example of this is the Symbian OS file server, which can be extended at runtime to support different types of filesystem plug-in. The core Symbian OS filesystem provides support for local media (ROM, RAM and CF card) using a VFAT filing system, implemented as a plug-in, ELocal.fsy. Other filesystems may be added, for example to support a remote filesystem over a network or encryption of file data before it is stored. These file system plug-ins may be installed and uninstalled dynamically; in the client-side file server session class, RFs, you’ll see a set of functions for this purpose (FileSystemName(),

AddFileSystem(), RemoveFileSystem(), MountFileSystem() and DismountFileSystem()).

The extension code should be implemented as a polymorphic DLL (targettype fsy) and must conform to the fsy plug-in interface defined by Symbian OS. More information about the use of framework and plug-in code in Symbian OS, and polymorphic DLLs, can be found in Chapter 13.

Since they normally run in the same thread as the server, and are often called directly from CServer::RunL(), it is important to note that installable server extension plug-in modules must not have a negative impact on the performance or runtime stability of the server.

11.17Example Code

Finally, here is an example of how a server may be accessed and used. It illustrates how a client thread creates a session with the Symbian OS file server. The file server session class, RFs, is defined in f32file.h, and to use the file server client-side implementation you must link against efsrv.lib.

SUMMARY

187

Having successfully created the session and made it leave-safe using the cleanup stack (as described in Chapter 3), the sample code submits a request to the file server, using RFs::Delete(). This function wraps the single descriptor parameter and passes it to the synchronous overload of RSessionBase::SendReceive(). Following this, it creates an RFile subsession of the RFs session, by calling

RFile::Create(). It then calls RFile::Read() on the subsession, which submits a request to the file server by wrapping a call to

RSubSessionBase::SendReceive(), passing in the descriptor parameter that identifies the buffer which will receive data read from the file.

RFs fs;

User::LeaveIfError(fs.Connect());

CleanupClosePushL(fs); // Closes the session in the event of a leave

_LIT(KClangerIni, "c:\\clanger.ini");

// Submits a delete request to the server User::LeaveIfError(fs.Delete(KClangerIni));

RFile file; // A subsession

User::LeaveIfError(file.Create(fs, KClangerIni,

EFileRead|EFileWrite|EFileShareExclusive)); // Closes the subsession in the event of a leave CleanupClosePushL(file);

TBuf8<32> buf;

// Submits a request using the subsession User::LeaveIfError(file.Read(buf)); CleanupStack::PopAndDestroy(2, &fs); // file, fs

11.18Summary

This chapter explored the theory behind the Symbian OS client–server framework. It is quite a complex subject, so the chapter was split into a number of short sections to allow it to be read at several different levels, depending on whether the information is required to use a server or to write one. The sections covered the following:

•The basics of the client–server framework and why it is used to share access to system resources and protect their integrity.

•The thread model for a client–server implementation. The client and server run in separate threads and often the server runs in a separate process; this isolates the system resource within a separate address space and protects it from potential misuse. Symbian OS threads and processes are discussed in Chapter 10.

188	THE CLIENT–SERVER FRAMEWORK IN THEORY

•The mechanism by which data is transferred between the client and server, using inter-thread data transfer. This uses inter-process communication (IPC) when the client and server run in different processes, and there are potential runtime overheads associated with IPC data transfer.

•The main classes which make up the Symbian OS client–server framework (RSessionBase, C(Sharable)Session, CServer, DSession, RMessage and RSubSessionBase), their main roles, features, fundamental methods and interactions.

•Server startup (which is examined in more detail in the next chapter) and shutdown, either when all clients have disconnected normally or as a result of the death of either the client or server.

•The overheads associated with using a client–server architecture, such as the number of kernel resources consumed by having multiple open sessions with a server, and the potential impact of using active objects with lengthy RunL() event handlers within the server.

•Example code using F32, the file server, as an example of a typical Symbian OS client–server model.

The following chapter uses a detailed code example to illustrate a typical server, its client-side implementation, and its use by a calling client.

12

The Client–Server Framework

in Practice

Kill the lion of Nemea Kill the nine-headed Hydra Capture the Ceryneian Hind

Kill the wild boar of Erymanthus Clean the stables of King Augeas Kill the birds of Stymphalis Capture the wild bull of Crete

Capture the man-eating mares of Diomedes Obtain the girdle of Hippolyta, Queen of the Amazons

Capture the oxen of Geryon

Take golden apples from the garden of Hesperides

Bring Cerberus, the three-headed dog of the underworld, to the surface

The Twelve Labors of Hercules

This chapter works through the code for an example client and server to illustrate the main points of the Symbian OS client–server architecture, which I discussed in detail in Chapter 11. This chapter will be of particular interest if you plan to implement your own server, or if you want to know more about how a client’s request to a server is transferred and handled.

The code examines the typical features of a client–server implementation using a transient server, which is started by its first client connection and terminates when its last outstanding client session closes, to save system resources. I’ll take the main elements of client–server code in turn and discuss the most important sections of each. You can find the entire set of sample code on the Symbian Press website (www.symbian.com/books). The bootstrap code used by a client to start a server can be quite complex and you may find it helps to download this example and step through the code to follow how it works.

As in the previous chapter, I discuss the client–server model only for Symbian OS releases up to and including v7.0s (the code samples in this chapter use the client–server APIs from Symbian OS v7.0). Some of

190	THE CLIENT–SERVER FRAMEWORK IN PRACTICE

the APIs have changed from Symbian OS 8.0 onwards and, although the concepts are generally the same, I’ve decided to concentrate solely on the releases available at the time of going to press, rather than confuse matters.

Client–server code can be notoriously complicated, so I have kept the services provided by the server as simple as possible. This comes, perhaps, at the expense of making the example code rather contrived; my client–server example provides a software representation of the twelve labors of the Greek hero Hercules.1 For each labor, I’ve exported a function from a client-side implementation class, RHerculesSession. These functions send a request to the server to perform the necessary heroic activity. The client-side implementation is delivered as a shared library DLL (client.dll) – callers wishing to use the functionality provided by server should link to this. The server code itself is built into a separate EPOCEXE component (shared library DLLs and targettype EPOCEXE are discussed in Chapter 13).

12.1Client–Server Request Codes

A set of enumerated values is used to identify which service the client requests from the server. These values are quite straightforward and are defined as follows:

enum THerculeanLabors

{

ESlayNemeanLion,

ESlayHydra,

ECaptureCeryneianHind,

ESlayErymanthianBoar,

ECleanAugeanStables,

ESlayStymphalianBirds,

ECaptureCretanBull,

ECaptureMaresOfDiomedes,

EObtainGirdleOfHippolyta,

ECaptureOxenOfGeryon,

ETakeGoldenApplesOfHesperides,

ECaptureCerberus,

ECancelCleanAugeanStables, ECancelSlayStymphalianBirds };

Later in the chapter you’ll see these shared request ”opcodes” passed to an overload of RSessionBase::SendReceive() on the client side and stored in the corresponding server-side RMessage object (which represents the client request) to identify which service the client has requested.

1 If nothing else, this chapter will prepare you well for a pub quiz question about the Herculean labors.