<?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>
<image href="GUID-B2539DB1-FA06-5900-A859-547D3381E361_d0e459378_href.png" placement="inline"/>
</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>
<image href="GUID-9BDD42FD-9D05-58D1-896B-AF6E8E5B51FE_d0e459579_href.png" placement="inline"/>
</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-&gt;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-&gt;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-&gt;SetStatusL( CPosIntGpsHwStatus::EStatusOn );
      break;
    case 4:
      iStatus-&gt;SetStatusL( CPosIntGpsHwStatus::EStatusActive );
      break;
    default:
      iStatus-&gt;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>
<image href="GUID-6EB98EE9-AEB9-59C1-A1D8-FFD2E96707F2_d0e459664_href.png" placement="inline"/>
</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-&gt;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&amp;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>