libnm-util Reference Manual | ||||
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
Synopsis
#include <nm-connection.h> enum NMConnectionScope; enum NMConnectionError; #define NM_TYPE_CONNECTION_ERROR #define NM_CONNECTION_ERROR GQuark nm_connection_error_quark (void
); #define NM_CONNECTION_SCOPE #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
); 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_scope (NMConnection *connection
,NMConnectionScope scope
); NMConnectionScope nm_connection_get_scope (NMConnection *connection
); 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
); void nm_connection_dump (NMConnection *connection
); NMSetting * nm_connection_create_setting (const char *name
); GType nm_connection_lookup_setting_type (const char *name
); GType nm_connection_lookup_setting_type_by_quark (GQuark error_quark
);
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).
Most connections also have a NMConnectionScope
; a connection will be
provided over D-Bus either by the user settings service
(org.freedesktop.NetworkManagerUserSettings) running in an active user
session, or by the system-wide system settings service
(org.freedesktop.NetworkManagerSystemSettings) which provides connections
for all users.
Details
enum NMConnectionScope
typedef enum { NM_CONNECTION_SCOPE_UNKNOWN = 0, NM_CONNECTION_SCOPE_SYSTEM, NM_CONNECTION_SCOPE_USER } NMConnectionScope;
Connection scope indicated what settings service, if any, provides the connection.
enum NMConnectionError
typedef enum { NM_CONNECTION_ERROR_UNKNOWN = 0, NM_CONNECTION_ERROR_CONNECTION_SETTING_NOT_FOUND } NMConnectionError;
Describes errors that may result from operations involving a NMConnection.
unknown or unclassified error | |
the NMConnection object did not contain the required NMSettingConnection object, which must be present for all connections |
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. |
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_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.
|
the GHashTable describing the connection |
|
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.
|
the NMConnection to duplicate |
Returns : |
a new NMConnection containing the same settings and properties as the source NMConnection |
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.
|
a NMConnection |
|
the NMSetting to add to the connection object |
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.
|
a NMConnection |
|
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.
|
a NMConnection |
|
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 |
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.
|
a NMConnection |
|
a setting name |
Returns : |
the NMSetting, or NULL if no setting with that name was previously added to the NMConnection |
nm_connection_replace_settings ()
gboolean nm_connection_replace_settings (NMConnection *connection
,GHashTable *new_settings
,GError **error
);
|
a NMConnection |
|
a GHashTable of settings |
|
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 NMConnection |
|
a second NMConnection to compare with the first |
|
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 NMConnection |
|
a second NMConnection to compare with the first |
|
compare flags, e.g. NM_SETTING_COMPARE_FLAG_EXACT
|
|
if the connections differ, on return a hash table mapping setting names to second-level GHashTable, which contains key names that differ |
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.
|
the NMConnection to verify |
|
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.
|
the NMConnection |
|
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()
|
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.
|
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).
|
the NMConnection |
|
the setting object name to which the secrets apply |
|
a GHashTable mapping string:GValue of setting property names and secrets |
|
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_scope ()
void nm_connection_set_scope (NMConnection *connection
,NMConnectionScope scope
);
Sets the scope of the connection. This property is not serialized, and is only for the reference of the caller. A connection may have no scope (internal, temporary connections), "system" scope (provided by the system settings service), or "user" scope, provided by a user settings service. The creator of the NMConnection object is responsible for setting the connection's scope if needed. Sets the "scope" property.
|
the NMConnection |
|
the scope of the connection |
nm_connection_get_scope ()
NMConnectionScope nm_connection_get_scope (NMConnection *connection
);
Returns the connection scope.
|
the NMConnection |
Returns : |
the scope of the connection, previously set by a call to
nm_connection_set_scope() .
|
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.
|
the NMConnection |
|
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.
|
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.
|
the NMConnection |
|
user-supplied function called for each setting's property |
|
user data passed to func at each invocation
|
nm_connection_to_hash ()
GHashTable * nm_connection_to_hash (NMConnection *connection
);
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.
|
the NMConnection |
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.
|
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.
|
the NMConnection |
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.
|
a setting name |
Returns : |
the new setting object, or NULL if the setting name was unknown |
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.
|
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.
|
a setting error quark |
Returns : |
the GType of the setting's class |
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
The "scope"
property
"scope" guint : Read / Write / Construct
The connection's scope, used only by the calling process as a record of which settings service the connection is provided by. One of the NM_CONNECTION_SCOPE_* defines.
Allowed values: <= 2
Default value: 0
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.
|
the object on which the signal is emitted |
|
the setting name of the NMSetting for which secrets were updated |
|
user data set when the signal handler was connected. |