From f75dd6fd1975146623052b843b182dc32c3fbe46 Mon Sep 17 00:00:00 2001 From: Michael Biebl Date: Fri, 8 Apr 2011 07:30:59 +0200 Subject: Imported Upstream version 0.8.998 --- docs/libnm-util/html/NMConnection.html | 1062 -------------------------------- 1 file changed, 1062 deletions(-) delete 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 deleted file mode 100644 index 7d660012..00000000 --- a/docs/libnm-util/html/NMConnection.html +++ /dev/null @@ -1,1062 +0,0 @@ - - - - -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