GeoclueMasterClient

GeoclueMasterClient — Geoclue MasterClient API

Functions

Properties

gchar * object-path Write / Construct Only

Signals

void address-provider-changed No Recursion
void invalidated No Recursion
void position-provider-changed No Recursion

Types and Values

Object Hierarchy

    GObject
    ╰── GeoclueMasterClient

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 * /

Functions

CreateAddressCallback ()

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

Callback function for geoclue_master_client_create_address_async().

Parameters

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

Parameters

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

 

GeoclueGetProviderCallback ()

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


GeoclueSetRequirementsCallback ()

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

Callback function for geoclue_master_client_set_requirements_async().

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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

 

Types and Values

GEOCLUE_MASTER_CLIENT_DBUS_INTERFACE

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


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;

Property Details

The “object-path” property

  “object-path”              gchar *

The DBus path to the object.

Flags: Write / Construct Only

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)

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

Parameters

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.

 

Flags: No Recursion


The “invalidated” signal

void
user_function (GeoclueMasterClient *client,
               gpointer             user_data)

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.

Parameters

client

the GeoclueMasterClient object emitting the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: No Recursion


The “position-provider-changed” signal

void
user_function (GeoclueMasterClient *client,
               gchar               *name,
               gchar               *description,
               gchar               *service,
               gchar               *path,
               gpointer             user_data)

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

Parameters

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.

 

Flags: No Recursion