## GeoclueProvider GeoclueProvider — Common client API for Geoclue providers |

## Synopsis

                        GeoclueProvider;
    gboolean            geoclue_provider_get_status         (GeoclueProvider *provider,
                                                             GeoclueStatus *status,
                                                             GError **error);
    void                (*GeoclueProviderStatusCallback)    (GeoclueProvider *provider,
                                                             GeoclueStatus status,
                                                             GError *error,
                                                             gpointer userdata);
    void                geoclue_provider_get_status_async   (GeoclueProvider *provider,
                                                             GeoclueProviderStatusCallback callback,
                                                             gpointer userdata);
    gboolean            geoclue_provider_get_provider_info  (GeoclueProvider *provider,
                                                             char **name,
                                                             char **description,
                                                             GError **error);
    void                (*GeoclueProviderInfoCallback)      (GeoclueProvider *provider,
                                                             char *name,
                                                             char *description,
                                                             GError *error,
                                                             gpointer userdata);
    void                geoclue_provider_get_provider_info_async
                                                            (GeoclueProvider *provider,
                                                             GeoclueProviderInfoCallback callback,
                                                             gpointer userdata);
    gboolean            geoclue_provider_set_options        (GeoclueProvider *provider,
                                                             GHashTable *options,
                                                             GError **error);
    void                (*GeoclueProviderOptionsCallback)   (GeoclueProvider *provider,
                                                             GError *error,
                                                             gpointer userdata);
    void                geoclue_provider_set_options_async  (GeoclueProvider *provider,
                                                             GHashTable *options,
                                                             GeoclueProviderOptionsCallback callback,
                                                             gpointer userdata);

## Object Hierarchy

      GObject
       +----GeoclueProvider
             +----GeocluePosition
             +----GeoclueVelocity
             +----GeoclueAddress
             +----GeoclueGeocode
             +----GeoclueReverseGeocode

## Properties

      "interface"                gchar*                : Write / Construct Only
      "path"                     gchar*                : Write / Construct Only
      "service"                  gchar*                : Write / Construct Only

## Signals

      "status-changed"                                 : Run First / No Recursion

## Description

GeoclueProvider contains the methods and signals common to all Geoclue providers. It is part of the public C client API which uses D-Bus to communicate with the actual provider.

A GeoclueProvider is not explicitly created. Instead any provider object can be cast to GeoclueProvider. Using a GeocluePosition as example here:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    GeocluePosition *pos;
    char *name;
    GError *error;

    pos = geoclue_position_new ("org.freedesktop.Geoclue.Providers.Example",
                                "/org/freedesktop/Geoclue/Providers/Example");

    if (geoclue_provider_get_provider_info (GEOCLUE_PROVIDER (pos),
                                            &name, NULL, &error)) {
    	g_print ("name = %s", name);
    }

GeoclueProvider can be used to obtain generic information about the provider and to set provider options.

## Details

### GeoclueProvider

    typedef struct _GeoclueProvider GeoclueProvider;

### geoclue_provider_get_status ()

    gboolean            geoclue_provider_get_status         (GeoclueProvider *provider,
                                                             GeoclueStatus *status,
                                                             GError **error);

Obtains the current status of the provider.

`provider` : | A GeoclueProvider object
`status` : | Pointer for returned status as GeoclueStatus
`error` : | Pointer for returned GError or `NULL`
Returns : | `TRUE` on success

### GeoclueProviderStatusCallback ()

    void                (*GeoclueProviderStatusCallback)    (GeoclueProvider *provider,
                                                             GeoclueStatus status,
                                                             GError *error,
                                                             gpointer userdata);

Callback function for `geoclue_provider_get_status_async()`.

`provider` : | A GeoclueProvider object
`status` : | A GeoclueStatus
`error` : | Error as GError or `NULL`
`userdata` : | User data pointer set in `geoclue_provider_get_status_async()`

### geoclue_provider_get_status_async ()

    void                geoclue_provider_get_status_async   (GeoclueProvider *provider,
                                                             GeoclueProviderStatusCallback callback,
                                                             gpointer userdata);

Asynchronous version of `geoclue_provider_get_status()`. Function returns (essentially) immediately and calls `callback` when status is available or when there is an error.

`provider` : | A GeoclueProvider object
`callback` : | A GeoclueProviderStatusCallback function that will be called when return values are available
`userdata` : | pointer for user specified data

### geoclue_provider_get_provider_info ()

    gboolean            geoclue_provider_get_provider_info  (GeoclueProvider *provider,
                                                             char **name,
                                                             char **description,
                                                             GError **error);

Obtains name and a short description of the provider.

`provider` : | A GeoclueProvider object
`name` : | Pointer for returned provider name or `NULL`
`description` : | Pointer for returned provider description or `NULL`
`error` : | Pointer for returned GError or `NULL`
Returns : | `TRUE` on success

### GeoclueProviderInfoCallback ()

    void                (*GeoclueProviderInfoCallback)      (GeoclueProvider *provider,
                                                             char *name,
                                                             char *description,
                                                             GError *error,
                                                             gpointer userdata);

Callback function for `geoclue_provider_get_provider_info_async()`.

`provider` : | A GeoclueProvider object
`name` : | Name of the provider
`description` : | one-line description of the provider
`error` : | Error as GError or `NULL`
`userdata` : | User data pointer set in `geoclue_provider_get_provider_info_async()`

### geoclue_provider_get_provider_info_async ()

    void                geoclue_provider_get_provider_info_async
                                                            (GeoclueProvider *provider,
                                                             GeoclueProviderInfoCallback callback,
                                                             gpointer userdata);

Asynchronous version of `geoclue_provider_get_provider_info()`. Function returns (essentially) immediately and calls `callback` when info is available or when there is an error.

`provider` : | A GeoclueProvider object
`callback` : | A GeoclueProviderInfoCallback function that will be called when info is available
`userdata` : | pointer for user specified data

### geoclue_provider_set_options ()

    gboolean            geoclue_provider_set_options        (GeoclueProvider *provider,
                                                             GHashTable *options,
                                                             GError **error);

Sets the options on the provider.

`provider` : | A GeoclueProvider object
`options` : | A GHashTable containing the options
`error` : | Pointer for returned GError or `NULL`
Returns : | `TRUE` if setting options succeeded

### GeoclueProviderOptionsCallback ()

    void                (*GeoclueProviderOptionsCallback)   (GeoclueProvider *provider,
                                                             GError *error,
                                                             gpointer userdata);

Callback function for `geoclue_provider_set_options_async()`.

`provider` : | A GeoclueProvider object
`error` : | Error as GError or `NULL`
`userdata` : | User data pointer set in `geoclue_provider_set_options_async()`

### geoclue_provider_set_options_async ()

    void                geoclue_provider_set_options_async  (GeoclueProvider *provider,
                                                             GHashTable *options,
                                                             GeoclueProviderOptionsCallback callback,
                                                             gpointer userdata);

Asynchronous version of `geoclue_provider_set_options()`. Function returns (essentially) immediately and calls `callback` when options have been set or when there is an error.

`provider` : | A GeoclueProvider object
`options` : | A GHashTable of options
`callback` : | A GeoclueProviderOptionsCallback function that will be called when options are set
`userdata` : | pointer for user specified data

## Property Details

### The `"interface"` property

      "interface"                gchar*                : Write / Construct Only

The D-Bus interface implemented by the object.

Default value: ""

### The `"path"` property

      "path"                     gchar*                : Write / Construct Only

The D-Bus path to this provider.

Default value: ""

### The `"service"` property

      "service"                  gchar*                : Write / Construct Only

The D-Bus service this object represents.

Default value: ""

## Signal Details

### The `"status-changed"` signal

    void                user_function                      (GeoclueProvider *provider,
                                                            gint             status,
                                                            gpointer         user_data)      : Run First / No Recursion

The status-changed signal is emitted each time the provider status changes

`provider` : | the provider object emitting the signal
`status` : | New provider status as GeoclueStatus
`user_data` : | user data set when the signal handler was connected.