diff options
| -rw-r--r-- | docs/reference/libgnome-bluetooth/gnome-bluetooth-docs.sgml | 2 | ||||
| -rw-r--r-- | docs/reference/libgnome-bluetooth/tmpl/bluetooth-enums.sgml | 86 | ||||
| -rw-r--r-- | lib/bluetooth-chooser-button.c | 8 | ||||
| -rw-r--r-- | lib/bluetooth-chooser.c | 2 | ||||
| -rw-r--r-- | lib/bluetooth-client.c | 84 | ||||
| -rw-r--r-- | lib/bluetooth-enums.h | 61 | ||||
| -rw-r--r-- | lib/bluetooth-plugin-manager.c | 3 | ||||
| -rw-r--r-- | 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 f8939a54..7247c69a 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 00000000..4163f2f4 --- /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 ccc06507..d9f05c68 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 4a6c247b..6ce95b1a 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 2cf04697..ff3a01f8 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 450c38cb..e0332837 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 ab1751c5..5606610b 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 9f6069c0..8fdc9978 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_ */ |