Class: Gio::DBusMessage

Inherits:
Object
  • Object
show all
Defined in:
(unknown)

Overview

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

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path, interface_, signal) ⇒ Gio::DBusMessage

Creates a new GDBus::Message for a signal emission.

Parameters:

  • path (String) —

    A valid object path.

  • interface_ (String) —

    A valid D-Bus interface name.

  • signal (String) —

    A valid signal name.

Class Method Details

.bytes_needed(blob, blob_len) ⇒ Gio::gssize

Utility function to calculate how many bytes are needed to completely deserialize the D-Bus message stored at blob. blob contains invalid data or not enough data is available to determine the size).

Parameters:

  • blob (Array<Integer>) —

    A blob representing a binary D-Bus message.

  • blob_len (Integer) —

    The length of blob (must be at least 16).

Returns:

  • (Gio::gssize) —

    Number of bytes needed or -1 if error is set (e.g. if

Instance Method Details

#arg0 ⇒ String

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

See [methodGio.DBusMessage.get_arg0_path] for returning object-path-typed arg0 values. message is not a string.

Returns:

  • (String) —

    The string item or nil if the first item in the body of

#arg0_path ⇒ String

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

See [methodGio.DBusMessage.get_arg0] for returning string-typed arg0 values.

Returns:

  • (String) —

    The object path item or NULL if the first item in the body of message is not an object path.

#body ⇒ GLib::Variant

Gets the body of a message. empty. Do not free, it is owned by message.

Returns:

  • (GLib::Variant) —

    A #GVariant or nil if the body is

#body=(body) ⇒ nil

Sets the body message. As a side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the type string of body (or cleared if body is nil).

If body is floating, message assumes ownership of body.

Parameters:

  • body (GLib::Variant) —

    Either nil or a #GVariant that is a tuple.

Returns:

  • (nil)

#byte_order ⇒ Gio::DBusMessageByteOrder

Gets the byte order of message.

Returns:

#byte_order=(byte_order) ⇒ nil

Sets the byte order of message.

Parameters:

Returns:

  • (nil)

#copy ⇒ Gio::DBusMessage

Copies message. The copy is a deep copy and the returned GDBus::Message 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.

Returns:

  • (Gio::DBusMessage) —

    A new GDBus::Message or nil if error is set. Free with g_object_unref().

#destination ⇒ String

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.

Returns:

  • (String) —

    The value.

#destination=(value) ⇒ nil

Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.

Parameters:

  • value (String) —

    The value to set.

Returns:

  • (nil)

#error_name ⇒ String

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.

Returns:

  • (String) —

    The value.

#error_name=(value) ⇒ nil

Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.

Parameters:

  • value (String) —

    The value to set.

Returns:

  • (nil)

#flags ⇒ Gio::DBusMessageFlags

Gets the flags for message.

Returns:

  • (Gio::DBusMessageFlags) —

    Flags that are set (typically values from the GDBus::MessageFlags enumeration bitwise ORed together).

#flags=(flags) ⇒ nil

Sets the flags to set on message. enumeration bitwise ORed together).

Parameters:

  • flags (Gio::DBusMessageFlags) —

    Flags for message that are set (typically values from the GDBus::MessageFlags

Returns:

  • (nil)

#get_header(header_field) ⇒ GLib::Variant

Gets a header field on message.

The caller is responsible for checking the type of the returned #GVariant matches what is expected. otherwise. Do not free, it is owned by message.

Parameters:

  • header_field (Gio::DBusMessageHeaderField) —

    A 8-bit unsigned integer (typically a value from the GDBus::MessageHeaderField enumeration)

Returns:

  • (GLib::Variant) —

    A #GVariant with the value if the header was found, nil

#header_fields ⇒ Array<Integer>

Gets an array of all header fields on message that are set. terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a #guchar. Free with g_free().

Returns:

  • (Array<Integer>) —

    An array of header fields

#interface ⇒ String

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.

Returns:

  • (String) —

    The value.

#interface=(value) ⇒ nil

Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.

Parameters:

  • value (String) —

    The value to set.

Returns:

  • (nil)

#lock ⇒ nil

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

Returns:

  • (nil)

#locked ⇒ Boolean

Checks whether message is locked. To monitor changes to this value, conncet to the #GObject::notify signal to listen for changes on the GDBus::Message:locked property.

Returns:

  • (Boolean) —

    true if message is locked, false otherwise.

#locked=(locked) ⇒ Boolean

Parameters:

  • locked (Boolean)

Returns:

  • (Boolean) —

    locked

  • (Boolean) —

    locked

#locked? ⇒ Boolean

Returns locked.

Returns:

  • (Boolean) —

    locked

#member ⇒ String

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.

Returns:

  • (String) —

    The value.

#member=(value) ⇒ nil

Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.

Parameters:

  • value (String) —

    The value to set.

Returns:

  • (nil)

#message_type ⇒ Gio::DBusMessageType

Gets the type of message.

Returns:

  • (Gio::DBusMessageType) —

    A 8-bit unsigned integer (typically a value from the GDBus::MessageType enumeration).

#message_type=(type) ⇒ nil

Sets message to be of type.

Parameters:

  • type (Gio::DBusMessageType) —

    A 8-bit unsigned integer (typically a value from the GDBus::MessageType enumeration).

Returns:

  • (nil)

#new_method_error(error_name, error_message_format, array) ⇒ Gio::DBusMessage

Creates a new GDBus::Message that is an error reply to method_call_message.

Parameters:

  • error_name (String) —

    A valid D-Bus error name.

  • error_message_format (String) —

    The D-Bus error message in a printf() format.

  • array (Array) —

    Arguments for error_message_format.

Returns:

#new_method_error_literal(error_name, error_message) ⇒ Gio::DBusMessage

Creates a new GDBus::Message that is an error reply to method_call_message.

Parameters:

  • error_name (String) —

    A valid D-Bus error name.

  • error_message (String) —

    The D-Bus error message.

Returns:

#new_method_error_valist(error_name, error_message_format, var_args) ⇒ Gio::DBusMessage

Like g_dbus_message_new_method_error() but intended for language bindings.

Parameters:

  • error_name (String) —

    A valid D-Bus error name.

  • error_message_format (String) —

    The D-Bus error message in a printf() format.

  • var_args (Gio::va_list) —

    Arguments for error_message_format.

Returns:

#new_method_reply ⇒ Gio::DBusMessage

Creates a new GDBus::Message that is a reply to method_call_message.

Returns:

#num_unix_fds ⇒ Integer

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.

Returns:

  • (Integer) —

    The value.

#num_unix_fds=(value) ⇒ nil

Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.

Parameters:

  • value (Integer) —

    The value to set.

Returns:

  • (nil)

#path ⇒ String

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.

Returns:

  • (String) —

    The value.

#path=(value) ⇒ nil

Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.

Parameters:

  • value (String) —

    The value to set.

Returns:

  • (nil)

#print(indent) ⇒ String

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 (Integer) —

    Indentation level.

Returns:

  • (String) —

    A string that should be freed with [funcGLib.free].

#reply_serial ⇒ Integer

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.

Returns:

  • (Integer) —

    The value.

#reply_serial=(value) ⇒ nil

Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.

Parameters:

  • value (Integer) —

    The value to set.

Returns:

  • (nil)

#sender ⇒ String

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.

Returns:

  • (String) —

    The value.

#sender=(value) ⇒ nil

Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.

Parameters:

  • value (String) —

    The value to set.

Returns:

  • (nil)

#serial ⇒ Integer

Gets the serial for message.

Returns:

  • (Integer) —

    A #guint32.

#serial=(serial) ⇒ nil

Sets the serial for message.

Parameters:

  • serial (Integer) —

    A #guint32.

Returns:

  • (nil)

#set_header(header_field, value) ⇒ nil

Sets a header field on message.

If value is floating, message assumes ownership of value.

Parameters:

  • header_field (Gio::DBusMessageHeaderField) —

    A 8-bit unsigned integer (typically a value from the GDBus::MessageHeaderField enumeration)

  • value (GLib::Variant) —

    A #GVariant to set the header field or nil to clear the header field.

Returns:

  • (nil)

#signature ⇒ String

Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.

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

Returns:

  • (String) —

    The value.

#signature=(value) ⇒ nil

Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.

Parameters:

  • value (String) —

    The value to set.

Returns:

  • (nil)

#to_blob(out_size, capabilities) ⇒ Array<Integer>

Serializes message to a blob. The byte order returned by g_dbus_message_get_byte_order() will be used. valid binary D-Bus message of out_size bytes generated by message or nil if error is set. Free with g_free().

Parameters:

  • out_size (Integer) —

    Return location for size of generated blob.

  • capabilities (Gio::DBusCapabilityFlags) —

    A GDBus::CapabilityFlags describing what protocol features are supported.

Returns:

  • (Array<Integer>) —

    A pointer to a

#to_gerror ⇒ Boolean

If message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does nothing and returns false.

Otherwise this method encodes the error in message as a #GError using g_dbus_error_set_dbus_error() using the information in the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of message as well as the first string item in message's body.

Returns:

  • (Boolean) —

    true if error was set, false otherwise.

#unix_fd_list ⇒ Gio::UnixFDList

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 g_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, ...). associated. Do not free, this object is owned by message.

Returns:

#unix_fd_list=(fd_list) ⇒ nil

Sets the UNIX file descriptors associated with message. As a side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field is set to the number of fds in fd_list (or cleared if fd_list is nil).

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:

Returns:

  • (nil)