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.

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