data: Document the session_handle type mismatch

This was erroneously implemented as `s` but for backwards compatibility cannot be changed as it would break existing clients. Best we can do here is fix the documentation and tell people about it. See eebb041 ("use correct type for the session object path") and its revert in e452353. Closes #1359
flatpak · Aug 6, 2024 · ffa25b7 · ffa25b7
1 parent 5941475
commit ffa25b7
Show file tree

Hide file tree

Showing 4 changed files with 20 additions and 4 deletions.
diff --git a/data/org.freedesktop.portal.GlobalShortcuts.xml b/data/org.freedesktop.portal.GlobalShortcuts.xml
@@ -65,11 +65,15 @@
 
         The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:
 
-        * ``session_handle`` (``o``)
+        * ``session_handle`` (``s``)
 
           The session handle. An object path for the
           org.freedesktop.portal.Session object representing the created
           session.
+
+          .. note::
+            The ``session_handle`` is an object path that was erroneously implemented
+            as ``s``. For backwards compatibility it will remain this type.
     -->
     <method name="CreateSession">
       <arg type="a{sv}" name="options" direction="in"/>

diff --git a/data/org.freedesktop.portal.Inhibit.xml b/data/org.freedesktop.portal.Inhibit.xml
@@ -97,12 +97,16 @@
 
         The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:
 
-        * ``session_handle`` (``o``)
+        * ``session_handle`` (``s``)
 
           The session handle. An object path for the
           :ref:`org.freedesktop.portal.Session` object representing the created
           session.
 
+          .. note::
+            The ``session_handle`` is an object path that was erroneously implemented
+            as ``s``. For backwards compatibility it will remain this type.
+
         This method was added in version 2 of this interface.
     -->
     <method name="CreateMonitor">

diff --git a/data/org.freedesktop.portal.RemoteDesktop.xml b/data/org.freedesktop.portal.RemoteDesktop.xml
@@ -65,11 +65,15 @@
 
         The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:
 
-        * ``session_handle`` (``o``)
+        * ``session_handle`` (``s``)
 
           The session handle. An object path for the
           :ref:`org.freedesktop.portal.Session` object representing the created
           session.
+
+          .. note::
+            The ``session_handle`` is an object path that was erroneously implemented
+            as ``s``. For backwards compatibility it will remain this type.
     -->
     <method name="CreateSession">
       <arg type="a{sv}" name="options" direction="in"/>

diff --git a/data/org.freedesktop.portal.ScreenCast.xml b/data/org.freedesktop.portal.ScreenCast.xml
@@ -52,11 +52,15 @@
 
         The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:
 
-        * ``session_handle`` (``o``)
+        * ``session_handle`` (``s``)
 
           The session handle. An object path for the
           :ref:`org.freedesktop.portal.Session` object representing the created
           session.
+
+          .. note::
+            The ``session_handle`` is an object path that was erroneously implemented
+            as ``s``. For backwards compatibility it will remain this type.
     -->
     <method name="CreateSession">
       <arg type="a{sv}" name="options" direction="in"/>