Using ClientMessage Framework

Procedure

1. Create and initialize a TClientMessageSchema structure to represent a single message from the client.

   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.

   const TParameterDetails KMessageParams2[1] = {{EParamInt,-10,100}};
   
   const TClientMessageSchema KClientMessages[] = 
   MESSAGE_SCHEMA( EMessage0, KDefaultPolicy, KMessageParams2 );

2. Create and initialize a TClientMessageServerData structure containing an array of custom validation functionsTCustomValidationFn and TClientMessageSchema structure defining a schema for each message that will be accepted by the server.

   extern const TClientMessageServerData aServerData=
       {
       sizeof( KClientMessages )/sizeof( TClientMessageSchema ),
       KClientMessages,                                               
       KCustomValidationFunctions,
       ( TUint8* )"My Server"
       }

3. Initialize the framework by calling the static function CClientMessage::InitialiseFrameworkL () and pass it to TClientMessageServerData structure.

   IMPORT_C static void InitialiseFrameworkL( const TClientMessageServerData &aServerData );

Results

On construction, CMessageParameterBase objects are instantiated using the TParameterDetails structs in the message schema and stored in an RPointerArray. The objects represent the individual message arguments and are used to validate each argument against the constraints defined in the message schema.

Example

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 TClientMessageServerData structure.

#include <bsul/bsul.h>
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"
    };