Week 28 contribution of SDK documentation content. See release notes for details. Fixes bugs Bug 1897 and Bug 1522.
<?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_d0e453790_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&+ −
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_d0e453991_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 <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;+ −
}+ −
}+ −
+ − </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& + −
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_d0e454076_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 <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;+ −
}+ −
}+ −
}+ −
</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>+ −