[glib/wip/smcv/dbus-fd-convention] gdbus: Document the intended semantics of handles and fds

[Simon McVittie <smcv src gnome org>]

commit fc1f4969bf29da9fe46e91f8a96fcee220a53b0f
Author: Simon McVittie <smcv collabora com>
Date:   Wed Oct 28 11:42:13 2020 +0000

    gdbus: Document the intended semantics of handles and fds
    
    In the D-Bus wire protocol, the handle type (G_VARIANT_TYPE_HANDLE, h)
    is intended to be an index/pointer into the implementation's closest
    equivalent of GUnixFDList: its numeric value has no semantic meaning
    (in the same way that the numeric values of pointers have no semantic
    meaning), but a handle with value n acts as a reference to the nth fd
    in the fd list.
    
    GDBus provides a fairly direct mapping from the wire protocol to the
    C API, which makes it technically possible to attach and use fds
    without ever referring to them in the message body, and some
    GLib-centric D-Bus APIs rely on this.
    
    However, the other major implementations of D-Bus (libdbus and sd-bus)
    transparently replace file descriptors with handles when building
    messages, and transparently replace handles with file descriptors when
    parsing messages. This means they cannot implement D-Bus APIs that do
    not follow the conventional meaning of handles as indexes/pointers into
    an equivalent of GUnixFDList.
    
    For interoperability, we should encourage D-Bus API designers to follow
    the convention, even though code written against GDBus doesn't strictly
    need to do so.
    
    Signed-off-by: Simon McVittie <smcv collabora com>

 gio/gdbusconnection.c | 25 +++++++++++++++++++++++++
 gio/gdbusmessage.c    | 11 +++++++++++
 2 files changed, 36 insertions(+)
---
diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c
index 54aaf43d9..ed8cf6219 100644
--- a/gio/gdbusconnection.c
+++ b/gio/gdbusconnection.c
@@ -6248,6 +6248,18 @@ g_dbus_connection_call_sync (GDBusConnection     *connection,
  *
  * Like g_dbus_connection_call() but also takes a #GUnixFDList object.
  *
+ * The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE
+ * values in the body of the message. For example, if a message contains
+ * two file descriptors, @fd_list would have length 2, and
+ * `g_variant_new_handle (0)` and `g_variant_new_handle (1)` would appear
+ * somewhere in the body of the message (not necessarily in that order!)
+ * to represent the file descriptors at indexes 0 and 1 respectively.
+ *
+ * When designing D-Bus APIs that are intended to be interoperable,
+ * please note that non-GDBus implementations of D-Bus can usually only
+ * access file descriptors if they are referenced in this way by a
+ * value of type %G_VARIANT_TYPE_HANDLE in the body of the message.
+ *
  * This method is only available on UNIX.
  *
  * Since: 2.30
@@ -6280,6 +6292,17 @@ g_dbus_connection_call_with_unix_fd_list (GDBusConnection     *connection,
  *
  * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
  *
+ * The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE
+ * values in the body of the message. For example,
+ * if g_variant_get_handle() returns 5, that is intended to be a reference
+ * to the file descriptor that can be accessed by
+ * `g_unix_fd_list_get (*out_fd_list, 5, ...)`.
+ *
+ * When designing D-Bus APIs that are intended to be interoperable,
+ * please note that non-GDBus implementations of D-Bus can usually only
+ * access file descriptors if they are referenced in this way by a
+ * value of type %G_VARIANT_TYPE_HANDLE in the body of the message.
+ *
  * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
  *     return values. Free with g_variant_unref().
  *
@@ -6314,6 +6337,8 @@ g_dbus_connection_call_with_unix_fd_list_finish (GDBusConnection  *connection,
  * @error: return location for error or %NULL
  *
  * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
+ * See g_dbus_connection_call_with_unix_fd_list() and
+ * g_dbus_connection_call_with_unix_fd_list_finish() for more details.
  *
  * This method is only available on UNIX.
  *
diff --git a/gio/gdbusmessage.c b/gio/gdbusmessage.c
index 0e4878dfb..cbcea844e 100644
--- a/gio/gdbusmessage.c
+++ b/gio/gdbusmessage.c
@@ -1158,6 +1158,12 @@ g_dbus_message_set_body (GDBusMessage  *message,
  *
  * This method is only available on UNIX.
  *
+ * The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE
+ * values in the body of the message. For example,
+ * if g_variant_get_handle() returns 5, that is intended to be a reference
+ * to the file descriptor that can be accessed by
+ * `g_unix_fd_list_get (list, 5, ...)`.
+ *
  * Returns: (transfer none):A #GUnixFDList or %NULL if no file descriptors are
  * associated. Do not free, this object is owned by @message.
  *
@@ -1182,6 +1188,11 @@ g_dbus_message_get_unix_fd_list (GDBusMessage  *message)
  *
  * This method is only available on UNIX.
  *
+ * When designing D-Bus APIs that are intended to be interoperable,
+ * please note that non-GDBus implementations of D-Bus can usually only
+ * access file descriptors if they are referenced by a value of type
+ * %G_VARIANT_TYPE_HANDLE in the body of the message.
+ *
  * Since: 2.26
  */
 void