FCL/sftools/depl/docscontent: comparison Symbian3/PDK/Source/GUID-A8130D83-E684-5B6C-BDFE-EB6EE3CD49E8.dita

equal deleted inserted replaced

-:4816d766a08a
+:f345bda72bc4
 <?xml version="1.0" encoding="utf-8"?>
-<!--Arbortext, Inc., 1988-2004, v.4002-->
-<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
-"concept.dtd">
 <!-- 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-A8130D83-E684-5B6C-BDFE-EB6EE3CD49E8" xml:lang="en"><title>Writing
-a UPS Dialog Creator</title>
+a UPS Dialog Creator</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<prolog>
+<section id="GUID-9383005F-53E7-465E-A10E-8A781EDB52E2"><title>Introduction</title> <p>Dialog
-<metadata>
+creators are ECom plug-ins that device creators can write to generate the
-<keywords></keywords>
+dialogs containing prompts for phone users. </p> <p>The plug-in has an API
-</metadata>
+that consists of two asynchronous functions: </p> <ul>
-</prolog>
-<conbody>
-<section><title>Introduction</title> <p>Dialog creators are EComplug-ins that
-device creators can write to generate the dialogs containing prompts for phone
-users. </p> <p>The plug-in has an API that consists of two asynchronous functions: </p> <ul>
 <li id="GUID-96CBCE79-4F5D-5F87-AC6B-C366346447AB"><p>The <codeph>PrepareDialog()</codeph> function.
 This function is called first by the UPS server. It enables the dialog creator
 to query other system servers such as AppArc or the SIS registry to retrieve
 additional information to display in the dialog. For example it might query
 the SIS registry using the client application’s secure id. </p> </li>
 the option selected by the user and, if applicable, the fingerprint for a
 new decision record. </p> </li>
 </ul> <p>The UPS displays only one prompt at a time so it is possible for
 there to be a delay between calling the function to prepare the dialog and
 the function to display the dialog. It is also possible for other dialogs
-to be displayed between the dialog being prepared and its being displayed. </p> <p>Both <codeph>PrepareDialog()</codeph> and <codeph>DisplayDialog()</codeph
+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>.
-> are asynchronous and must support cancellation through <codeph>CActive::Cancel</codeph>.
 If either function is cancelled, the dialog creator instance is destroyed
 without calling further methods. </p> <p>The work split between <codeph>PrepareDialog()</codeph> and <codeph>DisplayDialog()</codeph> described
 above is a recommendation, and some of the functionality could be implemented
 directly in the notifier implementation. </p> <p>In the example given in this
 document, the functionality for dialogs is implemented separately from the
 functionality for policy evaluators. This allows multiple policy evaluators
 to share common UI code. However, it is possible to deliver policy evaluator
 and dialog creator plug-ins in the same DLL. </p> </section>
-<section><title>Procedure</title> <p>Dialog creators implement the <codeph>CDialogCreator</codeph> interface.
+<section id="GUID-38974132-906B-45C9-8C38-0C9D0F396D15"><title>Procedure</title> <p>Dialog
-This section shows how to implement the functions that prepare and display
+creators implement the <codeph>CDialogCreator</codeph> interface. This section
-the user prompt. </p> <ol id="GUID-0F29F8B7-F303-5D42-BB95-A32B1FE13A9A">
+shows how to implement the functions that prepare and display the user prompt. </p> <ol id="GUID-0F29F8B7-F303-5D42-BB95-A32B1FE13A9A">
 <li id="GUID-9FDDAD1F-4B9A-516A-8A00-0C331F38C4CA"><p>Prepare a dialog using
 the <xref href="GUID-2308E2F4-A878-3B0A-951B-EFC4908AD9BB.dita"><apiname>PrepareDialog()</apiname></xref> function. </p> </li>
 <li id="GUID-45C16A52-A05E-545A-AB3A-967CCA35BB15"><p>Display the dialog using
 the <xref href="GUID-E6C3B0F0-43A7-3656-946B-5CFE97DCFC80.dita"><apiname>DisplayDialog()</apiname></xref> function. </p> </li>
 </ol> <p>The Dialog Creator plug-in creates a dialog prompt in cases where
 no previous decision is found in the decision database. </p> <p><b> Preparing
 the dialog</b> </p> <p>The parameters to <codeph>PrepareDialog()</codeph> are
 mostly <codeph>const</codeph> pointers and references to the data that has
 already been generated by the UPS or policy evaluator. </p> <p>The following
-table describes the parameters for the <codeph>PrepareDialog()</codeph> function: </p> <table
+table describes the parameters for the <codeph>PrepareDialog()</codeph> function: </p> <table id="GUID-6D139216-B6A8-55A1-8D9B-C15134198198">
-id="GUID-6D139216-B6A8-55A1-8D9B-C15134198198">
 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
 <thead>
 <row>
 <entry>Parameter</entry>
 <entry>Description</entry>
 <entry><p>The request status used to contain completion information for the
 function. </p> </entry>
 </row>
 </tbody>
 </tgroup>
-</table> <p><note></note> The UPS does not allow any responses to be returned
+</table> <p><note/> The UPS does not allow any responses to be returned
 to the system server except those defined in the UPS policy file. If the dialog
 creator returns an option that was not specified in the policy, the request
 is rejected and <codeph>EUpsDecNo</codeph> is returned. </p><p>Your implementation
 can assume that the pointers remain valid until after <codeph>DisplayDialog()</codeph> has
 been called. </p><p>The <codeph>PrepareDialog()</codeph> function sets values. </p><p>The<codeph> DoPrepareDialogL()</codeph> function
 </ul> <p>In the example at the end of this section, the <codeph>DisplayDialog()</codeph> function
 sets values. The <codeph>DoDisplayDialogL()</codeph> function calls the notifier
 framework to display the dialogs. The <codeph>DoDisplayDialogL()</codeph> function
 is called through a <codeph>switch</codeph> statement, which can be seen in
 the full code sample at the end of this section: </p> </section>
-<section><title>Example</title> <p>The following code shows an example of
+<section id="GUID-9C1BBD11-028A-4853-98FC-BF4B881BE2AF"><title>Example</title> <p>The
-a full implementation of the dialog creator file: </p> <codeblock id="GUID-314673F2-BBA0-56C0-A76D-07862BB4592F"
+following code shows an example of a full implementation of the dialog creator
-xml:space="preserve">#<?Pub Caret1?>include "refdialogcreator.h"
+file: </p> <codeblock id="GUID-314673F2-BBA0-56C0-A76D-07862BB4592F" xml:space="preserve">#include "refdialogcreator.h"
-#include &lt;ecom/implementationproxy.h>
+#include &lt;ecom/implementationproxy.h&gt;
-#include &lt;apaid.h>
+#include &lt;apaid.h&gt;
-#include &lt;apgcli.h>
+#include &lt;apgcli.h&gt;
-#include &lt;ups/promptrequest.h>
+#include &lt;ups/promptrequest.h&gt;
-#include &lt;swi/sisregistrypackage.h>
+#include &lt;swi/sisregistrypackage.h&gt;
-#include &lt;swi/sisregistrysession.h>
+#include &lt;swi/sisregistrysession.h&gt;
-#include &lt;scs/nullstream.h>
+#include &lt;scs/nullstream.h&gt;
-#include &lt;s32mem.h>
+#include &lt;s32mem.h&gt;
 static const TUint KRefDialogCreatorImplementationId = 0x10283694;
 static const TUint KRefNotifierImplementationId = 0x1028369B;
 @return A pointer to the new reference dialog creator object.
 */
 {
 CRefDialogCreator* self = new (ELeave)CRefDialogCreator();
 CleanupStack::PushL(self);
-self->ConstructL();
+self-&gt;ConstructL();
 CleanupStack::Pop(self);
 return self;
 }
 static const TImplementationProxy ImplementationTable[] =
 iPromptData = CPromptData::NewL();
 // Only one state at the moment but more should be
 // added for long running operators e.g. querying the SIS registry
 // or resolving the client entity.
-ResolveClientNameL(iRequest->ClientSid());
+ResolveClientNameL(iRequest-&gt;ClientSid());
 // Get the vendor name for the client process
-ResolveVendorNameL(iRequest->ClientVid());
+ResolveVendorNameL(iRequest-&gt;ClientVid());
 // Server / Service localized names generated in notifier plug-in.
-iPromptData->iServerSid = iRequest->ServerSid();
+iPromptData-&gt;iServerSid = iRequest-&gt;ServerSid();
-iPromptData->iServiceId = iRequest->ServiceId();
+iPromptData-&gt;iServiceId = iRequest-&gt;ServiceId();
 // Different dialog text is displayed depending on whether the client application
 // is signed.
 // N.B. Protected SID is assumed to be signed or included at ROM build.
-if (iRequest->IsClientSidProtected()) iPromptData->iFlags |= ETrustedClient;
+if (iRequest-&gt;IsClientSidProtected()) iPromptData-&gt;iFlags |= ETrustedClient;
 // Use the options specified by the policy
-iPromptData->iOptions = iPolicy->Options();
+iPromptData-&gt;iOptions = iPolicy-&gt;Options();
 // Add the descriptions of the fingerprints. This could be used
 // to allow the user to grant access to all destinations
 // or a single destination.
-TInt count = iFingerprints->Count();
+TInt count = iFingerprints-&gt;Count();
 for (TInt i = 0; i &lt; count; ++i)
 {
-HBufC* description = (*iFingerprints)[i]->Description().AllocLC();
+HBufC* description = (*iFingerprints)[i]-&gt;Description().AllocLC();
-iPromptData->iDescriptions.AppendL(description);
+iPromptData-&gt;iDescriptions.AppendL(description);
 CleanupStack::Pop(description);
 }
 User::RequestComplete(iClientStatus, KErrNone);
 // DisplayDialog is invoked by the UPS, this just verifies
 // The Always or Never option was selected so return the fingerprint
 // for the new decision record.
 //
 // In this implementation a copy of the original fingerprint is returned. However,
 // it is permitted to return a different fingerprint e.g. a modifier description.
-if (iPromptResult.iDestination >= 0 &amp;&amp; iPromptResult.iDestination &lt; iFingerprints->Count())
+if (iPromptResult.iDestination &gt;= 0 &amp;&amp; iPromptResult.iDestination &lt; iFingerprints-&gt;Count())
 {
 *iFingerprint = (*iFingerprints)[iPromptResult.iDestination];
 }
 else
 {
 }
 void CRefDialogCreator::ResolveVendorNameL(const TVendorId&amp; aVid)
 /**
 Looks up the localized vendor name for the client process and writes
-this to iPromptData->iVendorName.
+this to iPromptData-&gt;iVendorName.
 Typically, this would be resolved from the SIS registry or a lookup table.
 @param aVid    The vendor id of the client process.
 */
 {
-if (iPromptData->iVendorName.Length() != 0)
+if (iPromptData-&gt;iVendorName.Length() != 0)
 {
 // already obtained vendor name from SIS registry
 return;
 }
 if (aVid.iId == 0x70000001)
 {
-_LIT(KSymbian, "Symbian Foundation");
+_LIT(KSymbian, "XYZ Vendor");
-iPromptData->iVendorName.Create(KSymbian);
+iPromptData-&gt;iVendorName.Create(KSymbian);
 }
 else
 {
 _LIT(KUnknown, "Unknown vendor");
-iPromptData->iVendorName.Create(KUnknown);
+iPromptData-&gt;iVendorName.Create(KUnknown);
 }
 }
 void CRefDialogCreator::ResolveClientNameL(const TSecureId&amp; aSid)
 /**
 // If the process has exited then it's o.k. to leave.
 if (! found)
 {
 RProcess clientProcess;
-User::LeaveIfError(clientProcess.Open(iRequest->ClientProcessId()));
+User::LeaveIfError(clientProcess.Open(iRequest-&gt;ClientProcessId()));
 CleanupClosePushL(clientProcess);
-iPromptData->iClientName.Create(clientProcess.FileName());
+iPromptData-&gt;iClientName.Create(clientProcess.FileName());
 CleanupStack::PopAndDestroy(&amp;clientProcess);
 }
 }
 TBool CRefDialogCreator::ResolveClientNameFromAppArcL(const TSecureId&amp; aSid)
 CleanupStack::PushL(info);
 err = apa.GetAppInfo(*info, TUid::Uid(aSid));
 if (err == KErrNone)
 {
-iPromptData->iClientName.Close();
+iPromptData-&gt;iClientName.Close();
-iPromptData->iClientName.Create(info->iCaption);
+iPromptData-&gt;iClientName.Create(info-&gt;iCaption);
 found = ETrue;
 }
 else if (err != KErrNotFound)
 {
 User::Leave(err);
 Swi::CSisRegistryPackage* p(0);
 TRAPD(err, p = r.SidToPackageL(TUid::Uid(aSid.iId)));
 if (err == KErrNone)
 {
-iPromptData->iClientName.Create(p->Name());
+iPromptData-&gt;iClientName.Create(p-&gt;Name());
-iPromptData->iVendorName.Create(p->Vendor());
+iPromptData-&gt;iVendorName.Create(p-&gt;Vendor());
 found = ETrue;
 delete p;
 }
 CleanupStack::PopAndDestroy(&amp;r);
 return found;
 }
 // From CDialogCreator
 void CRefDialogCreator::PrepareDialog(
 const UserPromptService::CPromptRequest&amp; aRequest, const CPolicy&amp; aPolicy,
-const RPointerArray&lt;CFingerprint>&amp; aFingerprints, const CClientEntity* aClientEntity,
+const RPointerArray&lt;CFingerprint&gt;&amp; aFingerprints, const CClientEntity* aClientEntity,
 const TAny* aEvalPrivateData, TRequestStatus&amp; aStatus)
 {
 aStatus = KRequestPending;
 iClientStatus = &amp;aStatus;
 TRequestStatus* status = &amp;iStatus;
 SetActive();
 User::RequestComplete(status, KErrNone);
 }
 </codeblock> </section>
-</conbody>
+</conbody></concept>
-</concept>
-<?Pub *0000019622?>

changeset 5	f345bda72bc4
parent 3	46218c8b8afa
child 14	578be2adaf3e