From f5678377c0616b292c3992ef550ffdc079838604 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= Date: Sat, 30 Nov 2024 12:15:10 +0200 Subject: [PATCH] gdbus: Add a few missing `(nullable)` annotations to GDBus method invocation related functions Sender can be NULL if not specified by the caller, e.g. on peer-to-peer connections. Interface name can be NULL on method calls if it was not specified by the sender. Both is explicitly allowed by the DBus specification. --- gio/gdbusconnection.h | 19 +++++++++++++++---- gio/gdbusmethodinvocation.c | 12 ++++++++++-- 2 files changed, 25 insertions(+), 6 deletions(-) diff --git a/gio/gdbusconnection.h b/gio/gdbusconnection.h index 3a8cb9d27..fe31ea0f4 100644 --- a/gio/gdbusconnection.h +++ b/gio/gdbusconnection.h @@ -265,9 +265,11 @@ GVariant *g_dbus_connection_call_with_unix_fd_list_sync (GDBusConnection /** * GDBusInterfaceMethodCallFunc: * @connection: A #GDBusConnection. - * @sender: The unique bus name of the remote caller. + * @sender: (nullable): The unique bus name of the remote caller, or `NULL` if + * not specified by the caller, e.g. on peer-to-peer connections. * @object_path: The object path that the method was invoked on. - * @interface_name: The D-Bus interface name the method was invoked on. + * @interface_name: (nullable): The D-Bus interface name the method was invoked on, + * or `NULL` if not specified by the sender. * @method_name: The name of the method that was invoked. * @parameters: A #GVariant tuple with parameters. * @invocation: (transfer full): A #GDBusMethodInvocation object that must be used to return a value or error. @@ -275,6 +277,13 @@ GVariant *g_dbus_connection_call_with_unix_fd_list_sync (GDBusConnection * * The type of the @method_call function in #GDBusInterfaceVTable. * + * @interface_name may be `NULL` if not specified by the sender, although it’s + * encouraged for the sender to set it. If unset, and the object has only one + * method (across all interfaces) matching @method_name, that method is invoked. + * Otherwise, behaviour is implementation defined. See the + * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-types-method). + * It is recommended to return [error@Gio.DBusError.UNKNOWN_METHOD]. + * * Since: 2.26 */ typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection, @@ -289,7 +298,8 @@ typedef void (*GDBusInterfaceMethodCallFunc) (GDBusConnection *connection, /** * GDBusInterfaceGetPropertyFunc: * @connection: A #GDBusConnection. - * @sender: The unique bus name of the remote caller. + * @sender: (nullable): The unique bus name of the remote caller or %NULL if + * not specified by the caller, e.g. on peer-to-peer connections. * @object_path: The object path that the method was invoked on. * @interface_name: The D-Bus interface name for the property. * @property_name: The name of the property to get the value of. @@ -315,7 +325,8 @@ typedef GVariant *(*GDBusInterfaceGetPropertyFunc) (GDBusConnection *conne /** * GDBusInterfaceSetPropertyFunc: * @connection: A #GDBusConnection. - * @sender: The unique bus name of the remote caller. + * @sender: (nullable): The unique bus name of the remote caller or %NULL if + * not specified by the caller, e.g. on peer-to-peer connections. * @object_path: The object path that the method was invoked on. * @interface_name: The D-Bus interface name for the property. * @property_name: The name of the property to get the value of. diff --git a/gio/gdbusmethodinvocation.c b/gio/gdbusmethodinvocation.c index 2e4f0d679..63236188b 100644 --- a/gio/gdbusmethodinvocation.c +++ b/gio/gdbusmethodinvocation.c @@ -128,7 +128,10 @@ g_dbus_method_invocation_init (GDBusMethodInvocation *invocation) * * Gets the bus name that invoked the method. * - * Returns: A string. Do not free, it is owned by @invocation. + * This can return %NULL if not specified by the caller, e.g. on peer-to-peer + * connections. + * + * Returns: (nullable): A string. Do not free, it is owned by @invocation. * * Since: 2.26 */ @@ -162,12 +165,17 @@ g_dbus_method_invocation_get_object_path (GDBusMethodInvocation *invocation) * * Gets the name of the D-Bus interface the method was invoked on. * + * This can be `NULL` if it was not specified by the sender. See + * [callback@Gio.DBusInterfaceMethodCallFunc] or the + * [D-Bus Specification](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-types-method) + * for details on when this can happen and how it should be handled. + * * If this method call is a property Get, Set or GetAll call that has * been redirected to the method call handler then * "org.freedesktop.DBus.Properties" will be returned. See * #GDBusInterfaceVTable for more information. * - * Returns: A string. Do not free, it is owned by @invocation. + * Returns: (nullable): A string. Do not free, it is owned by @invocation. * * Since: 2.26 */