MMModemLocation: libmm-glib Reference Manual

## MMModemLocation MMModemLocation — The Location interface |

## Functions

const gchar * | mm_modem_location_get_path ()
gchar * | mm_modem_location_dup_path ()
MMModemLocationSource | mm_modem_location_get_capabilities ()
MMModemLocationSource | mm_modem_location_get_enabled ()
gboolean | mm_modem_location_signals_location ()
void | mm_modem_location_setup ()
gboolean | mm_modem_location_setup_finish ()
gboolean | mm_modem_location_setup_sync ()
void | mm_modem_location_get_3gpp ()
MMLocation3gpp * | mm_modem_location_get_3gpp_finish ()
MMLocation3gpp * | mm_modem_location_get_3gpp_sync ()
void | mm_modem_location_get_gps_nmea ()
MMLocationGpsNmea * | mm_modem_location_get_gps_nmea_finish ()
MMLocationGpsNmea * | mm_modem_location_get_gps_nmea_sync ()
void | mm_modem_location_get_gps_raw ()
MMLocationGpsRaw * | mm_modem_location_get_gps_raw_finish ()
MMLocationGpsRaw * | mm_modem_location_get_gps_raw_sync ()
void | mm_modem_location_get_cdma_bs ()
MMLocationCdmaBs * | mm_modem_location_get_cdma_bs_finish ()
MMLocationCdmaBs * | mm_modem_location_get_cdma_bs_sync ()
void | mm_modem_location_get_full ()
gboolean | mm_modem_location_get_full_finish ()
gboolean | mm_modem_location_get_full_sync ()

## Types and Values

struct | MMModemLocation
#define | MM_LOCATION_LONGITUDE_UNKNOWN
#define | MM_LOCATION_LATITUDE_UNKNOWN
#define | MM_LOCATION_ALTITUDE_UNKNOWN

## Object Hierarchy

        GObject
        ╰── GDBusProxy
            ╰── MmGdbusModemLocationProxy
                ╰── MMModemLocation

## Implemented Interfaces

MMModemLocation implements GDBusInterface, GInitable, GAsyncInitable and MmGdbusModemLocation.

## Description

The MMModemLocation is an object providing access to the methods, signals and properties of the Location interface.

The Location interface is exposed whenever a modem has location capabilities.

## Functions

### mm_modem_location_get_path ()

    const gchar *
    mm_modem_location_get_path (MMModemLocation *self);

Gets the DBus path of the MMObject which implements this interface.

#### Parameters

self | A MMModemLocation. |

#### Returns

The DBus path of the MMObject object.

[transfer none]

### mm_modem_location_dup_path ()

    gchar *
    mm_modem_location_dup_path (MMModemLocation *self);

Gets a copy of the DBus path of the MMObject object which implements this interface.

#### Parameters

self | A MMModemLocation. |

#### Returns

The DBus path of the MMObject. The returned value should be freed with `g_free()`.

[transfer full]

### mm_modem_location_get_capabilities ()

    MMModemLocationSource
    mm_modem_location_get_capabilities (MMModemLocation *self);

Gets a bitmask of the location capabilities supported by this MMModemLocation.

#### Parameters

self | A MMModemLocation. |

#### Returns

A MMModemLocationSource.

### mm_modem_location_get_enabled ()

    MMModemLocationSource
    mm_modem_location_get_enabled (MMModemLocation *self);

Gets a bitmask of the location capabilities which are enabled in this MMModemLocation.

#### Parameters

self | A MMModemLocation. |

#### Returns

A MMModemLocationSource.

### mm_modem_location_signals_location ()

    gboolean
    mm_modem_location_signals_location (MMModemLocation *self);

Gets the status of the location signaling in the MMModemLocation.

#### Parameters

self | A MMModemLocation. |

#### Returns

`TRUE` if location changes are signaled, `FALSE` otherwise..

### mm_modem_location_setup ()

    void
    mm_modem_location_setup (MMModemLocation *self,
                             MMModemLocationSource sources,
                             gboolean signal_location,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Asynchronously configures the location sources to use when gathering location information. Also enable or disable location information gathering.

When the operation is finished, `callback` will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call `mm_modem_location_setup_finish()` to get the result of the operation.

See `mm_modem_location_setup_sync()` for the synchronous, blocking version of this method.

#### Parameters

self | A MMModemLocation. |
sources | Bitmask of MMModemLocationSource values specifying which locations should get enabled. |
signal_location | Flag to enable or disable location signaling. |
cancellable | A GCancellable or `NULL`. | [allow-none]
callback | A GAsyncReadyCallback to call when the request is satisfied or `NULL`. |
user_data | User data to pass to `callback` . |

### mm_modem_location_setup_finish ()

    gboolean
    mm_modem_location_setup_finish (MMModemLocation *self,
                                    GAsyncResult *res,
                                    GError **error);

Finishes an operation started with `mm_modem_location_setup()`.

#### Parameters

self | A MMModemLocation. |
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_modem_location_setup()`. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the setup was successful, `FALSE` if `error` is set.

### mm_modem_location_setup_sync ()

    gboolean
    mm_modem_location_setup_sync (MMModemLocation *self,
                                  MMModemLocationSource sources,
                                  gboolean signal_location,
                                  GCancellable *cancellable,
                                  GError **error);

Synchronously configures the location sources to use when gathering location information. Also enable or disable location information gathering.

The calling thread is blocked until a reply is received. See `mm_modem_location_setup()` for the asynchronous version of this method.

#### Parameters

self | A MMModemLocation. |
sources | Bitmask of MMModemLocationSource values specifying which locations should get enabled. |
signal_location | Flag to enable or disable location signaling. |
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the setup was successful, `FALSE` if `error` is set.

### mm_modem_location_get_3gpp ()

    void
    mm_modem_location_get_3gpp (MMModemLocation *self,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously gets the current 3GPP location information.

When the operation is finished, `callback` will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call `mm_modem_location_get_3gpp_finish()` to get the result of the operation.

See `mm_modem_location_get_3gpp_sync()` for the synchronous, blocking version of this method.

#### Parameters

self | A MMModemLocation. |
cancellable | A GCancellable or `NULL`. | [allow-none]
callback | A GAsyncReadyCallback to call when the request is satisfied or `NULL`. |
user_data | User data to pass to `callback` . |

### mm_modem_location_get_3gpp_finish ()

    MMLocation3gpp *
    mm_modem_location_get_3gpp_finish (MMModemLocation *self,
                                       GAsyncResult *res,
                                       GError **error);

Finishes an operation started with `mm_modem_location_get_3gpp()`.

#### Parameters

self | A MMModemLocation. |
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_modem_location_get_3gpp()`. |
error | Return location for error or `NULL`. |

#### Returns

A MMLocation3gpp, or NULL if not available. The returned value should be freed with `g_object_unref()`.

[transfer full]

### mm_modem_location_get_3gpp_sync ()

    MMLocation3gpp *
    mm_modem_location_get_3gpp_sync (MMModemLocation *self,
                                     GCancellable *cancellable,
                                     GError **error);

Synchronously gets the current 3GPP location information.

The calling thread is blocked until a reply is received. See `mm_modem_location_get_3gpp()` for the asynchronous version of this method.

#### Parameters

self | A MMModemLocation. |
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

A MMLocation3gpp, or NULL if not available. The returned value should be freed with `g_object_unref()`.

[transfer full]

### mm_modem_location_get_gps_nmea ()

    void
    mm_modem_location_get_gps_nmea (MMModemLocation *self,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Asynchronously gets the current GPS NMEA location information.

When the operation is finished, `callback` will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call `mm_modem_location_get_gps_nmea_finish()` to get the result of the operation.

See `mm_modem_location_get_gps_nmea_sync()` for the synchronous, blocking version of this method.

#### Parameters

self | A MMModemLocation. |
cancellable | A GCancellable or `NULL`. | [allow-none]
callback | A GAsyncReadyCallback to call when the request is satisfied or `NULL`. |
user_data | User data to pass to `callback` . |

### mm_modem_location_get_gps_nmea_finish ()

    MMLocationGpsNmea *
    mm_modem_location_get_gps_nmea_finish (MMModemLocation *self,
                                           GAsyncResult *res,
                                           GError **error);

Finishes an operation started with `mm_modem_location_get_gps_nmea()`.

#### Parameters

self | A MMModemLocation. |
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_modem_location_get_gps_nmea()`. |
error | Return location for error or `NULL`. |

#### Returns

A MMLocationGpsNmea, or NULL if not available. The returned value should be freed with `g_object_unref()`.

[transfer full]

### mm_modem_location_get_gps_nmea_sync ()

    MMLocationGpsNmea *
    mm_modem_location_get_gps_nmea_sync (MMModemLocation *self,
                                         GCancellable *cancellable,
                                         GError **error);

Synchronously gets the current GPS NMEA location information.

The calling thread is blocked until a reply is received. See `mm_modem_location_get_gps_nmea()` for the asynchronous version of this method.

#### Parameters

self | A MMModemLocation. |
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

A MMLocationGpsNmea, or NULL if not available. The returned value should be freed with `g_object_unref()`.

[transfer full]

### mm_modem_location_get_gps_raw ()

    void
    mm_modem_location_get_gps_raw (MMModemLocation *self,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Asynchronously gets the current GPS raw location information.

When the operation is finished, `callback` will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call `mm_modem_location_get_gps_raw_finish()` to get the result of the operation.

See `mm_modem_location_get_gps_raw_sync()` for the synchronous, blocking version of this method.

#### Parameters

self | A MMModemLocation. |
cancellable | A GCancellable or `NULL`. | [allow-none]
callback | A GAsyncReadyCallback to call when the request is satisfied or `NULL`. |
user_data | User data to pass to `callback` . |

### mm_modem_location_get_gps_raw_finish ()

    MMLocationGpsRaw *
    mm_modem_location_get_gps_raw_finish (MMModemLocation *self,
                                          GAsyncResult *res,
                                          GError **error);

Finishes an operation started with `mm_modem_location_get_gps_raw()`.

#### Parameters

self | A MMModemLocation. |
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_modem_location_get_gps_raw()`. |
error | Return location for error or `NULL`. |

#### Returns

A MMLocationGpsRaw, or NULL if not available. The returned value should be freed with `g_object_unref()`.

[transfer full]

### mm_modem_location_get_gps_raw_sync ()

    MMLocationGpsRaw *
    mm_modem_location_get_gps_raw_sync (MMModemLocation *self,
                                        GCancellable *cancellable,
                                        GError **error);

Synchronously gets the current GPS raw location information.

The calling thread is blocked until a reply is received. See `mm_modem_location_get_gps_raw()` for the asynchronous version of this method.

#### Parameters

self | A MMModemLocation. |
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

A MMLocationGpsRaw, or NULL if not available. The returned value should be freed with `g_object_unref()`.

[transfer full]

### mm_modem_location_get_cdma_bs ()

    void
    mm_modem_location_get_cdma_bs (MMModemLocation *self,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Asynchronously gets the current CDMA base station location information.

When the operation is finished, `callback` will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call `mm_modem_location_get_cdma_bs_finish()` to get the result of the operation.

See `mm_modem_location_get_cdma_bs_sync()` for the synchronous, blocking version of this method.

#### Parameters

self | A MMModemLocation. |
cancellable | A GCancellable or `NULL`. | [allow-none]
callback | A GAsyncReadyCallback to call when the request is satisfied or `NULL`. |
user_data | User data to pass to `callback` . |

### mm_modem_location_get_cdma_bs_finish ()

    MMLocationCdmaBs *
    mm_modem_location_get_cdma_bs_finish (MMModemLocation *self,
                                          GAsyncResult *res,
                                          GError **error);

Finishes an operation started with `mm_modem_location_get_cdma_bs()`.

#### Parameters

self | A MMModemLocation. |
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_modem_location_get_cdma_bs()`. |
error | Return location for error or `NULL`. |

#### Returns

A MMLocationCdmaBs, or NULL if not available. The returned value should be freed with `g_object_unref()`.

[transfer full]

### mm_modem_location_get_cdma_bs_sync ()

    MMLocationCdmaBs *
    mm_modem_location_get_cdma_bs_sync (MMModemLocation *self,
                                        GCancellable *cancellable,
                                        GError **error);

Synchronously gets the current CDMA base station location information.

The calling thread is blocked until a reply is received. See `mm_modem_location_get_cdma_bs()` for the asynchronous version of this method.

#### Parameters

self | A MMModemLocation. |
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

A MMLocationCdmaBs, or NULL if not available. The returned value should be freed with `g_object_unref()`.

[transfer full]

### mm_modem_location_get_full ()

    void
    mm_modem_location_get_full (MMModemLocation *self,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronously gets the current location information.

When the operation is finished, `callback` will be invoked in the thread-default main loop of the thread you are calling this method from. You can then call `mm_modem_location_get_full_finish()` to get the result of the operation.

See `mm_modem_location_get_full_sync()` for the synchronous, blocking version of this method.

#### Parameters

self | A MMModemLocation. |
cancellable | A GCancellable or `NULL`. | [allow-none]
callback | A GAsyncReadyCallback to call when the request is satisfied or `NULL`. |
user_data | User data to pass to `callback` . |

### mm_modem_location_get_full_finish ()

    gboolean
    mm_modem_location_get_full_finish (MMModemLocation *self,
                                       GAsyncResult *res,
                                       MMLocation3gpp **location_3gpp,
                                       MMLocationGpsNmea **location_gps_nmea,
                                       MMLocationGpsRaw **location_gps_raw,
                                       MMLocationCdmaBs **location_cdma_bs,
                                       GError **error);

Finishes an operation started with `mm_modem_location_get_full()`.

#### Parameters

self | A MMModemLocation. |
location_3gpp | Return location for a MMLocation3gpp if 3GPP location is requested, or NULL if not required. The returned value should be freed with `g_object_unref()`. | [out][allow-none][transfer full]
location_gps_nmea | Return location for a MMLocationGpsNmea if GPS NMEA location is requested, or NULL if not required. The returned value should be freed with `g_object_unref()`. | [out][allow-none][transfer full]
location_gps_raw | Return location for a MMLocationGpsRaw if GPS raw location is requested, or NULL if not required. The returned value should be freed with `g_object_unref()`. | [out][allow-none][transfer full]
location_cdma_bs | Return location for a MMLocationCdmaBs if CDMA Base Station location is requested, or NULL if not required. The returned value should be freed with `g_object_unref()`. | [out][allow-none][transfer full]
res | The GAsyncResult obtained from the GAsyncReadyCallback passed to `mm_modem_location_get_full()`. |
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the retrieval was successful, `FALSE` if `error` is set.

### mm_modem_location_get_full_sync ()

    gboolean
    mm_modem_location_get_full_sync (MMModemLocation *self,
                                     MMLocation3gpp **location_3gpp,
                                     MMLocationGpsNmea **location_gps_nmea,
                                     MMLocationGpsRaw **location_gps_raw,
                                     MMLocationCdmaBs **location_cdma_bs,
                                     GCancellable *cancellable,
                                     GError **error);

Synchronously gets the current location information.

The calling thread is blocked until a reply is received. See `mm_modem_location_get_full()` for the asynchronous version of this method.

#### Parameters

self | A MMModemLocation. |
location_3gpp | Return location for a MMLocation3gpp if 3GPP location is requested, or NULL if not required. The returned value should be freed with `g_object_unref()`. | [out][allow-none][transfer full]
location_gps_nmea | Return location for a MMLocationGpsNmea if GPS NMEA location is requested, or NULL if not required. The returned value should be freed with `g_object_unref()`. | [out][allow-none][transfer full]
location_gps_raw | Return location for a MMLocationGpsRaw if GPS raw location is requested, or NULL if not required. The returned value should be freed with `g_object_unref()`. | [out][allow-none][transfer full]
location_cdma_bs | Return location for a MMLocationCdmaBs if CDMA Base Station location is requested, or NULL if not required. The returned value should be freed with `g_object_unref()`. | [out][allow-none][transfer full]
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

`TRUE` if the setup was successful, `FALSE` if `error` is set.

## Types and Values

### struct MMModemLocation

    struct MMModemLocation;

The MMModemLocation structure contains private data and should only be accessed using the provided API.

### MM_LOCATION_LONGITUDE_UNKNOWN

    #define MM_LOCATION_LONGITUDE_UNKNOWN G_MINDOUBLE

Identifier for an unknown longitude value.

Proper longitude values fall in the [-180,180] range.

### MM_LOCATION_LATITUDE_UNKNOWN

    #define MM_LOCATION_LATITUDE_UNKNOWN  G_MINDOUBLE

Identifier for an unknown latitude value.

Proper latitude values fall in the [-90,90] range.

### MM_LOCATION_ALTITUDE_UNKNOWN

    #define MM_LOCATION_ALTITUDE_UNKNOWN  G_MINDOUBLE

Identifier for an unknown altitude value.