NMRemoteSettings: libnm-glib Reference Manual

- - -

NMRemoteSettings

NMRemoteSettings — A helper for NetworkManager's settings API

Functions

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-GQuark -	-nm_remote_settings_error_quark () -
-void -	-(*NMRemoteSettingsAddConnectionFunc) () -
-void -	-(*NMRemoteSettingsLoadConnectionsFunc) () -
-void -	-(*NMRemoteSettingsSaveHostnameFunc) () -
-NMRemoteSettings * -	-nm_remote_settings_new () -
-void -	-nm_remote_settings_new_async () -
-NMRemoteSettings * -	-nm_remote_settings_new_finish () -
-GSList * -	-nm_remote_settings_list_connections () -
-NMRemoteConnection * -	-nm_remote_settings_get_connection_by_id () -
-NMRemoteConnection * -	-nm_remote_settings_get_connection_by_path () -
-NMRemoteConnection * -	-nm_remote_settings_get_connection_by_uuid () -
-gboolean -	-nm_remote_settings_add_connection () -
-gboolean -	-nm_remote_settings_add_connection_unsaved () -
-gboolean -	-nm_remote_settings_load_connections () -
-gboolean -	-nm_remote_settings_reload_connections () -
-gboolean -	-nm_remote_settings_save_hostname () -

Properties

----- - - - - - - - - - - - - - - - - - - - - - - -

-DBusGConnection *	bus	Read / Write / Construct Only
gboolean	can-modify	Read
-gchar *	hostname	Read
gboolean	service-running	Read

Signals

----- - - - - - - - - - - - - -

void	connections-read	Run First
void	new-connection	Run First

Types and Values

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

enum	NMRemoteSettingsError
#define	NM_REMOTE_SETTINGS_ERROR
#define	NM_REMOTE_SETTINGS_BUS
#define	NM_REMOTE_SETTINGS_SERVICE_RUNNING
#define	NM_REMOTE_SETTINGS_HOSTNAME
#define	NM_REMOTE_SETTINGS_CAN_MODIFY
#define	NM_REMOTE_SETTINGS_NEW_CONNECTION
#define	NM_REMOTE_SETTINGS_CONNECTIONS_READ

Object Hierarchy

    GObject
-    ╰── NMRemoteSettings
-

Description

The NMRemoteSettings object represents NetworkManager's "settings" service, -which stores network configuration and allows authenticated clients to -add, delete, and modify that configuration. The data required to connect -to a specific network is called a "connection" and encapsulated by the -NMConnection object. Once a connection is known to NetworkManager, having -either been added by a user or read from on-disk storage, the -NMRemoteSettings object creates a NMRemoteConnection object which -represents this stored connection. Use the NMRemoteConnection object to -perform any operations like modification or deletion.

To add a new network connection to the NetworkManager settings service, first -build up a template NMConnection object. Since this connection is not yet -added to NetworkManager, it is known only to your program and is not yet -an NMRemoteConnection. Then ask NMRemoteSettings to add your connection. -When the connection is added successfully, the supplied callback is called -and returns to your program the new NMRemoteConnection which represents -the stored object known to NetworkManager.

- - - - - - - -

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
-26
-27
-28
-29
-30
-31
-32
-33
-34
-35
-36
-37
-38
-39
-40
-41
-42
-43
-44
-45
-46
-47
-48
-49
-50
-51
-52
-53
-54
-55
-56
-57
-58
-59

static void
-added_cb (NMRemoteSettings *settings,
-          NMRemoteConnection *remote,
-          GError *error,
-          gpointer user_data)
-{
-   if (error)
-       g_print ("Error adding connection: %s", error->message);
-   else {
-       g_print ("Added: %s\n", nm_connection_get_path (NM_CONNECTION (remote)));
-       /* Use 'remote' with nm_remote_connection_commit_changes() to save
-        * changes and nm_remote_connection_delete() to delete the connection */
-   }
-}
-
-static gboolean
-add_wired_connection (const char *human_name)
-{
-   NMConnection *connection;
-   NMSettingConnection *s_con;
-   NMSettingWired *s_wired;
-   char *uuid;
-   gboolean success;
-
-   connection = nm_connection_new ();
-
-   /* Build up the 'connection' setting */
-   s_con = (NMSettingConnection *) nm_setting_connection_new ();
-   uuid = nm_utils_uuid_generate ();
-   g_object_set (G_OBJECT (s_con),
-                 NM_SETTING_CONNECTION_UUID, uuid,
-                 NM_SETTING_CONNECTION_ID, human_name,
-                 NM_SETTING_CONNECTION_TYPE, NM_SETTING_WIRED_SETTING_NAME,
-                 NULL);
-   g_free (uuid);
-   nm_connection_add_setting (connection, NM_SETTING (s_con));
-
-   /* Add the required 'wired' setting as this is a wired connection */
-   nm_connection_add_setting (connection, nm_setting_wired_new ());
-
-   /* Add an 'ipv4' setting using AUTO configuration (eg DHCP) */
-   s_ip4 = (NMSettingIP4Config *) nm_setting_ip4_config_new ();
-   g_object_set (G_OBJECT (s_ip4),
-                 NM_SETTING_IP4_CONFIG_METHOD, NM_SETTING_IP4_CONFIG_METHOD_AUTO,
-                 NULL);
-   nm_connection_add_setting (connection, NM_SETTING (s_ip4));
-
-   /* Ask NetworkManager to store the connection */
-   success = nm_remote_settings_add_connection (settings, connection, added_cb, loop);
-
-   /* Release the template connection; the actual stored connection will
-    * be returned in added_cb() */
-   g_object_unref (connection);
-
-   /* Let glib event loop run and added_cb() will be called when NetworkManager
-    * is done adding the new connection. */
-
-   return success;
-}

- -

Functions

nm_remote_settings_error_quark ()

GQuark
-nm_remote_settings_error_quark (void);

Registers an error quark for NMRemoteSettings if necessary.

Returns

the error quark used for NMRemoteSettings errors.

NMRemoteSettingsAddConnectionFunc ()

void
-(*NMRemoteSettingsAddConnectionFunc) (NMRemoteSettings *settings,
-                                      NMRemoteConnection *connection,
-                                      GError *error,
-                                      gpointer user_data);

NMRemoteSettingsLoadConnectionsFunc ()

void
-(*NMRemoteSettingsLoadConnectionsFunc)
-                               (NMRemoteSettings *settings,
-                                char **failures,
-                                GError *error,
-                                gpointer user_data);

NMRemoteSettingsSaveHostnameFunc ()

void
-(*NMRemoteSettingsSaveHostnameFunc) (NMRemoteSettings *settings,
-                                     GError *error,
-                                     gpointer user_data);

nm_remote_settings_new ()

NMRemoteSettings *
-nm_remote_settings_new (DBusGConnection *bus);

Creates a new object representing the remote settings service.

Note that this will do blocking D-Bus calls to initialize the -settings object. You can use nm_remote_settings_new_async() if you -want to avoid that.

Parameters

----- - - - - - -

bus

a valid and connected D-Bus connection.

[allow-none]

Returns

the new remote settings object on success, or NULL on failure

nm_remote_settings_new_async ()

void
-nm_remote_settings_new_async (DBusGConnection *bus,
-                              GCancellable *cancellable,
-                              GAsyncReadyCallback callback,
-                              gpointer user_data);

Creates a new object representing the remote settings service and -begins asynchronously initializing it. callback - will be called -when it is done; use nm_remote_settings_new_finish() to get the -result.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

bus	a valid and connected D-Bus connection.	[allow-none]
cancellable	a GCancellable, or `NULL`
callback	callback to call when the settings object is created
user_data	data for `callback` -

nm_remote_settings_new_finish ()

NMRemoteSettings *
-nm_remote_settings_new_finish (GAsyncResult *result,
-                               GError **error);

Gets the result of an nm_remote_settings_new_async() call.

Parameters

----- - - - - - - - - - - - - -

result	a GAsyncResult
error	location for a GError, or `NULL`

Returns

a new NMRemoteSettings object, or NULL on error

nm_remote_settings_list_connections ()

GSList *
-nm_remote_settings_list_connections (NMRemoteSettings *settings);

Parameters

----- - - - - - -

settings

the NMRemoteSettings

Returns

a -list containing all connections provided by the remote settings service. -Each element of the returned list is a NMRemoteConnection instance, which is -owned by the NMRemoteSettings object and should not be freed by the caller. -The returned list is, however, owned by the caller and should be freed -using g_slist_free() when no longer required.

[transfer container][element-type NMRemoteConnection]

nm_remote_settings_get_connection_by_id ()

NMRemoteConnection *
-nm_remote_settings_get_connection_by_id
-                               (NMRemoteSettings *settings,
-                                const char *id);

Returns the first matching NMRemoteConnection matching a given id -.

Parameters

----- - - - - - - - - - - - - -

settings	the `NMRemoteSettings`
id	the id of the remote connection

Returns

the remote connection object on success, or NULL if no -matching object was found.

[transfer none]

Since: 0.9.10

nm_remote_settings_get_connection_by_path ()

NMRemoteConnection *
-nm_remote_settings_get_connection_by_path
-                               (NMRemoteSettings *settings,
-                                const char *path);

Returns the NMRemoteConnection representing the connection at path -.

Parameters

----- - - - - - - - - - - - - -

settings	the `NMRemoteSettings`
path	the D-Bus object path of the remote connection

Returns

the remote connection object on success, or NULL if the object was -not known.

[transfer none]

nm_remote_settings_get_connection_by_uuid ()

NMRemoteConnection *
-nm_remote_settings_get_connection_by_uuid
-                               (NMRemoteSettings *settings,
-                                const char *uuid);

Returns the NMRemoteConnection identified by uuid -.

Parameters

----- - - - - - - - - - - - - -

settings	the `NMRemoteSettings`
uuid	the UUID of the remote connection

Returns

the remote connection object on success, or NULL if the object was -not known.

[transfer none]

nm_remote_settings_add_connection ()

gboolean
-nm_remote_settings_add_connection (NMRemoteSettings *settings,
-                                   NMConnection *connection,
-                                   NMRemoteSettingsAddConnectionFunc callback,
-                                   gpointer user_data);

Requests that the remote settings service add the given settings to a new -connection. The connection is immediately written to disk. connection - is -untouched by this function and only serves as a template of the settings to -add. The NMRemoteConnection object that represents what NetworkManager -actually added is returned to callback - when the addition operation is complete.

Note that the NMRemoteConnection returned in callback - may not contain -identical settings to connection - as NetworkManager may perform automatic -completion and/or normalization of connection properties.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

settings	the `NMRemoteSettings`
connection	the connection to add. Note that this object's settings will be -added, not the object itself
callback	callback to be called when the add operation completes.	[scope async]
user_data	caller-specific data passed to `callback` -.	[closure]

Returns

TRUE if the request was successful, FALSE if it failed

nm_remote_settings_add_connection_unsaved ()

gboolean
-nm_remote_settings_add_connection_unsaved
-                               (NMRemoteSettings *settings,
-                                NMConnection *connection,
-                                NMRemoteSettingsAddConnectionFunc callback,
-                                gpointer user_data);

Requests that the remote settings service add the given settings to a new -connection. The connection is not written to disk, which may be done at -a later time by calling the connection's nm_remote_connection_commit_changes() -method.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

settings	the `NMRemoteSettings`
connection	the connection to add. Note that this object's settings will be -added, not the object itself
callback	callback to be called when the add operation completes.	[scope async]
user_data	caller-specific data passed to `callback` -.	[closure]

Returns

TRUE if the request was successful, FALSE if it failed

Since: 0.9.10

nm_remote_settings_load_connections ()

gboolean
-nm_remote_settings_load_connections (NMRemoteSettings *settings,
-                                     char **filenames,
-                                     char ***failures,
-                                     GError **error);

Requests that the remote settings service load or reload the given files, -adding or updating the connections described within.

The changes to the indicated files will not yet be reflected in -settings -'s connections array when the function returns.

If all of the indicated files were successfully loaded, the -function will return TRUE, and failures - will be set to NULL. If -NetworkManager tried to load the files, but some (or all) failed, -then failures - will be set to a NULL-terminated array of the -filenames that failed to load.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

settings	the `NMRemoteSettings`
filenames	`NULL`-terminated array of filenames to load
failures	on return, a `NULL`-terminated array of -filenames that failed to load.	[out][transfer full]
error	return location for GError

Returns

TRUE if NetworkManager at least tried to load filenames -, -FALSE if an error occurred (eg, permission denied).

Since: 0.9.10

nm_remote_settings_reload_connections ()

gboolean
-nm_remote_settings_reload_connections (NMRemoteSettings *settings,
-                                       GError **error);

Requests that the remote settings service reload all connection -files from disk, adding, updating, and removing connections until -the in-memory state matches the on-disk state.

Parameters

----- - - - - - - - - - - - - -

settings	the NMRemoteSettings
error	return location for GError

Returns

TRUE on success, FALSE on failure

Since: 0.9.10

nm_remote_settings_save_hostname ()

gboolean
-nm_remote_settings_save_hostname (NMRemoteSettings *settings,
-                                  const char *hostname,
-                                  NMRemoteSettingsSaveHostnameFunc callback,
-                                  gpointer user_data);

Requests that the machine's persistent hostname be set to the specified value -or cleared.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - -

settings	the `NMRemoteSettings`
hostname	the new persistent hostname to set, or `NULL` to clear any existing -persistent hostname
callback	callback to be called when the -hostname operation completes.	[scope async][allow-none]
user_data	caller-specific data passed to `callback` -.	[closure]

Returns

TRUE if the request was successful, FALSE if it failed

Types and Values

enum NMRemoteSettingsError

Describes errors that may result from operations involving a NMRemoteSettings.

Members

----- - - - - - - - - - - - - - - - - - - - - - - -

NM_REMOTE_SETTINGS_ERROR_UNKNOWN	- unknown or unclassified error -
NM_REMOTE_SETTINGS_ERROR_CONNECTION_REMOVED	- the NMRemoteConnection object - was removed before it was completely initialized -
NM_REMOTE_SETTINGS_ERROR_CONNECTION_UNAVAILABLE	- the NMRemoteConnection object - is not visible or otherwise unreadable -
NM_REMOTE_SETTINGS_ERROR_SERVICE_UNAVAILABLE	- NetworkManager is not running. - (Since 0.9.10) -

NM_REMOTE_SETTINGS_ERROR

#define NM_REMOTE_SETTINGS_ERROR nm_remote_settings_error_quark ()
-

NM_REMOTE_SETTINGS_BUS

#define NM_REMOTE_SETTINGS_BUS             "bus"
-

NM_REMOTE_SETTINGS_SERVICE_RUNNING

#define NM_REMOTE_SETTINGS_SERVICE_RUNNING "service-running"
-

NM_REMOTE_SETTINGS_HOSTNAME

#define NM_REMOTE_SETTINGS_HOSTNAME        "hostname"
-

NM_REMOTE_SETTINGS_CAN_MODIFY

#define NM_REMOTE_SETTINGS_CAN_MODIFY      "can-modify"
-

NM_REMOTE_SETTINGS_NEW_CONNECTION

#define NM_REMOTE_SETTINGS_NEW_CONNECTION    "new-connection"
-

NM_REMOTE_SETTINGS_CONNECTIONS_READ

#define NM_REMOTE_SETTINGS_CONNECTIONS_READ  "connections-read"
-

Property Details

The `“bus”` property

  “bus”                      DBusGConnection *

The DBusGConnection that the NMRemoteSettings is connected to. Defaults -to the system bus if not specified.

Flags: Read / Write / Construct Only

The `“can-modify”` property

  “can-modify”               gboolean

If TRUE, adding and modifying connections is supported.

Flags: Read

Default value: FALSE

The `“hostname”` property

  “hostname”                 gchar *

The machine hostname stored in persistent configuration. This can be -modified by calling nm_remote_settings_save_hostname().

Flags: Read

Default value: NULL

The `“service-running”` property

  “service-running”          gboolean

Whether the settings service is running.

Flags: Read

Default value: FALSE

Signal Details

The `“connections-read”` signal

void
-user_function (NMRemoteSettings *nmremotesettings,
-               gpointer          user_data)

Flags: Run First

The `“new-connection”` signal

void
-user_function (NMRemoteSettings *nmremotesettings,
-               GObject          *arg1,
-               gpointer          user_data)

Flags: Run First