Skip to content

Gio.DBusMessage

class — extends GObject.Object

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

Constructors

new

@classmethod
def new(cls) -> DBusMessage

Creates a new empty DBusMessage.

new_from_blob

@classmethod
def new_from_blob(cls, blob: list[int], capabilities: DBusCapabilityFlags | int) -> DBusMessage

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

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

Parameters:

  • blob — A blob representing a binary D-Bus message.
  • capabilities — A DBusCapabilityFlags describing what protocol features are supported.

new_method_call

@classmethod
def new_method_call(cls, name: str | None, path: str, interface_: str | None, method: str) -> DBusMessage

Creates a new DBusMessage for a method call.

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.

new_signal

@classmethod
def new_signal(cls, path: str, interface_: str, signal: str) -> DBusMessage

Creates a new DBusMessage for a signal emission.

Parameters:

  • path — A valid object path.
  • interface_ — A valid D-Bus interface name.
  • signal — A valid signal name.

Methods

copy

def copy(self) -> DBusMessage

Copies message. The copy is a deep copy and the returned DBusMessage is completely identical except that it is guaranteed to not be locked.

This operation can fail if e.g. message contains file descriptors and the per-process or system-wide open files limit is reached.

get_arg0

def get_arg0(self) -> str | None

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

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

get_arg0_path

def get_arg0_path(self) -> str | None

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

See DBusMessage.get_arg0 for returning string-typed arg0 values.

get_body

def get_body(self) -> GLib.Variant | None

Gets the body of a message.

get_byte_order

def get_byte_order(self) -> DBusMessageByteOrder

Gets the byte order of message.

get_destination

def get_destination(self) -> str | None

Convenience getter for the DBusMessageHeaderField.DESTINATION header field.

get_error_name

def get_error_name(self) -> str | None

Convenience getter for the DBusMessageHeaderField.ERROR_NAME header field.

get_flags

def get_flags(self) -> DBusMessageFlags

Gets the flags for message.

get_header

def get_header(self, header_field: DBusMessageHeaderField | int) -> GLib.Variant | None

Gets a header field on message.

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

Parameters:

get_header_fields

def get_header_fields(self) -> list[int]

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

get_interface

def get_interface(self) -> str | None

Convenience getter for the DBusMessageHeaderField.INTERFACE header field.

get_locked

def get_locked(self) -> bool

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

get_member

def get_member(self) -> str | None

Convenience getter for the DBusMessageHeaderField.MEMBER header field.

get_message_type

def get_message_type(self) -> DBusMessageType

Gets the type of message.

get_num_unix_fds

def get_num_unix_fds(self) -> int

Convenience getter for the DBusMessageHeaderField.NUM_UNIX_FDS header field.

get_path

def get_path(self) -> str | None

Convenience getter for the DBusMessageHeaderField.PATH header field.

get_reply_serial

def get_reply_serial(self) -> int

Convenience getter for the DBusMessageHeaderField.REPLY_SERIAL header field.

get_sender

def get_sender(self) -> str | None

Convenience getter for the DBusMessageHeaderField.SENDER header field.

get_serial

def get_serial(self) -> int

Gets the serial for message.

get_signature

def get_signature(self) -> str

Convenience getter for the DBusMessageHeaderField.SIGNATURE header field.

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

get_unix_fd_list

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

lock

def lock(self) -> None

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

new_method_error_literal

def new_method_error_literal(self, error_name: str, error_message: str) -> DBusMessage

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

Parameters:

  • error_name — A valid D-Bus error name.
  • error_message — The D-Bus error message.

new_method_reply

def new_method_reply(self) -> DBusMessage

Creates a new DBusMessage that is a reply to method_call_message.

print

def print(self, indent: int) -> str

Produces a human-readable multi-line description of message.

The contents of the description has no ABI guarantees, the contents and formatting is subject to change at any time. Typical output looks something like this: 

Flags:   none
Version: 0
Serial:  4
Headers:
  path -> objectpath '/org/gtk/GDBus/TestObject'
  interface -> 'org.gtk.GDBus.TestInterface'
  member -> 'GimmeStdout'
  destination -> ':1.146'
Body: ()
UNIX File Descriptors:
  (none)
or 
Flags:   no-reply-expected
Version: 0
Serial:  477
Headers:
  reply-serial -> uint32 4
  destination -> ':1.159'
  sender -> ':1.146'
  num-unix-fds -> uint32 1
Body: ()
UNIX File Descriptors:
  fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635

Parameters:

  • indent — Indentation level.

set_body

def set_body(self, body: GLib.Variant) -> None

Sets the body message. As a side-effect the DBusMessageHeaderField.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.

Parameters:

set_byte_order

def set_byte_order(self, byte_order: DBusMessageByteOrder | int) -> None

Sets the byte order of message.

Parameters:

  • byte_order — The byte order.

set_destination

def set_destination(self, value: str | None = ...) -> None

Convenience setter for the DBusMessageHeaderField.DESTINATION header field.

Parameters:

  • value — The value to set.

set_error_name

def set_error_name(self, value: str) -> None

Convenience setter for the DBusMessageHeaderField.ERROR_NAME header field.

Parameters:

  • value — The value to set.

set_flags

def set_flags(self, flags: DBusMessageFlags | int) -> None

Sets the flags to set on message.

Parameters:

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

set_header

def set_header(self, header_field: DBusMessageHeaderField | int, value: GLib.Variant | None = ...) -> None

Sets a header field on message.

If value is floating, message assumes ownership of value.

Parameters:

  • header_field — A 8-bit unsigned integer (typically a value from the DBusMessageHeaderField enumeration)
  • value — A GLib.Variant to set the header field or None to clear the header field.

set_interface

def set_interface(self, value: str | None = ...) -> None

Convenience setter for the DBusMessageHeaderField.INTERFACE header field.

Parameters:

  • value — The value to set.

set_member

def set_member(self, value: str | None = ...) -> None

Convenience setter for the DBusMessageHeaderField.MEMBER header field.

Parameters:

  • value — The value to set.

set_message_type

def set_message_type(self, type: DBusMessageType | int) -> None

Sets message to be of type.

Parameters:

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

set_num_unix_fds

def set_num_unix_fds(self, value: int) -> None

Convenience setter for the DBusMessageHeaderField.NUM_UNIX_FDS header field.

Parameters:

  • value — The value to set.

set_path

def set_path(self, value: str | None = ...) -> None

Convenience setter for the DBusMessageHeaderField.PATH header field.

Parameters:

  • value — The value to set.

set_reply_serial

def set_reply_serial(self, value: int) -> None

Convenience setter for the DBusMessageHeaderField.REPLY_SERIAL header field.

Parameters:

  • value — The value to set.

set_sender

def set_sender(self, value: str | None = ...) -> None

Convenience setter for the DBusMessageHeaderField.SENDER header field.

Parameters:

  • value — The value to set.

set_serial

def set_serial(self, serial: int) -> None

Sets the serial for message.

The D-Bus specification does not allow the serial to be zero.

Parameters:

  • serial — A #guint32, which must not be zero.

set_signature

def set_signature(self, value: str | None = ...) -> None

Convenience setter for the DBusMessageHeaderField.SIGNATURE header field.

Parameters:

  • value — The value to set.

set_unix_fd_list

def set_unix_fd_list(self, fd_list: UnixFDList | None = ...) -> None

Sets the UNIX file descriptors associated with message. As a side-effect the DBusMessageHeaderField.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.

Parameters:

to_blob

def to_blob(self, capabilities: DBusCapabilityFlags | int) -> list[int]

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

Parameters:

to_gerror

def to_gerror(self) -> bool

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

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

Static functions

bytes_needed

@staticmethod
def bytes_needed(blob: list[int]) -> int

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

Parameters:

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

Properties

locked

locked: bool  # read-only