Added some GSoC'10 docs (temprorary)

Some impl's

7 files changed, 407 insertions, 8 deletions

diff --git a/doc/bluez-tools.txt b/doc/bluez-tools.txt
new file mode 100644
index 0000000..37179a8
--- /dev/null
+++ b/doc/bluez-tools.txt
@@ -0,0 +1,177 @@
+blueZ-tools:
+A set of tools to manage bluetooth devices and services.
+
+1) blueZ-agent (btagent/btagentlib)
+Bluetooth agent/lib, that implements org.bluez.Agent/org.openobex.Agent interfaces;
+Tasks:
+ - request pincode/passkey for an authentication from user (bluetooth v2.0)
+ - display passkey to user (bluetooth v2.1)
+ - request confirmation from user, that a passkey for an authentication is valid (bluetooth v2.1)
+ - authorize a connection/service request
+ - cancel request if request failed/reply was not returned
+ - confirm mode change of adapter
+ - register/unregister self for an selected adapter
+ OBEX:
+  - accept/reject a bluetooth object push request
+
+btagent is an external tool, that manage incoming? connections.
+command line arguments:
+./btagent [help|--help|-h] [adapter#id]
+ adapter#id  -  register agent for an given adapter
+ help        -  show help and exit
+
+If no adapter#id is given, than agent register self to a default adapter;
+Agentlib is used as embedded agent to manage outgoing? connections;
+
+2) blueZ-monitor (btmon)
+Bluetooth monitor, that displays some events (ie signals);
+Tasks:
+ Adaper signals:
+  - adapter added/removed (GLOBAL)
+  - default adapter changed (GLOBAL)
+  - adapter property changed
+ Device(remote) signals:
+  - device added/removed (ie created/removed)
+  - device property changed
+  - disconnection to a remote device has been requested
+  - node created/removed (TODO)
+ Input service signals:
+  - input device connected/disconnected
+ Network service signals:
+  - network device connected/disconnected (also displays interface name)
+ Audio service signals (generic, org.bluez.Audio interface):
+  - audio device connected/disconnected/connection state changed
+ Others:
+  - AVRCP service monitoring? (TODO)
+ OBEX:
+  - FTP OBEX connection has been accepted/disconnected
+  - object push operation starts
+  - object has been received
+
+command line arguments:
+./btmon [help|--help|-h] [adapter#id]
+ adapter#id  -  show events only for an given adapter
+ help        -  show help and exit
+
+If no adapter#id is given, that display events from all adapters and devices;
+GLOBAL events are displayed for all;
+
+Also, if needed - monitor can listen for an error messages and display it;
+
+3) blueZ-tool (bttool)
+Bluetooth tool to manage devices and services;
+Tasks:
+ Adapter managment:
+  - list all available adapters
+  - get/set properties
+  - discover remote devices
+ Device managment:
+  - list of added devices
+  - add remote device and initiate pairing
+  - remove device
+  - get/set properties
+  - discover services
+  - disconnect from device
+  - list/create/remove node(s) (TODO)
+ Services managment:
+  - list connected services
+  - connect/disconnect to/from an input device
+  - connect/disconnect to/from a serial device
+  - connect/disconnect to/from a network device (TODO: can be moved to btnetwork)
+  - connect/disconnect to/from an audio device (TODO: can be moved to btaudio)
+
+command line arguments:
+./bttool [help|--help|-h] [list|--list|-l] [ [adapter#id] commands [params] ]
+  help        -  show help and exit
+  list        -  list all available adapters
+  
+  [adapter#id] ...  (use an given adapter or default if does not defined)
+   Adapter commands:
+    prop[erties] [name] [value]  -  list/get/set property(es)
+    disc[over]                   -  discover available remote devices
+    
+    dev[ice] addr|name? ...
+     Device commands:
+      list                         -  list of added devices
+      conn[ect]                    -  add remote device and initiate pairing
+      rem[ove]                     -  remove device
+      discon[nect]                 -  disconnect from device
+      prop[erties] [name] [value]  -  list/get/set property(es)
+      disc[over]                   -  discover services
+      
+      serv[ice] ...
+       Services comands:
+        list                           -  list connected services
+        disc[over]                     -  discover services (alias)
+        in[put] conn[ect]|discon[ect]  -  connect/disconnect to/from an input device
+        ser[ial] ...
+         conn[ect] uuid|profile|channel  -  connect to a serial device
+         discon[nect] device             -  disconnect from a serial device
+        net[work] ...
+         conn[ect] gn|panu|nap           - connect to a network device
+         discon[nect]                    - disconnect from a network device
+        au[dio] conn[ect]|discon[ect]  -  connect/disconnect to/from an audio device
+
+If no options are given - show help page;
+
+Examples of usage:
+ a) Discover remote devices
+ bttool disc
+ b) Connect to a remote device and initiate pairing
+ bttool dev xx:xx:xx:xx:xx:xx conn
+ c) Discover remote services
+ bttool dev xx:xx:xx:xx:xx:xx disc
+  or
+ bttool dev xx:xx:xx:xx:xx:xx serv disc
+ d) Connect to an input device
+ bttool dev xx:xx:xx:xx:xx:xx serv in conn
+ e) Change adapter mode/properties
+ bttool prop Discoverable off
+ bttool prop DiscoverableTimeout 1h
+ f) List added devices
+ bttool dev list
+ g) List all connected services
+ bttool dev xx:xx:xx:xx:xx:xx serv list
+
+4) blueZ-audio (btaudio)
+
+(TODO)
+
+5) blueZ-network (btnetwork)
+
+(TODO)
+
+6) blueZ-obex (btobex)
+Bluetooth utility, that implements OBEX protocol;
+Tasks:
+ - Send files via object push request
+ - Provide ftp access to remote device
+
+command line arguments:
+./btobex [--help|-h|help] [adapter#id] dev[ice] addr|name? send|ftp [file1..fileN]
+  help        -  show help and exit
+  adapter#id  -  use an given adapter or default if does not defined
+  
+  dev[ice] addr|name? ...
+   Commands:
+    ftp                -  open FTP session
+    send file1..fileN  -  send file(s)
+
+FTP session example:
+./btobex dev xx:xx:xx:xx:xx:xx ftp
+> help
+Available commands:
+cd <name>		Change directory
+mkdir <name>		Make directory
+ls			List files in current directory
+put <src> [<dst>] 	Copy the src file (from local filesystem) to the dst file (on remote device)
+get <src> [<dst>]	Copy the src file (from remote device) to the dst file (on local filesystem)
+cp <src> <dst>		Copy file
+mv <src> <dst>		Move file
+rm <name>		Deletes the specified file/folder
+quit			End sessions
+> quit
+
+
+---------
+* (TODO) These features will be available in future versions
diff --git a/doc/bttools-v3_pub.txt b/doc/bttools-v3_pub.txt
new file mode 100644
index 0000000..07ce88e
--- /dev/null
+++ b/doc/bttools-v3_pub.txt
@@ -0,0 +1,166 @@
+                                   bttools project
+------------------------------------------------------------------------------------------
+Abstract:
+	Sometimes we need to work with bluetooth devices without having a X server. Also, 
+many peoples prefer to perform most operations in the console, even from a full DE. The 
+idea of this project - write a set of console utilities to work with the bluetooth devices. 
+The main advantage - X server is not needed, no bindings to the DE/WM. The main goal - to 
+implement the maximum functionality for a simple and easy work with the devices.
+------------------------------------------------------------------------------------------
+
+Base set of utilities:
+-----------------------
+ - bttool-agent
+ - bttool-monitor
+ - bttool-utility
+
+----------------------------------------------
+1) bttool-agent (btagent/btagentlib)
+Bluetooth agent/agentlib, to manage incoming and outgoing requests and connections;
+
+Tasks:
+ - request pincode/passkey for an authentication from user (bluetooth v2.0)
+ - display passkey to user (bluetooth v2.1 only)
+ - request confirmation from user, that a passkey for an authentication is valid (bluetooth v2.1 only)
+ - authorize a connection/service request
+ - cancel request if request failed/reply was not returned
+ - confirm mode change of adapter
+ - register/unregister self for an selected adapter
+
+btagent is an external tool, that manage incoming connections.
+command line arguments:
+./btagent [help|--help|-h] [adapter#id]
+ adapter#id  -  register agent for an given adapter
+ help        -  show help and exit
+
+If no adapter#id is given, than agent register self to a default adapter;
+Agentlib is used as embedded agent to manage outgoing connections in bttool-utility;
+
+----------------------------------------------
+2) bttool-monitor (btmon)
+Bluetooth monitor, that displays some events (and possible - an errors);
+
+Tasks (events to display):
+ Adaper events:
+  - adapter added/removed (GLOBAL)
+  - default adapter changed (GLOBAL)
+  - adapter property changed
+ Device events:
+  - device added/removed (ie created/removed)
+  - device property changed
+  - disconnection to a remote device has been requested
+ Input service events:
+  - input device connected/disconnected
+ Network service events:
+  - network device connected/disconnected (also displays interface name)
+ Audio service events (generic):
+  - audio device connected/disconnected/connection state changed
+
+command line arguments:
+./btmon [help|--help|-h] [adapter#id]
+ adapter#id  -  show events only for an given adapter
+ help        -  show help and exit
+
+If no adapter#id is given, that display events from all adapters and devices;
+GLOBAL events are displayed for all;
+
+Also, monitor can listen for an error messages from bttool-agent/bttool-utility and display they;
+
+----------------------------------------------
+3) bttool-utility (bttool)
+Main bluetooth tool to manage devices and services;
+
+Tasks:
+ Adapter managment:
+  - list all available adapters
+  - get/set properties
+  - discover remote devices
+ Device managment:
+  - list of added devices
+  - add remote device and initiate pairing
+  - remove device
+  - get/set properties
+  - discover services
+  - disconnect from device
+ Services managment:
+  - list connected services
+  - connect/disconnect to/from an input device
+  - connect/disconnect to/from a serial device
+  - connect/disconnect to/from a network device
+  - connect/disconnect to/from an audio device
+
+command line arguments:
+./bttool [help|--help|-h] [list|--list|-l] [ [adapter#id] commands [params] ]
+  help        -  show help and exit
+  list        -  list all available adapters
+  
+  [adapter#id] ...  (use an given adapter or default if does not defined)
+   Adapter commands:
+    prop[erties] [name] [value]  -  list/get/set property(es)
+    disc[over]                   -  discover available remote devices
+    
+    dev[ice] addr|name? ...
+     Device commands:
+      list                         -  list of added devices
+      conn[ect]                    -  add remote device and initiate pairing
+      rem[ove]                     -  remove device
+      discon[nect]                 -  disconnect from device
+      prop[erties] [name] [value]  -  list/get/set property(es)
+      disc[over]                   -  discover services
+      
+      serv[ice] ...
+       Services comands:
+        list                           -  list connected services
+        disc[over]                     -  discover services (alias)
+        in[put] conn[ect]|discon[ect]  -  connect/disconnect to/from an input device
+        ser[ial] ...
+         conn[ect] uuid|profile|channel  -  connect to a serial device
+         discon[nect] device             -  disconnect from a serial device
+        net[work] ...
+         conn[ect] gn|panu|nap           - connect to a network device
+         discon[nect]                    - disconnect from a network device
+        au[dio] conn[ect]|discon[ect]  -  connect/disconnect to/from an audio device
+
+If no options are given - show help page;
+
+This utility will support full and short syntax.
+
+Examples of usage:
+ a) Discover remote devices
+ ./bttool disc     (short)
+ ./bttool discover (full)
+
+ b) Connect to a remote device and initiate pairing
+ ./bttool dev xx:xx:xx:xx:xx:xx conn    (short)
+ ./bttool device xx:xx:xx:xx:xx connect (full)
+
+ c) Discover remote services
+ ./bttool dev xx:xx:xx:xx:xx:xx disc        (short)
+ ./bttool device xx:xx:xx:xx:xx:xx discover (full)
+  OR
+ ./bttool dev xx:xx:xx:xx:xx:xx serv disc           (short)
+ ./bttool device xx:xx:xx:xx:xx:xx service(s) discover (full)
+
+ d) Connect to an input device
+ ./bttool dev xx:xx:xx:xx:xx:xx serv in conn             (short)
+ ./bttool device xx:xx:xx:xx:xx:xx service input connect (full)
+
+ e) Change adapter mode/properties
+ ./bttool prop Discoverable off       (short)
+ ./bttool prop DiscoverableTimeout 1h (short)
+ ./bttool property Discoverable off   (full)
+
+ f) List added devices
+ ./bttool dev list       (short)
+ ./bttool device(s) list (full)
+
+ g) List all connected services
+ ./bttool dev xx:xx:xx:xx:xx:xx serv list          (short)
+ ./bttool device xx:xx:xx:xx:xx:xx service(s) list (full)
+
+---------
+*  adapter#id also can be: hci0, 0, 00:11:22:33:44:55, ?MyCoolAdapter?
+** device xx:xx:xx:xx:xx:xx can be: 11:22:33:44:55:66, ?CoolRemoteDevice?
+
+IMPORTANT: This is a base document (ie demo), all other features, such as OBEX support, bash-completion, etc 
+           will be described later. 
diff --git a/src/bt-adapter.c b/src/bt-adapter.c
index d28f4b6..f9f5148 100644
--- a/src/bt-adapter.c
+++ b/src/bt-adapter.c
@@ -151,7 +151,7 @@ int main(int argc, char *argv[])
 		g_print("  Pairable: %d [rw]\n", adapter_get_pairable(adapter));

 		g_print("  PairableTimeout: %d [rw]\n", adapter_get_pairable_timeout(adapter));

 		g_print("  Powered: %d [rw]\n", adapter_get_powered(adapter));

-		g_print("  Service(s): [");

+		g_print("  UUIDs: [");

 		const gchar **uuids = adapter_get_uuids(adapter);

 		for (int j = 0; uuids[j] != NULL; j++) {

 			if (j > 0) g_print(", ");

@@ -238,7 +238,7 @@ int main(int argc, char *argv[])
 		adapter_set_property(adapter, set_name_arg, &v, &error);

 		exit_if_error(error);

 

-		g_value_unset (&v);

+		g_value_unset(&v);

 		g_object_unref(adapter);

 	}

 

diff --git a/src/bt-agent.c b/src/bt-agent.c
index d4ad882..24b6b0e 100644
--- a/src/bt-agent.c
+++ b/src/bt-agent.c
@@ -73,7 +73,7 @@ int main(int argc, char *argv[])
 

 	Agent *agent = g_object_new(AGENT_TYPE, NULL);

 

-	adapter_register_agent(adapter, AGENT_DBUS_PATH, "DisplayYesNo", &error);

+	adapter_register_agent(adapter, DBUS_AGENT_PATH, "DisplayYesNo", &error);

 	exit_if_error(error);

 

 	g_print("Agent registered\n");

@@ -81,7 +81,7 @@ int main(int argc, char *argv[])
 	GMainLoop *mainloop = g_main_loop_new(NULL, FALSE);

 	g_main_loop_run(mainloop);

 

-	adapter_unregister_agent(adapter, AGENT_DBUS_PATH, &error);

+	adapter_unregister_agent(adapter, DBUS_AGENT_PATH, &error);

 	exit_if_error(error);

 

 	g_print("Agent unregistered\n");

diff --git a/src/bt-device.c b/src/bt-device.c
index 2ba1172..421936a 100644
--- a/src/bt-device.c
+++ b/src/bt-device.c
@@ -109,7 +109,7 @@ int main(int argc, char *argv[])
 	} else if (connect_arg) {
 		g_print("Connecting to: %s\n", connect_arg);
 		Agent *agent = g_object_new(AGENT_TYPE, NULL);
-		adapter_create_paired_device(adapter, connect_arg, AGENT_DBUS_PATH, "DisplayYesNo", &error);
+		adapter_create_paired_device(adapter, connect_arg, DBUS_AGENT_PATH, "DisplayYesNo", &error);
 		exit_if_error(error);
 		g_object_unref(agent);
 	} else if (remove_arg) {
@@ -127,19 +127,74 @@ int main(int argc, char *argv[])
 
 		g_print("[%s]\n", device_get_address(device));
 		g_print("  Name: %s\n", device_get_name(device));
-		g_print("  Alias: %s\n", device_get_alias(device));
+		g_print("  Alias: %s [rw]\n", device_get_alias(device));
 		g_print("  Address: %s\n", device_get_address(device));
 		g_print("  Class: %x\n", device_get_class(device));
+		g_print("  Paired: %d\n", device_get_paired(device));
+		g_print("  Trusted: %d [rw]\n", device_get_trusted(device));
+		g_print("  Blocked: %d [rw]\n", device_get_blocked(device));
+		g_print("  Connected: %d\n", device_get_connected(device));
+		g_print("  UUIDs: [");
+		const gchar **uuids = device_get_uuids(device);
+		for (int j = 0; uuids[j] != NULL; j++) {
+			if (j > 0) g_print(", ");
+			g_print("%s", uuid2service(uuids[j]));
+		}
+		g_print("]\n");
 
 		g_object_unref(device);
 	} else if (services_arg) {
 		Device *device = find_device(adapter, services_arg, &error);
 		exit_if_error(error);
 
+		g_object_unref(device);
 	} else if (set_arg) {
+		set_device_arg = argv[1];
+		set_name_arg = argv[2];
+		set_value_arg = argv[3];
+
 		Device *device = find_device(adapter, set_device_arg, &error);
 		exit_if_error(error);
 
+		GValue v = {0,};
+
+		if (g_strcmp0(set_name_arg, "Alias") == 0) {
+			g_value_init(&v, G_TYPE_STRING);
+			g_value_set_string(&v, set_value_arg);
+		} else if (
+				g_strcmp0(set_name_arg, "Trusted") == 0 ||
+				g_strcmp0(set_name_arg, "Blocked") == 0
+				) {
+			g_value_init(&v, G_TYPE_BOOLEAN);
+
+			if (g_strcmp0(set_value_arg, "0") == 0 || g_strcmp0(set_value_arg, "FALSE") == 0) {
+				g_value_set_boolean(&v, FALSE);
+			} else if (g_strcmp0(set_value_arg, "1") == 0 || g_strcmp0(set_value_arg, "TRUE") == 0) {
+				g_value_set_boolean(&v, TRUE);
+			} else {
+				g_print("Invalid value: %s\n", set_value_arg);
+			}
+		} else {
+			g_print("Invalid property: %s\n", set_name_arg);
+			exit(EXIT_FAILURE);
+		}
+
+		GHashTable *props = device_get_properties(device, &error);
+		exit_if_error(error);
+		GValue *old_value = g_hash_table_lookup(props, set_name_arg);
+		g_assert(old_value != NULL);
+		if (G_VALUE_HOLDS_STRING(old_value)) {
+			g_print("%s: %s -> %s\n", set_name_arg, g_value_get_string(old_value), g_value_get_string(&v));
+		} else if (G_VALUE_HOLDS_BOOLEAN(old_value)) {
+			g_print("%s: %d -> %d\n", set_name_arg, g_value_get_boolean(old_value), g_value_get_boolean(&v));
+		}
+		g_hash_table_unref(props);
+
+		device_set_property(device, set_name_arg, &v, &error);
+		exit_if_error(error);
+
+		g_value_unset(&v);
+		g_object_unref(device);
 	}
 
 	g_object_unref(adapter);
diff --git a/src/lib/agent.c b/src/lib/agent.c
index e4ea0d7..ea75b6f 100644
--- a/src/lib/agent.c
+++ b/src/lib/agent.c
@@ -65,13 +65,14 @@ static void agent_init(Agent *self)
 
 	g_assert(conn != NULL);
 
-	dbus_g_connection_register_g_object(conn, AGENT_DBUS_PATH, G_OBJECT(self));
+	dbus_g_connection_register_g_object(conn, DBUS_AGENT_PATH, G_OBJECT(self));
 }
 
 /* Methods */
 
 gboolean agent_release(Agent *self, GError **error)
 {
+	g_print("Agent released\n");
 	return TRUE;
 }
 
diff --git a/src/lib/agent.h b/src/lib/agent.h
index ae54e3c..2c80d2c 100644
--- a/src/lib/agent.h
+++ b/src/lib/agent.h
@@ -29,7 +29,7 @@
 
 #include "marshallers.h"
 
-#define AGENT_DBUS_PATH "/agent"
+#define DBUS_AGENT_PATH "/Agent"
 
 /*
  * Type macros