## GeoclueMasterClient

GeoclueMasterClient — Geoclue MasterClient API

## Synopsis

    #define             GEOCLUE_MASTER_CLIENT_DBUS_INTERFACE
                        GeoclueMasterClient;
    gboolean            geoclue_master_client_set_requirements
                                                            (GeoclueMasterClient *client,
                                                             GeoclueAccuracyLevel min_accuracy,
                                                             int min_time,
                                                             gboolean require_updates,
                                                             GeoclueResourceFlags allowed_resources,
                                                             GError **error);
    void                (*GeoclueSetRequirementsCallback)   (GeoclueMasterClient *client,
                                                             GError *error,
                                                             gpointer userdata);
    void                geoclue_master_client_set_requirements_async
                                                            (GeoclueMasterClient *client,
                                                             GeoclueAccuracyLevel min_accuracy,
                                                             int min_time,
                                                             gboolean require_updates,
                                                             GeoclueResourceFlags allowed_resources,
                                                             GeoclueSetRequirementsCallback callback,
                                                             gpointer userdata);
    GeoclueAddress *    geoclue_master_client_create_address
                                                            (GeoclueMasterClient *client,
                                                             GError **error);
    void                (*CreateAddressCallback)            (GeoclueMasterClient *client,
                                                             GeoclueAddress *address,
                                                             GError *error,
                                                             gpointer userdata);
    void                geoclue_master_client_create_address_async
                                                            (GeoclueMasterClient *client,
                                                             CreateAddressCallback callback,
                                                             gpointer userdata);
    GeocluePosition *   geoclue_master_client_create_position
                                                            (GeoclueMasterClient *client,
                                                             GError **error);
    void                (*CreatePositionCallback)           (GeoclueMasterClient *client,
                                                             GeocluePosition *position,
                                                             GError *error,
                                                             gpointer userdata);
    void                geoclue_master_client_create_position_async
                                                            (GeoclueMasterClient *client,
                                                             CreatePositionCallback callback,
                                                             gpointer userdata);
    gboolean            geoclue_master_client_get_address_provider
                                                            (GeoclueMasterClient *client,
                                                             char **name,
                                                             char **description,
                                                             char **service,
                                                             char **path,
                                                             GError **error);
    void                (*GeoclueGetProviderCallback)       (GeoclueMasterClient *client,
                                                             char *name,
                                                             char *description,
                                                             char *service,
                                                             char *path,
                                                             GError *error,
                                                             gpointer userdata);
    void                geoclue_master_client_get_address_provider_async
                                                            (GeoclueMasterClient *client,
                                                             GeoclueGetProviderCallback callback,
                                                             gpointer userdata);
    gboolean            geoclue_master_client_get_position_provider
                                                            (GeoclueMasterClient *client,
                                                             char **name,
                                                             char **description,
                                                             char **service,
                                                             char **path,
                                                             GError **error);
    void                geoclue_master_client_get_position_provider_async
                                                            (GeoclueMasterClient *client,
                                                             GeoclueGetProviderCallback callback,
                                                             gpointer userdata);

## Object Hierarchy

      GObject
       +----GeoclueMasterClient

## Properties

      "object-path"              gchar*                : Write / Construct Only

## Signals

      "address-provider-changed"                       : Run First / No Recursion
      "invalidated"                                    : Run First / No Recursion
      "position-provider-changed"                      : Run First / No Recursion

## Description

GeoclueMasterClient is part of the Geoclue public C client API. It uses D-Bus to communicate with the actual Master service.

GeoclueMasterClient is used to control the client specific behaviour of Geoclue Master. Chapter "Master provider: simple example in C" contains a more complete example, but here are the main parts:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25

    GeoclueMaster *master;
    GeoclueMasterClient *client;
    GeoclueAddress *address;

    ...

    master = geoclue_master_get_default ();
    client = geoclue_master_create_client (master, NULL, NULL);

    if (!geoclue_master_client_set_requirements (client,
                                                 GEOCLUE_ACCURACY_LEVEL_NONE,
                                                 0, FALSE,
                                                 GEOCLUE_RESOURCE_NETWORK,
                                                 &error)) {
    	/ * handle error * /
    }

    address = geoclue_master_client_create_address (client, error);
    if (!address) {
    	/ * handle error * /
    }

    / * Now we can use address just like we'd use a normal address provider,
        but GeoclueMasterClient makes sure that underneath the provider
        that best matches our requirements is used * /

## Details

### GEOCLUE_MASTER_CLIENT_DBUS_INTERFACE

    #define GEOCLUE_MASTER_CLIENT_DBUS_INTERFACE "org.freedesktop.Geoclue.MasterClient"

### GeoclueMasterClient

    typedef struct _GeoclueMasterClient GeoclueMasterClient;

### geoclue_master_client_set_requirements ()

    gboolean            geoclue_master_client_set_requirements
                                                            (GeoclueMasterClient *client,
                                                             GeoclueAccuracyLevel min_accuracy,
                                                             int min_time,
                                                             gboolean require_updates,
                                                             GeoclueResourceFlags allowed_resources,
                                                             GError **error);

Sets the criteria that should be used when selecting the used provider

`client` : | A GeoclueMasterClient
`min_accuracy` : | The required minimum accuracy as a GeoclueAccuracyLevel.
`min_time` : | The minimum time between update signals (currently not implemented)
`require_updates` : | Whether the updates (signals) are required. Only applies to interfaces with signals
`allowed_resources` : | The resources that are allowed to be used as a GeoclueResourceFlags
`error` : | A pointer to returned GError or `NULL`.
Returns : | `TRUE` on success

### GeoclueSetRequirementsCallback ()

    void                (*GeoclueSetRequirementsCallback)   (GeoclueMasterClient *client,
                                                             GError *error,
                                                             gpointer userdata);

Callback function for `geoclue_master_client_set_requirements_async()`.

`client` : | A GeoclueMasterClient object
`error` : | Error as Gerror (may be `NULL`)
`userdata` : | User data pointer set in `geoclue_master_client_set_requirements_async()`

### geoclue_master_client_set_requirements_async ()

    void                geoclue_master_client_set_requirements_async
                                                            (GeoclueMasterClient *client,
                                                             GeoclueAccuracyLevel min_accuracy,
                                                             int min_time,
                                                             gboolean require_updates,
                                                             GeoclueResourceFlags allowed_resources,
                                                             GeoclueSetRequirementsCallback callback,
                                                             gpointer userdata);

Asynchronous version of `geoclue_master_client_set_requirements()`.

`client` : | A GeoclueMasterClient
`min_accuracy` : | The required minimum accuracy as a GeoclueAccuracyLevel.
`min_time` : | The minimum time between update signals (currently not implemented)
`require_updates` : | Whether the updates (signals) are required. Only applies to interfaces with signals
`allowed_resources` : | The resources that are allowed to be used as a GeoclueResourceFlags
`callback` : | GeoclueSetRequirementsCallback function to call when requirements have been set
`userdata` : | User data pointer

### geoclue_master_client_create_address ()

    GeoclueAddress *    geoclue_master_client_create_address
                                                            (GeoclueMasterClient *client,
                                                             GError **error);

Starts the GeoclueMasterClient address provider and returns a GeoclueAddress that uses the same D-Bus object as the GeoclueMasterClient.

`client` : | A GeoclueMasterClient
`error` : | A pointer to returned GError or `NULL`.
Returns : | New GeoclueAddress or `NULL` on error

### CreateAddressCallback ()

    void                (*CreateAddressCallback)            (GeoclueMasterClient *client,
                                                             GeoclueAddress *address,
                                                             GError *error,
                                                             gpointer userdata);

Callback function for `geoclue_master_client_create_address_async()`.

`client` : | A GeoclueMasterClient object
`address` : | returned GeoclueAddress
`error` : | Error as Gerror (may be `NULL`)
`userdata` : | User data pointer set in `geoclue_master_client_create_address_async()`

### geoclue_master_client_create_address_async ()

    void                geoclue_master_client_create_address_async
                                                            (GeoclueMasterClient *client,
                                                             CreateAddressCallback callback,
                                                             gpointer userdata);

Function returns (essentially) immediately and calls `callback` when it has started the address provider and a GeoclueAddress is available.

`client` : | A GeoclueMasterClient object
`callback` : | A CreateAddressCallback function that should be called when return values are available
`userdata` : | pointer for user specified data

### geoclue_master_client_create_position ()

    GeocluePosition *   geoclue_master_client_create_position
                                                            (GeoclueMasterClient *client,
                                                             GError **error);

Starts the GeoclueMasterClient position provider and returns a GeocluePosition that uses the same D-Bus object as the GeoclueMasterClient.

`client` : | A GeoclueMasterClient
`error` : | A pointer to returned GError or `NULL`.
Returns : | New GeocluePosition or `NULL` on error

### CreatePositionCallback ()

    void                (*CreatePositionCallback)           (GeoclueMasterClient *client,
                                                             GeocluePosition *position,
                                                             GError *error,
                                                             gpointer userdata);

Callback function for `geoclue_master_client_create_position_async()`.

`client` : | A GeoclueMasterClient object
`position` : | returned GeocluePosition
`error` : | Error as Gerror (may be `NULL`)
`userdata` : | User data pointer set in `geoclue_master_client_create_position_async()`

### geoclue_master_client_create_position_async ()

    void                geoclue_master_client_create_position_async
                                                            (GeoclueMasterClient *client,
                                                             CreatePositionCallback callback,
                                                             gpointer userdata);

Function returns (essentially) immediately and calls `callback` when it has started the position provider and a GeocluePosition is available.

`client` : | A GeoclueMasterClient object
`callback` : | A CreatePositionCallback function that should be called when return values are available
`userdata` : | pointer for user specified data

### geoclue_master_client_get_address_provider ()

    gboolean            geoclue_master_client_get_address_provider
                                                            (GeoclueMasterClient *client,
                                                             char **name,
                                                             char **description,
                                                             char **service,
                                                             char **path,
                                                             GError **error);

Gets name and other information for the currently used address provider.

`client` : | A GeoclueMasterClient
`name` : | Pointer to returned provider name or `NULL`
`description` : | Pointer to returned provider description or `NULL`
`service` : | Pointer to returned D-Bus service name or `NULL`
`path` : | Pointer to returned D-Bus object path or `NULL`
`error` : | Pointer to returned GError or `NULL`
Returns : | `TRUE` on success

### GeoclueGetProviderCallback ()

    void                (*GeoclueGetProviderCallback)       (GeoclueMasterClient *client,
                                                             char *name,
                                                             char *description,
                                                             char *service,
                                                             char *path,
                                                             GError *error,
                                                             gpointer userdata);

`client` : |
`name` : |
`description` : |
`service` : |
`path` : |
`error` : |
`userdata` : |

### geoclue_master_client_get_address_provider_async ()

    void                geoclue_master_client_get_address_provider_async
                                                            (GeoclueMasterClient *client,
                                                             GeoclueGetProviderCallback callback,
                                                             gpointer userdata);

Gets name and other information for the currently used address provider asynchronously.

`client` : | A GeoclueMasterClient
`callback` : | A GeoclueGetProviderCallback function that will be called when return values are available
`userdata` : | pointer for user specified data

### geoclue_master_client_get_position_provider ()

    gboolean            geoclue_master_client_get_position_provider
                                                            (GeoclueMasterClient *client,
                                                             char **name,
                                                             char **description,
                                                             char **service,
                                                             char **path,
                                                             GError **error);

Gets name and other information for the currently used position provider.

`client` : | A GeoclueMasterClient
`name` : | Pointer to returned provider name or `NULL`
`description` : | Pointer to returned provider description or `NULL`
`service` : | Pointer to returned D-Bus service name or `NULL`
`path` : | Pointer to returned D-Bus object path or `NULL`
`error` : | Pointer to returned GError or `NULL`
Returns : | `TRUE` on success

### geoclue_master_client_get_position_provider_async ()

    void                geoclue_master_client_get_position_provider_async
                                                            (GeoclueMasterClient *client,
                                                             GeoclueGetProviderCallback callback,
                                                             gpointer userdata);

Gets name and other information for the currently used position provider asynchronously.

`client` : | A GeoclueMasterClient
`callback` : | A GeoclueGetProviderCallback function that will be called when return values are available
`userdata` : | pointer for user specified data

## Property Details

### The `"object-path"` property

      "object-path"              gchar*                : Write / Construct Only

The DBus path to the object.

Default value: ""

## Signal Details

### The `"address-provider-changed"` signal

    void                user_function                      (GeoclueMasterClient *client,
                                                            gchar               *name,
                                                            gchar               *description,
                                                            gchar               *service,
                                                            gchar               *path,
                                                            gpointer             user_data)        : Run First / No Recursion

The address-provider-changed signal is emitted each time the used address provider changes.

`client` : | the GeoclueMasterClient object emitting the signal
`name` : | name of the new provider (e.g. "Hostip") or `NULL` if there is no provider
`description` : | a short description of the new provider or `NULL` if there is no provider
`service` : | D-Bus service name of the new provider or `NULL` if there is no provider
`path` : | D-Bus object path name of the new provider or `NULL` if there is no provider
`user_data` : | user data set when the signal handler was connected.

### The `"invalidated"` signal

    void                user_function                      (GeoclueMasterClient *client,
                                                            gpointer             user_data)      : Run First / No Recursion

The client has been invalidated. This is emitted when Geoclue Dbus services disappear unexpectedly (possibly due to a crash). Upon receiving this signal, you should unref your client and create a new one.

`client` : | the GeoclueMasterClient object emitting the signal
`user_data` : | user data set when the signal handler was connected.

### The `"position-provider-changed"` signal

    void                user_function                      (GeoclueMasterClient *client,
                                                            gchar               *name,
                                                            gchar               *description,
                                                            gchar               *service,
                                                            gchar               *path,
                                                            gpointer             user_data)        : Run First / No Recursion

The position-provider-changed signal is emitted each time the used position provider changes.

`client` : | the GeoclueMasterClient object emitting the signal
`name` : | name of the new provider (e.g. "Hostip") or `NULL` if there is no provider
`description` : | a short description of the new provider or `NULL` if there is no provider
`service` : | D-Bus service name of the new provider or `NULL` if there is no provider
`path` : | D-Bus object path name of the new provider or `NULL` if there is no provider
`user_data` : | user data set when the signal handler was connected.