[PATCH v0 0/2] Media API clarifications

[PATCH v0 0/2] Media API clarifications

[Mikel Astiz]

From: Mikel Astiz <mikel.astiz@bmw-carit.de>

The documentation of BlueZ 5.0 is lacking some details affecting the Media API, specially regarding the control of HFP/HSP volume.

There is no known implementation of MediaTransport1 at this point so updating the documentation with two new optional properties could be in practice done without updating the interface suffix.

Besides, the error codes returned by Acquire() and TryAcquire() are convenient to implement proper error logging in the client side.

Mikel Astiz (2):
  media: Add HFP/HSP gains to transport API
  media: Clarify Acquire/TryAcquire error cases

 doc/media-api.txt          | 32 +++++++++++++++++++++++++++++++-
 profiles/audio/transport.c |  2 +-
 2 files changed, 32 insertions(+), 2 deletions(-)

-- 
1.7.11.7

[PATCH v0 1/2] media: Add HFP/HSP gains to transport API

[Mikel Astiz]

From: Mikel Astiz <mikel.astiz@bmw-carit.de>

Add two independent and HSP/HFP-specific properties to the media
transport representing the input and output audio volumes.
---
 doc/media-api.txt | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/doc/media-api.txt b/doc/media-api.txt
index e2a72dc..cdde6ea 100644
--- a/doc/media-api.txt
+++ b/doc/media-api.txt
@@ -393,4 +393,26 @@ Properties	object Device [readonly]
 			this property is only writeable when the transport was
 			acquired by the sender.
 
+			Note: the property will not be present for HSP/HFP
+			transports and MicrophoneGain/SpeakerGain should be
+			used instead.
+
 			Possible Values: 0-127
+
+		byte MicrophoneGain [readwrite]
+
+			Optional. Indicates volume level of the transport's
+			incoming audio stream for HSP/HFP transports. This
+			property is only writeable when the transport was
+			acquired by the sender.
+
+			Possible Values: 0-15
+
+		byte SpeakerGain [readwrite]
+
+			Optional. Indicates volume level of the transport's
+			outgoing audio stream for HSP/HFP transports. This
+			property is only writeable when the transport was
+			acquired by the sender.
+
+			Possible Values: 0-15
-- 
1.7.11.7

[PATCH v0 2/2] media: Clarify Acquire/TryAcquire error cases

[Mikel Astiz]

From: Mikel Astiz <mikel.astiz@bmw-carit.de>

Document the reported errors for Acquire() and TryAcquire(). For the
later, make sure a specific error in guaranteed for the typical scenario
of audio not streaming.
---
 doc/media-api.txt          | 10 +++++++++-
 profiles/audio/transport.c |  2 +-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/doc/media-api.txt b/doc/media-api.txt
index cdde6ea..bb5ced0 100644
--- a/doc/media-api.txt
+++ b/doc/media-api.txt
@@ -321,12 +321,20 @@ Methods		fd, uint16, uint16 Acquire()
 			Acquire transport file descriptor and the MTU for read
 			and write respectively.
 
+			Possible Errors: org.bluez.Error.NotAuthorized
+					 org.bluez.Error.Failed
+
 		fd, uint16, uint16 TryAcquire()
 
 			Acquire transport file descriptor only if the transport
 			is in "pending" state at the time the message is
 			received by BlueZ. Otherwise no request will be sent
-			to the remote device and the function will just fail.
+			to the remote device and the function will just fail
+			with org.bluez.Error.NotAvailable.
+
+			Possible Errors: org.bluez.Error.NotAuthorized
+					 org.bluez.Error.Failed
+					 org.bluez.Error.NotAvailable
 
 		void Release()
 
diff --git a/profiles/audio/transport.c b/profiles/audio/transport.c
index 54461d8..58240ac 100644
--- a/profiles/audio/transport.c
+++ b/profiles/audio/transport.c
@@ -477,7 +477,7 @@ static DBusMessage *try_acquire(DBusConnection *conn, DBusMessage *msg,
 		return btd_error_not_authorized(msg);
 
 	if (transport->state != TRANSPORT_STATE_PENDING)
-		return btd_error_failed(msg, "Transport not playing");
+		return btd_error_not_available(msg);
 
 	owner = media_owner_create(msg);
 	id = transport->resume(transport, owner);
-- 
1.7.11.7

Re: [PATCH v0 0/2] Media API clarifications

[Johan Hedberg]

Hi Mikel,

On Tue, Jan 08, 2013, Mikel Astiz wrote:
> The documentation of BlueZ 5.0 is lacking some details affecting the
> Media API, specially regarding the control of HFP/HSP volume.
> 
> There is no known implementation of MediaTransport1 at this point so
> updating the documentation with two new optional properties could be
> in practice done without updating the interface suffix.
> 
> Besides, the error codes returned by Acquire() and TryAcquire() are
> convenient to implement proper error logging in the client side.
> 
> Mikel Astiz (2):
>   media: Add HFP/HSP gains to transport API
>   media: Clarify Acquire/TryAcquire error cases
> 
>  doc/media-api.txt          | 32 +++++++++++++++++++++++++++++++-
>  profiles/audio/transport.c |  2 +-
>  2 files changed, 32 insertions(+), 2 deletions(-)

Both patches have been applied. Thanks.

Johan