NMConnection: libnm Reference Manual

- - -

NMConnection

NMConnection — Describes a connection to specific network or provider

Functions

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

-void -	-nm_connection_add_setting () -
-void -	-nm_connection_remove_setting () -
-NMSetting * -	-nm_connection_get_setting () -
-NMSetting * -	-nm_connection_get_setting_by_name () -
-GVariant * -	-nm_connection_to_dbus () -
-gboolean -	-nm_connection_replace_settings () -
-void -	-nm_connection_replace_settings_from_connection () -
-void -	-nm_connection_clear_settings () -
-gboolean -	-nm_connection_compare () -
-gboolean -	-nm_connection_diff () -
-gboolean -	-nm_connection_verify () -
-gboolean -	-nm_connection_verify_secrets () -
-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_interface_name () -
-gboolean -	-nm_connection_is_type () -
-void -	-nm_connection_for_each_setting_value () -
-void -	-nm_connection_dump () -
const char * -	-nm_connection_get_uuid () -
const char * -	-nm_connection_get_id () -
const char * -	-nm_connection_get_connection_type () -
-gboolean -	-nm_connection_is_virtual () -
-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 () -
-NMSettingIPTunnel * -	-nm_connection_get_setting_ip_tunnel () -
-NMSettingIPConfig * -	-nm_connection_get_setting_ip4_config () -
-NMSettingIPConfig * -	-nm_connection_get_setting_ip6_config () -
-NMSettingMacvlan * -	-nm_connection_get_setting_macvlan () -
-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 () -
-NMSettingTun * -	-nm_connection_get_setting_tun () -
-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 () -
-NMSettingVxlan * -	-nm_connection_get_setting_vxlan () -

Types and Values

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

#define	NM_CONNECTION_SECRETS_UPDATED
#define	NM_CONNECTION_SECRETS_CLEARED
#define	NM_CONNECTION_CHANGED
#define	NM_CONNECTION_NORMALIZE_PARAM_IP6_CONFIG_METHOD
	NMConnectionInterface
#define	NM_VARIANT_TYPE_SETTING
enum	NMConnectionSerializationFlags

Object Hierarchy

    GFlags
-    ╰── NMConnectionSerializationFlags
-

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

GVariant *
-nm_connection_to_dbus (NMConnection *connection,
-                       NMConnectionSerializationFlags flags);

Converts the NMConnection into a GVariant of type -NM_VARIANT_TYPE_CONNECTION describing the connection, suitable for -marshalling over D-Bus or otherwise serializing.

Parameters

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

connection	the NMConnection
flags	serialization flags, e.g. `NM_CONNECTION_SERIALIZE_ALL`

Returns

a new floating GVariant describing the connection, -its settings, and each setting's properties.

[transfer none]

nm_connection_replace_settings ()

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

Replaces connection -'s settings with new_settings - (which must be -syntactically valid, and describe a known type of connection, but does not -need to result in a connection that passes nm_connection_verify()).

Parameters

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

connection	a NMConnection
new_settings	a GVariant of type `NM_VARIANT_TYPE_CONNECTION`, with the new settings
error	location to store error, or `NULL`

Returns

TRUE if connection was updated, FALSE if new_settings -could not -be deserialized (in which case connection -will be unchanged).

nm_connection_replace_settings_from_connection ()

void
-nm_connection_replace_settings_from_connection
-                               (NMConnection *connection,
-                                NMConnection *new_connection);

Deep-copies the settings of new_connection - 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

nm_connection_clear_settings ()

void
-nm_connection_clear_settings (NMConnection *connection);

Deletes all of connection -'s settings.

Parameters

----- - - - - - -

connection

a NMConnection

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

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

Verifies the secrets in the connection.

Parameters

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

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

Returns

TRUE if the secrets are valid, FALSE if they are not

Since: 1.2

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

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 GVariant of secrets, of type `NM_VARIANT_TYPE_CONNECTION` -or `NM_VARIANT_TYPE_SETTING`
error	location to store error, or `NULL`

connection	the NMConnection
path	the D-Bus path of the connection as given by the settings service -which provides the connection

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

GTypeInterface `parent`;	the parent interace struct
`secrets_updated` ()	emitted when the connection's secrets are updated
`secrets_cleared` ()	emitted when the connection's secrets are cleared
`changed` ()	emitted when any change to the connection's settings occurs

NM_CONNECTION_SERIALIZE_ALL	- serialize all properties (including secrets) -
NM_CONNECTION_SERIALIZE_NO_SECRETS	- do not include secrets -
NM_CONNECTION_SERIALIZE_ONLY_SECRETS	- only serialize secrets -

NMConnection

Functions

Types and Values

Object Hierarchy

Description

Functions

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

Parameters

Returns

nm_connection_replace_settings ()

Parameters

Returns

nm_connection_replace_settings_from_connection ()

Parameters

nm_connection_clear_settings ()

Parameters

nm_connection_compare ()

Parameters

Returns

nm_connection_diff ()

Parameters

Returns

nm_connection_verify ()

Parameters

Returns

nm_connection_verify_secrets ()

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

Parameters

Returns

nm_connection_is_type ()

Parameters

Returns

nm_connection_for_each_setting_value ()

Parameters

nm_connection_dump ()

Parameters

nm_connection_get_uuid ()

Parameters

Returns

nm_connection_get_id ()

Parameters

Returns

nm_connection_get_connection_type ()

Parameters

Returns

nm_connection_is_virtual ()

Parameters

Returns

nm_connection_get_virtual_device_description ()

Parameters