:right-sidebar: True DebugControllerDBus =================================================================== .. currentmodule:: gi.repository.Gio .. versionadded:: 2.72 .. class:: DebugControllerDBus(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gio.DebugController`, :class:`~gi.repository.Gio.Initable` ``GDebugControllerDBus`` is an implementation of :obj:`~gi.repository.Gio.DebugController` which exposes debug settings as a D-Bus object. It is a :obj:`~gi.repository.Gio.Initable` object, and will register an object at ``/org/gtk/Debugging`` on the bus given as :obj:`~gi.repository.Gio.DebugControllerDBus.props.connection` once it’s initialized. The object will be unregistered when the last reference to the ``GDebugControllerDBus`` is dropped. This D-Bus object can be used by remote processes to enable or disable debug output in this process. Remote processes calling ``org.gtk.Debugging.SetDebugEnabled()`` will affect the value of :obj:`~gi.repository.Gio.DebugController.props.debug_enabled` and, by default, :obj:`~gi.repository.GLib.log_get_debug_enabled`\. By default, no processes are allowed to call ``SetDebugEnabled()`` unless a :obj:`~gi.repository.Gio.DebugControllerDBus.signals.authorize` signal handler is installed. This is because the process may be privileged, or might expose sensitive information in its debug output. You may want to restrict the ability to enable debug output to privileged users or processes. One option is to install a D-Bus security policy which restricts access to ``SetDebugEnabled()``\, installing something like the following in ``$datadir/dbus-1/system.d/``\: .. code-block:: xml :dedent: This will prevent the ``SetDebugEnabled()`` method from being called by all except root. It will not prevent the ``DebugEnabled`` property from being read, as it’s accessed through the ``org.freedesktop.DBus.Properties`` interface. Another option is to use polkit to allow or deny requests on a case-by-case basis, allowing for the possibility of dynamic authorisation. To do this, connect to the :obj:`~gi.repository.Gio.DebugControllerDBus.signals.authorize` signal and query polkit in it: .. code-block:: c :dedent: g_autoptr(GError) child_error = NULL; g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL); gulong debug_controller_authorize_id = 0; // Set up the debug controller. debug_controller = G_DEBUG_CONTROLLER (g_debug_controller_dbus_new (priv->connection, NULL, &child_error)); if (debug_controller == NULL) { g_error ("Could not register debug controller on bus: %s"), child_error->message); } debug_controller_authorize_id = g_signal_connect (debug_controller, "authorize", G_CALLBACK (debug_controller_authorize_cb), self); static gboolean debug_controller_authorize_cb (GDebugControllerDBus *debug_controller, GDBusMethodInvocation *invocation, gpointer user_data) { g_autoptr(PolkitAuthority) authority = NULL; g_autoptr(PolkitSubject) subject = NULL; g_autoptr(PolkitAuthorizationResult) auth_result = NULL; g_autoptr(GError) local_error = NULL; GDBusMessage *message; GDBusMessageFlags message_flags; PolkitCheckAuthorizationFlags flags = POLKIT_CHECK_AUTHORIZATION_FLAGS_NONE; message = g_dbus_method_invocation_get_message (invocation); message_flags = g_dbus_message_get_flags (message); authority = polkit_authority_get_sync (NULL, &local_error); if (authority == NULL) { g_warning ("Failed to get polkit authority: %s", local_error->message); return FALSE; } if (message_flags & G_DBUS_MESSAGE_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION) flags |= POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION; subject = polkit_system_bus_name_new (g_dbus_method_invocation_get_sender (invocation)); auth_result = polkit_authority_check_authorization_sync (authority, subject, "com.example.MyService.set-debug-enabled", NULL, flags, NULL, &local_error); if (auth_result == NULL) { g_warning ("Failed to get check polkit authorization: %s", local_error->message); return FALSE; } return polkit_authorization_result_get_is_authorized (auth_result); } Constructors ------------ .. rst-class:: interim-class .. class:: DebugControllerDBus :no-index: .. classmethod:: new(connection: ~gi.repository.Gio.DBusConnection, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.Gio.DebugControllerDBus | None Create a new :obj:`~gi.repository.Gio.DebugControllerDBus` and synchronously initialize it. Initializing the object will export the debug object on ``connection``\. The object will remain registered until the last reference to the :obj:`~gi.repository.Gio.DebugControllerDBus` is dropped. Initialization may fail if registering the object on ``connection`` fails. .. versionadded:: 2.72 :param connection: a :obj:`~gi.repository.Gio.DBusConnection` to register the debug object on :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`\, or :const:`None` Methods ------- .. rst-class:: interim-class .. class:: DebugControllerDBus :no-index: .. method:: do_authorize(self, invocation: ~gi.repository.Gio.DBusMethodInvocation) -> bool :param invocation: .. method:: stop() -> None Stop the debug controller, unregistering its object from the bus. Any pending method calls to the object will complete successfully, but new ones will return an error. This method will block until all pending :obj:`~gi.repository.Gio.DebugControllerDBus`\::authorize signals have been handled. This is expected to not take long, as it will just be waiting for threads to join. If any :obj:`~gi.repository.Gio.DebugControllerDBus`\::authorize signal handlers are still executing in other threads, this will block until after they have returned. This method will be called automatically when the final reference to the :obj:`~gi.repository.Gio.DebugControllerDBus` is dropped. You may want to call it explicitly to know when the controller has been fully removed from the bus, or to break reference count cycles. Calling this method from within a :obj:`~gi.repository.Gio.DebugControllerDBus`\::authorize signal handler will cause a deadlock and must not be done. .. versionadded:: 2.72 Properties ---------- .. rst-class:: interim-class .. class:: DebugControllerDBus :no-index: .. attribute:: props.connection :type: ~gi.repository.Gio.DBusConnection The type of the None singleton. .. versionadded:: 2.72 Signals ------- .. rst-class:: interim-class .. class:: DebugControllerDBus.signals :no-index: .. method:: authorize(invocation: ~gi.repository.Gio.DBusMethodInvocation) -> bool The type of the None singleton. .. versionadded:: 2.72 :param invocation: A :obj:`~gi.repository.Gio.DBusMethodInvocation`\. Virtual Methods --------------- .. rst-class:: interim-class .. class:: DebugControllerDBus :no-index: .. method:: do_authorize(invocation: ~gi.repository.Gio.DBusMethodInvocation) -> bool The type of the None singleton. :param invocation: Fields ------ .. rst-class:: interim-class .. class:: DebugControllerDBus :no-index: .. attribute:: parent_instance