NMConnection: libnm-util Reference Manual

- - -

NMConnection

NMConnection — Describes a connection to specific network or provider

Functions

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

-GQuark -	-nm_connection_error_quark () -
-NMConnection * -	-nm_connection_new () -
-NMConnection * -	-nm_connection_new_from_hash () -
-NMConnection * -	-nm_connection_duplicate () -
-NMSetting * -	-nm_connection_create_setting () -
-void -	-nm_connection_add_setting () -
-void -	-nm_connection_remove_setting () -
-NMSetting * -	-nm_connection_get_setting () -
-NMSetting * -	-nm_connection_get_setting_by_name () -
-gboolean -	-nm_connection_replace_settings () -
-gboolean -	-nm_connection_replace_settings_from_connection () -
-gboolean -	-nm_connection_compare () -
-gboolean -	-nm_connection_diff () -
-gboolean -	-nm_connection_verify () -
-gboolean -	-nm_connection_normalize () -
const char * -	-nm_connection_need_secrets () -
-void -	-nm_connection_clear_secrets () -
-void -	-nm_connection_clear_secrets_with_flags () -
-gboolean -	-nm_connection_update_secrets () -
-void -	-nm_connection_set_path () -
const char * -	-nm_connection_get_path () -
const char * -	-nm_connection_get_virtual_iface_name () -
const char * -	-nm_connection_get_interface_name () -
-gboolean -	-nm_connection_is_type () -
-void -	-nm_connection_for_each_setting_value () -
-GHashTable * -	-nm_connection_to_hash () -
-void -	-nm_connection_dump () -
-GType -	-nm_connection_lookup_setting_type () -
-GType -	-nm_connection_lookup_setting_type_by_quark () -
const char * -	-nm_connection_get_uuid () -
const char * -	-nm_connection_get_id () -
const char * -	-nm_connection_get_connection_type () -
-char * -	-nm_connection_get_virtual_device_description () -
-NMSetting8021x * -	-nm_connection_get_setting_802_1x () -
-NMSettingBluetooth * -	-nm_connection_get_setting_bluetooth () -
-NMSettingBond * -	-nm_connection_get_setting_bond () -
-NMSettingTeam * -	-nm_connection_get_setting_team () -
-NMSettingTeamPort * -	-nm_connection_get_setting_team_port () -
-NMSettingBridge * -	-nm_connection_get_setting_bridge () -
-NMSettingBridgePort * -	-nm_connection_get_setting_bridge_port () -
-NMSettingCdma * -	-nm_connection_get_setting_cdma () -
-NMSettingConnection * -	-nm_connection_get_setting_connection () -
-NMSettingDcb * -	-nm_connection_get_setting_dcb () -
-NMSettingGeneric * -	-nm_connection_get_setting_generic () -
-NMSettingGsm * -	-nm_connection_get_setting_gsm () -
-NMSettingInfiniband * -	-nm_connection_get_setting_infiniband () -
-NMSettingIP4Config * -	-nm_connection_get_setting_ip4_config () -
-NMSettingIP6Config * -	-nm_connection_get_setting_ip6_config () -
-NMSettingOlpcMesh * -	-nm_connection_get_setting_olpc_mesh () -
-NMSettingPPP * -	-nm_connection_get_setting_ppp () -
-NMSettingPPPOE * -	-nm_connection_get_setting_pppoe () -
-NMSettingSerial * -	-nm_connection_get_setting_serial () -
-NMSettingVPN * -	-nm_connection_get_setting_vpn () -
-NMSettingWimax * -	-nm_connection_get_setting_wimax () -
-NMSettingAdsl * -	-nm_connection_get_setting_adsl () -
-NMSettingWired * -	-nm_connection_get_setting_wired () -
-NMSettingWireless * -	-nm_connection_get_setting_wireless () -
-NMSettingWirelessSecurity * -	-nm_connection_get_setting_wireless_security () -
-NMSettingVlan * -	-nm_connection_get_setting_vlan () -

Properties

----- - - - - - -

-gchar *

path

Read / Write / Construct

Signals

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

void	changed	Run First
void	secrets-cleared	Run First
void	secrets-updated	Run First

Types and Values

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

#define	NM_CONNECTION_SECRETS_UPDATED
#define	NM_CONNECTION_SECRETS_CLEARED
#define	NM_CONNECTION_CHANGED
#define	NM_CONNECTION_PATH
enum	NMConnectionError
#define	NM_CONNECTION_NORMALIZE_PARAM_IP6_CONFIG_METHOD
#define	NM_CONNECTION_ERROR
	NMConnection

Object Hierarchy

    GEnum
-    ╰── NMConnectionError
-    GObject
-    ╰── NMConnection
-

Includes

#include <nm-connection.h>
-

Description

An NMConnection describes all the settings and configuration values that -are necessary to configure network devices for operation on a specific -network. Connections are the fundamental operating object for -NetworkManager; no device is connected without a NMConnection, or -disconnected without having been connected with a NMConnection.

Each NMConnection contains a list of NMSetting objects usually referenced -by name (using nm_connection_get_setting_by_name()) or by type (with -nm_connection_get_setting()). The settings describe the actual parameters -with which the network devices are configured, including device-specific -parameters (MTU, SSID, APN, channel, rate, etc) and IP-level parameters -(addresses, routes, addressing methods, etc).

Functions

nm_connection_error_quark ()

GQuark
-nm_connection_error_quark (void);

Registers an error quark for NMConnection if necessary.

Returns

the error quark used for NMConnection errors.

nm_connection_new ()

NMConnection *
-nm_connection_new (void);

Creates a new NMConnection object with no NMSetting objects.

Returns

the new empty NMConnection object

nm_connection_new_from_hash ()

NMConnection *
-nm_connection_new_from_hash (GHashTable *hash,
-                             GError **error);

Creates a new NMConnection from a hash table describing the connection. See -nm_connection_to_hash() for a description of the expected hash table.

Parameters

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

hash	the GHashTable describing -the connection.	[element-type utf8 GLib.HashTable]
error	on unsuccessful return, an error

Returns

the new NMConnection object, populated with settings created -from the values in the hash table, or NULL if the connection failed to -validate

nm_connection_duplicate ()

NMConnection *
-nm_connection_duplicate (NMConnection *connection);

Duplicates a NMConnection.

Parameters

----- - - - - - -

connection

the NMConnection to duplicate

Returns

a new NMConnection containing the same settings and properties -as the source NMConnection.

[transfer full]

nm_connection_create_setting ()

NMSetting *
-nm_connection_create_setting (const char *name);

Create a new NMSetting object of the desired type, given a setting name.

Parameters

----- - - - - - -

name

a setting name

Returns

the new setting object, or NULL if the setting name was unknown.

[transfer full]

nm_connection_add_setting ()

void
-nm_connection_add_setting (NMConnection *connection,
-                           NMSetting *setting);

Adds a NMSetting to the connection, replacing any previous NMSetting of the -same name which has previously been added to the NMConnection. The -connection takes ownership of the NMSetting object and does not increase -the setting object's reference count.

Parameters

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

connection	a NMConnection
setting	the NMSetting to add to the connection object.	[transfer full]

nm_connection_remove_setting ()

void
-nm_connection_remove_setting (NMConnection *connection,
-                              GType setting_type);

Removes the NMSetting with the given GType from the NMConnection. This -operation dereferences the NMSetting object.

Parameters

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

connection	a NMConnection
setting_type	the GType of the setting object to remove

nm_connection_get_setting ()

NMSetting *
-nm_connection_get_setting (NMConnection *connection,
-                           GType setting_type);

Gets the NMSetting with the given GType, if one has been previously added -to the NMConnection.

Parameters

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

connection	a NMConnection
setting_type	the GType of the setting object to return

Returns

the NMSetting, or NULL if no setting of that type was previously -added to the NMConnection.

[transfer none]

nm_connection_get_setting_by_name ()

NMSetting *
-nm_connection_get_setting_by_name (NMConnection *connection,
-                                   const char *name);

Gets the NMSetting with the given name, if one has been previously added -the NMConnection.

Parameters

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

connection	a NMConnection
name	a setting name

Returns

the NMSetting, or NULL if no setting with that name was previously -added to the NMConnection.

[transfer none]

nm_connection_replace_settings ()

gboolean
-nm_connection_replace_settings (NMConnection *connection,
-                                GHashTable *new_settings,
-                                GError **error);

Parameters

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

connection	a NMConnection
new_settings	a GHashTable of settings.	[element-type utf8 GLib.HashTable]
error	location to store error, or `NULL`

Returns

TRUE if the settings were valid and added to the connection, FALSE -if they were not

nm_connection_replace_settings_from_connection ()

gboolean
-nm_connection_replace_settings_from_connection
-                               (NMConnection *connection,
-                                NMConnection *new_connection,
-                                GError **error);

Deep-copies the settings of new_conenction - and replaces the settings of connection - -with the copied settings.

Parameters

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

connection	a NMConnection
new_connection	a NMConnection to replace the settings of `connection` -with
error	location to store error, or `NULL`

Returns

TRUE if the settings were valid after replacing the connection, FALSE -if they were not. Regardless of whether TRUE or FALSE is returned, the connection -is successfully replaced. FALSE only means, that the connection does not verify -at the end of the operation.

Since: 0.9.10

nm_connection_compare ()

gboolean
-nm_connection_compare (NMConnection *a,
-                       NMConnection *b,
-                       NMSettingCompareFlags flags);

Compares two NMConnection objects for similarity, with comparison behavior -modified by a set of flags. See nm_setting_compare() for a description of -each flag's behavior.

Parameters

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

a	a NMConnection
b	a second NMConnection to compare with the first
flags	compare flags, e.g. `NM_SETTING_COMPARE_FLAG_EXACT`

Returns

TRUE if the comparison succeeds, FALSE if it does not

nm_connection_diff ()

gboolean
-nm_connection_diff (NMConnection *a,
-                    NMConnection *b,
-                    NMSettingCompareFlags flags,
-                    GHashTable **out_settings);

Compares two NMConnection objects for similarity, with comparison behavior -modified by a set of flags. See nm_setting_compare() for a description of -each flag's behavior. If the connections differ, settings and keys within -each setting that differ are added to the returned out_settings - hash table. -No values are returned, only key names.

Parameters

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

a	a NMConnection
b	a second NMConnection to compare with the first
flags	compare flags, e.g. `NM_SETTING_COMPARE_FLAG_EXACT`
out_settings	if the -connections differ, on return a hash table mapping setting names to -second-level GHashTable (utf8 to guint32), which contains the key names that -differ mapped to one or more of `NMSettingDiffResult` as a bitfield.	[element-type utf8 GLib.HashTable]

Returns

TRUE if the connections contain the same values, FALSE if they do -not

nm_connection_verify ()

gboolean
-nm_connection_verify (NMConnection *connection,
-                      GError **error);

Validates the connection and all its settings. Each setting's properties -have allowed values, and some values are dependent on other values. For -example, if a Wi-Fi connection is security enabled, the NMSettingWireless -setting object's 'security' property must contain the setting name of the -NMSettingWirelessSecurity object, which must also be present in the -connection for the connection to be valid. As another example, the -NMSettingWired object's 'mac-address' property must be a validly formatted -MAC address. The returned GError contains information about which -setting and which property failed validation, and how it failed validation.

Parameters

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

connection	the NMConnection to verify
error	location to store error, or `NULL`

Returns

TRUE if the connection is valid, FALSE if it is not

nm_connection_normalize ()

gboolean
-nm_connection_normalize (NMConnection *connection,
-                         GHashTable *parameters,
-                         gboolean *modified,
-                         GError **error);

Does some basic normalization and fixup of well known inconsistencies -and deprecated fields. If the connection was modified in any way, -the output parameter modified - is set TRUE.

Finally the connection will be verified and TRUE returns if the connection -is valid. As this function only performs some specific normalization steps -it cannot repair all connections. If the connection has errors that -cannot be normalized, the connection will not be modified.

Parameters

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

connection	the NMConnection to normalize
parameters	a GHashTable with -normalization parameters to allow customization of the normalization by providing -specific arguments. Unknown arguments will be ignored and the default will be -used. The keys must be strings, hashed by `g_str_hash()` and `g_str_equal()` functions. -The values are opaque and depend on the parameter name.	[allow-none][element-type utf8 gpointer]
modified	outputs whether any settings were modified.	[out][allow-none]
error	location to store error, or `NULL`. Contains the reason, -why the connection is invalid, if the function returns an error.

Returns

TRUE if the connection is valid, FALSE if it is not

Since: 1.0

nm_connection_need_secrets ()

const char *
-nm_connection_need_secrets (NMConnection *connection,
-                            GPtrArray **hints);

Returns the name of the first setting object in the connection which would -need secrets to make a successful connection. The returned hints are only -intended as a guide to what secrets may be required, because in some -circumstances, there is no way to conclusively determine exactly which -secrets are needed.

Parameters

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

connection	the NMConnection
hints	the address of a pointer to a GPtrArray, initialized to `NULL`, which on -return points to an allocated GPtrArray containing the property names of -secrets of the NMSetting which may be required; the caller owns the array -and must free the array itself with `g_ptr_array_free()`, but not free its -elements.	[out][element-type utf8][allow-none][transfer container]

Returns

the setting name of the NMSetting object which has invalid or -missing secrets

nm_connection_clear_secrets ()

void
-nm_connection_clear_secrets (NMConnection *connection);

Clears and frees any secrets that may be stored in the connection, to avoid -keeping secret data in memory when not needed.

Parameters

----- - - - - - -

connection

connection	the NMConnection
func	function to be called to determine whether a -specific secret should be cleared or not.	[scope call]
user_data	caller-supplied data passed to `func` -

connection	the NMConnection
setting_name	the setting object name to which the secrets apply
secrets	a GHashTable mapping -string:GValue of setting property names and secrets of the given `setting_name` -.	[element-type utf8 GObject.Value]
error	location to store error, or `NULL`

connection	the NMConnection
type	a setting name to check the connection's type against (like -`NM_SETTING_WIRELESS_SETTING_NAME` or `NM_SETTING_WIRED_SETTING_NAME`)

NM_CONNECTION_ERROR_UNKNOWN	- unknown or unclassified error -
NM_CONNECTION_ERROR_CONNECTION_SETTING_NOT_FOUND	- the NMConnection object - did not contain the required NMSettingConnection object, which must be - present for all connections -
NM_CONNECTION_ERROR_CONNECTION_TYPE_INVALID	- the 'type' property of the - 'connection' setting did not point to a valid connection base type; ie - it was not a hardware-related setting like NMSettingWired or - NMSettingWireless. -
NM_CONNECTION_ERROR_SETTING_NOT_FOUND	- the NMConnection object - did not contain the specified NMSetting object -
NM_CONNECTION_ERROR_INVALID_SETTING	- the NMConnection object contains - a conflicting setting object -

connection	the object on which the signal is emitted
user_data	user data set when the signal handler was connected.

NMConnection

Functions

Properties

Signals

Types and Values

Object Hierarchy

Includes

Description

Functions

nm_connection_error_quark ()

Returns

nm_connection_new ()

Returns

nm_connection_new_from_hash ()

Parameters

Returns

nm_connection_duplicate ()

Parameters

Returns

nm_connection_create_setting ()

Parameters

Returns

nm_connection_add_setting ()

Parameters

nm_connection_remove_setting ()

Parameters

nm_connection_get_setting ()

Parameters

Returns

nm_connection_get_setting_by_name ()

Parameters

Returns

nm_connection_replace_settings ()

Parameters

Returns

nm_connection_replace_settings_from_connection ()

Parameters

Returns

nm_connection_compare ()

Parameters

Returns

nm_connection_diff ()

Parameters

Returns

nm_connection_verify ()

Parameters

Returns

nm_connection_normalize ()

Parameters

Returns

nm_connection_need_secrets ()

Parameters

Returns

nm_connection_clear_secrets ()

Parameters

nm_connection_clear_secrets_with_flags ()

Parameters

nm_connection_update_secrets ()

Parameters

Returns

nm_connection_set_path ()

Parameters

nm_connection_get_path ()

Parameters

Returns

nm_connection_get_virtual_iface_name ()

Parameters

Returns

nm_connection_get_interface_name ()

Parameters

Returns

nm_connection_is_type ()

Parameters

Returns

nm_connection_for_each_setting_value ()

Parameters

nm_connection_to_hash ()

Parameters

Returns

nm_connection_dump ()