GeoclueMasterClient

GeoclueMasterClient — Geoclue MasterClient API

Synopsis

void                (*CreateAddressCallback)            (GeoclueMasterClient *client,
                                                         GeoclueAddress *address,
                                                         GError *error,
                                                         gpointer userdata);
void                (*CreatePositionCallback)           (GeoclueMasterClient *client,
                                                         GeocluePosition *position,
                                                         GError *error,
                                                         gpointer userdata);
#define             GEOCLUE_MASTER_CLIENT_DBUS_INTERFACE
void                (*GeoclueGetProviderCallback)       (GeoclueMasterClient *client,
                                                         char *name,
                                                         char *description,
                                                         char *service,
                                                         char *path,
                                                         GError *error,
                                                         gpointer userdata);
                    GeoclueMasterClient;
                    GeoclueMasterClientClass;
void                (*GeoclueSetRequirementsCallback)   (GeoclueMasterClient *client,
                                                         GError *error,
                                                         gpointer userdata);
GeoclueAddress *    geoclue_master_client_create_address
                                                        (GeoclueMasterClient *client,
                                                         GError **error);
void                geoclue_master_client_create_address_async
                                                        (GeoclueMasterClient *client,
                                                         CreateAddressCallback callback,
                                                         gpointer userdata);
GeocluePosition *   geoclue_master_client_create_position
                                                        (GeoclueMasterClient *client,
                                                         GError **error);
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                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);
gboolean            geoclue_master_client_set_requirements
                                                        (GeoclueMasterClient *client,
                                                         GeoclueAccuracyLevel min_accuracy,
                                                         int min_time,
                                                         gboolean require_updates,
                                                         GeoclueResourceFlags allowed_resources,
                                                         GError **error);
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);

Object Hierarchy

  GObject
   +----GeoclueMasterClient

Properties

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

Signals

  "address-provider-changed"                       : No Recursion
  "invalidated"                                    : No Recursion
  "position-provider-changed"                      : 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

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()

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_DBUS_INTERFACE

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

GeoclueGetProviderCallback ()

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

GeoclueMasterClient

typedef struct _GeoclueMasterClient GeoclueMasterClient;

GeoclueMasterClientClass

typedef struct {
	GObjectClass parent_class;
	void (* address_provider_changed) (GeoclueMasterClient  *client,
	                                   char                 *name,
	                                   char                 *description,
	                                   char                 *service,
	                                   char                 *path);
	void (* position_provider_changed) (GeoclueMasterClient  *client,
	                                    char                 *name,
	                                    char                 *description,
	                                    char                 *service,
	                                    char                 *path);
	void (* invalidated) (GeoclueMasterClient *client);
} GeoclueMasterClientClass;

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

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

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

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 in seconds

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

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)        : 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)      : 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)        : 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.
Generated by GTK-Doc V1.18.1