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#

The type of the None singleton.