glibmm  2.32.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions
Gio::DBus::Message Class Reference

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

#include <giomm/dbusmessage.h>

Inheritance diagram for Gio::DBus::Message:
Inheritance graph
[legend]

List of all members.

Public Types

enum  ByteOrder {
  BYTE_ORDER_BIG_ENDIAN = 'B',
  BYTE_ORDER_LITTLE_ENDIAN = 'l'
}

Public Member Functions

virtual ~Message ()
GDBusMessage* gobj ()
 Provides access to the underlying C GObject.
const GDBusMessage* gobj () const
 Provides access to the underlying C GObject.
GDBusMessage* gobj_copy ()
 Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
Glib::ustring print (guint indent)
 Produces a human-readable multi-line description of message.
bool get_locked () const
 Checks whether message is locked.
void lock ()
 If message is locked, does nothing.
Glib::RefPtr< Messagecopy () const
 Copies message.
MessageType get_message_type () const
 Gets the type of message.
void set_message_type (MessageType type)
 Sets message to be of type.
ByteOrder get_byte_order () const
 Gets the byte order of message.
void set_byte_order (ByteOrder byte_order)
 Sets the byte order of message.
guint32 get_serial () const
 Gets the serial for message.
void set_serial (guint32 serial)
 Sets the serial for message.
MessageFlags get_flags () const
 Gets the flags for message.
void set_flags (MessageFlags flags)
 Sets the flags to set on message.
void get_body (Glib::VariantBase&value) const
 Gets the body of a message.
void set_body (const Glib::VariantBase& body)
 Sets the body message.
guint32 get_num_unix_fds () const
 Gets the UNIX file descriptors associated with message, if any.
void set_num_unix_fds (guint32 value)
 Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
void get_header (Glib::VariantBase&value, MessageHeaderField header_field) const
 Gets a header field on the message.
void set_header (MessageHeaderField header_field, const Glib::VariantBase&value)
 Sets a header field on message.
Glib::ArrayHandle< guchar > get_header_fields () const
 Gets an array of all header fields on message that are set.
Glib::ustring get_destination () const
 Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
void set_destination (const Glib::ustring&value)
 Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.
Glib::ustring get_error_name () const
 Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
void set_error_name (const Glib::ustring&value)
 Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.
Glib::ustring get_interface () const
 Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
void set_interface (const Glib::ustring&value)
 Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.
Glib::ustring get_member () const
 Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
void set_member (const Glib::ustring&value)
 Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.
Glib::ustring get_path () const
 Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_PATH header field.
void set_path (const Glib::ustring&value)
 Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_PATH header field.
guint32 get_reply_serial () const
 Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
void set_reply_serial (guint32 value)
 Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.
Glib::ustring get_sender () const
 Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
void set_sender (const Glib::ustring&value)
 Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_SENDER header field.
Glib::ustring get_signature () const
 Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
void set_signature (const Glib::ustring&value)
 Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
Glib::ustring get_arg0 () const
 Convenience to get the first item in the body of message.
guchar* to_blob (gsize& out_size, CapabilityFlags capabilities=CAPABILITY_FLAGS_NONE)
 Serializes message to a blob.
void to_exception ()
 If message is not of type DBUS_MESSAGE_TYPE_ERROR does nothing and returns false.
Glib::PropertyProxy_ReadOnly
< bool > 
property_locked () const
 Whether the message is locked.

Static Public Member Functions

static Glib::RefPtr< Messagecreate ()
 Creates a new empty DBusMessage.
static Glib::RefPtr< Messagecreate_signal (const Glib::ustring& path, const Glib::ustring& interface, const Glib::ustring& signal)
 Creates a new DBusMessage for a signal emission.
static Glib::RefPtr< Messagecreate_method_call (const Glib::ustring& name, const Glib::ustring& path, const Glib::ustring& interface, const Glib::ustring& method)
 Creates a new DBusMessage for a method call.
static Glib::RefPtr< Messagecreate_method_reply (const Glib::RefPtr< Message >& method_call_message)
 Creates a new DBusMessage that is a reply to method_call_message.
static Glib::RefPtr< Messagecreate_method_error_literal (const Glib::RefPtr< const Message >& method_call_message, const Glib::ustring& error_name, const Glib::ustring& error_message)
 Creates a new DBusMessage that is an error reply to method_call_message.
static Glib::RefPtr< Messagecreate_from_blob (const guchar* blob, gsize blob_len, CapabilityFlags capabilities=CAPABILITY_FLAGS_NONE)
 Creates a new DBusMessage from the data stored at blob.
static gssize bytes_needed (const guchar* blob, gsize blob_len)
 Utility function to calculate how many bytes are needed to completely deserialize the D-Bus message stored at blob.

Protected Member Functions

 Message ()

Related Functions

(Note that these are not member functions.)

Glib::RefPtr< Gio::DBus::Messagewrap (GDBusMessage* object, bool take_copy=false)
 A Glib::wrap() method for this object.

Detailed Description

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

Since glibmm 2.28:

Member Enumeration Documentation

Enumerator:
BYTE_ORDER_BIG_ENDIAN 
BYTE_ORDER_LITTLE_ENDIAN 

Constructor & Destructor Documentation

virtual Gio::DBus::Message::~Message ( ) [virtual]
Gio::DBus::Message::Message ( ) [protected]

Member Function Documentation

static gssize Gio::DBus::Message::bytes_needed ( const guchar *  blob,
gsize  blob_len 
) [static]

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

Since glibmm 2.26:
Parameters:
blobA blob represent a binary D-Bus message.
blob_lenThe length of blob (must be at least 16).
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).

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.

Since glibmm 2.26:
Returns:
A new DBusMessage or 0 if error is set. Free with Glib::object_unref().

Creates a new empty DBusMessage.

Since glibmm 2.26:
Returns:
A DBusMessage. Free with Glib::object_unref().
static Glib::RefPtr<Message> Gio::DBus::Message::create_from_blob ( const guchar *  blob,
gsize  blob_len,
CapabilityFlags  capabilities = CAPABILITY_FLAGS_NONE 
) [static]

Creates a new DBusMessage from the data stored at blob.

The byte order that the message was in can be retrieved using g_dbus_message_get_byte_order().

Since glibmm 2.26:
Parameters:
blobA blob represent a binary D-Bus message.
blob_lenThe length of blob.
capabilitiesA DBusCapabilityFlags describing what protocol features are supported.
Returns:
A new DBusMessage or 0 if error is set. Free with Glib::object_unref().
static Glib::RefPtr<Message> Gio::DBus::Message::create_method_call ( const Glib::ustring name,
const Glib::ustring path,
const Glib::ustring interface,
const Glib::ustring method 
) [static]

Creates a new DBusMessage for a method call.

Since glibmm 2.26:
Parameters:
nameA valid D-Bus name or 0.
pathA valid object path.
interfaceA valid D-Bus interface name or 0.
methodA valid method name.
Returns:
A DBusMessage. Free with Glib::object_unref().
static Glib::RefPtr<Message> Gio::DBus::Message::create_method_error_literal ( const Glib::RefPtr< const Message >&  method_call_message,
const Glib::ustring error_name,
const Glib::ustring error_message 
) [static]

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

Since glibmm 2.26:
Parameters:
error_nameA valid D-Bus error name.
error_messageThe D-Bus error message.
Returns:
A DBusMessage. Free with Glib::object_unref().
static Glib::RefPtr<Message> Gio::DBus::Message::create_method_reply ( const Glib::RefPtr< Message >&  method_call_message) [static]

Creates a new DBusMessage that is a reply to method_call_message.

Since glibmm 2.26:
Returns:
DBusMessage. Free with Glib::object_unref().
static Glib::RefPtr<Message> Gio::DBus::Message::create_signal ( const Glib::ustring path,
const Glib::ustring interface,
const Glib::ustring signal 
) [static]

Creates a new DBusMessage for a signal emission.

Since glibmm 2.26:
Parameters:
pathA valid object path.
interfaceA valid D-Bus interface name.
signalA valid signal name.
Returns:
A DBusMessage. Free with Glib::object_unref().

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

Since glibmm 2.26:
Returns:
The string item or 0 if the first item in the body of message is not a string.

Gets the body of a message.

The body is returned in value.

Parameters:
valueLocation in which to store the header.

Gets the byte order of message.

Returns:
The byte order.

Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.

Since glibmm 2.26:
Returns:
The value.

Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.

Since glibmm 2.26:
Returns:
The value.

Gets the flags for message.

Since glibmm 2.26:
Returns:
Flags that are set (typically values from the DBusMessageFlags enumeration bitwise ORed together).
void Gio::DBus::Message::get_header ( Glib::VariantBase value,
MessageHeaderField  header_field 
) const

Gets a header field on the message.

The header is returned in value.

Parameters:
valueLocation in which to store the header.
header_fieldThe header field type.

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

Since glibmm 2.26:
Returns:
An array of header fields terminated by DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a #guchar. Free with Glib::free().

Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.

Since glibmm 2.26:
Returns:
The value.

Checks whether message is locked.

To monitor changes to this value, conncet to the Object::signal_notify() signal to listen for changes on the DBusMessage::property_locked() property.

Since glibmm 2.26:
Returns:
true if message is locked, false otherwise.

Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.

Since glibmm 2.26:
Returns:
The value.

Gets the type of message.

Since glibmm 2.26:
Returns:
A 8-bit unsigned integer (typically a value from the DBusMessageType enumeration).

Gets the UNIX file descriptors associated with message, if any.

This method is only available on UNIX.

Since glibmm 2.26:
Returns:
A UnixFDList or 0 if no file descriptors are associated. Do not free, this object is owned by message. Gets the UNIX file descriptors associated with message, if any.

This method is only available on UNIX.

Since glibmm 2.26:
Returns:
A UnixFDList or 0 if no file descriptors are associated. Do not free, this object is owned by message. Sets the UNIX file descriptors associated with message. As a side-effect the 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 0).

This method is only available on UNIX.

Since glibmm 2.26:
Parameters:
fd_listA UnixFDList or 0. Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.
Since glibmm 2.26:
Returns:
The value.

Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_PATH header field.

Since glibmm 2.26:
Returns:
The value.

Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.

Since glibmm 2.26:
Returns:
The value.

Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_SENDER header field.

Since glibmm 2.26:
Returns:
The value.
guint32 Gio::DBus::Message::get_serial ( ) const

Gets the serial for message.

Since glibmm 2.26:
Returns:
A #guint32.

Convenience getter for the DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.

Since glibmm 2.26:
Returns:
The value.
GDBusMessage* Gio::DBus::Message::gobj ( ) [inline]

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

const GDBusMessage* Gio::DBus::Message::gobj ( ) const [inline]

Provides access to the underlying C GObject.

Reimplemented from Glib::ObjectBase.

GDBusMessage* Gio::DBus::Message::gobj_copy ( )

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

If message is locked, does nothing.

Otherwise locks the message.

Since glibmm 2.26:

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:

Type: method-call 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

Type: method-return 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

Since glibmm 2.26:
Parameters:
indentIndentation level.
Returns:
A string that should be freed with Glib::free().

Whether the message is locked.

You rarely need to use properties because there are get_ and set_ methods for almost all of them.

Returns:
A PropertyProxy that allows you to get or set the property of the value, or receive notification when the value of the property changes.

Sets the body message.

As a side-effect the DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the type string of body (or cleared if body is 0).

If body is floating, message assumes ownership of body.

Since glibmm 2.26:
Parameters:
bodyEither 0 or a Variant that is a tuple.

Sets the byte order of message.

Parameters:
byte_orderThe byte order.

Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.

Since glibmm 2.26:
Parameters:
valueThe value to set.

Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.

Since glibmm 2.26:
Parameters:
valueThe value to set.

Sets the flags to set on message.

Since glibmm 2.26:
Parameters:
flagsFlags for message that are set (typically values from the DBusMessageFlags enumeration bitwise ORed together).
void Gio::DBus::Message::set_header ( MessageHeaderField  header_field,
const Glib::VariantBase value 
)

Sets a header field on message.

If value is floating, message assumes ownership of value.

Since glibmm 2.26:
Parameters:
header_fieldA 8-bit unsigned integer (typically a value from the DBusMessageHeaderField enumeration).
valueA Variant to set the header field or 0 to clear the header field.

Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.

Since glibmm 2.26:
Parameters:
valueThe value to set.

Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.

Since glibmm 2.26:
Parameters:
valueThe value to set.

Sets message to be of type.

Since glibmm 2.26:
Parameters:
typeA 8-bit unsigned integer (typically a value from the DBusMessageType enumeration).
void Gio::DBus::Message::set_num_unix_fds ( guint32  value)

Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.

Since glibmm 2.26:
Parameters:
valueThe value to set.

Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_PATH header field.

Since glibmm 2.26:
Parameters:
valueThe value to set.
void Gio::DBus::Message::set_reply_serial ( guint32  value)

Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.

Since glibmm 2.26:
Parameters:
valueThe value to set.

Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_SENDER header field.

Since glibmm 2.26:
Parameters:
valueThe value to set.
void Gio::DBus::Message::set_serial ( guint32  serial)

Sets the serial for message.

Since glibmm 2.26:
Parameters:
serialA #guint32.

Convenience setter for the DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.

Since glibmm 2.26:
Parameters:
valueThe value to set.
guchar* Gio::DBus::Message::to_blob ( gsize &  out_size,
CapabilityFlags  capabilities = CAPABILITY_FLAGS_NONE 
)

Serializes message to a blob.

The byte order returned by g_dbus_message_get_byte_order() will be used.

Since glibmm 2.26:
Parameters:
out_sizeReturn location for size of generated blob.
capabilitiesA DBusCapabilityFlags describing what protocol features are supported.
Returns:
A pointer to a valid binary D-Bus message of out_size bytes generated by message or 0 if error is set. Free with Glib::free().

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

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

Since glibmm 2.26:
Returns:
true if error was set, false otherwise.

Friends And Related Function Documentation

Glib::RefPtr< Gio::DBus::Message > wrap ( GDBusMessage *  object,
bool  take_copy = false 
) [related]

A Glib::wrap() method for this object.

Parameters:
objectThe C instance.
take_copyFalse if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns:
A C++ instance that wraps this C instance.