D-Bus 1.13.18

Data Structures | Macros | Typedefs | Functions
DBusMessage
D-Bus low-level public API

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

## Data Structures
struct | DBusMessageIter
| DBusMessageIter struct; contains no public fields. More...

## Macros
#define | DBUS_MESSAGE_ITER_INIT_CLOSED
| A message iterator for which dbus_message_iter_abandon_container_if_open() is the only valid operation. More...

## Typedefs
typedef struct DBusMessage | DBusMessage
| Opaque data type representing a message received from or to be sent to another application. More...
typedef struct DBusMessageIter | DBusMessageIter
| Opaque type representing a message iterator. More...

## Functions
dbus_uint32_t | dbus_message_get_serial (DBusMessage *message)
| Returns the serial of a message or 0 if none has been specified. More...
dbus_bool_t | dbus_message_set_reply_serial (DBusMessage *message, dbus_uint32_t reply_serial)
| Sets the reply serial of a message (the serial of the message this is a reply to). More...
dbus_uint32_t | dbus_message_get_reply_serial (DBusMessage *message)
| Returns the serial that the message is a reply to or 0 if none. More...
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 *destination, const char *path, const char *iface, 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 *iface, 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 another 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 another message, allowing you to use printf formatting. 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, 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. 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, freeing the message if the count reaches 0. More...
int | dbus_message_get_type (DBusMessage *message)
| Gets the type 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_append_args_valist (DBusMessage *message, int first_arg_type, va_list var_args)
| Like dbus_message_append_args() but takes a va_list for use by language bindings. 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)
| Like dbus_message_get_args but takes a va_list for use by language bindings. More...
dbus_bool_t | dbus_message_iter_init (DBusMessage *message, DBusMessageIter *iter)
| Initializes a DBusMessageIter for reading 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, if any. More...
int | dbus_message_iter_get_arg_type (DBusMessageIter *iter)
| Returns the argument type of the argument that the message iterator points to. More...
int | dbus_message_iter_get_element_type (DBusMessageIter *iter)
| Returns the element type of the array that the message iterator points to. More...
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. More...
char * | dbus_message_iter_get_signature (DBusMessageIter *iter)
| Returns the current signature of a message iterator. More...
void | dbus_message_iter_get_basic (DBusMessageIter *iter, void *value)
| Reads a basic-typed value from the message iterator. More...
int | dbus_message_iter_get_element_count (DBusMessageIter *iter)
| Returns the number of elements in the array-typed value pointed to by the iterator. More...
int | dbus_message_iter_get_array_len (DBusMessageIter *iter)
| Returns the number of bytes in the array as marshaled in the wire protocol. More...
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. More...
void | dbus_message_iter_init_append (DBusMessage *message, DBusMessageIter *iter)
| Initializes a DBusMessageIter for appending arguments to the end of a message. More...
dbus_bool_t | dbus_message_iter_append_basic (DBusMessageIter *iter, int type, const void *value)
| Appends a basic-typed value to the message. More...
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. More...
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. More...
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(). More...
void | dbus_message_iter_abandon_container (DBusMessageIter *iter, DBusMessageIter *sub)
| Abandons creation of a contained-typed value and frees resources created by dbus_message_iter_open_container(). More...
void | dbus_message_iter_abandon_container_if_open (DBusMessageIter *iter, DBusMessageIter *sub)
| Abandons creation of a contained-typed value and frees resources created by dbus_message_iter_open_container(). 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_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. More...
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. 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_has_path (DBusMessage *message, const char *path)
| Checks if the message has a particular object path. 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 *iface)
| 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_has_interface (DBusMessage *message, const char *iface)
| Checks if the message has an interface. 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_has_member (DBusMessage *message, const char *member)
| Checks if the message has an interface member. 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) or NULL if none. More...
dbus_bool_t | dbus_message_set_destination (DBusMessage *message, const char *destination)
| Sets the message's destination. More...
const char * | dbus_message_get_destination (DBusMessage *message)
| Gets the destination of a message or NULL if there is none set. More...
dbus_bool_t | dbus_message_set_sender (DBusMessage *message, const char *sender)
| Sets the message sender. More...
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. 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 *iface, 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 *iface, 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 *name)
| Checks whether the message was sent to the given name. More...
dbus_bool_t | dbus_message_has_sender (DBusMessage *message, const char *name)
| Checks whether the message has the given unique name 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...
dbus_bool_t | dbus_message_contains_unix_fds (DBusMessage *message)
| Checks whether a message contains unix fds. More...
dbus_bool_t | dbus_message_set_container_instance (DBusMessage *message, const char *object_path)
| Sets the container instance this message was sent from. More...
const char * | dbus_message_get_container_instance (DBusMessage *message)
| Gets the container instance this message was sent from, or NULL if none. More...
DBUS_EXPORT void | dbus_message_set_serial (DBusMessage *message, dbus_uint32_t serial)
| Sets the serial number of a message. More...
DBUS_EXPORT void | dbus_message_iter_init_closed (DBusMessageIter *iter)
| Initialize iter as if with DBUS_MESSAGE_ITER_INIT_CLOSED. More...
DBUS_EXPORT void | dbus_message_lock (DBusMessage *message)
| Locks a message. More...
DBUS_EXPORT dbus_bool_t | dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
| Allocates an integer ID to be used for storing application-specific data on any DBusMessage. More...
DBUS_EXPORT void | dbus_message_free_data_slot (dbus_int32_t *slot_p)
| Deallocates a global ID for message data slots. More...
DBUS_EXPORT dbus_bool_t | dbus_message_set_data (DBusMessage *message, dbus_int32_t slot, void *data, DBusFreeFunction free_data_func)
| Stores a pointer on a DBusMessage, along with an optional function to be used for freeing the data when the data is set again, or when the message is finalized. More...
DBUS_EXPORT void * | dbus_message_get_data (DBusMessage *message, dbus_int32_t slot)
| Retrieves data previously set with dbus_message_set_data(). More...
DBUS_EXPORT int | dbus_message_type_from_string (const char *type_str)
| Utility function to convert a machine-readable (not translated) string into a D-Bus message type. More...
DBUS_EXPORT const char * | dbus_message_type_to_string (int type)
| Utility function to convert a D-Bus message type into a machine-readable string (not translated). More...
DBUS_EXPORT dbus_bool_t | dbus_message_marshal (DBusMessage *msg, char **marshalled_data_p, int *len_p)
| Turn a DBusMessage into the marshalled form as described in the D-Bus specification. More...
DBUS_EXPORT DBusMessage * | dbus_message_demarshal (const char *str, int len, DBusError *error)
| Demarshal a D-Bus message from the format described in the D-Bus specification. More...
DBUS_EXPORT int | dbus_message_demarshal_bytes_needed (const char *str, int len)
| Returns the number of bytes required to be in the buffer to demarshal a D-Bus message. More...
DBUS_EXPORT void | dbus_message_set_allow_interactive_authorization (DBusMessage *message, dbus_bool_t allow)
| Sets a flag indicating that the caller of the method is prepared to wait for interactive authorization to take place (for instance via Polkit) before the actual method is processed. More...
DBUS_EXPORT dbus_bool_t | dbus_message_get_allow_interactive_authorization (DBusMessage *message)
| Returns whether the flag controlled by dbus_message_set_allow_interactive_authorization() has been set. 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.

A message has a message type, returned from dbus_message_get_type(). This indicates whether the message is a method call, a reply to a method call, a signal, or an error reply.

A message has header fields such as the sender, destination, method or signal name, and so forth. DBusMessage has accessor functions for these, such as dbus_message_get_member().

Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(), and dbus_message_is_error() check several header fields at once and are slightly more efficient than checking the header fields with individual accessor functions.

Finally, a message has arguments. The number and types of arguments are in the message's signature header field (accessed with dbus_message_get_signature()). Simple argument values are usually retrieved with dbus_message_get_args() but more complex values such as structs may require the use of DBusMessageIter.

The D-Bus specification goes into some more detail about header fields and message types.

## Macro Definition Documentation

## ◆ DBUS_MESSAGE_ITER_INIT_CLOSED

#define DBUS_MESSAGE_ITER_INIT_CLOSED

Value:
{ \
NULL, /* dummy1 */ \
NULL, /* dummy2 */ \
0, /* dummy3 */ \
0, /* dummy4 */ \
0, /* dummy5 */ \
0, /* dummy6 */ \
0, /* dummy7 */ \
0, /* dummy8 */ \
0, /* dummy9 */ \
0, /* dummy10 */ \
0, /* dummy11 */ \
0, /* pad1 */ \
NULL, /* pad2 */ \
NULL /* pad3 */ \
}

A message iterator for which dbus_message_iter_abandon_container_if_open() is the only valid operation.

Definition at line 83 of file dbus-message.h.

## Typedef Documentation

## ◆ DBusMessage

DBusMessage

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

Definition at line 44 of file dbus-message.h.

## ◆ DBusMessageIter

typedef struct DBusMessageIter DBusMessageIter

Opaque type representing a message iterator.

Can be copied by value and allocated on the stack.

A DBusMessageIter usually contains no allocated memory. However, there is one special case: after a successful call to dbus_message_iter_open_container(), the caller is responsible for calling either dbus_message_iter_close_container() or dbus_message_iter_abandon_container() exactly once, with the same pair of iterators.

Definition at line 56 of file dbus-message.h.

## Function Documentation

## ◆ dbus_message_allocate_data_slot()

DBUS_EXPORT dbus_bool_t dbus_message_allocate_data_slot | ( | dbus_int32_t * | slot_p | ) |

Allocates an integer ID to be used for storing application-specific data on any DBusMessage.

The allocated ID may then be used with dbus_message_set_data() and dbus_message_get_data(). The passed-in slot must be initialized to -1, and is filled in with the slot ID. If the passed-in slot is not -1, it's assumed to be already allocated, and its refcount is incremented.

The allocated slot is global, i.e. all DBusMessage objects will have a slot with the given integer ID reserved.

Parameters

  slot_p | address of a global variable storing the slot

Returns
  FALSE on failure (no memory)

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

References _dbus_data_slot_allocator_alloc().

## ◆ dbus_message_append_args()

DBUS_EXPORT 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 (except arrays of Unix file descriptors). 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_message_append_args (message,
DBUS_TYPE_INT32, &v_INT32,
DBUS_TYPE_STRING, &v_STRING,
DBUS_TYPE_INVALID);
dbus_message_append_args
dbus_bool_t dbus_message_append_args(DBusMessage *message, int first_arg_type,...)
Appends fields to a message given a variable argument list.
Definition: dbus-message.c:1831
DBUS_TYPE_INT32
#define DBUS_TYPE_INT32
Type code marking a 32-bit signed integer.
Definition: dbus-protocol.h:82
DBUS_TYPE_STRING
#define DBUS_TYPE_STRING
Type code marking a UTF-8 encoded, nul-terminated Unicode string.
Definition: dbus-protocol.h:102
DBUS_TYPE_INVALID
#define DBUS_TYPE_INVALID
Type code that is never equal to a legitimate type code.
Definition: dbus-protocol.h:60

To append an array of fixed-length basic types (except Unix file descriptors), 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_message_append_args (message,
DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3,
DBUS_TYPE_INVALID);
DBUS_TYPE_ARRAY
#define DBUS_TYPE_ARRAY
Type code marking a D-Bus array type.
Definition: dbus-protocol.h:120

This function does not support arrays of Unix file descriptors. If you need those you need to manually recurse into the array.

For Unix file descriptors this function will internally duplicate the descriptor you passed in. Hence you may close the descriptor immediately after this call.

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. If you don't do this then libdbus won't know to stop and will read invalid memory.

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

References dbus_message_append_args_valist(), FALSE, and NULL.

Referenced by 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_message_append_args_valist()

DBUS_EXPORT dbus_bool_t dbus_message_append_args_valist | ( | DBusMessage * | message,
|  | int | first_arg_type,
|  | va_list | var_args
| ) |  |

Like dbus_message_append_args() but takes a va_list for use by language bindings.

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

References _dbus_type_to_string(), _dbus_warn(), dbus_message_iter_abandon_container(), 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_ARRAY, DBUS_TYPE_INVALID, dbus_type_is_basic(), dbus_type_is_fixed(), DBUS_TYPE_UNIX_FD, FALSE, NULL, and TRUE.

Referenced by dbus_message_append_args().

## ◆ dbus_message_contains_unix_fds()

DBUS_EXPORT dbus_bool_t dbus_message_contains_unix_fds | ( | DBusMessage * | message | ) |

Checks whether a message contains unix fds.

Parameters

  message | the message

Returns
  TRUE if the message contains unix fds

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

References _dbus_assert, and FALSE.

## ◆ dbus_message_copy()

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

Todo:
  This function can't be used in programs that try to recover from OOM errors.

Parameters

  message | the message

Returns
  the new message.or NULL if not enough memory or Unix file descriptors (in case the message to copy includes Unix file descriptors) can be allocated.

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

References _dbus_atomic_inc(), _dbus_dup(), _dbus_header_copy(), _dbus_header_free(), _dbus_string_copy(), _dbus_string_init_preallocated(), body, dbus_free(), dbus_new, dbus_new0, FALSE, generation, header, locked, NULL, and refcount.

## ◆ dbus_message_demarshal()

DBUS_EXPORT DBusMessage * dbus_message_demarshal | ( | const char * | str,
|  | int | len,
|  | DBusError * | error
| ) |  |

Demarshal a D-Bus message from the format described in the D-Bus specification.

Generally, this function is only useful for encapsulating D-Bus messages in a different protocol.

Parameters

  str | the marshalled DBusMessage
  len | the length of str
  error | the location to save errors to

Returns
  NULL if there was an error

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

References _dbus_message_loader_get_buffer(), _dbus_message_loader_get_is_corrupted(), _dbus_message_loader_new(), _dbus_message_loader_pop_message(), _dbus_message_loader_queue_messages(), _dbus_message_loader_return_buffer(), _dbus_message_loader_unref(), _dbus_string_append_len(), DBUS_ERROR_INVALID_ARGS, dbus_set_error(), and NULL.

## ◆ dbus_message_demarshal_bytes_needed()

DBUS_EXPORT int dbus_message_demarshal_bytes_needed | ( | const char * | buf,
|  | int | len
| ) |  |

Returns the number of bytes required to be in the buffer to demarshal a D-Bus message.

Generally, this function is only useful for encapsulating D-Bus messages in a different protocol.

Parameters

  buf | data to be marshalled
  len | the length of `buf`

Returns
  -1 if there was no valid data to be demarshalled, 0 if there wasn't enough data to determine how much should be demarshalled. Otherwise returns the number of bytes to be demarshalled

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

References _dbus_assert, _dbus_header_have_message_untrusted(), _dbus_string_free(), _dbus_string_init_const_len(), DBUS_MAXIMUM_MESSAGE_LENGTH, DBUS_MINIMUM_HEADER_SIZE, and DBUS_VALID.

## ◆ dbus_message_free_data_slot()

DBUS_EXPORT void dbus_message_free_data_slot | ( | dbus_int32_t * | slot_p | ) |

Deallocates a global ID for message data slots.

dbus_message_get_data() and dbus_message_set_data() may no longer be used with this slot. Existing data stored on existing DBusMessage objects will be freed when the message is finalized, but may not be retrieved (and may only be replaced if someone else reallocates the slot). When the refcount on the passed-in slot reaches 0, it is set to -1.

Parameters

  slot_p | address storing the slot to deallocate

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

References _dbus_data_slot_allocator_free().

## ◆ dbus_message_get_allow_interactive_authorization()

DBUS_EXPORT dbus_bool_t dbus_message_get_allow_interactive_authorization | ( | DBusMessage * | message | ) |

Returns whether the flag controlled by dbus_message_set_allow_interactive_authorization() has been set.

Parameters

  message | the message

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

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

## ◆ dbus_message_get_args()

DBUS_EXPORT 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".

Similar to dbus_message_get_fixed_array() this function does not support arrays of type DBUS_TYPE_UNIX_FD. If you need to parse messages with arrays of Unix file descriptors you need to recurse into the array manually.

Unix file descriptors that are read with this function will have the FD_CLOEXEC flag set. If you need them without this flag set, make sure to unset it with fcntl().

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.

Except for string arrays, 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.

If more arguments than requested are present, the requested arguments are returned and the extra arguments are ignored.

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

References dbus_message_get_args_valist(), FALSE, and NULL.

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

## ◆ dbus_message_get_args_valist()

DBUS_EXPORT dbus_bool_t dbus_message_get_args_valist | ( | DBusMessage * | message,
|  | DBusError * | error,
|  | int | first_arg_type,
|  | va_list | var_args
| ) |  |

Like dbus_message_get_args but takes a va_list for use by language bindings.

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 2049 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_message_get_auto_start()

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

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

## ◆ dbus_message_get_container_instance()

DBUS_EXPORT const char * dbus_message_get_container_instance | ( | DBusMessage * | message | ) |

Gets the container instance this message was sent from, or NULL if none.

The returned string becomes invalid if the message is modified, since it points into the wire-marshaled message data.

Parameters

  message | the message

Returns
  the path (should not be freed) or NULL

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

References _dbus_header_get_field_basic(), DBUS_HEADER_FIELD_CONTAINER_INSTANCE, DBUS_TYPE_OBJECT_PATH, header, and NULL.

## ◆ dbus_message_get_data()

DBUS_EXPORT void * dbus_message_get_data | ( | DBusMessage * | message,
|  | dbus_int32_t | slot
| ) |  |

Retrieves data previously set with dbus_message_set_data().

The slot must still be allocated (must not have been freed).

Parameters

  message | the message
  slot | the slot to get data from

Returns
  the data, or NULL if not found

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

References _dbus_data_slot_list_get(), and NULL.

## ◆ dbus_message_get_destination()

DBUS_EXPORT const char * dbus_message_get_destination | ( | DBusMessage * | message | ) |

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

The returned string becomes invalid if the message is modified, since it points into the wire-marshaled message data.

Parameters

  message | the message

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

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

References _dbus_header_get_field_basic(), DBUS_HEADER_FIELD_DESTINATION, DBUS_TYPE_STRING, header, and NULL.

Referenced by dbus_message_has_destination().

## ◆ dbus_message_get_error_name()

DBUS_EXPORT const char * dbus_message_get_error_name | ( | DBusMessage * | message | ) |

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

The returned string becomes invalid if the message is modified, since it points into the wire-marshaled message data.

Parameters

  message | the message

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

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

References _dbus_header_get_field_basic(), DBUS_HEADER_FIELD_ERROR_NAME, DBUS_TYPE_STRING, header, and NULL.

Referenced by dbus_message_is_error(), and dbus_set_error_from_message().

## ◆ dbus_message_get_interface()

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

The returned string becomes invalid if the message is modified, since it points into the wire-marshaled message data.

Parameters

  message | the message

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

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

References _dbus_header_get_field_basic(), DBUS_HEADER_FIELD_INTERFACE, DBUS_TYPE_STRING, header, and NULL.

Referenced by _dbus_connection_message_sent_unlocked(), dbus_connection_send_preallocated(), and dbus_message_has_interface().

## ◆ dbus_message_get_member()

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

The returned string becomes invalid if the message is modified, since it points into the wire-marshaled message data.

Parameters

  message | the message

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

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

References _dbus_header_get_field_basic(), DBUS_HEADER_FIELD_MEMBER, DBUS_TYPE_STRING, header, and NULL.

Referenced by _dbus_connection_message_sent_unlocked(), dbus_connection_send_preallocated(), and dbus_message_has_member().

## ◆ dbus_message_get_no_reply()

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

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

## ◆ dbus_message_get_path()

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

See also dbus_message_get_path_decomposed().

The returned string becomes invalid if the message is modified, since it points into the wire-marshaled message data.

Parameters

  message | the message

Returns
  the path (should not be freed) or NULL

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

References _dbus_header_get_field_basic(), DBUS_HEADER_FIELD_PATH, DBUS_TYPE_OBJECT_PATH, header, and NULL.

Referenced by _dbus_connection_message_sent_unlocked(), dbus_message_get_path_decomposed(), and dbus_message_has_path().

## ◆ dbus_message_get_path_decomposed()

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

See also dbus_message_get_path().

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 3405 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_message_get_reply_serial()

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

References _dbus_header_get_field_basic(), DBUS_HEADER_FIELD_REPLY_SERIAL, DBUS_TYPE_UINT32, header, and NULL.

Referenced by _dbus_connection_queue_received_message_link(), and _dbus_pending_call_set_reply_unlocked().

## ◆ dbus_message_get_sender()

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

Note, the returned sender is always the unique bus name. Connections may own multiple other bus names, but those are not found in the sender field.

The returned string becomes invalid if the message is modified, since it points into the wire-marshaled message data.

Parameters

  message | the message

Returns
  the unique name of the sender or NULL

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

References _dbus_header_get_field_basic(), DBUS_HEADER_FIELD_SENDER, DBUS_TYPE_STRING, header, and NULL.

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

## ◆ dbus_message_get_serial()

DBUS_EXPORT 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 provided by the remote application.

For messages you're sending, dbus_connection_send() will assign a serial and return it to you.

Parameters

  message | the message

Returns
  the serial

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

References _dbus_header_get_serial(), header, and NULL.

## ◆ dbus_message_get_signature()

DBUS_EXPORT 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 (that is, 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).

The returned string becomes invalid if the message is modified, since it points into the wire-marshaled message data.

Parameters

  message | the message

Returns
  the type signature

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

References NULL.

Referenced by _dbus_connection_message_sent_unlocked(), dbus_message_has_signature(), and dbus_message_lock().

## ◆ dbus_message_get_type()

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

Parameters

  message | the message

Returns
  the type of the message

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

References _dbus_header_get_message_type(), DBUS_MESSAGE_TYPE_INVALID, header, and NULL.

Referenced by _dbus_connection_message_sent_unlocked(), _dbus_pending_call_set_reply_unlocked(), dbus_connection_send_preallocated(), dbus_message_is_error(), and dbus_set_error_from_message().

## ◆ dbus_message_has_destination()

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

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

## ◆ dbus_message_has_interface()

DBUS_EXPORT dbus_bool_t dbus_message_has_interface | ( | DBusMessage * | message,
|  | const char * | iface
| ) |  |

Checks if the message has an interface.

Parameters

  message | the message
  iface | the interface name

Returns
  TRUE if the interface field in the header matches

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

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

## ◆ dbus_message_has_member()

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

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

## ◆ dbus_message_has_path()

DBUS_EXPORT dbus_bool_t dbus_message_has_path | ( | DBusMessage * | message,
|  | const char * | path
| ) |  |

Checks if the message has a particular object path.

The object path is the destination object for a method call or the emitting object for a signal.

Parameters

  message | the message
  path | the path name

Returns
  TRUE if there is a path field in the header

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

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

## ◆ dbus_message_has_sender()

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

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

## ◆ dbus_message_has_signature()

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

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

## ◆ dbus_message_is_error()

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

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

## ◆ dbus_message_is_method_call()

DBUS_EXPORT dbus_bool_t dbus_message_is_method_call | ( | DBusMessage * | message,
|  | const char * | iface,
|  | 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
  iface | 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 3843 of file dbus-message.c.

References FALSE, and NULL.

## ◆ dbus_message_is_signal()

DBUS_EXPORT dbus_bool_t dbus_message_is_signal | ( | DBusMessage * | message,
|  | const char * | iface,
|  | 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
  iface | 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 3871 of file dbus-message.c.

References FALSE, and NULL.

## ◆ dbus_message_iter_abandon_container()

DBUS_EXPORT void dbus_message_iter_abandon_container | ( | DBusMessageIter * | iter,
|  | DBusMessageIter * | sub
| ) |  |

Abandons creation of a contained-typed value and frees resources created by dbus_message_iter_open_container().

Once this returns, the message is hosed and you have to start over building the whole message.

This should only be used to abandon creation of a message when you have open containers.

Parameters

  iter | the append iterator
  sub | sub-iterator to close

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

Referenced by dbus_message_append_args_valist().

## ◆ dbus_message_iter_abandon_container_if_open()

DBUS_EXPORT void dbus_message_iter_abandon_container_if_open | ( | DBusMessageIter * | iter,
|  | DBusMessageIter * | sub
| ) |  |

Abandons creation of a contained-typed value and frees resources created by dbus_message_iter_open_container().

Once this returns, the message is hosed and you have to start over building the whole message.

Unlike dbus_message_iter_abandon_container(), it is valid to call this function on an iterator that was initialized with DBUS_MESSAGE_ITER_INIT_CLOSED, or an iterator that was already closed or abandoned. However, it is not valid to call this function on uninitialized memory. This is intended to be used in error cleanup code paths, similar to this pattern:

      DBusMessageIter outer = DBUS_MESSAGE_ITER_INIT_CLOSED;
      DBusMessageIter inner = DBUS_MESSAGE_ITER_INIT_CLOSED;
      dbus_bool_t result = FALSE;

      if (!dbus_message_iter_open_container (iter, ..., &outer))
        goto out;

      if (!dbus_message_iter_open_container (&outer, ..., &inner))
        goto out;

      if (!dbus_message_iter_append_basic (&inner, ...))
        goto out;

      if (!dbus_message_iter_close_container (&outer, ..., &inner))
        goto out;

      if (!dbus_message_iter_close_container (iter, ..., &outer))
        goto out;

      result = TRUE;

    out:
      dbus_message_iter_abandon_container_if_open (&outer, &inner);
      dbus_message_iter_abandon_container_if_open (iter, &outer);
      return result;

Parameters

  iter | the append iterator
  sub | sub-iterator to close

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

## ◆ dbus_message_iter_append_basic()

DBUS_EXPORT 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*.

For Unix file descriptors this function will internally duplicate the descriptor you passed in. Hence you may close the descriptor immediately after this call.

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

Referenced by dbus_message_append_args_valist().

## ◆ dbus_message_iter_append_fixed_array()

DBUS_EXPORT 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. (Unix file descriptors however are not supported.) 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");
  dbus_message_iter_append_fixed_array
  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.
  Definition: dbus-message.c:2900
  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 2900 of file dbus-message.c.

Referenced by dbus_message_append_args_valist().

## ◆ dbus_message_iter_close_container()

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

Even if this function fails due to lack of memory, the sub-iterator sub has been closed and invalidated. It must not be closed again with this function, or abandoned with dbus_message_iter_abandon_container(). However, it remains valid to call dbus_message_iter_abandon_container_if_open().

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

Referenced by dbus_message_append_args_valist().

## ◆ dbus_message_iter_get_arg_type()

DBUS_EXPORT 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 (message, &iter);
while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
dbus_message_iter_next (&iter);
dbus_message_iter_next
dbus_bool_t dbus_message_iter_next(DBusMessageIter *iter)
Moves the iterator to the next field, if any.
Definition: dbus-message.c:2168
dbus_message_iter_get_arg_type
int dbus_message_iter_get_arg_type(DBusMessageIter *iter)
Returns the argument type of the argument that the message iterator points to.
Definition: dbus-message.c:2193
dbus_message_iter_init
dbus_bool_t dbus_message_iter_init(DBusMessage *message, DBusMessageIter *iter)
Initializes a DBusMessageIter for reading the arguments of the message passed in.
Definition: dbus-message.c:2118

Parameters

  iter | the message iter

Returns
  the argument type

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

References DBUS_TYPE_INVALID, and DBusMessageRealIter::iter_type.

Referenced by _dbus_message_iter_get_args_valist(), and dbus_message_iter_get_basic().

## ◆ dbus_message_iter_get_array_len()

DBUS_EXPORT DBUS_DEPRECATED int dbus_message_iter_get_array_len | ( | DBusMessageIter * | iter | ) |

Returns the number of bytes in the array as marshaled in the wire protocol.

The iterator must currently be inside an array-typed value.

This function is deprecated on the grounds that it is stupid. Why would you want to know how many bytes are in the array as marshaled in the wire protocol? Use dbus_message_iter_get_element_count() instead.

Parameters

  iter | the iterator

Returns
  the number of bytes in the array

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

References _dbus_type_reader_get_array_length(), DBusMessageRealIter::reader, and DBusMessageRealIter::u.

## ◆ dbus_message_iter_get_basic()

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

This call duplicates Unix file descriptors when reading them. It is your job to close them when you don't need them anymore.

Unix file descriptors that are read with this function will have the FD_CLOEXEC flag set. If you need them without this flag set, make sure to unset it with fcntl().

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.

To read any container type (array, struct, dict) you will need to recurse into the container with dbus_message_iter_recurse(). If the container is an array of fixed-length values (except Unix file descriptors), you can get all the array elements at once with dbus_message_iter_get_fixed_array(). Otherwise, you have to iterate over the container's contents one value at a time.

All basic-typed values are guaranteed to fit in a DBusBasicValue, so in versions of libdbus that have that type, you can write code like this:

DBusBasicValue 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);
dbus_message_iter_append_basic
dbus_bool_t dbus_message_iter_append_basic(DBusMessageIter *iter, int type, const void *value)
Appends a basic-typed value to the message.
Definition: dbus-message.c:2749
dbus_message_iter_get_basic
void dbus_message_iter_get_basic(DBusMessageIter *iter, void *value)
Reads a basic-typed value from the message iterator.
Definition: dbus-message.c:2347
DBusBasicValue
A simple value union that lets you access bytes as if they were various types; useful when dealing wi...
Definition: dbus-types.h:138

(All D-Bus basic types are either numeric and 8 bytes or smaller, or behave like a string; so in older versions of libdbus, DBusBasicValue can be replaced with union { char *string; unsigned char bytes[8]; }, for instance.)

Parameters

  iter | the iterator
  value | location to store the value

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

References _dbus_dup(), _dbus_type_reader_read_basic(), dbus_message_iter_get_arg_type(), DBUS_TYPE_UNIX_FD, DBusMessageRealIter::message, NULL, DBusMessageRealIter::reader, DBusMessageRealIter::u, and DBusBasicValue::u32.

## ◆ dbus_message_iter_get_element_count()

DBUS_EXPORT int dbus_message_iter_get_element_count | ( | DBusMessageIter * | iter | ) |

Returns the number of elements in the array-typed value pointed to by the iterator.

Note that this function is O(1) for arrays of fixed-size types but O(n) for arrays of variable-length types such as strings, so it may be a bad idea to use it.

Parameters

  iter | the iterator

Returns
  the number of elements in the array

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

References _dbus_type_get_alignment(), _dbus_type_reader_get_array_length(), _dbus_type_reader_get_current_type(), _dbus_type_reader_get_element_type(), _dbus_type_reader_next(), _dbus_type_reader_recurse(), DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID, dbus_type_is_fixed(), DBusMessageRealIter::reader, and DBusMessageRealIter::u.

## ◆ dbus_message_iter_get_element_type()

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

References DBUS_TYPE_INVALID, and DBusMessageRealIter::iter_type.

## ◆ dbus_message_iter_get_fixed_array()

DBUS_EXPORT 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 returned block will be from the current position in the array until the end of the array.

There is one exception here: although DBUS_TYPE_UNIX_FD is considered a 'fixed' type arrays of this type may not be read with this function.

The message iter should be "in" the array (that is, you recurse into the array, and then you call dbus_message_iter_get_fixed_array() on the "sub-iterator" created by dbus_message_iter_recurse()).

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.

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

If an array's elements are not fixed in size, you have to recurse into the array with dbus_message_iter_recurse() and read the elements one by one.

Because the array is not copied, this function runs in constant time and is fast; it's much preferred over walking the entire array with an iterator. (However, you can always use dbus_message_iter_recurse(), even for fixed-length types; dbus_message_iter_get_fixed_array() is just an optimization.)

Parameters

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

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

References _dbus_type_reader_get_current_type(), _dbus_type_reader_read_fixed_multi(), DBUS_TYPE_INVALID, dbus_type_is_fixed(), DBUS_TYPE_UNIX_FD, NULL, DBusMessageRealIter::reader, and DBusMessageRealIter::u.

## ◆ dbus_message_iter_get_signature()

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

The returned string must be freed with dbus_free().

Parameters

  iter | the message iterator

Returns
  the contained signature, or NULL if out of memory

Definition at line 2274 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(), NULL, DBusMessageRealIter::reader, and DBusMessageRealIter::u.

## ◆ dbus_message_iter_has_next()

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

References FALSE, and DBusMessageRealIter::iter_type.

## ◆ dbus_message_iter_init()

DBUS_EXPORT dbus_bool_t dbus_message_iter_init | ( | DBusMessage * | message,
|  | DBusMessageIter * | iter
| ) |  |

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

When possible, dbus_message_get_args() is much more convenient. Some types of argument can only be read with DBusMessageIter however.

The easiest way to iterate is like this:

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

DBusMessageIter contains no allocated memory; it need not be freed, and can be copied by assignment or memcpy().

Parameters

  message | the message
  iter | pointer to an iterator to initialize

Returns
  FALSE if the message has no arguments

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

References FALSE, and NULL.

Referenced by dbus_message_get_args_valist().

## ◆ dbus_message_iter_init_append()

DBUS_EXPORT 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, 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 2511 of file dbus-message.c.

References NULL.

Referenced by dbus_message_append_args_valist().

## ◆ dbus_message_iter_init_closed()

DBUS_EXPORT void dbus_message_iter_init_closed | ( | DBusMessageIter * | iter | ) |

Initialize iter as if with DBUS_MESSAGE_ITER_INIT_CLOSED.

The only valid operation for such an iterator is dbus_message_iter_abandon_container_if_open(), which does nothing.

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

References NULL.

## ◆ dbus_message_iter_next()

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

References FALSE, and DBusMessageRealIter::iter_type.

## ◆ dbus_message_iter_open_container()

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

On success, 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.

If this function fails, the sub-iterator remains invalid, and must not be closed with dbus_message_iter_close_container() or abandoned with dbus_message_iter_abandon_container(). However, after this function has either succeeded or failed, it is valid to call dbus_message_iter_abandon_container_if_open().

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

References FALSE, and NULL.

Referenced by dbus_message_append_args_valist().

## ◆ dbus_message_iter_recurse()

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

If a container is an array of fixed-length types (except Unix file descriptors), it is much more efficient to use dbus_message_iter_get_fixed_array() to get the whole array in one shot, rather than individually walking over the array elements.

Be sure you have somehow checked that dbus_message_iter_get_arg_type() matches the type you are expecting to recurse into. Results of this function are undefined if there is no container to recurse into at the current iterator position.

Parameters

  iter | the message iterator
  sub | the sub-iterator to initialize

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

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

## ◆ dbus_message_lock()

DBUS_EXPORT void dbus_message_lock | ( | DBusMessage * | message | ) |

Locks a message.

Allows checking that applications don't keep a reference to a message in the outgoing queue and change it underneath us. Messages are locked when they enter the outgoing queue (dbus_connection_send_message()), and the library complains if the message is modified while locked. This function may also called externally, for applications wrapping D-Bus in another protocol.

Parameters

  message | the message to lock.

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

References _dbus_assert, _dbus_header_update_lengths(), body, dbus_message_get_signature(), header, locked, NULL, and TRUE.

Referenced by dbus_message_marshal().

## ◆ dbus_message_marshal()

DBUS_EXPORT dbus_bool_t dbus_message_marshal | ( | DBusMessage * | msg,
|  | char ** | marshalled_data_p,
|  | int * | len_p
| ) |  |

Turn a DBusMessage into the marshalled form as described in the D-Bus specification.

Generally, this function is only useful for encapsulating D-Bus messages in a different protocol.

Parameters

  msg | the DBusMessage
  marshalled_data_p | the location to save the marshalled form to
  len_p | the location to save the length of the marshalled form to

Returns
  FALSE if there was not enough memory

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

References _dbus_string_copy(), _dbus_string_free(), _dbus_string_init(), _dbus_string_steal_data(), body, DBusHeader::data, dbus_message_lock(), FALSE, header, locked, NULL, and TRUE.

## ◆ dbus_message_new()

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

Usually you want to use dbus_message_new_method_call(), dbus_message_new_method_return(), dbus_message_new_signal(), or dbus_message_new_error() instead.

Parameters

  message_type | type of message

Returns
  new message or NULL if no memory

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

References DBUS_MESSAGE_TYPE_INVALID, and NULL.

## ◆ dbus_message_new_error()

DBUS_EXPORT 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 another message.

Error replies are most common in response to method calls, but can be returned in reply to any message.

The error name must be a valid error name according to the syntax given in the D-Bus specification. If you don't want to make up an error name just use DBUS_ERROR_FAILED.

Parameters

  reply_to | the message we're replying to
  error_name | the error name
  error_message | the error message string (or NULL for none, but please give a message)

Returns
  a new error message object, free with dbus_message_unref()

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

References dbus_message_get_sender(), and NULL.

Referenced by _dbus_pending_call_set_timeout_error_unlocked(), and dbus_message_new_error_printf().

## ◆ dbus_message_new_error_printf()

DBUS_EXPORT 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 another message, allowing you to use printf formatting.

See dbus_message_new_error() for details - this function is the same aside from the printf formatting.

Todo:
  add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to public header, see DBUS_DEPRECATED for an example)

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

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

## ◆ dbus_message_new_method_call()

DBUS_EXPORT DBusMessage * dbus_message_new_method_call | ( | const char * | destination,
|  | const char * | path,
|  | const char * | iface,
|  | 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.

The path and method names may not be NULL.

Destination, path, interface, and method name can't contain any invalid characters (see the D-Bus specification).

Parameters

  destination | name that the message should be sent to or NULL
  path | object path the message should be sent to
  iface | interface to invoke method on, or NULL
  method | method to invoke

Returns
  a new DBusMessage, free with dbus_message_unref()

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

References NULL.

Referenced by dbus_bus_add_match(), dbus_bus_get_id(), 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_message_new_method_return()

DBUS_EXPORT 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 being replied to

Returns
  a new DBusMessage, free with dbus_message_unref()

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

References dbus_message_get_sender(), and NULL.

## ◆ dbus_message_new_signal()

DBUS_EXPORT DBusMessage * dbus_message_new_signal | ( | const char * | path,
|  | const char * | iface,
|  | 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 object path, interface, and the name of the signal.

Path, interface, and signal name must all be valid (the D-Bus specification defines the syntax of these fields).

Parameters

  path | the path to the object emitting the signal
  iface | the interface the signal is emitted from
  name | name of the signal

Returns
  a new DBusMessage, free with dbus_message_unref()

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

References NULL.

## ◆ dbus_message_ref()

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

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

Referenced by _dbus_pending_call_set_reply_unlocked().

## ◆ dbus_message_set_allow_interactive_authorization()

DBUS_EXPORT void dbus_message_set_allow_interactive_authorization | ( | DBusMessage * | message,
|  | dbus_bool_t | allow
| ) |  |

Sets a flag indicating that the caller of the method is prepared to wait for interactive authorization to take place (for instance via Polkit) before the actual method is processed.

The flag is FALSE by default; that is, by default the other end is expected to make any authorization decisions non-interactively and promptly. It may use the error DBUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED to signal that authorization failed, but could have succeeded if this flag had been used.

For messages whose type is not DBUS_MESSAGE_TYPE_METHOD_CALL, this flag is meaningless and should not be set.

On the protocol level this toggles DBUS_HEADER_FLAG_ALLOW_INTERACTIVE_AUTHORIZATION.

Parameters

  message | the message
  allow | TRUE if interactive authorization is acceptable

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

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

## ◆ dbus_message_set_auto_start()

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

The flag is set to TRUE by default, i.e. auto starting is the default.

On the protocol level this toggles DBUS_HEADER_FLAG_NO_AUTO_START

Parameters

  message | the message
  auto_start | TRUE if auto-starting is desired

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

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

## ◆ dbus_message_set_container_instance()

DBUS_EXPORT dbus_bool_t dbus_message_set_container_instance | ( | DBusMessage * | message,
|  | const char * | object_path
| ) |  |

Sets the container instance this message was sent from.

The path must contain only valid characters for an object path as defined in the D-Bus specification.

Parameters

  message | the message
  object_path | the path or NULL to unset

Returns
  FALSE if not enough memory

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

References FALSE, locked, and NULL.

## ◆ dbus_message_set_data()

DBUS_EXPORT dbus_bool_t dbus_message_set_data | ( | DBusMessage * | message,
|  | dbus_int32_t | slot,
|  | void * | data,
|  | DBusFreeFunction | free_data_func
| ) |  |

Stores a pointer on a DBusMessage, along with an optional function to be used for freeing the data when the data is set again, or when the message is finalized.

The slot number must have been allocated with dbus_message_allocate_data_slot().

Parameters

  message | the message
  slot | the slot number
  data | the data to store
  free_data_func | finalizer function for the data

Returns
  TRUE if there was enough memory to store the data

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

References _dbus_data_slot_list_set(), FALSE, and NULL.

## ◆ dbus_message_set_destination()

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

The destination name must contain only valid characters as defined in the D-Bus specification.

Parameters

  message | the message
  destination | the destination name or NULL to unset

Returns
  FALSE if not enough memory

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

References FALSE, locked, and NULL.

## ◆ dbus_message_set_error_name()

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

The error name must contain only valid characters as defined in the D-Bus specification.

Parameters

  message | the message
  error_name | the name or NULL to unset

Returns
  FALSE if not enough memory

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

References FALSE, locked, and NULL.

## ◆ dbus_message_set_interface()

DBUS_EXPORT dbus_bool_t dbus_message_set_interface | ( | DBusMessage * | message,
|  | const char * | iface
| ) |  |

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

The interface name must contain only valid characters as defined in the D-Bus specification.

Parameters

  message | the message
  iface | the interface or NULL to unset

Returns
  FALSE if not enough memory

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

References FALSE, locked, and NULL.

## ◆ dbus_message_set_member()

DBUS_EXPORT 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 member name must contain only valid characters as defined in the D-Bus specification.

Parameters

  message | the message
  member | the member or NULL to unset

Returns
  FALSE if not enough memory

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

References FALSE, locked, and NULL.

## ◆ dbus_message_set_no_reply()

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

The flag is FALSE by default, that is by default the other end is required to reply.

On the protocol level this toggles DBUS_HEADER_FLAG_NO_REPLY_EXPECTED

Parameters

  message | the message
  no_reply | TRUE if no reply is desired

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

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

## ◆ dbus_message_set_path()

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

The path must contain only valid characters as defined in the D-Bus specification.

Parameters

  message | the message
  object_path | the path or NULL to unset

Returns
  FALSE if not enough memory

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

References FALSE, locked, and NULL.

## ◆ dbus_message_set_reply_serial()

DBUS_EXPORT dbus_bool_t dbus_message_set_reply_serial | ( | DBusMessage * | message,
|  | dbus_uint32_t | reply_serial
| ) |  |

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

Parameters

  message | the message
  reply_serial | the serial we're replying to

Returns
  FALSE if not enough memory

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

References _dbus_header_set_field_basic(), DBUS_HEADER_FIELD_REPLY_SERIAL, DBUS_TYPE_UINT32, FALSE, header, locked, NULL, and DBusBasicValue::u32.

## ◆ dbus_message_set_sender()

DBUS_EXPORT dbus_bool_t dbus_message_set_sender | ( | DBusMessage * | message,
|  | const char * | sender
| ) |  |

Sets the message sender.

The sender must be a valid bus name as defined in the D-Bus specification.

Usually you don't want to call this. The message bus daemon will call it to set the origin of each message. If you aren't implementing a message bus daemon you shouldn't need to set the sender.

Parameters

  message | the message
  sender | the sender or NULL to unset

Returns
  FALSE if not enough memory

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

References FALSE, locked, and NULL.

## ◆ dbus_message_set_serial()

DBUS_EXPORT void dbus_message_set_serial | ( | DBusMessage * | message,
|  | dbus_uint32_t | serial
| ) |  |

Sets the serial number of a message.

This can only be done once on a message.

DBusConnection will automatically set the serial to an appropriate value when the message is sent; this function is only needed when encapsulating messages in another protocol, or otherwise bypassing DBusConnection.

Parameters

  message | the message
  serial | the serial

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

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

## ◆ dbus_message_type_from_string()

DBUS_EXPORT int dbus_message_type_from_string | ( | const char * | type_str | ) |

Utility function to convert a machine-readable (not translated) string into a D-Bus message type.

"method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
"method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
"signal" -> DBUS_MESSAGE_TYPE_SIGNAL
"error" -> DBUS_MESSAGE_TYPE_ERROR
anything else -> DBUS_MESSAGE_TYPE_INVALID
DBUS_MESSAGE_TYPE_METHOD_CALL
#define DBUS_MESSAGE_TYPE_METHOD_CALL
Message type of a method call message, see dbus_message_get_type()
Definition: dbus-protocol.h:234
DBUS_MESSAGE_TYPE_ERROR
#define DBUS_MESSAGE_TYPE_ERROR
Message type of an error reply message, see dbus_message_get_type()
Definition: dbus-protocol.h:238
DBUS_MESSAGE_TYPE_METHOD_RETURN
#define DBUS_MESSAGE_TYPE_METHOD_RETURN
Message type of a method return message, see dbus_message_get_type()
Definition: dbus-protocol.h:236
DBUS_MESSAGE_TYPE_SIGNAL
#define DBUS_MESSAGE_TYPE_SIGNAL
Message type of a signal message, see dbus_message_get_type()
Definition: dbus-protocol.h:240
DBUS_MESSAGE_TYPE_INVALID
#define DBUS_MESSAGE_TYPE_INVALID
This value is never a valid message type, see dbus_message_get_type()
Definition: dbus-protocol.h:232

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

References DBUS_MESSAGE_TYPE_ERROR, DBUS_MESSAGE_TYPE_INVALID, DBUS_MESSAGE_TYPE_METHOD_CALL, DBUS_MESSAGE_TYPE_METHOD_RETURN, and DBUS_MESSAGE_TYPE_SIGNAL.

## ◆ dbus_message_type_to_string()

DBUS_EXPORT const char * dbus_message_type_to_string | ( | int | type | ) |

Utility function to convert a D-Bus message type into a machine-readable string (not translated).

DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
DBUS_MESSAGE_TYPE_ERROR -> "error"
DBUS_MESSAGE_TYPE_INVALID -> "invalid"

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

References DBUS_MESSAGE_TYPE_ERROR, DBUS_MESSAGE_TYPE_METHOD_CALL, DBUS_MESSAGE_TYPE_METHOD_RETURN, and DBUS_MESSAGE_TYPE_SIGNAL.

Referenced by _dbus_connection_message_sent_unlocked().

## ◆ dbus_message_unref()

DBUS_EXPORT void dbus_message_unref | ( | DBusMessage * | message | ) |

Decrements the reference count of a DBusMessage, freeing the message if the count reaches 0.

Parameters

  message | the message

See also
  dbus_message_ref

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

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

Referenced by _dbus_connection_unlock(), _dbus_message_loader_unref(), _dbus_pending_call_set_timeout_error_unlocked(), dbus_bus_add_match(), dbus_bus_get_id(), dbus_bus_get_unix_user(), dbus_bus_name_has_owner(), dbus_bus_release_name(), dbus_bus_remove_match(), dbus_bus_request_name(), dbus_bus_start_service_by_name(), and dbus_connection_send_with_reply_and_block().

## ◆ dbus_set_error_from_message()

DBUS_EXPORT 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;
dbus_set_error_from_message
dbus_bool_t dbus_set_error_from_message(DBusError *error, DBusMessage *message)
Sets a DBusError based on the contents of the given message.
Definition: dbus-message.c:4037

Parameters

  error | the error to set
  message | the message to set it from

Returns
  TRUE if the message had type DBUS_MESSAGE_TYPE_ERROR

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

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

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