From 8baa1aca8dfd35e3190d7d5655eb83b5b901e263 Mon Sep 17 00:00:00 2001 From: Michael Biebl Date: Thu, 21 Apr 2011 10:42:53 +0200 Subject: Imported Upstream version 0.8.4.0 --- docs/libnm-util/html/NMConnection.html | 1062 ++++++++++++++++++++++++++++++++ 1 file changed, 1062 insertions(+) create mode 100644 docs/libnm-util/html/NMConnection.html (limited to 'docs/libnm-util/html/NMConnection.html') diff --git a/docs/libnm-util/html/NMConnection.html b/docs/libnm-util/html/NMConnection.html new file mode 100644 index 00000000..3ff24b7e --- /dev/null +++ b/docs/libnm-util/html/NMConnection.html @@ -0,0 +1,1062 @@ + + + + +NMConnection + + + + + + + + + + + + + + + + + + + +
+
+
+ + +
+

NMConnection

+

NMConnection — Describes a connection to specific network or provider

+
+
+

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

Object Hierarchy

+
+  GObject
+   +----NMConnection
+
+
+
+

Properties

+
+  "path"                     gchar*                : Read / Write / Construct
+  "scope"                    guint                 : 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). +

+

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

+
++ + + + + + + + + + + + + + +

NM_CONNECTION_SCOPE_UNKNOWN

scope not known or not yet set +

NM_CONNECTION_SCOPE_SYSTEM

connection is provided by the system settings + service +

NM_CONNECTION_SCOPE_USER

connection is provided by a user settings service +
+
+
+
+

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

+
++ + + + + + + + + + +

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

+
#define NM_CONNECTION_SCOPE "scope"
+
+

+

+
+
+
+

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

+

+
++ + + + +

Returns :

 +
+
+
+
+

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 +

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 +
+
+
+
+

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 +
+
+
+
+

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 +
+
+
+
+

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 +
+
+
+
+

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 +

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, 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. +

+
++ + + + + + + + + + + + + + +

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

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

+
++ + + + + + + + + + + + + + + + + + + + + + +

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 +

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

+
++ + + + + + + + + + +

connection :

the NMConnection +

scope :

the scope of the connection +
+
+
+
+

nm_connection_get_scope ()

+
NMConnectionScope   nm_connection_get_scope             (NMConnection *connection);
+

+Returns the connection scope. +

+
++ + + + + + + + + + +

connection :

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

+
++ + + + + + + + + + +

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 +

user_data :

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

+
++ + + + + + + + + + +

connection :

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

+
++ + + + +

connection :

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

+
++ + + + + + + + + + +

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

+
++ + + + + + + + + + +

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 +
+
+
+
+

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

+
++ + + + + + + + + + + + + + +

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.15
+ + \ No newline at end of file -- cgit 1.3.0-6-gf8a5