manpagez: man pages & more
html files: gio
Home | html | info | man

GDBusMessage

GDBusMessage — D-Bus Message

Functions

GDBusMessage * g_dbus_message_new ()
GDBusMessage * g_dbus_message_new_signal ()
GDBusMessage * g_dbus_message_new_method_call ()
GDBusMessage * g_dbus_message_new_method_reply ()
GDBusMessage * g_dbus_message_new_method_error ()
GDBusMessage * g_dbus_message_new_method_error_valist ()
GDBusMessage * g_dbus_message_new_method_error_literal ()
gchar * g_dbus_message_print ()
gboolean g_dbus_message_get_locked ()
void g_dbus_message_lock ()
GDBusMessage * g_dbus_message_copy ()
GDBusMessageByteOrder g_dbus_message_get_byte_order ()
void g_dbus_message_set_byte_order ()
GDBusMessageType g_dbus_message_get_message_type ()
void g_dbus_message_set_message_type ()
guint32 g_dbus_message_get_serial ()
void g_dbus_message_set_serial ()
GDBusMessageFlags g_dbus_message_get_flags ()
void g_dbus_message_set_flags ()
GVariant * g_dbus_message_get_body ()
void g_dbus_message_set_body ()
GUnixFDList * g_dbus_message_get_unix_fd_list ()
void g_dbus_message_set_unix_fd_list ()
guint32 g_dbus_message_get_num_unix_fds ()
void g_dbus_message_set_num_unix_fds ()
guchar * g_dbus_message_get_header_fields ()
GVariant * g_dbus_message_get_header ()
void g_dbus_message_set_header ()
const gchar * g_dbus_message_get_destination ()
void g_dbus_message_set_destination ()
const gchar * g_dbus_message_get_error_name ()
void g_dbus_message_set_error_name ()
const gchar * g_dbus_message_get_interface ()
void g_dbus_message_set_interface ()
const gchar * g_dbus_message_get_member ()
void g_dbus_message_set_member ()
const gchar * g_dbus_message_get_path ()
void g_dbus_message_set_path ()
guint32 g_dbus_message_get_reply_serial ()
void g_dbus_message_set_reply_serial ()
const gchar * g_dbus_message_get_sender ()
void g_dbus_message_set_sender ()
const gchar * g_dbus_message_get_signature ()
void g_dbus_message_set_signature ()
const gchar * g_dbus_message_get_arg0 ()
guchar * g_dbus_message_to_blob ()
gssize g_dbus_message_bytes_needed ()
GDBusMessage * g_dbus_message_new_from_blob ()
gboolean g_dbus_message_to_gerror ()

Properties

Object Hierarchy

    GObject
    ╰── GDBusMessage

Includes

#include <gio/gio.h>

Description

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

Functions

g_dbus_message_new ()

GDBusMessage *
g_dbus_message_new (void);

Creates a new empty GDBusMessage.

Returns

A GDBusMessage. Free with g_object_unref().

Since 2.26


g_dbus_message_new_signal ()

GDBusMessage *
g_dbus_message_new_signal (const gchar *path,
                           const gchar *interface_,
                           const gchar *signal);

Creates a new GDBusMessage for a signal emission.

Parameters

path

A valid object path.

 

interface_

A valid D-Bus interface name.

 

signal

A valid signal name.

 

Returns

A GDBusMessage. Free with g_object_unref().

Since 2.26


g_dbus_message_new_method_call ()

GDBusMessage *
g_dbus_message_new_method_call (const gchar *name,
                                const gchar *path,
                                const gchar *interface_,
                                const gchar *method);

Creates a new GDBusMessage for a method call.

Parameters

name

A valid D-Bus name or NULL.

[allow-none]

path

A valid object path.

 

interface_

A valid D-Bus interface name or NULL.

[allow-none]

method

A valid method name.

 

Returns

A GDBusMessage. Free with g_object_unref().

Since 2.26


g_dbus_message_new_method_reply ()

GDBusMessage *
g_dbus_message_new_method_reply (GDBusMessage *method_call_message);

Creates a new GDBusMessage that is a reply to method_call_message .

Parameters

method_call_message

A message of type G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.

 

Returns

GDBusMessage. Free with g_object_unref().

[transfer full]

Since 2.26


g_dbus_message_new_method_error ()

GDBusMessage *
g_dbus_message_new_method_error (GDBusMessage *method_call_message,
                                 const gchar *error_name,
                                 const gchar *error_message_format,
                                 ...);

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

Parameters

method_call_message

A message of type G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.

 

error_name

A valid D-Bus error name.

 

error_message_format

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

 

...

Arguments for error_message_format .

 

Returns

A GDBusMessage. Free with g_object_unref().

[transfer full]

Since 2.26


g_dbus_message_new_method_error_valist ()

GDBusMessage *
g_dbus_message_new_method_error_valist
                               (GDBusMessage *method_call_message,
                                const gchar *error_name,
                                const gchar *error_message_format,
                                va_list var_args);

Like g_dbus_message_new_method_error() but intended for language bindings.

Parameters

method_call_message

A message of type G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.

 

error_name

A valid D-Bus error name.

 

error_message_format

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

 

var_args

Arguments for error_message_format .

 

Returns

A GDBusMessage. Free with g_object_unref().

[transfer full]

Since 2.26


g_dbus_message_new_method_error_literal ()

GDBusMessage *
g_dbus_message_new_method_error_literal
                               (GDBusMessage *method_call_message,
                                const gchar *error_name,
                                const gchar *error_message);

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

Parameters

method_call_message

A message of type G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to.

 

error_name

A valid D-Bus error name.

 

error_message

The D-Bus error message.

 

Returns

A GDBusMessage. Free with g_object_unref().

[transfer full]

Since 2.26


g_dbus_message_print ()

gchar *
g_dbus_message_print (GDBusMessage *message,
                      guint indent);

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:

1
2
3
4
5
6
7
8
9
10
11
12
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

1
2
3
4
5
6
7
8
9
10
11
12
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

Parameters

message

A GDBusMessage.

 

indent

Indentation level.

 

Returns

A string that should be freed with g_free().

Since 2.26


g_dbus_message_get_locked ()

gboolean
g_dbus_message_get_locked (GDBusMessage *message);

Checks whether message is locked. To monitor changes to this value, conncet to the “notify” signal to listen for changes on the “locked” property.

Parameters

message

A GDBusMessage.

 

Returns

TRUE if message is locked, FALSE otherwise.

Since 2.26


g_dbus_message_lock ()

void
g_dbus_message_lock (GDBusMessage *message);

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

Parameters

message

A GDBusMessage.

 

Since 2.26


g_dbus_message_copy ()

GDBusMessage *
g_dbus_message_copy (GDBusMessage *message,
                     GError **error);

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

Parameters

message

A GDBusMessage.

 

error

Return location for error or NULL.

 

Returns

A new GDBusMessage or NULL if error is set. Free with g_object_unref().

[transfer full]

Since 2.26


g_dbus_message_get_byte_order ()

GDBusMessageByteOrder
g_dbus_message_get_byte_order (GDBusMessage *message);

Gets the byte order of message .

Parameters

message

A GDBusMessage.

 

Returns

The byte order.


g_dbus_message_set_byte_order ()

void
g_dbus_message_set_byte_order (GDBusMessage *message,
                               GDBusMessageByteOrder byte_order);

Sets the byte order of message .

Parameters

message

A GDBusMessage.

 

byte_order

The byte order.

 

g_dbus_message_get_message_type ()

GDBusMessageType
g_dbus_message_get_message_type (GDBusMessage *message);

Gets the type of message .

Parameters

message

A GDBusMessage.

 

Returns

A 8-bit unsigned integer (typically a value from the GDBusMessageType enumeration).

Since 2.26


g_dbus_message_set_message_type ()

void
g_dbus_message_set_message_type (GDBusMessage *message,
                                 GDBusMessageType type);

Sets message to be of type .

Parameters

message

A GDBusMessage.

 

type

A 8-bit unsigned integer (typically a value from the GDBusMessageType enumeration).

 

Since 2.26


g_dbus_message_get_serial ()

guint32
g_dbus_message_get_serial (GDBusMessage *message);

Gets the serial for message .

Parameters

message

A GDBusMessage.

 

Returns

A guint32.

Since 2.26


g_dbus_message_set_serial ()

void
g_dbus_message_set_serial (GDBusMessage *message,
                           guint32 serial);

Sets the serial for message .

Parameters

message

A GDBusMessage.

 

serial

A guint32.

 

Since 2.26


g_dbus_message_get_flags ()

GDBusMessageFlags
g_dbus_message_get_flags (GDBusMessage *message);

Gets the flags for message .

Parameters

message

A GDBusMessage.

 

Returns

Flags that are set (typically values from the GDBusMessageFlags enumeration bitwise ORed together).

Since 2.26


g_dbus_message_set_flags ()

void
g_dbus_message_set_flags (GDBusMessage *message,
                          GDBusMessageFlags flags);

Sets the flags to set on message .

Parameters

message

A GDBusMessage.

 

flags

Flags for message that are set (typically values from the GDBusMessageFlags enumeration bitwise ORed together).

 

Since 2.26


g_dbus_message_get_body ()

GVariant *
g_dbus_message_get_body (GDBusMessage *message);

Gets the body of a message.

Parameters

message

A GDBusMessage.

 

Returns

A GVariant or NULL if the body is empty. Do not free, it is owned by message .

[transfer none]

Since 2.26


g_dbus_message_set_body ()

void
g_dbus_message_set_body (GDBusMessage *message,
                         GVariant *body);

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 NULL).

If body is floating, message assumes ownership of body .

Parameters

message

A GDBusMessage.

 

body

Either NULL or a GVariant that is a tuple.

 

Since 2.26


g_dbus_message_get_unix_fd_list ()

GUnixFDList *
g_dbus_message_get_unix_fd_list (GDBusMessage *message);

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

This method is only available on UNIX.

Parameters

message

A GDBusMessage.

 

Returns

A GUnixFDList or NULL if no file descriptors are associated. Do not free, this object is owned by message .

[transfer none]

Since 2.26


g_dbus_message_set_unix_fd_list ()

void
g_dbus_message_set_unix_fd_list (GDBusMessage *message,
                                 GUnixFDList *fd_list);

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 NULL).

This method is only available on UNIX.

Parameters

message

A GDBusMessage.

 

fd_list

A GUnixFDList or NULL.

[allow-none]

Since 2.26


g_dbus_message_get_num_unix_fds ()

guint32
g_dbus_message_get_num_unix_fds (GDBusMessage *message);

Convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.

Parameters

message

A GDBusMessage.

 

Returns

The value.

Since 2.26


g_dbus_message_set_num_unix_fds ()

void
g_dbus_message_set_num_unix_fds (GDBusMessage *message,
                                 guint32 value);

Convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field.

Parameters

message

A GDBusMessage.

 

value

The value to set.

 

Since 2.26


g_dbus_message_get_header_fields ()

guchar *
g_dbus_message_get_header_fields (GDBusMessage *message);

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

Parameters

message

A GDBusMessage.

 

Returns

An array of header fields terminated by G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a guchar. Free with g_free().

[array zero-terminated=1]

Since 2.26


g_dbus_message_get_header ()

GVariant *
g_dbus_message_get_header (GDBusMessage *message,
                           GDBusMessageHeaderField header_field);

Gets a header field on message .

Parameters

message

A GDBusMessage.

 

header_field

A 8-bit unsigned integer (typically a value from the GDBusMessageHeaderField enumeration)

 

Returns

A GVariant with the value if the header was found, NULL otherwise. Do not free, it is owned by message .

Since 2.26


g_dbus_message_set_header ()

void
g_dbus_message_set_header (GDBusMessage *message,
                           GDBusMessageHeaderField header_field,
                           GVariant *value);

Sets a header field on message .

If value is floating, message assumes ownership of value .

Parameters

message

A GDBusMessage.

 

header_field

A 8-bit unsigned integer (typically a value from the GDBusMessageHeaderField enumeration)

 

value

A GVariant to set the header field or NULL to clear the header field.

[allow-none]

Since 2.26


g_dbus_message_get_destination ()

const gchar *
g_dbus_message_get_destination (GDBusMessage *message);

Convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.

Parameters

message

A GDBusMessage.

 

Returns

The value.

Since 2.26


g_dbus_message_set_destination ()

void
g_dbus_message_set_destination (GDBusMessage *message,
                                const gchar *value);

Convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.

Parameters

message

A GDBusMessage.

 

value

The value to set.

 

Since 2.26


g_dbus_message_get_error_name ()

const gchar *
g_dbus_message_get_error_name (GDBusMessage *message);

Convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.

Parameters

message

A GDBusMessage.

 

Returns

The value.

Since 2.26


g_dbus_message_set_error_name ()

void
g_dbus_message_set_error_name (GDBusMessage *message,
                               const gchar *value);

Convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.

Parameters

message

A GDBusMessage.

 

value

The value to set.

 

Since 2.26


g_dbus_message_get_interface ()

const gchar *
g_dbus_message_get_interface (GDBusMessage *message);

Convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.

Parameters

message

A GDBusMessage.

 

Returns

The value.

Since 2.26


g_dbus_message_set_interface ()

void
g_dbus_message_set_interface (GDBusMessage *message,
                              const gchar *value);

Convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.

Parameters

message

A GDBusMessage.

 

value

The value to set.

 

Since 2.26


g_dbus_message_get_member ()

const gchar *
g_dbus_message_get_member (GDBusMessage *message);

Convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.

Parameters

message

A GDBusMessage.

 

Returns

The value.

Since 2.26


g_dbus_message_set_member ()

void
g_dbus_message_set_member (GDBusMessage *message,
                           const gchar *value);

Convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.

Parameters

message

A GDBusMessage.

 

value

The value to set.

 

Since 2.26


g_dbus_message_get_path ()

const gchar *
g_dbus_message_get_path (GDBusMessage *message);

Convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.

Parameters

message

A GDBusMessage.

 

Returns

The value.

Since 2.26


g_dbus_message_set_path ()

void
g_dbus_message_set_path (GDBusMessage *message,
                         const gchar *value);

Convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.

Parameters

message

A GDBusMessage.

 

value

The value to set.

 

Since 2.26


g_dbus_message_get_reply_serial ()

guint32
g_dbus_message_get_reply_serial (GDBusMessage *message);

Convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.

Parameters

message

A GDBusMessage.

 

Returns

The value.

Since 2.26


g_dbus_message_set_reply_serial ()

void
g_dbus_message_set_reply_serial (GDBusMessage *message,
                                 guint32 value);

Convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.

Parameters

message

A GDBusMessage.

 

value

The value to set.

 

Since 2.26


g_dbus_message_get_sender ()

const gchar *
g_dbus_message_get_sender (GDBusMessage *message);

Convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.

Parameters

message

A GDBusMessage.

 

Returns

The value.

Since 2.26


g_dbus_message_set_sender ()

void
g_dbus_message_set_sender (GDBusMessage *message,
                           const gchar *value);

Convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.

Parameters

message

A GDBusMessage.

 

value

The value to set.

 

Since 2.26


g_dbus_message_get_signature ()

const gchar *
g_dbus_message_get_signature (GDBusMessage *message);

Convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.

Parameters

message

A GDBusMessage.

 

Returns

The value.

Since 2.26


g_dbus_message_set_signature ()

void
g_dbus_message_set_signature (GDBusMessage *message,
                              const gchar *value);

Convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.

Parameters

message

A GDBusMessage.

 

value

The value to set.

 

Since 2.26


g_dbus_message_get_arg0 ()

const gchar *
g_dbus_message_get_arg0 (GDBusMessage *message);

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

Parameters

message

A GDBusMessage.

 

Returns

The string item or NULL if the first item in the body of message is not a string.

Since 2.26


g_dbus_message_to_blob ()

guchar *
g_dbus_message_to_blob (GDBusMessage *message,
                        gsize *out_size,
                        GDBusCapabilityFlags capabilities,
                        GError **error);

Serializes message to a blob. The byte order returned by g_dbus_message_get_byte_order() will be used.

Parameters

message

A GDBusMessage.

 

out_size

Return location for size of generated blob.

 

capabilities

A GDBusCapabilityFlags describing what protocol features are supported.

 

error

Return location for error.

 

Returns

A pointer to a valid binary D-Bus message of out_size bytes generated by message or NULL if error is set. Free with g_free().

[array length=out_size][transfer full]

Since 2.26


g_dbus_message_bytes_needed ()

gssize
g_dbus_message_bytes_needed (guchar *blob,
                             gsize blob_len,
                             GError **error);

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

Parameters

blob

A blob represent a binary D-Bus message.

[array length=blob_len][element-type guint8]

blob_len

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

 

error

Return location for error or NULL.

 

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

Since 2.26


g_dbus_message_new_from_blob ()

GDBusMessage *
g_dbus_message_new_from_blob (guchar *blob,
                              gsize blob_len,
                              GDBusCapabilityFlags capabilities,
                              GError **error);

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

Parameters

blob

A blob represent a binary D-Bus message.

[array length=blob_len][element-type guint8]

blob_len

The length of blob .

 

capabilities

A GDBusCapabilityFlags describing what protocol features are supported.

 

error

Return location for error or NULL.

 

Returns

A new GDBusMessage or NULL if error is set. Free with g_object_unref().

Since 2.26


g_dbus_message_to_gerror ()

gboolean
g_dbus_message_to_gerror (GDBusMessage *message,
                          GError **error);

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.

Parameters

message

A GDBusMessage.

 

error

The GError to set.

 

Returns

TRUE if error was set, FALSE otherwise.

Since 2.26

Types and Values

GDBusMessage

typedef struct _GDBusMessage GDBusMessage;

The GDBusMessage structure contains only private data and should only be accessed using the provided API.

Since 2.26


enum GDBusMessageType

Message types used in GDBusMessage.

Members

G_DBUS_MESSAGE_TYPE_INVALID

Message is of invalid type.

 

G_DBUS_MESSAGE_TYPE_METHOD_CALL

Method call.

 

G_DBUS_MESSAGE_TYPE_METHOD_RETURN

Method reply.

 

G_DBUS_MESSAGE_TYPE_ERROR

Error reply.

 

G_DBUS_MESSAGE_TYPE_SIGNAL

Signal emission.

 

Since 2.26


enum GDBusMessageFlags

Message flags used in GDBusMessage.

Members

G_DBUS_MESSAGE_FLAGS_NONE

No flags set.

 

G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED

A reply is not expected.

 

G_DBUS_MESSAGE_FLAGS_NO_AUTO_START

The bus must not launch an owner for the destination name in response to this message.

 

Since 2.26


enum GDBusMessageHeaderField

Header fields used in GDBusMessage.

Members

G_DBUS_MESSAGE_HEADER_FIELD_INVALID

Not a valid header field.

 

G_DBUS_MESSAGE_HEADER_FIELD_PATH

The object path.

 

G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE

The interface name.

 

G_DBUS_MESSAGE_HEADER_FIELD_MEMBER

The method or signal name.

 

G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME

The name of the error that occurred.

 

G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL

The serial number the message is a reply to.

 

G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION

The name the message is intended for.

 

G_DBUS_MESSAGE_HEADER_FIELD_SENDER

Unique name of the sender of the message (filled in by the bus).

 

G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE

The signature of the message body.

 

G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS

The number of UNIX file descriptors that accompany the message.

 

Since 2.26


enum GDBusMessageByteOrder

Enumeration used to describe the byte order of a D-Bus message.

Members

G_DBUS_MESSAGE_BYTE_ORDER_BIG_ENDIAN

The byte order is big endian.

 

G_DBUS_MESSAGE_BYTE_ORDER_LITTLE_ENDIAN

The byte order is little endian.

 

Since 2.26

Property Details

The “locked” property

  “locked”                   gboolean

Whether the message is locked.

Flags: Read

Default value: FALSE

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.