NMConnection

NMConnection — Describes a connection to specific network or provider

Synopsis

#include <nm-connection.h>

enum                NMConnectionError;
#define             NM_TYPE_CONNECTION_ERROR
#define             NM_CONNECTION_ERROR
GQuark              nm_connection_error_quark           (void);
#define             NM_CONNECTION_PATH
                    NMConnection;
                    NMConnectionClass;
GType               nm_connection_get_type              (void);
NMConnection *      nm_connection_new                   (void);
NMConnection *      nm_connection_new_from_hash         (GHashTable *hash,
                                                         GError **error);
NMConnection *      nm_connection_duplicate             (NMConnection *connection);
NMSetting *         nm_connection_create_setting        (const char *name);
void                nm_connection_add_setting           (NMConnection *connection,
                                                         NMSetting *setting);
void                nm_connection_remove_setting        (NMConnection *connection,
                                                         GType setting_type);
NMSetting *         nm_connection_get_setting           (NMConnection *connection,
                                                         GType setting_type);
NMSetting *         nm_connection_get_setting_by_name   (NMConnection *connection,
                                                         const char *name);
gboolean            nm_connection_replace_settings      (NMConnection *connection,
                                                         GHashTable *new_settings,
                                                         GError **error);
gboolean            nm_connection_compare               (NMConnection *a,
                                                         NMConnection *b,
                                                         NMSettingCompareFlags flags);
gboolean            nm_connection_diff                  (NMConnection *a,
                                                         NMConnection *b,
                                                         NMSettingCompareFlags flags,
                                                         GHashTable **out_settings);
gboolean            nm_connection_verify                (NMConnection *connection,
                                                         GError **error);
const char *        nm_connection_need_secrets          (NMConnection *connection,
                                                         GPtrArray **hints);
void                nm_connection_clear_secrets         (NMConnection *connection);
gboolean            nm_connection_update_secrets        (NMConnection *connection,
                                                         const char *setting_name,
                                                         GHashTable *setting_secrets,
                                                         GError **error);
void                nm_connection_set_path              (NMConnection *connection,
                                                         const char *path);
const char *        nm_connection_get_path              (NMConnection *connection);
void                nm_connection_for_each_setting_value
                                                        (NMConnection *connection,
                                                         NMSettingValueIterFn func,
                                                         gpointer user_data);
GHashTable *        nm_connection_to_hash               (NMConnection *connection,
                                                         NMSettingHashFlags flags);
void                nm_connection_dump                  (NMConnection *connection);
GType               nm_connection_lookup_setting_type   (const char *name);
GType               nm_connection_lookup_setting_type_by_quark
                                                        (GQuark error_quark);
const char *        nm_connection_get_uuid              (NMConnection *connection);
const char *        nm_connection_get_id                (NMConnection *connection);
NMSetting8021x *            nm_connection_get_setting_802_1x
                                                        (NMConnection *connection);
NMSettingBluetooth *        nm_connection_get_setting_bluetooth
                                                        (NMConnection *connection);
NMSettingCdma *             nm_connection_get_setting_cdma
                                                        (NMConnection *connection);
NMSettingConnection *       nm_connection_get_setting_connection
                                                        (NMConnection *connection);
NMSettingGsm *              nm_connection_get_setting_gsm
                                                        (NMConnection *connection);
NMSettingIP4Config *        nm_connection_get_setting_ip4_config
                                                        (NMConnection *connection);
NMSettingIP6Config *        nm_connection_get_setting_ip6_config
                                                        (NMConnection *connection);
NMSettingOlpcMesh *         nm_connection_get_setting_olpc_mesh
                                                        (NMConnection *connection);
NMSettingPPP *              nm_connection_get_setting_ppp
                                                        (NMConnection *connection);
NMSettingPPPOE *            nm_connection_get_setting_pppoe
                                                        (NMConnection *connection);
NMSettingVPN *              nm_connection_get_setting_vpn
                                                        (NMConnection *connection);
NMSettingWimax *            nm_connection_get_setting_wimax
                                                        (NMConnection *connection);
NMSettingWired *            nm_connection_get_setting_wired
                                                        (NMConnection *connection);
NMSettingWireless *         nm_connection_get_setting_wireless
                                                        (NMConnection *connection);
NMSettingWirelessSecurity * nm_connection_get_setting_wireless_security
                                                        (NMConnection *connection);

Object Hierarchy

  GEnum
   +----NMConnectionError

  GObject
   +----NMConnection

Properties

  "path"                     gchar*                : Read / Write / Construct

Signals

  "secrets-updated"                                : Run First

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

Details

enum NMConnectionError

typedef enum
{
	NM_CONNECTION_ERROR_UNKNOWN = 0,
	NM_CONNECTION_ERROR_CONNECTION_SETTING_NOT_FOUND,
	NM_CONNECTION_ERROR_CONNECTION_TYPE_INVALID
} NMConnectionError;

Describes errors that may result from operations involving a NMConnection.

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_TYPE_CONNECTION_ERROR

#define NM_TYPE_CONNECTION_ERROR (nm_connection_error_get_type ())

NM_CONNECTION_ERROR

#define NM_CONNECTION_ERROR nm_connection_error_quark ()

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_PATH

#define NM_CONNECTION_PATH "path"

NMConnection

typedef struct _NMConnection NMConnection;

The NMConnection struct contains only private data. It should only be accessed through the functions described below.

NMConnectionClass

typedef struct {
	GObjectClass parent;

	/* Signals */
	void (*secrets_updated) (NMConnection *connection, const char * setting);
} NMConnectionClass;

nm_connection_get_type ()

GType               nm_connection_get_type              (void);

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.

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.

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.

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.

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.

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.

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 the NMConnection.

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

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

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.

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

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

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 each array element with g_free(), as well as the array itself with g_ptr_array_free(). [out callee-allocates][element-type utf8][allow-none][transfer full]

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.

connection :

 the NMConnection

nm_connection_update_secrets ()

gboolean            nm_connection_update_secrets        (NMConnection *connection,
                                                         const char *setting_name,
                                                         GHashTable *setting_secrets,
                                                         GError **error);

Update the specified setting's secrets, given a hash table of secrets intended for that setting (deserialized from D-Bus for example). Will also extract the given setting's secrets hash if given a hash of hashes, as would be returned from nm_connection_to_hash().

connection :

 the NMConnection

setting_name :

 the setting object name to which the secrets apply

setting_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

Returns :

 TRUE if the secrets were successfully updated and the connection is valid, FALSE on failure or if the setting was never added to the connection

nm_connection_set_path ()

void                nm_connection_set_path              (NMConnection *connection,
                                                         const char *path);

Sets the D-Bus path of the connection. This property is not serialized, and is only for the reference of the caller. Sets the "path" property.

connection :

 the NMConnection

path :

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

nm_connection_get_path ()

const char *        nm_connection_get_path              (NMConnection *connection);

Returns the connection's D-Bus path.

connection :

 the NMConnection

Returns :

 the D-Bus path of the connection, previously set by a call to nm_connection_set_path().

nm_connection_for_each_setting_value ()

void                nm_connection_for_each_setting_value
                                                        (NMConnection *connection,
                                                         NMSettingValueIterFn func,
                                                         gpointer user_data);

Iterates over the properties of each NMSetting object in the NMConnection, calling the supplied user function for each property.

connection :

 the NMConnection

func :

 user-supplied function called for each setting's property. [scope call]

user_data :

 user data passed to func at each invocation

nm_connection_to_hash ()

GHashTable *        nm_connection_to_hash               (NMConnection *connection,
                                                         NMSettingHashFlags flags);

Converts the NMConnection into a GHashTable describing the connection, suitable for marshalling over D-Bus or serializing. The hash table mapping is string:GHashTable with each element in the returned hash representing a NMSetting object. The keys are setting object names, and the values are GHashTables mapping string:GValue, each of which represents the properties of the NMSetting object.

connection :

 the NMConnection

flags :

 hash flags, e.g. NM_SETTING_HASH_FLAG_ALL

Returns :

 a new GHashTable describing the connection, its settings, and each setting's properties. The caller owns the hash table and must unref the hash table with g_hash_table_unref() when it is no longer needed. [transfer full][element-type utf8 GLib.HashTable]

nm_connection_dump ()

void                nm_connection_dump                  (NMConnection *connection);

Print the connection to stdout. For debugging purposes ONLY, should NOT be used for serialization of the connection or machine-parsed in any way. The output format is not guaranteed to be stable and may change at any time.

connection :

 the NMConnection

nm_connection_lookup_setting_type ()

GType               nm_connection_lookup_setting_type   (const char *name);

Returns the GType of the setting's class for a given setting name.

name :

 a setting name

Returns :

 the GType of the setting's class

nm_connection_lookup_setting_type_by_quark ()

GType               nm_connection_lookup_setting_type_by_quark
                                                        (GQuark error_quark);

Returns the GType of the setting's class for a given setting error quark. Useful for figuring out which setting a returned error is for.

error_quark :

 a setting error quark

Returns :

 the GType of the setting's class

nm_connection_get_uuid ()

const char *        nm_connection_get_uuid              (NMConnection *connection);

A shortcut to return the UUID from the connection's NMSettingConnection.

connection :

 the NMConnection

Returns :

 the UUID from the connection's 'connection' setting

nm_connection_get_id ()

const char *        nm_connection_get_id                (NMConnection *connection);

A shortcut to return the ID from the connection's NMSettingConnection.

connection :

 the NMConnection

Returns :

 the ID from the connection's 'connection' setting

nm_connection_get_setting_802_1x ()

NMSetting8021x *            nm_connection_get_setting_802_1x
                                                        (NMConnection *connection);

A shortcut to return any NMSetting8021x the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSetting8021x if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_bluetooth ()

NMSettingBluetooth *        nm_connection_get_setting_bluetooth
                                                        (NMConnection *connection);

A shortcut to return any NMSettingBluetooth the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingBluetooth if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_cdma ()

NMSettingCdma *             nm_connection_get_setting_cdma
                                                        (NMConnection *connection);

A shortcut to return any NMSettingCdma the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingCdma if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_connection ()

NMSettingConnection *       nm_connection_get_setting_connection
                                                        (NMConnection *connection);

A shortcut to return any NMSettingConnection the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingConnection if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_gsm ()

NMSettingGsm *              nm_connection_get_setting_gsm
                                                        (NMConnection *connection);

A shortcut to return any NMSettingGsm the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingGsm if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_ip4_config ()

NMSettingIP4Config *        nm_connection_get_setting_ip4_config
                                                        (NMConnection *connection);

A shortcut to return any NMSettingIP4Config the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingIP4Config if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_ip6_config ()

NMSettingIP6Config *        nm_connection_get_setting_ip6_config
                                                        (NMConnection *connection);

A shortcut to return any NMSettingIP6Config the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingIP6Config if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_olpc_mesh ()

NMSettingOlpcMesh *         nm_connection_get_setting_olpc_mesh
                                                        (NMConnection *connection);

A shortcut to return any NMSettingOlpcMesh the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingOlpcMesh if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_ppp ()

NMSettingPPP *              nm_connection_get_setting_ppp
                                                        (NMConnection *connection);

A shortcut to return any NMSettingPPP the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingPPP if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_pppoe ()

NMSettingPPPOE *            nm_connection_get_setting_pppoe
                                                        (NMConnection *connection);

A shortcut to return any NMSettingPPOE the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingPPPOE if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_vpn ()

NMSettingVPN *              nm_connection_get_setting_vpn
                                                        (NMConnection *connection);

A shortcut to return any NMSettingVPN the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingVPN if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_wimax ()

NMSettingWimax *            nm_connection_get_setting_wimax
                                                        (NMConnection *connection);

A shortcut to return any NMSettingWimax the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingWimax if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_wired ()

NMSettingWired *            nm_connection_get_setting_wired
                                                        (NMConnection *connection);

A shortcut to return any NMSettingWired the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingWired if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_wireless ()

NMSettingWireless *         nm_connection_get_setting_wireless
                                                        (NMConnection *connection);

A shortcut to return any NMSettingWireless the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingWireless if the connection contains one, otherwise NULL. [transfer none]

nm_connection_get_setting_wireless_security ()

NMSettingWirelessSecurity * nm_connection_get_setting_wireless_security
                                                        (NMConnection *connection);

A shortcut to return any NMSettingWirelessSecurity the connection might contain.

connection :

 the NMConnection

Returns :

 an NMSettingWirelessSecurity if the connection contains one, otherwise NULL. [transfer none]

Property Details

The "path" property

  "path"                     gchar*                : Read / Write / Construct

The connection's D-Bus path, used only by the calling process as a record of the D-Bus path of the connection as provided by a settings service.

Default value: NULL

Signal Details

The "secrets-updated" signal

void                user_function                      (NMConnection *connection,
                                                        gchar        *setting_name,
                                                        gpointer      user_data)         : Run First

The ::secrets-updated signal is emitted when the secrets of a setting have been changed.

connection :

 the object on which the signal is emitted

setting_name :

 the setting name of the NMSetting for which secrets were updated

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.17