NMRemoteConnection: libnm Reference Manual

## NMRemoteConnection NMRemoteConnection — A connection managed by NetworkManager server |

## Functions

void | nm_remote_connection_update2 ()
GVariant * | nm_remote_connection_update2_finish ()
gboolean | nm_remote_connection_commit_changes ()
void | nm_remote_connection_commit_changes_async ()
gboolean | nm_remote_connection_commit_changes_finish ()
gboolean | nm_remote_connection_save ()
void | nm_remote_connection_save_async ()
gboolean | nm_remote_connection_save_finish ()
gboolean | nm_remote_connection_delete ()
void | nm_remote_connection_delete_async ()
gboolean | nm_remote_connection_delete_finish ()
GVariant * | nm_remote_connection_get_secrets ()
void | nm_remote_connection_get_secrets_async ()
GVariant * | nm_remote_connection_get_secrets_finish ()
gboolean | nm_remote_connection_get_unsaved ()
NMSettingsConnectionFlags | nm_remote_connection_get_flags ()
const char * | nm_remote_connection_get_filename ()
gboolean | nm_remote_connection_get_visible ()
guint64 | nm_remote_connection_get_version_id ()

## Properties

char * | filename | Read
guint | flags | Read
gboolean | unsaved | Read
guint64 | version-id | Read
gboolean | visible | Read

## Types and Values

#define | NM_REMOTE_CONNECTION_DBUS_CONNECTION
#define | NM_REMOTE_CONNECTION_PATH
#define | NM_REMOTE_CONNECTION_UNSAVED
#define | NM_REMOTE_CONNECTION_FLAGS
#define | NM_REMOTE_CONNECTION_FILENAME
#define | NM_REMOTE_CONNECTION_VERSION_ID
#define | NM_REMOTE_CONNECTION_VISIBLE
| NMRemoteConnection

## Object Hierarchy

        GObject
        ╰── NMObject
            ╰── NMRemoteConnection

## Implemented Interfaces

NMRemoteConnection implements NMConnection.

## Description

A NMRemoteConnection represents a connection that is exported via NetworkManager D-Bus interface.

## Functions

### nm_remote_connection_update2 ()

    void
    nm_remote_connection_update2 (NMRemoteConnection *connection,
                                  GVariant *settings,
                                  NMSettingsUpdate2Flags flags,
                                  GVariant *args,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Asynchronously calls the `Update2()` D-Bus method.

#### Parameters

connection | the NMRemoteConnection |
settings | optional connection to update the settings. | [nullable]
flags | update-flags |
args | optional arguments. | [nullable]
cancellable | a GCancellable, or `NULL` |
callback | callback to be called when the commit operation completes |
user_data | caller-specific data passed to `callback` |

Since: 1.12

### nm_remote_connection_update2_finish ()

    GVariant *
    nm_remote_connection_update2_finish (NMRemoteConnection *connection,
                                         GAsyncResult *result,
                                         GError **error);

Gets the result of a call to `nm_remote_connection_commit_changes_async()`.

#### Parameters

connection | the NMRemoteConnection |
result | the result passed to the GAsyncReadyCallback |
error | location for a GError, or `NULL` |

#### Returns

on success, a GVariant of type "a{sv}" with the result. On failure, `NULL`.

[transfer full]

Since: 1.12

### nm_remote_connection_commit_changes ()

    gboolean
    nm_remote_connection_commit_changes (NMRemoteConnection *connection,
                                         gboolean save_to_disk,
                                         GCancellable *cancellable,
                                         GError **error);

`nm_remote_connection_commit_changes` has been deprecated since version 1.22 and should not be used in newly-written code.

Use `nm_remote_connection_commit_changes_async()` or GDBusConnection.

Send any local changes to the settings and properties of `connection` to NetworkManager. If `save_to_disk` is `TRUE`, the updated connection will be saved to disk; if `FALSE`, then only the in-memory representation will be changed.

#### Parameters

connection | the NMRemoteConnection |
save_to_disk | whether to persist the changes to disk |
cancellable | a GCancellable, or `NULL` |
error | location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error, in which case `error` will be set.

### nm_remote_connection_commit_changes_async ()

    void
    nm_remote_connection_commit_changes_async
                                   (NMRemoteConnection *connection,
                                    gboolean save_to_disk,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Asynchronously sends any local changes to the settings and properties of `connection` to NetworkManager. If `save` is `TRUE`, the updated connection will be saved to disk; if `FALSE`, then only the in-memory representation will be changed.

#### Parameters

connection | the NMRemoteConnection |
save_to_disk | whether to save the changes to persistent storage |
cancellable | a GCancellable, or `NULL` |
callback | callback to be called when the commit operation completes |
user_data | caller-specific data passed to `callback` |

### nm_remote_connection_commit_changes_finish ()

    gboolean
    nm_remote_connection_commit_changes_finish
                                   (NMRemoteConnection *connection,
                                    GAsyncResult *result,
                                    GError **error);

Gets the result of a call to `nm_remote_connection_commit_changes_async()`.

#### Parameters

connection | the NMRemoteConnection |
result | the result passed to the GAsyncReadyCallback |
error | location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error, in which case `error` will be set.

### nm_remote_connection_save ()

    gboolean
    nm_remote_connection_save (NMRemoteConnection *connection,
                               GCancellable *cancellable,
                               GError **error);

`nm_remote_connection_save` has been deprecated since version 1.22 and should not be used in newly-written code.

Use `nm_remote_connection_save_async()` or GDBusConnection.

Saves the connection to disk if the connection has changes that have not yet been written to disk, or if the connection has never been saved.

#### Parameters

connection | the NMRemoteConnection |
cancellable | a GCancellable, or `NULL` |
error | location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error, in which case `error` will be set.

### nm_remote_connection_save_async ()

    void
    nm_remote_connection_save_async (NMRemoteConnection *connection,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Saves the connection to disk if the connection has changes that have not yet been written to disk, or if the connection has never been saved.

#### Parameters

connection | the NMRemoteConnection |
cancellable | a GCancellable, or `NULL` |
callback | callback to be called when the save operation completes |
user_data | caller-specific data passed to `callback` |

### nm_remote_connection_save_finish ()

    gboolean
    nm_remote_connection_save_finish (NMRemoteConnection *connection,
                                      GAsyncResult *result,
                                      GError **error);

Gets the result of a call to `nm_remote_connection_save_async()`.

#### Parameters

connection | the NMRemoteConnection |
result | the result passed to the GAsyncReadyCallback |
error | location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error, in which case `error` will be set.

### nm_remote_connection_delete ()

    gboolean
    nm_remote_connection_delete (NMRemoteConnection *connection,
                                 GCancellable *cancellable,
                                 GError **error);

`nm_remote_connection_delete` has been deprecated since version 1.22 and should not be used in newly-written code.

Use `nm_remote_connection_delete_async()` or GDBusConnection.

Deletes the connection.

#### Parameters

connection | the NMRemoteConnection |
cancellable | a GCancellable, or `NULL` |
error | location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error, in which case `error` will be set.

### nm_remote_connection_delete_async ()

    void
    nm_remote_connection_delete_async (NMRemoteConnection *connection,
                                       GCancellable *cancellable,
                                       GAsyncReadyCallback callback,
                                       gpointer user_data);

Asynchronously deletes the connection.

#### Parameters

connection | the NMRemoteConnection |
cancellable | a GCancellable, or `NULL` |
callback | callback to be called when the delete operation completes |
user_data | caller-specific data passed to `callback` |

### nm_remote_connection_delete_finish ()

    gboolean
    nm_remote_connection_delete_finish (NMRemoteConnection *connection,
                                        GAsyncResult *result,
                                        GError **error);

Gets the result of a call to `nm_remote_connection_delete_async()`.

#### Parameters

connection | the NMRemoteConnection |
result | the result passed to the GAsyncReadyCallback |
error | location for a GError, or `NULL` |

#### Returns

`TRUE` on success, `FALSE` on error, in which case `error` will be set.

### nm_remote_connection_get_secrets ()

    GVariant *
    nm_remote_connection_get_secrets (NMRemoteConnection *connection,
                                      const char *setting_name,
                                      GCancellable *cancellable,
                                      GError **error);

Request the connection's secrets. Note that this is a blocking D-Bus call, not a simple property accessor.

#### Parameters

connection | the NMRemoteConnection |
setting_name | the NMSetting object name to get secrets for |
cancellable | a GCancellable, or `NULL` |
error | location for a GError, or `NULL` |

#### Returns

a GVariant of type `NM_VARIANT_TYPE_CONNECTION` containing `connection` 's secrets, or `NULL` on error.

Warning: NMClient contains a cache of objects on D-Bus. This cache gets updated with D-Bus signals when iterating the GMainContext. This function performs a (pseudo) blocking D-Bus call. Aside blocking, the result will not be in sync and not be ordered with the content of the NMClient cache. This function used to be deprecated between 1.22 and 1.38 releases.

[transfer full]

### nm_remote_connection_get_secrets_async ()

    void
    nm_remote_connection_get_secrets_async
                                   (NMRemoteConnection *connection,
                                    const char *setting_name,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Asynchronously requests the connection's secrets.

#### Parameters

connection | the NMRemoteConnection |
setting_name | the NMSetting object name to get secrets for |
cancellable | a GCancellable, or `NULL` |
callback | callback to be called when the secret request completes |
user_data | caller-specific data passed to `callback` |

### nm_remote_connection_get_secrets_finish ()

    GVariant *
    nm_remote_connection_get_secrets_finish
                                   (NMRemoteConnection *connection,
                                    GAsyncResult *result,
                                    GError **error);

Gets the result of a call to `nm_remote_connection_get_secrets_async()`.

#### Parameters

connection | the NMRemoteConnection |
result | the result passed to the GAsyncReadyCallback |
error | location for a GError, or `NULL` |

#### Returns

a GVariant of type `NM_VARIANT_TYPE_CONNECTION` containing `connection` 's secrets, or `NULL` on error.

[transfer full]

### nm_remote_connection_get_unsaved ()

    gboolean
    nm_remote_connection_get_unsaved (NMRemoteConnection *connection);

#### Parameters

connection | the NMRemoteConnection |

#### Returns

`TRUE` if the remote connection contains changes that have not been saved to disk, `FALSE` if the connection is the same as its on-disk representation.

### nm_remote_connection_get_flags ()

    NMSettingsConnectionFlags
    nm_remote_connection_get_flags (NMRemoteConnection *connection);

#### Parameters

connection | the NMRemoteConnection |

#### Returns

the flags of the connection of type NMSettingsConnectionFlags.

Since: 1.12

### nm_remote_connection_get_filename ()

    const char *
    nm_remote_connection_get_filename (NMRemoteConnection *connection);

#### Parameters

connection | the NMRemoteConnection |

#### Returns

file that stores the connection in case the connection is file-backed.

Since: 1.12

### nm_remote_connection_get_visible ()

    gboolean
    nm_remote_connection_get_visible (NMRemoteConnection *connection);

Checks if the connection is visible to the current user. If the connection is not visible then it is essentially useless; it will not contain any settings, and operations such as `nm_remote_connection_save()` and `nm_remote_connection_delete()` will always fail. (NMRemoteSettings will not normally return non-visible connections to callers, but it is possible for a connection's visibility to change after you already have a reference to it.)

#### Parameters

connection | the NMRemoteConnection |

#### Returns

`TRUE` if the remote connection is visible to the current user, `FALSE` if not.

### nm_remote_connection_get_version_id ()

    guint64
    nm_remote_connection_get_version_id (NMRemoteConnection *connection);

#### Parameters

connection | the NMRemoteConnection |

#### Returns

the version-id of the profile. This ID is incremented whenever the profile is modified.

Since: 1.44

## Types and Values

### NM_REMOTE_CONNECTION_DBUS_CONNECTION

    #define NM_REMOTE_CONNECTION_DBUS_CONNECTION "dbus-connection"

### NM_REMOTE_CONNECTION_PATH

    #define NM_REMOTE_CONNECTION_PATH            "path"

### NM_REMOTE_CONNECTION_UNSAVED

    #define NM_REMOTE_CONNECTION_UNSAVED         "unsaved"

### NM_REMOTE_CONNECTION_FLAGS

    #define NM_REMOTE_CONNECTION_FLAGS           "flags"

### NM_REMOTE_CONNECTION_FILENAME

    #define NM_REMOTE_CONNECTION_FILENAME        "filename"

### NM_REMOTE_CONNECTION_VERSION_ID

    #define NM_REMOTE_CONNECTION_VERSION_ID      "version-id"

### NM_REMOTE_CONNECTION_VISIBLE

    #define NM_REMOTE_CONNECTION_VISIBLE         "visible"

### NMRemoteConnection

    typedef struct _NMRemoteConnection NMRemoteConnection;

## Property Details

### The `“filename”` property

      “filename”                 char *

File that stores the connection in case the connection is file-backed.

Owner: NMRemoteConnection

Flags: Read

Default value: NULL

Since: 1.12

### The `“flags”` property

      “flags”                    guint

The flags of the connection as unsigned integer. The values correspond to the NMSettingsConnectionFlags enum.

Owner: NMRemoteConnection

Flags: Read

Default value: 0

Since: 1.12

### The `“unsaved”` property

      “unsaved”                  gboolean

`TRUE` if the remote connection contains changes that have not been saved to disk, `FALSE` if the connection is the same as its on-disk representation.

Owner: NMRemoteConnection

Flags: Read

Default value: FALSE

### The `“version-id”` property

      “version-id”               guint64

The version ID of the profile that is incremented when the profile gets modified. This can be used to track concurrent modifications of the profile.

Owner: NMRemoteConnection

Flags: Read

Default value: 0

Since: 1.44

### The `“visible”` property

      “visible”                  gboolean

`TRUE` if the remote connection is visible to the current user, `FALSE` if not. If the connection is not visible then it is essentially useless; it will not contain any settings, and operations such as `nm_remote_connection_save()` and `nm_remote_connection_delete()` will always fail. (NMRemoteSettings will not normally return non-visible connections to callers, but it is possible for a connection's visibility to change after you already have a reference to it.)

Owner: NMRemoteConnection

Flags: Read

Default value: FALSE