<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1" xml:lang="en"><title> Integrated

GPS Hardware Status API</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>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. </p>

<section id="GUID-95DC83F8-BACE-4268-857F-9FAB42C99C13"><title>Contents</title> <ul>

<li id="GUID-7E469640-A285-5E2D-BBD6-C261936E6A84"><p><xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita#GUID-EB914A6D-9B61-5789-9546-8E466A0988D1/GUID-4D88709A-5F9F-5AA5-9081-2796A5BFD71E">Purpose</xref>  </p> </li>

<li id="GUID-7EDF85A9-C39D-58AE-AA12-58564D609A1B"><p><xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita#GUID-EB914A6D-9B61-5789-9546-8E466A0988D1/GUID-00B9D8F1-DABA-5029-9620-37E09B997436">API description</xref>  </p> </li>

<li id="GUID-61896A18-C1BF-5697-8A49-3FC1C8F126D7"><p><xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita#GUID-EB914A6D-9B61-5789-9546-8E466A0988D1/GUID-A2F5269C-9573-5C21-93F8-31C1C4487F80">API summary</xref>  </p> </li>

<li id="GUID-C3C3FFCE-3296-5CC8-9EB6-91F0F00C0CE4"><p><xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita#GUID-EB914A6D-9B61-5789-9546-8E466A0988D1/GUID-B95BC247-11CC-53E0-97CA-2473DBDEA849">Using the API</xref>  </p> <ul>

<li id="GUID-318B9FB4-5C46-55E6-A7A6-462C895B657D"><p><xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita#GUID-EB914A6D-9B61-5789-9546-8E466A0988D1/GUID-9B341963-90EB-59DF-BFC9-3AC78FD88615">Publishing the current status of integrated GPS hardware</xref>  </p> </li>

<li id="GUID-BF8C0C39-BAB0-575D-AFA2-DD254036BB63"><p><xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita#GUID-EB914A6D-9B61-5789-9546-8E466A0988D1/GUID-290A8675-E971-5CF8-A698-C86EDF2734B7">Getting the current status of integrated GPS hardware</xref>  </p> </li>

</ul> </li>

<li id="GUID-8DCBA75A-0E4B-51FA-9BB3-747FE0247A8C"><p><xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita#GUID-EB914A6D-9B61-5789-9546-8E466A0988D1/GUID-563E7E48-434F-552C-A76A-79577F451D93">Memory usage</xref>  </p> </li>

</ul> </section>

<section id="GUID-4D88709A-5F9F-5AA5-9081-2796A5BFD71E"><title>Purpose</title> <p>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. </p> </section>

<section id="GUID-00B9D8F1-DABA-5029-9620-37E09B997436"><title>API description</title> <p>The

API is used for two purposes: </p> <ul>

<li id="GUID-ADB3C80D-1D81-552C-859B-FED189C2DF67"><p>To publish the current

state of the integrated GPS hardware in the mobile device </p> <p>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. </p> </li>

<li id="GUID-72C40A33-1159-5221-BA74-3B3D8400C8BB"><p>To receive notification

of changes to the status of the GPS hardware and to get the new status </p> <p>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. </p> </li>

</ul> <p> </p> </section>

<section id="GUID-A2F5269C-9573-5C21-93F8-31C1C4487F80"><title>API summary</title> <p>The

API consists of the classes shown in the following diagram: </p> <fig id="GUID-E1F75907-DD6D-5290-BE96-116A05AB5155">

<title>              Integrated GPS HW Status API class diagram          

 </title>

</fig> <p>The classes of the Integrated GPS Hardware Status API are defined

in the file <filepath>epos_intgpshwstatus.h</filepath> and are summarised

in table 1. </p> <table id="GUID-73F1A811-8B76-5B0C-9C21-A52A21EF80B8">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Class Name</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312.dita"><apiname>CPosIntGpsHwStatus</apiname></xref>  </p> </entry>

<entry><p>This class provides the method <xref href="GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312.dita#GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312/GUID-29523EBA-8E8C-3C71-AD1D-F2F9C6006B3D"><apiname>CPosIntGpsHwStatus::SetStatusL()</apiname></xref> for

publishing the status of GPS hardware. It also provides the method <xref href="GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312.dita#GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312/GUID-8D3F9A56-3BCD-32F3-B9CF-252FE6EC0A19"><apiname>CPosIntGpsHwStatus::GetStatusL()</apiname></xref> to

get the current status of GPS hardware. </p> <p>It defines NewL() and NewLC()

methods that <xref href="GUID-A8A11194-74F6-38C6-AC5F-54678642CFDC.dita"><apiname>MPosIntGpsHwStatusObserver</apiname></xref> clients can used

to register themselves for notification of GPS hardware status changes. </p> <p>This

class also defines enumeration <codeph>CPosIntGpsHwStatus::TIntGpsHwState</codeph> that

defines the range of valid GPS hardware states that can be published. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-A8A11194-74F6-38C6-AC5F-54678642CFDC.dita"><apiname>MPosIntGpsHwStatusObserver</apiname></xref>  </p> </entry>

<entry><p>This class allows a client to register itself for notifications

of GPS hardware status changes. The class defines the method <xref href="GUID-A8A11194-74F6-38C6-AC5F-54678642CFDC.dita#GUID-A8A11194-74F6-38C6-AC5F-54678642CFDC/GUID-AF8EF2F7-4158-357E-B050-F662E1438DF1"><apiname>MPosIntGpsHwStatusObserver::OnStatusUpdateEvent()</apiname></xref> that

updates the client with GPS hardware status changes. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p> <i>Table 1. Classes of the GPS Hardware Status API.</i>  </p> <p>API

classes are packaged in the library <filepath>eposindicator.dll</filepath>.

Clients link with <filepath>eposindicator.lib</filepath>. </p> <p>Clients

require the capability <codeph>WriteDeviceData</codeph> to call <codeph>CPosIntGpsHwStatus::NewL()</codeph> (the

version that does not take a <codeph>MPosIntGpsHwStatusObserver</codeph> argument)

and <codeph>CPosIntGpsHwStatus::SetStatusL()</codeph>. </p> <p>Clients do

not require any capabilities to call <codeph>CPosIntGpsHwStatus::NewL(MPosIntGpsHwStatusObserver&amp;

          aObserver)</codeph> or <codeph>CPosIntGpsHwStatus::GetStatusL()</codeph>. </p> </section>

<section id="GUID-B95BC247-11CC-53E0-97CA-2473DBDEA849"><title>Using the API</title> <p>This

API supports two use cases: </p> <ul>

<li id="GUID-FD7219A4-869E-51AD-9B37-D77BB2554401"><p><xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita#GUID-EB914A6D-9B61-5789-9546-8E466A0988D1/GUID-9B341963-90EB-59DF-BFC9-3AC78FD88615">Publishing the current status of integrated GPS hardware</xref>  </p> </li>

<li id="GUID-36BCE102-6DCE-5CAB-84EB-E9ADED1EB745"><p><xref href="GUID-EB914A6D-9B61-5789-9546-8E466A0988D1.dita#GUID-EB914A6D-9B61-5789-9546-8E466A0988D1/GUID-290A8675-E971-5CF8-A698-C86EDF2734B7">Getting the current status of integrated GPS hardware</xref>  </p> </li>

</ul> </section>

<section id="GUID-9B341963-90EB-59DF-BFC9-3AC78FD88615"><title>Publishing

the current status of integrated GPS hardware</title> <p>In order to publish

GPS hardware status a client has to create a <xref href="GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312.dita"><apiname>CPosIntGpsHwStatus</apiname></xref> object

by using one of the static constructors, <codeph>NewL()</codeph> or <codeph>NewLC()</codeph> (the

versions that do not take an argument). A client must have capability <codeph>WriteDeviceData</codeph> to

call the constructors. A client can publish the status of the GPS hardware

as many times as needed using the same object instance. </p> <p>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. </p> <p>Publishing the hardware

status is performed by calling <xref href="GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312.dita#GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312/GUID-29523EBA-8E8C-3C71-AD1D-F2F9C6006B3D"><apiname>CPosIntGpsHwStatus::SetStatusL()</apiname></xref>.

A client must have <codeph>WriteDeviceData</codeph> capability to use this

method. Possible state values are defined by <xref href="GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312.dita#GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312/GUID-036AF204-A29D-32B2-9B7A-F24A391FC041"><apiname>CPosIntGpsHwStatus::TIntGpsHwState</apiname></xref>. </p> <p>The

following diagram shows a simple sequence for publishing the status of the

GPS hardware. </p> <fig id="GUID-D7C3C331-024C-5C97-8B1E-4952CC18B43A">

<title>              Simple sequence showing publishing the status of GPS

hardware.            </title>

</fig> <p>Below is a code example that demonstrates how to publish the GPS

hardware status. The example class <codeph>CMyGpsStatusController</codeph> class

publishes the GPS hardware status. When it is instantiated, it creates a new <xref href="GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312.dita"><apiname>CPosIntGpsHwStatus</apiname></xref> object

and keeps a pointer to it as a member variable. <codeph>CMyGpsStatusController</codeph> deletes

its <codeph>CPosIntGpsHwStatus</codeph> object when it is destroyed. </p> <p>The

main responsibility of the example class is mapping from internal numeric

IDs of GPS hardware states used by the parent component into the <xref href="GUID-832B7CAF-55A8-3E0A-82EB-3A7ECBD3082A.dita#GUID-832B7CAF-55A8-3E0A-82EB-3A7ECBD3082A/GUID-C5AC92C7-5AC2-32A9-A3DD-5E1777C6B560"><apiname>PosIntGpsHwStatus::TIntGpsHwStatus</apiname></xref> state

values defined by this API. </p> <p>The method <codeph>HandleNewGpsStateL()</codeph> 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 <xref href="GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312.dita#GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312/GUID-29523EBA-8E8C-3C71-AD1D-F2F9C6006B3D"><apiname>CPosIntGpsHwStatus::SetStatusL()</apiname></xref>. </p> <codeblock id="GUID-02ED509F-A80F-5E9D-A878-91414808403A" xml:space="preserve">#include &lt;epos_intgpshwstatus.h&gt;

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;

    }

  }

</codeblock> </section>

<section id="GUID-290A8675-E971-5CF8-A698-C86EDF2734B7"><title>Getting the

current status of integrated GPS hardware</title> <p>There are two ways that

a client can use the API to get the GPS hardware status: </p> <ul>

<li id="GUID-3D68CD24-D298-5FEC-971B-218CA8EEBFF0"><p>A client registers for

notifications for GPS hardware status updates by creating an instance of <codeph>CPosIntGpsHwStatus</codeph> by

calling <codeph>CPosIntGpsHwStatus::NewL(MPosIntGpsHwStatusObserver&amp; 

               aObserver)</codeph>. The client must pass a reference to <xref href="GUID-A8A11194-74F6-38C6-AC5F-54678642CFDC.dita"><apiname>MPosIntGpsHwStatusObserver</apiname></xref> in <codeph>NewL()</codeph>.

No platform security capabilities are required. </p> </li>

<li id="GUID-9A0A8B17-1D4F-54A8-845D-30A65A5A215E"><p>A client gets the current

GPS status at any time by calling <xref href="GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312.dita#GUID-1D92654B-E7FA-37FE-AC8F-2CCC0B118312/GUID-8D3F9A56-3BCD-32F3-B9CF-252FE6EC0A19"><apiname>CPosIntGpsHwStatus::GetStatusL()</apiname></xref>.

No platform security capabilities are required. </p> </li>

</ul> <p>The following diagram shows a simple sequence for getting GPS hardware

status events. </p> <fig id="GUID-4E45C675-E943-52B7-9367-62A8B193E50E">

<title>              Getting GPS hardware status changes            </title>

</fig> <p>Below is a code example that shows how a client gets updates of

GPS hardware status changes </p> <codeblock id="GUID-F10F4697-BEC5-502C-9822-E7AB9243B77E" xml:space="preserve">#include &lt;epos_intgpshwstatus.h&gt;

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;

            }

        }

}

</codeblock> </section>

<section id="GUID-563E7E48-434F-552C-A76A-79577F451D93"><title>Memory usage</title> <p>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 <codeph>CPosIntGpsHwStatus</codeph> are

created. </p> </section>

</conbody></concept>