GNOME.org
 

[gnome-bluetooth] Update API docs

commit 3a776210771f11b85c9353f2ed973ff0cea5cda5
Author: Bastien Nocera <hadess hadess net>
Date:   Wed Sep 23 17:21:12 2009 +0100

    Update API docs
    
    Add BluetoothClient and plugin documentations, update the others.

 .../libgnome-bluetooth/gnome-bluetooth-docs.sgml   |    2 +
 .../libgnome-bluetooth/tmpl/bluetooth-enums.sgml   |   86 ++++++++++++++++++++
 lib/bluetooth-chooser-button.c                     |    8 +-
 lib/bluetooth-chooser.c                            |    2 -
 lib/bluetooth-client.c                             |   84 +++++++++++++++++++-
 lib/bluetooth-enums.h                              |   61 ++++++++++++++
 lib/bluetooth-plugin-manager.c                     |    3 +
 lib/bluetooth-plugin.h                             |   31 ++++++--
 8 files changed, 263 insertions(+), 14 deletions(-)
---
diff --git a/docs/reference/libgnome-bluetooth/gnome-bluetooth-docs.sgml b/docs/reference/libgnome-bluetooth/gnome-bluetooth-docs.sgml
index f8939a5..7247c69 100644
--- a/docs/reference/libgnome-bluetooth/gnome-bluetooth-docs.sgml
+++ b/docs/reference/libgnome-bluetooth/gnome-bluetooth-docs.sgml
@@ -18,7 +18,9 @@
   <chapter>
     <title>API Reference</title>
         <xi:include href="xml/bluetooth-chooser.xml"/>
+    <xi:include href="xml/bluetooth-client.xml"/>
     <xi:include href="xml/bluetooth-chooser-button.xml"/>
+    <xi:include href="xml/bluetooth-plugin.xml"/>
     <xi:include href="xml/bluetooth-enums.xml"/>
 
   </chapter>
diff --git a/docs/reference/libgnome-bluetooth/tmpl/bluetooth-enums.sgml b/docs/reference/libgnome-bluetooth/tmpl/bluetooth-enums.sgml
new file mode 100644
index 0000000..4163f2f
--- /dev/null
+++ b/docs/reference/libgnome-bluetooth/tmpl/bluetooth-enums.sgml
@@ -0,0 +1,86 @@
+<!-- ##### SECTION Title ##### -->
+bluetooth-enums
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### ENUM BluetoothCategory ##### -->
+<para>
+
+</para>
+
+ BLUETOOTH_CATEGORY_ALL: 
+ BLUETOOTH_CATEGORY_PAIRED: 
+ BLUETOOTH_CATEGORY_TRUSTED: 
+ BLUETOOTH_CATEGORY_NOT_PAIRED_OR_TRUSTED: 
+ BLUETOOTH_CATEGORY_PAIRED_OR_TRUSTED: 
+
+<!-- ##### ENUM BluetoothType ##### -->
+<para>
+
+</para>
+
+ BLUETOOTH_TYPE_ANY: 
+ BLUETOOTH_TYPE_PHONE: 
+ BLUETOOTH_TYPE_MODEM: 
+ BLUETOOTH_TYPE_COMPUTER: 
+ BLUETOOTH_TYPE_NETWORK: 
+ BLUETOOTH_TYPE_HEADSET: 
+ BLUETOOTH_TYPE_HEADPHONES: 
+ BLUETOOTH_TYPE_OTHER_AUDIO: 
+ BLUETOOTH_TYPE_KEYBOARD: 
+ BLUETOOTH_TYPE_MOUSE: 
+ BLUETOOTH_TYPE_CAMERA: 
+ BLUETOOTH_TYPE_PRINTER: 
+ BLUETOOTH_TYPE_JOYPAD: 
+ BLUETOOTH_TYPE_TABLET: 
+
+<!-- ##### MACRO BLUETOOTH_TYPE_INPUT ##### -->
+<para>
+a bitmask for use in filters representing any input Bluetooth device.
+</para>
+
+
+
+<!-- ##### MACRO BLUETOOTH_TYPE_AUDIO ##### -->
+<para>
+a bitmask for use in filters representing any audio Bluetooth device.
+</para>
+
+
+
+<!-- ##### ENUM BluetoothColumn ##### -->
+<para>
+
+</para>
+
+ BLUETOOTH_COLUMN_PROXY: 
+ BLUETOOTH_COLUMN_ADDRESS: 
+ BLUETOOTH_COLUMN_ALIAS: 
+ BLUETOOTH_COLUMN_NAME: 
+ BLUETOOTH_COLUMN_TYPE: 
+ BLUETOOTH_COLUMN_ICON: 
+ BLUETOOTH_COLUMN_RSSI: 
+ BLUETOOTH_COLUMN_DEFAULT: 
+ BLUETOOTH_COLUMN_PAIRED: 
+ BLUETOOTH_COLUMN_TRUSTED: 
+ BLUETOOTH_COLUMN_CONNECTED: 
+ BLUETOOTH_COLUMN_DISCOVERING: 
+ BLUETOOTH_COLUMN_LEGACYPAIRING: 
+ BLUETOOTH_COLUMN_POWERED: 
+ BLUETOOTH_COLUMN_SERVICES: 
+ BLUETOOTH_COLUMN_UUIDS: 
+
diff --git a/lib/bluetooth-chooser-button.c b/lib/bluetooth-chooser-button.c
index ccc0650..d9f05c6 100644
--- a/lib/bluetooth-chooser-button.c
+++ b/lib/bluetooth-chooser-button.c
@@ -315,15 +315,13 @@ bluetooth_chooser_button_class_init (BluetoothChooserButtonClass *klass)
 	button_class->clicked = bluetooth_chooser_button_clicked;
 
 	/**
-	 * BluetoothChooserButton:chooser-created:
-	 *
-	 * @bluetoothchooserbutton: a #BluetoothChooserButton widget
-	 * @arg1: a #BluetoothChooser widget
+	 * BluetoothChooserButton::chooser-created:
+	 * @self: a #BluetoothChooserButton widget
+	 * @chooser: a #BluetoothChooser widget
 	 *
 	 * The signal is sent when a popup dialogue is created for the user to select
 	 * a device. This signal allows you to change the configuration and filtering
 	 * of the tree from its defaults.
-	 *
 	 **/
 	signals[CHOOSER_CREATED] =
 		g_signal_new ("chooser-created",
diff --git a/lib/bluetooth-chooser.c b/lib/bluetooth-chooser.c
index 4a6c247..6ce95b1 100644
--- a/lib/bluetooth-chooser.c
+++ b/lib/bluetooth-chooser.c
@@ -1107,13 +1107,11 @@ bluetooth_chooser_class_init (BluetoothChooserClass *klass)
 
 	/**
 	 * BluetoothChooser::selected-device-changed:
-	 *
 	 * @chooser: a #BluetoothChooser widget which received the signal
 	 * @address: the Bluetooth address for the currently selected device, or %NULL
 	 *
 	 * The #BluetoothChooser:selected-device-changed signal is launched when the
 	 * selected device is changed, it will be %NULL if a device was unselected.
-	 *
 	 **/
 	selection_table_signals[SELECTED_DEVICE_CHANGED] =
 		g_signal_new ("selected-device-changed",
diff --git a/lib/bluetooth-client.c b/lib/bluetooth-client.c
index 2cf0469..ff3a01f 100644
--- a/lib/bluetooth-client.c
+++ b/lib/bluetooth-client.c
@@ -102,7 +102,13 @@ enum {
 
 G_DEFINE_TYPE(BluetoothClient, bluetooth_client, G_TYPE_OBJECT)
 
-const gchar *bluetooth_type_to_string(guint type)
+/**
+ * bluetooth_type_to_string:
+ * @type: a #BluetoothType
+ *
+ * Return value: the string representation of the @type passed. Do not free the return value.
+ **/
+const gchar *bluetooth_type_to_string(BluetoothType type)
 {
 	switch (type) {
 	case BLUETOOTH_TYPE_ANY:
@@ -139,6 +145,12 @@ const gchar *bluetooth_type_to_string(guint type)
 	}
 }
 
+/**
+ * bluetooth_verify_address:
+ * @bdaddr: a string representing a Bluetooth address
+ *
+ * Return value: Whether the string is a valid Bluetooth address. This does not contact the device in any way.
+ **/
 gboolean
 bluetooth_verify_address (const char *bdaddr)
 {
@@ -508,6 +520,12 @@ uuid16_to_string (guint uuid16, const char *uuid)
 	}
 }
 
+/**
+ * bluetooth_uuid_to_string:
+ * @uuid: a string representing a Bluetooth UUID
+ *
+ * Return value: a string representing a human-readable (but not usable for display to users) version of the @uuid. Do not free the return value.
+ **/
 const char *
 bluetooth_uuid_to_string (const char *uuid)
 {
@@ -1194,6 +1212,11 @@ static void bluetooth_client_class_init(BluetoothClientClass *klass)
 	}
 }
 
+/**
+ * bluetooth_client_new:
+ *
+ * Return value: a reference to the #BluetoothClient singleton. Unref the object when done.
+ **/
 BluetoothClient *bluetooth_client_new(void)
 {
 	static BluetoothClient *bluetooth_client = NULL;
@@ -1210,6 +1233,12 @@ BluetoothClient *bluetooth_client_new(void)
 	return bluetooth_client;
 }
 
+/**
+ * bluetooth_client_get_model:
+ * @client: a #BluetoothClient object
+ *
+ * Return value: an unfiltered #GtkTreeModel representing the adapter and devices available on the system.
+ **/
 GtkTreeModel *bluetooth_client_get_model (BluetoothClient *client)
 {
 	BluetoothClientPrivate *priv;
@@ -1225,6 +1254,15 @@ GtkTreeModel *bluetooth_client_get_model (BluetoothClient *client)
 	return model;
 }
 
+/**
+ * bluetooth_client_get_filter_model:
+ * @client: a #BluetoothClient object
+ * @func: a #GtkTreeModelFilterVisibleFunc
+ * @data: user data to pass to gtk_tree_model_filter_set_visible_func()
+ * @destroy: a destroy function for gtk_tree_model_filter_set_visible_func()
+ *
+ * Return value: a #GtkTreeModel of devices filtered using the @func, @data and @destroy arguments to pass to gtk_tree_model_filter_set_visible_func().
+ **/
 GtkTreeModel *bluetooth_client_get_filter_model (BluetoothClient *client,
 						 GtkTreeModelFilterVisibleFunc func,
 						 gpointer data, GDestroyNotify destroy)
@@ -1264,6 +1302,12 @@ static gboolean adapter_filter(GtkTreeModel *model,
 	return active;
 }
 
+/**
+ * bluetooth_client_get_adapter_model:
+ * @client: a #BluetoothClient object
+ *
+ * Return value: a filtered #GtkTreeModel with only adapters present.
+ **/
 GtkTreeModel *bluetooth_client_get_adapter_model (BluetoothClient *client)
 {
 	DBG("client %p", client);
@@ -1272,6 +1316,13 @@ GtkTreeModel *bluetooth_client_get_adapter_model (BluetoothClient *client)
 						  NULL, NULL);
 }
 
+/**
+ * bluetooth_client_get_device_model:
+ * @client: a #BluetoothClient object
+ * @adapter: a #DBusGProxy of the adapter object, or %NULL to get the default adapter.
+ *
+ * Return value: a filtered #GtkTreeModel with only devices belonging to the selected adapter listed. Note that the model will follow a specific adapter, and will not follow the default-adapter when %NULL is passed.
+ **/
 GtkTreeModel *bluetooth_client_get_device_model (BluetoothClient *client,
 						 DBusGProxy *adapter)
 {
@@ -1324,6 +1375,15 @@ GtkTreeModel *bluetooth_client_get_device_model (BluetoothClient *client,
 	return model;
 }
 
+/**
+ * bluetooth_client_get_device_filter_model:
+ * @client: a #BluetoothClient object
+ * @func: a #GtkTreeModelFilterVisibleFunc
+ * @data: user data to pass to gtk_tree_model_filter_set_visible_func()
+ * @destroy: a destroy function for gtk_tree_model_filter_set_visible_func()
+ *
+ * Return value: a #GtkTreeModel of adapters filtered using the @func, @data and @destroy arguments to pass to gtk_tree_model_filter_set_visible_func().
+ **/
 GtkTreeModel *bluetooth_client_get_device_filter_model(BluetoothClient *client,
 		DBusGProxy *adapter, GtkTreeModelFilterVisibleFunc func,
 				gpointer data, GDestroyNotify destroy)
@@ -1342,6 +1402,12 @@ GtkTreeModel *bluetooth_client_get_device_filter_model(BluetoothClient *client,
 	return model;
 }
 
+/**
+ * bluetooth_client_get_default_adapter:
+ * @client: a #BluetoothClient object
+ *
+ * Return value: a #DBusGProxy object representing the default adapter, or %NULL if no adapters are present.
+ **/
 DBusGProxy *bluetooth_client_get_default_adapter(BluetoothClient *client)
 {
 	BluetoothClientPrivate *priv = BLUETOOTH_CLIENT_GET_PRIVATE(client);
@@ -1375,6 +1441,14 @@ DBusGProxy *bluetooth_client_get_default_adapter(BluetoothClient *client)
 	return NULL;
 }
 
+/**
+ * bluetooth_client_start_discovery:
+ * @client: a #BluetoothClient object
+ *
+ * Start a discovery on the default adapter.
+ *
+ * Return value: Whether a discovery was successfully started on the default adapter.
+ **/
 gboolean bluetooth_client_start_discovery(BluetoothClient *client)
 {
 	DBusGProxy *adapter;
@@ -1394,6 +1468,14 @@ gboolean bluetooth_client_start_discovery(BluetoothClient *client)
 	return TRUE;
 }
 
+/**
+ * bluetooth_client_stop_discovery:
+ * @client: a #BluetoothClient object
+ *
+ * Stop a discovery started on the default adapter.
+ *
+ * Return value: Whether a discovery was successfully stopped on the default adapter.
+ **/
 gboolean bluetooth_client_stop_discovery(BluetoothClient *client)
 {
 	DBusGProxy *adapter;
diff --git a/lib/bluetooth-enums.h b/lib/bluetooth-enums.h
index 450c38c..e033283 100644
--- a/lib/bluetooth-enums.h
+++ b/lib/bluetooth-enums.h
@@ -28,6 +28,16 @@
 
 G_BEGIN_DECLS
 
+/**
+ * BluetoothCategory:
+ * @BLUETOOTH_CATEGORY_ALL: all devices
+ * @BLUETOOTH_CATEGORY_PAIRED: paired devices
+ * @BLUETOOTH_CATEGORY_TRUSTED: trusted devices
+ * @BLUETOOTH_CATEGORY_NOT_PAIRED_OR_TRUSTED: neither paired, nor trusted devices
+ * @BLUETOOTH_CATEGORY_PAIRED_OR_TRUSTED: paired and/or trusted devices
+ *
+ * The category of a Bluetooth devices.
+ **/
 typedef enum {
 	BLUETOOTH_CATEGORY_ALL,
 	BLUETOOTH_CATEGORY_PAIRED,
@@ -37,6 +47,25 @@ typedef enum {
 	BLUETOOTH_CATEGORY_NUM_CATEGORIES /*< skip >*/
 } BluetoothCategory;
 
+/**
+ * BluetoothType:
+ * @BLUETOOTH_TYPE_ANY: any device, or a device of an unknown type
+ * @BLUETOOTH_TYPE_PHONE: a telephone (usually a cell/mobile phone)
+ * @BLUETOOTH_TYPE_MODEM: a modem
+ * @BLUETOOTH_TYPE_COMPUTER: a computer, can be a laptop, a wearable computer, etc.
+ * @BLUETOOTH_TYPE_NETWORK: a network device, such as a router
+ * @BLUETOOTH_TYPE_HEADSET: a headset (usually a hands-free device)
+ * @BLUETOOTH_TYPE_HEADPHONES: headphones (covers two ears)
+ * @BLUETOOTH_TYPE_OTHER_AUDIO: another type of audio device
+ * @BLUETOOTH_TYPE_KEYBOARD: a keyboard
+ * @BLUETOOTH_TYPE_MOUSE: a mouse
+ * @BLUETOOTH_TYPE_CAMERA: a camera (still or moving)
+ * @BLUETOOTH_TYPE_PRINTER: a printer
+ * @BLUETOOTH_TYPE_JOYPAD: a joypad, joystick, or other game controller
+ * @BLUETOOTH_TYPE_TABLET: a drawing tablet
+ *
+ * The type of a Bluetooth device. See also %BLUETOOTH_TYPE_INPUT and %BLUETOOTH_TYPE_AUDIO
+ **/
 typedef enum {
 	BLUETOOTH_TYPE_ANY		= 1 << 0,
 	BLUETOOTH_TYPE_PHONE		= 1 << 1,
@@ -59,6 +88,27 @@ typedef enum {
 #define BLUETOOTH_TYPE_INPUT (BLUETOOTH_TYPE_KEYBOARD | BLUETOOTH_TYPE_MOUSE | BLUETOOTH_TYPE_TABLET | BLUETOOTH_TYPE_JOYPAD)
 #define BLUETOOTH_TYPE_AUDIO (BLUETOOTH_TYPE_HEADSET | BLUETOOTH_TYPE_HEADPHONES | BLUETOOTH_TYPE_OTHER_AUDIO)
 
+/**
+ * BluetoothColumn:
+ * @BLUETOOTH_COLUMN_PROXY: a #DBusGProxy object
+ * @BLUETOOTH_COLUMN_ADDRESS: a string representing a Bluetooth address
+ * @BLUETOOTH_COLUMN_ALIAS: a string to use for display (the name of the device, or its address if the name is not known). Only available for devices.
+ * @BLUETOOTH_COLUMN_NAME: a string representing the device or adapter's name
+ * @BLUETOOTH_COLUMN_TYPE: the #BluetoothType of the device. Only available for devices.
+ * @BLUETOOTH_COLUMN_ICON: a string representing the icon name for the device. Only available for devices.
+ * @BLUETOOTH_COLUMN_RSSI: an indication of signal strength
+ * @BLUETOOTH_COLUMN_DEFAULT: whether the adapter is the default one. Only available for adapters.
+ * @BLUETOOTH_COLUMN_PAIRED: whether the device is paired to its parent adapter. Only available for devices.
+ * @BLUETOOTH_COLUMN_TRUSTED: whether the device is trusted. Only available for devices.
+ * @BLUETOOTH_COLUMN_CONNECTED: whether the device is connected. Only available for devices.
+ * @BLUETOOTH_COLUMN_DISCOVERING: whether the adapter is discovering. Only available for adapters.
+ * @BLUETOOTH_COLUMN_LEGACYPAIRING: whether the device does not support Bluetooth 2.1 Simple Secure Pairing. Only available for devices.
+ * @BLUETOOTH_COLUMN_POWERED: whether the adapter is powered. Only available for adapters.
+ * @BLUETOOTH_COLUMN_SERVICES: an array of service names and #BluetoothStatus connection statuses.
+ * @BLUETOOTH_COLUMN_UUIDS: a string array of human-readable UUIDs.
+ *
+ * A column identifier to pass to bluetooth_chooser_get_selected_device_info().
+ **/
 typedef enum {
 	BLUETOOTH_COLUMN_PROXY,
 	BLUETOOTH_COLUMN_ADDRESS,
@@ -79,6 +129,17 @@ typedef enum {
 	_BLUETOOTH_NUM_COLUMNS /*< skip >*/
 } BluetoothColumn;
 
+/**
+ * BluetoothStatus:
+ *
+ * @BLUETOOTH_STATUS_INVALID: whether the status has been set yet
+ * @BLUETOOTH_STATUS_DISCONNECTED: whether the service is disconnected
+ * @BLUETOOTH_STATUS_CONNECTED: whether the service is connected
+ * @BLUETOOTH_STATUS_CONNECTING: whether the service is connecting
+ * @BLUETOOTH_STATUS_PLAYING: whether the service is playing (only used by the audio service)
+ *
+ * The connection status of a service on a particular device. Note that @BLUETOOTH_STATUS_CONNECTING and @BLUETOOTH_STATUS_PLAYING might not be available for all services.
+ **/
 typedef enum {
 	BLUETOOTH_STATUS_INVALID = 0,
 	BLUETOOTH_STATUS_DISCONNECTED,
diff --git a/lib/bluetooth-plugin-manager.c b/lib/bluetooth-plugin-manager.c
index ab1751c..5606610 100644
--- a/lib/bluetooth-plugin-manager.c
+++ b/lib/bluetooth-plugin-manager.c
@@ -33,6 +33,9 @@
 
 #define UNINSTALLED_PLUGINDIR "../lib/plugins"
 
+#define SOEXT           ("." G_MODULE_SUFFIX)
+#define SOEXT_LEN       (strlen (SOEXT))
+
 GList *plugin_list = NULL;
 
 static void
diff --git a/lib/bluetooth-plugin.h b/lib/bluetooth-plugin.h
index 9f6069c..8fdc997 100644
--- a/lib/bluetooth-plugin.h
+++ b/lib/bluetooth-plugin.h
@@ -7,20 +7,42 @@
 typedef struct _GbtPluginInfo GbtPluginInfo;
 typedef struct _GbtPlugin GbtPlugin;
 
+/**
+ * GbtPluginInfo:
+ * @id: A unique ID representing the plugin
+ * @has_config_widget: Whether the passed Bluetooth address and UUIDs would have a configuration widget
+ * @get_config_widgets: Returns the configuration widget for the passed Bluetooth address and UUIDs
+ * @device_removed: Remove any configuration relating to the Bluetooth address passed
+ *
+ * A structure representing a gnome-bluetooth wizard and properties plugin. You should also call GBT_INIT_PLUGIN() on the plugin structure to export it.
+ **/
 struct _GbtPluginInfo 
 {
-	const char *id;
-	gboolean (* has_config_widget) (const char *bdaddr, const char **uuids);
+	const char                         *id;
+	gboolean (* has_config_widget)     (const char *bdaddr, const char **uuids);
 	GtkWidget * (* get_config_widgets) (const char *bdaddr, const char **uuids);
-	void (* device_removed) (const char *bdaddr);
+	void (* device_removed)            (const char *bdaddr);
 };
 
+/**
+ * GbtPlugin:
+ * @module: the #GModule for the opened shared library
+ * @info: a #GbtPluginInfo structure
+ *
+ * A structure as used in gnome-bluetooth.
+ **/
 struct _GbtPlugin
 {
 	GModule *module;
 	GbtPluginInfo *info;
 };
 
+/**
+* GBT_INIT_PLUGIN:
+* @plugininfo: a #GbtPluginInfo structure representing the plugin
+*
+* Call this on an #GbtPluginInfo structure to make it available to gnome-bluetooth.
+**/
 #define GBT_INIT_PLUGIN(plugininfo)					\
 	gboolean gbt_init_plugin (GbtPlugin *plugin);			\
 	G_MODULE_EXPORT gboolean					\
@@ -29,8 +51,5 @@ struct _GbtPlugin
 		return TRUE;						\
 	}
 
-#define SOEXT           ("." G_MODULE_SUFFIX)
-#define SOEXT_LEN       (strlen (SOEXT))
-
 #endif /* _GNOME_BLUETOOTH_PLUGIN_H_ */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]