API Documentation

Documentation for developing SailfishOS applications

LocationSettings Class

(Sailfish::Mdm::LocationSettings)

The LocationSettings class controls device positioning features. More...

Header: #include <mdm-location.h>

Public Types

enum DataSource { NoDataSources, OnlineDataSources, DeviceSensorsData, BluetoothData, ..., LastDataSource }
flags DataSources
enum LocationMode { HighAccuracyMode, BatterySavingMode, DeviceOnlyMode, CustomMode }
enum Mode { AsynchronousMode, SynchronousMode }

Properties

Public Functions

LocationSettings(QObject *parent = Q_NULLPTR)
LocationSettings(Mode mode, QObject *parent = Q_NULLPTR)
bool agpsAgreementAccepted(const QString &agpsProvider) const
bool agpsAvailable(const QString &agpsProvider) const
bool agpsEnabled(const QString &agpsProvider) const
void allowDataSource(DataSource dataSource)
DataSources allowedDataSources() const
QStringList availableAgpsProviders() const
void disallowDataSource(DataSource dataSource)
bool gpsAvailable() const
bool gpsEnabled() const
bool gpsFlightMode() const
bool locationEnabled() const
LocationMode locationMode() const
void setAgpsAgreementAccepted(const QString &agpsProvider, bool value)
void setAgpsEnabled(const QString &agpsProvider, bool value)
void setAllowedDataSources(DataSources dataSources)
void setGpsEnabled(bool value)
void setGpsFlightMode(bool value)
void setLocationEnabled(bool value)
void setLocationMode(LocationMode locationMode)

Signals

Detailed Description

The LocationSettings class controls device positioning features.

A variety of device positioning methods can be enabled or disabled, including GPS and aGPS positioning.

To use this class, clients must add the following to their qmake project:

 CONFIG += link_pkgconfig
 PKGCONFIG += sailfishmdm

and then #include <mdm-location.h>.

Example of usage:

 #include <mdm-location.h>
 void enableOrDisableGps(bool enable, QObject *parent)
 {
     Sailfish::Mdm::LocationSettings *settings = new Sailfish::Mdm::LocationSettings(parent);
     settings->setGpsEnabled(enable);
     settings->setGpsFlightMode(!enable);
     settings->setLocationEnabled(enable);
 }

Member Type Documentation

enum LocationSettings::DataSource
flags LocationSettings::DataSources

Defines the available positioning data sources.

ConstantValueDescription
Sailfish::Mdm::LocationSettings::NoDataSources0ULNo data sources are in use
Sailfish::Mdm::LocationSettings::OnlineDataSources1UL<<0Online services
Sailfish::Mdm::LocationSettings::DeviceSensorsData1UL<<5Device sensor data
Sailfish::Mdm::LocationSettings::BluetoothData1UL<<10Bluetooth positioning data
Sailfish::Mdm::LocationSettings::WlanData1UL<<15WLAN positioning data
Sailfish::Mdm::LocationSettings::CellTowerData1UL<<20Mobile cell towers
Sailfish::Mdm::LocationSettings::GpsData1UL<<25Global Positioning System (GPS)
Sailfish::Mdm::LocationSettings::GlonassData1UL<<26Global Navigation Satellite System (GLONASS)
Sailfish::Mdm::LocationSettings::BeidouData1UL<<27BeiDou Navigation Satellite System (BDS)
Sailfish::Mdm::LocationSettings::GalileoData1UL<<28Galileo satellite system
Sailfish::Mdm::LocationSettings::QzssData1UL<<29Quasi-Zenith Satellite System (QZSS)
Sailfish::Mdm::LocationSettings::SbasData1UL<<30Satellite-based Augmentation System (SBAS)
Sailfish::Mdm::LocationSettings::LastDataSource1UL<<31A placeholder value indicating the last possible value in this enum.

The DataSources type is a typedef for QFlags<DataSource>. It stores an OR combination of DataSource values.

enum LocationSettings::LocationMode

This enum type specifies some modes which define how the device will calculate its location. Each mode is simply a short-hand label for a selection of various settings.

ConstantValueDescription
Sailfish::Mdm::LocationSettings::HighAccuracyMode0The device will use the GPS (global positioning system), and any aGPS (assisted global positioning system) or NLPs (network location providers), to calculate its location.
Sailfish::Mdm::LocationSettings::BatterySavingMode1The device will use NLPs and device-based (e.g. cell-tower triangulation) positioning, but not the GPS.
Sailfish::Mdm::LocationSettings::DeviceOnlyMode2The device will use the GPS and aGPS, plus device-based (e.g. cell-tower triangulation) positioning, but no NLPs, to calculate its location.
Sailfish::Mdm::LocationSettings::CustomMode3The device will use some custom selection of positioning methods to calculate its location.

enum LocationSettings::Mode

Describes whether settings are modified and retrieved synchronously or asynchronously.

ConstantValueDescription
Sailfish::Mdm::LocationSettings::AsynchronousMode0When a setting is value is retrieved or modified, the method returns immediately; if the value is modified, the setting value does not change until the modification is confirmed by the backend libraries.
Sailfish::Mdm::LocationSettings::SynchronousMode1Attempts to retrieve or modify a setting block the current thread until the operation to retrieve or modify the property is completed.

Property Documentation

allowedDataSources : DataSources

This property holds the currently allowed data sources which may be used by the device to determine its location.

Access functions:

DataSources allowedDataSources() const
void setAllowedDataSources(DataSources dataSources)

Notifier signal:

void allowedDataSourcesChanged()

gpsAvailable : const bool

This property holds true if the device has a GPS and supports this positioning method.

Access functions:

bool gpsAvailable() const

gpsEnabled : bool

This property holds true if GPS positioning is currently enabled on the device.

If this is true, and positioning is globally enabled (as reported by locationEnabled), then the GPS provider will provide position updates to clients.

If this is true but positioning is globally disabled (as reported by locationEnabled) then the GPS provider will NOT provide any position updates, and the GPS hardware will be turned off, just as if GPS positioning was itself disabled.

Note: Changing this setting does not prevent it from being changed via e.g. the settings UI. In order to prevent the value from being changed by the user, the MDM client should also set the policy for this setting via the libsailfishpolicy API.

Access functions:

bool gpsEnabled() const
void setGpsEnabled(bool value)

Notifier signal:

void gpsEnabledChanged()

locationEnabled : bool

This property holds true if positioning is currently enabled on the device.

If positioning is enabled, and at least one positioning method (i.e., GPS or an aGPS provider) is also enabled, then applications with the appropriate privileges will be able to receive location updates.

Note: Changing this setting does not prevent it from being changed via e.g. the settings UI. In order to prevent the value from being changed by the user, the MDM client should also set the policy for this setting via the libsailfishpolicy API.

Access functions:

bool locationEnabled() const
void setLocationEnabled(bool value)

Notifier signal:

void locationEnabledChanged()

locationMode : LocationMode

This property holds the current LocationMode which defines which methods the device will use in order to determine its location.

Note that the various location modes are merely short-hand descriptors for different enablement states which may be independently set using the other methods of this class. See the LocationMode documentation for more information.

Also note that this operation may not be able to be completed, if the appropriate agreements have not yet been accepted or if appropriate network location providers are not available. In that case, the next-most-applicable settings for the given locationMode will be applied.

Access functions:

LocationMode locationMode() const
void setLocationMode(LocationMode locationMode)

Notifier signal:

void locationModeChanged()

Member Function Documentation

LocationSettings::LocationSettings(QObject *parent = Q_NULLPTR)

Default constructs an instance of LocationSettings.

LocationSettings::LocationSettings(Mode mode, QObject *parent = Q_NULLPTR)

Default constructs an instance of LocationSettings.

bool LocationSettings::agpsAgreementAccepted(const QString &agpsProvider) const

Returns true if the usage terms agreement with the aGPS provider whose name matches the given agpsProvider name has been accepted.

See also setAgpsAgreementAccepted().

bool LocationSettings::agpsAvailable(const QString &agpsProvider) const

Returns true if the device has an aGPS provider whose name matches the given agpsProvider name.

Agps provider can be, for example, "here" or "mls" (Mozilla Location Services).

bool LocationSettings::agpsEnabled(const QString &agpsProvider) const

Returns true if the aGPS provider whose name matches the given agpsProvider name is enabled.

If the aGPS provider is enabled and positioning is globally enabled (as reported by locationEnabled()) then the aGPS provider will provide position updates to clients.

Note that if the aGPS provider is enabled but positioning is globally disabled (as reported by locationEnabled()) then the aGPS provider will NOT provide any position updates, nor attempt to communicate with the aGPS backend services, just as if the aGPS provider was itself disabled.

See also setAgpsEnabled().

void LocationSettings::allowDataSource(DataSource dataSource)

Allows the client to allow the device to use the specified dataSource to determine its location.

QStringList LocationSettings::availableAgpsProviders() const

Returns the names of known network location providers and device-local location assistance providers which are available on the device.

void LocationSettings::disallowDataSource(DataSource dataSource)

Allows the client to disallow the device from using the specified dataSource to determine its location.

bool LocationSettings::gpsFlightMode() const

Returns true if the GPS hardware is currently powered off due to Flight Mode.

Note that if the GPS is powered off due to Flight Mode, then the GPS provider will NOT provide any position updates, and the GPS hardware will be turned off.

See also setGpsFlightMode().

[signal] void LocationSettings::gpsFlightModeChanged()

This signal is emitted if the GPS hardware should be powered off due to flight mode, or if it can be powered on due to flight mode being disabled or due to the user explicitly allowing the GPS to be used even in flight mode.

void LocationSettings::setAgpsAgreementAccepted(const QString &agpsProvider, bool value)

Allows the client to accept or revoke the usage terms agreement with the aGPS provider whose name matches the given agpsProvider name, depending on the given acceptance value.

See also agpsAgreementAccepted().

void LocationSettings::setAgpsEnabled(const QString &agpsProvider, bool value)

Allows the client to enable or disable the aGPS provider whose name matches the given agpsProvider name, depending on the given enablement value.

Note that this method allows the MDM client to enable or disable aGPS providers, but doesn't prevent these settings from being changed via e.g. the settings UI. In order to prevent the value from being changed by the user, the MDM client should also set the policy for this setting via the libsailfishpolicy API.

See also agpsEnabled().

void LocationSettings::setGpsFlightMode(bool value)

Allows the client to set the Flight Mode state of the GPS hardware to value.

Note that this method allows the MDM client to set the GPS flight mode state, but doesn't prevent this setting from being changed via e.g. the settings UI. In order to prevent the value from being changed by the user, the MDM client should also set the policy for this setting via the libsailfishpolicy API.

See also gpsFlightMode().

We use cookies to improve your user experience and to help us to develop our services. By continuing to browse the site, you approve of our use of cookies.