colin/NetworkManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation updates

Browse Source 
git-svn-id: http://svn-archive.gnome.org/svn/NetworkManager/trunk@4331 4912f4e0-d625-0410-9fb7-b9a5a253dbdc
This commit is contained in:
Dan Williams
2008-11-24 04:30:36 +00:00
parent d0dd5171ba
commit ccbd9155ec
6 changed files with 227 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
libnm-util/nm-connection.c
View File

@@ -76,7 +76,7 @@
*
* Registers an error quark for #NMConnection if necessary.
*
* Returns: the error quark used for NMConnection errors.
* Returns: the error quark used for #NMConnection errors.
**/
GQuark
nm_connection_error_quark (void)
@@ -98,9 +98,7 @@ nm_connection_error_get_type (void)
if (etype == 0) {
static const GEnumValue values[] = {
/* Unknown error. */
ENUM_ENTRY (NM_CONNECTION_ERROR_UNKNOWN, "UnknownError"),
/* The required 'connection' setting was not found. */
ENUM_ENTRY (NM_CONNECTION_ERROR_CONNECTION_SETTING_NOT_FOUND, "ConnectionSettingNotFound"),
{ 0, 0, 0 }
};
@@ -985,7 +983,7 @@ nm_connection_get_path (NMConnection *connection)
*
* Creates a new #NMConnection object with no #NMSetting objects.
*
* Returns: the new blank #NMConnection object
* Returns: the new empty #NMConnection object
**/
NMConnection *
nm_connection_new (void)

35
libnm-util/nm-connection.h
View File

@@ -39,18 +39,34 @@ G_BEGIN_DECLS
#define NM_IS_CONNECTION_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((obj), NM_TYPE_CONNECTION))
#define NM_CONNECTION_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_CONNECTION, NMConnectionClass))
/* connection scope, used only by the caller for tracking connections
* provided by multiple settings services.
*/
/**
* NMConnectionScope:
* @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
*
* Connection scope indicated what settings service, if any, provides the
* connection.
*
**/
typedef enum {
/* The connection's scope is unknown, or not yet set */
NM_CONNECTION_SCOPE_UNKNOWN = 0,
/* The connection is provided by the system settings service */
NM_CONNECTION_SCOPE_SYSTEM,
/* The connection is provided by a user settings service */
NM_CONNECTION_SCOPE_USER
} NMConnectionScope;
/**
* NMConnectionError:
* @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
*
* Describes errors that may result from operations involving a #NMConnection.
*
**/
typedef enum
{
NM_CONNECTION_ERROR_UNKNOWN = 0,
@@ -66,6 +82,12 @@ GQuark nm_connection_error_quark (void);
#define NM_CONNECTION_SCOPE "scope"
#define NM_CONNECTION_PATH "path"
/**
* NMConnection:
*
* The NMConnection struct contains only private data.
* It should only be accessed through the functions described below.
*/
typedef struct {
GObject parent;
} NMConnection;
@@ -101,7 +123,6 @@ gboolean nm_connection_replace_settings (NMConnection *connection,
GHashTable *new_settings,
GError **error);
/* Returns TRUE if the connections are the same */
gboolean nm_connection_compare (NMConnection *a,
NMConnection *b,
NMSettingCompareFlags flags);

124
libnm-util/nm-setting-connection.c
View File

@@ -26,6 +26,24 @@
#include <string.h>
#include "nm-setting-connection.h"
/**
* SECTION:nm-setting-connection
* @short_description: Describes general connection properties
* @include: nm-setting-connection.h
*
* The #NMSettingConnection object is a #NMSetting subclass that describes
* properties that apply to all #NMConnection objects, regardless of what type
* of network connection they describe. Each #NMConnection object must contain
* a #NMSettingConnection setting.
*/
/**
* nm_setting_connection_error_quark:
*
* Registers an error quark for #NMSettingConnection if necessary.
*
* Returns: the error quark used for #NMSettingConnection errors.
**/
GQuark
nm_setting_connection_error_quark (void)
{
@@ -46,13 +64,9 @@ nm_setting_connection_error_get_type (void)
if (etype == 0) {
static const GEnumValue values[] = {
/* Unknown error. */
ENUM_ENTRY (NM_SETTING_CONNECTION_ERROR_UNKNOWN, "UnknownError"),
/* The specified property was invalid. */
ENUM_ENTRY (NM_SETTING_CONNECTION_ERROR_INVALID_PROPERTY, "InvalidProperty"),
/* The specified property was missing and is required. */
ENUM_ENTRY (NM_SETTING_CONNECTION_ERROR_MISSING_PROPERTY, "MissingProperty"),
/* The setting specified by the 'type' field was not found. */
ENUM_ENTRY (NM_SETTING_CONNECTION_ERROR_TYPE_SETTING_NOT_FOUND, "TypeSettingNotFound"),
{ 0, 0, 0 }
};
@@ -87,11 +101,26 @@ enum {
LAST_PROP
};
/**
* nm_setting_connection_new:
*
* Creates a new #NMSettingConnection object with default values.
*
* Returns: the new empty #NMSettingConnection object
**/
NMSetting *nm_setting_connection_new (void)
{
return (NMSetting *) g_object_new (NM_TYPE_SETTING_CONNECTION, NULL);
}
/**
* nm_setting_connection_get_id:
* @setting: the #NMSettingConnection
*
* Returns the #NMSettingConnection:id property of the connection.
*
* Returns: the connection ID
**/
const char *
nm_setting_connection_get_id (NMSettingConnection *setting)
{
@@ -100,6 +129,14 @@ nm_setting_connection_get_id (NMSettingConnection *setting)
return NM_SETTING_CONNECTION_GET_PRIVATE (setting)->id;
}
/**
* nm_setting_connection_get_uuid:
* @setting: the #NMSettingConnection
*
* Returns the #NMSettingConnection:uuid property of the connection.
*
* Returns: the connection UUID
**/
const char *
nm_setting_connection_get_uuid (NMSettingConnection *setting)
{
@@ -108,6 +145,14 @@ nm_setting_connection_get_uuid (NMSettingConnection *setting)
return NM_SETTING_CONNECTION_GET_PRIVATE (setting)->uuid;
}
/**
* nm_setting_connection_get_type:
* @setting: the #NMSettingConnection
*
* Returns the #NMSettingConnection:type property of the connection.
*
* Returns: the connection type
**/
const char *
nm_setting_connection_get_connection_type (NMSettingConnection *setting)
{
@@ -116,6 +161,14 @@ nm_setting_connection_get_connection_type (NMSettingConnection *setting)
return NM_SETTING_CONNECTION_GET_PRIVATE (setting)->type;
}
/**
* nm_setting_connection_get_autoconnect:
* @setting: the #NMSettingConnection
*
* Returns the #NMSettingConnection:autoconnect property of the connection.
*
* Returns: the connection's autoconnect behavior
**/
gboolean
nm_setting_connection_get_autoconnect (NMSettingConnection *setting)
{
@@ -124,6 +177,14 @@ nm_setting_connection_get_autoconnect (NMSettingConnection *setting)
return NM_SETTING_CONNECTION_GET_PRIVATE (setting)->autoconnect;
}
/**
* nm_setting_connection_get_timestamp:
* @setting: the #NMSettingConnection
*
* Returns the #NMSettingConnection:timestamp property of the connection.
*
* Returns: the connection's timestamp
**/
guint64
nm_setting_connection_get_timestamp (NMSettingConnection *setting)
{
@@ -132,6 +193,14 @@ nm_setting_connection_get_timestamp (NMSettingConnection *setting)
return NM_SETTING_CONNECTION_GET_PRIVATE (setting)->timestamp;
}
/**
* nm_setting_connection_get_read_only:
* @setting: the #NMSettingConnection
*
* Returns the #NMSettingConnection:read-only property of the connection.
*
* Returns: %TRUE if the connection is read-only, %FALSE if it is not
**/
gboolean
nm_setting_connection_get_read_only (NMSettingConnection *setting)
{
@@ -306,6 +375,13 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
parent_class->verify = verify;
/* Properties */
/**
* NMSettingConnection:id:
*
* A human readable unique idenfier for the connection, like "Work WiFi" or
* "T-Mobile 3G".
**/
g_object_class_install_property
(object_class, PROP_ID,
g_param_spec_string (NM_SETTING_CONNECTION_ID,
@@ -314,6 +390,17 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
NULL,
G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE));
/**
* NMSettingConnection:uuid:
*
* A universally unique idenfier for the connection, for example generated
* with libuuid. Should be assigned when the connection is created, and
* never changed as long as the connection still applies to the same
* network. For example, should not be changed when the
* #NMSettingConnection:id or #NMSettingIP4Config changes, but might need
* to be re-created when the WiFi SSID, mobile broadband network provider,
* or #NMSettingConnection:type changes.
**/
g_object_class_install_property
(object_class, PROP_UUID,
g_param_spec_string (NM_SETTING_CONNECTION_UUID,
@@ -322,6 +409,14 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
NULL,
G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE));
/**
* NMSettingConnection:type:
*
* The general hardware type of the device used for the network connection,
* contains the name of the #NMSetting object that describes that hardware
* type's parameters. For example, for WiFi devices, the name of the
* #NMSettingWireless setting.
**/
g_object_class_install_property
(object_class, PROP_TYPE,
g_param_spec_string (NM_SETTING_CONNECTION_TYPE,
@@ -330,6 +425,14 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
NULL,
G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE));
/**
* NMSettingConnection:autoconnect:
*
* Whether or not the connection should be automatically connected by
* NetworkManager when the resources for the connection are available.
* %TRUE to automatically activate the connection, %FALSE to require manual
* intervention to activate the connection.
**/
g_object_class_install_property
(object_class, PROP_AUTOCONNECT,
g_param_spec_boolean (NM_SETTING_CONNECTION_AUTOCONNECT,
@@ -338,6 +441,12 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
FALSE,
G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE));
/**
* NMSettingConnection:timestamp:
*
* The time, in seconds since the Unix Epoch, that the connection was last
* _successfully_ fully activated.
**/
g_object_class_install_property
(object_class, PROP_TIMESTAMP,
g_param_spec_uint64 (NM_SETTING_CONNECTION_TIMESTAMP,
@@ -346,6 +455,13 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
0, G_MAXUINT64, 0,
G_PARAM_READWRITE | NM_SETTING_PARAM_SERIALIZE | NM_SETTING_PARAM_FUZZY_IGNORE));
/**
* NMSettingConnection:read-only:
*
* %TRUE if the connection can be modified using the providing settings
* service's D-Bus interface with the right privileges, or %FALSE
* if the connection is read-only and cannot be modified.
**/
g_object_class_install_property
(object_class, PROP_READ_ONLY,
g_param_spec_boolean (NM_SETTING_CONNECTION_READ_ONLY,

21
libnm-util/nm-setting-connection.h
View File

@@ -39,6 +39,21 @@ G_BEGIN_DECLS
#define NM_SETTING_CONNECTION_SETTING_NAME "connection"
/**
* NMSettingConnectionError:
* @NM_SETTING_CONNECTION_ERROR_UNKNOWN: unknown or unclassified error
* @NM_SETTING_CONNECTION_ERROR_INVALID_PROPERTY: the property's value is
* invalid
* @NM_SETTING_CONNECTION_ERROR_MISSING_PROPERTY: a required property is not
* present
* @NM_SETTING_CONNECTION_ERROR_TYPE_SETTING_NOT_FOUND: the #NMSetting object
* referenced by the setting name contained in the
* #NMSettingConnection:type property was not present in the #NMConnection
*
* Describes errors that may result from operations involving a
* #NMSettingConnection.
*
**/
typedef enum
{
NM_SETTING_CONNECTION_ERROR_UNKNOWN = 0,
@@ -60,6 +75,12 @@ GQuark nm_setting_connection_error_quark (void);
#define NM_SETTING_CONNECTION_TIMESTAMP "timestamp"
#define NM_SETTING_CONNECTION_READ_ONLY "read-only"
/**
* NMSettingConnection:
*
* The NMSettingConnection struct contains only private data.
* It should only be accessed through the functions described below.
*/
typedef struct {
NMSetting parent;
} NMSettingConnection;

17
libnm-util/nm-setting.c
View File

@@ -29,6 +29,19 @@
#include "nm-setting-connection.h"
#include "nm-utils.h"
/**
* SECTION:nm-setting
* @short_description: Describes related configuration information
* @include: nm-setting.h
*
* Each #NMSetting contains properties that describe configuration that applies
* to a specific network layer (like IPv4 or IPv6 configuration) or device type
* (like Ethernet, or WiFi). A collection of individual settings together
* make up an #NMConnection. Each property is strongly typed and usually has
* a number of allowed values. See each #NMSetting subclass for a description
* of properties and allowed values.
*/
/**
* nm_setting_error_quark:
*
@@ -56,13 +69,9 @@ nm_setting_error_get_type (void)
if (etype == 0) {
static const GEnumValue values[] = {
/* Unknown error. */
ENUM_ENTRY (NM_SETTING_ERROR_UNKNOWN, "UnknownError"),
/* The property was not found. */
ENUM_ENTRY (NM_SETTING_ERROR_PROPERTY_NOT_FOUND, "PropertyNotFound"),
/* The property was not a secret. */
ENUM_ENTRY (NM_SETTING_ERROR_PROPERTY_NOT_SECRET, "PropertyNotSecret"),
/* The property type didn't match the required property type. */
ENUM_ENTRY (NM_SETTING_ERROR_PROPERTY_TYPE_MISMATCH, "PropertyTypeMismatch"),
{ 0, 0, 0 }
};

54
libnm-util/nm-setting.h
View File

@@ -38,6 +38,20 @@ G_BEGIN_DECLS
#define NM_IS_SETTING_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((obj), NM_TYPE_SETTING))
#define NM_SETTING_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), NM_TYPE_SETTING, NMSettingClass))
/**
* NMSettingError:
* @NM_SETTING_ERROR_UNKNOWN: unknown or unclassified error
* @NM_SETTING_ERROR_PROPERTY_NOT_FOUND: a property required by the operation
* was not found; for example, an attempt to update an invalid secret
* @NM_SETTING_ERROR_PROPERTY_NOT_SECRET: an operation which requires a secret
* was attempted on a non-secret property
* @NM_SETTING_ERROR_PROPERTY_TYPE_MISMATCH: the operation requires a property
* of a specific type, or the value couldn't be transformed to the same type
* as the property being acted upon
*
* Describes errors that may result from operations involving a #NMSetting.
*
**/
typedef enum
{
NM_SETTING_ERROR_UNKNOWN = 0,
@@ -52,13 +66,29 @@ GType nm_setting_error_get_type (void);
#define NM_SETTING_ERROR nm_setting_error_quark ()
GQuark nm_setting_error_quark (void);
/* The property of the #NMSetting should be serialized */
#define NM_SETTING_PARAM_SERIALIZE (1 << (0 + G_PARAM_USER_SHIFT))
/* The property of the #NMSetting is required for the setting to be valid */
#define NM_SETTING_PARAM_REQUIRED (1 << (1 + G_PARAM_USER_SHIFT))
/* The property of the #NMSetting is a secret */
#define NM_SETTING_PARAM_SECRET (1 << (2 + G_PARAM_USER_SHIFT))
/* The property of the #NMSetting should be ignored during comparisons that
* use the %NM_SETTING_COMPARE_FLAG_FUZZY flag.
*/
#define NM_SETTING_PARAM_FUZZY_IGNORE (1 << (3 + G_PARAM_USER_SHIFT))
#define NM_SETTING_NAME "name"
/**
* NMSetting:
*
* The NMSetting struct contains only private data.
* It should only be accessed through the functions described below.
*/
typedef struct {
GObject parent;
} NMSetting;
@@ -100,24 +130,26 @@ gboolean nm_setting_verify (NMSetting *setting,
GSList *all_settings,
GError **error);
/**
* NMSettingCompareFlags:
* @NM_SETTING_COMPARE_FLAG_EXACT: match all properties exactly
* @NM_SETTING_COMPARE_FLAG_FUZZY: match only important attributes, like SSID,
* type, security settings, etc. Does not match, for example, connection ID
* or UUID.
* @NM_SETTING_COMPARE_FLAG_IGNORE_ID: ignore the connection's ID
* @NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS: ignore secrets
*
* These flags modify the comparison behavior when comparing two settings or
* two connections.
*
**/
typedef enum {
/* Match all attributes exactly */
NM_SETTING_COMPARE_FLAG_EXACT = 0x00000000,
/* Match only important attributes, like SSID, type, security settings, etc;
* For example, does not match connection ID or UUID.
*/
NM_SETTING_COMPARE_FLAG_FUZZY = 0x00000001,
/* Ignore the connection ID */
NM_SETTING_COMPARE_FLAG_IGNORE_ID = 0x00000002,
/* Ignore connection secrets */
NM_SETTING_COMPARE_FLAG_IGNORE_SECRETS = 0x00000004
} NMSettingCompareFlags;
/* Returns TRUE if the connections are the same */
gboolean nm_setting_compare (NMSetting *a,
NMSetting *b,
NMSettingCompareFlags flags);