NMClient: libnm Reference Manual

## NMClient NMClient |

## Functions

GQuark | nm_client_error_quark ()
NMClient * | nm_client_new ()
void | nm_client_new_async ()
NMClient * | nm_client_new_finish ()
const char * | nm_client_get_version ()
NMState | nm_client_get_state ()
gboolean | nm_client_get_startup ()
gboolean | nm_client_get_nm_running ()
gboolean | nm_client_networking_get_enabled ()
gboolean | nm_client_networking_set_enabled ()
gboolean | nm_client_wireless_get_enabled ()
void | nm_client_wireless_set_enabled ()
gboolean | nm_client_wireless_hardware_get_enabled ()
gboolean | nm_client_wwan_get_enabled ()
void | nm_client_wwan_set_enabled ()
gboolean | nm_client_wwan_hardware_get_enabled ()
gboolean | nm_client_wimax_get_enabled ()
void | nm_client_wimax_set_enabled ()
gboolean | nm_client_wimax_hardware_get_enabled ()
gboolean | nm_client_get_logging ()
gboolean | nm_client_set_logging ()
NMClientPermissionResult | nm_client_get_permission_result ()
NMConnectivityState | nm_client_get_connectivity ()
NMConnectivityState | nm_client_check_connectivity ()
void | nm_client_check_connectivity_async ()
NMConnectivityState | nm_client_check_connectivity_finish ()
gboolean | nm_client_save_hostname ()
void | nm_client_save_hostname_async ()
gboolean | nm_client_save_hostname_finish ()
const GPtrArray * | nm_client_get_devices ()
const GPtrArray * | nm_client_get_all_devices ()
NMDevice * | nm_client_get_device_by_path ()
NMDevice * | nm_client_get_device_by_iface ()
const GPtrArray * | nm_client_get_active_connections ()
NMActiveConnection * | nm_client_get_primary_connection ()
NMActiveConnection * | nm_client_get_activating_connection ()
void | nm_client_activate_connection_async ()
NMActiveConnection * | nm_client_activate_connection_finish ()
void | nm_client_add_and_activate_connection_async ()
NMActiveConnection * | nm_client_add_and_activate_connection_finish ()
gboolean | nm_client_deactivate_connection ()
void | nm_client_deactivate_connection_async ()
gboolean | nm_client_deactivate_connection_finish ()
const GPtrArray * | nm_client_get_connections ()
NMRemoteConnection * | nm_client_get_connection_by_id ()
NMRemoteConnection * | nm_client_get_connection_by_path ()
NMRemoteConnection * | nm_client_get_connection_by_uuid ()
void | nm_client_add_connection_async ()
NMRemoteConnection * | nm_client_add_connection_finish ()
gboolean | nm_client_load_connections ()
void | nm_client_load_connections_async ()
gboolean | nm_client_load_connections_finish ()
gboolean | nm_client_reload_connections ()
void | nm_client_reload_connections_async ()
gboolean | nm_client_reload_connections_finish ()

## Properties

NMActiveConnection * | activating-connection | Read
GPtrArray * | active-connections | Read
GPtrArray * | all-devices | Read
gboolean | can-modify | Read
GPtrArray * | connections | Read
NMConnectivityState | connectivity | Read
GPtrArray * | devices | Read
gchar * | hostname | Read
guint | metered | Read
gboolean | networking-enabled | Read / Write
gboolean | nm-running | Read
NMActiveConnection * | primary-connection | Read
gboolean | startup | Read
NMState | state | Read
gchar * | version | Read
gboolean | wimax-enabled | Read / Write
gboolean | wimax-hardware-enabled | Read
gboolean | wireless-enabled | Read / Write
gboolean | wireless-hardware-enabled | Read
gboolean | wwan-enabled | Read / Write
gboolean | wwan-hardware-enabled | Read

## Signals

void | any-device-added | Run First
void | any-device-removed | Run First
void | connection-added | Run First
void | connection-removed | Run First
void | device-added | Run First
void | device-removed | Run First
void | permission-changed | Run First

## Types and Values

#define | NM_CLIENT_VERSION
#define | NM_CLIENT_STATE
#define | NM_CLIENT_STARTUP
#define | NM_CLIENT_NM_RUNNING
#define | NM_CLIENT_NETWORKING_ENABLED
#define | NM_CLIENT_WIRELESS_ENABLED
#define | NM_CLIENT_WIRELESS_HARDWARE_ENABLED
#define | NM_CLIENT_WWAN_ENABLED
#define | NM_CLIENT_WWAN_HARDWARE_ENABLED
#define | NM_CLIENT_WIMAX_ENABLED
#define | NM_CLIENT_WIMAX_HARDWARE_ENABLED
#define | NM_CLIENT_ACTIVE_CONNECTIONS
#define | NM_CLIENT_CONNECTIVITY
#define | NM_CLIENT_PRIMARY_CONNECTION
#define | NM_CLIENT_ACTIVATING_CONNECTION
#define | NM_CLIENT_DEVICES
#define | NM_CLIENT_ALL_DEVICES
#define | NM_CLIENT_CONNECTIONS
#define | NM_CLIENT_HOSTNAME
#define | NM_CLIENT_CAN_MODIFY
#define | NM_CLIENT_METERED
#define | NM_CLIENT_DEVICE_ADDED
#define | NM_CLIENT_DEVICE_REMOVED
#define | NM_CLIENT_ANY_DEVICE_ADDED
#define | NM_CLIENT_ANY_DEVICE_REMOVED
#define | NM_CLIENT_PERMISSION_CHANGED
#define | NM_CLIENT_CONNECTION_ADDED
#define | NM_CLIENT_CONNECTION_REMOVED
enum | NMClientPermission
enum | NMClientPermissionResult
enum | NMClientError
#define | NM_CLIENT_ERROR
| NMClient

## Object Hierarchy

        GEnum
        ├── NMClientError
        ├── NMClientPermission
        ╰── NMClientPermissionResult
        GObject
        ╰── NMClient

## Implemented Interfaces

NMClient implements GInitable and GAsyncInitable.

## Description

## Functions

### nm_client_error_quark ()

    GQuark
    nm_client_error_quark (void);

Registers an error quark for NMClient if necessary.

#### Returns

the error quark used for NMClient errors.

### nm_client_new ()

    NMClient *
    nm_client_new (GCancellable *cancellable,
                   GError **error);

Creates a new NMClient.

Note that this will do blocking D-Bus calls to initialize the client. You can use `nm_client_new_async()` if you want to avoid that.

#### Parameters

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

#### Returns

a new NMClient or NULL on an error

### nm_client_new_async ()

    void
    nm_client_new_async (GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data);

Creates a new NMClient and begins asynchronously initializing it. `callback` will be called when it is done; use `nm_client_new_finish()` to get the result. Note that on an error, the callback can be invoked with two first parameters as NULL.

#### Parameters

cancellable | a GCancellable, or `NULL` |
callback | callback to call when the client is created |
user_data | data for `callback` |

### nm_client_new_finish ()

    NMClient *
    nm_client_new_finish (GAsyncResult *result,
                          GError **error);

Gets the result of an `nm_client_new_async()` call.

#### Parameters

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

#### Returns

a new NMClient, or `NULL` on error

### nm_client_get_version ()

    const char *
    nm_client_get_version (NMClient *client);

Gets NetworkManager version.

#### Parameters

client | a NMClient |

#### Returns

string with the version (or `NULL` if NetworkManager is not running)

### nm_client_get_state ()

    NMState
    nm_client_get_state (NMClient *client);

Gets the current daemon state.

#### Parameters

client | a NMClient |

#### Returns

the current `NMState`

### nm_client_get_startup ()

    gboolean
    nm_client_get_startup (NMClient *client);

Tests whether the daemon is still in the process of activating connections at startup.

#### Parameters

client | a NMClient |

#### Returns

whether the daemon is still starting up

### nm_client_get_nm_running ()

    gboolean
    nm_client_get_nm_running (NMClient *client);

Determines whether the daemon is running.

#### Parameters

client | a NMClient |

#### Returns

`TRUE` if the daemon is running

### nm_client_networking_get_enabled ()

    gboolean
    nm_client_networking_get_enabled (NMClient *client);

Whether networking is enabled or disabled.

#### Parameters

client | a NMClient |

#### Returns

`TRUE` if networking is enabled, `FALSE` if networking is disabled

### nm_client_networking_set_enabled ()

    gboolean
    nm_client_networking_set_enabled (NMClient *client,
                                      gboolean enabled,
                                      GError **error);

Enables or disables networking. When networking is disabled, all controlled interfaces are disconnected and deactivated. When networking is enabled, all controlled interfaces are available for activation.

#### Parameters

client | a NMClient |
enabled | `TRUE` to set networking enabled, `FALSE` to set networking disabled |
error | return location for a GError, or `NULL`. | [allow-none]

#### Returns

`TRUE` on success, `FALSE` otherwise

### nm_client_wireless_get_enabled ()

    gboolean
    nm_client_wireless_get_enabled (NMClient *client);

Determines whether the wireless is enabled.

#### Parameters

client | a NMClient |

#### Returns

`TRUE` if wireless is enabled

### nm_client_wireless_set_enabled ()

    void
    nm_client_wireless_set_enabled (NMClient *client,
                                    gboolean enabled);

Enables or disables wireless devices.

#### Parameters

client | a NMClient |
enabled | `TRUE` to enable wireless |

### nm_client_wireless_hardware_get_enabled ()

    gboolean
    nm_client_wireless_hardware_get_enabled
                                   (NMClient *client);

Determines whether the wireless hardware is enabled.

#### Parameters

client | a NMClient |

#### Returns

`TRUE` if the wireless hardware is enabled

### nm_client_wwan_get_enabled ()

    gboolean
    nm_client_wwan_get_enabled (NMClient *client);

Determines whether WWAN is enabled.

#### Parameters

client | a NMClient |

#### Returns

`TRUE` if WWAN is enabled

### nm_client_wwan_set_enabled ()

    void
    nm_client_wwan_set_enabled (NMClient *client,
                                gboolean enabled);

Enables or disables WWAN devices.

#### Parameters

client | a NMClient |
enabled | `TRUE` to enable WWAN |

### nm_client_wwan_hardware_get_enabled ()

    gboolean
    nm_client_wwan_hardware_get_enabled (NMClient *client);

Determines whether the WWAN hardware is enabled.

#### Parameters

client | a NMClient |

#### Returns

`TRUE` if the WWAN hardware is enabled

### nm_client_wimax_get_enabled ()

    gboolean
    nm_client_wimax_get_enabled (NMClient *client);

Determines whether WiMAX is enabled.

#### Parameters

client | a NMClient |

#### Returns

`TRUE` if WiMAX is enabled

### nm_client_wimax_set_enabled ()

    void
    nm_client_wimax_set_enabled (NMClient *client,
                                 gboolean enabled);

Enables or disables WiMAX devices.

#### Parameters

client | a NMClient |
enabled | `TRUE` to enable WiMAX |

### nm_client_wimax_hardware_get_enabled ()

    gboolean
    nm_client_wimax_hardware_get_enabled (NMClient *client);

Determines whether the WiMAX hardware is enabled.

#### Parameters

client | a NMClient |

#### Returns

`TRUE` if the WiMAX hardware is enabled

### nm_client_get_logging ()

    gboolean
    nm_client_get_logging (NMClient *client,
                           char **level,
                           char **domains,
                           GError **error);

Gets NetworkManager current logging level and domains.

#### Parameters

client | a NMClient |
level | return location for logging level string. | [allow-none]
domains | return location for log domains string. The string is a list of domains separated by ",". | [allow-none]
error | return location for a GError, or `NULL`. | [allow-none]

#### Returns

`TRUE` on success, `FALSE` otherwise

### nm_client_set_logging ()

    gboolean
    nm_client_set_logging (NMClient *client,
                           const char *level,
                           const char *domains,
                           GError **error);

Sets NetworkManager logging level and/or domains.

#### Parameters

client | a NMClient |
level | logging level to set (`NULL` or an empty string for no change). | [allow-none]
domains | logging domains to set. The string should be a list of log domains separated by ",". (`NULL` or an empty string for no change). | [allow-none]
error | return location for a GError, or `NULL`. | [allow-none]

#### Returns

`TRUE` on success, `FALSE` otherwise

### nm_client_get_permission_result ()

    NMClientPermissionResult
    nm_client_get_permission_result (NMClient *client,
                                     NMClientPermission permission);

Requests the result of a specific permission, which indicates whether the client can or cannot perform the action the permission represents

#### Parameters

client | a NMClient |
permission | the permission for which to return the result, one of NMClientPermission |

#### Returns

the permission's result, one of NMClientPermissionResult

### nm_client_get_connectivity ()

    NMConnectivityState
    nm_client_get_connectivity (NMClient *client);

Gets the current network connectivity state. Contrast `nm_client_check_connectivity()` and `nm_client_check_connectivity_async()`, which re-check the connectivity state first before returning any information.

#### Parameters

client | an NMClient |

#### Returns

the current connectivity state

### nm_client_check_connectivity ()

    NMConnectivityState
    nm_client_check_connectivity (NMClient *client,
                                  GCancellable *cancellable,
                                  GError **error);

Updates the network connectivity state and returns the (new) current state. Contrast `nm_client_get_connectivity()`, which returns the most recent known state without re-checking.

This is a blocking call; use `nm_client_check_connectivity_async()` if you do not want to block.

#### Parameters

client | an NMClient |
cancellable | a GCancellable |
error | return location for a GError |

#### Returns

the (new) current connectivity state

### nm_client_check_connectivity_async ()

    void
    nm_client_check_connectivity_async (NMClient *client,
                                        GCancellable *cancellable,
                                        GAsyncReadyCallback callback,
                                        gpointer user_data);

Asynchronously updates the network connectivity state and invokes `callback` when complete. Contrast `nm_client_get_connectivity()`, which (immediately) returns the most recent known state without re-checking, and `nm_client_check_connectivity()`, which blocks.

#### Parameters

client | an NMClient |
cancellable | a GCancellable |
callback | callback to call with the result |
user_data | data for `callback` . |

### nm_client_check_connectivity_finish ()

    NMConnectivityState
    nm_client_check_connectivity_finish (NMClient *client,
                                         GAsyncResult *result,
                                         GError **error);

Retrieves the result of an `nm_client_check_connectivity_async()` call.

#### Parameters

client | an NMClient |
result | the GAsyncResult |
error | return location for a GError |

#### Returns

the (new) current connectivity state

### nm_client_save_hostname ()

    gboolean
    nm_client_save_hostname (NMClient *client,
                             const char *hostname,
                             GCancellable *cancellable,
                             GError **error);

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

#### Parameters

client | the `NMClient` |
hostname | the new persistent hostname to set, or `NULL` to clear any existing persistent hostname. | [allow-none]
cancellable | a GCancellable, or `NULL` |
error | return location for GError |

#### Returns

`TRUE` if the request was successful, `FALSE` if it failed

### nm_client_save_hostname_async ()

    void
    nm_client_save_hostname_async (NMClient *client,
                                   const char *hostname,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

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

#### Parameters

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

### nm_client_save_hostname_finish ()

    gboolean
    nm_client_save_hostname_finish (NMClient *client,
                                    GAsyncResult *result,
                                    GError **error);

Gets the result of an `nm_client_save_hostname_async()` call.

#### Parameters

client | the `NMClient` |
result | the result passed to the GAsyncReadyCallback |
error | return location for GError |

#### Returns

`TRUE` if the request was successful, `FALSE` if it failed

### nm_client_get_devices ()

    const GPtrArray *
    nm_client_get_devices (NMClient *client);

Gets all the known network devices. Use `nm_device_get_type()` or the `NM_IS_DEVICE_XXXX` functions to determine what kind of device member of the returned array is, and then you may use device-specific methods such as `nm_device_ethernet_get_hw_address()`.

#### Parameters

client | a NMClient |

#### Returns

a GPtrArray containing all the NMDevices. The returned array is owned by the NMClient object and should not be modified.

[transfer none][element-type NMDevice]

### nm_client_get_all_devices ()

    const GPtrArray *
    nm_client_get_all_devices (NMClient *client);

Gets both real devices and device placeholders (eg, software devices which do not currently exist, but could be created automatically by NetworkManager if one of their NMDevice::ActivatableConnections was activated). Use `nm_device_is_real()` to determine whether each device is a real device or a placeholder.

Use `nm_device_get_type()` or the `NM_IS_DEVICE_XXXX()` functions to determine what kind of device each member of the returned array is, and then you may use device-specific methods such as `nm_device_ethernet_get_hw_address()`.

#### Parameters

client | a NMClient |

#### Returns

a GPtrArray containing all the NMDevices. The returned array is owned by the NMClient object and should not be modified.

[transfer none][element-type NMDevice]

Since: 1.2

### nm_client_get_device_by_path ()

    NMDevice *
    nm_client_get_device_by_path (NMClient *client,
                                  const char *object_path);

Gets a NMDevice from a NMClient.

#### Parameters

client | a NMClient |
object_path | the object path to search for |

#### Returns

the NMDevice for the given `object_path` or `NULL` if none is found.

[transfer none]

### nm_client_get_device_by_iface ()

    NMDevice *
    nm_client_get_device_by_iface (NMClient *client,
                                   const char *iface);

Gets a NMDevice from a NMClient.

#### Parameters

client | a NMClient |
iface | the interface name to search for |

#### Returns

the NMDevice for the given `iface` or `NULL` if none is found.

[transfer none]

### nm_client_get_active_connections ()

    const GPtrArray *
    nm_client_get_active_connections (NMClient *client);

Gets the active connections.

#### Parameters

client | a NMClient |

#### Returns

a GPtrArray containing all the active NMActiveConnections. The returned array is owned by the client and should not be modified.

[transfer none][element-type NMActiveConnection]

### nm_client_get_primary_connection ()

    NMActiveConnection *
    nm_client_get_primary_connection (NMClient *client);

Gets the NMActiveConnection corresponding to the primary active network device.

In particular, when there is no VPN active, or the VPN does not have the default route, this returns the active connection that has the default route. If there is a VPN active with the default route, then this function returns the active connection that contains the route to the VPN endpoint.

If there is no default route, or the default route is over a non-NetworkManager-recognized device, this will return `NULL`.

#### Parameters

client | an NMClient |

#### Returns

the appropriate NMActiveConnection, if any.

[transfer none]

### nm_client_get_activating_connection ()

    NMActiveConnection *
    nm_client_get_activating_connection (NMClient *client);

Gets the NMActiveConnection corresponding to a currently-activating connection that is expected to become the new “primary-connection” upon successful activation.

#### Parameters

client | an NMClient |

#### Returns

the appropriate NMActiveConnection, if any.

[transfer none]

### nm_client_activate_connection_async ()

    void
    nm_client_activate_connection_async (NMClient *client,
                                         NMConnection *connection,
                                         NMDevice *device,
                                         const char *specific_object,
                                         GCancellable *cancellable,
                                         GAsyncReadyCallback callback,
                                         gpointer user_data);

Asynchronously starts a connection to a particular network using the configuration settings from `connection` and the network device `device` . Certain connection types also take a "specific object" which is the object path of a connection- specific object, like an NMAccessPoint for Wi-Fi connections, or an NMWimaxNsp for WiMAX connections, to which you wish to connect. If the specific object is not given, NetworkManager can, in some cases, automatically determine which network to connect to given the settings in `connection` .

If `connection` is not given for a device-based activation, NetworkManager picks the best available connection for the device and activates it.

Note that the callback is invoked when NetworkManager has started activating the new connection, not when it finishes. You can used the returned NMActiveConnection object (in particular, “state”) to track the activation to its completion.

#### Parameters

client | a NMClient |
connection | an NMConnection. | [allow-none]
device | the NMDevice. | [allow-none]
specific_object | the object path of a connection-type-specific object this activation should use. This parameter is currently ignored for wired and mobile broadband connections, and the value of `NULL` should be used (ie, no specific object). For Wi-Fi or WiMAX connections, pass the object path of a NMAccessPoint or NMWimaxNsp owned by `device` , which you can get using `nm_object_get_path()`, and which will be used to complete the details of the newly added connection. | [allow-none]
cancellable | a GCancellable, or `NULL` |
callback | callback to be called when the activation has started |
user_data | caller-specific data passed to `callback` |

### nm_client_activate_connection_finish ()

    NMActiveConnection *
    nm_client_activate_connection_finish (NMClient *client,
                                          GAsyncResult *result,
                                          GError **error);

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

#### Parameters

client | an NMClient |
result | the result passed to the GAsyncReadyCallback |
error | location for a GError, or `NULL` |

#### Returns

the new NMActiveConnection on success, `NULL` on failure, in which case `error` will be set.

[transfer full]

### nm_client_add_and_activate_connection_async ()

    void
    nm_client_add_and_activate_connection_async
                                   (NMClient *client,
                                    NMConnection *partial,
                                    NMDevice *device,
                                    const char *specific_object,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Adds a new connection using the given details (if any) as a template, automatically filling in missing settings with the capabilities of the given device and specific object. The new connection is then asynchronously activated as with `nm_client_activate_connection_async()`. Cannot be used for VPN connections at this time.

Note that the callback is invoked when NetworkManager has started activating the new connection, not when it finishes. You can used the returned NMActiveConnection object (in particular, “state”) to track the activation to its completion.

#### Parameters

client | a NMClient |
partial | an NMConnection to add; the connection may be partially filled (or even `NULL`) and will be completed by NetworkManager using the given `device` and `specific_object` before being added. | [allow-none]
device | the NMDevice |
specific_object | the object path of a connection-type-specific object this activation should use. This parameter is currently ignored for wired and mobile broadband connections, and the value of `NULL` should be used (ie, no specific object). For Wi-Fi or WiMAX connections, pass the object path of a NMAccessPoint or NMWimaxNsp owned by `device` , which you can get using `nm_object_get_path()`, and which will be used to complete the details of the newly added connection. | [allow-none]
cancellable | a GCancellable, or `NULL` |
callback | callback to be called when the activation has started |
user_data | caller-specific data passed to `callback` |

### nm_client_add_and_activate_connection_finish ()

    NMActiveConnection *
    nm_client_add_and_activate_connection_finish
                                   (NMClient *client,
                                    GAsyncResult *result,
                                    GError **error);

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

You can call `nm_active_connection_get_connection()` on the returned NMActiveConnection to find the path of the created NMConnection.

#### Parameters

client | an NMClient |
result | the result passed to the GAsyncReadyCallback |
error | location for a GError, or `NULL` |

#### Returns

the new NMActiveConnection on success, `NULL` on failure, in which case `error` will be set.

[transfer full]

### nm_client_deactivate_connection ()

    gboolean
    nm_client_deactivate_connection (NMClient *client,
                                     NMActiveConnection *active,
                                     GCancellable *cancellable,
                                     GError **error);

Deactivates an active NMActiveConnection.

#### Parameters

client | a NMClient |
active | the NMActiveConnection to deactivate |
cancellable | a GCancellable, or `NULL` |
error | location for a GError, or `NULL` |

#### Returns

success or failure

### nm_client_deactivate_connection_async ()

    void
    nm_client_deactivate_connection_async (NMClient *client,
                                           NMActiveConnection *active,
                                           GCancellable *cancellable,
                                           GAsyncReadyCallback callback,
                                           gpointer user_data);

Asynchronously deactivates an active NMActiveConnection.

#### Parameters

client | a NMClient |
active | the NMActiveConnection to deactivate |
cancellable | a GCancellable, or `NULL` |
callback | callback to be called when the deactivation has completed |
user_data | caller-specific data passed to `callback` |

### nm_client_deactivate_connection_finish ()

    gboolean
    nm_client_deactivate_connection_finish
                                   (NMClient *client,
                                    GAsyncResult *result,
                                    GError **error);

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

#### Parameters

client | a NMClient |
result | the result passed to the GAsyncReadyCallback |
error | location for a GError, or `NULL` |

#### Returns

success or failure

### nm_client_get_connections ()

    const GPtrArray *
    nm_client_get_connections (NMClient *client);

#### Parameters

client | the `NMClient` |

#### Returns

an array containing all connections provided by the remote settings service. The returned array is owned by the NMClient object and should not be modified.

The connections are as received from D-Bus and might not validate according to `nm_connection_verify()`.

[transfer none][element-type NMRemoteConnection]

### nm_client_get_connection_by_id ()

    NMRemoteConnection *
    nm_client_get_connection_by_id (NMClient *client,
                                    const char *id);

Returns the first matching `NMRemoteConnection` matching a given `id` .

#### Parameters

client | the `NMClient` |
id | the id of the remote connection |

#### Returns

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

The connection is as received from D-Bus and might not validate according to `nm_connection_verify()`.

[transfer none]

### nm_client_get_connection_by_path ()

    NMRemoteConnection *
    nm_client_get_connection_by_path (NMClient *client,
                                      const char *path);

Returns the `NMRemoteConnection` representing the connection at `path` .

#### Parameters

client | the `NMClient` |
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

The connection is as received from D-Bus and might not validate according to `nm_connection_verify()`.

[transfer none]

### nm_client_get_connection_by_uuid ()

    NMRemoteConnection *
    nm_client_get_connection_by_uuid (NMClient *client,
                                      const char *uuid);

Returns the `NMRemoteConnection` identified by `uuid` .

#### Parameters

client | the `NMClient` |
uuid | the UUID of the remote connection |

#### Returns

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

The connection is as received from D-Bus and might not validate according to `nm_connection_verify()`.

[transfer none]

### nm_client_add_connection_async ()

    void
    nm_client_add_connection_async (NMClient *client,
                                    NMConnection *connection,
                                    gboolean save_to_disk,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Requests that the remote settings service add the given settings to a new connection. If `save_to_disk` is `TRUE`, the connection is immediately written to disk; otherwise it is initially only stored in memory, but may be saved later by calling the connection's `nm_remote_connection_commit_changes()` method.

`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

client | the `NMClient` |
connection | the connection to add. Note that this object's settings will be added, not the object itself |
save_to_disk | whether to immediately save the connection to disk |
cancellable | a GCancellable, or `NULL` |
callback | callback to be called when the add operation completes. | [scope async]
user_data | caller-specific data passed to `callback` . | [closure]

### nm_client_add_connection_finish ()

    NMRemoteConnection *
    nm_client_add_connection_finish (NMClient *client,
                                     GAsyncResult *result,
                                     GError **error);

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

#### Parameters

client | an NMClient |
result | the result passed to the GAsyncReadyCallback |
error | location for a GError, or `NULL` |

#### Returns

the new NMRemoteConnection on success, `NULL` on failure, in which case `error` will be set.

[transfer full]

### nm_client_load_connections ()

    gboolean
    nm_client_load_connections (NMClient *client,
                                char **filenames,
                                char ***failures,
                                GCancellable *cancellable,
                                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 `client` '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

client | the `NMClient` |
filenames | `NULL`-terminated array of filenames to load. | [array zero-terminated=1]
failures | on return, a `NULL`-terminated array of filenames that failed to load. | [out][transfer full]
cancellable | a GCancellable, or `NULL` |
error | return location for GError |

#### Returns

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

### nm_client_load_connections_async ()

    void
    nm_client_load_connections_async (NMClient *client,
                                      char **filenames,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

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

See `nm_client_load_connections()` for more details.

#### Parameters

client | the `NMClient` |
filenames | `NULL`-terminated array of filenames to load. | [array zero-terminated=1]
cancellable | a GCancellable, or `NULL` |
callback | callback to be called when the operation completes. | [scope async]
user_data | caller-specific data passed to `callback` . | [closure]

### nm_client_load_connections_finish ()

    gboolean
    nm_client_load_connections_finish (NMClient *client,
                                       char ***failures,
                                       GAsyncResult *result,
                                       GError **error);

Gets the result of an `nm_client_load_connections_async()` call.

See `nm_client_load_connections()` for more details.

#### Parameters

client | the `NMClient` |
failures | on return, a `NULL`-terminated array of filenames that failed to load. | [out][transfer full][array zero-terminated=1]
result | the result passed to the GAsyncReadyCallback |
error | location for a GError, or `NULL` |

#### Returns

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

### nm_client_reload_connections ()

    gboolean
    nm_client_reload_connections (NMClient *client,
                                  GCancellable *cancellable,
                                  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

client | the NMClient |
cancellable | a GCancellable, or `NULL` |
error | return location for GError |

#### Returns

`TRUE` on success, `FALSE` on failure

### nm_client_reload_connections_async ()

    void
    nm_client_reload_connections_async (NMClient *client,
                                        GCancellable *cancellable,
                                        GAsyncReadyCallback callback,
                                        gpointer user_data);

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

#### Parameters

client | the NMClient |
cancellable | a GCancellable, or `NULL` |
callback | callback to be called when the reload operation completes. | [scope async]
user_data | caller-specific data passed to `callback` . | [closure]

### nm_client_reload_connections_finish ()

    gboolean
    nm_client_reload_connections_finish (NMClient *client,
                                         GAsyncResult *result,
                                         GError **error);

Gets the result of an `nm_client_reload_connections_async()` call.

#### Parameters

client | the NMClient |
result | the result passed to the GAsyncReadyCallback |
error | return location for GError |

#### Returns

`TRUE` on success, `FALSE` on failure

## Types and Values

### NM_CLIENT_VERSION

    #define NM_CLIENT_VERSION "version"

### NM_CLIENT_STATE

    #define NM_CLIENT_STATE "state"

### NM_CLIENT_STARTUP

    #define NM_CLIENT_STARTUP "startup"

### NM_CLIENT_NM_RUNNING

    #define NM_CLIENT_NM_RUNNING "nm-running"

### NM_CLIENT_NETWORKING_ENABLED

    #define NM_CLIENT_NETWORKING_ENABLED "networking-enabled"

### NM_CLIENT_WIRELESS_ENABLED

    #define NM_CLIENT_WIRELESS_ENABLED "wireless-enabled"

### NM_CLIENT_WIRELESS_HARDWARE_ENABLED

    #define NM_CLIENT_WIRELESS_HARDWARE_ENABLED "wireless-hardware-enabled"

### NM_CLIENT_WWAN_ENABLED

    #define NM_CLIENT_WWAN_ENABLED "wwan-enabled"

### NM_CLIENT_WWAN_HARDWARE_ENABLED

    #define NM_CLIENT_WWAN_HARDWARE_ENABLED "wwan-hardware-enabled"

### NM_CLIENT_WIMAX_ENABLED

    #define NM_CLIENT_WIMAX_ENABLED "wimax-enabled"

### NM_CLIENT_WIMAX_HARDWARE_ENABLED

    #define NM_CLIENT_WIMAX_HARDWARE_ENABLED "wimax-hardware-enabled"

### NM_CLIENT_ACTIVE_CONNECTIONS

    #define NM_CLIENT_ACTIVE_CONNECTIONS "active-connections"

### NM_CLIENT_CONNECTIVITY

    #define NM_CLIENT_CONNECTIVITY "connectivity"

### NM_CLIENT_PRIMARY_CONNECTION

    #define NM_CLIENT_PRIMARY_CONNECTION "primary-connection"

### NM_CLIENT_ACTIVATING_CONNECTION

    #define NM_CLIENT_ACTIVATING_CONNECTION "activating-connection"

### NM_CLIENT_DEVICES

    #define NM_CLIENT_DEVICES "devices"

### NM_CLIENT_ALL_DEVICES

    #define NM_CLIENT_ALL_DEVICES "all-devices"

### NM_CLIENT_CONNECTIONS

    #define NM_CLIENT_CONNECTIONS "connections"

### NM_CLIENT_HOSTNAME

    #define NM_CLIENT_HOSTNAME "hostname"

### NM_CLIENT_CAN_MODIFY

    #define NM_CLIENT_CAN_MODIFY "can-modify"

### NM_CLIENT_METERED

    #define NM_CLIENT_METERED "metered"

### NM_CLIENT_DEVICE_ADDED

    #define NM_CLIENT_DEVICE_ADDED "device-added"

### NM_CLIENT_DEVICE_REMOVED

    #define NM_CLIENT_DEVICE_REMOVED "device-removed"

### NM_CLIENT_ANY_DEVICE_ADDED

    #define NM_CLIENT_ANY_DEVICE_ADDED "any-device-added"

### NM_CLIENT_ANY_DEVICE_REMOVED

    #define NM_CLIENT_ANY_DEVICE_REMOVED "any-device-removed"

### NM_CLIENT_PERMISSION_CHANGED

    #define NM_CLIENT_PERMISSION_CHANGED "permission-changed"

### NM_CLIENT_CONNECTION_ADDED

    #define NM_CLIENT_CONNECTION_ADDED "connection-added"

### NM_CLIENT_CONNECTION_REMOVED

    #define NM_CLIENT_CONNECTION_REMOVED "connection-removed"

### enum NMClientPermission

NMClientPermission values indicate various permissions that NetworkManager clients can obtain to perform certain tasks on behalf of the current user.

#### Members

NM_CLIENT_PERMISSION_NONE | unknown or no permission |
NM_CLIENT_PERMISSION_ENABLE_DISABLE_NETWORK | controls whether networking can be globally enabled or disabled |
NM_CLIENT_PERMISSION_ENABLE_DISABLE_WIFI | controls whether Wi-Fi can be globally enabled or disabled |
NM_CLIENT_PERMISSION_ENABLE_DISABLE_WWAN | controls whether WWAN (3G) can be globally enabled or disabled |
NM_CLIENT_PERMISSION_ENABLE_DISABLE_WIMAX | controls whether WiMAX can be globally enabled or disabled |
NM_CLIENT_PERMISSION_SLEEP_WAKE | controls whether the client can ask NetworkManager to sleep and wake |
NM_CLIENT_PERMISSION_NETWORK_CONTROL | controls whether networking connections can be started, stopped, and changed |
NM_CLIENT_PERMISSION_WIFI_SHARE_PROTECTED | controls whether a password protected Wi-Fi hotspot can be created |
NM_CLIENT_PERMISSION_WIFI_SHARE_OPEN | controls whether an open Wi-Fi hotspot can be created |
NM_CLIENT_PERMISSION_SETTINGS_MODIFY_SYSTEM | controls whether connections that are available to all users can be modified |
NM_CLIENT_PERMISSION_SETTINGS_MODIFY_OWN | controls whether connections owned by the current user can be modified |
NM_CLIENT_PERMISSION_SETTINGS_MODIFY_HOSTNAME | controls whether the persistent hostname can be changed |
NM_CLIENT_PERMISSION_SETTINGS_MODIFY_GLOBAL_DNS | modify persistent global DNS configuration |
NM_CLIENT_PERMISSION_RELOAD | controls access to Reload. |
NM_CLIENT_PERMISSION_LAST | a reserved boundary value |

### enum NMClientPermissionResult

NMClientPermissionResult values indicate what authorizations and permissions the user requires to obtain a given NMClientPermission

#### Members

NM_CLIENT_PERMISSION_RESULT_UNKNOWN | unknown or no authorization |
NM_CLIENT_PERMISSION_RESULT_YES | the permission is available |
NM_CLIENT_PERMISSION_RESULT_AUTH | authorization is necessary before the permission is available |
NM_CLIENT_PERMISSION_RESULT_NO | permission to perform the operation is denied by system policy |

### enum NMClientError

Describes errors that may result from operations involving a NMClient.

D-Bus operations may also return errors from other domains, including NMManagerError, NMSettingsError, NMAgentManagerError, and NMConnectionError.

#### Members

NM_CLIENT_ERROR_FAILED | unknown or unclassified error |
NM_CLIENT_ERROR_MANAGER_NOT_RUNNING | an operation that requires NetworkManager failed because NetworkManager is not running |
NM_CLIENT_ERROR_OBJECT_CREATION_FAILED | NetworkManager claimed that an operation succeeded, but the object that was allegedly created (eg, NMRemoteConnection, NMActiveConnection) was apparently destroyed before NMClient could create a representation of it. |

### NM_CLIENT_ERROR

    #define NM_CLIENT_ERROR nm_client_error_quark ()

### NMClient

    typedef struct _NMClient NMClient;

## Property Details

### The `“activating-connection”` property

      “activating-connection”    NMActiveConnection *

The NMActiveConnection of the activating connection that is likely to become the new “primary-connection”.

Flags: Read

### The `“active-connections”` property

      “active-connections”       GPtrArray *

The active connections.

Element-type: NMActiveConnection

Flags: Read

### The `“all-devices”` property

      “all-devices”              GPtrArray *

List of both real devices and device placeholders.

Element-type: NMDevice

Flags: Read

Since: 1.2

### The `“can-modify”` property

      “can-modify”               gboolean

If `TRUE`, adding and modifying connections is supported.

Flags: Read

Default value: FALSE

### The `“connections”` property

      “connections”              GPtrArray *

The list of configured connections that are available to the user. (Note that this differs from the underlying D-Bus property, which may also contain the object paths of connections that the user does not have permission to read the details of.)

Element-type: NMRemoteConnection

Flags: Read

### The `“connectivity”` property

      “connectivity”             NMConnectivityState

The network connectivity state.

Flags: Read

Default value: NM_CONNECTIVITY_UNKNOWN

### The `“devices”` property

      “devices”                  GPtrArray *

List of real network devices. Does not include placeholder devices.

Element-type: NMDevice

Flags: Read

### The `“hostname”` property

      “hostname”                 gchar *

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

Flags: Read

Default value: NULL

### The `“metered”` property

      “metered”                  guint

Whether the connectivity is metered.

Flags: Read

Default value: 0

Since: 1.2

### The `“networking-enabled”` property

      “networking-enabled”       gboolean

Whether networking is enabled.

Flags: Read / Write

Default value: TRUE

### The `“nm-running”` property

      “nm-running”               gboolean

Whether the daemon is running.

Flags: Read

Default value: FALSE

### The `“primary-connection”` property

      “primary-connection”       NMActiveConnection *

The NMActiveConnection of the device with the default route; see `nm_client_get_primary_connection()` for more details.

Flags: Read

### The `“startup”` property

      “startup”                  gboolean

Whether the daemon is still starting up.

Flags: Read

Default value: FALSE

### The `“state”` property

      “state”                    NMState

The current daemon state.

Flags: Read

Default value: NM_STATE_UNKNOWN

### The `“version”` property

      “version”                  gchar *

The NetworkManager version.

Flags: Read

Default value: NULL

### The `“wimax-enabled”` property

      “wimax-enabled”            gboolean

Whether WiMAX functionality is enabled.

Flags: Read / Write

Default value: FALSE

### The `“wimax-hardware-enabled”` property

      “wimax-hardware-enabled”   gboolean

Whether the WiMAX hardware is enabled.

Flags: Read

Default value: FALSE

### The `“wireless-enabled”` property

      “wireless-enabled”         gboolean

Whether wireless is enabled.

Flags: Read / Write

Default value: FALSE

### The `“wireless-hardware-enabled”` property

      “wireless-hardware-enabled” gboolean

Whether the wireless hardware is enabled.

Flags: Read

Default value: TRUE

### The `“wwan-enabled”` property

      “wwan-enabled”             gboolean

Whether WWAN functionality is enabled.

Flags: Read / Write

Default value: FALSE

### The `“wwan-hardware-enabled”` property

      “wwan-hardware-enabled”    gboolean

Whether the WWAN hardware is enabled.

Flags: Read

Default value: FALSE

## Signal Details

### The `“any-device-added”` signal

    void
    user_function (NMClient *client,
                   GObject  *device,
                   gpointer  user_data)

Notifies that a NMDevice is added. This signal is emitted for both regular devices and placeholder devices.

#### Parameters

client | the client that received the signal |
device | the new device. | [type NMDevice]
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“any-device-removed”` signal

    void
    user_function (NMClient *client,
                   GObject  *device,
                   gpointer  user_data)

Notifies that a NMDevice is removed. This signal is emitted for both regular devices and placeholder devices.

#### Parameters

client | the client that received the signal |
device | the removed device. | [type NMDevice]
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“connection-added”` signal

    void
    user_function (NMClient           *client,
                   NMRemoteConnection *connection,
                   gpointer            user_data)

Notifies that a NMConnection has been added.

#### Parameters

client | the settings object that received the signal |
connection | the new connection |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“connection-removed”` signal

    void
    user_function (NMClient           *client,
                   NMRemoteConnection *connection,
                   gpointer            user_data)

Notifies that a NMConnection has been removed.

#### Parameters

client | the settings object that received the signal |
connection | the removed connection |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“device-added”` signal

    void
    user_function (NMClient *client,
                   GObject  *device,
                   gpointer  user_data)

Notifies that a NMDevice is added. This signal is not emitted for placeholder devices.

#### Parameters

client | the client that received the signal |
device | the new device. | [type NMDevice]
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“device-removed”` signal

    void
    user_function (NMClient *client,
                   GObject  *device,
                   gpointer  user_data)

Notifies that a NMDevice is removed. This signal is not emitted for placeholder devices.

#### Parameters

client | the client that received the signal |
device | the removed device. | [type NMDevice]
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“permission-changed”` signal

    void
    user_function (NMClient *client,
                   guint     permission,
                   guint     result,
                   gpointer  user_data)

Notifies that a permission has changed

#### Parameters

client | the client that received the signal |
permission | a permission from NMClientPermission |
result | the permission's result, one of NMClientPermissionResult |
user_data | user data set when the signal handler was connected. |

Flags: Run First