<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-E6F08B67-8DBC-5896-946D-BD0D27F82FE2" xml:lang="en"><title>Views

of a Server Application System</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-AC0E13F3-5DFE-5060-BE09-B76A08632B5E"><title>Process view</title> <p>Client

objects, in the client, talk to server objects, in the server application.

The client and the server are in different processes. </p> <fig id="GUID-C5650791-6E61-5212-B563-42778AAEDE98">

<image href="GUID-08698D45-1F37-553A-9497-0081271535A1_d0e147370_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-1453B676-A271-5D89-80B4-88C8DBDEAF1C"><title>Service view</title> <p>The

diagram below shows the point of view of services which operate over the server

application system. Services are things such as "printing", "send-as" and

"contacts selection", which offer useful functionality to applications. </p> <p>The

server application framework provides generic service support over a client/server

link, upon which real services can be created. A service will typically provide

a client-side interface that clients can use directly, and a server-side interface

that server applications have to implement. </p> <fig id="GUID-81435382-06BE-5057-A23D-EDDC829191E4">

<image href="GUID-CCC121FA-C180-5103-915D-583A0CE9FB45_d0e147386_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-A608EB50-672E-54B3-B438-BD42F7D3F191"><title>Symbian platform

component view</title> <p>The diagram below shows the Symbian platform components

involved in the server application support system. </p> <p>The core of the

server application framework support is in Apparc, built on the client/server

system provided by Base. Apparc is responsible for: </p> <ul>

<li id="GUID-929FB213-9E6D-5056-B480-5B0E4C1B6825"><p>supporting multiple

service types over the client server link </p> </li>

<li id="GUID-1CF56457-2412-5C1C-A6EB-D36D7EC55ABB"><p>establishing client/server

connections to already running server applications </p> </li>

<li id="GUID-21AF6CB0-D1F9-51CE-B442-8FB29E8AF334"><p>monitoring the lifetime

of the server for the client. </p> </li>

</ul> <p>The server application framework is specialised by Uikon to allow

the launching of new server application instances for the client to connect

to. </p> <p>The server application framework may be specialised by System

GUIs, for instance, to add policy regarding the relationships between window

groups in client and server applications. </p> <p>Services may be provided

by Symbian or Licensees. These depend on the server application framework,

either as implemented in Apparc or Uikon. Only services based on Uikon's implementation

of the server application framework can be used to start new application instances.

Those based on Apparc's implementation must connect to a server application

which is already started. </p> <p>Applications will use the server application

framework appropriate for their platform. They may use whatever services are

available on that platform, subject to security restrictions. </p> <fig id="GUID-6D5FD60F-731C-57EB-9019-FEFD04EA29DC">

<image href="GUID-D3F800F3-0818-5DF2-947C-AB8DE0C0053C_d0e147432_href.png" placement="inline"/>

</fig> </section>

<section><title>Client-server view</title> <p>The diagram below shows Apparc's

implementation of the server application system from the client/server point

of view. These are the points to note about this system: </p> <ul>

<li id="GUID-1AAAFB86-9FF2-5E2E-90B6-675D38784A8E"><p>The basic client server

link is between <xref href="GUID-2E824A1A-078A-3D43-8B49-DF6328330B51.dita"><apiname>RApaAppServiceBase</apiname></xref> and <xref href="GUID-90450078-D05F-3EEB-8A5E-B7110943DD33.dita"><apiname>CApaAppServiceBase</apiname></xref>.

The protocol used on this link is for monitoring the lifetime of client and

server. </p> </li>

<li id="GUID-37D37F18-B68E-57DA-87AE-5D646B77DB39"><p>Services are implemented

in sub-classes of <xref href="GUID-2E824A1A-078A-3D43-8B49-DF6328330B51.dita"><apiname>RApaAppServiceBase</apiname></xref> and <xref href="GUID-90450078-D05F-3EEB-8A5E-B7110943DD33.dita"><apiname>CApaAppServiceBase</apiname></xref>.

The sub-class type for each particular service is identified by a UID. The

protocol added between the client and server-side of a service protocol is

specific to that service. </p> </li>

<li id="GUID-29F5685B-6C96-5332-A0DA-65511EECB2E5"><p>Clients may monitor

the lifetime of server applications using the <xref href="GUID-DB7DF858-5380-368F-BDAD-F9B6CBA4A2CC.dita"><apiname>CApaServerAppExitMonitor</apiname></xref> active

object and the <xref href="GUID-1FE93B7E-FDA2-328A-A3A0-8C5351C1EF54.dita"><apiname>MApaServerAppExitObserver</apiname></xref> interface. The

active object can be used to monitor any <xref href="GUID-2E824A1A-078A-3D43-8B49-DF6328330B51.dita"><apiname>RApaAppServiceBase</apiname></xref> derived

object. </p> </li>

<li id="GUID-507C6312-5D47-526D-8E0E-A1C38F91B386"><p>A server application

has to derive a server class from <xref href="GUID-A056179D-64B3-3674-92F5-DE9B7749D450.dita"><apiname>CApaAppServer</apiname></xref>. This class

should implement a function, <codeph>CApaAppServer::CreateServiceL()</codeph> which

takes a UID identifying the type of service that the session should implement. </p> </li>

<li id="GUID-C4207CD6-77CE-59F0-B91B-0A4F1DB2762C"><p>The service specific

sessions on client and server-side marshal parameters across the client server

link. Typically, the server-side will introduce a number of virtual functions

to handle the client requests, which the server application must override

and implement. </p> </li>

</ul> <fig id="GUID-FBF5D23A-C44E-597D-8B85-9BAEACF55710">

<image href="GUID-866B69E6-8D4C-546F-B9C9-244AD8988DE5_d0e147508_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-4D0B549E-E11D-54E2-9D8C-90F04771FF48"><title>Security view </title> <p>This

section discusses security aspects of the server application support. Essentially,

both client and server need to protect themselves against malicious versions

of their counterpart that they may connect to. </p> <ol id="GUID-1E43D0D8-919E-5778-8C06-322C7049933A">

<li id="GUID-0C4697C4-E0AB-56BE-B9F3-0400DF98AC60"><p> <xref href="GUID-2E824A1A-078A-3D43-8B49-DF6328330B51.dita"><apiname>RApaAppServiceBase</apiname></xref> protects

the client from malicious servers in three ways: Firstly, it can monitor the

lifetime of the server by holding open a request for server exit status; secondly,

it has a time-out on the connection to the server so that the server cannot

lock the client by not responding; thirdly, it can make this time-out mechanism

available to derived classes. </p> </li>

<li id="GUID-12FC7A23-41D5-590F-A211-5A07138B17E3"><p> <xref href="GUID-90450078-D05F-3EEB-8A5E-B7110943DD33.dita"><apiname>CApaAppServiceBase</apiname></xref> protects

the server from malicious clients by allowing a security policy to be set

for client requests. Note that the client/server framework provides support

for unexpected client exit. There are two functions that server applications

can override for security checking: <codeph>CApaAppServer::CreateServiceSecurityCheckL()</codeph> allows

a capability check on connect and <codeph>CApaAppServiceBase::SecurityCheckL()</codeph> allows

a security check on each message. </p> </li>

<li id="GUID-2F7F6A94-4292-5A72-9862-CDAECA84B1E6"><p>Service specific sub

sessions on the client-side should protect the client by checking the validity

of parameters received from the server. They should not assume that they are

talking to their equivalent class on the server-side. </p> </li>

<li id="GUID-D61DDBA1-9E29-53BC-9F3C-492A41ADEADF"><p>Service specific sub

sessions on the server-side should protect the server by checking the validity

of parameters received from the client. They should not assume that they are

talking to their equivalent class on the client-side. </p> </li>

</ol> <fig id="GUID-A040B1BF-AF99-5E41-B9F8-3245F54AD25C">

<image href="GUID-8617B132-D8C8-5769-95B9-867815B45B18_d0e147558_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-8C154D80-591D-5834-93B0-A99E9EF4BCD2"><title>Sequence views</title> <p>The

following sections show sequence diagrams illustrating various dynamic relationships

between client and server application. </p> <p><b>Server application start</b> </p> <p>When

a client wishes to establish a connection with a new server application, it

connects an <xref href="GUID-92F2DA99-0954-3399-9005-F3E817CB7E72.dita"><apiname>REikAppServiceBase</apiname></xref> derived object by calling

its <codeph>REikAppServiceBase::ConnectNewAppL()</codeph> function. This starts

a new instance of the server application, and passes information about the

server name to the server. The server application creates a server with the

appropriate name. <codeph>REikAppServiceBase</codeph> then connects to the

server and tells the server what session type it requires. </p> <p>Note: <xref href="GUID-92F2DA99-0954-3399-9005-F3E817CB7E72.dita"><apiname>REikAppServiceBase</apiname></xref> (implemented

in Uikon) has to be used to start new server applications. <xref href="GUID-2E824A1A-078A-3D43-8B49-DF6328330B51.dita"><apiname>RApaAppServiceBase</apiname></xref> (implemented

in Apparc) cannot start new server applications, but it can connect to existing

server applications, either by server name, or with the help of another connected <codeph>RApaAppServiceBase</codeph> instance. </p> <p>It

would not be safe for the client to dictate the full name of the server to

the server application. If this were possible, the client may be able to make

server applications impersonate system servers. Instead, the client application

tells the server a random number to use in the server name. The server name

is then generated from this random number and the UID of the server application.

Since both numbers are known to both parties, the combination can be checked

for uniqueness and they can't be used to impersonate system servers. This

name agreement system is therefore safe. </p> <fig id="GUID-DD480C95-45A1-5FE6-BDD6-A72E34BE0278">

<image href="GUID-5690EA18-106E-52E6-ABD3-4D5EE3CA8B23_d0e147606_href.png" placement="inline"/>

</fig> <p><b>Service creation</b> </p> <p>Continuing from the previous diagram,

this diagram shows the creation and use of a service specific sub-session

between the client and server application. </p> <p>To use a service, the client

must first create a service specific session. This happens during the call

to the <codeph>Connect…()</codeph> functions in <xref href="GUID-2E824A1A-078A-3D43-8B49-DF6328330B51.dita"><apiname>RApaAppServiceBase</apiname></xref> and <xref href="GUID-92F2DA99-0954-3399-9005-F3E817CB7E72.dita"><apiname>REikAppServiceBase</apiname></xref>.

These functions connect the appropriate session sub-type by sending the UID

for the session type to the server in the connect message. Because there are

no spare slots in the connect message, this UID is passed in the version field.

The server application's override of the <codeph>CreateServiceL()</codeph> function

is called passing in the UID of the requested service. The server application

can now instantiate it's implementation of the server-side objects for the

service. </p> <fig id="GUID-7A6DB7F6-4CBC-5A69-A8E1-5BEF12911E20">

<image href="GUID-84E742A8-2D24-55B8-A4DA-A67939A50754_d0e147636_href.png" placement="inline"/>

</fig> <p><b>Service use</b> </p> <p>The diagram below shows the use of a

service specific session between the client and server application. </p> <p>To

use a service, the client-side implementation of the service sends service

specific messages to the server, which are passed to the service's interface

in the server. This decodes the messages and calls virtual functions in the

server application's implementation of the service, to actually carry out

the service. </p> <fig id="GUID-71C39EBC-EF06-5CA8-A7AC-ADD1BC8F562A">

<image href="GUID-68C4E5E5-65A2-51BC-B3DC-2B83D29212D4_d0e147652_href.png" placement="inline"/>

</fig> <p><b>Server application lifetime monitoring</b> </p> <p>If the client

application requires monitoring of the server application's lifetime, which

it often will, it should implement the <xref href="GUID-1FE93B7E-FDA2-328A-A3A0-8C5351C1EF54.dita"><apiname>MApaServerAppExitObserver</apiname></xref> interface

and create a <xref href="GUID-DB7DF858-5380-368F-BDAD-F9B6CBA4A2CC.dita"><apiname>CApaServerAppExitMonitor</apiname></xref> to monitor a <xref href="GUID-2E824A1A-078A-3D43-8B49-DF6328330B51.dita"><apiname>RApaAppServiceBase</apiname></xref> derived

connection to the server application. <codeph>CApaServerAppExitMonitor</codeph> opens

a request for notification of exit to the server. When the server exits, this

notification will be completed. The <codeph>CApaServerAppExitMonitor</codeph> then

runs and tells its observer that the server application has exited. </p> <fig id="GUID-5807A9C6-86FC-5779-BA9D-A490791E7EE5">

<image href="GUID-3457B9BC-2F8F-55C1-9B5F-FA210D3439C6_d0e147683_href.png" placement="inline"/>

</fig> </section>

<section><title>See also</title><p><xref href="GUID-940F3F6E-BA9C-5E19-9AC5-D848B5E175FB.dita">Application

Architecture Overview</xref></p></section>