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].

New 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 (e.g. if blob contains invalid data or not enough data is available to determine the size).
Return type:: int

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

New in version 2.26.

classmethod new()[source]¶

Returns:: A Gio.DBusMessage. Free with GObject.Object.unref().
Return type:: Gio.DBusMessage

Creates a new empty Gio.DBusMessage.

New 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) – A Gio.DBusCapabilityFlags describing what protocol features are supported.

Raises:

GLib.Error

Returns:

A new Gio.DBusMessage or None if error is set. Free with GObject.Object.unref().

Return type:

Gio.DBusMessage

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

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

New in version 2.26.

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

Parameters:

name (str or None) – A valid D-Bus name or None.
path (str) – A valid object path.
interface (str or None) – A valid D-Bus interface name or None.
method (str) – A valid method name.

Returns:

A Gio.DBusMessage. Free with GObject.Object.unref().

Return type:

Gio.DBusMessage

Creates a new Gio.DBusMessage for a method call.

New 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:

A Gio.DBusMessage. Free with GObject.Object.unref().

Return type:

Gio.DBusMessage

Creates a new Gio.DBusMessage for a signal emission.

New in version 2.26.

copy()[source]¶

Raises:: GLib.Error
Returns:: A new Gio.DBusMessage or None if error is set. Free with GObject.Object.unref().
Return type:: Gio.DBusMessage

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

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

New in version 2.26.

get_arg0()[source]¶

Returns:: The string item or None 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.

New 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.

New in version 2.80.

get_body()[source]¶

Returns:: A GLib.Variant or None if the body is empty. Do not free, it is owned by self.
Return type:: GLib.Variant or None

Gets the body of a message.

New 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 Gio.DBusMessageHeaderField.DESTINATION header field.

New in version 2.26.

get_error_name()[source]¶

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

Convenience getter for the Gio.DBusMessageHeaderField.ERROR_NAME header field.

New in version 2.26.

get_flags()[source]¶

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

Gets the flags for self.

New in version 2.26.

get_header(header_field)[source]¶

Parameters:: header_field (Gio.DBusMessageHeaderField) – A 8-bit unsigned integer (typically a value from the Gio.DBusMessageHeaderField enumeration)
Returns:: A GLib.Variant with the value if the header was found, None otherwise. Do not free, it is owned by self.
Return type:: GLib.Variant or None

Gets a header field on self.

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

New in version 2.26.

get_header_fields()[source]¶

Returns:: An array of header fields terminated by Gio.DBusMessageHeaderField.INVALID. Each element is a #guchar. Free with GLib.free().
Return type:: bytes

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

New in version 2.26.

get_interface()[source]¶

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

Convenience getter for the Gio.DBusMessageHeaderField.INTERFACE header field.

New 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, conncet to the GObject.Object ::notify signal to listen for changes on the Gio.DBusMessage :locked property.

New in version 2.26.

get_member()[source]¶

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

Convenience getter for the Gio.DBusMessageHeaderField.MEMBER header field.

New in version 2.26.

get_message_type()[source]¶

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

Gets the type of self.

New in version 2.26.

get_num_unix_fds()[source]¶

Returns:: The value.
Return type:: int

Convenience getter for the Gio.DBusMessageHeaderField.NUM_UNIX_FDS header field.

New in version 2.26.

get_path()[source]¶

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

Convenience getter for the Gio.DBusMessageHeaderField.PATH header field.

New in version 2.26.

get_reply_serial()[source]¶

Returns:: The value.
Return type:: int

Convenience getter for the Gio.DBusMessageHeaderField.REPLY_SERIAL header field.

New in version 2.26.

get_sender()[source]¶

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

Convenience getter for the Gio.DBusMessageHeaderField.SENDER header field.

New in version 2.26.

get_serial()[source]¶

Returns:: A #guint32.
Return type:: int

Gets the serial for self.

New in version 2.26.

get_signature()[source]¶

Returns:: The value.
Return type:: str

Convenience getter for the Gio.DBusMessageHeaderField.SIGNATURE header field.

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

New in version 2.26.

get_unix_fd_list()[source]¶

Returns:: A Gio.UnixFDList or None if no file descriptors are associated. Do not free, this object is owned by self.
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 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, ...).

New in version 2.26.

lock()[source]¶: If self is locked, does nothing. Otherwise locks the message.

New 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:

A Gio.DBusMessage. Free with GObject.Object.unref().

Return type:

Gio.DBusMessage

Creates a new Gio.DBusMessage that is an error reply to self.

New in version 2.26.

new_method_reply()[source]¶

Returns:: Gio.DBusMessage. Free with GObject.Object.unref().
Return type:: Gio.DBusMessage

Creates a new Gio.DBusMessage that is a reply to self.

New in version 2.26.

print_(indent)[source]¶

Parameters:: indent (int) – Indentation level.
Returns:: A string that should be freed with [func`GLib`.free].
Return type:: str

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

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

``

New in version 2.26.

set_body(body)[source]¶

Parameters:: body (GLib.Variant) – Either None or a GLib.Variant that is a tuple.

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

If body is floating, self assumes ownership of body.

New 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 Gio.DBusMessageHeaderField.DESTINATION header field.

New in version 2.26.

set_error_name(value)[source]¶

Parameters:: value (str) – The value to set.

Convenience setter for the Gio.DBusMessageHeaderField.ERROR_NAME header field.

New in version 2.26.

set_flags(flags)[source]¶

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

Sets the flags to set on self.

New 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 Gio.DBusMessageHeaderField enumeration)
value (GLib.Variant or None) – A GLib.Variant to set the header field or None to clear the header field.

Sets a header field on self.

If value is floating, self assumes ownership of value.

New in version 2.26.

set_interface(value)[source]¶

Parameters:: value (str or None) – The value to set.

Convenience setter for the Gio.DBusMessageHeaderField.INTERFACE header field.

New in version 2.26.

set_member(value)[source]¶

Parameters:: value (str or None) – The value to set.

Convenience setter for the Gio.DBusMessageHeaderField.MEMBER header field.

New in version 2.26.

set_message_type(type)[source]¶

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

Sets self to be of type.

New in version 2.26.

set_num_unix_fds(value)[source]¶

Parameters:: value (int) – The value to set.

Convenience setter for the Gio.DBusMessageHeaderField.NUM_UNIX_FDS header field.

New in version 2.26.

set_path(value)[source]¶

Parameters:: value (str or None) – The value to set.

Convenience setter for the Gio.DBusMessageHeaderField.PATH header field.

New in version 2.26.

set_reply_serial(value)[source]¶

Parameters:: value (int) – The value to set.

Convenience setter for the Gio.DBusMessageHeaderField.REPLY_SERIAL header field.

New in version 2.26.

set_sender(value)[source]¶

Parameters:: value (str or None) – The value to set.

Convenience setter for the Gio.DBusMessageHeaderField.SENDER header field.

New in version 2.26.

set_serial(serial)[source]¶

Parameters:: serial (int) – A #guint32, which must not be zero.

Sets the serial for self.

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

New in version 2.26.

set_signature(value)[source]¶

Parameters:: value (str or None) – The value to set.

Convenience setter for the Gio.DBusMessageHeaderField.SIGNATURE header field.

New in version 2.26.

set_unix_fd_list(fd_list)[source]¶

Parameters:: fd_list (Gio.UnixFDList or None) – A Gio.UnixFDList or None.

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

New in version 2.26.

to_blob(capabilities)[source]¶

Parameters:: capabilities (Gio.DBusCapabilityFlags) – A Gio.DBusCapabilityFlags 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 or None if error is set. Free with GLib.free().
Return type:: bytes

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

New in version 2.26.

to_gerror()[source]¶

Raises:: GLib.Error
Returns:: True if error was set, False otherwise.
Return type:: bool

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

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

New in version 2.26.

Property Details¶

Gio.DBusMessage.props.locked¶

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