doc: Add description of org.bluez.obex.Image

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.

Signed-off-by: Anuj Jain <anuj01.jain@samsung.com>

diff --git a/Makefile.am b/Makefile.am
index 90bac312d1f6b478b67851e5f7eef64b1aa68a18..430a322c31af70b0c3b88d152c998f411aa13012 100755 (executable)
--- a/Makefile.am
+++ b/Makefile.am
@@ -366,7 +366,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.Image.5
 endif
 manual_pages += src/bluetoothd.8
 manual_pages += doc/l2cap.7 doc/rfcomm.7
@@ -399,7 +400,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.Image.5
 
 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
                        src/main_m.conf src/main_w.conf profiles/network/network.conf \
@@ -476,7 +478,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.Image.rst
 
 EXTRA_DIST += doc/pics-opp.txt doc/pixit-opp.txt \
                doc/pts-opp.txt

diff --git a/doc/org.bluez.obex.Image.rst b/doc/org.bluez.obex.Image.rst
new file mode 100644 (file)
index 0000000..c40d3f4
--- /dev/null
+++ b/doc/org.bluez.obex.Image.rst
@@ -0,0 +1,118 @@
+====================
+org.bluez.obex.Image
+====================
+
+--------------------------------------------------
+BlueZ D-Bus OBEX Image API documentation
+--------------------------------------------------
+
+:Version: BlueZ
+:Date: August 2024
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:      org.bluez.obex
+:Interface:    org.bluez.obex.Image1 [experimental]
+:Object path:  [Session object path]
+
+Methods
+-------
+
+object, dict Get(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} Properties(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 property values:
+
+       :string type:
+
+               Type of dict properties. Mandatory for each dict.
+
+               Possible values:
+
+               :"native":
+               :"variant":
+
+       :string encoding:
+
+               File encoding format.
+
+               Possible values:
+
+               :"BMP":
+               :"GIF":
+               :"JPEG":
+               :"JPEG2000":
+               :"PNG":
+               :"WBMP":
+
+       :string pixel:
+
+               File encoding format size of form "<width>*<height>".
+
+       :uint64 size:
+
+               File size.
+
+       :uint64 maxsize:
+
+               File maximum size.
+
+       :string transformation:
+
+               List of available transformations separated by space.
+
+               Possible values:
+
+               :"crop":
+               :"fill":
+               :"stretch":
+
+       Possible errors:
+
+       :org.bluez.obex.Error.InvalidArguments:
+       :org.bluez.obex.Error.Failed:
+
+object, dict GetThumbnail(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: