luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-12-09 10:04:50 +01:00
Code Issues Packages Projects Releases Wiki Activity

gdbus: Document the intended semantics of handles and fds

Browse Source 
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>
This commit is contained in:
Simon McVittie
2020-10-28 11:42:13 +00:00
parent 2d008e4645
commit fc1f4969bf
2 changed files with 36 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
gio/gdbusmessage.c
View File

@@ -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