From fc1f4969bf29da9fe46e91f8a96fcee220a53b0f Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Wed, 28 Oct 2020 11:42:13 +0000 Subject: [PATCH] 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 --- 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