NMClient: libnm Reference Manual

- - -

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 () -
const guint32 * -	-nm_client_get_version_info () -
-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 () -
-NMRadioFlags -	-nm_client_get_radio_flags () -
-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 () -
-gboolean -	-nm_utils_file_is_certificate () -
-gboolean -	-nm_utils_file_is_private_key () -
-gboolean -	-nm_utils_file_is_pkcs12 () -
-void -	-nm_client_wait_shutdown () -
-gboolean -	-nm_client_wait_shutdown_finish () -

Properties

-NMActiveConnection *	activating-connection	Read
-GPtrArray *	active-connections	Read
-GPtrArray *	all-devices	Read
gboolean	can-modify	Read
-GArray *	capabilities	Read
-GPtrArray *	checkpoints	Read
-GPtrArray *	connections	Read
NMConnectivityState	connectivity	Read
gboolean	connectivity-check-available	Read
gboolean	connectivity-check-enabled	Read / Write
-char *	connectivity-check-uri	Read
-GDBusConnection *	dbus-connection	Read / Write / Construct Only
-char *	dbus-name-owner	Read
-GPtrArray *	devices	Read
-GPtrArray *	dns-configuration	Read
-char *	dns-mode	Read
-char *	dns-rc-manager	Read
-char *	hostname	Read
guint	instance-flags	Read / Write / Construct
guint	metered	Read
gboolean	networking-enabled	Read / Write
gboolean	nm-running	Read
NMTernary	permissions-state	Read
-NMActiveConnection *	primary-connection	Read
guint	radio-flags	Read
gboolean	startup	Read
NMState	state	Read
-char *	version	Read
-GArray *	version-info	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	active-connection-added	Run First
void	active-connection-removed	Run First
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

enum	NMClientInstanceFlags
#define	NM_CLIENT_VERSION
#define	NM_CLIENT_VERSION_INFO
#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_RADIO_FLAGS
#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
	NMClient
	NMDnsEntry

Object Hierarchy

    GBoxed
-    ╰── NMDnsEntry
-    GEnum
-    ╰── NMClientError
-    GFlags
-    ╰── NMClientInstanceFlags
-    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_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_version_info ()

const guint32 *
-nm_client_get_version_info (NMClient *client,
-                            gsize *length);

If available, the first element in the array is NM_VERSION which -encodes the daemon version as "(major << 16 | minor << 8 | micro)". -The following elements are a bitfield of NMVersionInfoCapabilities -that indicate that the daemon supports a certain capability.

Parameters

----- - - - - - - - - - - - - -

client	the NMClient instance
length	the number of returned capabilities.	[out]

Returns

the -list of capabilities reported by the server or NULL -if the capabilities are unknown.

[transfer none][array length=length]

Since: 1.42

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][optional]

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`

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

NMRadioFlags
-nm_client_get_radio_flags (NMClient *client);

Get radio flags.

Parameters

----- - - - - - -

client

a NMClient

Returns

the NMRadioFlags.

Since: 1.38

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.	[out][optional][nullable]
domains	return location for log domains string. The string is -a list of domains separated by ",".	[out][optional][nullable]
error	return location for a GError, or `NULL`

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).	[nullable]
domains	logging domains to set. The string should be a list of log -domains separated by ",". (`NULL` or an empty string for no change).	[nullable]
error	return location for a GError, or `NULL`

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.	[nullable]
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.	[nullable]
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.	[nullable]
device	the NMDevice.	[nullable]
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.	[nullable]
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.	[nullable]
device	the NMDevice.	[nullable]
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.	[nullable]
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);

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.	[nullable]
device	the NMDevice.	[nullable]
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.	[nullable]
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.	[out][optional][nullable][transfer full]

Returns

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

[transfer full]

Since: 1.16

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.	[nullable]
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`.	[out][optional][nullable][transfer full]
error	the error argument.

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.

LIBNM_CLIENT_DEBUG is a list of keywords separated by commas. The keyword -"trace" enables printing messages of the lowest up to the highest severity. -Likewise, the severities "debug", "warn" ("warning") and "error" are honored -in similar way. Setting the flags "ERROR" or "WARN" ("WARNING") implies that -respective levels are enabled, but also are ERROR messages printed with -g_critical() and WARN messages with g_warning(). Together with G_DEBUG="fatal-warnings" -or G_DEBUG="fatal-critical" this can be used to abort the program on errors. -Note that all <error> messages imply an unexpected data on the D-Bus API -(due to a bug). <warn> also implies unexepected data, but that can happen -when using different versions of libnm and daemon. For testing, it is -good to turn these into assertions.

By default, messages are printed to stderr, unless LIBNM_CLIENT_DEBUG -contains "stdout" flag. Also, libnm honors LIBNM_CLIENT_DEBUG_FILE -environment. If this is set to a filename pattern (accepting "%p" for the -process ID), then the debug log is written to that file instead of -stderr/stdout. With output_mode - zero, the same location will be written.

LIBNM_CLIENT_DEBUG_FILE is supported since 1.44. "ERROR", "WARN" and "WARNING" -are supported since 1.46.

Parameters

----- - - - - - - - - - - - - -

output_mode	if 1 it uses `g_print()`. If 2, it uses `g_printerr()`. -If 0, it uses the same output as internal libnm debug logging -does. That is, depending on LIBNM_CLIENT_DEBUG's "stdout" flag -it uses `g_print()` or `g_printerr()` and if LIBNM_CLIENT_DEBUG_FILE is -set, it writes the output to file instead
msg	the message to print. The function does not append -a trailing newline.

Since: 1.30

nm_utils_file_is_certificate ()

gboolean
-nm_utils_file_is_certificate (const char *filename);

Tests if filename - has a valid extension for an X.509 certificate file -(".cer", ".crt", ".der", or ".pem"), and contains a certificate in a format -recognized by NetworkManager.

Parameters

----- - - - - - -

filename

name of the file to test

Returns

TRUE if the file is a certificate, FALSE if it is not

nm_utils_file_is_private_key ()

gboolean
-nm_utils_file_is_private_key (const char *filename,
-                              gboolean *out_encrypted);

Tests if filename - has a valid extension for an X.509 private key file -(".der", ".key", ".pem", or ".p12"), and contains a private key in a format -recognized by NetworkManager.

Parameters

----- - - - - - - - - - - - - -

filename	name of the file to test
out_encrypted	on return, whether the file is encrypted.	[out]

Returns

TRUE if the file is a private key, FALSE if it is not

nm_utils_file_is_pkcs12 ()

gboolean
-nm_utils_file_is_pkcs12 (const char *filename);

Tests if filename - is a PKCS#12 file.

Parameters

----- - - - - - -

filename

name of the file to test

Returns

TRUE if the file is PKCS#12, FALSE if it is not

nm_client_wait_shutdown ()

void
-nm_client_wait_shutdown (NMClient *client,
-                         gboolean integrate_maincontext,
-                         GCancellable *cancellable,
-                         GAsyncReadyCallback callback,
-                         gpointer user_data);

The way to stop NMClient is by unrefing it. That will cancel all -internally pending async operations. However, as async operations in -NMClient use GTask, hence they cannot complete right away. Instead, -their (internal) result callback still needs to be dispatched by iterating -the client's main context.

You thus cannot stop iterating the client's main context until -everything is wrapped up. nm_client_get_context_busy_watcher() -helps to watch how long that will be.

This function automates that waiting. Like all glib async operations -this honors the current g_main_context_get_thread_default().

In any case, to complete the shutdown, nm_client_get_main_context() -must be iterated. If the current g_main_context_get_thread_default() is -the same as nm_client_get_main_context(), then integrate_maincontext - -is ignored. In that case, the caller is required to iterate the context -for shutdown to complete. Otherwise, if g_main_context_get_thread_default() -differs from nm_client_get_main_context() and integrate_maincontext - -is FALSE, the caller must make sure that both contexts are iterated -until completion. Otherwise, if integrate_maincontext - is TRUE, then -nm_client_get_main_context() will be integrated in g_main_context_get_thread_default(). -This means, the caller gives nm_client_get_main_context() up until the waiting -completes, the function will acquire the context and hook it into -g_main_context_get_thread_default(). -It is a bug to request integrate_maincontext - while having nm_client_get_main_context() -acquired or iterated otherwise because a context can only be acquired once -at a time.

Shutdown can only complete after all references to client - were released.

It is possible to call this function multiple times for the same client. -But note that with integrate_maincontext - the client's context is acquired, -which can only be done once at a time.

It is permissible to start waiting before the objects is fully initialized.

The function really allows two separate things. To get a notification (callback) when -shutdown is complete, and to integrate the client's context in another context. -The latter case is useful if the client has a separate context and you hand it -over to another GMainContext to wrap up.

The main use is to have a NMClient and a separate GMainContext on a worker -thread. When being done, you can hand over the cleanup of the context -to g_main_context_default(), assuming that the main thread iterates -the default context. In that case, you don't need to care about passing -a callback to know when shutdown completed.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

client	the NMClient to shutdown.
integrate_maincontext	whether to hook the client's maincontext -in the current thread default. Otherwise, you must ensure -that the client's maincontext gets iterated so that it can complete. -By integrating the maincontext in the current thread default, you -may instead only iterate the latter.
cancellable	the GCancellable to abort the shutdown.
callback	a GAsyncReadyCallback to call when the request -is satisfied or `NULL` if you don't care about the result of the -method invocation.
user_data	the data to pass to `callback` -

Since: 1.42

nm_client_wait_shutdown_finish ()

gboolean
-nm_client_wait_shutdown_finish (GAsyncResult *result,
-                                GError **error);

Parameters

----- - - - - - - - - - - - - -

result	a GAsyncResult obtained from the GAsyncReadyCallback passed to `nm_client_wait_shutdown()`
error	return location for error or `NULL`

Returns

TRUE if waiting is complete successfully. In that case, all resources of the -nmclient are wrapped up and released. This can only fail by user cancellation.

Since: 1.42

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. -
NM_CLIENT_INSTANCE_FLAGS_INITIALIZED_GOOD	- as NMClient is an GInitable -and GAsyncInitable, `nm_client_get_instance_flags()` returns this flag -once initialization completed with success. This flag cannot be set -as NM_CLIENT_INSTANCE_FLAGS property. Since: 1.42. -
NM_CLIENT_INSTANCE_FLAGS_INITIALIZED_BAD	- like `NM_CLIENT_INSTANCE_FLAGS_INITIALIZED_GOOD` - -indicates that the instance completed initialization with failure. In that -case the instance is unusable. Since: 1.42. -

Since: 1.24

NM_CLIENT_VERSION

#define NM_CLIENT_VERSION         "version"
-

NM_CLIENT_VERSION_INFO

#define NM_CLIENT_VERSION_INFO    "version-info"
-

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_RADIO_FLAGS

#define NM_CLIENT_RADIO_FLAGS "radio-flags"
-

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

NMClient

typedef struct _NMClient NMClient;

NMClient contains a cache of the objects of NetworkManager's D-Bus API. -It uses GMainContext and GDBusConnection for that and registers to -D-Bus signals. That means, when iterating the associated GMainContext, -D-Bus signals gets processed and the NMClient instance updates and -emits GObject signals.

NMDnsEntry

typedef struct _NMDnsEntry NMDnsEntry;

Since: 1.6

Property Details

The `“activating-connection”` property

  “activating-connection”    NMActiveConnection *

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

Owner: NMClient

Flags: Read

The `“active-connections”` property

  “active-connections”       GPtrArray *

The active connections.

[type GPtrArray(NMActiveConnection)]

Owner: NMClient

Flags: Read

The `“all-devices”` property

  “all-devices”              GPtrArray *

List of both real devices and device placeholders.

[type GPtrArray(NMDevice)]

Owner: NMClient

Flags: Read

Since: 1.2

The `“can-modify”` property

  “can-modify”               gboolean

If TRUE, adding and modifying connections is supported.

Owner: NMClient

Flags: Read

Default value: FALSE

The `“capabilities”` property

  “capabilities”             GArray *

The list of capabilities numbers as guint32 or NULL if -there are no capabilities. The numeric value correspond -to NMCapability enum.

[type GArray(guint32)]

Owner: NMClient

Flags: Read

Since: 1.24

The `“checkpoints”` property

  “checkpoints”              GPtrArray *

The list of active checkpoints.

[type GPtrArray(NMCheckpoint)]

Owner: NMClient

Flags: Read

Since: 1.12

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

[type GPtrArray(NMRemoteConnection)]

Owner: NMClient

Flags: Read

The `“connectivity”` property

  “connectivity”             NMConnectivityState

The network connectivity state.

Owner: NMClient

Flags: Read

Default value: NM_CONNECTIVITY_UNKNOWN

The `“connectivity-check-available”` property

  “connectivity-check-available” gboolean

Owner: NMClient

Flags: Read

Default value: FALSE

The `“connectivity-check-enabled”` property

  “connectivity-check-enabled” gboolean

Owner: NMClient

Flags: Read / Write

Default value: FALSE

The `“connectivity-check-uri”` property

  “connectivity-check-uri”   char *

The used URI for connectivity checking.

Owner: NMClient

Flags: Read

Default value: NULL

Since: 1.22

The `“dbus-connection”` property

  “dbus-connection”          GDBusConnection *

The GDBusConnection to use.

If this is not set during object construction, the D-Bus connection will -automatically be chosen during async/sync initalization via g_bus_get().

Owner: NMClient

Flags: Read / Write / Construct Only

Since: 1.22

The `“dbus-name-owner”` property

  “dbus-name-owner”          char *

The name owner of the NetworkManager D-Bus service.

Owner: NMClient

Flags: Read

Default value: NULL

Since: 1.22

The `“devices”` property

  “devices”                  GPtrArray *

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

[type GPtrArray(NMDevice)]

Owner: NMClient

Flags: Read

The `“dns-configuration”` property

  “dns-configuration”        GPtrArray *

The current DNS configuration, represented as an array -of NMDnsEntry objects.

[type GPtrArray(NMDnsEntry)]

Owner: NMClient

Flags: Read

Since: 1.6

The `“dns-mode”` property

  “dns-mode”                 char *

The current DNS processing mode.

Owner: NMClient

Flags: Read

Default value: NULL

Since: 1.6

The `“dns-rc-manager”` property

  “dns-rc-manager”           char *

The current resolv.conf management mode.

Owner: NMClient

Flags: Read

Default value: NULL

Since: 1.6

The `“hostname”` property

  “hostname”                 char *

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

Owner: NMClient

Flags: Read

Default value: NULL

The `“instance-flags”` property

  “instance-flags”           guint

NMClientInstanceFlags for the instance. These affect behavior of NMClient. -This is a construct property and you may only set most flags only during -construction.

The flag NM_CLIENT_INSTANCE_FLAGS_NO_AUTO_FETCH_PERMISSIONS can be toggled any time, -even after constructing the instance. Note that you may want to watch NMClient:permissions-state -property to know whether permissions are ready. Note that permissions are only fetched -when NMClient has a D-Bus name owner.

The flags NM_CLIENT_INSTANCE_FLAGS_INITIALIZED_GOOD and NM_CLIENT_INSTANCE_FLAGS_INITIALIZED_BAD -cannot be set, however they will be returned by the getter after initialization completes.

Owner: NMClient

Flags: Read / Write / Construct

Default value: 0

Since: 1.24

The `“metered”` property

  “metered”                  guint

Whether the connectivity is metered.

Owner: NMClient

Flags: Read

Default value: 0

Since: 1.2

The `“networking-enabled”` property

  “networking-enabled”       gboolean

Whether networking is enabled.

The property setter is a synchronous D-Bus call. This is deprecated since 1.22.

Owner: NMClient

Flags: Read / Write

Default value: FALSE

The `“nm-running”` property

  “nm-running”               gboolean

Whether the daemon is running.

Owner: NMClient

Flags: Read

Default value: FALSE

The `“permissions-state”` property

  “permissions-state”        NMTernary

The state of the cached permissions. The value NM_TERNARY_DEFAULT -means that no permissions are yet received (or not yet requested). -NM_TERNARY_TRUE means that permissions are received, cached and up -to date. NM_TERNARY_FALSE means that permissions were received and are -cached, but in the meantime a "CheckPermissions" signal was received -that invalidated the cached permissions. -Note that NMClient will always emit a notify::permissions-state signal -when a "CheckPermissions" signal got received or after new permissions -got received (that is regardless whether the value of the permission state -actually changed). With this you can watch the permissions-state property -to know whether the permissions are ready. Note that while NMClient has -no D-Bus name owner, no permissions are fetched (and this property won't -change).

Owner: NMClient

Flags: Read

Default value: NM_TERNARY_DEFAULT

Since: 1.24

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.

Owner: NMClient

Flags: Read

The `“radio-flags”` property

  “radio-flags”              guint

Flags for radio interfaces. See NMRadioFlags.

Owner: NMClient

Flags: Read

Default value: 0

Since: 1.38

The `“startup”` property

  “startup”                  gboolean

Whether the daemon is still starting up.

Owner: NMClient

Flags: Read

Default value: FALSE

The `“state”` property

  “state”                    NMState

The current daemon state.

Owner: NMClient

Flags: Read

Default value: NM_STATE_UNKNOWN

The `“version”` property

  “version”                  char *

The NetworkManager version.

Owner: NMClient

Flags: Read

Default value: NULL

The `“version-info”` property

  “version-info”             GArray *

Expose version info and capabilities of NetworkManager. If non-empty, -the first element is NM_VERSION, which encodes the version of the -daemon as "(major << 16 | minor << 8 | micro)". The following elements -is a bitfields of NMVersionInfoCapabilities. If a bit is set, then -the running NetworkManager has the respective capability.

[type GArray(guint32)]

Owner: NMClient

Flags: Read

Since: 1.42

The `“wimax-enabled”` property

  “wimax-enabled”            gboolean

Whether WiMAX functionality is enabled.

NMClient:wimax-enabled has been deprecated since version 1.22 and should not be used in newly-written code.

WiMAX is no longer supported and this always returns FALSE. The setter has no effect.

Owner: NMClient

Flags: Read / Write

Default value: FALSE

The `“wimax-hardware-enabled”` property

  “wimax-hardware-enabled”   gboolean

Whether the WiMAX hardware is enabled.

NMClient:wimax-hardware-enabled has been deprecated since version 1.22 and should not be used in newly-written code.

WiMAX is no longer supported and this always returns FALSE.

Owner: NMClient

Flags: Read

Default value: FALSE

The `“wireless-enabled”` property

  “wireless-enabled”         gboolean

Whether wireless is enabled.

The property setter is a synchronous D-Bus call. This is deprecated since 1.22.

Owner: NMClient

Flags: Read / Write

Default value: FALSE

The `“wireless-hardware-enabled”` property

  “wireless-hardware-enabled” gboolean

Whether the wireless hardware is enabled.

Owner: NMClient

Flags: Read

Default value: FALSE

The `“wwan-enabled”` property

  “wwan-enabled”             gboolean

Whether WWAN functionality is enabled.

The property setter is a synchronous D-Bus call. This is deprecated since 1.22.

Owner: NMClient

Flags: Read / Write

Default value: FALSE

The `“wwan-hardware-enabled”` property

  “wwan-hardware-enabled”    gboolean

Whether the WWAN hardware is enabled.

Owner: NMClient

Flags: Read

Default value: FALSE

Signal Details

The `“active-connection-added”` signal

void
-user_function (NMClient           *client,
-               NMActiveConnection *active_connection,
-               gpointer            user_data)

Notifies that a NMActiveConnection has been added.

Parameters

----- - - - - - - - - - - - - - - - - - -

client	the client that received the signal
active_connection	the new active connection
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“active-connection-removed”` signal

void
-user_function (NMClient           *client,
-               NMActiveConnection *active_connection,
-               gpointer            user_data)

Notifies that a NMActiveConnection has been removed.

Parameters

----- - - - - - - - - - - - - - - - - - -

client	the client that received the signal
active_connection	the removed active connection
user_data	user data set when the signal handler was connected.

Flags: Run First

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 client 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 client 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