system/NetworkManager
system/NetworkManager
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/NetworkManager/NetworkManager synced 2024-07-23 03:04:18 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

libnm, docs: docs fixes

Browse source 
Update the docs build to include and exclude the correct files.

Fill in some missing documentation, and fix problems in the existing
docs. (In particular, "<" can't appear as a literal in documentation,
so change it to "&lt;". Also, "PKCS#12" has to be written as
"PKCS#<!-- -->12", or gtk-doc will think "#12" is a reference to a
type named "12".)
This commit is contained in:
Dan Winship 2014-11-07 12:38:17 -05:00
parent 941897cc97
commit cbabd13581
13 changed files with 114 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
docs/libnm/Makefile.am
View file

@ -30,9 +30,11 @@ CFILE_GLOB=$(top_srcdir)/libnm-core/*.c $(top_srcdir)/libnm/*.c
# Header files to ignore when scanning.
IGNORE_HFILES= \
common.h \
crypto.h \
nm-dbus-helpers-private.h \
nm-dbus-helpers.h \
nm-core-internal.h \
nm-core-types.h \
nm-device-private.h \
nm-dhcp4-config.h \
nm-dhcp6-config.h \
@ -41,12 +43,13 @@ IGNORE_HFILES= \
nm-manager.h \
nm-object-cache.h \
nm-object-private.h \
nm-param-spec-dbus.h \
nm-property-compare.h \
nm-remote-connection-private.h \
nm-remote-settings.h \
nm-setting-private.h \
nm-types-private.h \
nm-utils-private.h
nm-types.h \
nm-utils-private.h \
nm-vpn-plugin-old.h
# Images to copy into HTML directory.
HTML_IMAGES = libnm.png

10
docs/libnm/libnm-docs.xml
View file

@ -68,11 +68,14 @@
<xi:include href="xml/nm-client.xml"/>
<xi:include href="xml/nm-secret-agent.xml"/>
<xi:include href="xml/nm-object.xml"/>
<xi:include href="xml/nm-errors.xml"/>
<xi:include href="xml/nm-dbus-interface.xml"/>
</chapter>
<chapter>
<title>Connection and Setting API Reference</title>
<xi:include href="xml/nm-connection.xml"/>
<xi:include href="xml/nm-simple-connection.xml"/>
<xi:include href="xml/nm-setting.xml"/>
<xi:include href="xml/nm-setting-connection.xml"/>
<!-- begin alphabetical -->
@ -135,6 +138,13 @@
<chapter>
<title>Utility API Reference</title>
<xi:include href="xml/nm-utils.xml"/>
<xi:include href="xml/nm-version.xml"/>
</chapter>
<chapter>
<title>VPN Plugin API Reference</title>
<xi:include href="xml/nm-vpn-dbus-interface.xml"/>
<xi:include href="xml/nm-vpn-editor-plugin.xml"/>
</chapter>
<chapter id="object-tree">

7
libnm-core/nm-connection.h
View file

@ -57,6 +57,13 @@ G_BEGIN_DECLS
* client side, and #NMSettingsConnection on the daemon side.
*/
/**
* NMConnectionInterface:
* @parent: the parent interace struct
* @secrets_updated: emitted when the connection's secrets are updated
* @secrets_cleared: emitted when the connection's secrets are cleared
* @changed: emitted when any change to the connection's settings occurs
*/
typedef struct {
GTypeInterface parent;

2
libnm-core/nm-dbus-interface.h
View file

@ -526,8 +526,6 @@ typedef enum {
NM_DEVICE_STATE_REASON_MODEM_FAILED = 57,
NM_DEVICE_STATE_REASON_MODEM_AVAILABLE = 58,
NM_DEVICE_STATE_REASON_SIM_PIN_INCORRECT = 59,
NM_DEVICE_STATE_REASON_LAST = 0xFFFF
} NMDeviceStateReason;

12
libnm-core/nm-errors.h
View file

@ -63,21 +63,21 @@ GQuark nm_agent_manager_error_quark (void);
* was attempted on a non-secret property
* @NM_CONNECTION_ERROR_MISSING_SETTING: the #NMConnection object is missing an
* #NMSetting which is required for its configuration. The error message will
* always be prefixed with "<setting-name>: ", where "<setting-name>" is the
* always be prefixed with "&lt;setting-name>: ", where "&lt;setting-name>" is the
* name of the setting that is missing.
* @NM_CONNECTION_ERROR_INVALID_SETTING: the #NMConnection object contains an
* invalid or inappropriate #NMSetting. The error message will always be
* prefixed with "<setting-name>: ", where "<setting-name>" is the name of the
* prefixed with "&lt;setting-name>: ", where "&lt;setting-name>" is the name of the
* setting that is invalid.
* @NM_CONNECTION_ERROR_MISSING_PROPERTY: the #NMConnection object is invalid
* because it is missing a required property. The error message will always be
* prefixed with "<setting-name>.<property-name>: ", where "<setting-name>" is
* the name of the setting with the missing property, and "<property-name>" is
* prefixed with "&lt;setting-name>.&lt;property-name>: ", where "&lt;setting-name>" is
* the name of the setting with the missing property, and "&lt;property-name>" is
* the property that is missing.
* @NM_CONNECTION_ERROR_INVALID_PROPERTY: the #NMConnection object is invalid
* because a property has an invalid value. The error message will always be
* prefixed with "<setting-name>.<property-name>: ", where "<setting-name>" is
* the name of the setting with the invalid property, and "<property-name>" is
* prefixed with "&lt;setting-name>.&lt;property-name>: ", where "&lt;setting-name>" is
* the name of the setting with the invalid property, and "&lt;property-name>" is
* the property that is invalid.
*
* Describes errors that may result from operations involving a #NMConnection

57
libnm-core/nm-setting-8021x.c
View file

@ -820,7 +820,7 @@ nm_setting_802_1x_get_client_cert_path (NMSetting8021x *setting)
* @setting: the #NMSetting8021x
* @cert_path: when @scheme is set to either %NM_SETTING_802_1X_CK_SCHEME_PATH
* or %NM_SETTING_802_1X_CK_SCHEME_BLOB, pass the path of the client
* certificate file (PEM, DER, or PKCS#12 format). The path must be UTF-8
* certificate file (PEM, DER, or PKCS#<!-- -->12 format). The path must be UTF-8
* encoded; use g_filename_to_utf8() to convert if needed. Passing %NULL with
* any @scheme clears the client certificate.
* @scheme: desired storage scheme for the certificate
@ -1403,7 +1403,7 @@ nm_setting_802_1x_get_phase2_client_cert_path (NMSetting8021x *setting)
* @setting: the #NMSetting8021x
* @cert_path: when @scheme is set to either %NM_SETTING_802_1X_CK_SCHEME_PATH
* or %NM_SETTING_802_1X_CK_SCHEME_BLOB, pass the path of the "phase2" client
* certificate file (PEM, DER, or PKCS#12 format). The path must be UTF-8
* certificate file (PEM, DER, or PKCS#<!-- -->12 format). The path must be UTF-8
* encoded; use g_filename_to_utf8() to convert if needed. Passing %NULL with
* any @scheme clears the "phase2" client certificate.
* @scheme: desired storage scheme for the certificate
@ -1687,7 +1687,7 @@ file_to_secure_bytes (const char *filename)
* @setting: the #NMSetting8021x
* @key_path: when @scheme is set to either %NM_SETTING_802_1X_CK_SCHEME_PATH or
* %NM_SETTING_802_1X_CK_SCHEME_BLOB, pass the path of the private key file
* (PEM, DER, or PKCS#12 format). The path must be UTF-8 encoded; use
* (PEM, DER, or PKCS#<!-- -->12 format). The path must be UTF-8 encoded; use
* g_filename_to_utf8() to convert if needed. Passing %NULL with any @scheme
* clears the private key.
* @password: password used to decrypt the private key, or %NULL if the password
@ -1997,7 +1997,7 @@ nm_setting_802_1x_get_phase2_private_key_path (NMSetting8021x *setting)
* @setting: the #NMSetting8021x
* @key_path: when @scheme is set to either %NM_SETTING_802_1X_CK_SCHEME_PATH or
* %NM_SETTING_802_1X_CK_SCHEME_BLOB, pass the path of the "phase2" private
* key file (PEM, DER, or PKCS#12 format). The path must be UTF-8 encoded;
* key file (PEM, DER, or PKCS#<!-- -->12 format). The path must be UTF-8 encoded;
* use g_filename_to_utf8() to convert if needed. Passing %NULL with any
* @scheme clears the private key.
* @password: password used to decrypt the private key, or %NULL if the password
@ -3502,15 +3502,16 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
* should be set to the key's encrypted PEM encoded data. When using private
* keys with the path scheme, this property should be set to the full UTF-8
* encoded path of the key, prefixed with the string "file://" and ending
* with a terminating NUL byte. When using PKCS#12 format private keys and
* the blob scheme, this property should be set to the PKCS#12 data and the
* #NMSetting8021x:private-key-password property must be set to password
* used to decrypt the PKCS#12 certificate and key. When using PKCS#12 files
* and the path scheme, this property should be set to the full UTF-8
* encoded path of the key, prefixed with the string "file://" and and
* ending with a terminating NUL byte, and as with the blob scheme the
* "private-key-password" property must be set to the password used to
* decode the PKCS#12 private key and certificate.
* with a terminating NUL byte. When using PKCS#<!-- -->12 format private
* keys and the blob scheme, this property should be set to the
* PKCS#<!-- -->12 data and the #NMSetting8021x:private-key-password
* property must be set to password used to decrypt the PKCS#<!-- -->12
* certificate and key. When using PKCS#<!-- -->12 files and the path
* scheme, this property should be set to the full UTF-8 encoded path of the
* key, prefixed with the string "file://" and and ending with a terminating
* NUL byte, and as with the blob scheme the "private-key-password" property
* must be set to the password used to decode the PKCS#<!-- -->12 private
* key and certificate.
*
* Setting this property directly is discouraged; use the
* nm_setting_802_1x_set_private_key() function instead.
@ -3537,7 +3538,7 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
*
* The password used to decrypt the private key specified in the
* #NMSetting8021x:private-key property when the private key either uses the
* path scheme, or if the private key is a PKCS#12 format key. Setting this
* path scheme, or if the private key is a PKCS#<!-- -->12 format key. Setting this
* property directly is not generally necessary except when returning
* secrets to NetworkManager; it is generally set automatically when setting
* the private key by the nm_setting_802_1x_set_private_key() function.
@ -3576,15 +3577,16 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
* should be set to the key's encrypted PEM encoded data. When using private
* keys with the path scheme, this property should be set to the full UTF-8
* encoded path of the key, prefixed with the string "file://" and ending
* with a terminating NUL byte. When using PKCS#12 format private keys and
* the blob scheme, this property should be set to the PKCS#12 data and the
* #NMSetting8021x:phase2-private-key-password property must be set to
* password used to decrypt the PKCS#12 certificate and key. When using
* PKCS#12 files and the path scheme, this property should be set to the
* full UTF-8 encoded path of the key, prefixed with the string "file://"
* and and ending with a terminating NUL byte, and as with the blob scheme
* the #NMSetting8021x:phase2-private-key-password property must be set to
* the password used to decode the PKCS#12 private key and certificate.
* with a terminating NUL byte. When using PKCS#<!-- -->12 format private
* keys and the blob scheme, this property should be set to the
* PKCS#<!-- -->12 data and the #NMSetting8021x:phase2-private-key-password
* property must be set to password used to decrypt the PKCS#<!-- -->12
* certificate and key. When using PKCS#<!-- -->12 files and the path
* scheme, this property should be set to the full UTF-8 encoded path of the
* key, prefixed with the string "file://" and and ending with a terminating
* NUL byte, and as with the blob scheme the
* #NMSetting8021x:phase2-private-key-password property must be set to the
* password used to decode the PKCS#<!-- -->12 private key and certificate.
*
* Setting this property directly is discouraged; use the
* nm_setting_802_1x_set_phase2_private_key() function instead.
@ -3605,10 +3607,11 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *setting_class)
*
* The password used to decrypt the "phase 2" private key specified in the
* #NMSetting8021x:phase2-private-key property when the private key either
* uses the path scheme, or is a PKCS#12 format key. Setting this property
* directly is not generally necessary except when returning secrets to
* NetworkManager; it is generally set automatically when setting the
* private key by the nm_setting_802_1x_set_phase2_private_key() function.
* uses the path scheme, or is a PKCS#<!-- -->12 format key. Setting this
* property directly is not generally necessary except when returning
* secrets to NetworkManager; it is generally set automatically when setting
* the private key by the nm_setting_802_1x_set_phase2_private_key()
* function.
**/
g_object_class_install_property
(object_class, PROP_PHASE2_PRIVATE_KEY_PASSWORD,

2
libnm-core/nm-setting-8021x.h
View file

@ -37,7 +37,7 @@ G_BEGIN_DECLS
* @NM_SETTING_802_1X_CK_FORMAT_X509: file contains an X.509 format certificate
* @NM_SETTING_802_1X_CK_FORMAT_RAW_KEY: file contains an old-style OpenSSL PEM
* or DER private key
* @NM_SETTING_802_1X_CK_FORMAT_PKCS12: file contains a PKCS#12 certificate
* @NM_SETTING_802_1X_CK_FORMAT_PKCS12: file contains a PKCS#<!-- -->12 certificate
* and private key
*
* #NMSetting8021xCKFormat values indicate the general type of a certificate

3
libnm-core/nm-setting-bluetooth.c
View file

@ -79,7 +79,8 @@ NMSetting *nm_setting_bluetooth_new (void)
* Returns the connection method for communicating with the remote device (i.e.
* either DUN to a DUN-capable device or PANU to a NAP-capable device).
*
* Returns: the type, either %NM_SETTING_BLUETOOTH_PANU or %NM_SETTING_BLUETOOTH_DUN
* Returns: the type, either %NM_SETTING_BLUETOOTH_TYPE_PANU or
* %NM_SETTING_BLUETOOTH_TYPE_DUN
**/
const char *
nm_setting_bluetooth_get_connection_type (NMSettingBluetooth *setting)

4
libnm-core/nm-utils.c
View file

@ -2233,9 +2233,9 @@ nm_utils_rsa_key_encrypt_aes (const guint8 *data,
* nm_utils_file_is_pkcs12:
* @filename: name of the file to test
*
* Utility function to find out if the @filename is in PKCS#12 format.
* Utility function to find out if the @filename is in PKCS#<!-- -->12 format.
*
* Returns: %TRUE if the file is PKCS#12, %FALSE if it is not
* Returns: %TRUE if the file is PKCS#<!-- -->12, %FALSE if it is not
**/
gboolean
nm_utils_file_is_pkcs12 (const char *filename)

3
libnm/nm-device.c
View file

@ -1568,8 +1568,7 @@ get_short_vendor (NMDevice *device)
* nm_device_get_description:
* @device: an #NMDevice
*
* Gets a description of @device, incorporating the results of
* nm_device_get_short_vendor() and nm_device_get_short_product().
* Gets a description of @device, based on its vendor and product names.
*
* Returns: a description of @device. If either the vendor or the
* product name is unknown, this returns the interface name.

2
libnm/nm-types.h
View file

@ -49,8 +49,6 @@ typedef struct _NMObject NMObject;
typedef struct _NMRemoteConnection NMRemoteConnection;
typedef struct _NMSecretAgent NMSecretAgent;
typedef struct _NMVpnConnection NMVpnConnection;
typedef struct _NMVpnEditorPlugin NMVpnEditorPlugin;
typedef struct _NMVpnEditor NMVpnEditor;
typedef struct _NMWimaxNsp NMWimaxNsp;
#endif /* NM_TYPES_H */

67
libnm/nm-vpn-editor-plugin.h
View file

@ -32,6 +32,9 @@
G_BEGIN_DECLS
typedef struct _NMVpnEditorPlugin NMVpnEditorPlugin;
typedef struct _NMVpnEditor NMVpnEditor;
/* Plugin's factory function that returns a GObject that implements
* NMVpnEditorPlugin.
*/
@ -75,41 +78,44 @@ typedef enum /*< flags >*/ {
/* D-Bus service name of the plugin's VPN service */
#define NM_VPN_EDITOR_PLUGIN_SERVICE "service"
/**
* NMVpnEditorPluginInterface:
* @g_iface: the parent interface
* @get_editor: returns an #NMVpnEditor, pre-filled with values from @connection
* if non-%NULL.
* @get_capabilities: returns a bitmask of capabilities.
* @import_from_file: Try to import a connection from the specified path. On
* success, return a partial #NMConnection object. On error, return %NULL and
* set @error with additional information. Note that @error can be %NULL, in
* which case no additional error information should be provided.
* @export_to_file: Export the given connection to the specified path. Return
* %TRUE on success. On error, return %FALSE and set @error with additional
* error information. Note that @error can be %NULL, in which case no
* additional error information should be provided.
* @get_suggested_filename: For a given connection, return a suggested file
* name. Returned value will be %NULL or a suggested file name to be freed by
* the caller.
*
* Interface for VPN editor plugins.
*/
typedef struct {
GTypeInterface g_iface;
/* Returns an #NMVpnEditor, pre-filled with values from @connection if
* non-%NULL.
*/
NMVpnEditor * (*get_editor) (NMVpnEditorPlugin *plugin,
NMConnection *connection,
GError **error);
/* Plugin's capabiltity function that returns a bitmask of capabilities. */
NMVpnEditorPluginCapability (*get_capabilities) (NMVpnEditorPlugin *plugin);
/* Try to import a connection from the specified path. On success, return a
* partial #NMConnection object. On error, return %NULL and set @error with
* additional information. Note that @error can be %NULL, in which case no
* additional error information should be provided.
*/
NMConnection * (*import_from_file) (NMVpnEditorPlugin *plugin,
const char *path,
GError **error);
/* Export the given connection to the specified path. Return %TRUE on success.
* On error, return %FALSE and set @error with additional error information.
* Note that @error can be %NULL, in which case no additional error information
* should be provided.
*/
gboolean (*export_to_file) (NMVpnEditorPlugin *plugin,
const char *path,
NMConnection *connection,
GError **error);
/* For a given connection, return a suggested file name. Returned value
* will be %NULL or a suggested file name to be freed by the caller.
*/
char * (*get_suggested_filename) (NMVpnEditorPlugin *plugin, NMConnection *connection);
} NMVpnEditorPluginInterface;
@ -140,28 +146,33 @@ char *nm_vpn_editor_plugin_get_suggested_filename (NMVpnEditorPlugin *pl
#define NM_IS_VPN_EDITOR(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), NM_TYPE_VPN_EDITOR))
#define NM_VPN_EDITOR_GET_INTERFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), NM_TYPE_VPN_EDITOR, NMVpnEditorInterface))
/**
* NMVpnEditorInterface:
* @g_iface: the parent interface
* @get_widget: return the #GtkWidget for the VPN editor's UI
* @placeholder: not currently used
* @update_connection: called to save the user-entered options to the connection
* object. Should return %FALSE and set @error if the current options are
* invalid. @error should contain enough information for the plugin to
* determine which UI widget is invalid at a later point in time. For
* example, creating unique error codes for what error occurred and populating
* the message field of @error with the name of the invalid property.
* @changed: emitted when the value of a UI widget changes. May trigger a
* validity check via @update_connection to write values to the connection.
*
* Interface for editing a specific #NMConnection
*/
typedef struct {
GTypeInterface g_iface;
/* Return the #GtkWidget for the VPN editor's UI */
GObject * (*get_widget) (NMVpnEditor *editor);
void (*placeholder) (void);
/* Called to save the user-entered options to the connection object. Should
* return %FALSE and set @error if the current options are invalid. @error
* should contain enough information for the plugin to determine which UI
* widget is invalid at a later point in time. For example, creating unique
* error codes for what error occurred and populating the message field
* of @error with the name of the invalid property.
*/
gboolean (*update_connection) (NMVpnEditor *editor,
NMConnection *connection,
GError **error);
/* Emitted when the value of a UI widget changes. May trigger a validity
* check via update_connection() to write values to the connection.
*/
void (*changed) (NMVpnEditor *editor);
} NMVpnEditorInterface;

9
libnm/nm-wimax-nsp.h
View file

@ -41,6 +41,15 @@ G_BEGIN_DECLS
#define NM_WIMAX_NSP_SIGNAL_QUALITY "signal-quality"
#define NM_WIMAX_NSP_NETWORK_TYPE "network-type"
/**
* NMWimaxNspNetworkType:
* @NM_WIMAX_NSP_NETWORK_TYPE_UNKNOWN: unknown network type
* @NM_WIMAX_NSP_NETWORK_TYPE_HOME: home network
* @NM_WIMAX_NSP_NETWORK_TYPE_PARTNER: partner network
* @NM_WIMAX_NSP_NETWORK_TYPE_ROAMING_PARTNER: roaming partner network
*
* WiMAX network type.
*/
typedef enum {
NM_WIMAX_NSP_NETWORK_TYPE_UNKNOWN = 0,
NM_WIMAX_NSP_NETWORK_TYPE_HOME = 1,