diff options
author | Dan Winship <danw@gnome.org> | 2014-11-07 12:38:17 -0500 |
---|---|---|
committer | Dan Winship <danw@gnome.org> | 2014-11-07 13:16:54 -0500 |
commit | cbabd135818fd4749ad0b827ba1f0bc444b92a97 (patch) | |
tree | 24433faa3c0077c5865525b7878833c9a2f3891b | |
parent | 941897cc9721997d106e2ab7ac438dafe441fb4e (diff) | |
download | NetworkManager-cbabd135818fd4749ad0b827ba1f0bc444b92a97.tar.gz |
libnm, docs: docs fixes
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 "<". Also, "PKCS#12" has to be written as
"PKCS#<!-- -->12", or gtk-doc will think "#12" is a reference to a
type named "12".)
-rw-r--r-- | docs/libnm/Makefile.am | 11 | ||||
-rw-r--r-- | docs/libnm/libnm-docs.xml | 10 | ||||
-rw-r--r-- | libnm-core/nm-connection.h | 7 | ||||
-rw-r--r-- | libnm-core/nm-dbus-interface.h | 2 | ||||
-rw-r--r-- | libnm-core/nm-errors.h | 12 | ||||
-rw-r--r-- | libnm-core/nm-setting-8021x.c | 57 | ||||
-rw-r--r-- | libnm-core/nm-setting-8021x.h | 2 | ||||
-rw-r--r-- | libnm-core/nm-setting-bluetooth.c | 3 | ||||
-rw-r--r-- | libnm-core/nm-utils.c | 4 | ||||
-rw-r--r-- | libnm/nm-device.c | 3 | ||||
-rw-r--r-- | libnm/nm-types.h | 2 | ||||
-rw-r--r-- | libnm/nm-vpn-editor-plugin.h | 67 | ||||
-rw-r--r-- | libnm/nm-wimax-nsp.h | 9 |
13 files changed, 114 insertions, 75 deletions
diff --git a/docs/libnm/Makefile.am b/docs/libnm/Makefile.am index 2d1200b485..e04d1722bf 100644 --- a/docs/libnm/Makefile.am +++ b/docs/libnm/Makefile.am @@ -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 diff --git a/docs/libnm/libnm-docs.xml b/docs/libnm/libnm-docs.xml index e722a30964..2bb9f37521 100644 --- a/docs/libnm/libnm-docs.xml +++ b/docs/libnm/libnm-docs.xml @@ -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"> diff --git a/libnm-core/nm-connection.h b/libnm-core/nm-connection.h index 2f9883c33d..c76ad60768 100644 --- a/libnm-core/nm-connection.h +++ b/libnm-core/nm-connection.h @@ -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; diff --git a/libnm-core/nm-dbus-interface.h b/libnm-core/nm-dbus-interface.h index b4cbd1793e..ccf21ee14a 100644 --- a/libnm-core/nm-dbus-interface.h +++ b/libnm-core/nm-dbus-interface.h @@ -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; diff --git a/libnm-core/nm-errors.h b/libnm-core/nm-errors.h index fa6919c569..a9857445b7 100644 --- a/libnm-core/nm-errors.h +++ b/libnm-core/nm-errors.h @@ -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 "<setting-name>: ", where "<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 "<setting-name>: ", where "<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 "<setting-name>.<property-name>: ", where "<setting-name>" is + * the name of the setting with the missing property, and "<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 "<setting-name>.<property-name>: ", where "<setting-name>" is + * the name of the setting with the invalid property, and "<property-name>" is * the property that is invalid. * * Describes errors that may result from operations involving a #NMConnection diff --git a/libnm-core/nm-setting-8021x.c b/libnm-core/nm-setting-8021x.c index a1019060d1..6b202dd4ff 100644 --- a/libnm-core/nm-setting-8021x.c +++ b/libnm-core/nm-setting-8021x.c @@ -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, diff --git a/libnm-core/nm-setting-8021x.h b/libnm-core/nm-setting-8021x.h index 10338de998..43885daaa3 100644 --- a/libnm-core/nm-setting-8021x.h +++ b/libnm-core/nm-setting-8021x.h @@ -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 diff --git a/libnm-core/nm-setting-bluetooth.c b/libnm-core/nm-setting-bluetooth.c index 952dd61b51..6b169301ba 100644 --- a/libnm-core/nm-setting-bluetooth.c +++ b/libnm-core/nm-setting-bluetooth.c @@ -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) diff --git a/libnm-core/nm-utils.c b/libnm-core/nm-utils.c index 5356399baa..12ad1f2d50 100644 --- a/libnm-core/nm-utils.c +++ b/libnm-core/nm-utils.c @@ -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) diff --git a/libnm/nm-device.c b/libnm/nm-device.c index 29f5db8d33..ba5dbacb85 100644 --- a/libnm/nm-device.c +++ b/libnm/nm-device.c @@ -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. diff --git a/libnm/nm-types.h b/libnm/nm-types.h index 2e62ffdea3..3602878a6a 100644 --- a/libnm/nm-types.h +++ b/libnm/nm-types.h @@ -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 */ diff --git a/libnm/nm-vpn-editor-plugin.h b/libnm/nm-vpn-editor-plugin.h index 76b365876e..5910aa3653 100644 --- a/libnm/nm-vpn-editor-plugin.h +++ b/libnm/nm-vpn-editor-plugin.h @@ -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; diff --git a/libnm/nm-wimax-nsp.h b/libnm/nm-wimax-nsp.h index a8f9105268..cdc7b23665 100644 --- a/libnm/nm-wimax-nsp.h +++ b/libnm/nm-wimax-nsp.h @@ -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, |