Network Privacy API Tutorial

This document describes how to use the Network Privacy API.

1. 
   Listen for privacy and location requests received from the network.
2. 
   Use the Network Privacy API to forward privacy requests to the LBS subsystem.
3. 
   Receive responses to privacy requests from the LBS subsystem via the Network Privacy API and return them to the network.
4. 
   If a privacy request is accepted, forward the subsequent location request to a component in the licensee domestic OS so that a position fix can be obtained.
5. To use the Network Privacy API create a Network Privacy API Client.
   1. 
      Define a Network Privacy API MPosVerificationObserver subclass The code example below shows a simple implementation of an MPosVerificationObserver subclass that uses the Network Privacy API. Such a class could be the basis of an observer class in a licensee client application.

      #ifndef CMYNETWORKLISTENER_H_
      #define CMYNETWORKLISTENER_H_
      
      #include <EPos_MPosVerificationObserver.h>
      #include <EPos_CPosNetworkPrivacy.h>
      #include <EPos_CPosGSMPrivacyRequestInfo.h>
      
      class CMyNetworkObserver : public MPosVerificationObserver
      {
      
      public:
          static CMyNetworkObserver* NewL();
      
      public:
          CMyNetworkObserver();
          virtual ~CMyNetworkObserver();
      
      public:
          void GSMVerifyPrivacyRequestL(const TDesC* aLCSClient, const TDesC* aRequestor,
                                     CPosNetworkPrivacy::TRequestDecision aTimeoutAction);
          void CancelPrivacyRequestL(TInt aRequestId, CPosNetworkPrivacy::TCancelReason aCancelReason);
          void GSMNotifyLocationRequestL(TDesC* aLCSClient, TDesC* aRequestor);
          void GSMTimeoutPrivacyRequestL(const TDesC* aLCSClient, const TDesC* aRequestor, 
                                       TInt aRequestId, CPosNetworkPrivacy::TRequestDecision aTimeoutAction);
      
          
      public:
          // Method from MPosVerificationObserver
          void HandleVerifyComplete(TInt aRequestId, TInt aCompletionCode);
          
      private:
          CPosNetworkPrivacy* iPrivacy;
          TInt iRequestId; // This demo client just stores a single request ID
          void ConstructL();
      
      };
      
      
      #endif /*CMYNETWORKLISTENER_H_*/
      

   2. 
      Create an instance of CPosNetworkPrivacy in the client constructor The code below shows the creation of a CPosNetworkPrivacy object in the second phase constructor of the observer. Note that in the Standalone Privacy Mode configuration the LBS subsystem is transient, and creating an instance of this class does not cause the LBS subsystem to be started.

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

6. Write code to send a privacy verification request. The licensee client receives a privacy verification request from the network. 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 CPosGSMPrivacyRequestInfo or CPosSUPLPrivacyRequestInfo. The class of object that the client creates depends on whether the privacy request was received from the network via GSM or via SUPL.
   2. 
      The client calls CPosNetworkPrivacy::VerifyPrivacyRequest(). This method is asynchronous and non-blocking. The client can process multiple privacy requests by calling VerifyPrivacyRequest() multiple times. Each request is identified by a unique request ID. The LBS subsystem is started if it is not running when a request is made.
   3. 
      When the privacy request is completed, the method MPosVerificationObserver::HandleVerifyComplete() is called on the client observer. The client sends the privacy response to the network.
   The following code example demonstrates how to use the Network Privacy API to verify a privacy request received over a GSM network.

   
   // Send a privacy request to LBS
   void CMyNetworkObserver::GSMVerifyPrivacyRequestL(const TDesC* aLCSClient, const TDesC* aRequestor,
                                                     CPosNetworkPrivacy::TRequestDecision aTimeoutAction)
       {
   
       // Create a new CPosGSMPrivacyRequestInfo object
       CPosGSMPrivacyRequestInfo* info = CPosGSMPrivacyRequestInfo::NewLC();
       
       // In this example, aLCSClientName is a proper name and aRequestor is a phone number
       info->SetLCSClientL(*aLCSClient, CPosGSMPrivacyRequestInfo::EIdTypeLogicalName);
       info->SetRequestorL(*aRequestor, CPosGSMPrivacyRequestInfo::EIdTypeMSISDN);
       
       // In this example set the request type to single shot
       info->SetRequestType(CPosNetworkPrivacyRequestInfo::ERequestSingleShot);
       
       // Client has an iRequestId member variable (a production client may need an array to track multiple requests)
       //iRequestId is set when VerifyLocationRequestL is called
       iPrivacy->VerifyLocationRequestL(*info, iRequestId, *this, aTimeoutAction);
       
       CleanupStack::PopAndDestroy(info);
       
       }
             

7. Write code to send a privacy notification request. The licensee client receives a privacy request from the network. 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 CPosGSMPrivacyRequestInfo or CPosSUPLPrivacyRequestInfo. The class of object that the client creates depends on whether the privacy request was received from the network via GSM or via SUPL.
   2. 
      The client calls CPosNetworkPrivacy::NotifyLocationRequest(). This method is asynchronous and non-blocking. The client can process multiple requests by calling NotifyLocationRequest() multiple times. Multiple requests are queued within the LBS subsystem. Each request is identified by a unique request ID. The LBS subsystem is started if it is not running when a request is made.
   The following code example demonstrates how to use the Network Privacy API to notify LBS of a location request received over a GSM network.

   
   // Notify LBS of a location request
   void CMyNetworkObserver::GSMNotifyLocationRequestL(TDesC* aLCSClient, TDesC* aRequestor)
       {
       
       // Create a new CPosGSMPrivacyRequestInfo object
       CPosGSMPrivacyRequestInfo* info = CPosGSMPrivacyRequestInfo::NewLC();
   
       // In this example, aLCSClientName is a proper name and aRequestor is a phone number
       info->SetLCSClientL(*aLCSClient, CPosGSMPrivacyRequestInfo::EIdTypeLogicalName);
       info->SetRequestorL(*aRequestor, CPosGSMPrivacyRequestInfo::EIdTypeMSISDN);
   
       // In this example set the request type to single shot
       info->SetRequestType(CPosNetworkPrivacyRequestInfo::ERequestSingleShot);
       
       // Client has an iRequestId member variable (a production client may need an array to track multiple requests)
       //iRequestId is set when NotifyLocationRequestL is called
       iPrivacy->NotifyLocationRequestL(*info, iRequestId);
       
       CleanupStack::PopAndDestroy(info);
       
       }
   

8. Write code to cancel a pending privacy verification request. The code example below shows how a client can cancel an outstanding request by calling CPosNetworkPrivacy::CancelRequest().

   
   // Cancel an outstanding request
   void CMyNetworkObserver::CancelPrivacyRequestL(TInt aRequestId, CPosNetworkPrivacy::TCancelReason aCancelReason)
       {
       
       // TCancelReason may be e.g. CPosNetworkPrivacy::ECancelReasonTimeout
   
       iPrivacy->CancelVerifyLocationRequest(aRequestId, aCancelReason);
       
       }
   

9. Write code to send a timeout notification to LBS. The code example below shows how a request can be timed out. The network can timeout the request and the client forwards this to the LBS subsystem by calling CPosNetworkPrivacy::NotifyVerificationTimeoutL().

   // Notify LBS that a completed privacy request has timed out
   void CMyNetworkObserver::GSMTimeoutPrivacyRequestL(const TDesC* aLCSClient, const TDesC* aRequestor,
                                                     TInt aRequestId, CPosNetworkPrivacy::TRequestDecision aTimeoutAction)
       {
       
       // Create a new CPosGSMPrivacyRequestInfo object    
       CPosGSMPrivacyRequestInfo* info = CPosGSMPrivacyRequestInfo::NewLC();
   
       // In this example, aLCSClientName is a proper name and aRequestor is a phone number
       info->SetLCSClientL(*aLCSClient, CPosGSMPrivacyRequestInfo::EIdTypeLogicalName);
       info->SetRequestorL(*aRequestor, CPosGSMPrivacyRequestInfo::EIdTypeMSISDN);
   
       iPrivacy->NotifyVerificationTimeoutL(*info, aRequestId, aTimeoutAction);
       
       CleanupStack::PopAndDestroy(info);
       
       }
   

   
   // Handle verify complete messages from LBS
   void CMyNetworkObserver::HandleVerifyComplete(TInt aRequestId, TInt aCompleteCode)
       {
       
       // The privacy request identified by aRequestId is complete
       // Inform the network...
   
       }
   

10. Define client capabilities The following is a simple MMP file for the client. The header files for the Network Privacy API are located at \epoc32\include\lbs and the client links to eposnwprv.lib. A client requires the capabilities Location, NetworkServices and ReadDeviceData.

    /*
    ============================================================================
     Name        : NetworkPrivacyAPI_Example.mmp
     Author      : 
     Copyright   :
     Description : 
    ============================================================================
    */
    
    TARGET          NetworkPrivacyAPI_Example.exe
    TARGETTYPE      exe
    UID             0 0xE3DC328A
    
    USERINCLUDE     ..\inc
    SYSTEMINCLUDE   \epoc32\include \epoc32\include\lbs
    
    SOURCEPATH      ..\src
    SOURCE          NetworkPrivacyAPI_Example.cpp CMyNetworkListener.cpp
    
    LIBRARY         euser.lib eposnwprv.lib
    
    
    CAPABILITY Location NetworkServices ReadDeviceData