Main Page   Modules   Data Structures   File List   Data Fields   Related Pages  

DBusMessage
[D-BUS message system public API]

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

Typedefs

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


Functions

DBusMessage * dbus_message_new (int message_type)
 Constructs a new message of the given message type. More...

DBusMessage * dbus_message_new_method_call (const char *service, const char *path, const char *interface, const char *method)
 Constructs a new message to invoke a method on a remote object. More...

DBusMessage * dbus_message_new_method_return (DBusMessage *method_call)
 Constructs a message that is a reply to a method call. More...

DBusMessage * dbus_message_new_signal (const char *path, const char *interface, const char *name)
 Constructs a new message representing a signal emission. More...

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

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

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

DBusMessage * dbus_message_ref (DBusMessage *message)
 Increments the reference count of a DBusMessage. More...

void dbus_message_unref (DBusMessage *message)
 Decrements the reference count of a DBusMessage. More...

int dbus_message_get_type (DBusMessage *message)
 Gets the type of a message. More...

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

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

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

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

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

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

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

dbus_bool_t dbus_message_set_error_name (DBusMessage *message, const char *error_name)
 Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR). More...

const char * dbus_message_get_error_name (DBusMessage *message)
 Gets the error name (DBUS_MESSAGE_TYPE_ERROR only). More...

dbus_bool_t dbus_message_set_destination (DBusMessage *message, const char *destination)
 Sets the message's destination service. More...

const char * dbus_message_get_destination (DBusMessage *message)
 Gets the destination service of a message. More...

dbus_bool_t dbus_message_append_args (DBusMessage *message, int first_arg_type,...)
 Appends fields to a message given a variable argument list. More...

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

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

dbus_bool_t dbus_message_iter_get_args (DBusMessageIter *iter, DBusError *error, int first_arg_type,...)
 Gets arguments from a message iterator given a variable argument list. More...

dbus_bool_t dbus_message_iter_init (DBusMessage *message, DBusMessageIter *iter)
 Initializes a DBusMessageIter representing the arguments of the message passed in. More...

dbus_bool_t dbus_message_iter_has_next (DBusMessageIter *iter)
 Checks if an iterator has any more fields. More...

dbus_bool_t dbus_message_iter_next (DBusMessageIter *iter)
 Moves the iterator to the next field. More...

int dbus_message_iter_get_arg_type (DBusMessageIter *iter)
 Returns the argument type of the argument that the message iterator points at. More...

int dbus_message_iter_get_array_type (DBusMessageIter *iter)
 Returns the element type of the array that the message iterator points at. More...

char * dbus_message_iter_get_string (DBusMessageIter *iter)
 Returns the string value that an iterator may point to. More...

char * dbus_message_iter_get_object_path (DBusMessageIter *iter)
 Returns the object path value that an iterator may point to. More...

dbus_bool_t dbus_message_iter_get_custom (DBusMessageIter *iter, char **name, unsigned char **value, int *len)
 Returns the name and data from a custom type that an iterator may point to. More...

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

unsigned char dbus_message_iter_get_byte (DBusMessageIter *iter)
 Returns the byte value that an iterator may point to. More...

dbus_bool_t dbus_message_iter_get_boolean (DBusMessageIter *iter)
 Returns the boolean value that an iterator may point to. More...

dbus_int32_t dbus_message_iter_get_int32 (DBusMessageIter *iter)
 Returns the 32 bit signed integer value that an iterator may point to. More...

dbus_uint32_t dbus_message_iter_get_uint32 (DBusMessageIter *iter)
 Returns the 32 bit unsigned integer value that an iterator may point to. More...

dbus_int64_t dbus_message_iter_get_int64 (DBusMessageIter *iter)
 Returns the 64 bit signed integer value that an iterator may point to. More...

dbus_uint64_t dbus_message_iter_get_uint64 (DBusMessageIter *iter)
 Returns the 64 bit unsigned integer value that an iterator may point to. More...

double dbus_message_iter_get_double (DBusMessageIter *iter)
 Returns the double value that an iterator may point to. More...

dbus_bool_t dbus_message_iter_init_array_iterator (DBusMessageIter *iter, DBusMessageIter *array_iter, int *array_type)
 Initializes an iterator for the array that the iterator may point to. More...

dbus_bool_t dbus_message_iter_init_dict_iterator (DBusMessageIter *iter, DBusMessageIter *dict_iter)
 Initializes an iterator for the dict that the iterator may point to. More...

dbus_bool_t dbus_message_iter_get_byte_array (DBusMessageIter *iter, unsigned char **value, int *len)
 Returns the byte array that the iterator may point to. More...

dbus_bool_t dbus_message_iter_get_boolean_array (DBusMessageIter *iter, unsigned char **value, int *len)
 Returns the boolean array that the iterator may point to. More...

dbus_bool_t dbus_message_iter_get_int32_array (DBusMessageIter *iter, dbus_int32_t **value, int *len)
 Returns the 32 bit signed integer array that the iterator may point to. More...

dbus_bool_t dbus_message_iter_get_uint32_array (DBusMessageIter *iter, dbus_uint32_t **value, int *len)
 Returns the 32 bit unsigned integer array that the iterator may point to. More...

dbus_bool_t dbus_message_iter_get_int64_array (DBusMessageIter *iter, dbus_int64_t **value, int *len)
 Returns the 64 bit signed integer array that the iterator may point to. More...

dbus_bool_t dbus_message_iter_get_uint64_array (DBusMessageIter *iter, dbus_uint64_t **value, int *len)
 Returns the 64 bit unsigned integer array that the iterator may point to. More...

dbus_bool_t dbus_message_iter_get_double_array (DBusMessageIter *iter, double **value, int *len)
 Returns the double array that the iterator may point to. More...

dbus_bool_t dbus_message_iter_get_string_array (DBusMessageIter *iter, char ***value, int *len)
 Returns the string array that the iterator may point to. More...

dbus_bool_t dbus_message_iter_get_object_path_array (DBusMessageIter *iter, char ***value, int *len)
 Returns the object path array that the iterator may point to. More...

char * dbus_message_iter_get_dict_key (DBusMessageIter *iter)
 Returns the key name fot the dict entry that an iterator may point to. More...

void dbus_message_append_iter_init (DBusMessage *message, DBusMessageIter *iter)
 Initializes a DBusMessageIter pointing to the end of the message. More...

dbus_bool_t dbus_message_iter_append_nil (DBusMessageIter *iter)
 Appends a nil value to the message. More...

dbus_bool_t dbus_message_iter_append_boolean (DBusMessageIter *iter, dbus_bool_t value)
 Appends a boolean value to the message. More...

dbus_bool_t dbus_message_iter_append_byte (DBusMessageIter *iter, unsigned char value)
 Appends a byte to the message. More...

dbus_bool_t dbus_message_iter_append_int32 (DBusMessageIter *iter, dbus_int32_t value)
 Appends a 32 bit signed integer to the message. More...

dbus_bool_t dbus_message_iter_append_uint32 (DBusMessageIter *iter, dbus_uint32_t value)
 Appends a 32 bit unsigned integer to the message. More...

dbus_bool_t dbus_message_iter_append_int64 (DBusMessageIter *iter, dbus_int64_t value)
 Appends a 64 bit signed integer to the message. More...

dbus_bool_t dbus_message_iter_append_uint64 (DBusMessageIter *iter, dbus_uint64_t value)
 Appends a 64 bit unsigned integer to the message. More...

dbus_bool_t dbus_message_iter_append_double (DBusMessageIter *iter, double value)
 Appends a double value to the message. More...

dbus_bool_t dbus_message_iter_append_string (DBusMessageIter *iter, const char *value)
 Appends a UTF-8 string to the message. More...

dbus_bool_t dbus_message_iter_append_object_path (DBusMessageIter *iter, const char *value)
 Appends an object path to the message. More...

dbus_bool_t dbus_message_iter_append_custom (DBusMessageIter *iter, const char *name, const unsigned char *data, int len)
 Appends a custom type data chunk to the message. More...

dbus_bool_t dbus_message_iter_append_dict_key (DBusMessageIter *iter, const char *value)
 Appends a dict key name to the message. More...

dbus_bool_t dbus_message_iter_append_array (DBusMessageIter *iter, DBusMessageIter *array_iter, int element_type)
 Appends an array to the message and initializes an iterator that can be used to append to the array. More...

dbus_bool_t dbus_message_iter_append_dict (DBusMessageIter *iter, DBusMessageIter *dict_iter)
 Appends a dict to the message and initializes an iterator that can be used to append to the dict. More...

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

dbus_bool_t dbus_message_iter_append_boolean_array (DBusMessageIter *iter, unsigned const char *value, int len)
 Appends a boolean array to the message. More...

dbus_bool_t dbus_message_iter_append_int32_array (DBusMessageIter *iter, const dbus_int32_t *value, int len)
 Appends a 32 bit signed integer array to the message. More...

dbus_bool_t dbus_message_iter_append_uint32_array (DBusMessageIter *iter, const dbus_uint32_t *value, int len)
 Appends a 32 bit unsigned integer array to the message. More...

dbus_bool_t dbus_message_iter_append_int64_array (DBusMessageIter *iter, const dbus_int64_t *value, int len)
 Appends a 64 bit signed integer array to the message. More...

dbus_bool_t dbus_message_iter_append_uint64_array (DBusMessageIter *iter, const dbus_uint64_t *value, int len)
 Appends a 64 bit unsigned integer array to the message. More...

dbus_bool_t dbus_message_iter_append_double_array (DBusMessageIter *iter, const double *value, int len)
 Appends a double array to the message. More...

dbus_bool_t dbus_message_iter_append_byte_array (DBusMessageIter *iter, unsigned const char *value, int len)
 Appends a byte array to the message. More...

dbus_bool_t dbus_message_iter_append_string_array (DBusMessageIter *iter, const char **value, int len)
 Appends a string array to the message. More...

dbus_bool_t dbus_message_iter_append_object_path_array (DBusMessageIter *iter, const char **value, int len)
 Appends an object path array to the message. More...

dbus_bool_t dbus_message_set_sender (DBusMessage *message, const char *sender)
 Sets the message sender. More...

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

dbus_bool_t dbus_message_get_no_reply (DBusMessage *message)
 Returns TRUE if the message does not expect a reply. More...

void dbus_message_set_auto_activation (DBusMessage *message, dbus_bool_t auto_activation)
 Sets a flag indicating that the addressed service will be auto-activated before the message is delivered. More...

dbus_bool_t dbus_message_get_auto_activation (DBusMessage *message)
 Returns TRUE if the message will cause the addressed service to be auto-activated. More...

const char * dbus_message_get_sender (DBusMessage *message)
 Gets the service which originated this message, or NULL if unknown or inapplicable. More...

const char * dbus_message_get_signature (DBusMessage *message)
 Gets the type signature of the message, i.e. More...

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

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

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

dbus_bool_t dbus_message_has_destination (DBusMessage *message, const char *service)
 Checks whether the message was sent to the given service. More...

dbus_bool_t dbus_message_has_sender (DBusMessage *message, const char *service)
 Checks whether the message has the given service as its sender. More...

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

dbus_bool_t dbus_set_error_from_message (DBusError *error, DBusMessage *message)
 Sets a DBusError based on the contents of the given message. More...


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_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 the argument followed by the value to add. Array values are specified by an int typecode followed by a pointer to the array followed by an int giving the length of the array. The argument list must be terminated with DBUS_TYPE_INVALID.

This function doesn't support dicts or non-fundamental arrays.

This function supports DBUS_TYPE_INT64 and DBUS_TYPE_UINT64 only if DBUS_HAVE_INT64 is defined.

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 2032 of file dbus-message.c.

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:
: Shouldn't this function clean up the changes to the message on failures? (Yes)

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 3963 of file dbus-message.c.

References body.

void dbus_message_append_iter_init DBusMessage   message,
DBusMessageIter   iter
 

Initializes a DBusMessageIter pointing to the end of the message.

This iterator can be used to append data to the message.

Parameters:
message  the message
iter  pointer to an iterator to initialize

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

References body, DBusMessageRealIter::changed_stamp, changed_stamp, DBusMessageRealIter::container_length_pos, DBusMessageRealIter::end, DBusMessageRealIter::message, DBusMessageRealIter::parent_iter, DBusMessageRealIter::pos, DBusMessageRealIter::type, and DBusMessageRealIter::wrote_dict_key.

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.

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

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

References body, byte_order, client_serial, header, header_fields, header_padding, locked, refcount, reply_serial, and DBusAtomic::value.

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 variable argument list should contain the type of the argumen followed by a pointer to where the value should be stored. The list is terminated with DBUS_TYPE_INVALID.

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 2063 of file dbus-message.c.

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.

Todo:
We need to free the argument data when an error occurs.

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 2094 of file dbus-message.c.

dbus_bool_t dbus_message_get_auto_activation DBusMessage   message
 

Returns TRUE if the message will cause the addressed service to be auto-activated.

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

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

References header.

const char* dbus_message_get_destination DBusMessage   message
 

Gets the destination service of a message.

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

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

const char* dbus_message_get_error_name DBusMessage   message
 

Gets the error name (DBUS_MESSAGE_TYPE_ERROR only).

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

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

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

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

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

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

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

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

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 4351 of file dbus-message.c.

References header.

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

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

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

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

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 1847 of file dbus-message.c.

const char* dbus_message_get_sender DBusMessage   message
 

Gets the service which originated this message, or NULL if unknown or inapplicable.

Parameters:
message  the message
Returns:
the service name or NULL

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

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_STRING. 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 4441 of file dbus-message.c.

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 1783 of file dbus-message.c.

References header.

dbus_bool_t dbus_message_has_destination DBusMessage   message,
const char *    service
 

Checks whether the message was sent to the given service.

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

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

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

dbus_bool_t dbus_message_has_sender DBusMessage   message,
const char *    service
 

Checks whether the message has the given service as its sender.

If the message has no sender specified or has a different sender, returns FALSE. Note that if a peer application owns multiple services, its messages will have only one of those services as the sender (usually the base service). So you can't use this function to prove the sender didn't own service Foo, you can only use it to prove that it did.

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

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

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 4633 of file dbus-message.c.

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 4545 of file dbus-message.c.

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.

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 4495 of file dbus-message.c.

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.

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 4521 of file dbus-message.c.

dbus_bool_t dbus_message_iter_append_array DBusMessageIter   iter,
DBusMessageIter   array_iter,
int    element_type
 

Appends an array to the message and initializes an iterator that can be used to append to the array.

Parameters:
iter  an iterator pointing to the end of the message
array_iter  pointer to an iter that will be initialized
element_type  the type of the array elements
Returns:
TRUE on success

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

References DBusMessageRealIter::array_type_done, DBusMessageRealIter::array_type_pos, body, byte_order, DBusMessageRealIter::changed_stamp, changed_stamp, DBusMessageRealIter::container_length_pos, DBusMessageRealIter::container_start, DBusMessageRealIter::end, DBusMessageRealIter::message, DBusMessageRealIter::parent_iter, DBusMessageRealIter::pos, DBusMessageRealIter::type, and DBusMessageRealIter::wrote_dict_key.

dbus_bool_t dbus_message_iter_append_boolean DBusMessageIter   iter,
dbus_bool_t    value
 

Appends a boolean value to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the boolean value
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_boolean_array DBusMessageIter   iter,
unsigned const char *    value,
int    len
 

Appends a boolean array to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the array
len  the length of the array
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_byte DBusMessageIter   iter,
unsigned char    value
 

Appends a byte to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the byte value
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_byte_array DBusMessageIter   iter,
unsigned const char *    value,
int    len
 

Appends a byte array to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the array
len  the length of the array
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_custom DBusMessageIter   iter,
const char *    name,
const unsigned char *    data,
int    len
 

Appends a custom type data chunk to the message.

A custom type is simply an arbitrary UTF-8 string used as a type tag, plus an array of arbitrary bytes to be interpreted according to the type tag.

Parameters:
iter  an iterator pointing to the end of the message
name  the name of the type
data  the binary data used to store the value
len  the length of the binary data in bytes
Returns:
TRUE on success

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

References body, byte_order, DBusMessageRealIter::message, and DBusMessageRealIter::pos.

dbus_bool_t dbus_message_iter_append_dict DBusMessageIter   iter,
DBusMessageIter   dict_iter
 

Appends a dict to the message and initializes an iterator that can be used to append to the dict.

Parameters:
iter  an iterator pointing to the end of the message
dict_iter  pointer to an iter that will be initialized
Returns:
TRUE on success

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

References body, byte_order, DBusMessageRealIter::changed_stamp, changed_stamp, DBusMessageRealIter::container_length_pos, DBusMessageRealIter::container_start, DBusMessageRealIter::end, DBusMessageRealIter::message, DBusMessageRealIter::parent_iter, DBusMessageRealIter::pos, DBusMessageRealIter::type, and DBusMessageRealIter::wrote_dict_key.

dbus_bool_t dbus_message_iter_append_dict_key DBusMessageIter   iter,
const char *    value
 

Appends a dict key name to the message.

The iterator used must point to a dict.

Parameters:
iter  an iterator pointing to the end of the message
value  the string
Returns:
TRUE on success

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

References body, byte_order, DBusMessageRealIter::message, DBusMessageRealIter::type, and DBusMessageRealIter::wrote_dict_key.

dbus_bool_t dbus_message_iter_append_double DBusMessageIter   iter,
double    value
 

Appends a double value to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the double value
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_double_array DBusMessageIter   iter,
const double *    value,
int    len
 

Appends a double array to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the array
len  the length of the array
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_int32 DBusMessageIter   iter,
dbus_int32_t    value
 

Appends a 32 bit signed integer to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the integer value
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_int32_array DBusMessageIter   iter,
const dbus_int32_t   value,
int    len
 

Appends a 32 bit signed integer array to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the array
len  the length of the array
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_int64 DBusMessageIter   iter,
dbus_int64_t    value
 

Appends a 64 bit signed integer to the message.

This function only exists if DBUS_HAVE_INT64 is defined.

Parameters:
iter  an iterator pointing to the end of the message
value  the integer value
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_int64_array DBusMessageIter   iter,
const dbus_int64_t   value,
int    len
 

Appends a 64 bit signed integer array to the message.

This function only exists if DBUS_HAVE_INT64 is defined.

Parameters:
iter  an iterator pointing to the end of the message
value  the array
len  the length of the array
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_nil DBusMessageIter   iter
 

Appends a nil value to the message.

Parameters:
iter  an iterator pointing to the end of the message
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_object_path DBusMessageIter   iter,
const char *    value
 

Appends an object path to the message.

Todo:
add return_val_if_fail(UTF-8 is valid)
Parameters:
iter  an iterator pointing to the end of the message
value  the object path
Returns:
TRUE on success

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

References body, byte_order, DBusMessageRealIter::message, and DBusMessageRealIter::pos.

dbus_bool_t dbus_message_iter_append_object_path_array DBusMessageIter   iter,
const char **    value,
int    len
 

Appends an object path array to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the array
len  the length of the array
Returns:
TRUE on success

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

References body, byte_order, DBusMessageRealIter::message, and DBusMessageRealIter::pos.

dbus_bool_t dbus_message_iter_append_string DBusMessageIter   iter,
const char *    value
 

Appends a UTF-8 string to the message.

Todo:
add return_val_if_fail(UTF-8 is valid)
Parameters:
iter  an iterator pointing to the end of the message
value  the string
Returns:
TRUE on success

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

References body, byte_order, DBusMessageRealIter::message, and DBusMessageRealIter::pos.

dbus_bool_t dbus_message_iter_append_string_array DBusMessageIter   iter,
const char **    value,
int    len
 

Appends a string array to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the array
len  the length of the array
Returns:
TRUE on success

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

References body, byte_order, DBusMessageRealIter::message, and DBusMessageRealIter::pos.

dbus_bool_t dbus_message_iter_append_uint32 DBusMessageIter   iter,
dbus_uint32_t    value
 

Appends a 32 bit unsigned integer to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the integer value
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_uint32_array DBusMessageIter   iter,
const dbus_uint32_t   value,
int    len
 

Appends a 32 bit unsigned integer array to the message.

Parameters:
iter  an iterator pointing to the end of the message
value  the array
len  the length of the array
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_uint64 DBusMessageIter   iter,
dbus_uint64_t    value
 

Appends a 64 bit unsigned integer to the message.

This function only exists if DBUS_HAVE_INT64 is defined.

Parameters:
iter  an iterator pointing to the end of the message
value  the integer value
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_append_uint64_array DBusMessageIter   iter,
const dbus_uint64_t   value,
int    len
 

Appends a 64 bit unsigned integer array to the message.

This function only exists if DBUS_HAVE_INT64 is defined.

Parameters:
iter  an iterator pointing to the end of the message
value  the array
len  the length of the array
Returns:
TRUE on success

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

int dbus_message_iter_get_arg_type DBusMessageIter   iter
 

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

Parameters:
iter  the message iter
Returns:
the field type

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

References DBusMessageRealIter::end, and DBusMessageRealIter::pos.

dbus_bool_t dbus_message_iter_get_args DBusMessageIter   iter,
DBusError   error,
int    first_arg_type,
...   
 

Gets arguments from a message iterator given a variable argument list.

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

Parameters:
iter  the message iterator
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 2121 of file dbus-message.c.

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.

This function supports DBUS_TYPE_INT64 and DBUS_TYPE_UINT64 only if DBUS_HAVE_INT64 is defined.

Todo:
this function (or some lower-level non-convenience function) needs better error handling; should allow the application to distinguish between out of memory, and bad data from the remote app. It also needs to not leak a bunch of args when it gets to the arg that's bad, as that would be a security hole (allow one app to force another to leak memory)

We need to free the argument data when an error occurs.

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 2572 of file dbus-message.c.

int dbus_message_iter_get_array_type DBusMessageIter   iter
 

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

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 field type

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

References DBusMessageRealIter::end, and DBusMessageRealIter::pos.

dbus_bool_t dbus_message_iter_get_boolean DBusMessageIter   iter
 

Returns the boolean value that an iterator may point to.

Note that you need to check that the iterator points to a boolean value before using this function.

See also:
dbus_message_iter_get_arg_type
Parameters:
iter  the message iter
Returns:
the boolean value

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

dbus_bool_t dbus_message_iter_get_boolean_array DBusMessageIter   iter,
unsigned char **    value,
int *    len
 

Returns the boolean array that the iterator may point to.

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

Parameters:
iter  the iterator
value  return location for the array
len  return location for the array length
Returns:
TRUE on success

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

unsigned char dbus_message_iter_get_byte DBusMessageIter   iter
 

Returns the byte value that an iterator may point to.

Note that you need to check that the iterator points to a byte value before using this function.

See also:
dbus_message_iter_get_arg_type
Parameters:
iter  the message iter
Returns:
the byte value

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

dbus_bool_t dbus_message_iter_get_byte_array DBusMessageIter   iter,
unsigned char **    value,
int *    len
 

Returns the byte array that the iterator may point to.

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

Parameters:
iter  the iterator
value  return location for array values
len  return location for length of byte array
Returns:
TRUE on success

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

dbus_bool_t dbus_message_iter_get_custom DBusMessageIter   iter,
char **    name,
unsigned char **    value,
int *    len
 

Returns the name and data from a custom type that an iterator may point to.

Note that you need to check that the iterator points to a custom type before using this function.

See also:
dbus_message_iter_get_arg_type
Parameters:
iter  the message iter
name  return location for the name of the custom type
value  return location for data
len  return location for length of data
Returns:
TRUE if get succeed

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

References body, byte_order, and DBusMessageRealIter::message.

char* dbus_message_iter_get_dict_key DBusMessageIter   iter
 

Returns the key name fot the dict entry that an iterator may point to.

Note that you need to check that the iterator points to a dict entry before using this function.

See also:
dbus_message_iter_init_dict_iterator
Parameters:
iter  the message iter
Returns:
the key name

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

References body, byte_order, DBusMessageRealIter::message, DBusMessageRealIter::pos, and DBusMessageRealIter::type.

double dbus_message_iter_get_double DBusMessageIter   iter
 

Returns the double value that an iterator may point to.

Note that you need to check that the iterator points to a string value before using this function.

See also:
dbus_message_iter_get_arg_type
Parameters:
iter  the message iter
Returns:
the double

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

dbus_bool_t dbus_message_iter_get_double_array DBusMessageIter   iter,
double **    value,
int *    len
 

Returns the double array that the iterator may point to.

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

Parameters:
iter  the iterator
value  return location for the array
len  return location for the array length
Returns:
TRUE on success

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

dbus_int32_t dbus_message_iter_get_int32 DBusMessageIter   iter
 

Returns the 32 bit signed integer value that an iterator may point to.

Note that you need to check that the iterator points to a 32-bit integer value before using this function.

See also:
dbus_message_iter_get_arg_type
Parameters:
iter  the message iter
Returns:
the integer

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

dbus_bool_t dbus_message_iter_get_int32_array DBusMessageIter   iter,
dbus_int32_t **    value,
int *    len
 

Returns the 32 bit signed integer array that the iterator may point to.

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

Parameters:
iter  the iterator
value  return location for the array
len  return location for the array length
Returns:
TRUE on success

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

dbus_int64_t dbus_message_iter_get_int64 DBusMessageIter   iter
 

Returns the 64 bit signed integer value that an iterator may point to.

Note that you need to check that the iterator points to a 64-bit integer value before using this function.

This function only exists if DBUS_HAVE_INT64 is defined.

See also:
dbus_message_iter_get_arg_type
Parameters:
iter  the message iter
Returns:
the integer

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

dbus_bool_t dbus_message_iter_get_int64_array DBusMessageIter   iter,
dbus_int64_t **    value,
int *    len
 

Returns the 64 bit signed integer array that the iterator may point to.

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

This function only exists if DBUS_HAVE_INT64 is defined.

Parameters:
iter  the iterator
value  return location for the array
len  return location for the array length
Returns:
TRUE on success

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

char* dbus_message_iter_get_object_path DBusMessageIter   iter
 

Returns the object path value that an iterator may point to.

Note that you need to check that the iterator points to an object path value before using this function.

See also:
dbus_message_iter_get_arg_type
Parameters:
iter  the message iter
Returns:
the path

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

References body, byte_order, and DBusMessageRealIter::message.

dbus_bool_t dbus_message_iter_get_object_path_array DBusMessageIter   iter,
char ***    value,
int *    len
 

Returns the object path array that the iterator may point to.

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

The returned value is a NULL-terminated array of strings. Each string is a separate malloc block, and the array itself is a malloc block. You can free this type of array with dbus_free_string_array().

Parameters:
iter  the iterator
value  return location for string values
len  return location for length of byte array
Returns:
TRUE on success

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

References body, byte_order, and DBusMessageRealIter::message.

char* dbus_message_iter_get_string DBusMessageIter   iter
 

Returns the string value that an iterator may point to.

Note that you need to check that the iterator points to a string value before using this function.

See also:
dbus_message_iter_get_arg_type
Parameters:
iter  the message iter
Returns:
the string

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

References body, byte_order, and DBusMessageRealIter::message.

dbus_bool_t dbus_message_iter_get_string_array DBusMessageIter   iter,
char ***    value,
int *    len
 

Returns the string array that the iterator may point to.

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

The returned value is a NULL-terminated array of strings. Each string is a separate malloc block, and the array itself is a malloc block. You can free this type of string array with dbus_free_string_array().

Parameters:
iter  the iterator
value  return location for string values
len  return location for length of byte array
Returns:
TRUE on success

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

References body, byte_order, and DBusMessageRealIter::message.

dbus_uint32_t dbus_message_iter_get_uint32 DBusMessageIter   iter
 

Returns the 32 bit unsigned integer value that an iterator may point to.

Note that you need to check that the iterator points to a 32-bit unsigned integer value before using this function.

See also:
dbus_message_iter_get_arg_type
Parameters:
iter  the message iter
Returns:
the integer

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

dbus_bool_t dbus_message_iter_get_uint32_array DBusMessageIter   iter,
dbus_uint32_t **    value,
int *    len
 

Returns the 32 bit unsigned integer array that the iterator may point to.

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

Parameters:
iter  the iterator
value  return location for the array
len  return location for the array length
Returns:
TRUE on success

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

dbus_uint64_t dbus_message_iter_get_uint64 DBusMessageIter   iter
 

Returns the 64 bit unsigned integer value that an iterator may point to.

Note that you need to check that the iterator points to a 64-bit unsigned integer value before using this function.

This function only exists if DBUS_HAVE_INT64 is defined.

See also:
dbus_message_iter_get_arg_type
Parameters:
iter  the message iter
Returns:
the integer

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

dbus_bool_t dbus_message_iter_get_uint64_array DBusMessageIter   iter,
dbus_uint64_t **    value,
int *    len
 

Returns the 64 bit unsigned integer array that the iterator may point to.

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

This function only exists if DBUS_HAVE_INT64 is defined.

Parameters:
iter  the iterator
value  return location for the array
len  return location for the array length
Returns:
TRUE on success

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

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 2279 of file dbus-message.c.

References body, byte_order, DBusMessageRealIter::end, DBusMessageRealIter::message, and DBusMessageRealIter::pos.

dbus_bool_t dbus_message_iter_init DBusMessage   message,
DBusMessageIter   iter
 

Initializes a DBusMessageIter representing 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 2148 of file dbus-message.c.

References DBusMessageRealIter::array_type_pos, body, DBusMessageRealIter::changed_stamp, changed_stamp, DBusMessageRealIter::container_length_pos, DBusMessageRealIter::container_start, DBusMessageRealIter::end, DBusMessageRealIter::message, DBusMessageRealIter::parent_iter, DBusMessageRealIter::pos, DBusMessageRealIter::type, and DBusMessageRealIter::wrote_dict_key.

dbus_bool_t dbus_message_iter_init_array_iterator DBusMessageIter   iter,
DBusMessageIter   array_iter,
int *    array_type
 

Initializes an iterator for the array that the iterator may point to.

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

The array element type is returned in array_type, and the array iterator can only be used to get that type of data.

Parameters:
iter  the iterator
array_iter  pointer to an iterator to initialize
array_type  gets set to the type of the array elements
Returns:
FALSE if the array is empty

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

References DBusMessageRealIter::array_type_done, DBusMessageRealIter::array_type_pos, body, byte_order, DBusMessageRealIter::changed_stamp, changed_stamp, DBusMessageRealIter::container_length_pos, DBusMessageRealIter::container_start, DBusMessageRealIter::end, DBusMessageRealIter::message, DBusMessageRealIter::parent_iter, DBusMessageRealIter::pos, DBusMessageRealIter::type, and DBusMessageRealIter::wrote_dict_key.

dbus_bool_t dbus_message_iter_init_dict_iterator DBusMessageIter   iter,
DBusMessageIter   dict_iter
 

Initializes an iterator for the dict that the iterator may point to.

Note that you need to check that the iterator points to a dict prior to using this function.

Parameters:
iter  the iterator
dict_iter  pointer to an iterator to initialize
Returns:
FALSE if the dict is empty

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

References body, byte_order, DBusMessageRealIter::changed_stamp, changed_stamp, DBusMessageRealIter::container_length_pos, DBusMessageRealIter::container_start, DBusMessageRealIter::end, DBusMessageRealIter::message, DBusMessageRealIter::parent_iter, DBusMessageRealIter::pos, DBusMessageRealIter::type, and DBusMessageRealIter::wrote_dict_key.

dbus_bool_t dbus_message_iter_next DBusMessageIter   iter
 

Moves the iterator to the next field.

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

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

References body, byte_order, DBusMessageRealIter::end, DBusMessageRealIter::message, and DBusMessageRealIter::pos.

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 1383 of file dbus-message.c.

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 1544 of file dbus-message.c.

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 string to be printed
...  value of first argument, list of additional values to print
Returns:
a new error message

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

DBusMessage* dbus_message_new_method_call const char *    service,
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 service may be NULL in which case no service 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:
service  service 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 1422 of file dbus-message.c.

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 1457 of file dbus-message.c.

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 1507 of file dbus-message.c.

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 1714 of file dbus-message.c.

References refcount.

void dbus_message_set_auto_activation DBusMessage   message,
dbus_bool_t    auto_activation
 

Sets a flag indicating that the addressed service will be auto-activated before the message is delivered.

When this flag is set, the message is held until the service is succesfully activated or fail to activate. In case of failure, the reply will be an activation error.

Parameters:
message  the message
auto_activation  TRUE if auto-activation is desired

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

References header, and locked.

dbus_bool_t dbus_message_set_destination DBusMessage   message,
const char *    destination
 

Sets the message's destination service.

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

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

References locked.

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 1948 of file dbus-message.c.

References locked.

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 1869 of file dbus-message.c.

References locked.

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 1909 of file dbus-message.c.

References locked.

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.

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

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

References header, and locked.

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 1803 of file dbus-message.c.

References locked.

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 4304 of file dbus-message.c.

References locked.

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 1745 of file dbus-message.c.

References body, header, refcount, size_counters, and slot_list.

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.

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 4667 of file dbus-message.c.


Generated on Wed Jun 9 05:01:28 2004 for D-BUS by doxygen1.2.15