luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-07-07 02:59:39 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'wip/smcv/dbus-fd-convention' into 'master'

Browse Source 
gdbus: Document the intended semantics of handles and fds

See merge request GNOME/glib!1726
This commit is contained in:
Philip Withnall 2020-10-28 12:40:28 +00:00
commit 5b0a7ed046
2 changed files with 36 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
gio/gdbusconnection.c
View File

@ -6248,6 +6248,18 @@ g_dbus_connection_call_sync (GDBusConnection *connection,
* *
* Like g_dbus_connection_call() but also takes a #GUnixFDList object. * 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. * This method is only available on UNIX.
* *
* Since: 2.30 * 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(). * 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 * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
* return values. Free with g_variant_unref(). * 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 * @error: return location for error or %NULL
* *
* Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. * 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. * This method is only available on UNIX.
* *

11
gio/gdbusmessage.c
View File

@ -1158,6 +1158,12 @@ g_dbus_message_set_body (GDBusMessage *message,
* *
* This method is only available on UNIX. * 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 * Returns: (transfer none):A #GUnixFDList or %NULL if no file descriptors are
* associated. Do not free, this object is owned by @message. * 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. * 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 * Since: 2.26
*/ */
void void