API standard changes on attribute-api.txt

Layout changes. Splitting into Local Service, Device Service and Device
Characteristic hierarchy.

1 files changed, 73 insertions, 50 deletions

diff --git a/doc/attribute-api.txt b/doc/attribute-api.txt
index ee91f934..79d44ea7 100644
--- a/doc/attribute-api.txt
+++ b/doc/attribute-api.txt
@@ -3,17 +3,6 @@ BlueZ D-Bus Attribute API description
 
 Copyright (C) 2004-2010  Marcel Holtmann <marcel@holtmann.org>
 
-
-Attribute hierarchy
-===================
-
-Service		org.bluez
-Interface	org.bluez.Service
-		org.bluez.Characteristic
-Object path	[prefix]/{hci0}/{service0}
-		[prefix]/{hci0}/{device0}/{service0}/{characteristic0,...}
-		[prefix]/{hci0}/{device0}/{service1}/{characteristic0,...}
-
 Service details
 ---------------
 
@@ -34,64 +23,98 @@ fully transparent and a differentiation becomes unimportant in the future.
 A service consists of some generic service information and a set of
 characteristics. All characteristic are presented as object path as well.
 
+
+Local Service hierarchy
+=======================
+
+Service		org.bluez
+Interface	org.bluez.Service
+		org.bluez.Characteristic
+Object path	[prefix]/{hci0}/{service0, service1, ...}
+
+Methods
+
 Properties
-----------
-	string Name (mandatory)
 
-		General name of service
 
-	string Description (optional)
+Device Service hierarchy
+========================
 
-		Description of service
+Service		org.bluez
+Interface	org.bluez.Characteristic
+Object path	[prefix]/{hci0}/{service0, service1, ...}
+
+Methods		array[(object, dict)] GetCharacteristics()
+
+			Array of tuples with object path as identifier. An
+			alternative is doing dict of dict since the object
+			path is unique and the order of characteristics is
+			irrelevant. However it might be good to actually
+			present an order here.
+
+			See Characteristics properties for dictionary details.
+
+		RegisterCharacteristicsWatcher(object path)
+
+			Register a watcher for changes in specific characteristics
+			to monitor changes.
+
+			A watcher will be registered for this service and will
+			notifier about any changed characteristics in the service.
+			This also notifies about any included characteristics.
 
-	string UUID (mandatory)
+			Method for the watch objects still need to be defined.
 
-		UUID of service. Service class value for SDP and GATT UUID
-		for attribute based services.
+		UnregisterCharacteristicsWatcher(object path)
 
-	array{object} Characteristics
+			Unregister a watcher.
 
-		This list contains the characteristics owned by this specific
-		service and other characteristics from service includes. That
-		way no complicated service includes array is needed.
+Properties	string Name (mandatory) [readonly]
 
-		string UUID
-		string Name
-		string Description
-		struct Format (type, name, exponet etc.)
+			General name of service
 
-		array{byte} Value
-		string Representation (of the binary Value)
+		string Description (optional) [readonly]
 
-		object Service (the original service in case of includes)
+			Description of service
 
-		At this point only GetProperties() method call should be
-		supported for simplicity. Changing characteristics is up
-		to future support.
+		string UUID (mandatory) [readonly]
 
-		The object path of the characteristics might be split
-		over multiple service objects, because of includes.
+			UUID of service. Service class value for SDP and GATT
+			UUID for attribute based services.
 
-	array[(object, dict)] GetCharacteristics()
+		array{object} Characteristics [readonly]
 
-		Array of tuples with object path as identifier. An alternativ
-		is doing dict of dict since the object path is unique and the
-		order of characteristics is irrelevant. However it might be
-		good to actually present an order here.
+			This list contains the characteristics owned by this
+			specific service and other characteristics from service
+			includes. That way no complicated service includes array
+			is needed.
 
-		See Characteristics properties for dictionary details.
+			string UUID
+			string Name
+			string Description
+			struct Format (type, name, exponet etc.)
 
-	RegisterCharacteristicsWatcher(object path)
+			array{byte} Value
+			string Representation (of the binary Value)
 
-		Register a watcher for changes in specific characteristics
-		to monitor changes.
+			object Service (the original service in case of includes)
 
-		A watcher will be registered for this service and will
-		notifier about any changed characteristics in the service.
-		This also notifies about any included characteristics.
+			At this point only GetProperties() method call should be
+			supported for simplicity. Changing characteristics is up
+			to future support.
 
-		Method for the watch objects still need to be defined.
+			The object path of the characteristics might be split
+			over multiple service objects, because of includes.
 
-	UnregisterCharacteristicsWatcher(object path)
 
-		Unregister a watcher.
+Device Characteristic hierarchy
+===============================
+
+Service		org.bluez
+Interface	org.bluez.Characteristic
+Object path	[prefix]/{hci0}/{device0}/{service0}/{characteristic0,...}
+		[prefix]/{hci0}/{device0}/{service1}/{characteristic0,...}
+
+Methods
+
+Properties