NMClient

NMClient

Functions

GQuark nm_client_error_quark ()
void nm_dns_entry_unref ()
const char * nm_dns_entry_get_interface ()
const char *const * nm_dns_entry_get_nameservers ()
const char *const * nm_dns_entry_get_domains ()
int nm_dns_entry_get_priority ()
gboolean nm_dns_entry_get_vpn ()
NMClient * nm_client_new ()
void nm_client_new_async ()
NMClient * nm_client_new_finish ()
NMClientInstanceFlags nm_client_get_instance_flags ()
GDBusConnection * nm_client_get_dbus_connection ()
GMainContext * nm_client_get_main_context ()
GObject * nm_client_get_context_busy_watcher ()
const char * nm_client_get_dbus_name_owner ()
const char * nm_client_get_version ()
NMState nm_client_get_state ()
gboolean nm_client_get_startup ()
gboolean nm_client_get_nm_running ()
NMObject * nm_client_get_object_by_path ()
NMMetered nm_client_get_metered ()
gboolean nm_client_networking_get_enabled ()
const guint32 * nm_client_get_capabilities ()
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_connectivity_check_get_available ()
gboolean nm_client_connectivity_check_get_enabled ()
void nm_client_connectivity_check_set_enabled ()
const char * nm_client_connectivity_check_get_uri ()
gboolean nm_client_get_logging ()
gboolean nm_client_set_logging ()
NMClientPermissionResult nm_client_get_permission_result ()
NMTernary nm_client_get_permissions_state ()
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 ()
void nm_client_add_and_activate_connection2 ()
NMActiveConnection * nm_client_add_and_activate_connection2_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 ()
void nm_client_add_connection2 ()
NMRemoteConnection * nm_client_add_connection2_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 ()
const char * nm_client_get_dns_mode ()
const char * nm_client_get_dns_rc_manager ()
const GPtrArray * nm_client_get_dns_configuration ()
const GPtrArray * nm_client_get_checkpoints ()
void nm_client_checkpoint_create ()
NMCheckpoint * nm_client_checkpoint_create_finish ()
void nm_client_checkpoint_destroy ()
gboolean nm_client_checkpoint_destroy_finish ()
void nm_client_checkpoint_rollback ()
GHashTable * nm_client_checkpoint_rollback_finish ()
void nm_client_checkpoint_adjust_rollback_timeout ()
gboolean nm_client_checkpoint_adjust_rollback_timeout_finish ()
void nm_client_reload ()
gboolean nm_client_reload_finish ()
void nm_client_dbus_call ()
GVariant * nm_client_dbus_call_finish ()
void nm_client_dbus_set_property ()
gboolean nm_client_dbus_set_property_finish ()
void nm_utils_print ()

Types and Values

enum NMClientInstanceFlags
#define NM_CLIENT_VERSION
#define NM_CLIENT_STATE
#define NM_CLIENT_STARTUP
#define NM_CLIENT_NM_RUNNING
#define NM_CLIENT_DBUS_CONNECTION
#define NM_CLIENT_DBUS_NAME_OWNER
#define NM_CLIENT_INSTANCE_FLAGS
#define NM_CLIENT_NETWORKING_ENABLED
#define NM_CLIENT_WIRELESS_ENABLED
#define NM_CLIENT_WWAN_ENABLED
#define NM_CLIENT_WIMAX_ENABLED
#define NM_CLIENT_WIRELESS_HARDWARE_ENABLED
#define NM_CLIENT_WWAN_HARDWARE_ENABLED
#define NM_CLIENT_WIMAX_HARDWARE_ENABLED
#define NM_CLIENT_ACTIVE_CONNECTIONS
#define NM_CLIENT_CONNECTIVITY
#define NM_CLIENT_CONNECTIVITY_CHECK_URI
#define NM_CLIENT_CONNECTIVITY_CHECK_AVAILABLE
#define NM_CLIENT_CONNECTIVITY_CHECK_ENABLED
#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_DNS_MODE
#define NM_CLIENT_DNS_RC_MANAGER
#define NM_CLIENT_DNS_CONFIGURATION
#define NM_CLIENT_CHECKPOINTS
#define NM_CLIENT_CAPABILITIES
#define NM_CLIENT_PERMISSIONS_STATE
#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
#define NM_CLIENT_ACTIVE_CONNECTION_ADDED
#define NM_CLIENT_ACTIVE_CONNECTION_REMOVED
enum NMClientError
#define NM_CLIENT_ERROR

Object Hierarchy

    GBoxed
    ╰── NMDnsEntry
    GEnum
    ╰── NMClientError
    GFlags
    ╰── NMClientInstanceFlags

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_dns_entry_unref ()

void
nm_dns_entry_unref (NMDnsEntry *entry);

Decreases the reference count of the object. If the reference count reaches zero, the object will be destroyed.

Parameters

entry

the NMDnsEntry

 

Since: 1.6


nm_dns_entry_get_interface ()

const char *
nm_dns_entry_get_interface (NMDnsEntry *entry);

Gets the interface on which name servers are contacted.

Parameters

entry

the NMDnsEntry

 

Returns

the interface name.

[transfer none]

Since: 1.6


nm_dns_entry_get_nameservers ()

const char *const *
nm_dns_entry_get_nameservers (NMDnsEntry *entry);

Gets the list of name servers for this entry.

Parameters

entry

the NMDnsEntry

 

Returns

the list of name servers.

[transfer none]

Since: 1.6


nm_dns_entry_get_domains ()

const char *const *
nm_dns_entry_get_domains (NMDnsEntry *entry);

Gets the list of DNS domains.

Parameters

entry

the NMDnsEntry

 

Returns

the list of DNS domains.

[transfer none]

Since: 1.6


nm_dns_entry_get_priority ()

int
nm_dns_entry_get_priority (NMDnsEntry *entry);

Gets the priority of the entry

Parameters

entry

the NMDnsEntry

 

Returns

the priority of the entry

Since: 1.6


nm_dns_entry_get_vpn ()

gboolean
nm_dns_entry_get_vpn (NMDnsEntry *entry);

Gets whether the entry refers to VPN name servers.

Parameters

entry

the NMDnsEntry

 

Returns

TRUE if the entry refers to VPN name servers

Since: 1.6


nm_client_new ()

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

Creates a new NMClient synchronously.

Note that this will block until a NMClient instance is fully initialized. This does nothing beside calling g_initable_new(). You are free to call g_initable_new() or g_object_new()/g_initable_init() directly for more control, to set GObject properties or get access to the NMClient instance while it is still initializing.

Using the synchronous initialization creates an NMClient instance that uses an internal GMainContext. This context is invisible to the user. This introduces an additional overhead that is payed not only during object initialization, but for the entire lifetime of this object. Also, due to this internal GMainContext, the events are no longer in sync with other messages from GDBusConnection (but all events of the NMClient will themselves still be ordered). For a serious program, you should therefore avoid these problems by using g_async_initable_init_async() or nm_client_new_async() instead. The sync initialization is still useful for simple scripts or interactive testing for example via pygobject.

Creating an NMClient instance can only fail for two reasons. First, if you didn't provide a NM_CLIENT_DBUS_CONNECTION and the call to g_bus_get() fails. You can avoid that by using g_initable_new() directly and set a D-Bus connection. Second, if you cancelled the creation. If you do that, then note that after the failure there might still be idle actions pending which keep nm_client_get_main_context() alive. That means, in that case you must continue iterating the context to avoid leaks. See nm_client_get_context_busy_watcher().

Creating an NMClient instance when NetworkManager is not running does not cause a failure.

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 asynchronously. callback will be called when it is done. Use nm_client_new_finish() to get the result.

This does nothing beside calling g_async_initable_new_async(). You are free to call g_async_initable_new_async() or g_object_new()/g_async_initable_init_async() directly for more control, to set GObject properties or get access to the NMClient instance while it is still initializing.

Creating an NMClient instance can only fail for two reasons. First, if you didn't provide a NM_CLIENT_DBUS_CONNECTION and the call to g_bus_get() fails. You can avoid that by using g_async_initable_new_async() directly and set a D-Bus connection. Second, if you cancelled the creation. If you do that, then note that after the failure there might still be idle actions pending which keep nm_client_get_main_context() alive. That means, in that case you must continue iterating the context to avoid leaks. See nm_client_get_context_busy_watcher().

Creating an NMClient instance when NetworkManager is not running does not cause a failure.

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_instance_flags ()

NMClientInstanceFlags
nm_client_get_instance_flags (NMClient *self);

Parameters

self

the NMClient instance.

 

Returns

the NMClientInstanceFlags flags.

Since: 1.24


nm_client_get_dbus_connection ()

GDBusConnection *
nm_client_get_dbus_connection (NMClient *client);

Gets the GDBusConnection of the instance. This can be either passed when constructing the instance (as "dbus-connection" property), or it will be automatically initialized during async/sync init.

Parameters

client

a NMClient

 

Returns

the D-Bus connection of the client, or NULL if none is set.

[transfer none]

Since: 1.22


nm_client_get_main_context ()

GMainContext *
nm_client_get_main_context (NMClient *self);

The NMClient instance is permanently associated with the current thread default GMainContext, referenced the time when the instance was created. To receive events, the user must iterate this context and can use it to synchronize access to the client.

Note that even after NMClient instance got destroyed, there might still be pending sources registered in the context. That means, to fully clean up, the user must continue iterating the context as long as the nm_client_get_context_busy_watcher() object is alive.

Parameters

self

the NMClient instance

 

Returns

the GMainContext of the client.

[transfer none]

Since: 1.22


nm_client_get_context_busy_watcher ()

GObject *
nm_client_get_context_busy_watcher (NMClient *self);

Parameters

self

the NMClient instance.

 

Returns

a GObject that stays alive as long as there are pending D-Bus operations.

NMClient will schedule asynchronous D-Bus requests which will complete on the GMainContext associated with the instance. When destroying the NMClient instance, those requests are cancelled right away, however their pending requests are still outstanding and queued in the GMainContext. These outstanding callbacks keep the GMainContext alive. In order to fully release all resources, the user must keep iterating the main context until all these callbacks are handled. Of course, at this point no more actual callbacks will be invoked for the user, those are all cancelled internally.

This just leaves one problem: how long does the user need to keep the GMainContext running to ensure everything is cleaned up? The answer is this GObject. Subscribe a weak reference to the returned object and keep iterating the main context until the object got unreferenced.

Note that after the NMClient instance gets destroyed, all outstanding operations will be cancelled right away. That means, the user needs to iterate the GMainContext a bit longer, but it is guaranteed that the cleanup happens soon after.

The way of using the context-busy-watch, is by registering a weak pointer to see when it gets destroyed. That means, user code should not take additional references on this object to not keep it alive longer.

If you plan to exit the program after releasing the NMClient instance you may not need to worry about these "leaks". Also, if you anyway plan to continue iterating the GMainContext afterwards, then you don't need to care when exactly NMClient is gone completely.

[transfer none]

Since: 1.22


nm_client_get_dbus_name_owner ()

const char *
nm_client_get_dbus_name_owner (NMClient *client);

Parameters

client

a NMClient

 

Returns

the current name owner of the D-Bus service of NetworkManager.

[transfer none]

Since: 1.22


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_get_object_by_path ()

NMObject *
nm_client_get_object_by_path (NMClient *client,
                              const char *dbus_path);

Parameters

client

the NMClient instance

 

dbus_path

the D-Bus path of the object to look up

 

Returns

the NMObject instance that is cached under dbus_path , or NULL if no such object exists.

[transfer none]

Since: 1.24


nm_client_get_metered ()

NMMetered
nm_client_get_metered (NMClient *client);

Parameters

client

a NMClient

 

Returns

whether the default route is metered.

Since: 1.22


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_get_capabilities ()

const guint32 *
nm_client_get_capabilities (NMClient *client,
                            gsize *length);

Parameters

client

the NMClient instance

 

length

the number of returned capabilities.

[out][allow-none]

Returns

the list of capabilities reported by the server or NULL if the capabilities are unknown. The numeric values correspond to NMCapability enum. The array is terminated by a numeric zero sentinel at position length .

[transfer none][array length=length]

Since: 1.24


nm_client_networking_set_enabled ()

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

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

Use the async command nm_client_dbus_call() on NM_DBUS_PATH, NM_DBUS_INTERFACE to call "Enable" with "(b)" arguments and no return value.

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

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

Use the async command nm_client_dbus_set_property() on NM_DBUS_PATH, NM_DBUS_INTERFACE to set "WirelessEnabled" property to a "(b)" value.

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

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

Use the async command nm_client_dbus_set_property() on NM_DBUS_PATH, NM_DBUS_INTERFACE to set "WwanEnabled" property to a "(b)" value.

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

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

This function always returns FALSE because WiMax is no longer supported.

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

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

This function does nothing because WiMax is no longer supported.

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

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

This function always returns FALSE because WiMax is no longer supported.

Determines whether the WiMAX hardware is enabled.

Parameters

client

a NMClient

 

Returns

TRUE if the WiMAX hardware is enabled


nm_client_connectivity_check_get_available ()

gboolean
nm_client_connectivity_check_get_available
                               (NMClient *client);

Determine whether connectivity checking is available. This requires that the URI of a connectivity service has been set in the configuration file.

Parameters

client

a NMClient

 

Returns

TRUE if connectivity checking is available.

Since: 1.10


nm_client_connectivity_check_get_enabled ()

gboolean
nm_client_connectivity_check_get_enabled
                               (NMClient *client);

Determine whether connectivity checking is enabled.

Parameters

client

a NMClient

 

Returns

TRUE if connectivity checking is enabled.

Since: 1.10


nm_client_connectivity_check_set_enabled ()

void
nm_client_connectivity_check_set_enabled
                               (NMClient *client,
                                gboolean enabled);

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

Use the async command nm_client_dbus_set_property() on NM_DBUS_PATH, NM_DBUS_INTERFACE to set "ConnectivityCheckEnabled" property to a "(b)" value.

Enable or disable connectivity checking. Note that if a connectivity checking URI has not been configured, this will not have any effect.

Parameters

client

a NMClient

 

enabled

TRUE to enable connectivity checking

 

Since: 1.10


nm_client_connectivity_check_get_uri ()

const char *
nm_client_connectivity_check_get_uri (NMClient *client);

Get the URI that will be queried to determine if there is internet connectivity.

Parameters

client

a NMClient

 

Returns

the connectivity URI in use.

[transfer none]

Since: 1.20


nm_client_get_logging ()

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

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

Use the async command nm_client_dbus_call() on NM_DBUS_PATH, NM_DBUS_INTERFACE to call "GetLogging" with no arguments to get "(ss)" for level and domains.

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

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

Use the async command nm_client_dbus_call() on NM_DBUS_PATH, NM_DBUS_INTERFACE to call "SetLogging" with "(ss)" arguments for level and domains.

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_permissions_state ()

NMTernary
nm_client_get_permissions_state (NMClient *self);

Parameters

self

the NMClient instance

 

Returns

the state of the cached permissions. NM_TERNARY_DEFAULT means that no permissions result was yet received. All permissions are unknown. NM_TERNARY_TRUE means that the permissions got received and are cached. %NM_TERNARY_FALSE means that permissions are cached, but they are invalided as "CheckPermissions" signal was received in the meantime.

Since: 1.24


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

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

Use nm_client_check_connectivity_async() or GDBusConnection.

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

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

Use nm_client_save_hostname_async() or GDBusConnection.

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 use 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. If the variant is floating, it will be consumed.

[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_add_and_activate_connection2 ()

void
nm_client_add_and_activate_connection2
                               (NMClient *client,
                                NMConnection *partial,
                                NMDevice *device,
                                const char *specific_object,
                                GVariant *options,
                                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.

This is identical to nm_client_add_and_activate_connection_async() but takes a further options parameter. Currently, the following options are supported by the daemon:

  • "persist": A string describing how the connection should be stored. The default is "disk", but it can be modified to "memory" (until the daemon quits) or "volatile" (will be deleted on disconnect).

  • "bind-activation": Bind the connection lifetime to something. The default is "none", meaning an explicit disconnect is needed. The value "dbus-client" means the connection will automatically be deactivated when the calling D-Bus client disappears from the system bus.

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 (i.e., 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]

options

a GVariant containing a dictionary with options, or NULL

 

cancellable

a GCancellable, or NULL

 

callback

callback to be called when the activation has started

 

user_data

caller-specific data passed to callback

 

Since: 1.16


nm_client_add_and_activate_connection2_finish ()

NMActiveConnection *
nm_client_add_and_activate_connection2_finish
                               (NMClient *client,
                                GAsyncResult *result,
                                GVariant **out_result,
                                GError **error);

Gets the result of a call to nm_client_add_and_activate_connection2().

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

 

out_result

the output result of type "a{sv}" returned by D-Bus' AddAndActivate2 call. Currently, no output is implemented yet.

[allow-none][transfer full]

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

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

Use nm_client_deactivate_connection_async() or GDBusConnection.

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_add_connection2 ()

void
nm_client_add_connection2 (NMClient *client,
                           GVariant *settings,
                           NMSettingsAddConnection2Flags flags,
                           GVariant *args,
                           gboolean ignore_out_result,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Call AddConnection2() D-Bus API asynchronously.

Parameters

client

the NMClient

 

settings

the "a{sa{sv}}" GVariant with the content of the setting.

 

flags

the NMSettingsAddConnection2Flags argument.

 

args

the "a{sv}" GVariant with extra argument or NULL for no extra arguments.

[allow-none]

ignore_out_result

this function wraps AddConnection2(), which has an additional result "a{sv}" output parameter. By setting this to TRUE, you signal that you are not interested in that output parameter. This allows the function to fall back to AddConnection() and AddConnectionUnsaved(), which is interesting if you run against an older server version that does not yet provide AddConnection2(). By setting this to FALSE, the function under the hood always calls AddConnection2().

 

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]

Since: 1.20


nm_client_add_connection2_finish ()

NMRemoteConnection *
nm_client_add_connection2_finish (NMClient *client,
                                  GAsyncResult *result,
                                  GVariant **out_result,
                                  GError **error);

Parameters

client

the NMClient

 

result

the GAsyncResult

 

out_result

the output GVariant from AddConnection2(). If you care about the output result, then the "ignore_out_result" parameter of nm_client_add_connection2() must not be set to TRUE.

[allow-none][transfer full][out]

error

the error argument.

[allow-none]

Returns

on success, a pointer to the added NMRemoteConnection.

[transfer full]

Since: 1.20


nm_client_load_connections ()

gboolean
nm_client_load_connections (NMClient *client,
                            char **filenames,
                            char ***failures,
                            GCancellable *cancellable,
                            GError **error);

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

Use nm_client_load_connections_async() or GDBusConnection.

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 on success.

Warning: before libnm 1.22, the boolean return value was inconsistent. That is made worse, because when running against certain server versions before 1.20, the server would return wrong values for success/failure. This means, if you use this function in libnm before 1.22, you are advised to ignore the boolean return value and only look at failures and error . With libnm >= 1.22, the boolean return value corresponds to whether error was set. Note that even in the success case, you might have individual failures . With 1.22, the return value is consistent with nm_client_load_connections_finish().


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 on success. Note that even in the success case, you might have individual failures .


nm_client_reload_connections ()

gboolean
nm_client_reload_connections (NMClient *client,
                              GCancellable *cancellable,
                              GError **error);

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

Use nm_client_reload_connections_async() or GDBusConnection.

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


nm_client_get_dns_mode ()

const char *
nm_client_get_dns_mode (NMClient *client);

Gets the current DNS processing mode.

Parameters

client

the NMClient

 

Returns

the DNS processing mode, or NULL in case the value is not available.

Since: 1.6


nm_client_get_dns_rc_manager ()

const char *
nm_client_get_dns_rc_manager (NMClient *client);

Gets the current DNS resolv.conf manager.

Parameters

client

the NMClient

 

Returns

the resolv.conf manager or NULL in case the value is not available.

Since: 1.6


nm_client_get_dns_configuration ()

const GPtrArray *
nm_client_get_dns_configuration (NMClient *client);

Gets the current DNS configuration

Parameters

client

a NMClient

 

Returns

a GPtrArray containing NMDnsEntry elements or NULL in case the value is not available. The returned array is owned by the NMClient object and should not be modified.

[transfer none][element-type NMDnsEntry]

Since: 1.6


nm_client_get_checkpoints ()

const GPtrArray *
nm_client_get_checkpoints (NMClient *client);

Gets all the active checkpoints.

Parameters

client

a NMClient

 

Returns

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

[transfer none][element-type NMCheckpoint]

Since: 1.12


nm_client_checkpoint_create ()

void
nm_client_checkpoint_create (NMClient *client,
                             const GPtrArray *devices,
                             guint32 rollback_timeout,
                             NMCheckpointCreateFlags flags,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Creates a checkpoint of the current networking configuration for given interfaces. An empty devices argument means all devices. If rollback_timeout is not zero, a rollback is automatically performed after the given timeout.

Parameters

client

the NMClient

 

devices

a list of devices for which a checkpoint should be created.

[element-type NMDevice]

rollback_timeout

the rollback timeout in seconds

 

flags

creation flags

 

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]

Since: 1.12


nm_client_checkpoint_create_finish ()

NMCheckpoint *
nm_client_checkpoint_create_finish (NMClient *client,
                                    GAsyncResult *result,
                                    GError **error);

Gets the result of a call to nm_client_checkpoint_create().

Parameters

client

the NMClient

 

result

the result passed to the GAsyncReadyCallback

 

error

location for a GError, or NULL

 

Returns

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

[transfer full]

Since: 1.12


nm_client_checkpoint_destroy ()

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

Destroys an existing checkpoint without performing a rollback.

Parameters

client

the NMClient

 

checkpoint_path

the D-Bus path for the checkpoint

 

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]

Since: 1.12


nm_client_checkpoint_destroy_finish ()

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

Gets the result of a call to nm_client_checkpoint_destroy().

Parameters

client

an NMClient

 

result

the result passed to the GAsyncReadyCallback

 

error

location for a GError, or NULL

 

Returns

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

Since: 1.12


nm_client_checkpoint_rollback ()

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

Performs the rollback of a checkpoint before the timeout is reached.

Parameters

client

the NMClient

 

checkpoint_path

the D-Bus path to the checkpoint

 

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]

Since: 1.12


nm_client_checkpoint_rollback_finish ()

GHashTable *
nm_client_checkpoint_rollback_finish (NMClient *client,
                                      GAsyncResult *result,
                                      GError **error);

Gets the result of a call to nm_client_checkpoint_rollback().

Parameters

client

an NMClient

 

result

the result passed to the GAsyncReadyCallback

 

error

location for a GError, or NULL

 

Returns

an hash table of devices and results. Devices are represented by their original D-Bus path; each result is a NMRollbackResult.

[transfer full][element-type utf8 guint32]

Since: 1.12


nm_client_checkpoint_adjust_rollback_timeout ()

void
nm_client_checkpoint_adjust_rollback_timeout
                               (NMClient *client,
                                const char *checkpoint_path,
                                guint32 add_timeout,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Resets the timeout for the checkpoint with path checkpoint_path to timeout_add .

Parameters

client

the NMClient

 

checkpoint_path

a D-Bus path to a checkpoint

 

add_timeout

the timeout in seconds counting from now. Set to zero, to disable the timeout.

 

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]

Since: 1.12


nm_client_checkpoint_adjust_rollback_timeout_finish ()

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

Gets the result of a call to nm_client_checkpoint_adjust_rollback_timeout().

Parameters

client

an NMClient

 

result

the result passed to the GAsyncReadyCallback

 

error

location for a GError, or NULL

 

Returns

TRUE on success or FALSE on failure.

Since: 1.12


nm_client_reload ()

void
nm_client_reload (NMClient *client,
                  NMManagerReloadFlags flags,
                  GCancellable *cancellable,
                  GAsyncReadyCallback callback,
                  gpointer user_data);

Reload NetworkManager's configuration and perform certain updates, like flushing caches or rewriting external state to disk. This is similar to sending SIGHUP to NetworkManager but it allows for more fine-grained control over what to reload (see flags ). It also allows non-root access via PolicyKit and contrary to signals it is synchronous.

Parameters

client

the NMClient

 

flags

flags indicating what to reload.

 

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]

Since: 1.22


nm_client_reload_finish ()

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

Gets the result of a call to nm_client_reload().

Parameters

client

an NMClient

 

result

the result passed to the GAsyncReadyCallback

 

error

location for a GError, or NULL

 

Returns

TRUE on success or FALSE on failure.

Since: 1.22


nm_client_dbus_call ()

void
nm_client_dbus_call (NMClient *client,
                     const char *object_path,
                     const char *interface_name,
                     const char *method_name,
                     GVariant *parameters,
                     const GVariantType *reply_type,
                     int timeout_msec,
                     GCancellable *cancellable,
                     GAsyncReadyCallback callback,
                     gpointer user_data);

Call g_dbus_connection_call() on the current name owner with the specified arguments. Most importantly, this invokes g_dbus_connection_call() with the client's GMainContext, so that the response is always in order with other events D-Bus events. Of course, the call uses GTask and will invoke the callback on the current g_main_context_get_thread_default().

This API is merely a convenient wrapper for g_dbus_connection_call(). You can also use g_dbus_connection_call() directly, with the same effect.

Parameters

client

the NMClient

 

object_path

path of remote object

 

interface_name

D-Bus interface to invoke method on

 

method_name

the name of the method to invoke

 

parameters

a GVariant tuple with parameters for the method or NULL if not passing parameters.

[nullable]

reply_type

the expected type of the reply (which will be a tuple), or NULL.

[nullable]

timeout_msec

the timeout in milliseconds, -1 to use the default timeout or G_MAXINT for no timeout

 

cancellable

a GCancellable or NULL.

[nullable]

callback

a GAsyncReadyCallback to call when the request is satisfied or NULL if you don't care about the result of the method invocation.

[nullable]

user_data

the data to pass to callback

 

Since: 1.24


nm_client_dbus_call_finish ()

GVariant *
nm_client_dbus_call_finish (NMClient *client,
                            GAsyncResult *result,
                            GError **error);

Gets the result of a call to nm_client_dbus_call().

Parameters

client

the NMClient instance

 

result

the result passed to the GAsyncReadyCallback

 

error

location for a GError, or NULL

 

Returns

the result GVariant or NULL on error.

[transfer full]

Since: 1.24


nm_client_dbus_set_property ()

void
nm_client_dbus_set_property (NMClient *client,
                             const char *object_path,
                             const char *interface_name,
                             const char *property_name,
                             GVariant *value,
                             int timeout_msec,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Like nm_client_dbus_call() but calls "Set" on the standard "org.freedesktop.DBus.Properties" D-Bus interface.

Parameters

client

the NMClient

 

object_path

path of remote object

 

interface_name

D-Bus interface for the property to set.

 

property_name

the name of the property to set

 

value

a GVariant with the value to set.

 

timeout_msec

the timeout in milliseconds, -1 to use the default timeout or G_MAXINT for no timeout

 

cancellable

a GCancellable or NULL.

[nullable]

callback

a GAsyncReadyCallback to call when the request is satisfied or NULL if you don't care about the result of the method invocation.

[nullable]

user_data

the data to pass to callback

 

Since: 1.24


nm_client_dbus_set_property_finish ()

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

Gets the result of a call to nm_client_dbus_set_property().

Parameters

client

the NMClient instance

 

result

the result passed to the GAsyncReadyCallback

 

error

location for a GError, or NULL

 

Returns

TRUE on success or FALSE on failure.

Since: 1.24


nm_utils_print ()

void
nm_utils_print (int output_mode,
                const char *msg);

The only purpose of this function is to give access to g_print() or g_printerr() from pygobject. libnm can do debug logging by setting LIBNM_CLIENT_DEBUG and uses thereby g_printerr() or g_print(). A plain "print()" function in python is not in sync with these functions (it implements additional buffering). By using nm_utils_print(), the same logging mechanisms can be used.

Parameters

output_mode

if 1 it uses g_print(). If 2, it uses g_printerr(). If 0, it uses either g_print() or g_printerr(), depending on LIBNM_CLIENT_DEBUG (and the "stdout" flag).

 

msg

the message to print. The function does not append a trailing newline.

 

Since: 1.30

Types and Values

enum NMClientInstanceFlags

Members

NM_CLIENT_INSTANCE_FLAGS_NONE

special value to indicate no flags.

 

NM_CLIENT_INSTANCE_FLAGS_NO_AUTO_FETCH_PERMISSIONS

by default, NMClient will fetch the permissions via "GetPermissions" and refetch them when "CheckPermissions" signal gets received. By setting this flag, this behavior can be disabled. You can toggle this flag to enable and disable automatic fetching of the permissions. Watch also nm_client_get_permissions_state() to know whether the permissions are up to date.

 

Since: 1.24


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_DBUS_CONNECTION

#define NM_CLIENT_DBUS_CONNECTION "dbus-connection"

NM_CLIENT_DBUS_NAME_OWNER

#define NM_CLIENT_DBUS_NAME_OWNER "dbus-name-owner"

NM_CLIENT_INSTANCE_FLAGS

#define NM_CLIENT_INSTANCE_FLAGS  "instance-flags"

NM_CLIENT_NETWORKING_ENABLED

#define NM_CLIENT_NETWORKING_ENABLED "networking-enabled"

NM_CLIENT_NETWORKING_ENABLED is deprecated and should not be used in newly-written code.


NM_CLIENT_WIRELESS_ENABLED

#define NM_CLIENT_WIRELESS_ENABLED "wireless-enabled"

NM_CLIENT_WIRELESS_ENABLED is deprecated and should not be used in newly-written code.


NM_CLIENT_WWAN_ENABLED

#define NM_CLIENT_WWAN_ENABLED "wwan-enabled"

NM_CLIENT_WWAN_ENABLED is deprecated and should not be used in newly-written code.


NM_CLIENT_WIMAX_ENABLED

#define NM_CLIENT_WIMAX_ENABLED "wimax-enabled"

NM_CLIENT_WIMAX_ENABLED is deprecated and should not be used in newly-written code.


NM_CLIENT_WIRELESS_HARDWARE_ENABLED

#define NM_CLIENT_WIRELESS_HARDWARE_ENABLED "wireless-hardware-enabled"

NM_CLIENT_WWAN_HARDWARE_ENABLED

#define NM_CLIENT_WWAN_HARDWARE_ENABLED     "wwan-hardware-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_CONNECTIVITY_CHECK_URI

#define NM_CLIENT_CONNECTIVITY_CHECK_URI       "connectivity-check-uri"

NM_CLIENT_CONNECTIVITY_CHECK_AVAILABLE

#define NM_CLIENT_CONNECTIVITY_CHECK_AVAILABLE "connectivity-check-available"

NM_CLIENT_CONNECTIVITY_CHECK_ENABLED

#define NM_CLIENT_CONNECTIVITY_CHECK_ENABLED "connectivity-check-enabled"

NM_CLIENT_CONNECTIVITY_CHECK_ENABLED is deprecated and should not be used in newly-written code.


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_DNS_MODE

#define NM_CLIENT_DNS_MODE              "dns-mode"

NM_CLIENT_DNS_RC_MANAGER

#define NM_CLIENT_DNS_RC_MANAGER        "dns-rc-manager"

NM_CLIENT_DNS_CONFIGURATION

#define NM_CLIENT_DNS_CONFIGURATION     "dns-configuration"

NM_CLIENT_CHECKPOINTS

#define NM_CLIENT_CHECKPOINTS           "checkpoints"

NM_CLIENT_CAPABILITIES

#define NM_CLIENT_CAPABILITIES          "capabilities"

NM_CLIENT_PERMISSIONS_STATE

#define NM_CLIENT_PERMISSIONS_STATE     "permissions-state"

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"

NM_CLIENT_ACTIVE_CONNECTION_ADDED

#define NM_CLIENT_ACTIVE_CONNECTION_ADDED   "active-connection-added"

NM_CLIENT_ACTIVE_CONNECTION_REMOVED

#define NM_CLIENT_ACTIVE_CONNECTION_REMOVED "active-connection-removed"

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()