DBusMessage
[D-BUS low-level public API]

Message to be sent or received over a DBusConnection. More...

Defines

#define MAX_MESSAGE_SIZE_TO_CACHE   10 * _DBUS_ONE_KILOBYTE
 Avoid caching huge messages.
#define MAX_MESSAGE_CACHE_SIZE   5
 Avoid caching too many messages.

Typedefs

typedef DBusMessage DBusMessage
 Opaque data type representing a message received from or to be sent to another application.

Functions

dbus_uint32_t dbus_message_get_serial (DBusMessage *message)
 Returns the serial of a message or 0 if none has been specified.
dbus_bool_t dbus_message_set_reply_serial (DBusMessage *message, dbus_uint32_t reply_serial)
 Sets the reply serial of a message (the client serial of the message this is a reply to).
dbus_uint32_t dbus_message_get_reply_serial (DBusMessage *message)
 Returns the serial that the message is a reply to or 0 if none.
DBusMessagedbus_message_new (int message_type)
 Constructs a new message of the given message type.
DBusMessagedbus_message_new_method_call (const char *destination, const char *path, const char *interface, const char *method)
 Constructs a new message to invoke a method on a remote object.
DBusMessagedbus_message_new_method_return (DBusMessage *method_call)
 Constructs a message that is a reply to a method call.
DBusMessagedbus_message_new_signal (const char *path, const char *interface, const char *name)
 Constructs a new message representing a signal emission.
DBusMessagedbus_message_new_error (DBusMessage *reply_to, const char *error_name, const char *error_message)
 Creates a new message that is an error reply to a certain message.
DBusMessagedbus_message_new_error_printf (DBusMessage *reply_to, const char *error_name, const char *error_format,...)
 Creates a new message that is an error reply to a certain message.
DBusMessagedbus_message_copy (const DBusMessage *message)
 Creates a new message that is an exact replica of the message specified, except that its refcount is set to 1, its message serial is reset to 0, and if the original message was "locked" (in the outgoing message queue and thus not modifiable) the new message will not be locked.
DBusMessagedbus_message_ref (DBusMessage *message)
 Increments the reference count of a DBusMessage.
void dbus_message_unref (DBusMessage *message)
 Decrements the reference count of a DBusMessage.
int dbus_message_get_type (DBusMessage *message)
 Gets the type of a message.
dbus_bool_t dbus_message_append_args (DBusMessage *message, int first_arg_type,...)
 Appends fields to a message given a variable argument list.
dbus_bool_t dbus_message_append_args_valist (DBusMessage *message, int first_arg_type, va_list var_args)
 This function takes a va_list for use by language bindings.
dbus_bool_t dbus_message_get_args (DBusMessage *message, DBusError *error, int first_arg_type,...)
 Gets arguments from a message given a variable argument list.
dbus_bool_t dbus_message_get_args_valist (DBusMessage *message, DBusError *error, int first_arg_type, va_list var_args)
 This function takes a va_list for use by language bindings.
dbus_bool_t dbus_message_iter_init (DBusMessage *message, DBusMessageIter *iter)
 Initializes a DBusMessageIter for reading the arguments of the message passed in.
dbus_bool_t dbus_message_iter_has_next (DBusMessageIter *iter)
 Checks if an iterator has any more fields.
dbus_bool_t dbus_message_iter_next (DBusMessageIter *iter)
 Moves the iterator to the next field, if any.
int dbus_message_iter_get_arg_type (DBusMessageIter *iter)
 Returns the argument type of the argument that the message iterator points to.
int dbus_message_iter_get_element_type (DBusMessageIter *iter)
 Returns the element type of the array that the message iterator points to.
void dbus_message_iter_recurse (DBusMessageIter *iter, DBusMessageIter *sub)
 Recurses into a container value when reading values from a message, initializing a sub-iterator to use for traversing the child values of the container.
char * dbus_message_iter_get_signature (DBusMessageIter *iter)
 Returns the current signature of a message iterator.
void dbus_message_iter_get_basic (DBusMessageIter *iter, void *value)
 Reads a basic-typed value from the message iterator.
int dbus_message_iter_get_array_len (DBusMessageIter *iter)
 Returns the number of elements in the array;.
void dbus_message_iter_get_fixed_array (DBusMessageIter *iter, void *value, int *n_elements)
 Reads a block of fixed-length values from the message iterator.
dbus_bool_t _dbus_message_iter_get_args_valist (DBusMessageIter *iter, DBusError *error, int first_arg_type, va_list var_args)
 This function takes a va_list for use by language bindings and is otherwise the same as dbus_message_iter_get_args().
void dbus_message_iter_init_append (DBusMessage *message, DBusMessageIter *iter)
 Initializes a DBusMessageIter for appending arguments to the end of a message.
dbus_bool_t dbus_message_iter_append_basic (DBusMessageIter *iter, int type, const void *value)
 Appends a basic-typed value to the message.
dbus_bool_t dbus_message_iter_append_fixed_array (DBusMessageIter *iter, int element_type, const void *value, int n_elements)
 Appends a block of fixed-length values to an array.
dbus_bool_t dbus_message_iter_open_container (DBusMessageIter *iter, int type, const char *contained_signature, DBusMessageIter *sub)
 Appends a container-typed value to the message; you are required to append the contents of the container using the returned sub-iterator, and then call dbus_message_iter_close_container().
dbus_bool_t dbus_message_iter_close_container (DBusMessageIter *iter, DBusMessageIter *sub)
 Closes a container-typed value appended to the message; may write out more information to the message known only after the entire container is written, and may free resources created by dbus_message_iter_open_container().
void dbus_message_set_no_reply (DBusMessage *message, dbus_bool_t no_reply)
 Sets a flag indicating that the message does not want a reply; if this flag is set, the other end of the connection may (but is not required to) optimize by not sending method return or error replies.
dbus_bool_t dbus_message_get_no_reply (DBusMessage *message)
 Returns TRUE if the message does not expect a reply.
void dbus_message_set_auto_start (DBusMessage *message, dbus_bool_t auto_start)
 Sets a flag indicating that an owner for the destination name will be automatically started before the message is delivered.
dbus_bool_t dbus_message_get_auto_start (DBusMessage *message)
 Returns TRUE if the message will cause an owner for destination name to be auto-started.
dbus_bool_t dbus_message_set_path (DBusMessage *message, const char *object_path)
 Sets the object path this message is being sent to (for DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
const char * dbus_message_get_path (DBusMessage *message)
 Gets the object path this message is being sent to (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
dbus_bool_t dbus_message_has_path (DBusMessage *message, const char *path)
 Checks if the message has a path.
dbus_bool_t dbus_message_get_path_decomposed (DBusMessage *message, char ***path)
 Gets the object path this message is being sent to (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed format (one array element per path component).
dbus_bool_t dbus_message_set_interface (DBusMessage *message, const char *interface)
 Sets the interface this message is being sent to (for DBUS_MESSAGE_TYPE_METHOD_CALL) or the interface a signal is being emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
const char * dbus_message_get_interface (DBusMessage *message)
 Gets the interface this message is being sent to (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
dbus_bool_t dbus_message_has_interface (DBusMessage *message, const char *interface)
 Checks if the message has an interface.
dbus_bool_t dbus_message_set_member (DBusMessage *message, const char *member)
 Sets the interface member being invoked (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted (DBUS_MESSAGE_TYPE_SIGNAL).
const char * dbus_message_get_member (DBusMessage *message)
 Gets the interface member being invoked (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted (DBUS_MESSAGE_TYPE_SIGNAL).
dbus_bool_t dbus_message_has_member (DBusMessage *message, const char *member)
 Checks if the message has an interface member.
dbus_bool_t dbus_message_set_error_name (DBusMessage *message, const char *error_name)
 Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
const char * dbus_message_get_error_name (DBusMessage *message)
 Gets the error name (DBUS_MESSAGE_TYPE_ERROR only) or NULL if none.
dbus_bool_t dbus_message_set_destination (DBusMessage *message, const char *destination)
 Sets the message's destination.
const char * dbus_message_get_destination (DBusMessage *message)
 Gets the destination of a message or NULL if there is none set.
dbus_bool_t dbus_message_set_sender (DBusMessage *message, const char *sender)
 Sets the message sender.
const char * dbus_message_get_sender (DBusMessage *message)
 Gets the unique name of the connection which originated this message, or NULL if unknown or inapplicable.
const char * dbus_message_get_signature (DBusMessage *message)
 Gets the type signature of the message, i.e.
dbus_bool_t dbus_message_is_method_call (DBusMessage *message, const char *interface, const char *method)
 Checks whether the message is a method call with the given interface and member fields.
dbus_bool_t dbus_message_is_signal (DBusMessage *message, const char *interface, const char *signal_name)
 Checks whether the message is a signal with the given interface and member fields.
dbus_bool_t dbus_message_is_error (DBusMessage *message, const char *error_name)
 Checks whether the message is an error reply with the given error name.
dbus_bool_t dbus_message_has_destination (DBusMessage *message, const char *name)
 Checks whether the message was sent to the given name.
dbus_bool_t dbus_message_has_sender (DBusMessage *message, const char *name)
 Checks whether the message has the given unique name as its sender.
dbus_bool_t dbus_message_has_signature (DBusMessage *message, const char *signature)
 Checks whether the message has the given signature; see dbus_message_get_signature() for more details on what the signature looks like.
dbus_bool_t dbus_set_error_from_message (DBusError *error, DBusMessage *message)
 Sets a DBusError based on the contents of the given message.

Detailed Description

Message to be sent or received over a DBusConnection.

A DBusMessage is the most basic unit of communication over a DBusConnection. A DBusConnection represents a stream of messages received from a remote application, and a stream of messages sent to a remote application.


Function Documentation

dbus_bool_t _dbus_message_iter_get_args_valist DBusMessageIter iter,
DBusError error,
int  first_arg_type,
va_list  var_args
 

This function takes a va_list for use by language bindings and is otherwise the same as dbus_message_iter_get_args().

dbus_message_get_args() is the place to go for complete documentation.

See also:
dbus_message_get_args
Parameters:
iter the message iter
error error to be filled in
first_arg_type type of the first argument
var_args return location for first argument, followed by list of type/location pairs
Returns:
FALSE if error was set

Definition at line 1761 of file dbus-message.c.

References _dbus_assert, _dbus_strdup(), _dbus_type_reader_get_current_type(), _dbus_type_reader_get_element_type(), _dbus_type_reader_next(), _dbus_type_reader_read_basic(), _dbus_type_reader_read_fixed_multi(), _dbus_type_reader_recurse(), _dbus_type_to_string(), _dbus_warn(), dbus_free_string_array(), dbus_message_iter_get_arg_type(), dbus_new0, dbus_set_error(), dbus_type_is_basic(), dbus_type_is_fixed(), FALSE, NULL, and TRUE.

Referenced by dbus_message_get_args_valist().

dbus_bool_t dbus_message_append_args DBusMessage message,
int  first_arg_type,
  ...
 

Appends fields to a message given a variable argument list.

The variable argument list should contain the type of each argument followed by the value to append. Appendable types are basic types, and arrays of fixed-length basic types. To append variable-length basic types, or any more complex value, you have to use an iterator rather than this function.

To append a basic type, specify its type code followed by the address of the value. For example:

 dbus_int32_t v_INT32 = 42;
 const char *v_STRING = "Hello World";
 DBUS_TYPE_INT32, &v_INT32,
 DBUS_TYPE_STRING, &v_STRING,

To append an array of fixed-length basic types, pass in the DBUS_TYPE_ARRAY typecode, the element typecode, the address of the array pointer, and a 32-bit integer giving the number of elements in the array. So for example:

 const dbus_int32_t array[] = { 1, 2, 3 };
 const dbus_int32_t *v_ARRAY = array;
 DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3

Warning:
in C, given "int array[]", "&array == array" (the comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree). So if you're using an array instead of a pointer you have to create a pointer variable, assign the array to it, then take the address of the pointer variable. For strings it works to write const char *array = "Hello" and then use &array though.
The last argument to this function must be DBUS_TYPE_INVALID, marking the end of the argument list.

String/signature/path arrays should be passed in as "const char*** address_of_array" and "int n_elements"

Todo:
support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
Todo:
If this fails due to lack of memory, the message is hosed and you have to start over building the whole message.
Parameters:
message the message
first_arg_type type of the first argument
... value of first argument, list of additional type-value pairs
Returns:
TRUE on success

Definition at line 1190 of file dbus-message.c.

References dbus_message_append_args_valist(), FALSE, and NULL.

Referenced by _dbus_message_test(), dbus_bus_add_match(), dbus_bus_get_unix_user(), dbus_bus_name_has_owner(), dbus_bus_release_name(), dbus_bus_remove_match(), dbus_bus_request_name(), and dbus_bus_start_service_by_name().

dbus_bool_t dbus_message_append_args_valist DBusMessage message,
int  first_arg_type,
va_list  var_args
 

This function takes a va_list for use by language bindings.

It's otherwise the same as dbus_message_append_args().

Todo:
for now, if this function fails due to OOM it will leave the message half-written and you have to discard the message and start over.
See also:
dbus_message_append_args.
Parameters:
message the message
first_arg_type type of first argument
var_args value of first argument, then list of type/value pairs
Returns:
TRUE on success

Definition at line 1223 of file dbus-message.c.

References _dbus_type_to_string(), _dbus_warn(), dbus_message_iter_append_basic(), dbus_message_iter_append_fixed_array(), dbus_message_iter_close_container(), dbus_message_iter_init_append(), dbus_message_iter_open_container(), dbus_type_is_basic(), dbus_type_is_fixed(), FALSE, NULL, and TRUE.

Referenced by dbus_message_append_args().

DBusMessage* dbus_message_copy const DBusMessage message  ) 
 

Creates a new message that is an exact replica of the message specified, except that its refcount is set to 1, its message serial is reset to 0, and if the original message was "locked" (in the outgoing message queue and thus not modifiable) the new message will not be locked.

Parameters:
message the message.
Returns:
the new message.

Definition at line 1023 of file dbus-message.c.

References _dbus_header_copy(), _dbus_header_free(), _dbus_string_copy(), _dbus_string_free(), _dbus_string_init_preallocated(), body, byte_order, dbus_free(), dbus_new0, FALSE, generation, header, locked, NULL, refcount, and DBusAtomic::value.

Referenced by _dbus_message_test().

dbus_bool_t dbus_message_get_args DBusMessage message,
DBusError error,
int  first_arg_type,
  ...
 

Gets arguments from a message given a variable argument list.

The supported types include those supported by dbus_message_append_args(); that is, basic types and arrays of fixed-length basic types. The arguments are the same as they would be for dbus_message_iter_get_basic() or dbus_message_iter_get_fixed_array().

In addition to those types, arrays of string, object path, and signature are supported; but these are returned as allocated memory and must be freed with dbus_free_string_array(), while the other types are returned as const references. To get a string array pass in "char ***array_location" and "int *n_elements"

The variable argument list should contain the type of the argument followed by a pointer to where the value should be stored. The list is terminated with DBUS_TYPE_INVALID.

The returned values are constant; do not free them. They point into the DBusMessage.

If the requested arguments are not present, or do not have the requested types, then an error will be set.

Todo:
support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
Parameters:
message the message
error error to be filled in on failure
first_arg_type the first argument type
... location for first argument value, then list of type-location pairs
Returns:
FALSE if the error was set

Definition at line 1364 of file dbus-message.c.

References dbus_message_get_args_valist(), FALSE, and NULL.

Referenced by dbus_bus_get_unix_user(), dbus_bus_name_has_owner(), dbus_bus_register(), dbus_bus_release_name(), dbus_bus_request_name(), dbus_bus_start_service_by_name(), and dbus_set_error_from_message().

dbus_bool_t dbus_message_get_args_valist DBusMessage message,
DBusError error,
int  first_arg_type,
va_list  var_args
 

This function takes a va_list for use by language bindings.

It is otherwise the same as dbus_message_get_args().

See also:
dbus_message_get_args
Parameters:
message the message
error error to be filled in
first_arg_type type of the first argument
var_args return location for first argument, followed by list of type/location pairs
Returns:
FALSE if error was set

Definition at line 1394 of file dbus-message.c.

References _dbus_message_iter_get_args_valist(), dbus_message_iter_init(), FALSE, and NULL.

Referenced by dbus_message_get_args().

dbus_bool_t dbus_message_get_auto_start DBusMessage message  ) 
 

Returns TRUE if the message will cause an owner for destination name to be auto-started.

Parameters:
message the message
Returns:
TRUE if the message will use auto-start

Definition at line 2377 of file dbus-message.c.

References _dbus_header_get_flag(), FALSE, header, and NULL.

const char* dbus_message_get_destination DBusMessage message  ) 
 

Gets the destination of a message or NULL if there is none set.

Parameters:
message the message
Returns:
the message destination (should not be freed) or NULL

Definition at line 2747 of file dbus-message.c.

References _dbus_header_get_field_basic(), header, and NULL.

Referenced by dbus_message_has_destination().

const char* dbus_message_get_error_name DBusMessage message  ) 
 

Gets the error name (DBUS_MESSAGE_TYPE_ERROR only) or NULL if none.

Parameters:
message the message
Returns:
the error name (should not be freed) or NULL

Definition at line 2700 of file dbus-message.c.

References _dbus_header_get_field_basic(), header, and NULL.

Referenced by dbus_message_is_error(), and dbus_set_error_from_message().

const char* dbus_message_get_interface DBusMessage message  ) 
 

Gets the interface this message is being sent to (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).

The interface name is fully-qualified (namespaced). Returns NULL if none.

Parameters:
message the message
Returns:
the message interface (should not be freed) or NULL

Definition at line 2541 of file dbus-message.c.

References _dbus_header_get_field_basic(), header, and NULL.

Referenced by _dbus_connection_message_sent(), _dbus_connection_queue_received_message_link(), _dbus_message_test(), dbus_connection_dispatch(), dbus_connection_send_preallocated(), and dbus_message_has_interface().

const char* dbus_message_get_member DBusMessage message  ) 
 

Gets the interface member being invoked (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted (DBUS_MESSAGE_TYPE_SIGNAL).

Returns NULL if none.

Parameters:
message the message
Returns:
the member name (should not be freed) or NULL

Definition at line 2622 of file dbus-message.c.

References _dbus_header_get_field_basic(), header, and NULL.

Referenced by _dbus_connection_message_sent(), _dbus_connection_queue_received_message_link(), _dbus_message_test(), dbus_connection_dispatch(), dbus_connection_send_preallocated(), and dbus_message_has_member().

dbus_bool_t dbus_message_get_no_reply DBusMessage message  ) 
 

Returns TRUE if the message does not expect a reply.

Parameters:
message the message
Returns:
TRUE if the message sender isn't waiting for a reply

Definition at line 2339 of file dbus-message.c.

References _dbus_header_get_flag(), FALSE, header, and NULL.

Referenced by _dbus_message_test().

const char* dbus_message_get_path DBusMessage message  ) 
 

Gets the object path this message is being sent to (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).

Returns NULL if none.

Parameters:
message the message
Returns:
the path (should not be freed) or NULL

Definition at line 2420 of file dbus-message.c.

References _dbus_header_get_field_basic(), header, and NULL.

Referenced by _dbus_connection_message_sent(), _dbus_connection_queue_received_message_link(), _dbus_message_test(), dbus_message_get_path_decomposed(), and dbus_message_has_path().

dbus_bool_t dbus_message_get_path_decomposed DBusMessage message,
char ***  path
 

Gets the object path this message is being sent to (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed format (one array element per path component).

Free the returned array with dbus_free_string_array().

An empty but non-NULL path array means the path "/". So the path "/foo/bar" becomes { "foo", "bar", NULL } and the path "/" becomes { NULL }.

Todo:
this could be optimized by using the len from the message instead of calling strlen() again
Parameters:
message the message
path place to store allocated array of path components; NULL set here if no path field exists
Returns:
FALSE if no memory to allocate the array

Definition at line 2484 of file dbus-message.c.

References _dbus_decompose_path(), dbus_message_get_path(), FALSE, NULL, and TRUE.

Referenced by _dbus_object_tree_dispatch_and_unlock().

dbus_uint32_t dbus_message_get_reply_serial DBusMessage message  ) 
 

Returns the serial that the message is a reply to or 0 if none.

Parameters:
message the message
Returns:
the reply serial

Definition at line 420 of file dbus-message.c.

References _dbus_header_get_field_basic(), header, and NULL.

Referenced by _dbus_connection_queue_received_message_link(), _dbus_message_test(), _dbus_pending_call_complete_and_unlock(), and dbus_connection_dispatch().

const char* dbus_message_get_sender DBusMessage message  ) 
 

Gets the unique name of the connection which originated this message, or NULL if unknown or inapplicable.

The sender is filled in by the message bus.

Parameters:
message the message
Returns:
the unique name of the sender or NULL

Definition at line 2793 of file dbus-message.c.

References _dbus_header_get_field_basic(), header, and NULL.

Referenced by dbus_g_method_get_sender(), dbus_message_has_sender(), dbus_message_new_error(), and dbus_message_new_method_return().

dbus_uint32_t dbus_message_get_serial DBusMessage message  ) 
 

Returns the serial of a message or 0 if none has been specified.

The message's serial number is provided by the application sending the message and is used to identify replies to this message. All messages received on a connection will have a serial, but messages you haven't sent yet may return 0.

Parameters:
message the message
Returns:
the client serial

Definition at line 384 of file dbus-message.c.

References _dbus_header_get_serial(), header, and NULL.

Referenced by _dbus_message_set_serial(), _dbus_message_test(), dbus_connection_send_with_reply(), dbus_message_new_error(), and dbus_message_new_method_return().

const char* dbus_message_get_signature DBusMessage message  ) 
 

Gets the type signature of the message, i.e.

the arguments in the message payload. The signature includes only "in" arguments for DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from what you might expect (it does not include the signature of the entire C++-style method).

The signature is a string made up of type codes such as DBUS_TYPE_INT32. The string is terminated with nul (nul is also the value of DBUS_TYPE_INVALID).

Parameters:
message the message
Returns:
the type signature

Definition at line 2823 of file dbus-message.c.

References header, and NULL.

Referenced by _dbus_connection_message_sent(), _dbus_connection_queue_received_message_link(), _dbus_message_lock(), _dbus_message_test(), dbus_connection_dispatch(), and dbus_message_has_signature().

int dbus_message_get_type DBusMessage message  ) 
 

Gets the type of a message.

Types include DBUS_MESSAGE_TYPE_METHOD_CALL, DBUS_MESSAGE_TYPE_METHOD_RETURN, DBUS_MESSAGE_TYPE_ERROR, DBUS_MESSAGE_TYPE_SIGNAL, but other types are allowed and all code must silently ignore messages of unknown type. DBUS_MESSAGE_TYPE_INVALID will never be returned, however.

Parameters:
message the message
Returns:
the type of the message

Definition at line 1130 of file dbus-message.c.

References _dbus_header_get_message_type(), header, and NULL.

Referenced by _dbus_connection_message_sent(), _dbus_connection_queue_received_message_link(), _dbus_pending_call_complete_and_unlock(), dbus_connection_dispatch(), dbus_connection_send_preallocated(), dbus_message_is_error(), and dbus_set_error_from_message().

dbus_bool_t dbus_message_has_destination DBusMessage message,
const char *  name
 

Checks whether the message was sent to the given name.

If the message has no destination specified or has a different destination, returns FALSE.

Parameters:
message the message
name the name to check (must not be NULL)
Returns:
TRUE if the message has the given destination name

Definition at line 2972 of file dbus-message.c.

References dbus_message_get_destination(), FALSE, NULL, and TRUE.

Referenced by _dbus_message_test().

dbus_bool_t dbus_message_has_interface DBusMessage message,
const char *  interface
 

Checks if the message has an interface.

Parameters:
message the message
interface the interface name
Returns:
TRUE if there is a interface field in the header

Definition at line 2563 of file dbus-message.c.

References dbus_message_get_interface(), FALSE, NULL, and TRUE.

dbus_bool_t dbus_message_has_member DBusMessage message,
const char *  member
 

Checks if the message has an interface member.

Parameters:
message the message
member the member name
Returns:
TRUE if there is a member field in the header

Definition at line 2644 of file dbus-message.c.

References dbus_message_get_member(), FALSE, NULL, and TRUE.

dbus_bool_t dbus_message_has_path DBusMessage message,
const char *  path
 

Checks if the message has a path.

Parameters:
message the message
path the path name
Returns:
TRUE if there is a path field in the header

Definition at line 2442 of file dbus-message.c.

References dbus_message_get_path(), FALSE, NULL, and TRUE.

dbus_bool_t dbus_message_has_sender DBusMessage message,
const char *  name
 

Checks whether the message has the given unique name as its sender.

If the message has no sender specified or has a different sender, returns FALSE. Note that a peer application will always have the unique name of the connection as the sender. So you can't use this function to see whether a sender owned a well-known name.

Messages from the bus itself will have DBUS_SERVICE_DBUS as the sender.

Parameters:
message the message
name the name to check (must not be NULL)
Returns:
TRUE if the message has the given sender

Definition at line 3007 of file dbus-message.c.

References dbus_message_get_sender(), FALSE, NULL, and TRUE.

Referenced by _dbus_message_test().

dbus_bool_t dbus_message_has_signature DBusMessage message,
const char *  signature
 

Checks whether the message has the given signature; see dbus_message_get_signature() for more details on what the signature looks like.

Parameters:
message the message
signature typecode array
Returns:
TRUE if message has the given signature

Definition at line 3036 of file dbus-message.c.

References dbus_message_get_signature(), FALSE, NULL, and TRUE.

Referenced by _dbus_message_test().

dbus_bool_t dbus_message_is_error DBusMessage message,
const char *  error_name
 

Checks whether the message is an error reply with the given error name.

If the message is not DBUS_MESSAGE_TYPE_ERROR, or has a different name, returns FALSE.

Parameters:
message the message
error_name the name to check (must not be NULL)
Returns:
TRUE if the message is the specified error

Definition at line 2939 of file dbus-message.c.

References dbus_message_get_error_name(), dbus_message_get_type(), FALSE, NULL, and TRUE.

dbus_bool_t dbus_message_is_method_call DBusMessage message,
const char *  interface,
const char *  method
 

Checks whether the message is a method call with the given interface and member fields.

If the message is not DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or member field, returns FALSE. If the interface field is missing, then it will be assumed equal to the provided interface. The D-BUS protocol allows method callers to leave out the interface name.

Parameters:
message the message
interface the name to check (must not be NULL)
method the name to check (must not be NULL)
Returns:
TRUE if the message is the specified method call

Definition at line 2882 of file dbus-message.c.

References FALSE, and NULL.

Referenced by _dbus_message_test().

dbus_bool_t dbus_message_is_signal DBusMessage message,
const char *  interface,
const char *  signal_name
 

Checks whether the message is a signal with the given interface and member fields.

If the message is not DBUS_MESSAGE_TYPE_SIGNAL, or has a different interface or member field, returns FALSE. If the interface field in the message is missing, it is assumed to match any interface you pass in to this function.

Parameters:
message the message
interface the name to check (must not be NULL)
signal_name the name to check (must not be NULL)
Returns:
TRUE if the message is the specified signal

Definition at line 2912 of file dbus-message.c.

References FALSE, and NULL.

Referenced by dbus_connection_dispatch().

dbus_bool_t dbus_message_iter_append_basic DBusMessageIter iter,
int  type,
const void *  value
 

Appends a basic-typed value to the message.

The basic types are the non-container types such as integer and string.

The "value" argument should be the address of a basic-typed value. So for string, const char**. For integer, dbus_int32_t*.

Todo:
If this fails due to lack of memory, the message is hosed and you have to start over building the whole message.
Parameters:
iter the append iterator
type the type of the value
value the address of the value
Returns:
FALSE if not enough memory

Definition at line 2117 of file dbus-message.c.

References _dbus_type_writer_write_basic(), dbus_type_is_basic(), FALSE, and NULL.

Referenced by dbus_message_append_args_valist(), and dbus_message_new_error().

dbus_bool_t dbus_message_iter_append_fixed_array DBusMessageIter iter,
int  element_type,
const void *  value,
int  n_elements
 

Appends a block of fixed-length values to an array.

The fixed-length types are all basic types that are not string-like. So int32, double, bool, etc. You must call dbus_message_iter_open_container() to open an array of values before calling this function. You may call this function multiple times (and intermixed with calls to dbus_message_iter_append_basic()) for the same array.

The "value" argument should be the address of the array. So for integer, "dbus_int32_t**" is expected for example.

Warning:
in C, given "int array[]", "&array == array" (the comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree). So if you're using an array instead of a pointer you have to create a pointer variable, assign the array to it, then take the address of the pointer variable.
 const dbus_int32_t array[] = { 1, 2, 3 };
 const dbus_int32_t *v_ARRAY = array;
 if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
   fprintf (stderr, "No memory!\n");
For strings it works to write const char *array = "Hello" and then use &array though.
Todo:
If this fails due to lack of memory, the message is hosed and you have to start over building the whole message.
Parameters:
iter the append iterator
element_type the type of the array elements
value the address of the array
n_elements the number of elements to append
Returns:
FALSE if not enough memory

Definition at line 2176 of file dbus-message.c.

References _dbus_type_get_alignment(), _dbus_type_writer_write_fixed_multi(), dbus_type_is_fixed(), FALSE, and NULL.

Referenced by dbus_message_append_args_valist().

dbus_bool_t dbus_message_iter_close_container DBusMessageIter iter,
DBusMessageIter sub
 

Closes a container-typed value appended to the message; may write out more information to the message known only after the entire container is written, and may free resources created by dbus_message_iter_open_container().

Todo:
If this fails due to lack of memory, the message is hosed and you have to start over building the whole message.
Parameters:
iter the append iterator
sub sub-iterator to close
Returns:
FALSE if not enough memory

Definition at line 2287 of file dbus-message.c.

References _dbus_type_writer_unrecurse(), and FALSE.

Referenced by dbus_message_append_args_valist().

int dbus_message_iter_get_arg_type DBusMessageIter iter  ) 
 

Returns the argument type of the argument that the message iterator points to.

If the iterator is at the end of the message, returns DBUS_TYPE_INVALID. You can thus write a loop as follows:

 dbus_message_iter_init (&iter);
 while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
   dbus_message_iter_next (&iter);

Parameters:
iter the message iter
Returns:
the argument type

Definition at line 1557 of file dbus-message.c.

References _dbus_type_reader_get_current_type(), and FALSE.

Referenced by _dbus_message_iter_get_args_valist(), and dbus_message_iter_get_element_type().

int dbus_message_iter_get_array_len DBusMessageIter iter  ) 
 

Returns the number of elements in the array;.

Parameters:
iter the iterator
Returns:
the number of elements in the array

Definition at line 1706 of file dbus-message.c.

References _dbus_type_reader_get_array_length().

void dbus_message_iter_get_basic DBusMessageIter iter,
void *  value
 

Reads a basic-typed value from the message iterator.

Basic types are the non-containers such as integer and string.

The value argument should be the address of a location to store the returned value. So for int32 it should be a "dbus_int32_t*" and for string a "const char**". The returned value is by reference and should not be freed.

All returned values are guaranteed to fit in 8 bytes. So you can write code like this:

 #ifdef DBUS_HAVE_INT64
 dbus_uint64_t value;
 int type;
 dbus_message_iter_get_basic (&read_iter, &value);
 type = dbus_message_iter_get_arg_type (&read_iter);
 dbus_message_iter_append_basic (&write_iter, type, &value);
 #endif

To avoid the DBUS_HAVE_INT64 conditional, create a struct or something that occupies at least 8 bytes, e.g. you could use a struct with two int32 values in it. dbus_uint64_t is just one example of a type that's large enough to hold any possible value.

Be sure you have somehow checked that dbus_message_iter_get_arg_type() matches the type you are expecting, or you'll crash when you try to use an integer as a string or something.

Parameters:
iter the iterator
value location to store the value

Definition at line 1687 of file dbus-message.c.

References _dbus_type_reader_read_basic(), and NULL.

int dbus_message_iter_get_element_type DBusMessageIter iter  ) 
 

Returns the element type of the array that the message iterator points to.

Note that you need to check that the iterator points to an array prior to using this function.

Parameters:
iter the message iter
Returns:
the array element type

Definition at line 1576 of file dbus-message.c.

References _dbus_type_reader_get_element_type(), and dbus_message_iter_get_arg_type().

void dbus_message_iter_get_fixed_array DBusMessageIter iter,
void *  value,
int *  n_elements
 

Reads a block of fixed-length values from the message iterator.

Fixed-length values are those basic types that are not string-like, such as integers, bool, double. The block read will be from the current position in the array until the end of the array.

This function should only be used if dbus_type_is_fixed returns TRUE for the element type.

The value argument should be the address of a location to store the returned array. So for int32 it should be a "const dbus_int32_t**" The returned value is by reference and should not be freed.

Parameters:
iter the iterator
value location to store the block
n_elements number of elements in the block

Definition at line 1733 of file dbus-message.c.

References _dbus_type_reader_get_current_type(), _dbus_type_reader_read_fixed_multi(), dbus_type_is_fixed(), and NULL.

char* dbus_message_iter_get_signature DBusMessageIter iter  ) 
 

Returns the current signature of a message iterator.

This is useful primarily for dealing with variants; one can recurse into a variant and determine the signature of the variant's value.

Parameters:
iter the message iterator
Returns:
the contained signature, or NULL if out of memory

Definition at line 1626 of file dbus-message.c.

References _dbus_string_append_len(), _dbus_string_free(), _dbus_string_init(), _dbus_string_steal_data(), _dbus_type_reader_get_signature(), and NULL.

dbus_bool_t dbus_message_iter_has_next DBusMessageIter iter  ) 
 

Checks if an iterator has any more fields.

Parameters:
iter the message iter
Returns:
TRUE if there are more fields following

Definition at line 1513 of file dbus-message.c.

References _dbus_type_reader_has_next(), and FALSE.

dbus_bool_t dbus_message_iter_init DBusMessage message,
DBusMessageIter iter
 

Initializes a DBusMessageIter for reading the arguments of the message passed in.

Parameters:
message the message
iter pointer to an iterator to initialize
Returns:
FALSE if the message has no arguments

Definition at line 1435 of file dbus-message.c.

References _dbus_type_reader_get_current_type(), _dbus_type_reader_init(), body, byte_order, FALSE, header, NULL, DBusMessageRealIter::reader, and DBusMessageRealIter::u.

Referenced by dbus_message_get_args_valist().

void dbus_message_iter_init_append DBusMessage message,
DBusMessageIter iter
 

Initializes a DBusMessageIter for appending arguments to the end of a message.

Todo:
If appending any of the arguments fails due to lack of memory, generally the message is hosed and you have to start over building the whole message.
Parameters:
message the message
iter pointer to an iterator to initialize

Definition at line 1949 of file dbus-message.c.

References _dbus_type_writer_init_types_delayed(), body, byte_order, NULL, DBusMessageRealIter::u, and DBusMessageRealIter::writer.

Referenced by dbus_g_method_return(), dbus_message_append_args_valist(), and dbus_message_new_error().

dbus_bool_t dbus_message_iter_next DBusMessageIter iter  ) 
 

Moves the iterator to the next field, if any.

If there's no next field, returns FALSE. If the iterator moves forward, returns TRUE.

Parameters:
iter the message iter
Returns:
TRUE if the iterator was moved to the next field

Definition at line 1532 of file dbus-message.c.

References _dbus_type_reader_next(), and FALSE.

dbus_bool_t dbus_message_iter_open_container DBusMessageIter iter,
int  type,
const char *  contained_signature,
DBusMessageIter sub
 

Appends a container-typed value to the message; you are required to append the contents of the container using the returned sub-iterator, and then call dbus_message_iter_close_container().

Container types are for example struct, variant, and array. For variants, the contained_signature should be the type of the single value inside the variant. For structs and dict entries, contained_signature should be NULL; it will be set to whatever types you write into the struct. For arrays, contained_signature should be the type of the array elements.

Todo:
If this fails due to lack of memory, the message is hosed and you have to start over building the whole message.
Parameters:
iter the append iterator
type the type of the value
contained_signature the type of container contents
sub sub-iterator to initialize
Returns:
FALSE if not enough memory

Definition at line 2221 of file dbus-message.c.

References _dbus_string_init_const(), _dbus_type_writer_recurse(), dbus_type_is_container(), FALSE, NULL, DBusMessageRealIter::u, and DBusMessageRealIter::writer.

Referenced by dbus_message_append_args_valist().

void dbus_message_iter_recurse DBusMessageIter iter,
DBusMessageIter sub
 

Recurses into a container value when reading values from a message, initializing a sub-iterator to use for traversing the child values of the container.

Note that this recurses into a value, not a type, so you can only recurse if the value exists. The main implication of this is that if you have for example an empty array of array of int32, you can recurse into the outermost array, but it will have no values, so you won't be able to recurse further. There's no array of int32 to recurse into.

Parameters:
iter the message iterator
sub the sub-iterator to initialize

Definition at line 1603 of file dbus-message.c.

References _dbus_type_reader_recurse(), NULL, DBusMessageRealIter::reader, and DBusMessageRealIter::u.

DBusMessage* dbus_message_new int  message_type  ) 
 

Constructs a new message of the given message type.

Types include DBUS_MESSAGE_TYPE_METHOD_CALL, DBUS_MESSAGE_TYPE_SIGNAL, and so forth.

Parameters:
message_type type of message
Returns:
new message or NULL If no memory

Definition at line 747 of file dbus-message.c.

References _dbus_header_create(), dbus_message_unref(), header, and NULL.

DBusMessage* dbus_message_new_error DBusMessage reply_to,
const char *  error_name,
const char *  error_message
 

Creates a new message that is an error reply to a certain message.

Error replies are possible in response to method calls primarily.

Parameters:
reply_to the original message
error_name the error name
error_message the error message string or NULL for none
Returns:
a new error message

Definition at line 915 of file dbus-message.c.

References _dbus_header_create(), dbus_message_get_sender(), dbus_message_get_serial(), dbus_message_iter_append_basic(), dbus_message_iter_init_append(), dbus_message_set_no_reply(), dbus_message_set_reply_serial(), dbus_message_unref(), header, NULL, and TRUE.

Referenced by dbus_connection_dispatch(), dbus_connection_send_with_reply(), and dbus_message_new_error_printf().

DBusMessage* dbus_message_new_error_printf DBusMessage reply_to,
const char *  error_name,
const char *  error_format,
  ...
 

Creates a new message that is an error reply to a certain message.

Error replies are possible in response to method calls primarily.

Parameters:
reply_to the original message
error_name the error name
error_format the error message format as with printf
... format string arguments
Returns:
a new error message

Definition at line 980 of file dbus-message.c.

References _dbus_string_append_printf_valist(), _dbus_string_free(), _dbus_string_init(), dbus_message_new_error(), and NULL.

DBusMessage* dbus_message_new_method_call const char *  destination,
const char *  path,
const char *  interface,
const char *  method
 

Constructs a new message to invoke a method on a remote object.

Returns NULL if memory can't be allocated for the message. The destination may be NULL in which case no destination is set; this is appropriate when using D-BUS in a peer-to-peer context (no message bus). The interface may be NULL, which means that if multiple methods with the given name exist it is undefined which one will be invoked.

Parameters:
destination name that the message should be sent to or NULL
path object path the message should be sent to
interface interface to invoke method on
method method to invoke
Returns:
a new DBusMessage, free with dbus_message_unref()
See also:
dbus_message_unref()

Definition at line 786 of file dbus-message.c.

References _dbus_header_create(), dbus_message_unref(), header, and NULL.

Referenced by _dbus_message_test(), dbus_bus_add_match(), dbus_bus_get_unix_user(), dbus_bus_name_has_owner(), dbus_bus_register(), dbus_bus_release_name(), dbus_bus_remove_match(), dbus_bus_request_name(), and dbus_bus_start_service_by_name().

DBusMessage* dbus_message_new_method_return DBusMessage method_call  ) 
 

Constructs a message that is a reply to a method call.

Returns NULL if memory can't be allocated for the message.

Parameters:
method_call the message which the created message is a reply to.
Returns:
a new DBusMessage, free with dbus_message_unref()
See also:
dbus_message_new_method_call(), dbus_message_unref()

Definition at line 827 of file dbus-message.c.

References _dbus_header_create(), dbus_message_get_sender(), dbus_message_get_serial(), dbus_message_set_no_reply(), dbus_message_set_reply_serial(), dbus_message_unref(), header, NULL, and TRUE.

Referenced by dbus_g_method_get_reply(), and dbus_g_method_return().

DBusMessage* dbus_message_new_signal const char *  path,
const char *  interface,
const char *  name
 

Constructs a new message representing a signal emission.

Returns NULL if memory can't be allocated for the message. A signal is identified by its originating interface, and the name of the signal.

Parameters:
path the path to the object emitting the signal
interface the interface the signal is emitted from
name name of the signal
Returns:
a new DBusMessage, free with dbus_message_unref()
See also:
dbus_message_unref()

Definition at line 875 of file dbus-message.c.

References _dbus_header_create(), dbus_message_set_no_reply(), dbus_message_unref(), header, NULL, and TRUE.

Referenced by _dbus_connection_new_for_transport().

DBusMessage* dbus_message_ref DBusMessage message  ) 
 

Increments the reference count of a DBusMessage.

Parameters:
message The message
Returns:
the message
See also:
dbus_message_unref

Definition at line 1077 of file dbus-message.c.

References _dbus_assert, _dbus_atomic_inc(), _dbus_current_generation, generation, in_cache, NULL, and refcount.

Referenced by _dbus_connection_queue_received_message(), _dbus_pending_call_complete_and_unlock(), dbus_g_message_ref(), and dbus_message_get_g_type().

void dbus_message_set_auto_start DBusMessage message,
dbus_bool_t  auto_start
 

Sets a flag indicating that an owner for the destination name will be automatically started before the message is delivered.

When this flag is set, the message is held until a name owner finishes starting up, or fails to start up. In case of failure, the reply will be an error.

Parameters:
message the message
auto_start TRUE if auto-starting is desired

Definition at line 2358 of file dbus-message.c.

References _dbus_header_toggle_flag(), header, locked, and NULL.

dbus_bool_t dbus_message_set_destination DBusMessage message,
const char *  destination
 

Sets the message's destination.

The destination is the name of another connection on the bus and may be either the unique name assigned by the bus to each connection, or a well-known name specified in advance.

Parameters:
message the message
destination the destination name or NULL to unset
Returns:
FALSE if not enough memory

Definition at line 2725 of file dbus-message.c.

References FALSE, locked, and NULL.

Referenced by dbus_g_proxy_send().

dbus_bool_t dbus_message_set_error_name DBusMessage message,
const char *  error_name
 

Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).

The name is fully-qualified (namespaced).

Parameters:
message the message
error_name the name or NULL to unset
Returns:
FALSE if not enough memory

Definition at line 2677 of file dbus-message.c.

References FALSE, locked, and NULL.

dbus_bool_t dbus_message_set_interface DBusMessage message,
const char *  interface
 

Sets the interface this message is being sent to (for DBUS_MESSAGE_TYPE_METHOD_CALL) or the interface a signal is being emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).

Parameters:
message the message
interface the interface or NULL to unset
Returns:
FALSE if not enough memory

Definition at line 2515 of file dbus-message.c.

References FALSE, locked, and NULL.

Referenced by _dbus_message_test(), and dbus_g_proxy_send().

dbus_bool_t dbus_message_set_member DBusMessage message,
const char *  member
 

Sets the interface member being invoked (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted (DBUS_MESSAGE_TYPE_SIGNAL).

The interface name is fully-qualified (namespaced).

Parameters:
message the message
member the member or NULL to unset
Returns:
FALSE if not enough memory

Definition at line 2598 of file dbus-message.c.

References FALSE, locked, and NULL.

Referenced by _dbus_message_test().

void dbus_message_set_no_reply DBusMessage message,
dbus_bool_t  no_reply
 

Sets a flag indicating that the message does not want a reply; if this flag is set, the other end of the connection may (but is not required to) optimize by not sending method return or error replies.

If this flag is set, there is no way to know whether the message successfully arrived at the remote end. Normally you know a message was received when you receive the reply to it.

Parameters:
message the message
no_reply TRUE if no reply is desired

Definition at line 2320 of file dbus-message.c.

References _dbus_header_toggle_flag(), header, locked, and NULL.

Referenced by _dbus_message_test(), dbus_g_proxy_call_no_reply(), dbus_message_new_error(), dbus_message_new_method_return(), and dbus_message_new_signal().

dbus_bool_t dbus_message_set_path DBusMessage message,
const char *  object_path
 

Sets the object path this message is being sent to (for DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).

Parameters:
message the message
object_path the path or NULL to unset
Returns:
FALSE if not enough memory

Definition at line 2396 of file dbus-message.c.

References FALSE, locked, and NULL.

Referenced by _dbus_message_test(), and dbus_g_proxy_send().

dbus_bool_t dbus_message_set_reply_serial DBusMessage message,
dbus_uint32_t  reply_serial
 

Sets the reply serial of a message (the client serial of the message this is a reply to).

Parameters:
message the message
reply_serial the client serial
Returns:
FALSE if not enough memory

Definition at line 400 of file dbus-message.c.

References _dbus_header_set_field_basic(), FALSE, header, locked, and NULL.

Referenced by _dbus_message_test(), dbus_message_new_error(), and dbus_message_new_method_return().

dbus_bool_t dbus_message_set_sender DBusMessage message,
const char *  sender
 

Sets the message sender.

Parameters:
message the message
sender the sender or NULL to unset
Returns:
FALSE if not enough memory

Definition at line 2769 of file dbus-message.c.

References FALSE, locked, and NULL.

Referenced by _dbus_message_test().

void dbus_message_unref DBusMessage message  ) 
 

Decrements the reference count of a DBusMessage.

Parameters:
message The message
See also:
dbus_message_ref

Definition at line 1098 of file dbus-message.c.

References _dbus_assert, _dbus_atomic_dec(), _dbus_current_generation, generation, in_cache, NULL, and refcount.

Referenced by _dbus_connection_message_sent(), _dbus_connection_new_for_transport(), _dbus_message_loader_queue_messages(), _dbus_message_loader_unref(), _dbus_message_test(), dbus_bus_add_match(), dbus_bus_get_unix_user(), dbus_bus_name_has_owner(), dbus_bus_register(), dbus_bus_release_name(), dbus_bus_remove_match(), dbus_bus_request_name(), dbus_bus_start_service_by_name(), dbus_connection_dispatch(), dbus_connection_send_with_reply(), dbus_connection_send_with_reply_and_block(), dbus_g_message_unref(), dbus_g_method_return_error(), dbus_g_method_send_reply(), dbus_g_proxy_call_no_reply(), dbus_message_get_g_type(), dbus_message_new(), dbus_message_new_error(), dbus_message_new_method_call(), dbus_message_new_method_return(), dbus_message_new_signal(), and dbus_pending_call_unref().

dbus_bool_t dbus_set_error_from_message DBusError error,
DBusMessage message
 

Sets a DBusError based on the contents of the given message.

The error is only set if the message is an error message, as in DBUS_MESSAGE_TYPE_ERROR. The name of the error is set to the name of the message, and the error message is set to the first argument if the argument exists and is a string.

The return value indicates whether the error was set (the error is set if and only if the message is an error message). So you can check for an error reply and convert it to DBusError in one go:

  if (dbus_set_error_from_message (error, reply))
    return error;
  else
    process reply;

Parameters:
error the error to set
message the message to set it from
Returns:
TRUE if dbus_message_get_is_error() returns TRUE for the message

Definition at line 3078 of file dbus-message.c.

References dbus_message_get_args(), dbus_message_get_error_name(), dbus_message_get_type(), dbus_set_error(), FALSE, NULL, and TRUE.

Referenced by dbus_bus_get_unix_user(), dbus_bus_register(), dbus_bus_release_name(), dbus_bus_request_name(), dbus_bus_start_service_by_name(), and dbus_connection_send_with_reply_and_block().


Generated on Tue Jul 7 15:14:02 2009 for D-BUS by  doxygen 1.4.6