Gio.DBusMessage¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`bytes_needed` (blob)
class	`new` ()
class	`new_from_blob` (blob, capabilities)
class	`new_method_call` (name, path, interface_, method)
class	`new_signal` (path, interface_, signal)
	`copy` ()
	`get_arg0` ()
	`get_arg0_path` ()
	`get_body` ()
	`get_byte_order` ()
	`get_destination` ()
	`get_error_name` ()
	`get_flags` ()
	`get_header` (header_field)
	`get_header_fields` ()
	`get_interface` ()
	`get_locked` ()
	`get_member` ()
	`get_message_type` ()
	`get_num_unix_fds` ()
	`get_path` ()
	`get_reply_serial` ()
	`get_sender` ()
	`get_serial` ()
	`get_signature` ()
	`get_unix_fd_list` ()
	`lock` ()
	`new_method_error_literal` (error_name, error_message)
	`new_method_reply` ()
	`print_` (indent)
	`set_body` (body)
	`set_byte_order` (byte_order)
	`set_destination` (value)
	`set_error_name` (value)
	`set_flags` (flags)
	`set_header` (header_field, value)
	`set_interface` (value)
	`set_member` (value)
	`set_message_type` (type)
	`set_num_unix_fds` (value)
	`set_path` (value)
	`set_reply_serial` (value)
	`set_sender` (value)
	`set_serial` (serial)
	`set_signature` (value)
	`set_unix_fd_list` (fd_list)
	`to_blob` (capabilities)
	`to_gerror` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Name	Type	Flags	Short Description
`locked`	`bool`	r

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Gio.DBusMessage(**kwargs)¶

Bases:: GObject.Object
Abstract:: No

A type for representing D-Bus messages that can be sent or received on a [class`Gio`.DBusConnection].

Added in version 2.26.

classmethod bytes_needed(blob)[source]¶

Parameters:: blob (bytes) – a blob representing a binary D-Bus message.
Raises:: GLib.Error
Returns:: Number of bytes needed or -1 if error is set
Return type:: int

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

An error will be returned if blob contains invalid data, or if not enough data is available to determine the size.

Added in version 2.26.

classmethod new()[source]¶

Returns:: The D-Bus message
Return type:: Gio.DBusMessage

Creates a new empty D-Bus message.

Added in version 2.26.

classmethod new_from_blob(blob, capabilities)[source]¶

Parameters:

blob (bytes) – a blob representing a binary D-Bus message
capabilities (Gio.DBusCapabilityFlags) – flags describing what protocol features are supported

Raises:

GLib.Error

Returns:

The D-Bus message

Return type:

Gio.DBusMessage

Creates a new D-Bus message from the data stored at blob.

You must have previously called [func`Gio`.DBusMessage.bytes_needed] on blob, and ensure that blob is at least as long as the return value from that function indicates. In particular, that means that blob must be at least 16 bytes long (but will typically be much longer).

The byte order that the message was in can be retrieved using [method`Gio`.DBusMessage.get_byte_order].

If the blob cannot be parsed, contains invalid fields, or contains invalid headers, [error`Gio`.IOErrorEnum.INVALID_ARGUMENT] will be returned.

Added in version 2.26.

classmethod new_method_call(name, path, interface_, method)[source]¶

Parameters:

name (str or None) – a valid D-Bus name, or NULL if no destination is needed
path (str) – a valid object path
interface (str or None) – a valid D-Bus interface name, or NULL if none is needed
method (str) – a valid method name

Returns:

The D-Bus message

Return type:

Gio.DBusMessage

Creates a new D-Bus message for a method call.

Added in version 2.26.

classmethod new_signal(path, interface_, signal)[source]¶

Parameters:

path (str) – a valid object path
interface (str) – a valid D-Bus interface name
signal (str) – a valid signal name

Returns:

The D-Bus message

Return type:

Gio.DBusMessage

Creates a new D-Bus message for a signal emission.

Added in version 2.26.

copy()[source]¶

Raises:: GLib.Error
Returns:: A new D-Bus message
Return type:: Gio.DBusMessage

Copies self with a deep copy.

The returned D-Bus message is completely identical to self except that it is guaranteed to not be locked.

This operation can fail if (for example) self contains file descriptors and the per-process or system-wide open files limit is reached.

Added in version 2.26.

get_arg0()[source]¶

Returns:: The string item, or NULL if the first item in the body of self is not a string
Return type:: str or None

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

See [method`Gio`.DBusMessage.get_arg0_path] for returning object-path-typed arg0 values.

Added in version 2.26.

get_arg0_path()[source]¶

Returns:: The object path item, or NULL if the first item in the body of self is not an object path
Return type:: str or None

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

See [method`Gio`.DBusMessage.get_arg0] for returning string-typed arg0 values.

Added in version 2.80.

get_body()[source]¶

Returns:: A [type`GLib`.Variant], or NULL if the body is empty
Return type:: GLib.Variant or None

Gets the body of a message.

Added in version 2.26.

get_byte_order()[source]¶

Returns:: The byte order
Return type:: Gio.DBusMessageByteOrder

Gets the byte order of self.

get_destination()[source]¶

Returns:: The value
Return type:: str or None

Convenience getter for the [enum`Gio`.DBusMessageHeaderField.DESTINATION] header field.

Added in version 2.26.

get_error_name()[source]¶

Returns:: The value
Return type:: str or None

Convenience getter for the [enum`Gio`.DBusMessageHeaderField.ERROR_NAME] header field.

Added in version 2.26.

get_flags()[source]¶

Returns:: Flags that are set (typically values from the [flags`Gio`.DBusMessageFlags] enumeration bitwise ORed together)
Return type:: Gio.DBusMessageFlags

Gets the flags for self.

Added in version 2.26.

get_header(header_field)[source]¶

Parameters:: header_field (Gio.DBusMessageHeaderField) – a 8-bit unsigned integer (typically a value from the [enum`Gio`.DBusMessageHeaderField] enumeration)
Returns:: A [type`GLib`.Variant] with the value, or NULL if the header was not found
Return type:: GLib.Variant or None

Gets a header field on self.

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

Added in version 2.26.

get_header_fields()[source]¶

Returns:: An array of header fields terminated by [enum`Gio`.DBusMessageHeaderField.INVALID]
Return type:: bytes

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

Each element in the array is an unsigned char.

Added in version 2.26.

get_interface()[source]¶

Returns:: The value
Return type:: str or None

Convenience getter for the [enum`Gio`.DBusMessageHeaderField.INTERFACE] header field.

Added in version 2.26.

get_locked()[source]¶

Returns:: true if self is locked, false otherwise
Return type:: bool

Checks whether self is locked.

To monitor changes to this value, connect to the [signal`GObject`.Object::notify] signal to listen for changes on the [property`Gio`.DBusMessage:locked] property.

Added in version 2.26.

get_member()[source]¶

Returns:: The value
Return type:: str or None

Convenience getter for the [enum`Gio`.DBusMessageHeaderField.MEMBER] header field.

Added in version 2.26.

get_message_type()[source]¶

Returns:: A 8-bit unsigned integer (typically a value from the [enum`Gio`.DBusMessageType] enumeration)
Return type:: Gio.DBusMessageType

Gets the type of self.

Added in version 2.26.

get_num_unix_fds()[source]¶

Returns:: The value
Return type:: int

Convenience getter for the [enum`Gio`.DBusMessageHeaderField.NUM_UNIX_FDS] header field.

Added in version 2.26.

get_path()[source]¶

Returns:: The value
Return type:: str or None

Convenience getter for the [enum`Gio`.DBusMessageHeaderField.PATH] header field.

Added in version 2.26.

get_reply_serial()[source]¶

Returns:: The value
Return type:: int

Convenience getter for the [enum`Gio`.DBusMessageHeaderField.REPLY_SERIAL] header field.

Added in version 2.26.

get_sender()[source]¶

Returns:: The value
Return type:: str or None

Convenience getter for the [enum`Gio`.DBusMessageHeaderField.SENDER] header field.

Added in version 2.26.

get_serial()[source]¶

Returns:: The serial number, which should not be zero
Return type:: int

Gets the serial for self.

Added in version 2.26.

get_signature()[source]¶

Returns:: The value
Return type:: str

Convenience getter for the [enum`Gio`.DBusMessageHeaderField.SIGNATURE header field.

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

Added in version 2.26.

get_unix_fd_list()[source]¶

Returns:: A [class`Gio`.UnixFDList] or NULL if no file descriptors are associated
Return type:: Gio.UnixFDList or None

Gets the UNIX file descriptors associated with self, 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 [method`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, ...).

Added in version 2.26.

lock()[source]¶

Locks the message.

If self is locked already, this does nothing.

Added in version 2.26.

new_method_error_literal(error_name, error_message)[source]¶

Parameters:

error_name (str) – a valid D-Bus error name
error_message (str) – the D-Bus error message

Returns:

The D-Bus message

Return type:

Gio.DBusMessage

Creates a new D-Bus message that is an error reply to self.

Added in version 2.26.

new_method_reply()[source]¶

Returns:: The D-Bus message
Return type:: Gio.DBusMessage

Creates a new D-Bus message that is a reply to self.

Added in version 2.26.

print_(indent)[source]¶

Parameters:: indent (int) – indentation level
Returns:: Human readable description of self
Return type:: str

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

The contents and formatting are subject to change at any time and no ABI guarantees are given. 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

``

Added in version 2.26.

set_body(body)[source]¶

Parameters:: body (GLib.Variant) – a [type`GLib`.Variant] containing a tuple, or NULL if no body is needed

Sets the body of self.

As a side-effect the [enum`Gio`.DBusMessageHeaderField.SIGNATURE] header field is set to the type string of body (or cleared if body is NULL).

If body is floating, self assumes ownership of body.

Added in version 2.26.

set_byte_order(byte_order)[source]¶

Parameters:: byte_order (Gio.DBusMessageByteOrder) – the byte order

Sets the byte order of self.

set_destination(value)[source]¶

Parameters:: value (str or None) – the value to set

Convenience setter for the [enum`Gio`.DBusMessageHeaderField.DESTINATION] header field.

Added in version 2.26.

set_error_name(value)[source]¶

Parameters:: value (str or None) – the value to set

Convenience setter for the [enum`Gio`.DBusMessageHeaderField.ERROR_NAME] header field.

Added in version 2.26.

set_flags(flags)[source]¶

Parameters:: flags (Gio.DBusMessageFlags) – flags for self that are set (typically values from the [flags`Gio`.DBusMessageFlags] enumeration bitwise ORed together)

Sets the flags to set on self.

Added in version 2.26.

set_header(header_field, value)[source]¶

Parameters:

header_field (Gio.DBusMessageHeaderField) – a 8-bit unsigned integer (typically a value from the [enum`Gio`.DBusMessageHeaderField enumeration)
value (GLib.Variant or None) – a [type`GLib`.Variant] to set the header field, or NULL to clear the header field.

Sets a header field on self.

If value is floating, self assumes ownership of value.

Added in version 2.26.

set_interface(value)[source]¶

Parameters:: value (str or None) – the value to set

Convenience setter for the [enum`Gio`.DBusMessageHeaderField.INTERFACE] header field.

Added in version 2.26.

set_member(value)[source]¶

Parameters:: value (str or None) – the value to set

Convenience setter for the [enum`Gio`.DBusMessageHeaderField.MEMBER] header field.

Added in version 2.26.

set_message_type(type)[source]¶

Parameters:: type (Gio.DBusMessageType) – a 8-bit unsigned integer (typically a value from the [enum`Gio`.DBusMessageType] enumeration)

Sets self to be of type.

Added in version 2.26.

set_num_unix_fds(value)[source]¶

Parameters:: value (int) – the value to set

Convenience setter for the [enum`Gio`.DBusMessageHeaderField.NUM_UNIX_FDS] header field.

Added in version 2.26.

set_path(value)[source]¶

Parameters:: value (str or None) – the value to set

Convenience setter for the [enum`Gio`.DBusMessageHeaderField.PATH] header field.

Added in version 2.26.

set_reply_serial(value)[source]¶

Parameters:: value (int) – the value to set

Convenience setter for the [enum`Gio`.DBusMessageHeaderField.REPLY_SERIAL] header field.

Added in version 2.26.

set_sender(value)[source]¶

Parameters:: value (str or None) – the value to set

Convenience setter for the [enum`Gio`.DBusMessageHeaderField.SENDER] header field.

Added in version 2.26.

set_serial(serial)[source]¶

Parameters:: serial (int) – a serial number, which must not be zero

Sets the serial for self.

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

Added in version 2.26.

set_signature(value)[source]¶

Parameters:: value (str or None) – the value to set

Convenience setter for the [enum`Gio`.DBusMessageHeaderField.SIGNATURE] header field.

Added in version 2.26.

set_unix_fd_list(fd_list)[source]¶

Parameters:: fd_list (Gio.UnixFDList or None) – A [class`Gio`.UnixFDList], or NULL to clear

Sets the UNIX file descriptors associated with self.

As a side-effect the [enum`Gio`.DBusMessageHeaderField.NUM_UNIX_FDS] header field is set to the number of fds in fd_list (or cleared if fd_list is NULL).

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.

to_blob(capabilities)[source]¶

Parameters:: capabilities (Gio.DBusCapabilityFlags) – flags describing what protocol features are supported
Raises:: GLib.Error
Returns:: A pointer to a valid binary D-Bus message of out_size bytes generated by self
Return type:: bytes

Serializes self to a blob.

The byte order returned by [method`Gio`.DBusMessage.get_byte_order] will be used.

Added in version 2.26.

to_gerror()[source]¶

Raises:: GLib.Error
Returns:: true if error was set, false otherwise
Return type:: bool

Encodes the error in self as a [type`GLib`.Error].

If self is of type [enum`Gio`.DBusMessageType.ERROR], this function calls [func`Gio`.DBusError.set_dbus_error] using the information in the [enum`Gio`.DBusMessageHeaderField.ERROR_NAME] header field of self as well as the first string item in self’s body.

If self is not of type [enum`Gio`.DBusMessageType.ERROR], this function does nothing and returns false.

Added in version 2.26.

Property Details¶

Gio.DBusMessage.props.locked¶

Name:: locked
Type:: bool
Default Value:: False
Flags:: READABLE