QGeoPositionInfoSource

Since: 1.0

#include <QtLocationSubset/QGeoPositionInfoSource>

The QGeoPositionInfoSource class is an abstract base class for the distribution of positional updates.

The static function QGeoPositionInfoSource::createDefaultSource() creates a default position source on the BlackBerry platform.

Users of a QGeoPositionInfoSource subclass can request the current position using requestUpdate(), or start and stop regular position updates using startUpdates() and stopUpdates(). When an update is available, positionUpdated() is emitted. The last known position can be accessed with lastKnownPosition().

If regular position updates are required, setUpdateInterval() can be used to specify how often these updates should be emitted. If no interval is specified, updates are simply provided whenever they are available. For example:

// Emit updates every 10 seconds if available
QGeoPositionInfoSource *source = QGeoPositionInfoSource::createDefaultSource(0);
if (source)
    source->setUpdateInterval(10000);

To remove an update interval that was previously set, call setUpdateInterval() with a value of 0.

Note that the position source may have a minimum value requirement for update intervals, as returned by minimumUpdateInterval().

Users of a BlackBerry QGeoPositionInfoSource subclass (obtained from QGeoPositionInfoSource::createDefaultSource()) can access the underlying backend (BlackBerry Location Manager) for additional functionality via the Qt property system.

The following properties extend QGeoPositionInfoSource allowing use of additional features of the BlackBerry Location Manager. They correspond to the fields of the dat parameter of the location request. Set these properties prior to calling startUpdates() or requestUpdate().

period
This property specifies the period of the location request, in seconds. A value of '0' indicates a one-time location request. Setting period is equivalent to setUpdateInterval(), apart from the units.
source->setProperty( "period", 5.0 );
accuracy
This property specifies the desired accuracy of the fix, in meters. A value of '0' disables accuracy criteria.
source->setProperty( "accuracy", 2.0 );
responseTime
This property specifies the desired response time of the fix, in seconds. A value of '0' disables response time criteria.
source->setProperty( "responseTime", 10.0 );
canRunInBackground
This property determines whether or not requests are allowed to run with the device in standby (i.e. screen off)
source->setProperty( "canRunInBackground", true );
provider
This property specifies the location provider you wish to use (hybrid, gnss, network). Setting provider is equivalent to setPreferredPositioningMethods().
source->setProperty( "provider", "hybrid" );    // equivalent to QGeoPositionInfoSource::AllPositioningMethods
source->setProperty( "provider", "gnss" );      // equivalent to QGeoPositionInfoSource::SatellitePositioningMethods
source->setProperty( "provider", "network" );   // equivalent to QGeoPositionInfoSource::NonSatellitePositioningMethods
fixType
This property specifies the fix type you wish to use (best, gps_ms_based, gps_ms_assisted, gps_autonomous, cellsite, wifi). Valid values depend on which provider is set.
source->setProperty( "provider", "network" );
source->setProperty( "fixType", "wifi" );
appId
This property specifies a special application id.
source->setProperty( "appId", "myId" );
source->setProperty( "appPassword", "myPassword" );
appPassword

This property specifies a special application password, goes with appId above.

pdeUrl
This property specifies the PDE URL (i.e. tcp://user:pass@address.dom:1234).
QUrl url("tcp://user:pass@address.dom:1234");
source->setProperty( "pdeUrl", url );
slpUrl
This property specifies the SLP URL (i.e. tcp://user:pass@address.dom:1234).
QUrl url("tcp://user:pass@address.dom:1234");
source->setProperty( "slpUrl", url );
stationaryDetectionEnabled
This property determines whether or not to enable the stationary detection filter. Sensor data is used to determine when there is no movement. If stationaryDetectionEnabled is set to true, and then startUpdates() is called, at least one position update will occur. After this, if the device is stationary, the timeout() signal will be emitted and the replyErrorCode will be bb::location::PositionErrorCode::WarnStationary. Position updates will resume automatically when device movement is detected. This property is useful for detecting position changes, and potentially reducing power consumption.
source->setProperty( "stationaryDetectionEnabled", true );
The following read-only property is used to query the Location Services status.
locationServicesEnabled
This property indicates whether the Location Services are enabled or not. If location services are disabled then no position updates will occur. If Location Services are not enabled the app developer should indicate to the end user that they must enable Location Services through the Settings app before any position updates will be available. This property can be queried at any time, and is not dependent on startUpdate(), etc. being invoked, as for the properties described above. The following code example demonstrates how to test for Location Services and present the end user with the Location Services page of the Settings app so that the services may be enabled.
// To link against these classes, add the following line to your .pro file : LIBS += -lbbsystem
#include <bb/system/InvokeManager>
#include <bb/system/InvokeRequest>
#include <bb/system/InvokeTargetReply>
.
.
.
// ensure location services are enabled
if ( !positionInfoSource->property("locationServicesEnabled").toBool() ) {
    // bring up the Settings app at the Location Services page so it can be turned on. One could
    // first bring up a dialog here to give the user context
    bb::system::InvokeManager * invokeManager = new bb::system::InvokeManager( NULL ); // or pass a QObject parent instead of NULL to relinquish delete responsibility
    bb::system::InvokeRequest request;
    request.setAction( "bb.action.OPEN" );
    request.setMimeType( "text/html" );
    request.setUri( "settings://location" );
    request.setTarget( "sys.settings.target" );
    bb::system::InvokeTargetReply *reply = invokeManager->invoke(request);
    if ( reply ) {
        // you can use reply to see how the invocation went...
    }

    delete invokeManager;   // deletes reply too...
}
The following read-only properties are fields of the BlackBerry Location Manager generic reply.
replyDat
This property specifies the object containing the reply data (such as latitude, longitude, satellites, etc) exactly as output by the Location Manager. If the replyErrorCode property is not PositionErrorCode::None then replyDat may be empty or stale. See replyErrorCode below for identifying position update errors. The replyDat property should be queried in the slot connected to the QGeoPositionInfoSource::positionUpdated() signal. Otherwise if it is queried at some other execution point then its contents are undefined. The replyDat property is represented by a QVariantMap that consists of a number of key/value pairs providing data relevant to the position update (see the Location Manager protocol). One of the QVariantMap values is an array of satellite data pertinent to the position update. This data is stored as a QVariantList of QVariantMap elements. Accessing positional data from within the slot can be done like this:
double hdop = 20.0; // horizontal dilution of precision
QVariant variant = source->property("replyDat");
if ( variant.isValid() ) {
    // the replyDat property is a QVariantMap
    QVariantMap rawDat = variant.toMap();
    QVariant field = rawDat.value( "hdop" );
    if ( field.isValid() ) {
        hdop = field.toDouble();
    }
}
Accessing satellite data can be done like this:
// This example gets the carrier-to-noise ratio for the first satellite in the list.
double cno = 0.0; // satellite carrier-to-noise ratio
QVariant variant = source->property("replyDat");
if ( variant.isValid() ) {
    // the replyDat property is a QVariantMap
    QVariantMap rawDat = variant.toMap();
    QVariant field = rawDat.value( "satellites" );
    if ( field.isValid() ) {
        // the satellites data is stored in a QVariantList
        QVariantList satArray = field.toList();
        // each element in the list is a QVariantMap corresponding to info for a single satellite.
        // Here we just access the first satellite in the list
        QVariantMap satInfo = satArray.at(0).toMap();
        QVariant satField = satInfo.value( "cno" );
        cno = satField.toDouble();
    }
}
replyErrorCode
In the event that the Location Manager cannot provide a position update the reason can potentially be determined from replyErrorCode. When a position update cannot be provided the signal QGeoPositionInfoSource::updateTimeout() is emitted. replyErrorCode has the enumerated type bb::location::PositionErrorCode::Type (#include <bb/location/PositionErrorCode>) and can be queried in the slot connected to QGeoPositionInfoSource::updateTimeout(). There are two types of codes, warning and fatal. A warning code indicates that position updates have stopped but that the Location Manager will automatically resume updates if conditions change. A fatal code indicates that position updates have stopped and the Location Manager has abandoned the location request(s). After a fatal error, if periodic updates are active stopUpdates() should be called, the problem should be resolved, and then startUpdates() should be called again.
#include <bb/location/PositionErrorCode>
.
.
.
// A timeout has occurred, check if the LM has reported an error
if ( positionInfoSource->property("replyErrorCode").isValid()  ) {
    bb::location::PositionErrorCode::Type errorCode = positionInfoSource->property("replyErrorCode").value<bb::location::PositionErrorCode::Type>();
    std::cout << "LM Error Code: ";
    switch ( errorCode ) {
        // this error code should not be encountered here (included for completeness)
        case bb::location::PositionErrorCode::None:
            std::cout << "None" << std::endl;
            break;

        case bb::location::PositionErrorCode::FatalDisabled:
            std::cout << "Fatal - disabled (turn on location services!)" << std::endl;
            break;

        // this error code should not normally be encountered, may require setting
        // the reset property to resolve.
        case bb::location::PositionErrorCode::FatalInsufficientProviders:
            std::cout << "Fatal - insufficient providers" << std::endl;
            break;

        // this error code could be encountered if an invalid value is set for a
        // property related to a BlackBerry Location Manager feature.
        case bb::location::PositionErrorCode::FatalInvalidRequest:
            std::cout << "Fatal - invalid request" << std::endl;
            break;

        // the following warning codes are simply to provide more information;
        // if periodic updates are active they will resume when conditions change.
        // It may be opportune to inform the user that finding the location is
        // taking longer than expected.
        case bb::location::PositionErrorCode::WarnTimeout:
            std::cout << "Warning - timeout" << std::endl;
            break;

        case bb::location::PositionErrorCode::WarnLostTracking:
            std::cout << "Warning - lost tracking" << std::endl;
            break;

        default:
            std::cout << "Unknown (bad enum value)" << std::endl;
            break;
    }
}
When set, the following property causes a RESET request to be sent to all the location providers.
reset
By setting this property a reset of all location providers is requested through the Location Manager. The value of reset specifies the type of reset to be performed. Valid reset types are "cold", "warm", "hot", "factory", "ee_data", "almanac", "ephemeris". The reset is not actually carried out until position updates are restarted.
positionInfoSource->setProperty("reset", "hot");
positionInfoSource->requestUpdate();

Overview

Inheritance

QtMobilitySubset::QGeoPositionInfoSource
QtMobilitySubset::QNmeaPositionInfoSource

Public Types Index

enum PositioningMethod

SatellitePositioningMethods = 0x000000ff, NonSatellitePositioningMethods = 0xffffff00, AllPositioningMethods = 0xffffffff

Properties Index

Public Functions Index

QGeoPositionInfoSource (QObject *parent)
virtual ~QGeoPositionInfoSource ()
QGeoPositionInfolastKnownPosition (bool fromSatellitePositioningMethodsOnly=false) const =0
intminimumUpdateInterval () const =0
PositioningMethodspreferredPositioningMethods () const
virtual voidsetPreferredPositioningMethods (PositioningMethods methods)
virtual voidsetUpdateInterval (int msec)
PositioningMethodssupportedPositioningMethods () const =0
intupdateInterval () const

Static Public Functions Index

QStringListavailableSources ()
QGeoPositionInfoSource *createDefaultSource (QObject *parent)
QGeoPositionInfoSource *createSource (const QString &sourceName, QObject *parent)

Public Slots Index

voidrequestUpdate (int timeout=0)=0
voidstartUpdates ()=0
voidstopUpdates ()=0

Signals Index

voidpositionUpdated (const QGeoPositionInfo &update)
voidupdateTimeout ()

Public Types

PositioningMethod

Defines the types of positioning methods.

SatellitePositioningMethods Satellite-based positioning methods such as GPS. NonSatellitePositioningMethods Other positioning methods. AllPositioningMethods A flag that matches all positioning methods.

SatellitePositioningMethods = 0x000000ff
NonSatellitePositioningMethods = 0xffffff00
AllPositioningMethods = 0xffffffff

Properties

int minimumUpdateInterval[read-only]

This property holds the minimum time (in milliseconds) required to retrieve a position update.

This is the minimum value accepted by setUpdateInterval() and requestUpdate().

int updateInterval

This property holds the requested interval in milliseconds between each update.

If the update interval is not set (or is set to 0) the source will provide updates as often as necessary.

If the update interval is set, the source will provide updates at an interval as close to the requested interval as possible. If the requested interval is less than the minimumUpdateInterval(), the minimum interval is used instead.

Changes to the update interval will happen as soon as is practical, however the time the change takes may vary between implementations. Whether or not the elapsed time from the previous interval is counted as part of the new interval is also implementation dependent.

The default value for this property is 0.

Note: Subclass implementations must call the base implementation of setUpdateInterval() so that updateInterval() returns the correct value.

Public Functions

QGeoPositionInfoSource (

Creates a position source with the specified parent.

virtual~QGeoPositionInfoSource ()

Destructor.

QGeoPositionInfo lastKnownPosition (
  • boolfromSatellitePositioningMethodsOnly)

Returns an update containing the last known position, or a null update if none is available.

If fromSatellitePositioningMethodsOnly is true, this returns the last known position received from a satellite positioning method; if none is available, a null update is returned.

int minimumUpdateInterval ()

PositioningMethods preferredPositioningMethods ()

Returns the positioning methods set by setPreferredPositioningMethods().

virtual void setPreferredPositioningMethods (
  • PositioningMethodsmethods)

Sets the preferred positioning methods for this source to methods.

virtual void setUpdateInterval (
  • intmsec)

PositioningMethods supportedPositioningMethods ()

Returns the positioning methods available to this source.

int updateInterval ()

Static Public Functions

QStringList availableSources ()

Returns a list of available source plugins.

Note that this list does not include the default platform backend, if one is available.

QGeoPositionInfoSource * createDefaultSource (

Creates and returns a position source with the given parent that reads from the system's default sources of location data, or the plugin with the highest available priority.

Returns 0 if the system has no default position source and no valid plugins could be found.

QGeoPositionInfoSource * createSource (

Creates and returns a position source with the given parent, by loading the plugin named sourceName.

Returns 0 if the plugin cannot be found.

Public Slots

void requestUpdate (
  • inttimeout)

Attempts to get the current position and emit positionUpdated() with this information.

If the current position cannot be found within the given timeout (in milliseconds) or if timeout is less than the value returned by minimumUpdateInterval(), updateTimeout() is emitted.

If the timeout is zero, the timeout defaults to a reasonable timeout period as appropriate for the source.

This does nothing if another update request is in progress. However it can be called even if startUpdates() has already been called and regular updates are in progress.

If the source uses multiple positioning methods, it tries to get the current position from the most accurate positioning method within the given timeout.

Note that on BlackBerry updateTimeout() may be emitted for other reasons, such as the app's permission to access location services being disabled. These situations can be identified in the slot connected to updateTimeout() using the replyErrorCode property of the BlackBerry QGeoPositionInfoSource instance.

void startUpdates ()

Starts emitting updates at regular intervals as specified by setUpdateInterval().

If setUpdateInterval() has not been called, the source will emit updates as soon as they become available.

An updateTimout() signal will be emitted if this QGeoPositionInfoSource subclass determines that it will not be able to provide regular updates. This could happen if a satellite fix is lost or if a hardware error is detected. Position updates will recommence if the data becomes available later on. The updateTimout() signal will not be emitted again until after the periodic updates resume.

Note on BlackBerry there are some situations where position updates will not recommence after an updateTimeout() signal is emitted. These situations can be identified in the slot connected to updateTimeout() using the replyErrorCode property of the BlackBerry QGeoPositionInfoSource instance.

void stopUpdates ()

Stops emitting updates at regular intervals.

Signals

void positionUpdated (

If startUpdates() or requestUpdate() is called, this signal is emitted when an update becomes available.

The update value holds the value of the new update.

Note that since QGeoPositionInfoSource is in the namespace QtMobilitySubset and this signal is not declared by fully qualifying the QGeoPositionInfo parameter, care must be taken when declaring a slot for connection to this signal. The following is a sample class definition:
// This enables the SIGNAL()/SLOT() macros to have matching signatures.
using ::QtMobilitySubset::QGeoPositionInfo;

class Sample : public QObject
{
    Q_OBJECT
    .
    .
    .
    public Q_SLOTS:
        void positionUpdated(const QGeoPositionInfo & pos);
}
Then the connection in the following code snippet will succeed:
Sample sample;
QtMobilitySubset::QGeoPositionInfoSource * positionInfoSource = QtMobilitySubset::QGeoPositionInfoSource::createDefaultSource(&sample);

QObject::connect(positionInfoSource, SIGNAL(positionUpdated( const QGeoPositionInfo & ) ), &sample, SLOT(positionUpdated(const QGeoPositionInfo &)));

void updateTimeout ()

If requestUpdate() was called, this signal will be emitted if the current position could not be retrieved within the specified timeout.

If startUpdates() has been called, this signal will be emitted if this QGeoPositionInfoSource subclass determines that it will not be able to provide further regular updates. This signal will not be emitted again until after the regular updates resume.

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus