QGeoPositionInfoSource

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 );

This property specifies the desired accuracy of the fix, in meters. A value of '0' disables accuracy criteria.

source->setProperty( "accuracy", 2.0 );

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 );

This property determines whether or not requests are allowed to run with the device in standby (i.e. screen off)

source->setProperty( "canRunInBackground", true );

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

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" );

This property specifies a special application id.

source->setProperty( "appId", "myId" );
source->setProperty( "appPassword", "myPassword" );

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 );

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 );

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...
}

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();
    }
}

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;
    }
}

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();