Implementing the MLbsPrivacyObserver Methods

A Privacy Controller must implement the virtual functions of the MLbsPrivacyObserver interface (and the shutdown function of the MLbsPrivacyObserver2 interface if appropriate).

Note that because the design of a Privacy Controller is a licensee task, it is only possible to describe the implementation of these functions in broad outline here. MLbsPrivacyObserver defines three methods:

• MLbsPrivacyObserver::ProcessNetworkLocationRequest() is called to process a privacy request. The code example below shows the following:

  • How the encoding of the requester ID and client name parameters (as defined by 3GPP specifications) can be obtained from the TLbsExternalRequestInfo parameter. The parameter encoding schemes are defined by TLbsExternalRequestInfo::_TCodingScheme.

  • How the format of the requester ID and client name parameters are obtained. The formats are defined by TLbsExternalRequestInfo::_TFormatIndicator.

    The parameter aRequestId is a unique identifier for a privacy request.

    The parameter aNotifyType specifies whether the request is a privacy verification request or a privacy notification request.

    // Process a privacy verification request or a location notification request
    void CMyLbsPrivacyControllerObserver::ProcessNetworkLocationRequest
       (TUint aRequestId, const TLbsExternalRequestInfo& aRequestInfo,
        const TNotificationType& aNotifyType)
    	{
    	// Get the Requester Id, Client name and external requester Id as specified by 3GPP specifications
    	
    	// Coding scheme and format for the requester id and client name
    	TLbsExternalRequestInfo::TCodingScheme requesterIdScheme, nameScheme;
    	TLbsExternalRequestInfo::TFormatIndicator requesterIdFormat, nameFormat;
    	
    	// Get the coding schemes for the requester ID and the client name
    	requesterIdScheme = aRequestInfo.RequesterIdCodingScheme();
    	nameScheme = aRequestInfo.ClientNameCodingScheme();
    	
    	// Get the data format for the requester ID and the client name
    	requesterIdFormat = aRequestInfo.RequesterIdFormat();
    	nameFormat = aRequestInfo.ClientNameFormat();
    
    	TLbsClientName clientName;
    	TLbsRequesterId requesterId;
    	TLbsClientExternalId externalId;
    	
    	// Get the ids and client name from the request info object
    	aRequestInfo.GetClientName(clientName);
    	aRequestInfo.GetRequesterId(requesterId);
    	aRequestInfo.GetClientExternalId(externalId);
    	
    	// Check the encoding schemes of requesterId and clientScheme
    	switch (requesterIdScheme)
    		{
    		case TLbsExternalRequestInfo::ECodingSchemeUCS2 :
    		
    		/*
    		Handle any character conversion that may
    		be required by the licensee Privacy Controller
    		Details are licensee specific...
    		*/
    		
    		break;
    		
    		case TLbsExternalRequestInfo::ECodingSchemeUTF8:
    		
    		/*
    		Handle any character conversion that may
    		be required by the licensee Privacy Controller
    		Details are licensee specific...
    		*/
    
    		break;
    		
    		case TLbsExternalRequestInfo::ECodingSchemeGSMDefault :
    		
    		/*
    		Handle any character conversion that may
    		be required by the licensee Privacy Controller
    		Details are licensee specific...
    		*/
    		
    		break;
    		
    		}
    	
    	/*
    	And similar to the above for the clientName parameter
    	Details omitted...
     */
    	
     /*
    	Check the format of the data held by requesterId and clientName
    	e.g. Email address, MSISDN etc.
    	*/
    	
    	switch (requesterIdFormat)
    		{
    		case TLbsExternalRequestInfo::EFormatLogicalName :
    		
    			/*
    			requesterId is a name
    			Licensee Privacy Controller can use the name to lookup the user in contacts
    			or format it for display to the user
    			Implementation details omitted...
    			*/
    		
    			break;
    		
    		case TLbsExternalRequestInfo::EFormatEmailAddress :
    		
    			/*
    			requesterId is an email address
    			Licensee Privacy Controller can use the email address to lookup the user in contacts
    			or format it for display to the user
    			Implementation details omitted...
    			*/
    		
    			break;
    		
    			/*
    			And so on to check for the other possible formats
    			defined in TLbsExternalRequestInfo::_TFormatIndicator
    	  ...
    
    			*/
    		}
    	
    	/*
    	 After getting the data encoding and the data format, the Privacy Controller
    	 can either :
    	 
    	 1. Automatically process the privacy request based on privacy rules
    	 2. Use privacy dialogs to obtain a response from the user
    	 3. Some combination of 1 & 2
    	 
    	 These are implementation details for the licensee...
    	*/ 
    	}

    As described in LBS Privacy Controller, when LBS is configured in the Standalone Privacy Mode configuration it is possible for large buffers to be passed over the Network Privacy API from the licensee domestic operating system into Symbian LBS. In this case it is necessary to cast the received TLbsExternalRequestInfo reference to a TLbsExternalRequestInfo2 reference before using it. Failure to do so may result in truncated data being returned if the length of the requester descriptors exceeds the size of the buffers in TLbsExternalRequestInfo. A simple static case is required:

    const TLbsExternalRequestInfo2& info = static_cast<const TLbsExternalRequestInfo2&>(aRequestInfo);
    
    // Now use info instead of aRequestInfo...

• MLbsPrivacyObserver::ProcessNetworkPositionUpdate() notifies the Privacy Controller that a position fix has been calculated or received from the network. When a Privacy Controller receives such a notification a licensee can choose to notify the user. The parameter aRequestId associates a position update with a previous ProcessNetworkLocationRequest() call.

  // Handle notification of a position update
  void CMyLbsPrivacyControllerObserver::ProcessNetworkPositionUpdate(TUint aRequestId, 
                                                                     const TPositionInfo& aPosInfo)
  	{
  		/*
  		A Privacy Controller is informed when the LBS subsystem calculates or receives a position update
  		The user can be informed if the licensee chooses to do so
  		
  	    This is an implementation task for the licensee...
  	 */
  	}

• MLbsPrivacyObserver::ProcessNetworkRequestComplete() notifies the Privacy Controller that the privacy request uniquely identified by aRequestId is complete. The parameter aReason specifies why the request was completed and is KErrNone for normal processing, KErrCancel if the network cancels the request or KErrTimedOut if the network times out the request because the Privacy Controller has not returned a response.

  // Privacy controller is notified that a request is completed
  void CMyLbsPrivacyControllerObserver::ProcessRequestComplete(TUint aRequestId, TInt aReason)
  	{
  		/*
  		The LBS subsystem notifies the Privacy Controller 
  		when a request is complete
  		*/
  	}

// Privacy Controller is told to shutdown

void CMyLbsPrivacyControllerObserver2::ProcessCloseDownNotification()
	{
		/*
		Free up all resources allocated by the Privacy Controller
		such as dialog resources, file sessions etc.
		
		The implementation of this method is specific
		to the licensee Privacy Controller, but all owned resources must be freed
		*/
	}