:right-sidebar: True DBusMessage =================================================================== .. currentmodule:: gi.repository.Gio .. versionadded:: 2.26 .. class:: DBusMessage(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` A type for representing D-Bus messages that can be sent or received on a :obj:`~gi.repository.Gio.DBusConnection`\. Constructors ------------ .. rst-class:: interim-class .. class:: DBusMessage :no-index: .. classmethod:: new() -> ~gi.repository.Gio.DBusMessage Creates a new empty :obj:`~gi.repository.Gio.DBusMessage`\. .. versionadded:: 2.26 .. classmethod:: new_from_blob(blob: list[int], capabilities: ~gi.repository.Gio.DBusCapabilityFlags) -> ~gi.repository.Gio.DBusMessage Creates a new :obj:`~gi.repository.Gio.DBusMessage` from the data stored at ``blob``\. The byte order that the message was in can be retrieved using :func:`~gi.repository.Gio.DBusMessage.get_byte_order`. If the ``blob`` cannot be parsed, contains invalid fields, or contains invalid headers, :const:`~gi.repository.Gio.IOErrorEnum.INVALID_ARGUMENT` will be returned. .. versionadded:: 2.26 :param blob: A blob representing a binary D-Bus message. :param capabilities: A :obj:`~gi.repository.Gio.DBusCapabilityFlags` describing what protocol features are supported. .. classmethod:: new_method_call(name: str | None, path: str, interface_: str | None, method: str) -> ~gi.repository.Gio.DBusMessage Creates a new :obj:`~gi.repository.Gio.DBusMessage` for a method call. .. versionadded:: 2.26 :param name: A valid D-Bus name or :const:`None`. :param path: A valid object path. :param interface_: A valid D-Bus interface name or :const:`None`. :param method: A valid method name. .. classmethod:: new_signal(path: str, interface_: str, signal: str) -> ~gi.repository.Gio.DBusMessage Creates a new :obj:`~gi.repository.Gio.DBusMessage` for a signal emission. .. versionadded:: 2.26 :param path: A valid object path. :param interface_: A valid D-Bus interface name. :param signal: A valid signal name. Methods ------- .. rst-class:: interim-class .. class:: DBusMessage :no-index: .. classmethod:: bytes_needed() -> int Utility function to calculate how many bytes are needed to completely deserialize the D-Bus message stored at ``blob``\. .. versionadded:: 2.26 .. method:: get_arg0() -> str | None Convenience to get the first item in the body of ``message``\. See :obj:`~gi.repository.Gio.DBusMessage.get_arg0_path` for returning object-path-typed arg0 values. .. versionadded:: 2.26 .. method:: get_arg0_path() -> str | None Convenience to get the first item in the body of ``message``\. See :obj:`~gi.repository.Gio.DBusMessage.get_arg0` for returning string-typed arg0 values. .. versionadded:: 2.80 .. method:: get_body() -> ~gi.repository.GLib.Variant | None Gets the body of a message. .. versionadded:: 2.26 .. method:: get_byte_order() -> ~gi.repository.Gio.DBusMessageByteOrder Gets the byte order of ``message``\. .. method:: get_destination() -> str | None Convenience getter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.DESTINATION` header field. .. versionadded:: 2.26 .. method:: get_error_name() -> str | None Convenience getter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.ERROR_NAME` header field. .. versionadded:: 2.26 .. method:: get_flags() -> ~gi.repository.Gio.DBusMessageFlags Gets the flags for ``message``\. .. versionadded:: 2.26 .. method:: get_header(header_field: ~gi.repository.Gio.DBusMessageHeaderField) -> ~gi.repository.GLib.Variant | None Gets a header field on ``message``\. The caller is responsible for checking the type of the returned :obj:`~gi.repository.GLib.Variant` matches what is expected. .. versionadded:: 2.26 :param header_field: A 8-bit unsigned integer (typically a value from the :obj:`~gi.repository.Gio.DBusMessageHeaderField` enumeration) .. method:: get_header_fields() -> list[int] Gets an array of all header fields on ``message`` that are set. .. versionadded:: 2.26 .. method:: get_interface() -> str | None Convenience getter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.INTERFACE` header field. .. versionadded:: 2.26 .. method:: get_locked() -> bool Checks whether ``message`` is locked. To monitor changes to this value, conncet to the :obj:`~gi.repository.GObject.Object`\::notify signal to listen for changes on the :obj:`~gi.repository.Gio.DBusMessage`\:locked property. .. versionadded:: 2.26 .. method:: get_member() -> str | None Convenience getter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.MEMBER` header field. .. versionadded:: 2.26 .. method:: get_message_type() -> ~gi.repository.Gio.DBusMessageType Gets the type of ``message``\. .. versionadded:: 2.26 .. method:: get_num_unix_fds() -> int Convenience getter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.NUM_UNIX_FDS` header field. .. versionadded:: 2.26 .. method:: get_path() -> str | None Convenience getter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.PATH` header field. .. versionadded:: 2.26 .. method:: get_reply_serial() -> int Convenience getter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.REPLY_SERIAL` header field. .. versionadded:: 2.26 .. method:: get_sender() -> str | None Convenience getter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.SENDER` header field. .. versionadded:: 2.26 .. method:: get_serial() -> int Gets the serial for ``message``\. .. versionadded:: 2.26 .. method:: get_signature() -> str Convenience getter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.SIGNATURE` header field. This will always be non-:const:`None`, but may be an empty string. .. versionadded:: 2.26 .. method:: get_unix_fd_list() -> ~gi.repository.Gio.UnixFDList | None Gets the UNIX file descriptors associated with ``message``\, if any. 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 :func:`~gi.repository.GLib.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, ...)``\. .. versionadded:: 2.26 .. method:: lock() -> None If ``message`` is locked, does nothing. Otherwise locks the message. .. versionadded:: 2.26 .. method:: new_method_error_literal(error_name: str, error_message: str) -> ~gi.repository.Gio.DBusMessage Creates a new :obj:`~gi.repository.Gio.DBusMessage` that is an error reply to ``method_call_message``\. .. versionadded:: 2.26 :param error_name: A valid D-Bus error name. :param error_message: The D-Bus error message. .. method:: new_method_reply() -> ~gi.repository.Gio.DBusMessage Creates a new :obj:`~gi.repository.Gio.DBusMessage` that is a reply to ``method_call_message``\. .. versionadded:: 2.26 .. method:: print_(indent: int) -> str :param indent: .. method:: set_body(body: ~gi.repository.GLib.Variant) -> None Sets the body ``message``\. As a side-effect the :const:`~gi.repository.Gio.DBusMessageHeaderField.SIGNATURE` header field is set to the type string of ``body`` (or cleared if ``body`` is :const:`None`). If ``body`` is floating, ``message`` assumes ownership of ``body``\. .. versionadded:: 2.26 :param body: Either :const:`None` or a :obj:`~gi.repository.GLib.Variant` that is a tuple. .. method:: set_byte_order(byte_order: ~gi.repository.Gio.DBusMessageByteOrder) -> None Sets the byte order of ``message``\. :param byte_order: The byte order. .. method:: set_destination(value: str | None = None) -> None Convenience setter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.DESTINATION` header field. .. versionadded:: 2.26 :param value: The value to set. .. method:: set_error_name(value: str) -> None Convenience setter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.ERROR_NAME` header field. .. versionadded:: 2.26 :param value: The value to set. .. method:: set_flags(flags: ~gi.repository.Gio.DBusMessageFlags) -> None Sets the flags to set on ``message``\. .. versionadded:: 2.26 :param flags: Flags for ``message`` that are set (typically values from the :obj:`~gi.repository.Gio.DBusMessageFlags` enumeration bitwise ORed together). .. method:: set_header(header_field: ~gi.repository.Gio.DBusMessageHeaderField, value: ~gi.repository.GLib.Variant | None = None) -> None Sets a header field on ``message``\. If ``value`` is floating, ``message`` assumes ownership of ``value``\. .. versionadded:: 2.26 :param header_field: A 8-bit unsigned integer (typically a value from the :obj:`~gi.repository.Gio.DBusMessageHeaderField` enumeration) :param value: A :obj:`~gi.repository.GLib.Variant` to set the header field or :const:`None` to clear the header field. .. method:: set_interface(value: str | None = None) -> None Convenience setter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.INTERFACE` header field. .. versionadded:: 2.26 :param value: The value to set. .. method:: set_member(value: str | None = None) -> None Convenience setter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.MEMBER` header field. .. versionadded:: 2.26 :param value: The value to set. .. method:: set_message_type(type: ~gi.repository.Gio.DBusMessageType) -> None Sets ``message`` to be of ``type``\. .. versionadded:: 2.26 :param type: A 8-bit unsigned integer (typically a value from the :obj:`~gi.repository.Gio.DBusMessageType` enumeration). .. method:: set_num_unix_fds(value: int) -> None Convenience setter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.NUM_UNIX_FDS` header field. .. versionadded:: 2.26 :param value: The value to set. .. method:: set_path(value: str | None = None) -> None Convenience setter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.PATH` header field. .. versionadded:: 2.26 :param value: The value to set. .. method:: set_reply_serial(value: int) -> None Convenience setter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.REPLY_SERIAL` header field. .. versionadded:: 2.26 :param value: The value to set. .. method:: set_sender(value: str | None = None) -> None Convenience setter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.SENDER` header field. .. versionadded:: 2.26 :param value: The value to set. .. method:: set_serial(serial: int) -> None Sets the serial for ``message``\. .. versionadded:: 2.26 :param serial: A :obj:`int`. .. method:: set_signature(value: str | None = None) -> None Convenience setter for the :const:`~gi.repository.Gio.DBusMessageHeaderField.SIGNATURE` header field. .. versionadded:: 2.26 :param value: The value to set. .. method:: set_unix_fd_list(fd_list: ~gi.repository.Gio.UnixFDList | None = None) -> None Sets the UNIX file descriptors associated with ``message``\. As a side-effect the :const:`~gi.repository.Gio.DBusMessageHeaderField.NUM_UNIX_FDS` header field is set to the number of fds in ``fd_list`` (or cleared if ``fd_list`` is :const:`None`). 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. .. versionadded:: 2.26 :param fd_list: A :obj:`~gi.repository.Gio.UnixFDList` or :const:`None`. .. method:: to_blob(capabilities: ~gi.repository.Gio.DBusCapabilityFlags) -> list[int] Serializes ``message`` to a blob. The byte order returned by :func:`~gi.repository.Gio.DBusMessage.get_byte_order` will be used. .. versionadded:: 2.26 :param capabilities: A :obj:`~gi.repository.Gio.DBusCapabilityFlags` describing what protocol features are supported. .. method:: to_gerror() -> bool If ``message`` is not of type :const:`~gi.repository.Gio.DBusMessageType.ERROR` does nothing and returns :const:`False`. Otherwise this method encodes the error in ``message`` as a :obj:`~gi.repository.GLib.Error` using g_dbus_error_set_dbus_error() using the information in the :const:`~gi.repository.Gio.DBusMessageHeaderField.ERROR_NAME` header field of ``message`` as well as the first string item in ``message``\'s body. .. versionadded:: 2.26 Properties ---------- .. rst-class:: interim-class .. class:: DBusMessage :no-index: .. attribute:: props.locked :type: bool The type of the None singleton.