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.