|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-3B2FB34B-B4FC-5273-AE35-DADA2FA4C419" xml:lang="en"><title>Using |
|
13 ClientMessage Framework</title><shortdesc>This section explains how to use the ClientMessage framework to |
|
14 sanitize the incoming messages. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section><title>Procedure</title> <ol id="GUID-99AB8BE4-C585-55A3-B16F-C4B53A9E9E61"> |
|
16 <li id="GUID-F6B94808-046E-5D80-9BDC-AEEEE1DB694B"><p>Create and initialize |
|
17 a <xref href="GUID-8AA6248D-64E4-3C73-8541-03C9880000F0.dita"><apiname>TClientMessageSchema</apiname></xref> structure to represent a single |
|
18 message from the client. </p> <p>It defines the function number corresponding |
|
19 to the message, the security policy for the message, the number of paramaters |
|
20 that are passed to the function and the type and constraint information for |
|
21 each of the parameters. </p> <p><codeblock id="GUID-76569264-62A5-53A4-A12F-55067521D309" xml:space="preserve">const TParameterDetails KMessageParams2[1] = {{EParamInt,-10,100}}; |
|
22 |
|
23 const TClientMessageSchema KClientMessages[] = |
|
24 MESSAGE_SCHEMA( EMessage0, KDefaultPolicy, KMessageParams2 );</codeblock> </p> </li> |
|
25 <li id="GUID-2BD81806-096B-58F3-A498-733BBC876809"><p>Create and initialize |
|
26 a <xref href="GUID-FF1684A9-62FF-3614-BA8D-084CA2FFC3AE.dita"><apiname>TClientMessageServerData</apiname></xref> structure containing an array |
|
27 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 |
|
28 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= |
|
29 { |
|
30 sizeof( KClientMessages )/sizeof( TClientMessageSchema ), |
|
31 KClientMessages, |
|
32 KCustomValidationFunctions, |
|
33 ( TUint8* )"My Server" |
|
34 }</codeblock> </p> </li> |
|
35 <li id="GUID-A3F4C516-B219-5E77-9F3B-6EB0F76944B4"><p>Initialize the framework |
|
36 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> () |
|
37 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 &aServerData );</codeblock> </p> </li> |
|
38 </ol> </section> |
|
39 <section><title>Results</title> <p>On construction, <codeph>CMessageParameterBase</codeph> objects |
|
40 are instantiated using the <codeph>TParameterDetails</codeph> structs in the |
|
41 message schema and stored in an <codeph>RPointerArray</codeph>. The objects |
|
42 represent the individual message arguments and are used to validate each argument |
|
43 against the constraints defined in the message schema. </p> </section> |
|
44 <section><title>Example</title> <p>Below is an example schema that defines |
|
45 four messages, including two that define custom validation functions. The |
|
46 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 <bsul/bsul.h> |
|
47 using namespace BSUL; |
|
48 //This enum defines the custom parameter types used to validate |
|
49 //TPckg<TMyStruct> and TPckg<TMyStruct1> parameters. |
|
50 enum TCustomParamType |
|
51 { |
|
52 EParamCustom1 = ( 0x000 | EParamPckg ), |
|
53 EParamCustom2 = ( 0x100 | EParamPckg ) |
|
54 }; |
|
55 //Defines the schema for each message |
|
56 const TParamaterDetails KMessage0Params[2] = {{EParamInt,-10,100}, |
|
57 {EParamInt,0,200}}; |
|
58 const TParamaterDetails KMessage1Params[2] = {{EParamDes8Read,64,64}, |
|
59 {EParamInt,0,64}}; |
|
60 //Parameter is TPckg<TMyStruct> |
|
61 const TParamaterDetails KMessage2Params[1] = {{EParamCustom1,sizeof( TMyStruct ), sizeof( TMyStruct )}}; |
|
62 //Parameter is TPckg<TMyStruct1> |
|
63 const TParamaterDetails KMessage3Params[1] = {{EParamCustom2,sizeof( TMyStruct1 ), sizeof( TMyStruct1 )}}; |
|
64 //Define the security policies for each message |
|
65 _LIT_SECURITY_POLICY_PASS( KDefaultPolicy ); |
|
66 _LIT_SECURITY_POLICY_C2( KMsg2Policy, ECapabilityReadUserData, ECapabilityWriteUserData ); |
|
67 //This is the array of TClientMessageSchema structs that define the messages that will be accepted by the server. |
|
68 const TClientMessageSchema KClientMessages[] = |
|
69 { |
|
70 {EMessage0, |
|
71 KDefaultPolicy, |
|
72 sizeof( KMessage0Params )/sizeof( TParamaterDetails ),KMessage0Params}, |
|
73 |
|
74 {EMessage1, |
|
75 KDefaultPolicy, |
|
76 sizeof( KMessage1Params )/sizeof( TParamaterDetails ),KMessage1Params}, |
|
77 |
|
78 {EMessage2, |
|
79 KMsg2Policy, |
|
80 sizeof( KMessage2Params )/sizeof( TParamaterDetails ),KMessage2Params}, |
|
81 |
|
82 {EMessage3, |
|
83 KDefaultPolicy, |
|
84 sizeof( KMessage3Params )/sizeof( TParamaterDetails ),KMessage3Params} |
|
85 }; |
|
86 //These are the custom validation functions that are used to validate |
|
87 //TPckg<TMyStruct1> and TPckg<TMyStruct1> parameters |
|
88 static void CustomValidationFn1L( CMessageParameterBase* aParameter ); |
|
89 static void CustomValidationFn2L( CMessageParameterBase* aParameter ); |
|
90 //This is the array of custom validation functions. The index of the function |
|
91 //in the array should match the upper 16 bits of the value defined in |
|
92 //TCustomParamType enum for that parameter type. |
|
93 const TCustomValidationFn KCustomValidationFunctions[] = |
|
94 { |
|
95 &CustomValidationFn1L, |
|
96 &CustomValidationFn2L |
|
97 }; |
|
98 //This is the initialization data that is passed into the ClientMessage |
|
99 //framework by the server. It contains everything the framework needs to |
|
100 //validate incoming messages |
|
101 extern const TClientMessageServerData KServerData = |
|
102 { |
|
103 sizeof( KClientMessages )/sizeof( TClientMessageSchema ), |
|
104 KClientMessages, |
|
105 KCustomValidationFunctions, |
|
106 ( TUint8* )"My Server" |
|
107 };</codeblock> </section> |
|
108 </conbody><related-links> |
|
109 <link href="GUID-42C94E3D-93DE-543E-A0D2-8B705C668BE0.dita"><linktext>Base Services |
|
110 Utility Library Overview</linktext></link> |
|
111 </related-links></concept> |