Privacy Data Types

Purpose

This document describes the classes and types of the Privacy Data Types that are used by the LBS Privacy Q&N Notifiers.

Contents

• Introduction

• API description

  • CPosRequestor

  • CPosServiceRequestor

  • CPosContactRequestor

  • RPosRequestorStack

  • TPosRequestSource

  • TPosRequestDecision

  • TPosNotificationReason

  • TPosVerifyCancelReason

• See also

Introduction

Figure 1 shows the Privacy Data Types within the Full LBS configuration. The Privacy Data Types are used to pass privacy request data and privacy response data between the LBS subsystem and licensee Privacy Q&N Notifier classes.

For a privacy request passed from the LBS subsystem to a Privacy Q&N Notifier, the Privacy Data Types specify the agent that is making the request (the requester) and the type of the request. For a privacy response, the Privacy Data Types specify why a privacy request was accepted, rejected or cancelled by a user.

Note that the Privacy Data Types are used only by the Privacy Q&N Notifiers API and are not used by the standard LBS Privacy Notifiers or the Privacy Controller, which are also shown in figure 1.

Note also that although figure 1 shows a (partial) Full LBS Mode configuration, the Privacy Q&N Notifiers and their associated Privacy Data Types can also be included in the Standalone Privacy Mode configuration.

See Privacy Q&N Notifiers for examples of how the Privacy Data Types are used.

API description

Privacy Data Types class diagram

Figure 2 shows the classes and types of the Privacy Data Types.

List of Privacy Data Types classes and types

The following table lists the main classes and types of the Privacy Data Types. Further details can be found by following the links to other sections of this document and to Symbian Developer Library reference documentation.

The Privacy Data Types have publishedPartner interface access.

Libraries

The Privacy Data Types are packaged in eposprvtyp.dll. A client (a Privacy Q&N Notifier) links to eposprvtyp.lib.

Capabilities

Use of the Privacy Data Types requires no capabilities.

CPosRequestor

Purpose

CPosRequestor is the base class that represents the agent (known as the requester) that is making a privacy request. Requesters are classified as either service or contact and these are represented by the derived classes CPosServiceRequestor and CPosContactRequestor.

CPosRequestor has the following attributes:

• The requester type

  CPosRequestor::TRequestorType specifies the type of requester: a service or contact.

• The ID descriptor

  A descriptor variable specifies the ID of the requester.

• The ID format

  CPosRequestor::TRequestorIdFormat specifies the type of data that the ID string contains, such as a name, a contact number or an email address.

• The network type

  CPosRequestor::_TNetworkType specifies whether a request is received over a GSM network or SUPL.

• The request type

  CPosRequestor::_TRequestType specifies if a request is single shot, periodic or an area event.

  Note that this property is not currently used within the LBS subsystem, but is defined for future use.

Usage

To send a privacy request to a Privacy Q&N Notifier the LBS subsystem instantiates one of the derived classes CPosServiceRequestor (for a request from a service) or CPosContactRequestor (for a request from a contact), setting the attributes listed above.

Note that not all information about a privacy request that may be required by the notifier is passed to it in the CPosRequestor object. The enumerations TPosNotificationReason, TPosRequestSource and TPosRequestDecision shown in figure 1 also describe request data. These are set directly by the LBS subsystem on the Privacy Q&N notifier (derived from CPosPrivacyNotifier) when it is started. See Privacy Q&N Notifiers for more information.

The LBS subsystem starts a Privacy Q&N Notifier plug-in to display the privacy request information to the user. The notifier extracts request information by calling:

• CPosRequestor::RequestorType() to get the type of requester: a service or contact

• CPosRequestor::RequestorIdString() to get the requester ID descriptor

• CPosRequestor::RequestorIdFormat() to get the format of the requester ID contained in CPosRequestor::RequestorIdString()

• CPosRequestor::NetworkType() to get the network type

• CPosRequestor::RequestType() to get the type of request

Information about the reason the notification was sent, the request source and the request timeout strategy is obtained directly from the CPosPrivacyNotifier derived notifier by calling:

• CPosPrivacyNotifier::NotificationReason() to get the reason the notification request was sent

• CPosPrivacyNotifier::RequestSource() to get the source of the request

• CPosPrivacyNotifier::QueryTimeoutStrategy() to get the timeout strategy that was supplied as part of the privacy request. The strategy specifies whether a request should be accepted or rejected if the notifier times out.

See Privacy Q&N Notifiers for more information about CPosPrivacyNotifier.

CPosServiceRequestor

Purpose

CPosServiceRequestor is the derived class that represents a service privacy requester (such as a network service).

Usage

The LBS subsystem creates an instance of this class to pass information about a privacy request received from a service to a Privacy Q&N Notifier.

The class adds the static constructors CPosServiceRequestor::NewL() and CPosServiceRequestor::NewLC() to the base class CPosRequestor.

CPosContactRequestor

Purpose

CPosContactRequestor is the derived class that represents a contact privacy requester (such as a phone number or email address).

Usage

The LBS subsystem creates an instance of this class to pass information about a privacy request received from a contact (such as a telephone number or email address) to a Privacy Q&N Notifier.

The class adds the static constructors CPosContactRequestor::NewL() and CPosContactRequestor::NewLC() to the base class CPosRequestor.

RPosRequestorStack

Purpose

RPosRequestorStack is an array of CPosRequestor objects.

Usage

The LBS subsystem creates an RPosRequestorStack instance populated with CPosRequestor derived objects when a privacy request is received. This stack object is passed to a Privacy Q&N Notifier. See Privacy Q&N Notifiers for more information about the use of RPosRequestorStack.

TPosRequestSource

Purpose

TPosRequestSource specifies the source of a privacy request. This enumeration defines two values for a network source and for an unknown source.

Usage

Set by the LBS subsystem on a Privacy Q&N notifier plug-in when it is started to specify the source of the request. CPosPrivacyNotifier::RequestSource() gets the value.

TPosRequestDecision

Purpose

TPosRequestDecision specifies if a privacy request was accepted or rejected by a Privacy Q&N notifier.

Usage

• Set by the LBS subsystem to specify the privacy response that should be made if a Privacy Q&N notifier times out. CPosPrivacyNotifier::QueryTimeoutStrategy() gets the value which can be to either accept or reject the request.

• Set by a Privacy Q&N Notifier to specify the privacy response. CPosPrivacyNotifier::LocationRequestDecision() gets the value set by the notifier.

TPosNotificationReason

Purpose

TPosNotificationReason specifies the reason why a notification message was received from the network:

A notification can be received for the following reasons:

• A privacy verification (sent previously) has timed out and the user needs to be notified of this fact.

• A location request was either accepted or rejected by the request source.

• For an unknown reason.

Usage

Set by the LBS subsystem on a Privacy Q&N Notifier to specify why a privacy notification was received. The value is obtained from the notifier by calling CPosPrivacyNotifier::NotificationReason().

TPosVerifyCancelReason

Purpose

TPosVerifyCancelReason specifies the reason why a privacy verification request was cancelled.

Usage

Set by the LBS subsystem on a Privacy Q&N Notifier to specify why a privacy verification request was cancelled. The value is obtained from the notifier by calling CPosPrivacyNotifier::CancelReason().