DBusMessage

Added in version 2.26.

class DBusMessage(**properties: Any)

Superclasses: Object

A type for representing D-Bus messages that can be sent or received on a DBusConnection.

Constructors

class DBusMessage
classmethod new() → DBusMessage

Creates a new empty DBusMessage.

Added in version 2.26.

classmethod new_from_blob(blob: Sequence[int], capabilities: DBusCapabilityFlags) → DBusMessage

Creates a new DBusMessage from the data stored at blob. The byte order that the message was in can be retrieved using get_byte_order().

If the blob cannot be parsed, contains invalid fields, or contains invalid headers, INVALID_ARGUMENT will be returned.

Added in version 2.26.

Parameters:

  • blob – A blob representing a binary D-Bus message.

  • capabilities – A DBusCapabilityFlags describing what protocol features are supported.

classmethod new_method_call(name: str | None, path: str, interface_: str | None, method: str) → DBusMessage

Creates a new DBusMessage for a method call.

Added in version 2.26.

Parameters:

  • name – A valid D-Bus name or None.

  • path – A valid object path.

  • interface – A valid D-Bus interface name or None.

  • method – A valid method name.

classmethod new_signal(path: str, interface_: str, signal: str) → DBusMessage

Creates a new DBusMessage for a signal emission.

Added in version 2.26.

Parameters:

  • path – A valid object path.

  • interface – A valid D-Bus interface name.

  • signal – A valid signal name.

Methods

class DBusMessage
bytes_needed(blob: Sequence[int]) → int

Utility function to calculate how many bytes are needed to completely deserialize the D-Bus message stored at blob.

Added in version 2.26.

Parameters:

blob – A blob representing a binary D-Bus message.

get_arg0() → str | None

Convenience to get the first item in the body of message.

See get_arg0_path for returning object-path-typed arg0 values.

Added in version 2.26.

get_arg0_path() → str | None

Convenience to get the first item in the body of message.

See get_arg0 for returning string-typed arg0 values.

Added in version 2.80.

get_body() → Variant | None

Gets the body of a message.

Added in version 2.26.

get_byte_order() → DBusMessageByteOrder

Gets the byte order of message.

get_destination() → str | None

Convenience getter for the DESTINATION header field.

Added in version 2.26.

get_error_name() → str | None

Convenience getter for the ERROR_NAME header field.

Added in version 2.26.

get_flags() → DBusMessageFlags

Gets the flags for message.

Added in version 2.26.

get_header(header_field: DBusMessageHeaderField) → Variant | None

Gets a header field on message.

The caller is responsible for checking the type of the returned Variant matches what is expected.

Added in version 2.26.

Parameters:

header_field – A 8-bit unsigned integer (typically a value from the DBusMessageHeaderField enumeration)

get_header_fields() → bytes

Gets an array of all header fields on message that are set.

Added in version 2.26.

get_interface() → str | None

Convenience getter for the INTERFACE header field.

Added in version 2.26.

get_locked() → bool

Checks whether message is locked. To monitor changes to this value, conncet to the Object::notify signal to listen for changes on the DBusMessage:locked property.

Added in version 2.26.

get_member() → str | None

Convenience getter for the MEMBER header field.

Added in version 2.26.

get_message_type() → DBusMessageType

Gets the type of message.

Added in version 2.26.

get_num_unix_fds() → int

Convenience getter for the NUM_UNIX_FDS header field.

Added in version 2.26.

get_path() → str | None

Convenience getter for the PATH header field.

Added in version 2.26.

get_reply_serial() → int

Convenience getter for the REPLY_SERIAL header field.

Added in version 2.26.

get_sender() → str | None

Convenience getter for the SENDER header field.

Added in version 2.26.

get_serial() → int

Gets the serial for message.

Added in version 2.26.

get_signature() → str

Convenience getter for the SIGNATURE header field.

This will always be non-None, but may be an empty string.

Added in version 2.26.

get_unix_fd_list() → 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 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, ...).

Added in version 2.26.

lock() → None

If message is locked, does nothing. Otherwise locks the message.

Added in version 2.26.

new_method_error_literal(error_name: str, error_message: str) → DBusMessage

Creates a new DBusMessage that is an error reply to method_call_message.

Added in version 2.26.

Parameters:

  • error_name – A valid D-Bus error name.

  • error_message – The D-Bus error message.

new_method_reply() → DBusMessage

Creates a new DBusMessage that is a reply to method_call_message.

Added in version 2.26.

print_(indent: int) → str
Parameters:

indent

set_body(body: Variant) → None

Sets the body message. As a side-effect the SIGNATURE header field is set to the type string of body (or cleared if body is None).

If body is floating, message assumes ownership of body.

Added in version 2.26.

Parameters:

body – Either None or a Variant that is a tuple.

set_byte_order(byte_order: DBusMessageByteOrder) → None

Sets the byte order of message.

Parameters:

byte_order – The byte order.

set_destination(value: str | None = None) → None

Convenience setter for the DESTINATION header field.

Added in version 2.26.

Parameters:

value – The value to set.

set_error_name(value: str) → None

Convenience setter for the ERROR_NAME header field.

Added in version 2.26.

Parameters:

value – The value to set.

set_flags(flags: DBusMessageFlags) → None

Sets the flags to set on message.

Added in version 2.26.

Parameters:

flags – Flags for message that are set (typically values from the DBusMessageFlags enumeration bitwise ORed together).

set_header(header_field: DBusMessageHeaderField, value: Variant | None = None) → None

Sets a header field on message.

If value is floating, message assumes ownership of value.

Added in version 2.26.

Parameters:

  • header_field – A 8-bit unsigned integer (typically a value from the DBusMessageHeaderField enumeration)

  • value – A Variant to set the header field or None to clear the header field.

set_interface(value: str | None = None) → None

Convenience setter for the INTERFACE header field.

Added in version 2.26.

Parameters:

value – The value to set.

set_member(value: str | None = None) → None

Convenience setter for the MEMBER header field.

Added in version 2.26.

Parameters:

value – The value to set.

set_message_type(type: DBusMessageType) → None

Sets message to be of type.

Added in version 2.26.

Parameters:

type – A 8-bit unsigned integer (typically a value from the DBusMessageType enumeration).

set_num_unix_fds(value: int) → None

Convenience setter for the NUM_UNIX_FDS header field.

Added in version 2.26.

Parameters:

value – The value to set.

set_path(value: str | None = None) → None

Convenience setter for the PATH header field.

Added in version 2.26.

Parameters:

value – The value to set.

set_reply_serial(value: int) → None

Convenience setter for the REPLY_SERIAL header field.

Added in version 2.26.

Parameters:

value – The value to set.

set_sender(value: str | None = None) → None

Convenience setter for the SENDER header field.

Added in version 2.26.

Parameters:

value – The value to set.

set_serial(serial: int) → None

Sets the serial for message.

Added in version 2.26.

Parameters:

serial – A guint32.

set_signature(value: str | None = None) → None

Convenience setter for the SIGNATURE header field.

Added in version 2.26.

Parameters:

value – The value to set.

set_unix_fd_list(fd_list: UnixFDList | None = None) → None

Sets the UNIX file descriptors associated with message. As a side-effect the NUM_UNIX_FDS header field is set to the number of fds in fd_list (or cleared if fd_list is 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.

Added in version 2.26.

Parameters:

fd_list – A UnixFDList or None.

to_blob(capabilities: DBusCapabilityFlags) → bytes

Serializes message to a blob. The byte order returned by get_byte_order() will be used.

Added in version 2.26.

Parameters:

capabilities – A DBusCapabilityFlags describing what protocol features are supported.

to_gerror() → bool

If message is not of type ERROR does nothing and returns False.

Otherwise this method encodes the error in message as a Error using g_dbus_error_set_dbus_error() using the information in the ERROR_NAME header field of message as well as the first string item in message’s body.

Added in version 2.26.

Properties

class DBusMessage
props.locked: bool