doc/gatt-api: New API properties and methods for the GATT D-Bus API.

This patch introduces the following new properties to the GattService1
interface:

  Device: A remote-service-only property that contains the D-Bus object
  path of the associated device.

  Primary: Reflects whether or not a services is primary or secondary.

This patch also introduces new methods to GattCharacteristic1 and
GattDescriptor1 for reading and writing the corresponding attribute
values and a new signal for being notified of received notifications and
indications.

The "Value" D-Bus property is removed from both interfaces
and replaced with asynchronous ReadValue and WriteValue functions. This
is due to the fact that DBus.Properties.Get is synchronous and without
an asynchronous way of issuing a GATT value read request, there are
cases where a single read and cache based approach becomes limiting
(e.g. when a characteristic allows reads but no notifications) and
relying on the PropertyChanged signal to retrieve the value of a read
request asynchonously as well as to signal notifications/indications
makes for a vague API.

1 files changed, 112 insertions, 12 deletions

diff --git a/doc/gatt-api.txt b/doc/gatt-api.txt
index 8c7975c4d..f7125a271 100644
--- a/doc/gatt-api.txt
+++ b/doc/gatt-api.txt
@@ -32,6 +32,25 @@ Properties	string UUID [read-only]
 
 			128-bit service UUID.
 
+		boolean Primary [read-only]
+
+			Indicates whether or not this GATT service is a
+			primary service. If false, the service is secondary.
+
+		object Device [read-only, optional]
+
+			Object path of the Bluetooth device the service
+			belongs to. Only present on services from remote
+			devices.
+
+		array{object} Characteristics [read-only]
+
+			Array of object paths representing the characteristics
+			of this service. This property is set only when the
+			characteristic discovery has been completed, however the
+			characteristic objects will become available via
+			ObjectManager as soon as they get discovered.
+
 		array{object} Includes [read-only]: Not implemented
 
 			Array of object paths representing the included
@@ -48,6 +67,50 @@ Service		org.bluez
 Interface	org.bluez.GattCharacteristic1 [Experimental]
 Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY
 
+Methods		array{byte} ReadValue()
+
+			Issues a request to read the value of the
+			characteristic and returns the value if the
+			operation was successful.
+
+			Possible Errors: org.bluez.Error.Failed
+					 org.bluez.Error.InProgress
+					 org.bluez.Error.ReadNotPermitted
+					 org.bluez.Error.NotAuthorized
+					 org.bluez.Error.NotPaired
+					 org.bluez.Error.NotSupported
+
+		void WriteValue(array{byte} value)
+
+			Issues a request to write the value of the
+			characteristic.
+
+			Possible Errors: org.bluez.Error.Failed
+					 org.bluez.Error.InProgress
+					 org.bluez.Error.WriteNotPermitted
+					 org.bluez.Error.InvalidValueLength
+					 org.bluez.Error.NotAuthorized
+					 org.bluez.Error.NotPaired
+					 org.bluez.Error.NotSupported
+
+		void StartNotify()
+
+			Starts a notification session from this characteristic
+			if it supports value notifications or indications.
+
+			Possible Errors: org.bluez.Error.Failed
+					 org.bluez.Error.InProgress
+					 org.bluez.Error.NotSupported
+
+		void StopNotify()
+
+			This method will cancel any previous StartNotify
+			transaction. Note that notifications from a
+			characteristic are shared between sessions thus
+			calling StopNotify will release a single session.
+
+			Possible Errors: org.bluez.Error.Failed
+
 Properties	string UUID [read-only]
 
 			128-bit characteristic UUID.
@@ -57,12 +120,19 @@ Properties	string UUID [read-only]
 			Object path of the GATT service the characteristc
 			belongs to.
 
-		array{byte} Value [read-write]
+		array{byte} Value [read-only, optional]
+
+			The cached value of the characteristic. This property
+			gets updated only after a successful read request and
+			when a notification or indication is received, upon
+			which a PropertiesChanged signal will be emitted.
 
-			Value read from the remote Bluetooth device or from
-			the external application implementing GATT services.
+		boolean Notifying [read-only]
 
-		array{string} Flags [read-only, optional]
+			True, if notifications or indications on this
+			characteristic are currently enabled.
+
+		array{string} Flags [read-only]
 
 			Defines how the characteristic value can be used. See
 			Core spec "Table 3.5: Characteristic Properties bit
@@ -79,6 +149,14 @@ Properties	string UUID [read-only]
 				"reliable-write"
 				"writable-auxiliaries"
 
+		array{object} Descriptors [read-only]
+
+			Array of object paths representing the descriptors
+			of this service. This property is set only when the
+			descriptor discovery has been completed, however the
+			descriptor objects will become available via
+			ObjectManager as soon as they get discovered.
+
 
 Characteristic Descriptors hierarchy
 ====================================
@@ -89,6 +167,32 @@ Service		org.bluez
 Interface	org.bluez.GattDescriptor1 [Experimental]
 Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX/serviceXX/charYYYY/descriptorZZZ
 
+Methods		array{byte} ReadValue()
+
+			Issues a request to read the value of the
+			characteristic and returns the value if the
+			operation was successful.
+
+			Possible Errors: org.bluez.Error.Failed
+					 org.bluez.Error.InProgress
+					 org.bluez.Error.ReadNotPermitted
+					 org.bluez.Error.NotAuthorized
+					 org.bluez.Error.NotPaired
+					 org.bluez.Error.NotSupported
+
+		void WriteValue(array{byte} value)
+
+			Issues a request to write the value of the
+			characteristic.
+
+			Possible Errors: org.bluez.Error.Failed
+					 org.bluez.Error.InProgress
+					 org.bluez.Error.WriteNotPermitted
+					 org.bluez.Error.InvalidValueLength
+					 org.bluez.Error.NotAuthorized
+					 org.bluez.Error.NotPaired
+					 org.bluez.Error.NotSupported
+
 Properties	string UUID [read-only]
 
 			128-bit descriptor UUID.
@@ -98,16 +202,12 @@ Properties	string UUID [read-only]
 			Object path of the GATT characteristc the descriptor
 			belongs to.
 
-		array{byte} Value [read-write]
-
-			Raw characteristic descriptor value read from the
-			remote Bluetooth device or from the external
-			application implementing GATT services.
+		array{byte} Value [read-only, optional]
 
-		string Permissions [read-only]: To be defined
+			The cached value of the descriptor. This property
+			gets updated only after a successful read request, upon
+			which a PropertiesChanged signal will be emitted.
 
-			Defines read/write authentication and authorization
-			requirements.
 
 Service Manager hierarchy
 =============================