Collapse all Symbian^3 Product Developer Library

Integrated GPS Hardware Status API

The Integrated GPS Hardware Status API allows a GPS hardware controller to publish notification of changes to GPS hardware status and to allow observers to receive notification that GPS hardware status has changed.

Purpose

This document describes the Integrated GPS Hardware Status API, which allows API clients to publish and receive the status of integrated GPS hardware in the mobile device.

API description

The API is used for two purposes:

To publish the current state of the integrated GPS hardware in the mobile device

The API is intended to be used by a component which is involved in the control of integrated GPS hardware of the terminal. Whenever the status of the hardware changes (e.g. when the hardware is turned on or off or when the internal state of the hardware changes) the API client can publish the status information by using the methods of this API.
To receive notification of changes to the status of the GPS hardware and to get the new status

A component that needs to be updated of changes to the status of the GPS hardware can use the API to subscribe for hardware status change events. Such components are typically UI indicators, such as a GPS status icon in a UI status bar.

API summary

The API consists of the classes shown in the following diagram:

Figure 1. Integrated GPS HW Status API class diagram

The classes of the Integrated GPS Hardware Status API are defined in the file epos_intgpshwstatus.h and are summarised in table 1.

Class Name	Description
CPosIntGpsHwStatus	This class provides the method CPosIntGpsHwStatus::SetStatusL() for publishing the status of GPS hardware. It also provides the method CPosIntGpsHwStatus::GetStatusL() to get the current status of GPS hardware. It defines NewL() and NewLC() methods that MPosIntGpsHwStatusObserver clients can used to register themselves for notification of GPS hardware status changes. This class also defines enumeration `CPosIntGpsHwStatus::TIntGpsHwState` that defines the range of valid GPS hardware states that can be published.
MPosIntGpsHwStatusObserver	This class allows a client to register itself for notifications of GPS hardware status changes. The class defines the method MPosIntGpsHwStatusObserver::OnStatusUpdateEvent() that updates the client with GPS hardware status changes.

Class Name

Description

CPosIntGpsHwStatus

This class provides the method CPosIntGpsHwStatus::SetStatusL() for publishing the status of GPS hardware. It also provides the method CPosIntGpsHwStatus::GetStatusL() to get the current status of GPS hardware.

It defines NewL() and NewLC() methods that MPosIntGpsHwStatusObserver clients can used to register themselves for notification of GPS hardware status changes.

This class also defines enumeration CPosIntGpsHwStatus::TIntGpsHwState that defines the range of valid GPS hardware states that can be published.

MPosIntGpsHwStatusObserver

This class allows a client to register itself for notifications of GPS hardware status changes. The class defines the method MPosIntGpsHwStatusObserver::OnStatusUpdateEvent() that updates the client with GPS hardware status changes.

Table 1. Classes of the GPS Hardware Status API.

API classes are packaged in the library eposindicator.dll. Clients link with eposindicator.lib.

Clients require the capability WriteDeviceData to call CPosIntGpsHwStatus::NewL() (the version that does not take a MPosIntGpsHwStatusObserver argument) and CPosIntGpsHwStatus::SetStatusL().

Clients do not require any capabilities to call CPosIntGpsHwStatus::NewL(MPosIntGpsHwStatusObserver& aObserver) or CPosIntGpsHwStatus::GetStatusL().

Using the API

This API supports two use cases:

Publishing the current status of integrated GPS hardware

In order to publish GPS hardware status a client has to create a CPosIntGpsHwStatus object by using one of the static constructors, NewL() or NewLC() (the versions that do not take an argument). A client must have capability WriteDeviceData to call the constructors. A client can publish the status of the GPS hardware as many times as needed using the same object instance.

A client destroys the instance of when it is no longer going to publish the status of the GPS hardware. The GPS hardware status setting is persistent and retains its value until it is changed again or the phone reboots.

Publishing the hardware status is performed by calling CPosIntGpsHwStatus::SetStatusL(). A client must have WriteDeviceData capability to use this method. Possible state values are defined by CPosIntGpsHwStatus::TIntGpsHwState.

The following diagram shows a simple sequence for publishing the status of the GPS hardware.

Figure 2. Simple sequence showing publishing the status of GPS hardware.

Below is a code example that demonstrates how to publish the GPS hardware status. The example class CMyGpsStatusController class publishes the GPS hardware status. When it is instantiated, it creates a new CPosIntGpsHwStatus object and keeps a pointer to it as a member variable. CMyGpsStatusController deletes its CPosIntGpsHwStatus object when it is destroyed.

The main responsibility of the example class is mapping from internal numeric IDs of GPS hardware states used by the parent component into the PosIntGpsHwStatus::TIntGpsHwStatus state values defined by this API.

The method HandleNewGpsStateL() is intended to be called by other parts of the component whenever the GPS hardware status changes (details of this are specific to hardware implementations and so are not shown). The example class publishes the new GPS status by calling CPosIntGpsHwStatus::SetStatusL().

#include <epos_intgpshwstatus.h>

class CMyGpsStatusController : public CBase
  {
  public:
    /* Static constructor. */
    static CMyGpsStatusController* NewL();

    ~CMyGpsStatusController();

    /* Publishes current status of the GPS HW */
    void HandleNewGpsStateL( TInt aStateId );

  private:
    /* Pointer to Integrated GPS HW Status API */
    CPosIntGpsHwStatus* iStatus;
  };
  

CMyGpsStatusController* CMyGpsStatusController::NewL()
  {
  CMyGpsStatusController* self = new (ELeave) CMyGpsStatusController;
  CleanupStack::PushL( self );

  // create own instance of status interface
  self->iStatus = CPosIntGpsHwStatus::NewL();

  CleanupStack::Pop( self );
  return self;
  }

CMyGpsStatusController::~CMyGpsStatusController()
  {
  delete iStatus; //delete instance
  }

/* Publishes current status of the GPS HW */
void CMyGpsStatusController::HandleNewGpsStateL( TInt aStateId )
  {
  // Map internal numeric HW state IDs to statuses defined
  // in Integrated GPS HW Status API. (example) 
  switch ( aStateId )
    {
    case 0:
      iStatus->SetStatusL( CPosIntGpsHwStatus::EStatusOff );
      break;
    case 1: // all these states are internal
    case 2: // and for upper levels can be
    case 3: // simplified just as ON state
      iStatus->SetStatusL( CPosIntGpsHwStatus::EStatusOn );
      break;
    case 4:
      iStatus->SetStatusL( CPosIntGpsHwStatus::EStatusActive );
      break;
    default:
      iStatus->SetStatusL( CPosIntGpsHwStatus::EStatusUnknown );
      break;
    }
  }

Getting the current status of integrated GPS hardware

There are two ways that a client can use the API to get the GPS hardware status:

A client registers for notifications for GPS hardware status updates by creating an instance of CPosIntGpsHwStatus by calling CPosIntGpsHwStatus::NewL(MPosIntGpsHwStatusObserver& aObserver). The client must pass a reference to MPosIntGpsHwStatusObserver in NewL(). No platform security capabilities are required.
A client gets the current GPS status at any time by calling CPosIntGpsHwStatus::GetStatusL(). No platform security capabilities are required.

The following diagram shows a simple sequence for getting GPS hardware status events.

Figure 3. Getting GPS hardware status changes

Below is a code example that shows how a client gets updates of GPS hardware status changes

#include <epos_intgpshwstatus.h>

class CMyGpsStatusObserver : public MPosIntGpsHwStatusObserver
  {
  public:
    /* Static constructor. */
    static CMyGpsStatusObserver* NewL();

    ~CMyGpsStatusObserver();

    /* Implement MPosIntGpsHwStatusObserver method */
    void OnStatusUpdateEvent(CPosIntGpsHwStatus::TIntGpsHwStatus aStatus, TInt aError);

  private:
    /* Pointer to Integrated GPS HW Status API */
    CPosIntGpsHwStatus* iStatus;
  };
  

CMyGpsStatusObserver* CMyGpsStatusObserver::NewL()
  {
  CMyGpsStatusObserver* self = new (ELeave) CMyGpsStatusObserver;
  CleanupStack::PushL(self);

  // create own instance of GPS HW status interface
  self->iStatus = CPosIntGpsHwStatus::NewL(*self);

  CleanupStack::Pop( self );
  return self;
  }

CMyGpsStatusObserver::~CMyGpsStatusObserver()
  {
  delete iStatus; //delete instance
  }

void CMyGpsStatusObserver::OnStatusUpdateEvent(CPosIntGpsHwStatus::TIntGpsHwStatus aStatus, TInt aError)
{
    if (aError != KErrNone)
        {
        // Handle error
        }
    else
        {
            switch (aStatus)
            {
            case CPosIntGpsHwStatus::EStatusOff :
            // GPS is off
            break;
    
            case CPosIntGpsHwStatus::EStatusOn :
            // GPS is powered
            break;
            
            case CPosIntGpsHwStatus::EStatusActive :
            // GPS is on and obtaining a position fix
            break;
            }
        }
}

Memory usage

Memory used by this API is only the size of its classes on the heap. This is about 100 bytes. The first client of this API will cause P&S key created in the OS and will exist until phone reboots. This adds to the memory usage, but any other client will use the same key, so no further increase in OS memory usage, even if several instances of the class CPosIntGpsHwStatus are created.

Parent topic: Location Admin