<?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-55629D12-06C9-412C-86FE-442577156A3B" xml:lang="en"><title>Implementing

the CPosPrivacyNotifier Subclass</title><shortdesc>To use the Privacy Query and Notification API to create a notifier

a licensee must first implement a single notifier class that derives from

the Privacy Query and Notification API base class <apiname>CPosPrivacyNotifier</apiname>.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita"><apiname>CPosPrivacyNotifier</apiname></xref> subclass must implement the

virtual functions of the base class:     </p>

<ul>

<li><p><xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-33E317F9-A8C0-34AF-B17A-72D46B2E4DBD"><apiname>CPosPrivacyNotifier::HandleNewRequestL()</apiname></xref></p></li>

<li><p><xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-3417B07B-DE69-3719-8634-B979CBA77AFE"><apiname>CPosPrivacyNotifier::HandleRequestCancelled()</apiname></xref></p></li>

<li><p><xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-6D3C8687-6FEC-34FF-9846-1508C9DF4E72"><apiname>CPosPrivacyNotifier::HandleAllRequestsCancelled()</apiname></xref></p></li>

</ul>

<section>       <title>Implementing HandleNewRequestL()</title>       <p>New

privacy verification query and notification requests are received by the notifier

through <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-33E317F9-A8C0-34AF-B17A-72D46B2E4DBD"><apiname>CPosPrivacyNotifier::HandleNewRequestL()</apiname></xref>. The example

code below shows how the notifier handles requests sequentially by simply

calling a helper function <xref href="GUID-BEB6299A-9BA4-36BB-8E43-52855B753A04.dita"><apiname>HandleNextRequestL()</apiname></xref> to get the

next request.</p>     <codeblock xml:space="preserve">void CMyPrivacyNotifier::HandleNewRequestL(TPosQNRequestId /*aRequestId*/)

    {

    if (iIsBusy) // TBool flag which specifies if the notifier is already

        {        // handling a request. If it is, do nothing for now.

        return;

        }

    // Handle the request

    HandleNextRequestL();

    }</codeblock></section>

<section><title>HandleNextRequestL() </title><p>The example code below shows

how the notifier gets the next request to be processed. The code shows how

the notifier: </p><ul>

<li><p>Gets an array of all waiting requests by calling <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-4E117090-89E5-33DA-AC4B-494906B4BAF9"><apiname>CPosPrivacyNotifier::GetRequestsL()</apiname></xref>. </p></li>

<li><p>Gets the first request in the array and sets it as the current request

by calling <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-A041F06C-8A22-37D3-B634-894AFE9B7FF0"><apiname>CPosPrivacyNotifier::SetCurrentRequestL()</apiname></xref>. </p></li>

<li><p>Checks if the request is a notification, and if so, checks if the request

type is supported by calling <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-22FFC3B2-A6B9-3501-AD89-1DB31027F53C"><apiname>CPosPrivacyNotifier::NotificationReason()</apiname></xref>.

If the request type is not supported the request is completed by calling <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-57739A9E-F6CD-3079-8B6F-9B80AAFE4D8B"><apiname>CPosPrivacyNotifier::CompleteRequest()</apiname></xref>. </p></li>

<li><p>Checks if the type of request is a privacy verification (<codeph>EQuery</codeph>)

or a notification (<codeph>ENotification</codeph>) and launches the appropriate

dialog for each case. </p><note><codeph>LauchQueryDialog()</codeph> and <codeph>LaunchNotificationDialog()</codeph> show

the dialogs. Dialog code varies between licensee platforms but it is important

that these methods do not launch modal dialogs. The methods must return quickly

and not wait for the dialogs to be dismissed. </note></li>

</ul><codeblock xml:space="preserve">void CMyPrivacyNotifier::HandleNextRequestL()

    {

    // Read the next request

    RArray<TPosQNRequestId> requests;

    CleanupClosePushL(requests);

    GetRequestsL(requests);

    // Choose next request to handle

    TBool requestFound = EFalse;

    while (!requestFound)

        {

        if (requests.Count() == 0)

            { // There are no requests to handle. Do nothing.

            CleanupStack::PopAndDestroy(); // requests

            return;

            }

        // Read information about the active request

        iActiveRequest = requests[0];

        SetCurrentRequestL(iActiveRequest);

        // In case of notification request, check that notification reason is

        // supported, otherwise complete the request with KErrNotSupported.

        if (RequestTypeL(iActiveRequest) == ENotification &&

            !(NotificationReason() == EPosDecisionByRequestSource ||

            NotificationReason() == EPosVerificationTimeout))

            { // The notification reason is not supported by the UI.

            CompleteRequest(iActiveRequest, KErrNotSupported);

            requests.Remove(0);

            }

        else

            {

            requestFound = ETrue;

            }

        }

    CleanupStack::PopAndDestroy(); // requests

    iIsBusy = ETrue;

    CDesCArrayFlat* requestors = new (ELeave) CDesCArrayFlat

        (KRequestorGranularity);

    CleanupStack::PushL(requestors);

    TInt nofRequestors = RequestorCountL();

    for (TInt I = 0; I < nofRequestors; I++)

        {

        CPosRequestor* requestor = RequestorLC(I);

        requestors->AppendL(requestor->RequestorIdString());

        CleanupStack::PopAndDestroy(requestor);

        }

    // Check whether the request is a query or a notification

    if (RequestTypeL(iActiveRequest) == EQuery)

        {

        LaunchQueryDialogL(requestors); // takes array ownership

        }

    else // RequestTypeL(iActiveRequest) == ENotification

        {

        LaunchNotificationDialogL(requestors); // takes array ownership

        }

    CleanupStack::Pop(requestors);

    }</codeblock></section>

<section><title>Implementing a method to handle dialog closure</title><p>When

the mobile device user has responded to the dialog, the notifier must send

a response back to the LBS subsystem. In the example code below, the method <codeph>DialogDismissed()</codeph> is

called when the dialog is closed. The type of request (<codeph>EQuery</codeph> or <codeph>ENotification</codeph>)

and the reason why the dialog was closed is passed as an input parameter to

the method. </p><note>It is important to note that <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-57739A9E-F6CD-3079-8B6F-9B80AAFE4D8B"><apiname>CPosPrivacyNotifier::CompleteRequest()</apiname></xref> must

be called for both privacy verification (query) requests and privacy notification

requests.</note><p>Note also how requests are handled sequentially in the

code: CPosPrivacyNotifier::HandleNextRequest() is called to process the next

request only when the current request is completed.</p><codeblock xml:space="preserve">void CMyPrivacyNotifier::DialogDismissed(TRequestType aRequestType, TInt aDismissReason)

    {

    iIsBusy = EFalse;

    // Complete the request with correct completion code.

    TInt completionCode = KErrNone;

    if (aRequestType == EQuery)

        {

        switch (aDismissReason)

            {

            case EUserChooseAccept : completionCode = KErrNone; break;

            case EUserChooseReject : completionCode = KErrAccessDenied; break;

            case EDialogTimedOut : completionCode = KErrTimedOut; break;

            default : completionCode = KErrGeneral;

            }

        }

    else // aRequestType == ENotification

        {

        switch (aDismissReason)

            {

            case EUserPressedOk : completionCode = KErrNone; break;

            case EDialogTimedOut : completionCode = KErrTimedOut; break;

            default : completionCode = KErrGeneral;

            }

        }

    CompleteRequest(iActiveRequest, completionCode);

    // Handle the next request

    HandleNextRequest();

    }

// Non leaving method for handling the next request

void CMyPrivacyNotifier::HandleNextRequest()

    {

    TRAPD(err, HandleNextRequestL());

    if (err)

        {

        CompleteAllRequests(err);

        }

    }</codeblock></section>

<section><title>Implementing HandleRequestCancelled() </title><p>A privacy

request can be cancelled by the network. The LBS subsystem calls <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-3417B07B-DE69-3719-8634-B979CBA77AFE"><apiname>CPosPrivacyNotifier::HandleRequestCancelled()</apiname></xref> on

the notifier to cancel the request. The code example below shows an implementation. </p><codeblock xml:space="preserve">void CMyPrivacyNotifier::HandleRequestCancelled(TPosQNRequestId aRequestId)

    {

    switch (CancelReason())

        {

        case EPosCancelReasonTimeout:

            // Notify the user that the query timed out.

            break;

        default: // Do nothing

            break;

        }

    // We only need to do anything if the request is the one which is currently

    // handled.

    if (iActiveRequest == aRequestId)

        {

        // Close the active dialog

        DismissDialog();

        HandleNextRequest();

        }

    }</codeblock></section>

<section><title>Implementing HandleAllRequestsCancelled()</title><p>The notifier

must implement this method to allow all outstanding requests to be cancelled. </p><codeblock xml:space="preserve">void CMyPrivacyNotifier::HandleAllRequestCancelled()

    {

    // Close the active dialog

    DismissDialog();

    }</codeblock></section>

</conbody></concept>