1 <?xml version="1.0" encoding="utf-8"?> |
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!--Arbortext, Inc., 1988-2004, v.4002--> |
|
3 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" |
|
4 "concept.dtd"> |
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
5 <!-- 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 |
6 <!-- 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, |
7 "Eclipse Public License v1.0" which accompanies this distribution, |
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
8 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
6 <!-- Initial Contributors: |
9 <!-- Initial Contributors: |
7 Nokia Corporation - initial contribution. |
10 Nokia Corporation - initial contribution. |
8 Contributors: |
11 Contributors: |
9 --> |
12 --> |
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-A8130D83-E684-5B6C-BDFE-EB6EE3CD49E8" xml:lang="en"><title>Writing |
13 <concept id="GUID-A8130D83-E684-5B6C-BDFE-EB6EE3CD49E8" xml:lang="en"><title>Writing |
13 a UPS Dialog Creator</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
14 a UPS Dialog Creator</title> |
14 <section><title>Introduction</title> <p>Dialog creators are EComplug-ins that |
15 <prolog> |
15 device creators can write to generate the dialogs containing prompts for phone |
16 <metadata> |
16 users. </p> <p>The plug-in has an API that consists of two asynchronous functions: </p> <ul> |
17 <keywords></keywords> |
|
18 </metadata> |
|
19 </prolog> |
|
20 <conbody> |
|
21 <section><title>Introduction</title> <p>Dialog creators are ECom <?Pub Caret?>plug-ins |
|
22 that device creators can write to generate the dialogs containing prompts |
|
23 for phone users. </p> <p>The plug-in has an API that consists of two asynchronous |
|
24 functions: </p> <ul> |
17 <li id="GUID-96CBCE79-4F5D-5F87-AC6B-C366346447AB"><p>The <codeph>PrepareDialog()</codeph> function. |
25 <li id="GUID-96CBCE79-4F5D-5F87-AC6B-C366346447AB"><p>The <codeph>PrepareDialog()</codeph> function. |
18 This function is called first by the UPS server. It enables the dialog creator |
26 This function is called first by the UPS server. It enables the dialog creator |
19 to query other system servers such as AppArc or the SIS registry to retrieve |
27 to query other system servers such as AppArc or the SIS registry to retrieve |
20 additional information to display in the dialog. For example it might query |
28 additional information to display in the dialog. For example it might query |
21 the SIS registry using the client application’s secure id. </p> </li> |
29 the SIS registry using the client application’s secure id. </p> </li> |
25 the option selected by the user and, if applicable, the fingerprint for a |
33 the option selected by the user and, if applicable, the fingerprint for a |
26 new decision record. </p> </li> |
34 new decision record. </p> </li> |
27 </ul> <p>The UPS displays only one prompt at a time so it is possible for |
35 </ul> <p>The UPS displays only one prompt at a time so it is possible for |
28 there to be a delay between calling the function to prepare the dialog and |
36 there to be a delay between calling the function to prepare the dialog and |
29 the function to display the dialog. It is also possible for other dialogs |
37 the function to display the dialog. It is also possible for other dialogs |
30 to be displayed between the dialog being prepared and its being displayed. </p> <p>Both <codeph>PrepareDialog()</codeph> and <codeph>DisplayDialog()</codeph> are asynchronous and must support cancellation through <codeph>CActive::Cancel</codeph>. |
38 to be displayed between the dialog being prepared and its being displayed. </p> <p>Both <codeph>PrepareDialog()</codeph> and <codeph>DisplayDialog()</codeph |
|
39 > are asynchronous and must support cancellation through <codeph>CActive::Cancel</codeph>. |
31 If either function is cancelled, the dialog creator instance is destroyed |
40 If either function is cancelled, the dialog creator instance is destroyed |
32 without calling further methods. </p> <p>The work split between <codeph>PrepareDialog()</codeph> and <codeph>DisplayDialog()</codeph> described |
41 without calling further methods. </p> <p>The work split between <codeph>PrepareDialog()</codeph> and <codeph>DisplayDialog()</codeph> described |
33 above is a recommendation, and some of the functionality could be implemented |
42 above is a recommendation, and some of the functionality could be implemented |
34 directly in the notifier implementation. </p> <p>In the example given in this |
43 directly in the notifier implementation. </p> <p>In the example given in this |
35 document, the functionality for dialogs is implemented separately from the |
44 document, the functionality for dialogs is implemented separately from the |
46 </ol> <p>The Dialog Creator plug-in creates a dialog prompt in cases where |
55 </ol> <p>The Dialog Creator plug-in creates a dialog prompt in cases where |
47 no previous decision is found in the decision database. </p> <p><b> Preparing |
56 no previous decision is found in the decision database. </p> <p><b> Preparing |
48 the dialog</b> </p> <p>The parameters to <codeph>PrepareDialog()</codeph> are |
57 the dialog</b> </p> <p>The parameters to <codeph>PrepareDialog()</codeph> are |
49 mostly <codeph>const</codeph> pointers and references to the data that has |
58 mostly <codeph>const</codeph> pointers and references to the data that has |
50 already been generated by the UPS or policy evaluator. </p> <p>The following |
59 already been generated by the UPS or policy evaluator. </p> <p>The following |
51 table describes the parameters for the <codeph>PrepareDialog()</codeph> function: </p> <table id="GUID-6D139216-B6A8-55A1-8D9B-C15134198198"> |
60 table describes the parameters for the <codeph>PrepareDialog()</codeph> function: </p> <table |
|
61 id="GUID-6D139216-B6A8-55A1-8D9B-C15134198198"> |
52 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
62 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
53 <thead> |
63 <thead> |
54 <row> |
64 <row> |
55 <entry>Parameter</entry> |
65 <entry>Parameter</entry> |
56 <entry>Description</entry> |
66 <entry>Description</entry> |
87 <entry><p>The request status used to contain completion information for the |
97 <entry><p>The request status used to contain completion information for the |
88 function. </p> </entry> |
98 function. </p> </entry> |
89 </row> |
99 </row> |
90 </tbody> |
100 </tbody> |
91 </tgroup> |
101 </tgroup> |
92 </table> <p><note/> The UPS does not allow any responses to be returned |
102 </table> <p><note></note> The UPS does not allow any responses to be returned |
93 to the system server except those defined in the UPS policy file. If the dialog |
103 to the system server except those defined in the UPS policy file. If the dialog |
94 creator returns an option that was not specified in the policy, the request |
104 creator returns an option that was not specified in the policy, the request |
95 is rejected and <codeph>EUpsDecNo</codeph> is returned. </p><p>Your implementation |
105 is rejected and <codeph>EUpsDecNo</codeph> is returned. </p><p>Your implementation |
96 can assume that the pointers remain valid until after <codeph>DisplayDialog()</codeph> has |
106 can assume that the pointers remain valid until after <codeph>DisplayDialog()</codeph> has |
97 been called. </p><p>The <codeph>PrepareDialog()</codeph> function sets values. </p><p>The<codeph> DoPrepareDialogL()</codeph> function |
107 been called. </p><p>The <codeph>PrepareDialog()</codeph> function sets values. </p><p>The<codeph> DoPrepareDialogL()</codeph> function |
116 sets values. The <codeph>DoDisplayDialogL()</codeph> function calls the notifier |
126 sets values. The <codeph>DoDisplayDialogL()</codeph> function calls the notifier |
117 framework to display the dialogs. The <codeph>DoDisplayDialogL()</codeph> function |
127 framework to display the dialogs. The <codeph>DoDisplayDialogL()</codeph> function |
118 is called through a <codeph>switch</codeph> statement, which can be seen in |
128 is called through a <codeph>switch</codeph> statement, which can be seen in |
119 the full code sample at the end of this section: </p> </section> |
129 the full code sample at the end of this section: </p> </section> |
120 <section><title>Example</title> <p>The following code shows an example of |
130 <section><title>Example</title> <p>The following code shows an example of |
121 a full implementation of the dialog creator file: </p> <codeblock id="GUID-314673F2-BBA0-56C0-A76D-07862BB4592F" xml:space="preserve">// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
131 a full implementation of the dialog creator file: </p> <codeblock id="GUID-314673F2-BBA0-56C0-A76D-07862BB4592F" |
122 // All rights reserved. |
132 xml:space="preserve">#include "refdialogcreator.h" |
123 // This component and the accompanying materials are made available |
133 #include <ecom/implementationproxy.h> |
124 // under the terms of the License "Symbian Foundation License v1.0" |
134 #include <apaid.h> |
125 // which accompanies this distribution, and is available |
135 #include <apgcli.h> |
126 // at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html". |
136 #include <ups/promptrequest.h> |
127 // |
137 #include <swi/sisregistrypackage.h> |
128 // Initial Contributors: |
138 #include <swi/sisregistrysession.h> |
129 // Nokia Corporation - initial contribution. |
139 #include <scs/nullstream.h> |
130 |
140 #include <s32mem.h> |
131 // refdialogcreator.cpp |
|
132 |
|
133 |
|
134 #include "refdialogcreator.h" |
|
135 #include <ecom/implementationproxy.h> |
|
136 #include <apaid.h> |
|
137 #include <apgcli.h> |
|
138 #include <ups/promptrequest.h> |
|
139 #include <swi/sisregistrypackage.h> |
|
140 #include <swi/sisregistrysession.h> |
|
141 #include <scs/nullstream.h> |
|
142 #include <s32mem.h> |
|
143 |
141 |
144 static const TUint KRefDialogCreatorImplementationId = 0x10283694; |
142 static const TUint KRefDialogCreatorImplementationId = 0x10283694; |
145 |
143 |
146 static const TUint KRefNotifierImplementationId = 0x1028369B; |
144 static const TUint KRefNotifierImplementationId = 0x1028369B; |
147 |
145 |
247 iPromptData = CPromptData::NewL(); |
245 iPromptData = CPromptData::NewL(); |
248 |
246 |
249 // Only one state at the moment but more should be |
247 // Only one state at the moment but more should be |
250 // added for long running operators e.g. querying the SIS registry |
248 // added for long running operators e.g. querying the SIS registry |
251 // or resolving the client entity. |
249 // or resolving the client entity. |
252 ResolveClientNameL(iRequest->ClientSid()); |
250 ResolveClientNameL(iRequest->ClientSid()); |
253 |
251 |
254 // Get the vendor name for the client process |
252 // Get the vendor name for the client process |
255 ResolveVendorNameL(iRequest->ClientVid()); |
253 ResolveVendorNameL(iRequest->ClientVid()); |
256 |
254 |
257 // Server / Service localized names generated in notifier plug-in. |
255 // Server / Service localized names generated in notifier plug-in. |
258 iPromptData->iServerSid = iRequest->ServerSid(); |
256 iPromptData->iServerSid = iRequest->ServerSid(); |
259 iPromptData->iServiceId = iRequest->ServiceId(); |
257 iPromptData->iServiceId = iRequest->ServiceId(); |
260 |
258 |
261 // Different dialog text is displayed depending on whether the client application |
259 // Different dialog text is displayed depending on whether the client application |
262 // is signed. |
260 // is signed. |
263 // N.B. Protected SID is assumed to be signed or included at ROM build. |
261 // N.B. Protected SID is assumed to be signed or included at ROM build. |
264 if (iRequest->IsClientSidProtected()) iPromptData->iFlags |= ETrustedClient; |
262 if (iRequest->IsClientSidProtected()) iPromptData->iFlags |= ETrustedClient; |
265 |
263 |
266 // Use the options specified by the policy |
264 // Use the options specified by the policy |
267 iPromptData->iOptions = iPolicy->Options(); |
265 iPromptData->iOptions = iPolicy->Options(); |
268 |
266 |
269 // Add the descriptions of the fingerprints. This could be used |
267 // Add the descriptions of the fingerprints. This could be used |
270 // to allow the user to grant access to all destinations |
268 // to allow the user to grant access to all destinations |
271 // or a single destination. |
269 // or a single destination. |
272 TInt count = iFingerprints->Count(); |
270 TInt count = iFingerprints->Count(); |
273 for (TInt i = 0; i < count; ++i) |
271 for (TInt i = 0; i < count; ++i) |
274 { |
272 { |
275 HBufC* description = (*iFingerprints)[i]->Description().AllocLC(); |
273 HBufC* description = (*iFingerprints)[i]->Description().AllocLC(); |
276 iPromptData->iDescriptions.AppendL(description); |
274 iPromptData->iDescriptions.AppendL(description); |
277 CleanupStack::Pop(description); |
275 CleanupStack::Pop(description); |
278 } |
276 } |
279 |
277 |
280 User::RequestComplete(iClientStatus, KErrNone); |
278 User::RequestComplete(iClientStatus, KErrNone); |
281 // DisplayDialog is invoked by the UPS, this just verifies |
279 // DisplayDialog is invoked by the UPS, this just verifies |
314 // The Always or Never option was selected so return the fingerprint |
312 // The Always or Never option was selected so return the fingerprint |
315 // for the new decision record. |
313 // for the new decision record. |
316 // |
314 // |
317 // In this implementation a copy of the original fingerprint is returned. However, |
315 // In this implementation a copy of the original fingerprint is returned. However, |
318 // it is permitted to return a different fingerprint e.g. a modifier description. |
316 // it is permitted to return a different fingerprint e.g. a modifier description. |
319 if (iPromptResult.iDestination >= 0 && iPromptResult.iDestination < iFingerprints->Count()) |
317 if (iPromptResult.iDestination >= 0 && iPromptResult.iDestination < iFingerprints->Count()) |
320 { |
318 { |
321 *iFingerprint = (*iFingerprints)[iPromptResult.iDestination]; |
319 *iFingerprint = (*iFingerprints)[iPromptResult.iDestination]; |
322 } |
320 } |
323 else |
321 else |
324 { |
322 { |
331 } |
329 } |
332 |
330 |
333 void CRefDialogCreator::ResolveVendorNameL(const TVendorId& aVid) |
331 void CRefDialogCreator::ResolveVendorNameL(const TVendorId& aVid) |
334 /** |
332 /** |
335 Looks up the localized vendor name for the client process and writes |
333 Looks up the localized vendor name for the client process and writes |
336 this to iPromptData->iVendorName. |
334 this to iPromptData->iVendorName. |
337 |
335 |
338 Typically, this would be resolved from the SIS registry or a lookup table. |
336 Typically, this would be resolved from the SIS registry or a lookup table. |
339 |
337 |
340 @param aVid The vendor id of the client process. |
338 @param aVid The vendor id of the client process. |
341 */ |
339 */ |
342 { |
340 { |
343 if (iPromptData->iVendorName.Length() != 0) |
341 if (iPromptData->iVendorName.Length() != 0) |
344 { |
342 { |
345 // already obtained vendor name from SIS registry |
343 // already obtained vendor name from SIS registry |
346 return; |
344 return; |
347 } |
345 } |
348 |
346 |
349 if (aVid.iId == 0x70000001) |
347 if (aVid.iId == 0x70000001) |
350 { |
348 { |
351 _LIT(KSymbian, "Symbian Foundation"); |
349 _LIT(KSymbian, "Symbian Foundation"); |
352 iPromptData->iVendorName.Create(KSymbian); |
350 iPromptData->iVendorName.Create(KSymbian); |
353 } |
351 } |
354 else |
352 else |
355 { |
353 { |
356 _LIT(KUnknown, "Unknown vendor"); |
354 _LIT(KUnknown, "Unknown vendor"); |
357 iPromptData->iVendorName.Create(KUnknown); |
355 iPromptData->iVendorName.Create(KUnknown); |
358 } |
356 } |
359 } |
357 } |
360 |
358 |
361 void CRefDialogCreator::ResolveClientNameL(const TSecureId& aSid) |
359 void CRefDialogCreator::ResolveClientNameL(const TSecureId& aSid) |
362 /** |
360 /** |
387 |
385 |
388 // If the process has exited then it's o.k. to leave. |
386 // If the process has exited then it's o.k. to leave. |
389 if (! found) |
387 if (! found) |
390 { |
388 { |
391 RProcess clientProcess; |
389 RProcess clientProcess; |
392 User::LeaveIfError(clientProcess.Open(iRequest->ClientProcessId())); |
390 User::LeaveIfError(clientProcess.Open(iRequest->ClientProcessId())); |
393 CleanupClosePushL(clientProcess); |
391 CleanupClosePushL(clientProcess); |
394 iPromptData->iClientName.Create(clientProcess.FileName()); |
392 iPromptData->iClientName.Create(clientProcess.FileName()); |
395 CleanupStack::PopAndDestroy(&clientProcess); |
393 CleanupStack::PopAndDestroy(&clientProcess); |
396 } |
394 } |
397 } |
395 } |
398 |
396 |
399 TBool CRefDialogCreator::ResolveClientNameFromAppArcL(const TSecureId& aSid) |
397 TBool CRefDialogCreator::ResolveClientNameFromAppArcL(const TSecureId& aSid) |
452 |
450 |
453 Swi::CSisRegistryPackage* p(0); |
451 Swi::CSisRegistryPackage* p(0); |
454 TRAPD(err, p = r.SidToPackageL(TUid::Uid(aSid.iId))); |
452 TRAPD(err, p = r.SidToPackageL(TUid::Uid(aSid.iId))); |
455 if (err == KErrNone) |
453 if (err == KErrNone) |
456 { |
454 { |
457 iPromptData->iClientName.Create(p->Name()); |
455 iPromptData->iClientName.Create(p->Name()); |
458 iPromptData->iVendorName.Create(p->Vendor()); |
456 iPromptData->iVendorName.Create(p->Vendor()); |
459 found = ETrue; |
457 found = ETrue; |
460 delete p; |
458 delete p; |
461 } |
459 } |
462 CleanupStack::PopAndDestroy(&r); |
460 CleanupStack::PopAndDestroy(&r); |
463 return found; |
461 return found; |
464 } |
462 } |
465 |
463 |
466 // From CDialogCreator |
464 // From CDialogCreator |
467 void CRefDialogCreator::PrepareDialog( |
465 void CRefDialogCreator::PrepareDialog( |
468 const UserPromptService::CPromptRequest& aRequest, const CPolicy& aPolicy, |
466 const UserPromptService::CPromptRequest& aRequest, const CPolicy& aPolicy, |
469 const RPointerArray<CFingerprint>& aFingerprints, const CClientEntity* aClientEntity, |
467 const RPointerArray<CFingerprint>& aFingerprints, const CClientEntity* aClientEntity, |
470 const TAny* aEvalPrivateData, TRequestStatus& aStatus) |
468 const TAny* aEvalPrivateData, TRequestStatus& aStatus) |
471 { |
469 { |
472 aStatus = KRequestPending; |
470 aStatus = KRequestPending; |
473 iClientStatus = &aStatus; |
471 iClientStatus = &aStatus; |
474 |
472 |