[RFC v2] DBus OutOfBand API update

[RFC v2] DBus OutOfBand API update

[Szymon Janc]

Changes in V2:
Added TK and 'SM OOB Flags' fields for BLE as suggested by Vinicius.

Some of V1 questions are still valid:
- short name vs full name distinguish
- emit DeviceDisappeared when removing oob data?
- enable OOB interface only for BLE and/or SSP capable adapters?

Comment are welcome.

-- 
BR
Szymon Janc

Szymon Janc (1):
  dbusoob: Update API

 doc/oob-api.txt |   70 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 64 insertions(+), 6 deletions(-)

-- 
1.7.9.5

[RFC v2] dbusoob: Update API

[Szymon Janc]

---
 doc/oob-api.txt |   70 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 64 insertions(+), 6 deletions(-)

diff --git a/doc/oob-api.txt b/doc/oob-api.txt
index d838712..94f0bdb 100644
--- a/doc/oob-api.txt
+++ b/doc/oob-api.txt
@@ -7,26 +7,84 @@ Service		org.bluez
 Interface	org.bluez.OutOfBand
 Object path	[variable prefix]/{hci0,hci1,...}
 
-Methods		array{byte} hash, array{byte} randomizer ReadLocalData()
+Methods		dict ReadLocalData()
 
 			This method reads local OOB data from adapter. Return
-			value is pair of arrays 16 bytes each.
+			value is a dictionary. Following keys are possible:
 
-			Note: This method will generate and return new local
-			OOB data.
+			array{byte} Hash:
+
+					16 bytes hash blob.
+
+			array{byte} Randomizer:
+
+					16 bytes randomizer blob.
+
+			array{byte} TK:
+
+					16 bytes TK blob.
+
+			Other data that can be transmitted via OOB mechanism
+			can be obtained from org.bluez.Adapter interface.
+
+			Note: This method will generate and return new data
+			every time it is called. Data received in previous
+			calls is invalidated and cannot be used for pairing.
 
 			Possible errors: org.bluez.Error.Failed
 					 org.bluez.Error.InProgress
 
-		void AddRemoteData(string address, array{byte} hash,
-							array{byte} randomizer)
+		void AddRemoteData(string address, dict data)
 
 			This method adds new Out Of Band data for
 			specified address. If data for specified address
 			already exists it will be overwritten with new one.
 
+			All data is optional.
+
+			On success DeviceFound signal will be emitted.
+
+			possible keys:
+
+				array{byte} Hash:
+
+					16 bytes hash blob, it is used as is
+					so the size and byte order must match.
+
+				array{byte} Randomizer:
+
+					16 bytes randomizer blob, it is used as
+					is so the size and byte order must
+					match. If Randomizer is provided Hash
+					also needs to be provided.
+
+				array{byte} TK:
+
+					16 byte Temporary Key (TK) blob, it is
+					used as is so size and byte order must
+					match.
+
+				uint32 Class:
+
+					The Bluetooth class of device of the
+					remote device.
+
+				uint8 SMFlags:
+
+					1 byte with Security Manager OOB flags.
+
+				string Name:
+
+					Remote device name.
+
+				array{string} UUIDs
+
+					List of 128-bit UUIDs that represents
+					the available local services.
+
 			Possible errors: org.bluez.Error.Failed
 					 org.bluez.Error.InvalidArguments
+					 org.bluez.Error.AlreadyPaired
 
 		void RemoveRemoteData(string address)
 
-- 
1.7.9.5

Re: [RFC v2] DBus OutOfBand API update

[Johan Hedberg]

Hi Szymon,

On Fri, Jul 27, 2012, Szymon Janc wrote:
> - short name vs full name distinguish

I don't think we need the distinction. Just support full name.

> - emit DeviceDisappeared when removing oob data?

I suppose we could, not that I feel particularly strongly either way.

> - enable OOB interface only for BLE and/or SSP capable adapters?

I'd just return org.bluez.Error.NotSupported for the methods.

Johan