GClueSimple: Libgeoclue Reference Manual

## GClueSimple GClueSimple — Simplified convenience API |

## Functions

void | gclue_simple_new ()
GClueSimple * | gclue_simple_new_finish ()
void | gclue_simple_new_with_thresholds ()
GClueSimple * | gclue_simple_new_with_thresholds_finish ()
GClueSimple * | gclue_simple_new_sync ()
GClueClient * | gclue_simple_get_client ()
GClueLocation * | gclue_simple_get_location ()

## Properties

GClueAccuracyLevel | accuracy-level | Write / Construct Only
GClueClientProxy * | client | Read
char * | desktop-id | Write / Construct Only
guint | distance-threshold | Read / Write / Construct Only
GClueLocationProxy * | location | Read
guint | time-threshold | Read / Write / Construct Only

## Object Hierarchy

        GObject
        ╰── GClueSimple

## Description

GClueSimple make it very simple to get latest location and monitoring location updates. It takes care of the boring tasks of creating a GClueClientProxy instance, starting it, waiting till we have a location fix and then creating a GClueLocationProxy instance for it.

Use `gclue_simple_new()` or `gclue_simple_new_sync()` to create a new GClueSimple instance. Once you have a GClueSimple instance, you can get the latest location using `gclue_simple_get_location()` or reading the “location” property. To monitor location updates, connect to notify signal for this property.

While most applications will find this API very useful, it is most useful for applications that simply want to get the current location as quickly as possible and do not care about accuracy (much).

## Functions

### gclue_simple_new ()

    void
    gclue_simple_new (const char *desktop_id,
                      GClueAccuracyLevel accuracy_level,
                      GCancellable *cancellable,
                      GAsyncReadyCallback callback,
                      gpointer user_data);

Asynchronously creates a GClueSimple instance. Use `gclue_simple_new_finish()` to get the created GClueSimple instance.

See `gclue_simple_new_sync()` for the synchronous, blocking version of this function.

#### Parameters

desktop_id | The desktop file id (the basename of the desktop file). |
accuracy_level | The requested accuracy level as GClueAccuracyLevel. |
cancellable | A GCancellable or `NULL`. | [allow-none]
callback | A GAsyncReadyCallback to call when the results are ready. |
user_data | User data to pass to `callback` . |

### gclue_simple_new_finish ()

    GClueSimple *
    gclue_simple_new_finish (GAsyncResult *result,
                             GError **error);

Finishes an operation started with `gclue_simple_new()`.

#### Parameters

result | The GAsyncResult obtained from the GAsyncReadyCallback passed to `gclue_simple_new()`. |
error | Return location for error or `NULL`. |

#### Returns

The constructed proxy object or `NULL` if `error` is set.

[transfer full][type GClueSimple]

### gclue_simple_new_with_thresholds ()

    void
    gclue_simple_new_with_thresholds (const char *desktop_id,
                                      GClueAccuracyLevel accuracy_level,
                                      guint time_threshold,
                                      guint distance_threshold,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

Asynchronously creates a GClueSimple instance. Use `gclue_simple_new_with_thresholds_finish()` to get the created GClueSimple instance.

See ``gclue_simple_new_with_thresholds_sync()`` for the synchronous, blocking version of this function.

#### Parameters

desktop_id | The desktop file id (the basename of the desktop file). |
accuracy_level | The requested accuracy level as GClueAccuracyLevel. |
time_threshold | Time threshold in seconds, 0 for no limit. |
distance_threshold | Distance threshold in meters, 0 for no limit. |
cancellable | A GCancellable or `NULL`. | [allow-none]
callback | A GAsyncReadyCallback to call when the results are ready. |
user_data | User data to pass to `callback` . |

### gclue_simple_new_with_thresholds_finish ()

    GClueSimple *
    gclue_simple_new_with_thresholds_finish
                                   (GAsyncResult *result,
                                    GError **error);

Finishes an operation started with `gclue_simple_new_with_thresholds()`.

#### Parameters

result | The GAsyncResult obtained from the GAsyncReadyCallback passed to `gclue_simple_new_with_thresholds()`. |
error | Return location for error or `NULL`. |

#### Returns

The constructed proxy object or `NULL` if `error` is set.

[transfer full][type GClueSimple]

### gclue_simple_new_sync ()

    GClueSimple *
    gclue_simple_new_sync (const char *desktop_id,
                           GClueAccuracyLevel accuracy_level,
                           GCancellable *cancellable,
                           GError **error);

The synchronous and blocking version of `gclue_simple_new()`.

#### Parameters

desktop_id | The desktop file id (the basename of the desktop file). |
accuracy_level | The requested accuracy level as GClueAccuracyLevel. |
cancellable | A GCancellable or `NULL`. | [allow-none]
error | Return location for error or `NULL`. |

#### Returns

The new GClueSimple object or `NULL` if `error` is set.

[transfer full][type GClueSimple]

### gclue_simple_get_client ()

    GClueClient *
    gclue_simple_get_client (GClueSimple *simple);

Gets the client proxy, or `NULL` if `simple` is not using a client proxy (i-e when inside the Flatpak sandbox).

#### Parameters

simple | A GClueSimple object. |

#### Returns

The client object.

[nullable][transfer none][type GClueClientProxy]

### gclue_simple_get_location ()

    GClueLocation *
    gclue_simple_get_location (GClueSimple *simple);

Gets the current location.

#### Parameters

simple | A GClueSimple object. |

#### Returns

The last known location as GClueLocation.

[nullable][transfer none][type GClueLocation]

## Property Details

### The `“accuracy-level”` property

      “accuracy-level”           GClueAccuracyLevel

The requested maximum accuracy level.

Owner: GClueSimple

Flags: Write / Construct Only

Default value: GCLUE_ACCURACY_LEVEL_NONE

### The `“client”` property

      “client”                   GClueClientProxy *

The client proxy. This is `NULL` if `simple` is not using a client proxy (i-e when inside the Flatpak sandbox).

Owner: GClueSimple

Flags: Read

### The `“desktop-id”` property

      “desktop-id”               char *

The Desktop ID of the application.

Owner: GClueSimple

Flags: Write / Construct Only

Default value: NULL

### The `“distance-threshold”` property

      “distance-threshold”       guint

The current distance threshold in meters. This value is used by the service when it gets new location info. If the distance moved is below the threshold, it won't emit the LocationUpdated signal.

When set to 0 (default), it always emits the signal.

Owner: GClueSimple

Flags: Read / Write / Construct Only

Default value: 0

### The `“location”` property

      “location”                 GClueLocationProxy *

The current location.

Owner: GClueSimple

Flags: Read

### The `“time-threshold”` property

      “time-threshold”           guint

The current time threshold in seconds. This value is used by the service when it gets new location info. If the time passed is below the threshold, it won't emit the LocationUpdated signal.

When set to 0 (default), it always emits the signal.

Owner: GClueSimple

Flags: Read / Write / Construct Only

Default value: 0