## NMRemoteSettings NMRemoteSettings — A helper for NetworkManager's settings API |

## Synopsis

    enum                NMRemoteSettingsError;
    #define             NM_REMOTE_SETTINGS_ERROR
    GQuark              nm_remote_settings_error_quark      (void);
    #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
    void                (*NMRemoteSettingsAddConnectionFunc)
                                                            (NMRemoteSettings *settings,
                                                             NMRemoteConnection *connection,
                                                             GError *error,
                                                             gpointer user_data);
    void                (*NMRemoteSettingsLoadConnectionsFunc)
                                                            (NMRemoteSettings *settings,
                                                             char **failures,
                                                             GError *error,
                                                             gpointer user_data);
    void                (*NMRemoteSettingsSaveHostnameFunc) (NMRemoteSettings *settings,
                                                             GError *error,
                                                             gpointer user_data);
    struct              NMRemoteSettings;
    struct              NMRemoteSettingsClass;
    NMRemoteSettings *  nm_remote_settings_new              (DBusGConnection *bus);
    void                nm_remote_settings_new_async        (DBusGConnection *bus,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    NMRemoteSettings *  nm_remote_settings_new_finish       (GAsyncResult *result,
                                                             GError **error);
    GSList *            nm_remote_settings_list_connections (NMRemoteSettings *settings);
    NMRemoteConnection * nm_remote_settings_get_connection_by_id
                                                            (NMRemoteSettings *settings,
                                                             const char *id);
    NMRemoteConnection * nm_remote_settings_get_connection_by_path
                                                            (NMRemoteSettings *settings,
                                                             const char *path);
    NMRemoteConnection * nm_remote_settings_get_connection_by_uuid
                                                            (NMRemoteSettings *settings,
                                                             const char *uuid);
    gboolean            nm_remote_settings_add_connection   (NMRemoteSettings *settings,
                                                             NMConnection *connection,
                                                             NMRemoteSettingsAddConnectionFunc callback,
                                                             gpointer user_data);
    gboolean            nm_remote_settings_add_connection_unsaved
                                                            (NMRemoteSettings *settings,
                                                             NMConnection *connection,
                                                             NMRemoteSettingsAddConnectionFunc callback,
                                                             gpointer user_data);
    gboolean            nm_remote_settings_load_connections (NMRemoteSettings *settings,
                                                             char **filenames,
                                                             char ***failures,
                                                             GError **error);
    gboolean            nm_remote_settings_reload_connections
                                                            (NMRemoteSettings *settings,
                                                             GError **error);
    gboolean            nm_remote_settings_save_hostname    (NMRemoteSettings *settings,
                                                             const char *hostname,
                                                             NMRemoteSettingsSaveHostnameFunc callback,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----NMRemoteSettings

## Implemented Interfaces

NMRemoteSettings implements GInitable and GAsyncInitable.

## Properties

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

## Signals

      "connections-read"                               : Run First
      "new-connection"                                 : Run First

## 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;
    }

## Details

### enum NMRemoteSettingsError

    typedef enum {
    	NM_REMOTE_SETTINGS_ERROR_UNKNOWN = 0,            /*< nick=UnknownError >*/
    	NM_REMOTE_SETTINGS_ERROR_CONNECTION_REMOVED,     /*< nick=ConnectionRemoved >*/
    	NM_REMOTE_SETTINGS_ERROR_CONNECTION_UNAVAILABLE, /*< nick=ConnectionUnavailable >*/
    	NM_REMOTE_SETTINGS_ERROR_SERVICE_UNAVAILABLE,    /*< nick=ServiceUnavailable >*/
    } NMRemoteSettingsError;

Describes errors that may result from operations involving a NMRemoteSettings.

`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_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.

### 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"

### 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);

### struct NMRemoteSettings

    struct NMRemoteSettings;

### struct NMRemoteSettingsClass

    struct NMRemoteSettingsClass {
    	GObjectClass parent;

    	/* Signals */
    	void (*new_connection) (NMRemoteSettings *settings,
    	                        NMRemoteConnection *connection);

    	void (*connections_read) (NMRemoteSettings *settings);

    	/* Padding for future expansion */
    	void (*_reserved1) (void);
    	void (*_reserved2) (void);
    	void (*_reserved3) (void);
    	void (*_reserved4) (void);
    	void (*_reserved5) (void);
    	void (*_reserved6) (void);
    };

### 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.

`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.

`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.

`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);

`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 NMClient.RemoteConnection]

### 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`.

`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`.

`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`.

`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.

`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.

`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.

`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.

`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.

`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

## Property Details

### The `"bus"` property

      "bus"                      DBusGConnection*      : Read / Write / Construct Only

DBusGConnection.

### The `"can-modify"` property

      "can-modify"               gboolean              : Read

Can modify anything (hostname, connections, etc).

Default value: FALSE

### The `"hostname"` property

      "hostname"                 gchar*                : Read

Persistent hostname.

Default value: NULL

### The `"service-running"` property

      "service-running"          gboolean              : Read

Is service running.

Default value: FALSE

## Signal Details

### The `"connections-read"` signal

    void                user_function                      (NMRemoteSettings *nmremotesettings,
                                                            gpointer          user_data)             : Run First

`nmremotesettings` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"new-connection"` signal

    void                user_function                      (NMRemoteSettings *nmremotesettings,
                                                            GObject          *arg1,
                                                            gpointer          user_data)             : Run First

`nmremotesettings` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

## See Also

NMRemoteConnection, NMClient