diff --git a/ChangeLog b/ChangeLog index f50cf958ac..fe7ca6808e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2008-08-12 Tambet Ingo + + * libnm-glib/*.c. Document some more. + 2008-08-12 Tambet Ingo Start documenting libnm-glib public API using gtk-doc. diff --git a/docs/libnm-glib/libnm-glib-docs.sgml b/docs/libnm-glib/libnm-glib-docs.sgml new file mode 100644 index 0000000000..5a3ca81b86 --- /dev/null +++ b/docs/libnm-glib/libnm-glib-docs.sgml @@ -0,0 +1,38 @@ + + + + + libnm-glib Reference Manual + + for libnm-glib [VERSION] + The latest version of this documentation can be found on-line at + http://[SERVER]/libnm-glib/. + + + + + [Insert title here] + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/libnm-glib/libnm-glib.types b/docs/libnm-glib/libnm-glib.types index 9adb5ac5d2..8c5fcf754e 100644 --- a/docs/libnm-glib/libnm-glib.types +++ b/docs/libnm-glib/libnm-glib.types @@ -4,6 +4,10 @@ #include #include #include +#include +#include +#include +#include nm_object_get_type nm_client_get_type @@ -13,3 +17,7 @@ nm_device_wifi_get_type nm_gsm_device_get_type nm_cdma_device_get_type nm_serial_device_get_type +nm_access_point_get_type +nm_ip4_config_get_type +nm_active_connection_get_type +nm_dhcp4_config_get_type diff --git a/libnm-glib/nm-access-point.c b/libnm-glib/nm-access-point.c index c06a161fd9..fba7532501 100644 --- a/libnm-glib/nm-access-point.c +++ b/libnm-glib/nm-access-point.c @@ -53,6 +53,15 @@ enum { #define DBUS_PROP_MAX_BITRATE "MaxBitrate" #define DBUS_PROP_STRENGTH "Strength" +/** + * nm_access_point_new: + * @connection: the #DBusGConnection + * @path: the DBusobject path of the access point + * + * Creates a new #NMAccessPoint. + * + * Returns: a new access point + **/ GObject * nm_access_point_new (DBusGConnection *connection, const char *path) { @@ -65,6 +74,14 @@ nm_access_point_new (DBusGConnection *connection, const char *path) NULL); } +/** + * nm_access_point_get_flags: + * @ap: a #NMAccessPoint + * + * Gets the flags of the access point + * + * Returns: the flags + **/ guint32 nm_access_point_get_flags (NMAccessPoint *ap) { @@ -82,6 +99,14 @@ nm_access_point_get_flags (NMAccessPoint *ap) return priv->flags; } +/** + * nm_access_point_get_wpa_flags: + * @ap: a #NMAccessPoint + * + * Gets the WPA flags of the access point. + * + * Returns: the WPA flags + **/ guint32 nm_access_point_get_wpa_flags (NMAccessPoint *ap) { @@ -99,6 +124,14 @@ nm_access_point_get_wpa_flags (NMAccessPoint *ap) return priv->wpa_flags; } +/** + * nm_access_point_get_rsn_flags: + * @ap: a #NMAccessPoint + * + * Gets the RSN flags of the access point. + * + * Returns: the RSN flags + **/ guint32 nm_access_point_get_rsn_flags (NMAccessPoint *ap) { @@ -116,6 +149,15 @@ nm_access_point_get_rsn_flags (NMAccessPoint *ap) return priv->rsn_flags; } +/** + * nm_access_point_get_ssid: + * @ap: a #NMAccessPoint + * + * Gets the SSID of the access point. + * + * Returns: the #GByteArray containing the SSID. This is the internal copy used by the + * access point, and must not be modified. + **/ const GByteArray * nm_access_point_get_ssid (NMAccessPoint *ap) { @@ -133,6 +175,14 @@ nm_access_point_get_ssid (NMAccessPoint *ap) return priv->ssid; } +/** + * nm_access_point_get_frequency: + * @ap: a #NMAccessPoint + * + * Gets the frequency of the access point. + * + * Returns: the frequency + **/ guint32 nm_access_point_get_frequency (NMAccessPoint *ap) { @@ -150,6 +200,15 @@ nm_access_point_get_frequency (NMAccessPoint *ap) return priv->frequency; } +/** + * nm_access_point_get_hw_address: + * @ap: a #NMAccessPoint + * + * Gets the hardware (MAC) address of the access point. + * + * Returns: the hardware address of the access point. This is the internal string used by the + * access point and must not be modified. + **/ const char * nm_access_point_get_hw_address (NMAccessPoint *ap) { @@ -167,6 +226,14 @@ nm_access_point_get_hw_address (NMAccessPoint *ap) return priv->hw_address; } +/** + * nm_access_point_get_mode: + * @ap: a #NMAccessPoint + * + * Gets the mode of the access point. + * + * Returns: the mode + **/ NM80211Mode nm_access_point_get_mode (NMAccessPoint *ap) { @@ -184,6 +251,14 @@ nm_access_point_get_mode (NMAccessPoint *ap) return priv->mode; } +/** + * nm_access_point_get_max_bitrate: + * @ap: a #NMAccessPoint + * + * Gets the maximum bit rate of the access point. + * + * Returns: the maximum bit rate + **/ guint32 nm_access_point_get_max_bitrate (NMAccessPoint *ap) { @@ -201,6 +276,14 @@ nm_access_point_get_max_bitrate (NMAccessPoint *ap) return priv->max_bitrate; } +/** + * nm_access_point_get_strength: + * @ap: + * + * Gets the current signal strength of the access point. + * + * Returns: the signal strength + **/ guint8 nm_access_point_get_strength (NMAccessPoint *ap) { @@ -371,6 +454,12 @@ nm_access_point_class_init (NMAccessPointClass *ap_class) object_class->finalize = finalize; /* properties */ + + /** + * NMAccessPoint:flags: + * + * The flags of the access point. + **/ g_object_class_install_property (object_class, PROP_FLAGS, g_param_spec_uint (NM_ACCESS_POINT_FLAGS, @@ -381,6 +470,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class) NM_802_11_AP_FLAGS_NONE, G_PARAM_READABLE)); + /** + * NMAccessPoint:wpa-flags: + * + * The WPA flags of the access point. + **/ g_object_class_install_property (object_class, PROP_WPA_FLAGS, g_param_spec_uint (NM_ACCESS_POINT_WPA_FLAGS, @@ -389,6 +483,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class) 0, G_MAXUINT32, 0, G_PARAM_READABLE)); + /** + * NMAccessPoint:rsn-flags: + * + * The RSN flags of the access point. + **/ g_object_class_install_property (object_class, PROP_RSN_FLAGS, g_param_spec_uint (NM_ACCESS_POINT_RSN_FLAGS, @@ -397,6 +496,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class) 0, G_MAXUINT32, 0, G_PARAM_READABLE)); + /** + * NMAccessPoint:ssid: + * + * The SSID of the access point. + **/ g_object_class_install_property (object_class, PROP_SSID, g_param_spec_boxed (NM_ACCESS_POINT_SSID, @@ -405,6 +509,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class) NM_TYPE_SSID, G_PARAM_READABLE)); + /** + * NMAccessPoint:frequency: + * + * The frequency of the access point. + **/ g_object_class_install_property (object_class, PROP_FREQUENCY, g_param_spec_uint (NM_ACCESS_POINT_FREQUENCY, @@ -413,6 +522,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class) 0, 10000, 0, G_PARAM_READABLE)); + /** + * NMAccessPoint:hw-address: + * + * The hardware address of the access point. + **/ g_object_class_install_property (object_class, PROP_HW_ADDRESS, g_param_spec_string (NM_ACCESS_POINT_HW_ADDRESS, @@ -421,6 +535,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class) NULL, G_PARAM_READABLE)); + /** + * NMAccessPoint:mode: + * + * The mode of the access point. + **/ g_object_class_install_property (object_class, PROP_MODE, g_param_spec_uint (NM_ACCESS_POINT_MODE, @@ -429,6 +548,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class) NM_802_11_MODE_ADHOC, NM_802_11_MODE_INFRA, NM_802_11_MODE_INFRA, G_PARAM_READABLE)); + /** + * NMAccessPoint:max-bitrate: + * + * The maximum bit rate of the access point. + **/ g_object_class_install_property (object_class, PROP_MAX_BITRATE, g_param_spec_uint (NM_ACCESS_POINT_MAX_BITRATE, @@ -437,6 +561,11 @@ nm_access_point_class_init (NMAccessPointClass *ap_class) 0, G_MAXUINT32, 0, G_PARAM_READABLE)); + /** + * NMAccessPoint:strength: + * + * The current signal strength of the access point. + **/ g_object_class_install_property (object_class, PROP_STRENGTH, g_param_spec_uchar (NM_ACCESS_POINT_STRENGTH, diff --git a/libnm-glib/nm-active-connection.c b/libnm-glib/nm-active-connection.c index 9d2eac719a..3d3e3b67e3 100644 --- a/libnm-glib/nm-active-connection.c +++ b/libnm-glib/nm-active-connection.c @@ -50,6 +50,15 @@ enum { #define DBUS_PROP_STATE "State" #define DBUS_PROP_DEFAULT "Default" +/** + * nm_active_connection_new: + * @connection: the #DBusGConnection + * @path: the DBus object path of the device + * + * Creates a new #NMActiveConnection. + * + * Returns: a new active connection + **/ GObject * nm_active_connection_new (DBusGConnection *connection, const char *path) { @@ -73,6 +82,15 @@ get_scope_for_service_name (const char *service_name) return NM_CONNECTION_SCOPE_UNKNOWN; } +/** + * nm_active_connection_get_service_name: + * @connection: a #NMActiveConnection + * + * Gets the service name of the active connection. + * + * Returns: the service name. This is the internal string used by the + * connection, and must not be modified. + **/ const char * nm_active_connection_get_service_name (NMActiveConnection *connection) { @@ -91,6 +109,14 @@ nm_active_connection_get_service_name (NMActiveConnection *connection) return priv->service_name; } +/** + * nm_active_connection_get_scope: + * @connection: a #NMActiveConnection + * + * Gets the scope of the active connection. + * + * Returns: the connection's scope + **/ NMConnectionScope nm_active_connection_get_scope (NMActiveConnection *connection) { @@ -101,6 +127,15 @@ nm_active_connection_get_scope (NMActiveConnection *connection) return NM_ACTIVE_CONNECTION_GET_PRIVATE (connection)->scope; } +/** + * nm_active_connection_get_connection: + * @connection: a #NMActiveConnection + * + * Gets the #NMConnection's DBus object path. + * + * Returns: the object path of the #NMConnection inside of #NMActiveConnection. + * This is the internal string used by the connection, and must not be modified. + **/ const char * nm_active_connection_get_connection (NMActiveConnection *connection) { @@ -118,6 +153,15 @@ nm_active_connection_get_connection (NMActiveConnection *connection) return priv->connection; } +/** + * nm_active_connection_get_specific_object: + * @connection: a #NMActiveConnection + * + * Gets the "specific object" used at the activation. + * + * Returns: the specific object's DBus path. This is the internal string used by the + * connection, and must not be modified. + **/ const char * nm_active_connection_get_specific_object (NMActiveConnection *connection) { @@ -135,6 +179,15 @@ nm_active_connection_get_specific_object (NMActiveConnection *connection) return priv->specific_object; } +/** + * nm_active_connection_get_devices: + * @connection: a #NMActiveConnection + * + * Gets the #NMDevices used for the active connections. + * + * Returns: the #GPtrArray containing #NMDevices. + * This is the internal copy used by the connection, and must not be modified. + **/ const GPtrArray * nm_active_connection_get_devices (NMActiveConnection *connection) { @@ -160,6 +213,14 @@ nm_active_connection_get_devices (NMActiveConnection *connection) return handle_ptr_array_return (priv->devices); } +/** + * nm_active_connection_get_state: + * @connection: a #NMActiveConnection + * + * Gets the active connection's state. + * + * Returns: the state + **/ NMActiveConnectionState nm_active_connection_get_state (NMActiveConnection *connection) { @@ -177,6 +238,15 @@ nm_active_connection_get_state (NMActiveConnection *connection) return priv->state; } +/** + * nm_active_connection_get_default: + * @connection: a #NMActiveConnection + * + * Whether the active connection is the default one (that is, is used for the default route + * and DNS information). + * + * Returns: %TRUE if the active connection is the default one + **/ gboolean nm_active_connection_get_default (NMActiveConnection *connection) { @@ -350,6 +420,12 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class) object_class->finalize = finalize; /* properties */ + + /** + * NMActiveConnection:service-name: + * + * The service name of the active connection. + **/ g_object_class_install_property (object_class, PROP_SERVICE_NAME, g_param_spec_string (NM_ACTIVE_CONNECTION_SERVICE_NAME, @@ -358,6 +434,11 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class) NULL, G_PARAM_READABLE)); + /** + * NMActiveConnection:connection: + * + * The connection's path of the active connection. + **/ g_object_class_install_property (object_class, PROP_CONNECTION, g_param_spec_string (NM_ACTIVE_CONNECTION_CONNECTION, @@ -366,6 +447,11 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class) NULL, G_PARAM_READABLE)); + /** + * NMActiveConnection:specific-object: + * + * The specific object's path of the active connection. + **/ g_object_class_install_property (object_class, PROP_SPECIFIC_OBJECT, g_param_spec_string (NM_ACTIVE_CONNECTION_SPECIFIC_OBJECT, @@ -374,6 +460,11 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class) NULL, G_PARAM_READABLE)); + /** + * NMActiveConnection:device: + * + * The devices (#NMDevice) of the active connection. + **/ g_object_class_install_property (object_class, PROP_DEVICES, g_param_spec_boxed (NM_ACTIVE_CONNECTION_DEVICES, @@ -382,6 +473,11 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class) NM_TYPE_OBJECT_ARRAY, G_PARAM_READABLE)); + /** + * NMActiveConnection:state: + * + * The state of the active connection. + **/ g_object_class_install_property (object_class, PROP_STATE, g_param_spec_uint (NM_ACTIVE_CONNECTION_STATE, @@ -392,6 +488,11 @@ nm_active_connection_class_init (NMActiveConnectionClass *ap_class) NM_ACTIVE_CONNECTION_STATE_UNKNOWN, G_PARAM_READABLE)); + /** + * NMActiveConnection:default: + * + * Whether the active connection is the default one. + **/ g_object_class_install_property (object_class, PROP_DEFAULT, g_param_spec_boolean (NM_ACTIVE_CONNECTION_DEFAULT, diff --git a/libnm-glib/nm-dhcp4-config.c b/libnm-glib/nm-dhcp4-config.c index 742bbe8812..a01be523c2 100644 --- a/libnm-glib/nm-dhcp4-config.c +++ b/libnm-glib/nm-dhcp4-config.c @@ -139,6 +139,12 @@ nm_dhcp4_config_class_init (NMDHCP4ConfigClass *config_class) object_class->finalize = finalize; /* properties */ + + /** + * NMDHCP4Config:options: + * + * The #GHashTable containing options of the configuration. + **/ g_object_class_install_property (object_class, PROP_OPTIONS, g_param_spec_boxed (NM_DHCP4_CONFIG_OPTIONS, @@ -148,6 +154,15 @@ nm_dhcp4_config_class_init (NMDHCP4ConfigClass *config_class) G_PARAM_READABLE)); } +/** + * nm_dhcp4_config_new: + * @connection: the #DBusGConnection + * @object_path: the DBus object path of the device + * + * Creates a new #NMDHCP4Config. + * + * Returns: a new configuration + **/ GObject * nm_dhcp4_config_new (DBusGConnection *connection, const char *object_path) { @@ -157,6 +172,15 @@ nm_dhcp4_config_new (DBusGConnection *connection, const char *object_path) NULL); } +/** + * nm_dhcp4_config_get_options: + * @self: a #NMDHCP4Config + * + * Gets all the options contained in the configuration. + * + * Returns: the #GHashTable containing strings for keys and values. + * This is the internal copy used by the configuration, and must not be modified. + **/ GHashTable * nm_dhcp4_config_get_options (NMDHCP4Config *self) { @@ -179,6 +203,16 @@ out: return priv->options; } +/** + * nm_dhcp4_config_get_one_option: + * @self: a #NMDHCP4Config + * @option: the option to retrieve + * + * Gets one option by option name. + * + * Returns: the configuration option's value. This is the internal string used by the + * configuration, and must not be modified. + **/ const char * nm_dhcp4_config_get_one_option (NMDHCP4Config *self, const char *option) { diff --git a/libnm-glib/nm-ip4-config.c b/libnm-glib/nm-ip4-config.c index 95bdb4dc29..dac3085eaa 100644 --- a/libnm-glib/nm-ip4-config.c +++ b/libnm-glib/nm-ip4-config.c @@ -200,6 +200,12 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class) object_class->finalize = finalize; /* properties */ + + /** + * NMIP4Config:addresses: + * + * The #GPtrArray containing #NMSettingIP4Addresses of the configuration. + **/ g_object_class_install_property (object_class, PROP_ADDRESSES, g_param_spec_pointer (NM_IP4_CONFIG_ADDRESSES, @@ -207,6 +213,11 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class) "Addresses", G_PARAM_READABLE)); + /** + * NMIP4Config:hostname: + * + * The host name string of the configuration. + **/ g_object_class_install_property (object_class, PROP_HOSTNAME, g_param_spec_string (NM_IP4_CONFIG_HOSTNAME, @@ -215,6 +226,11 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class) NULL, G_PARAM_READABLE)); + /** + * NMIP4Config:nameservers: + * + * The #GArray containing name servers (%guint32es) of the configuration. + **/ g_object_class_install_property (object_class, PROP_NAMESERVERS, g_param_spec_boxed (NM_IP4_CONFIG_NAMESERVERS, @@ -223,6 +239,11 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class) NM_TYPE_UINT_ARRAY, G_PARAM_READABLE)); + /** + * NMIP4Config:domains: + * + * The #GPtrArray containing domain strings of the configuration. + **/ g_object_class_install_property (object_class, PROP_DOMAINS, g_param_spec_boxed (NM_IP4_CONFIG_DOMAINS, @@ -231,6 +252,11 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class) NM_TYPE_STRING_ARRAY, G_PARAM_READABLE)); + /** + * NMIP4Config:routes: + * + * The #GPtrArray containing #NMSettingIP4Routes of the configuration. + **/ g_object_class_install_property (object_class, PROP_ROUTES, g_param_spec_pointer (NM_IP4_CONFIG_ROUTES, @@ -239,6 +265,15 @@ nm_ip4_config_class_init (NMIP4ConfigClass *config_class) G_PARAM_READABLE)); } +/** + * nm_ip4_config_new: + * @connection: the #DBusGConnection + * @object_path: the DBus object path of the device + * + * Creates a new #NMIP4Config. + * + * Returns: a new IP4 configuration + **/ GObject * nm_ip4_config_new (DBusGConnection *connection, const char *object_path) { @@ -248,6 +283,15 @@ nm_ip4_config_new (DBusGConnection *connection, const char *object_path) NULL); } +/** + * nm_ip4_config_get_addresses: + * @config: a #NMIP4Config + * + * Gets the IP4 addresses (containing the address, prefix, and gateway). + * + * Returns: the #GSList containing #NMSettingIP4Addresses. This is the internal copy + * used by the configuration and must not be modified. + **/ const GSList * nm_ip4_config_get_addresses (NMIP4Config *config) { @@ -273,6 +317,15 @@ nm_ip4_config_get_addresses (NMIP4Config *config) return priv->addresses; } +/** + * nm_ip4_config_get_hostname: + * @config: a #NMIP4Config + * + * Gets the host name. + * + * Returns: the host name from the configuration. This is the internal copy used by the + * configuration and must not be modified. + **/ const char * nm_ip4_config_get_hostname (NMIP4Config *config) { @@ -290,6 +343,15 @@ nm_ip4_config_get_hostname (NMIP4Config *config) return priv->hostname; } +/** + * nm_ip4_config_get_nameservers: + * @config: a #NMIP4Config + * + * Gets the domain name servers (DNS). + * + * Returns: the #GArray containing %guint32s. This is the internal copy used by the + * configuration and must not be modified. + **/ const GArray * nm_ip4_config_get_nameservers (NMIP4Config *config) { @@ -316,7 +378,15 @@ nm_ip4_config_get_nameservers (NMIP4Config *config) return priv->nameservers; } - +/** + * nm_ip4_config_get_domains: + * @config: a #NMIP4Config + * + * Gets the domain names. + * + * Returns: the #GPtrArray containing domains as strings. This is the + * internal copy used by the configuration, and must not be modified. + **/ const GPtrArray * nm_ip4_config_get_domains (NMIP4Config *config) { @@ -347,6 +417,15 @@ nm_ip4_config_get_domains (NMIP4Config *config) return handle_ptr_array_return (priv->domains); } +/** + * nm_ip4_config_get_routes: + * @config: a #NMIP4Config + * + * Gets the routes. + * + * Returns: the #GSList containing #NMSettingIP4Routes. This is the + * internal copy used by the configuration, and must not be modified. + **/ const GSList * nm_ip4_config_get_routes (NMIP4Config *config) { diff --git a/libnm-glib/nm-settings.c b/libnm-glib/nm-settings.c index 303f93cfc5..3ac5b63340 100644 --- a/libnm-glib/nm-settings.c +++ b/libnm-glib/nm-settings.c @@ -7,6 +7,13 @@ #include "nm-dbus-glib-types.h" +/** + * nm_settings_error_quark: + * + * Setting error quark. + * + * Returns: the setting error quark + **/ GQuark nm_settings_error_quark (void) { @@ -80,6 +87,14 @@ nm_settings_class_init (NMSettingsClass *settings_class) settings_class->list_connections = NULL; /* signals */ + + /** + * NMSettings::new-connection: + * @setting: the setting that received the signal + * @connection: the new #NMExportedConnection + * + * Notifies that a new exported connection is added. + **/ settings_signals[S_NEW_CONNECTION] = g_signal_new ("new-connection", G_OBJECT_CLASS_TYPE (object_class), @@ -94,6 +109,14 @@ nm_settings_class_init (NMSettingsClass *settings_class) &dbus_glib_nm_settings_object_info); } +/** + * nm_settings_list_connections: + * @settings: + * + * Lists all the available connections. + * + * Returns: the #GSList containing #NMExportedConnections + **/ GSList * nm_settings_list_connections (NMSettings *settings) {