DBusMessage#
Added in version 2.26.
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 atblob
. The byte order that the message was in can be retrieved usingget_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_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 theObject
::notify signal to listen for changes on theDBusMessage
:locked property.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_reply_serial() int #
Convenience getter for the
REPLY_SERIAL
header field.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, ifget_handle()
returns 5, that is intended to be a reference to the file descriptor that can be accessed byg_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 tomethod_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 tomethod_call_message
.Added in version 2.26.
- set_body(body: Variant) None #
Sets the body
message
. As a side-effect theSIGNATURE
header field is set to the type string ofbody
(or cleared ifbody
isNone
).If
body
is floating,message
assumes ownership ofbody
.Added in version 2.26.
- Parameters:
body – Either
None
or aVariant
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 theDBusMessageFlags
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 ofvalue
.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 orNone
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 oftype
.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 theNUM_UNIX_FDS
header field is set to the number of fds infd_list
(or cleared iffd_list
isNone
).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
orNone
.
- to_blob(capabilities: DBusCapabilityFlags) bytes #
Serializes
message
to a blob. The byte order returned byget_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 typeERROR
does nothing and returnsFalse
.Otherwise this method encodes the error in
message
as aError
using g_dbus_error_set_dbus_error() using the information in theERROR_NAME
header field ofmessage
as well as the first string item inmessage
’s body.Added in version 2.26.