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,