FCmdrProfile

FCmdrProfile — A settings profile

Functions

Properties

FCmdrProfileApplies * applies-to Read / Write / Construct Only
gchar * description Read / Write / Construct Only
gchar * etag Read / Write / Construct Only
gchar * name Read / Write / Construct Only
JsonObject * settings Read / Write / Construct Only
FCmdrProfileSource * source Read / Write
gchar * uid Read / Write / Construct Only

Types and Values

Object Hierarchy

    GObject
    ╰── FCmdrProfile

Implemented Interfaces

FCmdrProfile implements GInitable and JsonSerializable.

Description

A FCmdrProfile instance holds settings to be locked for some combination of users, groups, and hosts. Profiles are typically loaded from a remote source as described by a FCmdrProfileSource.

A FCmdrProfile consists of a unique identifier or “uid” field, an entity tag or “etag” field for fast comparisons, human-readable “name” and “description” fields, and an assortment of “settings” grouped by context.

Each “settings” context in a profile is handled by a custom FCmdrServiceBackend. For example the "org.gnome.gsettings" context is handled by a custom FCmdrServiceBackend that knows how to parse and apply those settings by interacting with

dconf.

Functions

fcmdr_profile_new ()

FCmdrProfile *
fcmdr_profile_new (const gchar *data,
                   gssize length,
                   GError **error);

Deserializes the JSON data into a new FCmdrProfile instance and checks the contents for validity. If an error occurs during deserialization or validation, the function sets error and returns NULL.

A validated profile is guaranteed to have non-empty “uid”, “etag”, and “settings” values.

Parameters

data

JSON data describing a profile

 

length

length of data , or -1 if it is NUL-terminated

 

error

return location for a GError, or NULL

 

Returns

a new FCmdrProfile, or NULL


fcmdr_profile_new_from_node ()

FCmdrProfile *
fcmdr_profile_new_from_node (JsonNode *node,
                             GError **error);

Deserializes node into a new FCmdrProfile instance and checks the contents for validity. If an error occurs during deserialization or validation, the function sets error and returns NULL.

A validated profile is guaranteed to have non-empty “uid”, “etag”, and “settings” values.

Parameters

node

a JsonNode of type JSON_NODE_OBJECT describing a profile

 

error

return location for a GError, or NULL

 

Returns

a new FCmdrProfile, or NULL


fcmdr_profile_new_from_stream ()

FCmdrProfile *
fcmdr_profile_new_from_stream (GInputStream *stream,
                               GCancellable *cancellable,
                               GError **error);

Deserializes the stream contents into a new FCmdrProfile instance and checks the contents for validity. If an error occurs during deserialization or validation, the function sets error and returns NULL.

A validated profile is guaranteed to have non-empty “uid”, “etag”, and “settings” values.

Parameters

stream

an open GInputStream

 

cancellable

optional GCancellable object, or NULL

 

error

return location for a GError, or NULL

 

Returns

a new FCmdrProfile, or NULL


fcmdr_profile_hash ()

guint
fcmdr_profile_hash (FCmdrProfile *profile);

Generates a hash value for profile . This function is intended for easily hashing a FCmdrProfile to add to a GHashTable or similar data structure.

Parameters

profile

a FCmdrProfile

 

Returns

a hash value for profile


fcmdr_profile_equal ()

gboolean
fcmdr_profile_equal (FCmdrProfile *profile1,
                     FCmdrProfile *profile2);

Checks two FCmdrProfile instances for equality. Two FCmdrProfile instances are equal if their “uid” values are equal.

Parameters

profile1

the first FCmdrProfile

 

profile2

the second FCmdrProfile

 

Returns

TRUE if profile1 and profile2 are equal


fcmdr_profile_get_uid ()

const gchar *
fcmdr_profile_get_uid (FCmdrProfile *profile);

Returns the profile 's unique identifier.

Parameters

profile

a FCmdrProfile

 

Returns

the profile 's “uid”


fcmdr_profile_get_etag ()

const gchar *
fcmdr_profile_get_etag (FCmdrProfile *profile);

Returns the profile 's entity tag.

Parameters

profile

a FCmdrProfile

 

Returns

the profile 's “etag”


fcmdr_profile_get_name ()

const gchar *
fcmdr_profile_get_name (FCmdrProfile *profile);

Returns the profile 's display name.

Parameters

profile

a FCmdrProfile

 

Returns

the profile 's “name”


fcmdr_profile_get_description ()

const gchar *
fcmdr_profile_get_description (FCmdrProfile *profile);

Returns a brief description of the profile .

Parameters

profile

a FCmdrProfile

 

Returns

the profile's “description”


fcmdr_profile_get_applies_to ()

FCmdrProfileApplies *
fcmdr_profile_get_applies_to (FCmdrProfile *profile);

Returns the FCmdrProfileApplies describing which users, groups and/or hosts profile applies to. A NULL return value indicates the profile applies unconditionally.

The returned FCmdrProfileApplies is owned by profile and should not be modified or freed.

Parameters

profile

a FCmdrProfile

 

Returns

a FCmdrProfileApplies, or NULL


fcmdr_profile_ref_settings ()

JsonObject *
fcmdr_profile_ref_settings (FCmdrProfile *profile);

Returns the raw settings data as a JSON object, grouped by context with member names denoting the context.

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

Parameters

profile

a FCmdrProfile

 

Returns

a referenced JsonObject


fcmdr_profile_ref_source ()

FCmdrProfileSource *
fcmdr_profile_ref_source (FCmdrProfile *profile);

Returns the FCmdrProfileSource from which the profile originated, or NULL if the profile was added interactively or by some other means.

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

Parameters

profile

a FCmdrProfile

 

Returns

a referenced FCmdrProfileSource, or NULL


fcmdr_profile_set_source ()

void
fcmdr_profile_set_source (FCmdrProfile *profile,
                          FCmdrProfileSource *source);

Sets the FCmdrProfileSource from which the profile originated. Typically this is called once, immediately after a FCmdrProfile is instantiated.

Parameters

profile

a FCmdrProfile

 

source

a FCmdrProfileSource, or NULL

 

fcmdr_profile_applies_to_user ()

gboolean
fcmdr_profile_applies_to_user (FCmdrProfile *profile,
                               uid_t uid,
                               guint *out_score);

Returns whether profile applies to the user identified by uid by examining the “applies-to” data.

If profile applies, the function returns TRUE and assigns a positive score to out_score . The score is meant to help rank a set of applicable profiles. Profiles with higher scores should be given higher priority.

If profile does NOT apply, the function returns FALSE and assigns zero to out_score .

Note the score value is based on heuristics which are subject to change.

Parameters

profile

a FCmdrProfile

 

uid

a user ID

 

out_score

return location for a match score, or NULL

 

Returns

whether profile applies to uid


fcmdr_profile_applies_new ()

FCmdrProfileApplies *
fcmdr_profile_applies_new (void);

Allocates and zero-fills a new FCmdrProfileApplies structure. Free the allocated structure with fcmdr_profile_applies_free().

Returns

an allocated FCmdrProfileApplies


fcmdr_profile_applies_copy ()

FCmdrProfileApplies *
fcmdr_profile_applies_copy (FCmdrProfileApplies *applies);

Allocates a complete copy of applies . Free the allocated copy with fcmdr_profile_applies_free().

Parameters

applies

a FCmdrProfileApplies

 

Returns

an allocated FCmdrProfileApplies


fcmdr_profile_applies_free ()

void
fcmdr_profile_applies_free (FCmdrProfileApplies *applies);

Frees applies as well as any NULL-terminated string arrays contained within, or does nothing if applies is NULL.

Parameters

applies

a FCmdrProfileApplies

 

Types and Values

struct FCmdrProfile

struct FCmdrProfile;

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


struct FCmdrProfileApplies

struct FCmdrProfileApplies {
	gchar **users;
	gchar **groups;
	gchar **hosts;
};

A FCmdrProfileApplies describes the applicability of a FCmdrProfile to a given user or host machine. If a user's name is included in users , or the user is a member of any groups included in groups , or if the local machine's host name is included in hosts , then the FCmdrProfile applies.

Members

gchar **users;

a NULL-terminated array of user names

 

gchar **groups;

a NULL-terminated array of group names

 

gchar **hosts;

a NULL-terminated array of host names

 

Property Details

The “applies-to” property

  “applies-to”               FCmdrProfileApplies *

Set of users, groups and hosts to which the profile applies.

Flags: Read / Write / Construct Only


The “description” property

  “description”              gchar *

A brief description of the profile.

Flags: Read / Write / Construct Only

Default value: NULL


The “etag” property

  “etag”                     gchar *

The profile's entity tag.

Flags: Read / Write / Construct Only

Default value: NULL


The “name” property

  “name”                     gchar *

The profile's display name.

Flags: Read / Write / Construct Only

Default value: NULL


The “settings” property

  “settings”                 JsonObject *

Raw settings data in JSON format.

Flags: Read / Write / Construct Only


The “source” property

  “source”                   FCmdrProfileSource *

The source of this profile.

Flags: Read / Write


The “uid” property

  “uid”                      gchar *

The profile's unique ID.

Flags: Read / Write / Construct Only

Default value: NULL