FCmdrService

FCmdrService — System service to manage settings profiles

Functions

Properties

GDBusConnection * connection Read / Write / Construct Only

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── FCmdrService

Implemented Interfaces

FCmdrService implements GInitable.

Description

The FCmdrService implements a service on the system message bus responsible for fetching and managing settings profiles from any number of remote sources. A single profile may contain settings for a variety of desktop configuration systems or applications.

The service is extensible by way of GLib's GIOExtensionPoint system. Relevant extension point names are FCMDR_SERVICE_BACKEND_EXTENSION_POINT_NAME and FCMDR_PROFILE_SOURCE_EXTENSION_POINT_NAME.

Functions

fcmdr_service_new ()

FCmdrService *
fcmdr_service_new (GDBusConnection *connection,
                   GError **error);

Creates a new FCmdrService and attempts to export its interfaces on connection at FCMDR_SERVICE_DBUS_OBJECT_PATH. If the FCmdrService is unable to export its interfaces, the function sets error and returns NULL.

Parameters

connection

a GDBusConnection to the system-wide message bus

 

error

return location for a GError, or NULL

 

Returns

a new FCmdrService, or NULL


fcmdr_service_get_connection ()

GDBusConnection *
fcmdr_service_get_connection (FCmdrService *service);

Returns the GDBusConnection passed to fcmdr_service_new().

Parameters

service

a FCmdrService

 

Returns

a GDBusConnection


fcmdr_service_get_user_resolver ()

FCmdrUserResolver *
fcmdr_service_get_user_resolver (FCmdrService *service);

Returns the service 's FCmdrUserResolver.

Parameters

service

a FCmdrService

 

Returns

a FCmdrUserResolver


fcmdr_service_ref_backend ()

FCmdrServiceBackend *
fcmdr_service_ref_backend (FCmdrService *service,
                           const gchar *backend_name);

Looks up a FCmdrServiceBackend instance by its extension name.

The returned FCmdrServiceBackend is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

Parameters

service

a FCmdrService

 

backend_name

backend extension name

 

Returns

a referenced FCmdrServiceBackend, or NULL if no match was found


fcmdr_service_list_backends ()

GList *
fcmdr_service_list_backends (FCmdrService *service);

Returns an unsorted list of available FCmdrServiceBackend instances.

The backends returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned list itself with g_list_free().

An easy way to free the list properly in one step is as follows:

Parameters

service

a FCmdrService

 

Returns

a list of referenced backends


fcmdr_service_add_profile ()

void
fcmdr_service_add_profile (FCmdrService *service,
                           FCmdrProfile *profile);

Adds profile to service , replacing any existing FCmdrProfile with the same “uid” value.

Parameters

service

a FCmdrService

 

profile

a FCmdrProfile

 

fcmdr_service_ref_profile ()

FCmdrProfile *
fcmdr_service_ref_profile (FCmdrService *service,
                           const gchar *profile_uid);

Looks up a FCmdrProfile in service by its “uid” value.

The returned FCmdrProfile is referenced for thread-safety and must be unreferenced with g_object_unref() when finished with it.

Parameters

service

a FCmdrService

 

profile_uid

a unique identifier string

 

Returns

a referenced FCmdrProfile, or NULL if no match was found


fcmdr_service_list_profiles ()

GList *
fcmdr_service_list_profiles (FCmdrService *service);

Returns an unsorted list of available FCmdrProfile instances.

The profiles returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned list itself with g_list_free().

An easy way to free the list properly in one step is as follows:

Parameters

service

a FCmdrService

 

Returns

a list of referenced profiles


fcmdr_service_list_profiles_for_user ()

GList *
fcmdr_service_list_profiles_for_user (FCmdrService *service,
                                      uid_t uid);

Returns a list of FCmdrProfile instances which apply to the user identified by uid , sorted from highest priority to lowest priority.

The profiles returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned list itself with g_list_free().

An easy way to free the list properly in one step is as follows:

Parameters

service

a FCmdrService

 

uid

a user ID

 

Returns

a list of referenced profiles


fcmdr_service_ref_profile_source ()

FCmdrProfileSource *
fcmdr_service_ref_profile_source (FCmdrService *service,
                                  SoupURI *source_uri);

Looks up a FCmdrProfileSource in service by its “uri” value.

The returned FCmdrProfileSource is referenced for thready-safety and must be unreferenced with g_object_unref() when finished with it.

Parameters

service

a FCmdrService

 

source_uri

a SoupURI for a profile source

 

Returns

a referenced FCmdrProfileSource, or NULL if no match was found


fcmdr_service_list_profile_sources ()

GList *
fcmdr_service_list_profile_sources (FCmdrService *service);

Returns an unsorted list of available FCmdrProfileSource instances.

The sources returned in the list are referenced for thread-safety. They must each be unreferenced with g_object_unref() when finished with them. Free the returned list itself with g_list_free().

An easy way to free the list properly in one step is as follows:

Parameters

service

a FCmdrService

 

Returns

a list of referenced profiles


fcmdr_service_load_remote_profiles ()

void
fcmdr_service_load_remote_profiles (FCmdrService *service,
                                    GList *profile_sources,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Asynchronously loads remote profile data for the given profile_sources . Updated profiles are added to the service as each FCmdrProfileSource finishes loading. When all profile sources are finished loading, all profiles in service are cached and (if necessary) applied.

When the operation is finished, callback will be called. You can then call fcmdr_service_load_remote_profiles_finish() to get the result of the operation.

Parameters

service

a FCmdrService

 

profile_sources

a GList of FCmdrProfileSource instances

 

cancellable

optional GCancellable object, or NULL

 

callback

a GAsyncReadyCallback to call when the request is satisfied

 

user_data

data to pass to the callback function

 

fcmdr_service_load_remote_profiles_finish ()

GHashTable *
fcmdr_service_load_remote_profiles_finish
                               (FCmdrService *service,
                                GAsyncResult *result);

Finishes the operation started with fcmdr_service_load_remote_profiles().

Instead of propagating a single GError when multiple failures are possible, the function returns a hash table of profile sources (as keys) which failed to load remote profile data, along with a GError (as values) for each failure. An empty hash table indicates all profile sources completed successfully. Free the returned GHashTable with g_hash_table_destroy().

Parameters

service

a FCmdrService

 

result

a GAsyncResult

 

Returns

a GHashTable of loading errors


fcmdr_service_update_profiles ()

gboolean
fcmdr_service_update_profiles (FCmdrService *service,
                               FCmdrProfileSource *source,
                               GList *new_profiles);

Adds a set of freshly-loaded profiles from source to service and determines whether there are any actual profile changes which need to be applied.

The function assumes new_profiles to be a complete set of profiles for source . Existing profiles with a matching “source” value that do not appear in new_profiles are removed.

If any new profiles are added, or old profiles removed, or existing profiles updated with different “etag” values, the function returns TRUE to indicate fcmdr_service_apply_profiles() should be called.

This function is called as part of fcmdr_service_load_remote_profiles().

Parameters

service

a FCmdrService

 

source

a FCmdrProfileSource

 

new_profiles

a GList of FCmdrProfile instances

 

Returns

whether any profile changes need to be applied


fcmdr_service_apply_profiles ()

void
fcmdr_service_apply_profiles (FCmdrService *service);

Invokes fcmdr_service_backend_apply_profiles() on all backends in service for all profiles in service .

This function is called as part of fcmdr_service_load_remote_profiles().

Parameters

service

a FCmdrService

 

fcmdr_service_cache_profiles ()

gboolean
fcmdr_service_cache_profiles (FCmdrService *service,
                              GError **error);

Serializes all FCmdrProfile instances in service and writes the contents to disk. If the write operation fails, the function sets error and returns FALSE.

This function is called as part of fcmdr_service_load_remote_profiles().

Parameters

service

a FCmdrService

 

error

return location for a GError, or NULL

 

Returns

TRUE on success, FALSE on failure


fcmdr_service_add_bus_address ()

void
fcmdr_service_add_bus_address (FCmdrService *service,
                               uid_t uid,
                               const gchar *bus_address);

Associates a user-session message bus address with a user ID. The service opens a GDBusConnection to the message bus, but only for the purpose of listening for “closed” events.

To send messages to the message bus, a service backend must fork() itself and set the effective user ID of the child process to uid with setuid(). Then the child process can call g_dbus_connection_new_for_address() with bus_address and G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION.

Parameters

service

a FCmdrService

 

uid

the user ID associated with bus_address

 

bus_address

a D-Bus session bus address

 

fcmdr_service_dup_bus_address ()

gchar *
fcmdr_service_dup_bus_address (FCmdrService *service,
                               uid_t uid);

Returns the address of a user-session message bus associated with the given user ID, or NULL if there is currently no message bus for uid (the user-session may have closed).

Free the returned bus address with g_free().

Parameters

service

a FCmdrService

 

uid

a user ID associated with a session bus

 

Returns

a bus address for uid , or NULL if no match was found

Types and Values

FCMDR_SERVICE_DBUS_OBJECT_PATH

#define FCMDR_SERVICE_DBUS_OBJECT_PATH "/org/gnome/FleetCommander"

The D-Bus object path on which the FCmdrService is exported.


struct FCmdrService

struct FCmdrService;

Contains only private data that should be read and manipulated using the functions below.

Property Details

The “connection” property

  “connection”               GDBusConnection *

The system bus connection.

Flags: Read / Write / Construct Only

Signal Details

The “session-added” signal

void
user_function (FCmdrService *service,
               guint         uid,
               gchar        *bus_address,
               gpointer      user_data)

Emitted when a new bus address is added to the service .

Parameters

service

the FCmdrService which emitted the signal

 

uid

the user ID of the newly-added session

 

bus_address

the bus address of the newly-added session

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last