diff mbox series

[BlueZ,v3,9/9] doc: Add description of org.bluez.obex.BipAvrcp

Message ID 20240916132813.165731-10-frederic.danis@collabora.com (mailing list archive)
State Superseded
Headers show
Series Add BIP for AVRCP covert art OBEX client | expand

Checks

Context Check Description
tedd_an/pre-ci_am success Success
tedd_an/CheckPatch success CheckPatch PASS
tedd_an/GitLint success Gitlint PASS
tedd_an/IncrementalBuild success Incremental Build PASS

Commit Message

Frédéric Danis Sept. 16, 2024, 1:28 p.m. UTC
This new interface allows to get the image referenced in the audio
metadata ImgHandle available in org.bluez.MediaPlayer track properties.
The image handle is only available in track info if an OBEX session is
connected to the ObexPort port provided in  org.bluez.MediaPlayer
properties.
---
 Makefile.am                     |  9 +++--
 doc/org.bluez.obex.BipAvrcp.rst | 72 +++++++++++++++++++++++++++++++++
 doc/org.bluez.obex.Client.rst   |  1 +
 3 files changed, 79 insertions(+), 3 deletions(-)
 create mode 100644 doc/org.bluez.obex.BipAvrcp.rst

Comments

Luiz Augusto von Dentz Sept. 16, 2024, 5:40 p.m. UTC | #1
Hi Frédéric,

On Mon, Sep 16, 2024 at 9:28 AM Frédéric Danis
<frederic.danis@collabora.com> wrote:
>
> This new interface allows to get the image referenced in the audio
> metadata ImgHandle available in org.bluez.MediaPlayer track properties.
> The image handle is only available in track info if an OBEX session is
> connected to the ObexPort port provided in  org.bluez.MediaPlayer
> properties.
> ---
>  Makefile.am                     |  9 +++--
>  doc/org.bluez.obex.BipAvrcp.rst | 72 +++++++++++++++++++++++++++++++++
>  doc/org.bluez.obex.Client.rst   |  1 +
>  3 files changed, 79 insertions(+), 3 deletions(-)
>  create mode 100644 doc/org.bluez.obex.BipAvrcp.rst
>
> diff --git a/Makefile.am b/Makefile.am
> index 88044aa05..3a9728782 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -382,7 +382,8 @@ man_MANS += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
>                 doc/org.bluez.obex.PhonebookAccess.5 \
>                 doc/org.bluez.obex.MessageAccess.5 \
>                 doc/org.bluez.obex.Message.5 \
> -               doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5
> +               doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5 \
> +               doc/org.bluez.obex.BipAvrcp.5
>  endif
>  manual_pages += src/bluetoothd.8
>  manual_pages += doc/l2cap.7 doc/rfcomm.7
> @@ -415,7 +416,8 @@ manual_pages += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
>                 doc/org.bluez.obex.PhonebookAccess.5 \
>                 doc/org.bluez.obex.MessageAccess.5 \
>                 doc/org.bluez.obex.Message.5 \
> -               doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5
> +               doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5 \
> +               doc/org.bluez.obex.BipAvrcp.5
>
>  EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
>                         src/main.conf profiles/network/network.conf \
> @@ -497,7 +499,8 @@ EXTRA_DIST += doc/org.bluez.obex.Client.rst doc/org.bluez.obex.Session.rst \
>                 doc/org.bluez.obex.PhonebookAccess.rst \
>                 doc/org.bluez.obex.MessageAccess.rst \
>                 doc/org.bluez.obex.Message.rst \
> -               doc/org.bluez.obex.AgentManager.rst doc/org.bluez.obex.Agent.rst
> +               doc/org.bluez.obex.AgentManager.rst doc/org.bluez.obex.Agent.rst \
> +               doc/org.bluez.obex.BipAvrcp.rst
>
>  EXTRA_DIST += doc/pics-opp.txt doc/pixit-opp.txt \
>                 doc/pts-opp.txt
> diff --git a/doc/org.bluez.obex.BipAvrcp.rst b/doc/org.bluez.obex.BipAvrcp.rst
> new file mode 100644
> index 000000000..46b12f645
> --- /dev/null
> +++ b/doc/org.bluez.obex.BipAvrcp.rst
> @@ -0,0 +1,72 @@
> +=======================
> +org.bluez.obex.BipAvrcp
> +=======================
> +
> +--------------------------------------------------
> +BlueZ D-Bus OBEX BipAvrcp API documentation
> +--------------------------------------------------
> +
> +:Version: BlueZ
> +:Date: August 2024
> +:Manual section: 5
> +:Manual group: Linux System Administration
> +
> +Interface
> +=========
> +
> +:Service:      org.bluez.obex
> +:Interface:    org.bluez.obex.BipAvrcp1 [experimental]

org.bluez.obex.Image

> +:Object path:  [Session object path]
> +
> +Methods
> +-------
> +
> +object, dict GetImage(string targetfile, string handle, dict description)
> +`````````````````````````````````````````````````````````````````````````
> +
> +    Retrieves the image corresponding to the handle and the description, as
> +    one of the descriptions retrieved by GetImageProperties, and store it in
> +    a local file.

We can probably just use Get instead of GetImage.

> +
> +    If the "transform" property description exists it should be set to one
> +    of the value listed by GetImageProperties for this description.

Id probably got with properties as the name so it is more obvious that
it is referring to GetProperty, or perhaps options and rename the
method to GetOptions.

> +    If description is an empty dict, the native image will be retrieved;
> +
> +       Possible errors:
> +
> +       :org.bluez.obex.Error.InvalidArguments:
> +       :org.bluez.obex.Error.Failed:
> +
> +array{dict} GetImageproperties(string handle)
> +`````````````````````````````````````````````
> +
> +    Retrieves the image properties corresponding to the handle.
> +
> +    The first dict entry is mandatory and correspond to 'handle' and 'name'
> +    of the image.
> +
> +    The second dict entry is mandatory and correspond to the native description
> +    ('type':'native') of the image.
> +
> +    The following dict entries are optional and correspond to variant
> +    descriptions of the image. If the 'transform' entry exists in the
> +    description, it lists the available possible image transformations and
> +    should be set to one of them before using the description as parameter
> +    to GetImage.

I'd recommend we include the list of possible table of key-value pairs
we could return here, otherwise the client would have to look at the
spec which sort of defeats the purpose of having this documented here.

> +
> +       Possible errors:
> +
> +       :org.bluez.obex.Error.InvalidArguments:
> +       :org.bluez.obex.Error.Failed:
> +
> +object, dict GetImageThumbnail(string targetfile, string handle)
> +````````````````````````````````````````````````````````````````
> +
> +    Retrieves the image thumbnail corresponding to the handle and store it in
> +    a local file.

GetThumbnail, also I assume the options don't apply here? So I assume
we cannot ask the server to convert to a different format?

> +       Possible errors:
> +
> +       :org.bluez.obex.Error.InvalidArguments:
> +       :org.bluez.obex.Error.Failed:
> diff --git a/doc/org.bluez.obex.Client.rst b/doc/org.bluez.obex.Client.rst
> index 5ae7cc5e8..f20dd5baa 100644
> --- a/doc/org.bluez.obex.Client.rst
> +++ b/doc/org.bluez.obex.Client.rst
> @@ -43,6 +43,7 @@ object CreateSession(string destination, dict args)
>                 :"opp":
>                 :"pbap":
>                 :"sync":
> +               :"bip-avrcp":

This change should probably go alongside the patch that introduces
support for creating the session of this type.

>         :string Source:
>
> --
> 2.34.1
>
>
diff mbox series

Patch

diff --git a/Makefile.am b/Makefile.am
index 88044aa05..3a9728782 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -382,7 +382,8 @@  man_MANS += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
 		doc/org.bluez.obex.PhonebookAccess.5 \
 		doc/org.bluez.obex.MessageAccess.5 \
 		doc/org.bluez.obex.Message.5 \
-		doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5
+		doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5 \
+		doc/org.bluez.obex.BipAvrcp.5
 endif
 manual_pages += src/bluetoothd.8
 manual_pages += doc/l2cap.7 doc/rfcomm.7
@@ -415,7 +416,8 @@  manual_pages += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
 		doc/org.bluez.obex.PhonebookAccess.5 \
 		doc/org.bluez.obex.MessageAccess.5 \
 		doc/org.bluez.obex.Message.5 \
-		doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5
+		doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5 \
+		doc/org.bluez.obex.BipAvrcp.5
 
 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
 			src/main.conf profiles/network/network.conf \
@@ -497,7 +499,8 @@  EXTRA_DIST += doc/org.bluez.obex.Client.rst doc/org.bluez.obex.Session.rst \
 		doc/org.bluez.obex.PhonebookAccess.rst \
 		doc/org.bluez.obex.MessageAccess.rst \
 		doc/org.bluez.obex.Message.rst \
-		doc/org.bluez.obex.AgentManager.rst doc/org.bluez.obex.Agent.rst
+		doc/org.bluez.obex.AgentManager.rst doc/org.bluez.obex.Agent.rst \
+		doc/org.bluez.obex.BipAvrcp.rst
 
 EXTRA_DIST += doc/pics-opp.txt doc/pixit-opp.txt \
 		doc/pts-opp.txt
diff --git a/doc/org.bluez.obex.BipAvrcp.rst b/doc/org.bluez.obex.BipAvrcp.rst
new file mode 100644
index 000000000..46b12f645
--- /dev/null
+++ b/doc/org.bluez.obex.BipAvrcp.rst
@@ -0,0 +1,72 @@ 
+=======================
+org.bluez.obex.BipAvrcp
+=======================
+
+--------------------------------------------------
+BlueZ D-Bus OBEX BipAvrcp API documentation
+--------------------------------------------------
+
+:Version: BlueZ
+:Date: August 2024
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez.obex
+:Interface:	org.bluez.obex.BipAvrcp1 [experimental]
+:Object path:	[Session object path]
+
+Methods
+-------
+
+object, dict GetImage(string targetfile, string handle, dict description)
+`````````````````````````````````````````````````````````````````````````
+
+    Retrieves the image corresponding to the handle and the description, as
+    one of the descriptions retrieved by GetImageProperties, and store it in
+    a local file.
+
+    If the "transform" property description exists it should be set to one
+    of the value listed by GetImageProperties for this description.
+
+    If description is an empty dict, the native image will be retrieved;
+
+	Possible errors:
+
+	:org.bluez.obex.Error.InvalidArguments:
+	:org.bluez.obex.Error.Failed:
+
+array{dict} GetImageproperties(string handle)
+`````````````````````````````````````````````
+
+    Retrieves the image properties corresponding to the handle.
+
+    The first dict entry is mandatory and correspond to 'handle' and 'name'
+    of the image.
+
+    The second dict entry is mandatory and correspond to the native description
+    ('type':'native') of the image.
+
+    The following dict entries are optional and correspond to variant
+    descriptions of the image. If the 'transform' entry exists in the
+    description, it lists the available possible image transformations and
+    should be set to one of them before using the description as parameter
+    to GetImage.
+
+	Possible errors:
+
+	:org.bluez.obex.Error.InvalidArguments:
+	:org.bluez.obex.Error.Failed:
+
+object, dict GetImageThumbnail(string targetfile, string handle)
+````````````````````````````````````````````````````````````````
+
+    Retrieves the image thumbnail corresponding to the handle and store it in
+    a local file.
+
+	Possible errors:
+
+	:org.bluez.obex.Error.InvalidArguments:
+	:org.bluez.obex.Error.Failed:
diff --git a/doc/org.bluez.obex.Client.rst b/doc/org.bluez.obex.Client.rst
index 5ae7cc5e8..f20dd5baa 100644
--- a/doc/org.bluez.obex.Client.rst
+++ b/doc/org.bluez.obex.Client.rst
@@ -43,6 +43,7 @@  object CreateSession(string destination, dict args)
 		:"opp":
 		:"pbap":
 		:"sync":
+		:"bip-avrcp":
 
 	:string Source: