## 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);
    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);
    gboolean            geoclue_master_client_get_position_provider
                                                            (GeoclueMasterClient *client,
                                                             char **name,
                                                             char **description,
                                                             char **service,
                                                             char **path,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----GeoclueMasterClient

## Properties

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

## Signals

      "address-provider-changed"                       : 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:

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

    ...

    master = geoclue_master_get_default ();

    client = geoclue_master_create_client (master, NULL, NULL);
    if (!client) {
    	/ * handle error * /
    }

    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

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

`client` : |
`address` : |
`error` : |
`userdata` : |

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

`client` : |
`position` : |
`error` : |
`userdata` : |

### 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

### 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

## 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 `"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.