Privacy Request API Tutorial

This topic describes how to use the Privacy Request API.

1. Create a Privacy Request API client. The code example below shows a simple implementation of an MLbsPrivacyRequestObserver subclass that uses the Privacy Request API. Such a class could be the basis of an observer class in a licensee client application.

   
   #ifndef CMYPRIVACYREQUESTLISTENER_H_
   #define CMYPRIVACYREQUESTLISTENER_H_
   
   #include <lbsprivacyrequest.h>
   #include <lbsloccommon.h>
   
   class CMyPrivacyRequestObserver : public MLbsPrivacyRequestObserver
   {
   
   public:
       static CMyPrivacyRequestObserver* NewL();
       virtual ~CMyPrivacyRequestObserver();
   
   // From MLbsPrivacyRequestObserver
   public:
       void OnPrivacyResponse(TLbsPrivacyRequestId aRequestId, const TLbsPrivacyResponse& aResponse, TInt aError);
       
   public:
       void VerifyPrivacyRequest(const TLbsExternalRequestInfo& aInfo);
       void NotifyPrivacyRequest(const TLbsExternalRequestInfo& aInfo);
       void CancelPrivacyRequest(TLbsPrivacyRequestId& aRequestId);
       void TimeoutPrivacyRequest(TLbsPrivacyRequestId& aRequestId);
   
   protected:
   CMyPrivacyRequestObserver();
   
   private:
       CLbsPrivacyRequest* iPrivacy;
       TLbsPrivacyRequestId iRequestId; // This demo client just stores a single request ID
       void ConstructL();
   };
   
   #endif /*CMYPRIVACYREQUESTLISTENER_H_*/
   

   The code below shows the creation of a CLbsPrivacyRequest object in the second phase constructor of the observer. The LBS subsystem is transient when it uses the Privacy Protocol Module. Creating an instance of CMyPrivacyRequestObserver does not cause the LBS subsystem to be started.

   
   CMyPrivacyRequestObserver* CMyPrivacyRequestObserver::NewL()
       {
       CMyPrivacyRequestObserver* listener = 
                     new (ELeave)CMyPrivacyRequestObserver();
   
       CleanupStack::PushL(listener);
       listener->ConstructL();
       CleanupStack::Pop(listener);
       return listener;
       }
   
   void CMyPrivacyRequestObserver::ConstructL()
       {
       iPrivacy = CLbsPrivacyRequest::NewL(*this);
       }
   

2. Write code to send a privacy verification request. The licensee client receives a privacy verification request from the network or a local application. The privacy request requires user verification. The following describes the steps the licensee client application performs for a privacy verification request:
   1. 
      The client creates an instance of class TLbsExternalRequestInfo (or TLbsExternalRequestInfo2) and populates it with the privacy request data. For a local privacy request, the client must call TLbsExternalRequestInfo::SetRequestSource() with a parameter of TLbsExternalRequestInfo::ERequestSourceLocal. The client must have the capabilities Location and ReadDeviceData. For a privacy request from the network, a parameter of TLbsExternalRequestInfo::ERequestSourceNetwork must be passed. The client must have the capabilities Location, ReadDeviceData and NetworkServices. The client creates an instance of an object of class TLbsPrivacyRequest and defines the privacy advice and privacy action. For a privacy verification request, the privacy advice is set to TLbsPrivacyRequest::ERequestAdviceVerify.
   2. 
      The client calls CLbsPrivacyRequest::NewPrivacyRequest(). This method is asynchronous and non-blocking. The client can process multiple privacy requests by calling NewPrivacyRequest() multiple times. Each request is identified by a unique request ID which is returned by LBS as an output parameter. The LBS subsystem is started if it is not running when a request is made.
   3. 
      When the privacy request is completed, the method MLbsPrivacyRequestObserver::OnPrivacyResponse() is called on the client observer. The licensee client sends the privacy response to the local application or the network (whichever made the privacy request).
   The following code example demonstrates how to use the Privacy Request API to verify a privacy request.

   
   // In this example, the TLbsExternalRequestInfo object
   // is created by the client application
   void CMyPrivacyRequestObserver::VerifyPrivacyRequest(const TLbsExternalRequestInfo& aInfo)
       {
       
       // Example shows how to set the privacy advice to verify the request
       // and set the privacy action to reject if there is no privacy response
       
       TLbsPrivacyRequest privacy;
       privacy.SetRequestAdvice(TLbsPrivacyRequest::ERequestAdviceVerify);
       privacy.SetRequestAction(TLbsPrivacyRequest::ERequestActionReject);
       TInt err = iPrivacy->NewPrivacyRequest(iRequestId, privacy, aInfo);
       if (err != KErrNone)
           {
           // Error could be KErrArgument if incorrect parameters passed
           // or any other Symbian error code
           }
       }
   

   MLbsPrivacyRequestObserver::OnPrivacyResponse() is called to complete the request.

   
   void CMyPrivacyRequestObserver::OnPrivacyResponse(TLbsPrivacyRequestId aRequestId, const TLbsPrivacyResponse& aResponse, TInt aError)
       {
       // Forward privacy response to client then call CompleteRequest...
       iPrivacy->CompleteRequest(aRequestId, KErrNone);
       }
   
   

3. Write code to send a privacy notification request. The licensee client receives a privacy request from the network or a local application. The privacy request does not require verification. The following describes the steps the licensee client application performs for a privacy notification request:
   1. 
      The client creates an instance of class TLbsExternalRequestInfo as described for privacy verification in the previous section. The client creates an instance of an object of class TLbsPrivacyRequest and defines the privacy advice and privacy action. For a privacy notification request, the privacy advice is set to TLbsPrivacyRequest::ERequestAdviceNotify.
   2. 
      The client calls CLbsPrivacyRequest::NewPrivacyRequest(). This method is asynchronous and non-blocking. The client can process multiple privacy requests by calling NewPrivacyRequest() multiple times. Each request is identified by a unique request ID which must be passed as a parameter. The LBS subsystem is started if it is not running when a request is made.
   The following code example demonstrates how to use the Privacy Request API to notify a privacy request.

   
   // In this example, the TLbsExternalRequestInfo object
   // is created by the client application
   void CMyPrivacyRequestObserver::NotifyPrivacyRequest(const TLbsExternalRequestInfo& aInfo)
       {
       
       // Example shows how to set the privacy advice to verify the request
       // and set the privacy action to reject if there is no privacy response
       
       TLbsPrivacyRequest privacy;
       privacy.SetRequestAdvice(TLbsPrivacyRequest::ERequestAdviceNotify);
       privacy.SetRequestAction(TLbsPrivacyRequest::ERequestActionReject);
       TInt err = iPrivacy->NewPrivacyRequest(iRequestId, privacy, aInfo);
       if (err != KErrNone)
           {
           // Error could be KErrArgument if incorrect parameters passed
           // or any other Symbian error code
           }
       }
   

   MLbsPrivacyRequestObserver::OnPrivacyResponse() is called to complete the request.
4. Write code to cancel a pending privacy verification request. The code example below shows how a client can cancel an outstanding request by calling CLbsPrivacyRequest::CompleteRequest().

   
   void CMyPrivacyRequestObserver::CancelPrivacyRequest(TLbsPrivacyRequestId& aRequestId)
       {
       iPrivacy->CompleteRequest(aRequestId, KErrCancel);
       }
   

5. Write code to send a timeout notification. The code example below shows how a request can be timed out. The timeout is sent to the LBS subsystem by calling CLbsPrivacyRequest::CompleteRequest().

   
   void CMyPrivacyRequestObserver::TimeoutPrivacyRequest(TLbsPrivacyRequestId& aRequestId)
       {
           iPrivacy->CompleteRequest(aRequestId, KErrTimedOut);
       }
   

6. Define client capabilities. The following is a simple MMP file for the client. The header files for the Privacy Request API are located at \epoc32\include\lbs and the client links to lbsprivacyrequest.lib. All clients require the capabilities Location and ReadDeviceData. Clients that create network privacy requests also require the capability NetworkServices.

   
   TARGET          PrivacyRequestAPI_Example.exe
   TARGETTYPE      exe
   UID             0 0x12345678
   
   USERINCLUDE     ..\inc
   SYSTEMINCLUDE   \epoc32\include \epoc32\include\lbs
   
   SOURCEPATH      ..\src
   SOURCE          PrivacyRequestAPI_Example.cpp CMyPrivacyRequestListener.cpp
   
   LIBRARY         euser.lib lbsprivacyrequest.lib
   
   CAPABILITY Location ReadDeviceData NetworkServices