<?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-3B2FB34B-B4FC-5273-AE35-DADA2FA4C419" xml:lang="en"><title>Using

ClientMessage Framework</title><shortdesc>This section explains how to use the ClientMessage framework to

sanitize the incoming messages. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Procedure</title> <ol id="GUID-99AB8BE4-C585-55A3-B16F-C4B53A9E9E61">

<li id="GUID-F6B94808-046E-5D80-9BDC-AEEEE1DB694B"><p>Create and initialize

a <xref href="GUID-8AA6248D-64E4-3C73-8541-03C9880000F0.dita"><apiname>TClientMessageSchema</apiname></xref> structure to represent a single

message from the client. </p> <p>It defines the function number corresponding

to the message, the security policy for the message, the number of paramaters

that are passed to the function and the type and constraint information for

each of the parameters. </p> <p><codeblock id="GUID-76569264-62A5-53A4-A12F-55067521D309" xml:space="preserve">const TParameterDetails KMessageParams2[1] = {{EParamInt,-10,100}};

const TClientMessageSchema KClientMessages[] = 

MESSAGE_SCHEMA( EMessage0, KDefaultPolicy, KMessageParams2 );</codeblock> </p> </li>

<li id="GUID-2BD81806-096B-58F3-A498-733BBC876809"><p>Create and initialize

a <xref href="GUID-FF1684A9-62FF-3614-BA8D-084CA2FFC3AE.dita"><apiname>TClientMessageServerData</apiname></xref> structure containing an array

of custom validation functions<xref href="GUID-DA261437-879F-3A8D-9D91-F683BF41CA32.dita"><apiname>TCustomValidationFn</apiname></xref> and <xref href="GUID-8AA6248D-64E4-3C73-8541-03C9880000F0.dita"><apiname>TClientMessageSchema</apiname></xref> structure

defining a schema for each message that will be accepted by the server. </p> <p><codeblock id="GUID-1B3F0610-C1D9-5354-959A-B4ABDE746350" xml:space="preserve">extern const TClientMessageServerData aServerData=

    {

    sizeof( KClientMessages )/sizeof( TClientMessageSchema ),

    KClientMessages,                                               

    KCustomValidationFunctions,

    ( TUint8* )"My Server"

    }</codeblock> </p> </li>

<li id="GUID-A3F4C516-B219-5E77-9F3B-6EB0F76944B4"><p>Initialize the framework

by calling the static function <xref href="GUID-45AFEB13-9D05-365D-A2A6-A34EF48A494D.dita"><apiname>CClientMessage</apiname></xref>::<xref href="GUID-25CE7350-2288-3E55-901C-0F0AAFECCD1B.dita"><apiname>InitialiseFrameworkL</apiname></xref> ()

and pass it to <xref href="GUID-FF1684A9-62FF-3614-BA8D-084CA2FFC3AE.dita"><apiname>TClientMessageServerData</apiname></xref> structure. </p> <p><codeblock id="GUID-F2AEF771-F37F-5028-99D7-6DD1CE9209E0" xml:space="preserve">IMPORT_C static void InitialiseFrameworkL( const TClientMessageServerData &amp;aServerData );</codeblock> </p> </li>

</ol> </section>

<section><title>Results</title> <p>On construction, <codeph>CMessageParameterBase</codeph> objects

are instantiated using the <codeph>TParameterDetails</codeph> structs in the

message schema and stored in an <codeph>RPointerArray</codeph>. The objects

represent the individual message arguments and are used to validate each argument

against the constraints defined in the message schema. </p> </section>

<section><title>Example</title> <p>Below is an example schema that defines

four messages, including two that define custom validation functions. The

data is passed to the framework through a constant <codeph>TClientMessageServerData</codeph> structure. </p> <codeblock id="GUID-5375E126-8C70-5B45-9202-E1F94A969E4B" xml:space="preserve">#include &lt;bsul/bsul.h&gt;

using namespace BSUL;

//This enum defines the custom parameter types used to validate 

//TPckg<TMyStruct> and TPckg<TMyStruct1> parameters.

enum TCustomParamType

    {        

    EParamCustom1 = ( 0x000 | EParamPckg ),        

    EParamCustom2 = ( 0x100 | EParamPckg )     

    };

//Defines the schema for each message

const TParamaterDetails KMessage0Params[2] = {{EParamInt,-10,100},

                                             {EParamInt,0,200}};

const TParamaterDetails KMessage1Params[2] = {{EParamDes8Read,64,64},

                                             {EParamInt,0,64}};

//Parameter is TPckg<TMyStruct>

const TParamaterDetails KMessage2Params[1] = {{EParamCustom1,sizeof( TMyStruct ), sizeof( TMyStruct )}};

//Parameter is TPckg<TMyStruct1>

const TParamaterDetails KMessage3Params[1] = {{EParamCustom2,sizeof( TMyStruct1 ), sizeof( TMyStruct1 )}};

//Define the security policies for each message

_LIT_SECURITY_POLICY_PASS( KDefaultPolicy );

_LIT_SECURITY_POLICY_C2( KMsg2Policy, ECapabilityReadUserData, ECapabilityWriteUserData );

//This is the array of TClientMessageSchema structs that define the messages that will be accepted by the server.

const TClientMessageSchema KClientMessages[] =      

    {

    {EMessage0,

    KDefaultPolicy,         

    sizeof( KMessage0Params )/sizeof( TParamaterDetails ),KMessage0Params},

    {EMessage1,

    KDefaultPolicy,

    sizeof( KMessage1Params )/sizeof( TParamaterDetails ),KMessage1Params},

    {EMessage2,

    KMsg2Policy,

    sizeof( KMessage2Params )/sizeof( TParamaterDetails ),KMessage2Params},

    {EMessage3,

    KDefaultPolicy,

    sizeof( KMessage3Params )/sizeof( TParamaterDetails ),KMessage3Params}

    };

//These are the custom validation functions that are used to validate 

//TPckg<TMyStruct1> and TPckg<TMyStruct1> parameters

static void CustomValidationFn1L( CMessageParameterBase* aParameter );

static void CustomValidationFn2L( CMessageParameterBase* aParameter );

//This is the array of custom validation functions. The index of the function 

//in the array should match the upper 16 bits of the value defined in 

//TCustomParamType enum for that parameter type.

const TCustomValidationFn KCustomValidationFunctions[] = 

    {

    &CustomValidationFn1L,

    &CustomValidationFn2L

    };

//This is the initialization data that is passed into the ClientMessage 

//framework by the server. It contains everything the framework needs to 

//validate incoming messages

extern const TClientMessageServerData KServerData =

    {

    sizeof( KClientMessages )/sizeof( TClientMessageSchema ),

    KClientMessages,                                               

    KCustomValidationFunctions,

    ( TUint8* )"My Server"

    };</codeblock> </section>

</conbody><related-links>

<link href="GUID-42C94E3D-93DE-543E-A0D2-8B705C668BE0.dita"><linktext>Base Services

Utility Library Overview</linktext></link>