1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 /* dbus-message.c DBusMessage object
4 * Copyright (C) 2002, 2003, 2004, 2005 Red Hat Inc.
5 * Copyright (C) 2002, 2003 CodeFactory AB
7 * Licensed under the Academic Free License version 2.1
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
26 #include "dbus-internals.h"
27 #include "dbus-marshal-recursive.h"
28 #include "dbus-marshal-validate.h"
29 #include "dbus-marshal-byteswap.h"
30 #include "dbus-marshal-header.h"
31 #include "dbus-signature.h"
32 #include "dbus-message-private.h"
33 #include "dbus-object-tree.h"
34 #include "dbus-memory.h"
35 #include "dbus-list.h"
36 #include "dbus-threads-internal.h"
38 #ifdef HAVE_UNIX_FD_PASSING
39 #include "dbus-sysdeps-unix.h"
44 #define _DBUS_TYPE_IS_STRINGLIKE(type) \
45 (type == DBUS_TYPE_STRING || type == DBUS_TYPE_SIGNATURE || \
46 type == DBUS_TYPE_OBJECT_PATH)
48 static void dbus_message_finalize (DBusMessage *message);
51 * @defgroup DBusMessageInternals DBusMessage implementation details
52 * @ingroup DBusInternals
53 * @brief DBusMessage private implementation details.
55 * The guts of DBusMessage and its methods.
60 #ifdef DBUS_ENABLE_EMBEDDED_TESTS
62 _dbus_enable_message_cache (void)
64 static int enabled = -1;
68 const char *s = _dbus_getenv ("DBUS_MESSAGE_CACHE");
79 _dbus_warn ("DBUS_MESSAGE_CACHE should be 0 or 1 if set, not '%s'",
87 /* constant expression, should be optimized away */
88 # define _dbus_enable_message_cache() (TRUE)
91 #ifndef _dbus_message_trace_ref
93 _dbus_message_trace_ref (DBusMessage *message,
98 static int enabled = -1;
100 _dbus_trace_ref ("DBusMessage", message, old_refcount, new_refcount, why,
101 "DBUS_MESSAGE_TRACE", &enabled);
105 /* Not thread locked, but strictly const/read-only so should be OK
107 /** An static string representing an empty signature */
108 _DBUS_STRING_DEFINE_STATIC(_dbus_empty_signature_str, "");
110 /* these have wacky values to help trap uninitialized iterators;
111 * but has to fit in 3 bits
114 DBUS_MESSAGE_ITER_TYPE_READER = 3,
115 DBUS_MESSAGE_ITER_TYPE_WRITER = 7
118 /** typedef for internals of message iterator */
119 typedef struct DBusMessageRealIter DBusMessageRealIter;
122 * @brief Internals of DBusMessageIter
124 * Object representing a position in a message. All fields are internal.
126 struct DBusMessageRealIter
128 DBusMessage *message; /**< Message used */
129 dbus_uint32_t changed_stamp : CHANGED_STAMP_BITS; /**< stamp to detect invalid iters */
130 dbus_uint32_t iter_type : 3; /**< whether this is a reader or writer iter */
131 dbus_uint32_t sig_refcount : 8; /**< depth of open_signature() */
134 DBusTypeWriter writer; /**< writer */
135 DBusTypeReader reader; /**< reader */
136 } u; /**< the type writer or reader that does all the work */
140 get_const_signature (DBusHeader *header,
141 const DBusString **type_str_p,
144 if (_dbus_header_get_field_raw (header,
145 DBUS_HEADER_FIELD_SIGNATURE,
149 *type_pos_p += 1; /* skip the signature length which is 1 byte */
153 *type_str_p = &_dbus_empty_signature_str;
159 * Swaps the message to compiler byte order if required
161 * @param message the message
164 _dbus_message_byteswap (DBusMessage *message)
166 const DBusString *type_str;
170 byte_order = _dbus_header_get_byte_order (&message->header);
172 if (byte_order == DBUS_COMPILER_BYTE_ORDER)
175 _dbus_verbose ("Swapping message into compiler byte order\n");
177 get_const_signature (&message->header, &type_str, &type_pos);
179 _dbus_marshal_byteswap (type_str, type_pos,
181 DBUS_COMPILER_BYTE_ORDER,
184 _dbus_header_byteswap (&message->header, DBUS_COMPILER_BYTE_ORDER);
185 _dbus_assert (_dbus_header_get_byte_order (&message->header) ==
186 DBUS_COMPILER_BYTE_ORDER);
189 /** byte-swap the message if it doesn't match our byte order.
190 * Called only when we need the message in our own byte order,
191 * normally when reading arrays of integers or doubles.
192 * Otherwise should not be called since it would do needless
195 #define ensure_byte_order(message) _dbus_message_byteswap (message)
198 * Gets the data to be sent over the network for this message.
199 * The header and then the body should be written out.
200 * This function is guaranteed to always return the same
201 * data once a message is locked (with dbus_message_lock()).
203 * @param message the message.
204 * @param header return location for message header data.
205 * @param body return location for message body data.
208 _dbus_message_get_network_data (DBusMessage *message,
209 const DBusString **header,
210 const DBusString **body)
212 _dbus_assert (message->locked);
214 *header = &message->header.data;
215 *body = &message->body;
219 * Gets the unix fds to be sent over the network for this message.
220 * This function is guaranteed to always return the same data once a
221 * message is locked (with dbus_message_lock()).
223 * @param message the message.
224 * @param fds return location of unix fd array
225 * @param n_fds return number of entries in array
227 void _dbus_message_get_unix_fds(DBusMessage *message,
231 _dbus_assert (message->locked);
233 #ifdef HAVE_UNIX_FD_PASSING
234 *fds = message->unix_fds;
235 *n_fds = message->n_unix_fds;
243 * Sets the serial number of a message.
244 * This can only be done once on a message.
246 * DBusConnection will automatically set the serial to an appropriate value
247 * when the message is sent; this function is only needed when encapsulating
248 * messages in another protocol, or otherwise bypassing DBusConnection.
250 * @param message the message
251 * @param serial the serial
254 dbus_message_set_serial (DBusMessage *message,
255 dbus_uint32_t serial)
257 _dbus_return_if_fail (message != NULL);
258 _dbus_return_if_fail (!message->locked);
260 _dbus_header_set_serial (&message->header, serial);
264 * Adds a counter to be incremented immediately with the size/unix fds
265 * of this message, and decremented by the size/unix fds of this
266 * message when this message if finalized. The link contains a
267 * counter with its refcount already incremented, but the counter
268 * itself not incremented. Ownership of link and counter refcount is
269 * passed to the message.
271 * This function may be called with locks held. As a result, the counter's
272 * notify function is not called; the caller is expected to either call
273 * _dbus_counter_notify() on the counter when they are no longer holding
274 * locks, or take the same action that would be taken by the notify function.
276 * @param message the message
277 * @param link link with counter as data
280 _dbus_message_add_counter_link (DBusMessage *message,
283 /* right now we don't recompute the delta when message
284 * size changes, and that's OK for current purposes
285 * I think, but could be important to change later.
286 * Do recompute it whenever there are no outstanding counters,
287 * since it's basically free.
289 if (message->counters == NULL)
291 message->size_counter_delta =
292 _dbus_string_get_length (&message->header.data) +
293 _dbus_string_get_length (&message->body);
295 #ifdef HAVE_UNIX_FD_PASSING
296 message->unix_fd_counter_delta = message->n_unix_fds;
300 _dbus_verbose ("message has size %ld\n",
301 message->size_counter_delta);
305 _dbus_list_append_link (&message->counters, link);
307 _dbus_counter_adjust_size (link->data, message->size_counter_delta);
309 #ifdef HAVE_UNIX_FD_PASSING
310 _dbus_counter_adjust_unix_fd (link->data, message->unix_fd_counter_delta);
315 * Adds a counter to be incremented immediately with the size/unix fds
316 * of this message, and decremented by the size/unix fds of this
317 * message when this message if finalized.
319 * This function may be called with locks held. As a result, the counter's
320 * notify function is not called; the caller is expected to either call
321 * _dbus_counter_notify() on the counter when they are no longer holding
322 * locks, or take the same action that would be taken by the notify function.
324 * @param message the message
325 * @param counter the counter
326 * @returns #FALSE if no memory
329 _dbus_message_add_counter (DBusMessage *message,
330 DBusCounter *counter)
334 link = _dbus_list_alloc_link (counter);
338 _dbus_counter_ref (counter);
339 _dbus_message_add_counter_link (message, link);
345 * Removes a counter tracking the size/unix fds of this message, and
346 * decrements the counter by the size/unix fds of this message.
348 * @param message the message
349 * @param counter the counter
352 _dbus_message_remove_counter (DBusMessage *message,
353 DBusCounter *counter)
357 link = _dbus_list_find_last (&message->counters,
359 _dbus_assert (link != NULL);
361 _dbus_list_remove_link (&message->counters, link);
363 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
365 #ifdef HAVE_UNIX_FD_PASSING
366 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
369 _dbus_counter_notify (counter);
370 _dbus_counter_unref (counter);
374 * Locks a message. Allows checking that applications don't keep a
375 * reference to a message in the outgoing queue and change it
376 * underneath us. Messages are locked when they enter the outgoing
377 * queue (dbus_connection_send_message()), and the library complains
378 * if the message is modified while locked. This function may also
379 * called externally, for applications wrapping D-Bus in another protocol.
381 * @param message the message to lock.
384 dbus_message_lock (DBusMessage *message)
386 if (!message->locked)
388 _dbus_header_update_lengths (&message->header,
389 _dbus_string_get_length (&message->body));
391 /* must have a signature if you have a body */
392 _dbus_assert (_dbus_string_get_length (&message->body) == 0 ||
393 dbus_message_get_signature (message) != NULL);
395 message->locked = TRUE;
399 #ifdef ENABLE_KDBUS_TRANSPORT
401 dbus_message_unlock (DBusMessage *message)
403 message->locked = FALSE;
408 set_or_delete_string_field (DBusMessage *message,
414 return _dbus_header_delete_field (&message->header, field);
416 return _dbus_header_set_field_basic (&message->header,
423 /* Probably we don't need to use this */
425 * Sets the signature of the message, i.e. the arguments in the
426 * message payload. The signature includes only "in" arguments for
427 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
428 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
429 * what you might expect (it does not include the signature of the
430 * entire C++-style method).
432 * The signature is a string made up of type codes such as
433 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
434 * the value of #DBUS_TYPE_INVALID). The macros such as
435 * #DBUS_TYPE_INT32 evaluate to integers; to assemble a signature you
436 * may find it useful to use the string forms, such as
437 * #DBUS_TYPE_INT32_AS_STRING.
439 * An "unset" or #NULL signature is considered the same as an empty
440 * signature. In fact dbus_message_get_signature() will never return
443 * @param message the message
444 * @param signature the type signature or #NULL to unset
445 * @returns #FALSE if no memory
448 _dbus_message_set_signature (DBusMessage *message,
449 const char *signature)
451 _dbus_return_val_if_fail (message != NULL, FALSE);
452 _dbus_return_val_if_fail (!message->locked, FALSE);
453 _dbus_return_val_if_fail (signature == NULL ||
454 _dbus_check_is_valid_signature (signature));
455 /* can't delete the signature if you have a message body */
456 _dbus_return_val_if_fail (_dbus_string_get_length (&message->body) == 0 ||
459 return set_or_delete_string_field (message,
460 DBUS_HEADER_FIELD_SIGNATURE,
468 * We cache some DBusMessage to reduce the overhead of allocating
469 * them. In my profiling this consistently made about an 8%
470 * difference. It avoids the malloc for the message, the malloc for
471 * the slot list, the malloc for the header string and body string,
472 * and the associated free() calls. It does introduce another global
473 * lock which could be a performance issue in certain cases.
475 * For the echo client/server the round trip time goes from around
476 * .000077 to .000069 with the message cache on my laptop. The sysprof
477 * change is as follows (numbers are cumulative percentage):
479 * with message cache implemented as array as it is now (0.000069 per):
480 * new_empty_header 1.46
481 * mutex_lock 0.56 # i.e. _DBUS_LOCK(message_cache)
487 * mutex_lock 0.33 # i.e. _DBUS_LOCK(message_cache)
490 * with message cache implemented as list (0.000070 per roundtrip):
491 * new_empty_header 2.72
492 * list_pop_first 1.88
496 * without cache (0.000077 per roundtrip):
497 * new_empty_header 6.7
498 * string_init_preallocated 3.43
507 * If you implement the message_cache with a list, the primary reason
508 * it's slower is that you add another thread lock (on the DBusList
512 /** Avoid caching huge messages */
513 #define MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE
515 /** Avoid caching too many messages */
516 #define MAX_MESSAGE_CACHE_SIZE 5
518 /* Protected by _DBUS_LOCK (message_cache) */
519 static DBusMessage *message_cache[MAX_MESSAGE_CACHE_SIZE];
520 static int message_cache_count = 0;
521 static dbus_bool_t message_cache_shutdown_registered = FALSE;
524 dbus_message_cache_shutdown (void *data)
528 if (!_DBUS_LOCK (message_cache))
529 _dbus_assert_not_reached ("we would have initialized global locks "
530 "before registering a shutdown function");
533 while (i < MAX_MESSAGE_CACHE_SIZE)
535 if (message_cache[i])
536 dbus_message_finalize (message_cache[i]);
541 message_cache_count = 0;
542 message_cache_shutdown_registered = FALSE;
544 _DBUS_UNLOCK (message_cache);
548 * Tries to get a message from the message cache. The retrieved
549 * message will have junk in it, so it still needs to be cleared out
550 * in dbus_message_new_empty_header()
552 * @returns the message, or #NULL if none cached
555 dbus_message_get_cached (void)
557 DBusMessage *message;
562 if (!_DBUS_LOCK (message_cache))
564 /* we'd have initialized global locks before caching anything,
565 * so there can't be anything in the cache */
569 _dbus_assert (message_cache_count >= 0);
571 if (message_cache_count == 0)
573 _DBUS_UNLOCK (message_cache);
577 /* This is not necessarily true unless count > 0, and
578 * message_cache is uninitialized until the shutdown is
581 _dbus_assert (message_cache_shutdown_registered);
584 while (i < MAX_MESSAGE_CACHE_SIZE)
586 if (message_cache[i])
588 message = message_cache[i];
589 message_cache[i] = NULL;
590 message_cache_count -= 1;
595 _dbus_assert (message_cache_count >= 0);
596 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
597 _dbus_assert (message != NULL);
599 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
601 _dbus_assert (message->counters == NULL);
603 _DBUS_UNLOCK (message_cache);
608 #ifdef HAVE_UNIX_FD_PASSING
610 close_unix_fds(int *fds, unsigned *n_fds)
620 for (i = 0; i < *n_fds; i++)
622 if (!_dbus_close(fds[i], &e))
624 _dbus_warn("Failed to close file descriptor: %s\n", e.message);
631 /* We don't free the array here, in case we can recycle it later */
636 free_counter (void *element,
639 DBusCounter *counter = element;
640 DBusMessage *message = data;
642 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
643 #ifdef HAVE_UNIX_FD_PASSING
644 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
647 _dbus_counter_notify (counter);
648 _dbus_counter_unref (counter);
652 * Tries to cache a message, otherwise finalize it.
654 * @param message the message
657 dbus_message_cache_or_finalize (DBusMessage *message)
659 dbus_bool_t was_cached;
662 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
664 /* This calls application code and has to be done first thing
665 * without holding the lock
667 _dbus_data_slot_list_clear (&message->slot_list);
669 _dbus_list_foreach (&message->counters,
670 free_counter, message);
671 _dbus_list_clear (&message->counters);
673 #ifdef HAVE_UNIX_FD_PASSING
674 close_unix_fds(message->unix_fds, &message->n_unix_fds);
679 if (!_DBUS_LOCK (message_cache))
681 /* The only way to get a non-null message goes through
682 * dbus_message_get_cached() which takes the lock. */
683 _dbus_assert_not_reached ("we would have initialized global locks "
684 "the first time we constructed a message");
687 if (!message_cache_shutdown_registered)
689 _dbus_assert (message_cache_count == 0);
691 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
695 while (i < MAX_MESSAGE_CACHE_SIZE)
697 message_cache[i] = NULL;
701 message_cache_shutdown_registered = TRUE;
704 _dbus_assert (message_cache_count >= 0);
706 if (!_dbus_enable_message_cache ())
709 if ((_dbus_string_get_length (&message->header.data) +
710 _dbus_string_get_length (&message->body)) >
711 MAX_MESSAGE_SIZE_TO_CACHE)
714 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
717 /* Find empty slot */
719 while (message_cache[i] != NULL)
722 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
724 _dbus_assert (message_cache[i] == NULL);
725 message_cache[i] = message;
726 message_cache_count += 1;
728 #ifndef DBUS_DISABLE_CHECKS
729 message->in_cache = TRUE;
733 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
735 _DBUS_UNLOCK (message_cache);
738 dbus_message_finalize (message);
741 #if defined(DBUS_ENABLE_CHECKS) || defined(DBUS_ENABLE_ASSERT)
743 _dbus_message_iter_check (DBusMessageRealIter *iter)
749 _dbus_warn_check_failed ("dbus message iterator is NULL\n");
753 byte_order = _dbus_header_get_byte_order (&iter->message->header);
755 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
757 if (iter->u.reader.byte_order != byte_order)
759 _dbus_warn_check_failed ("dbus message changed byte order since iterator was created\n");
762 /* because we swap the message into compiler order when you init an iter */
763 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
765 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
767 if (iter->u.writer.byte_order != byte_order)
769 _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created\n");
772 /* because we swap the message into compiler order when you init an iter */
773 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
777 _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted\n");
781 if (iter->changed_stamp != iter->message->changed_stamp)
783 _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
789 #endif /* DBUS_ENABLE_CHECKS || DBUS_ENABLE_ASSERT */
792 * Implementation of the varargs arg-getting functions.
793 * dbus_message_get_args() is the place to go for complete
796 * @todo This may leak memory and file descriptors if parsing fails. See #21259
798 * @see dbus_message_get_args
799 * @param iter the message iter
800 * @param error error to be filled in
801 * @param first_arg_type type of the first argument
802 * @param var_args return location for first argument, followed by list of type/location pairs
803 * @returns #FALSE if error was set
806 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
811 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
812 int spec_type, msg_type, i;
815 _dbus_assert (_dbus_message_iter_check (real));
819 spec_type = first_arg_type;
822 while (spec_type != DBUS_TYPE_INVALID)
824 msg_type = dbus_message_iter_get_arg_type (iter);
826 if (msg_type != spec_type)
828 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
829 "Argument %d is specified to be of type \"%s\", but "
830 "is actually of type \"%s\"\n", i,
831 _dbus_type_to_string (spec_type),
832 _dbus_type_to_string (msg_type));
837 if (spec_type == DBUS_TYPE_UNIX_FD)
839 #ifdef HAVE_UNIX_FD_PASSING
843 pfd = va_arg (var_args, int*);
846 _dbus_type_reader_read_basic(&real->u.reader, &idx);
848 if (idx.u32 >= real->message->n_unix_fds)
850 dbus_set_error (error, DBUS_ERROR_INCONSISTENT_MESSAGE,
851 "Message refers to file descriptor at index %i,"
852 "but has only %i descriptors attached.\n",
854 real->message->n_unix_fds);
858 if ((nfd = _dbus_dup(real->message->unix_fds[idx.u32], error)) < 0)
863 dbus_set_error (error, DBUS_ERROR_NOT_SUPPORTED,
864 "Platform does not support file desciptor passing.\n");
868 else if (dbus_type_is_basic (spec_type))
872 ptr = va_arg (var_args, DBusBasicValue*);
874 _dbus_assert (ptr != NULL);
876 _dbus_type_reader_read_basic (&real->u.reader,
879 else if (spec_type == DBUS_TYPE_ARRAY)
882 int spec_element_type;
883 const DBusBasicValue **ptr;
885 DBusTypeReader array;
887 spec_element_type = va_arg (var_args, int);
888 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
890 if (spec_element_type != element_type)
892 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
893 "Argument %d is specified to be an array of \"%s\", but "
894 "is actually an array of \"%s\"\n",
896 _dbus_type_to_string (spec_element_type),
897 _dbus_type_to_string (element_type));
902 if (dbus_type_is_fixed (spec_element_type) &&
903 element_type != DBUS_TYPE_UNIX_FD)
905 ptr = va_arg (var_args, const DBusBasicValue**);
906 n_elements_p = va_arg (var_args, int*);
908 _dbus_assert (ptr != NULL);
909 _dbus_assert (n_elements_p != NULL);
911 _dbus_type_reader_recurse (&real->u.reader, &array);
913 _dbus_type_reader_read_fixed_multi (&array,
914 (void *) ptr, n_elements_p);
916 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
922 str_array_p = va_arg (var_args, char***);
923 n_elements_p = va_arg (var_args, int*);
925 _dbus_assert (str_array_p != NULL);
926 _dbus_assert (n_elements_p != NULL);
928 /* Count elements in the array */
929 _dbus_type_reader_recurse (&real->u.reader, &array);
932 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
935 _dbus_type_reader_next (&array);
938 str_array = dbus_new0 (char*, n_elements + 1);
939 if (str_array == NULL)
941 _DBUS_SET_OOM (error);
945 /* Now go through and dup each string */
946 _dbus_type_reader_recurse (&real->u.reader, &array);
949 while (i < n_elements)
952 _dbus_type_reader_read_basic (&array,
955 str_array[i] = _dbus_strdup (s);
956 if (str_array[i] == NULL)
958 dbus_free_string_array (str_array);
959 _DBUS_SET_OOM (error);
965 if (!_dbus_type_reader_next (&array))
966 _dbus_assert (i == n_elements);
969 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
970 _dbus_assert (i == n_elements);
971 _dbus_assert (str_array[i] == NULL);
973 *str_array_p = str_array;
974 *n_elements_p = n_elements;
976 #ifndef DBUS_DISABLE_CHECKS
979 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
980 _DBUS_FUNCTION_NAME);
985 #ifndef DBUS_DISABLE_CHECKS
988 _dbus_warn ("you can only read arrays and basic types with %s for now\n",
989 _DBUS_FUNCTION_NAME);
994 spec_type = va_arg (var_args, int);
995 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
997 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
998 "Message has only %d arguments, but more were expected", i);
1015 * @defgroup DBusMessage DBusMessage
1017 * @brief Message to be sent or received over a #DBusConnection.
1019 * A DBusMessage is the most basic unit of communication over a
1020 * DBusConnection. A DBusConnection represents a stream of messages
1021 * received from a remote application, and a stream of messages
1022 * sent to a remote application.
1024 * A message has a message type, returned from
1025 * dbus_message_get_type(). This indicates whether the message is a
1026 * method call, a reply to a method call, a signal, or an error reply.
1028 * A message has header fields such as the sender, destination, method
1029 * or signal name, and so forth. DBusMessage has accessor functions for
1030 * these, such as dbus_message_get_member().
1032 * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
1033 * and dbus_message_is_error() check several header fields at once and are
1034 * slightly more efficient than checking the header fields with individual
1035 * accessor functions.
1037 * Finally, a message has arguments. The number and types of arguments
1038 * are in the message's signature header field (accessed with
1039 * dbus_message_get_signature()). Simple argument values are usually
1040 * retrieved with dbus_message_get_args() but more complex values such
1041 * as structs may require the use of #DBusMessageIter.
1043 * The D-Bus specification goes into some more detail about header fields and
1050 * @typedef DBusMessage
1052 * Opaque data type representing a message received from or to be
1053 * sent to another application.
1057 * Returns the serial of a message or 0 if none has been specified.
1058 * The message's serial number is provided by the application sending
1059 * the message and is used to identify replies to this message.
1061 * All messages received on a connection will have a serial provided
1062 * by the remote application.
1064 * For messages you're sending, dbus_connection_send() will assign a
1065 * serial and return it to you.
1067 * @param message the message
1068 * @returns the serial
1071 dbus_message_get_serial (DBusMessage *message)
1073 _dbus_return_val_if_fail (message != NULL, 0);
1075 return _dbus_header_get_serial (&message->header);
1079 * Sets the reply serial of a message (the serial of the message this
1082 * @param message the message
1083 * @param reply_serial the serial we're replying to
1084 * @returns #FALSE if not enough memory
1087 dbus_message_set_reply_serial (DBusMessage *message,
1088 dbus_uint32_t reply_serial)
1090 _dbus_return_val_if_fail (message != NULL, FALSE);
1091 _dbus_return_val_if_fail (!message->locked, FALSE);
1092 _dbus_return_val_if_fail (reply_serial != 0, FALSE); /* 0 is invalid */
1094 return _dbus_header_set_field_basic (&message->header,
1095 DBUS_HEADER_FIELD_REPLY_SERIAL,
1101 * Returns the serial that the message is a reply to or 0 if none.
1103 * @param message the message
1104 * @returns the reply serial
1107 dbus_message_get_reply_serial (DBusMessage *message)
1109 dbus_uint32_t v_UINT32;
1111 _dbus_return_val_if_fail (message != NULL, 0);
1113 if (_dbus_header_get_field_basic (&message->header,
1114 DBUS_HEADER_FIELD_REPLY_SERIAL,
1123 dbus_message_finalize (DBusMessage *message)
1125 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1127 /* This calls application callbacks! */
1128 _dbus_data_slot_list_free (&message->slot_list);
1130 _dbus_list_foreach (&message->counters,
1131 free_counter, message);
1132 _dbus_list_clear (&message->counters);
1134 _dbus_header_free (&message->header);
1135 _dbus_string_free (&message->body);
1137 #ifdef HAVE_UNIX_FD_PASSING
1138 close_unix_fds(message->unix_fds, &message->n_unix_fds);
1139 dbus_free(message->unix_fds);
1142 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1144 dbus_free (message);
1148 dbus_message_new_empty_header (void)
1150 DBusMessage *message;
1151 dbus_bool_t from_cache;
1153 message = dbus_message_get_cached ();
1155 if (message != NULL)
1162 message = dbus_new0 (DBusMessage, 1);
1163 if (message == NULL)
1165 #ifndef DBUS_DISABLE_CHECKS
1166 message->generation = _dbus_current_generation;
1169 #ifdef HAVE_UNIX_FD_PASSING
1170 message->unix_fds = NULL;
1171 message->n_unix_fds_allocated = 0;
1175 _dbus_atomic_inc (&message->refcount);
1177 _dbus_message_trace_ref (message, 0, 1, "new_empty_header");
1179 message->locked = FALSE;
1180 #ifndef DBUS_DISABLE_CHECKS
1181 message->in_cache = FALSE;
1183 message->counters = NULL;
1184 message->size_counter_delta = 0;
1185 message->changed_stamp = 0;
1187 #ifdef HAVE_UNIX_FD_PASSING
1188 message->n_unix_fds = 0;
1189 message->n_unix_fds_allocated = 0;
1190 message->unix_fd_counter_delta = 0;
1194 _dbus_data_slot_list_init (&message->slot_list);
1198 _dbus_header_reinit (&message->header);
1199 _dbus_string_set_length (&message->body, 0);
1203 if (!_dbus_header_init (&message->header))
1205 dbus_free (message);
1209 if (!_dbus_string_init_preallocated (&message->body, 32))
1211 _dbus_header_free (&message->header);
1212 dbus_free (message);
1221 * Constructs a new message of the given message type.
1222 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
1223 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
1225 * Usually you want to use dbus_message_new_method_call(),
1226 * dbus_message_new_method_return(), dbus_message_new_signal(),
1227 * or dbus_message_new_error() instead.
1229 * @param message_type type of message
1230 * @returns new message or #NULL if no memory
1233 dbus_message_new (int message_type)
1235 DBusMessage *message;
1237 _dbus_return_val_if_fail (message_type != DBUS_MESSAGE_TYPE_INVALID, NULL);
1239 message = dbus_message_new_empty_header ();
1240 if (message == NULL)
1243 if (!_dbus_header_create (&message->header,
1244 DBUS_COMPILER_BYTE_ORDER,
1246 NULL, NULL, NULL, NULL, NULL))
1248 dbus_message_unref (message);
1256 * Constructs a new message to invoke a method on a remote
1257 * object. Returns #NULL if memory can't be allocated for the
1258 * message. The destination may be #NULL in which case no destination
1259 * is set; this is appropriate when using D-Bus in a peer-to-peer
1260 * context (no message bus). The interface may be #NULL, which means
1261 * that if multiple methods with the given name exist it is undefined
1262 * which one will be invoked.
1264 * The path and method names may not be #NULL.
1266 * Destination, path, interface, and method name can't contain
1267 * any invalid characters (see the D-Bus specification).
1269 * @param destination name that the message should be sent to or #NULL
1270 * @param path object path the message should be sent to
1271 * @param iface interface to invoke method on, or #NULL
1272 * @param method method to invoke
1274 * @returns a new DBusMessage, free with dbus_message_unref()
1277 dbus_message_new_method_call (const char *destination,
1282 DBusMessage *message;
1284 _dbus_return_val_if_fail (path != NULL, NULL);
1285 _dbus_return_val_if_fail (method != NULL, NULL);
1286 _dbus_return_val_if_fail (destination == NULL ||
1287 _dbus_check_is_valid_bus_name (destination), NULL);
1288 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1289 _dbus_return_val_if_fail (iface == NULL ||
1290 _dbus_check_is_valid_interface (iface), NULL);
1291 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
1293 message = dbus_message_new_empty_header ();
1294 if (message == NULL)
1297 if (!_dbus_header_create (&message->header,
1298 DBUS_COMPILER_BYTE_ORDER,
1299 DBUS_MESSAGE_TYPE_METHOD_CALL,
1300 destination, path, iface, method, NULL))
1302 dbus_message_unref (message);
1310 * Constructs a message that is a reply to a method call. Returns
1311 * #NULL if memory can't be allocated for the message.
1313 * @param method_call the message being replied to
1314 * @returns a new DBusMessage, free with dbus_message_unref()
1317 dbus_message_new_method_return (DBusMessage *method_call)
1319 DBusMessage *message;
1322 _dbus_return_val_if_fail (method_call != NULL, NULL);
1324 sender = dbus_message_get_sender (method_call);
1326 /* sender is allowed to be null here in peer-to-peer case */
1328 message = dbus_message_new_empty_header ();
1329 if (message == NULL)
1332 if (!_dbus_header_create (&message->header,
1333 DBUS_COMPILER_BYTE_ORDER,
1334 DBUS_MESSAGE_TYPE_METHOD_RETURN,
1335 sender, NULL, NULL, NULL, NULL))
1337 dbus_message_unref (message);
1341 dbus_message_set_no_reply (message, TRUE);
1343 if (!dbus_message_set_reply_serial (message,
1344 dbus_message_get_serial (method_call)))
1346 dbus_message_unref (message);
1354 * Constructs a new message representing a signal emission. Returns
1355 * #NULL if memory can't be allocated for the message. A signal is
1356 * identified by its originating object path, interface, and the name
1359 * Path, interface, and signal name must all be valid (the D-Bus
1360 * specification defines the syntax of these fields).
1362 * @param path the path to the object emitting the signal
1363 * @param iface the interface the signal is emitted from
1364 * @param name name of the signal
1365 * @returns a new DBusMessage, free with dbus_message_unref()
1368 dbus_message_new_signal (const char *path,
1372 DBusMessage *message;
1374 _dbus_return_val_if_fail (path != NULL, NULL);
1375 _dbus_return_val_if_fail (iface != NULL, NULL);
1376 _dbus_return_val_if_fail (name != NULL, NULL);
1377 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1378 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (iface), NULL);
1379 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
1381 message = dbus_message_new_empty_header ();
1382 if (message == NULL)
1385 if (!_dbus_header_create (&message->header,
1386 DBUS_COMPILER_BYTE_ORDER,
1387 DBUS_MESSAGE_TYPE_SIGNAL,
1388 NULL, path, iface, name, NULL))
1390 dbus_message_unref (message);
1394 dbus_message_set_no_reply (message, TRUE);
1400 * Creates a new message that is an error reply to another message.
1401 * Error replies are most common in response to method calls, but
1402 * can be returned in reply to any message.
1404 * The error name must be a valid error name according to the syntax
1405 * given in the D-Bus specification. If you don't want to make
1406 * up an error name just use #DBUS_ERROR_FAILED.
1408 * @param reply_to the message we're replying to
1409 * @param error_name the error name
1410 * @param error_message the error message string (or #NULL for none, but please give a message)
1411 * @returns a new error message object, free with dbus_message_unref()
1414 dbus_message_new_error (DBusMessage *reply_to,
1415 const char *error_name,
1416 const char *error_message)
1418 DBusMessage *message;
1420 DBusMessageIter iter;
1422 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1423 _dbus_return_val_if_fail (error_name != NULL, NULL);
1424 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1426 sender = dbus_message_get_sender (reply_to);
1428 /* sender may be NULL for non-message-bus case or
1429 * when the message bus is dealing with an unregistered
1432 message = dbus_message_new_empty_header ();
1433 if (message == NULL)
1436 if (!_dbus_header_create (&message->header,
1437 DBUS_COMPILER_BYTE_ORDER,
1438 DBUS_MESSAGE_TYPE_ERROR,
1439 sender, NULL, NULL, NULL, error_name))
1441 dbus_message_unref (message);
1445 dbus_message_set_no_reply (message, TRUE);
1447 if (!dbus_message_set_reply_serial (message,
1448 dbus_message_get_serial (reply_to)))
1450 dbus_message_unref (message);
1454 if (error_message != NULL)
1456 dbus_message_iter_init_append (message, &iter);
1457 if (!dbus_message_iter_append_basic (&iter,
1461 dbus_message_unref (message);
1470 * Creates a new message that is an error reply to another message, allowing
1471 * you to use printf formatting.
1473 * See dbus_message_new_error() for details - this function is the same
1474 * aside from the printf formatting.
1476 * @todo add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to
1477 * public header, see DBUS_DEPRECATED for an example)
1479 * @param reply_to the original message
1480 * @param error_name the error name
1481 * @param error_format the error message format as with printf
1482 * @param ... format string arguments
1483 * @returns a new error message
1486 dbus_message_new_error_printf (DBusMessage *reply_to,
1487 const char *error_name,
1488 const char *error_format,
1493 DBusMessage *message;
1495 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1496 _dbus_return_val_if_fail (error_name != NULL, NULL);
1497 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1499 if (!_dbus_string_init (&str))
1502 va_start (args, error_format);
1504 if (_dbus_string_append_printf_valist (&str, error_format, args))
1505 message = dbus_message_new_error (reply_to, error_name,
1506 _dbus_string_get_const_data (&str));
1510 _dbus_string_free (&str);
1519 * Creates a new message that is an exact replica of the message
1520 * specified, except that its refcount is set to 1, its message serial
1521 * is reset to 0, and if the original message was "locked" (in the
1522 * outgoing message queue and thus not modifiable) the new message
1523 * will not be locked.
1525 * @todo This function can't be used in programs that try to recover from OOM errors.
1527 * @param message the message
1528 * @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.
1531 dbus_message_copy (const DBusMessage *message)
1533 DBusMessage *retval;
1535 _dbus_return_val_if_fail (message != NULL, NULL);
1537 retval = dbus_new0 (DBusMessage, 1);
1541 _dbus_atomic_inc (&retval->refcount);
1543 retval->locked = FALSE;
1544 #ifndef DBUS_DISABLE_CHECKS
1545 retval->generation = message->generation;
1548 if (!_dbus_header_copy (&message->header, &retval->header))
1554 if (!_dbus_string_init_preallocated (&retval->body,
1555 _dbus_string_get_length (&message->body)))
1557 _dbus_header_free (&retval->header);
1562 if (!_dbus_string_copy (&message->body, 0,
1566 #ifdef HAVE_UNIX_FD_PASSING
1567 retval->unix_fds = dbus_new(int, message->n_unix_fds);
1568 if (retval->unix_fds == NULL && message->n_unix_fds > 0)
1571 retval->n_unix_fds_allocated = message->n_unix_fds;
1573 for (retval->n_unix_fds = 0;
1574 retval->n_unix_fds < message->n_unix_fds;
1575 retval->n_unix_fds++)
1577 retval->unix_fds[retval->n_unix_fds] = _dbus_dup(message->unix_fds[retval->n_unix_fds], NULL);
1579 if (retval->unix_fds[retval->n_unix_fds] < 0)
1585 _dbus_message_trace_ref (retval, 0, 1, "copy");
1589 _dbus_header_free (&retval->header);
1590 _dbus_string_free (&retval->body);
1592 #ifdef HAVE_UNIX_FD_PASSING
1593 close_unix_fds(retval->unix_fds, &retval->n_unix_fds);
1594 dbus_free(retval->unix_fds);
1604 * Increments the reference count of a DBusMessage.
1606 * @param message the message
1607 * @returns the message
1608 * @see dbus_message_unref
1611 dbus_message_ref (DBusMessage *message)
1613 dbus_int32_t old_refcount;
1615 _dbus_return_val_if_fail (message != NULL, NULL);
1616 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1617 _dbus_return_val_if_fail (!message->in_cache, NULL);
1619 old_refcount = _dbus_atomic_inc (&message->refcount);
1620 _dbus_assert (old_refcount >= 1);
1621 _dbus_message_trace_ref (message, old_refcount, old_refcount + 1, "ref");
1627 * Decrements the reference count of a DBusMessage, freeing the
1628 * message if the count reaches 0.
1630 * @param message the message
1631 * @see dbus_message_ref
1634 dbus_message_unref (DBusMessage *message)
1636 dbus_int32_t old_refcount;
1638 _dbus_return_if_fail (message != NULL);
1639 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1640 _dbus_return_if_fail (!message->in_cache);
1642 old_refcount = _dbus_atomic_dec (&message->refcount);
1644 _dbus_assert (old_refcount >= 1);
1646 _dbus_message_trace_ref (message, old_refcount, old_refcount - 1, "unref");
1648 if (old_refcount == 1)
1650 /* Calls application callbacks! */
1651 dbus_message_cache_or_finalize (message);
1656 * Gets the type of a message. Types include
1657 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1658 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1659 * types are allowed and all code must silently ignore messages of
1660 * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
1662 * @param message the message
1663 * @returns the type of the message
1666 dbus_message_get_type (DBusMessage *message)
1668 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1670 return _dbus_header_get_message_type (&message->header);
1674 * Appends fields to a message given a variable argument list. The
1675 * variable argument list should contain the type of each argument
1676 * followed by the value to append. Appendable types are basic types,
1677 * and arrays of fixed-length basic types (except arrays of Unix file
1678 * descriptors). To append variable-length basic types, or any more
1679 * complex value, you have to use an iterator rather than this
1682 * To append a basic type, specify its type code followed by the
1683 * address of the value. For example:
1687 * dbus_int32_t v_INT32 = 42;
1688 * const char *v_STRING = "Hello World";
1689 * dbus_message_append_args (message,
1690 * DBUS_TYPE_INT32, &v_INT32,
1691 * DBUS_TYPE_STRING, &v_STRING,
1692 * DBUS_TYPE_INVALID);
1695 * To append an array of fixed-length basic types (except Unix file
1696 * descriptors), pass in the DBUS_TYPE_ARRAY typecode, the element
1697 * typecode, the address of the array pointer, and a 32-bit integer
1698 * giving the number of elements in the array. So for example: @code
1699 * const dbus_int32_t array[] = { 1, 2, 3 }; const dbus_int32_t
1700 * *v_ARRAY = array; dbus_message_append_args (message,
1701 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3, DBUS_TYPE_INVALID);
1704 * This function does not support arrays of Unix file descriptors. If
1705 * you need those you need to manually recurse into the array.
1707 * For Unix file descriptors this function will internally duplicate
1708 * the descriptor you passed in. Hence you may close the descriptor
1709 * immediately after this call.
1711 * @warning in C, given "int array[]", "&array == array" (the
1712 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
1713 * So if you're using an array instead of a pointer you have to create
1714 * a pointer variable, assign the array to it, then take the address
1715 * of the pointer variable. For strings it works to write
1716 * const char *array = "Hello" and then use &array though.
1718 * The last argument to this function must be #DBUS_TYPE_INVALID,
1719 * marking the end of the argument list. If you don't do this
1720 * then libdbus won't know to stop and will read invalid memory.
1722 * String/signature/path arrays should be passed in as "const char***
1723 * address_of_array" and "int n_elements"
1725 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1727 * @todo If this fails due to lack of memory, the message is hosed and
1728 * you have to start over building the whole message.
1730 * @param message the message
1731 * @param first_arg_type type of the first argument
1732 * @param ... value of first argument, list of additional type-value pairs
1733 * @returns #TRUE on success
1736 dbus_message_append_args (DBusMessage *message,
1743 _dbus_return_val_if_fail (message != NULL, FALSE);
1745 va_start (var_args, first_arg_type);
1746 retval = dbus_message_append_args_valist (message,
1755 * Like dbus_message_append_args() but takes a va_list for use by language bindings.
1757 * @todo for now, if this function fails due to OOM it will leave
1758 * the message half-written and you have to discard the message
1761 * @see dbus_message_append_args.
1762 * @param message the message
1763 * @param first_arg_type type of first argument
1764 * @param var_args value of first argument, then list of type/value pairs
1765 * @returns #TRUE on success
1768 dbus_message_append_args_valist (DBusMessage *message,
1773 DBusMessageIter iter;
1775 _dbus_return_val_if_fail (message != NULL, FALSE);
1777 type = first_arg_type;
1779 dbus_message_iter_init_append (message, &iter);
1781 while (type != DBUS_TYPE_INVALID)
1783 if (dbus_type_is_basic (type))
1785 const DBusBasicValue *value;
1786 value = va_arg (var_args, const DBusBasicValue*);
1788 if (!dbus_message_iter_append_basic (&iter,
1793 else if (type == DBUS_TYPE_ARRAY)
1796 DBusMessageIter array;
1799 element_type = va_arg (var_args, int);
1801 buf[0] = element_type;
1803 if (!dbus_message_iter_open_container (&iter,
1809 if (dbus_type_is_fixed (element_type) &&
1810 element_type != DBUS_TYPE_UNIX_FD)
1812 const DBusBasicValue **value;
1815 value = va_arg (var_args, const DBusBasicValue**);
1816 n_elements = va_arg (var_args, int);
1818 if (!dbus_message_iter_append_fixed_array (&array,
1822 dbus_message_iter_abandon_container (&iter, &array);
1826 else if (_DBUS_TYPE_IS_STRINGLIKE (element_type))
1828 const char ***value_p;
1833 value_p = va_arg (var_args, const char***);
1834 n_elements = va_arg (var_args, int);
1839 while (i < n_elements)
1841 if (!dbus_message_iter_append_basic (&array,
1844 dbus_message_iter_abandon_container (&iter, &array);
1852 _dbus_warn ("arrays of %s can't be appended with %s for now\n",
1853 _dbus_type_to_string (element_type),
1854 _DBUS_FUNCTION_NAME);
1858 if (!dbus_message_iter_close_container (&iter, &array))
1861 #ifndef DBUS_DISABLE_CHECKS
1864 _dbus_warn ("type %s isn't supported yet in %s\n",
1865 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
1870 type = va_arg (var_args, int);
1880 * Gets arguments from a message given a variable argument list. The
1881 * supported types include those supported by
1882 * dbus_message_append_args(); that is, basic types and arrays of
1883 * fixed-length basic types. The arguments are the same as they would
1884 * be for dbus_message_iter_get_basic() or
1885 * dbus_message_iter_get_fixed_array().
1887 * In addition to those types, arrays of string, object path, and
1888 * signature are supported; but these are returned as allocated memory
1889 * and must be freed with dbus_free_string_array(), while the other
1890 * types are returned as const references. To get a string array
1891 * pass in "char ***array_location" and "int *n_elements".
1893 * Similar to dbus_message_get_fixed_array() this function does not
1894 * support arrays of type DBUS_TYPE_UNIX_FD. If you need to parse
1895 * messages with arrays of Unix file descriptors you need to recurse
1896 * into the array manually.
1898 * Unix file descriptors that are read with this function will have
1899 * the FD_CLOEXEC flag set. If you need them without this flag set,
1900 * make sure to unset it with fcntl().
1902 * The variable argument list should contain the type of the argument
1903 * followed by a pointer to where the value should be stored. The list
1904 * is terminated with #DBUS_TYPE_INVALID.
1906 * Except for string arrays, the returned values are constant; do not
1907 * free them. They point into the #DBusMessage.
1909 * If the requested arguments are not present, or do not have the
1910 * requested types, then an error will be set.
1912 * If more arguments than requested are present, the requested
1913 * arguments are returned and the extra arguments are ignored.
1915 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1917 * @param message the message
1918 * @param error error to be filled in on failure
1919 * @param first_arg_type the first argument type
1920 * @param ... location for first argument value, then list of type-location pairs
1921 * @returns #FALSE if the error was set
1924 dbus_message_get_args (DBusMessage *message,
1932 _dbus_return_val_if_fail (message != NULL, FALSE);
1933 _dbus_return_val_if_error_is_set (error, FALSE);
1935 va_start (var_args, first_arg_type);
1936 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
1943 * Like dbus_message_get_args but takes a va_list for use by language bindings.
1945 * @see dbus_message_get_args
1946 * @param message the message
1947 * @param error error to be filled in
1948 * @param first_arg_type type of the first argument
1949 * @param var_args return location for first argument, followed by list of type/location pairs
1950 * @returns #FALSE if error was set
1953 dbus_message_get_args_valist (DBusMessage *message,
1958 DBusMessageIter iter;
1960 _dbus_return_val_if_fail (message != NULL, FALSE);
1961 _dbus_return_val_if_error_is_set (error, FALSE);
1963 dbus_message_iter_init (message, &iter);
1964 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
1968 _dbus_message_iter_init_common (DBusMessage *message,
1969 DBusMessageRealIter *real,
1972 _dbus_assert (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
1974 /* Since the iterator will read or write who-knows-what from the
1975 * message, we need to get in the right byte order
1977 ensure_byte_order (message);
1979 real->message = message;
1980 real->changed_stamp = message->changed_stamp;
1981 real->iter_type = iter_type;
1982 real->sig_refcount = 0;
1986 * Initializes a #DBusMessageIter for reading the arguments of the
1987 * message passed in.
1989 * When possible, dbus_message_get_args() is much more convenient.
1990 * Some types of argument can only be read with #DBusMessageIter
1993 * The easiest way to iterate is like this:
1995 * dbus_message_iter_init (message, &iter);
1996 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
1997 * dbus_message_iter_next (&iter);
2000 * #DBusMessageIter contains no allocated memory; it need not be
2001 * freed, and can be copied by assignment or memcpy().
2003 * @param message the message
2004 * @param iter pointer to an iterator to initialize
2005 * @returns #FALSE if the message has no arguments
2008 dbus_message_iter_init (DBusMessage *message,
2009 DBusMessageIter *iter)
2011 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2012 const DBusString *type_str;
2015 _dbus_return_val_if_fail (message != NULL, FALSE);
2016 _dbus_return_val_if_fail (iter != NULL, FALSE);
2018 get_const_signature (&message->header, &type_str, &type_pos);
2020 _dbus_message_iter_init_common (message, real,
2021 DBUS_MESSAGE_ITER_TYPE_READER);
2023 _dbus_type_reader_init (&real->u.reader,
2024 _dbus_header_get_byte_order (&message->header),
2029 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
2033 * Checks if an iterator has any more fields.
2035 * @param iter the message iter
2036 * @returns #TRUE if there are more fields following
2039 dbus_message_iter_has_next (DBusMessageIter *iter)
2041 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2043 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2044 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2046 return _dbus_type_reader_has_next (&real->u.reader);
2050 * Moves the iterator to the next field, if any. If there's no next
2051 * field, returns #FALSE. If the iterator moves forward, returns
2054 * @param iter the message iter
2055 * @returns #TRUE if the iterator was moved to the next field
2058 dbus_message_iter_next (DBusMessageIter *iter)
2060 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2062 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2063 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2065 return _dbus_type_reader_next (&real->u.reader);
2069 * Returns the argument type of the argument that the message iterator
2070 * points to. If the iterator is at the end of the message, returns
2071 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
2074 * dbus_message_iter_init (message, &iter);
2075 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2076 * dbus_message_iter_next (&iter);
2079 * @param iter the message iter
2080 * @returns the argument type
2083 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
2085 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2087 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2088 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2090 return _dbus_type_reader_get_current_type (&real->u.reader);
2094 * Returns the element type of the array that the message iterator
2095 * points to. Note that you need to check that the iterator points to
2096 * an array prior to using this function.
2098 * @param iter the message iter
2099 * @returns the array element type
2102 dbus_message_iter_get_element_type (DBusMessageIter *iter)
2104 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2106 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2107 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
2108 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
2110 return _dbus_type_reader_get_element_type (&real->u.reader);
2114 * Recurses into a container value when reading values from a message,
2115 * initializing a sub-iterator to use for traversing the child values
2118 * Note that this recurses into a value, not a type, so you can only
2119 * recurse if the value exists. The main implication of this is that
2120 * if you have for example an empty array of array of int32, you can
2121 * recurse into the outermost array, but it will have no values, so
2122 * you won't be able to recurse further. There's no array of int32 to
2125 * If a container is an array of fixed-length types (except Unix file
2126 * descriptors), it is much more efficient to use
2127 * dbus_message_iter_get_fixed_array() to get the whole array in one
2128 * shot, rather than individually walking over the array elements.
2130 * Be sure you have somehow checked that
2131 * dbus_message_iter_get_arg_type() matches the type you are expecting
2132 * to recurse into. Results of this function are undefined if there is
2133 * no container to recurse into at the current iterator position.
2135 * @param iter the message iterator
2136 * @param sub the sub-iterator to initialize
2139 dbus_message_iter_recurse (DBusMessageIter *iter,
2140 DBusMessageIter *sub)
2142 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2143 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2145 _dbus_return_if_fail (_dbus_message_iter_check (real));
2146 _dbus_return_if_fail (sub != NULL);
2149 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
2153 * Returns the current signature of a message iterator. This
2154 * is useful primarily for dealing with variants; one can
2155 * recurse into a variant and determine the signature of
2156 * the variant's value.
2158 * The returned string must be freed with dbus_free().
2160 * @param iter the message iterator
2161 * @returns the contained signature, or NULL if out of memory
2164 dbus_message_iter_get_signature (DBusMessageIter *iter)
2166 const DBusString *sig;
2170 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2172 _dbus_return_val_if_fail (_dbus_message_iter_check (real), NULL);
2174 if (!_dbus_string_init (&retstr))
2177 _dbus_type_reader_get_signature (&real->u.reader, &sig,
2179 if (!_dbus_string_append_len (&retstr,
2180 _dbus_string_get_const_data (sig) + start,
2183 if (!_dbus_string_steal_data (&retstr, &ret))
2185 _dbus_string_free (&retstr);
2190 * Reads a basic-typed value from the message iterator.
2191 * Basic types are the non-containers such as integer and string.
2193 * The value argument should be the address of a location to store
2194 * the returned value. So for int32 it should be a "dbus_int32_t*"
2195 * and for string a "const char**". The returned value is
2196 * by reference and should not be freed.
2198 * This call duplicates Unix file descriptors when reading them. It is
2199 * your job to close them when you don't need them anymore.
2201 * Unix file descriptors that are read with this function will have
2202 * the FD_CLOEXEC flag set. If you need them without this flag set,
2203 * make sure to unset it with fcntl().
2205 * Be sure you have somehow checked that
2206 * dbus_message_iter_get_arg_type() matches the type you are
2207 * expecting, or you'll crash when you try to use an integer as a
2208 * string or something.
2210 * To read any container type (array, struct, dict) you will need to
2211 * recurse into the container with dbus_message_iter_recurse(). If
2212 * the container is an array of fixed-length values (except Unix file
2213 * descriptors), you can get all the array elements at once with
2214 * dbus_message_iter_get_fixed_array(). Otherwise, you have to iterate
2215 * over the container's contents one value at a time.
2217 * All basic-typed values are guaranteed to fit in a #DBusBasicValue,
2218 * so in versions of libdbus that have that type, you can write code like this:
2221 * DBusBasicValue value;
2223 * dbus_message_iter_get_basic (&read_iter, &value);
2224 * type = dbus_message_iter_get_arg_type (&read_iter);
2225 * dbus_message_iter_append_basic (&write_iter, type, &value);
2228 * (All D-Bus basic types are either numeric and 8 bytes or smaller, or
2229 * behave like a string; so in older versions of libdbus, DBusBasicValue
2230 * can be replaced with union { char *string; unsigned char bytes[8]; },
2233 * @param iter the iterator
2234 * @param value location to store the value
2237 dbus_message_iter_get_basic (DBusMessageIter *iter,
2240 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2242 _dbus_return_if_fail (_dbus_message_iter_check (real));
2243 _dbus_return_if_fail (value != NULL);
2245 if (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_UNIX_FD)
2247 #ifdef HAVE_UNIX_FD_PASSING
2250 _dbus_type_reader_read_basic(&real->u.reader, &idx);
2252 if (idx.u32 >= real->message->n_unix_fds) {
2253 /* Hmm, we cannot really signal an error here, so let's make
2254 sure to return an invalid fd. */
2255 *((int*) value) = -1;
2259 *((int*) value) = _dbus_dup(real->message->unix_fds[idx.u32], NULL);
2261 *((int*) value) = -1;
2266 _dbus_type_reader_read_basic (&real->u.reader,
2272 * Returns the number of bytes in the array as marshaled in the wire
2273 * protocol. The iterator must currently be inside an array-typed
2276 * This function is deprecated on the grounds that it is stupid. Why
2277 * would you want to know how many bytes are in the array as marshaled
2278 * in the wire protocol? For now, use the n_elements returned from
2279 * dbus_message_iter_get_fixed_array() instead, or iterate over the
2280 * array values and count them.
2282 * @todo introduce a variant of this get_n_elements that returns
2283 * the number of elements, though with a non-fixed array it will not
2284 * be very efficient, so maybe it's not good.
2286 * @param iter the iterator
2287 * @returns the number of bytes in the array
2290 dbus_message_iter_get_array_len (DBusMessageIter *iter)
2292 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2294 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2296 return _dbus_type_reader_get_array_length (&real->u.reader);
2300 * Reads a block of fixed-length values from the message iterator.
2301 * Fixed-length values are those basic types that are not string-like,
2302 * such as integers, bool, double. The returned block will be from the
2303 * current position in the array until the end of the array.
2305 * There is one exception here: although DBUS_TYPE_UNIX_FD is
2306 * considered a 'fixed' type arrays of this type may not be read with
2309 * The message iter should be "in" the array (that is, you recurse into the
2310 * array, and then you call dbus_message_iter_get_fixed_array() on the
2311 * "sub-iterator" created by dbus_message_iter_recurse()).
2313 * The value argument should be the address of a location to store the
2314 * returned array. So for int32 it should be a "const dbus_int32_t**"
2315 * The returned value is by reference and should not be freed.
2317 * This function should only be used if dbus_type_is_fixed() returns
2318 * #TRUE for the element type.
2320 * If an array's elements are not fixed in size, you have to recurse
2321 * into the array with dbus_message_iter_recurse() and read the
2322 * elements one by one.
2324 * Because the array is not copied, this function runs in constant
2325 * time and is fast; it's much preferred over walking the entire array
2326 * with an iterator. (However, you can always use
2327 * dbus_message_iter_recurse(), even for fixed-length types;
2328 * dbus_message_iter_get_fixed_array() is just an optimization.)
2330 * @param iter the iterator
2331 * @param value location to store the block
2332 * @param n_elements number of elements in the block
2335 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
2339 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2340 #ifndef DBUS_DISABLE_CHECKS
2341 int subtype = _dbus_type_reader_get_current_type(&real->u.reader);
2343 _dbus_return_if_fail (_dbus_message_iter_check (real));
2344 _dbus_return_if_fail (value != NULL);
2345 _dbus_return_if_fail ((subtype == DBUS_TYPE_INVALID) ||
2346 (dbus_type_is_fixed (subtype) && subtype != DBUS_TYPE_UNIX_FD));
2349 _dbus_type_reader_read_fixed_multi (&real->u.reader,
2354 * Initializes a #DBusMessageIter for appending arguments to the end
2357 * @todo If appending any of the arguments fails due to lack of
2358 * memory, the message is hosed and you have to start over building
2359 * the whole message.
2361 * @param message the message
2362 * @param iter pointer to an iterator to initialize
2365 dbus_message_iter_init_append (DBusMessage *message,
2366 DBusMessageIter *iter)
2368 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2370 _dbus_return_if_fail (message != NULL);
2371 _dbus_return_if_fail (iter != NULL);
2373 _dbus_message_iter_init_common (message, real,
2374 DBUS_MESSAGE_ITER_TYPE_WRITER);
2376 /* We create the signature string and point iterators at it "on demand"
2377 * when a value is actually appended. That means that init() never fails
2380 _dbus_type_writer_init_types_delayed (&real->u.writer,
2381 _dbus_header_get_byte_order (&message->header),
2383 _dbus_string_get_length (&message->body));
2387 * Creates a temporary signature string containing the current
2388 * signature, stores it in the iterator, and points the iterator to
2389 * the end of it. Used any time we write to the message.
2391 * @param real an iterator without a type_str
2392 * @returns #FALSE if no memory
2395 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
2398 const DBusString *current_sig;
2399 int current_sig_pos;
2401 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2403 if (real->u.writer.type_str != NULL)
2405 _dbus_assert (real->sig_refcount > 0);
2406 real->sig_refcount += 1;
2410 str = dbus_new (DBusString, 1);
2414 if (!_dbus_header_get_field_raw (&real->message->header,
2415 DBUS_HEADER_FIELD_SIGNATURE,
2416 ¤t_sig, ¤t_sig_pos))
2423 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
2424 current_sig_pos += 1; /* move on to sig data */
2426 if (!_dbus_string_init_preallocated (str, current_len + 4))
2432 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
2435 _dbus_string_free (str);
2442 if (!_dbus_string_init_preallocated (str, 4))
2449 real->sig_refcount = 1;
2451 _dbus_type_writer_add_types (&real->u.writer,
2452 str, _dbus_string_get_length (str));
2457 * Sets the new signature as the message signature, frees the
2458 * signature string, and marks the iterator as not having a type_str
2459 * anymore. Frees the signature even if it fails, so you can't
2460 * really recover from failure. Kinda busted.
2462 * @param real an iterator without a type_str
2463 * @returns #FALSE if no memory
2466 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2469 const char *v_STRING;
2472 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2473 _dbus_assert (real->u.writer.type_str != NULL);
2474 _dbus_assert (real->sig_refcount > 0);
2476 real->sig_refcount -= 1;
2478 if (real->sig_refcount > 0)
2480 _dbus_assert (real->sig_refcount == 0);
2484 str = real->u.writer.type_str;
2486 v_STRING = _dbus_string_get_const_data (str);
2487 if (!_dbus_header_set_field_basic (&real->message->header,
2488 DBUS_HEADER_FIELD_SIGNATURE,
2489 DBUS_TYPE_SIGNATURE,
2493 _dbus_type_writer_remove_types (&real->u.writer);
2494 _dbus_string_free (str);
2501 * Frees the signature string and marks the iterator as not having a
2502 * type_str anymore. Since the new signature is not set, the message
2503 * will generally be hosed after this is called.
2505 * @param real an iterator without a type_str
2508 _dbus_message_iter_abandon_signature (DBusMessageRealIter *real)
2512 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2513 _dbus_assert (real->u.writer.type_str != NULL);
2514 _dbus_assert (real->sig_refcount > 0);
2516 real->sig_refcount -= 1;
2518 if (real->sig_refcount > 0)
2520 _dbus_assert (real->sig_refcount == 0);
2522 str = real->u.writer.type_str;
2524 _dbus_type_writer_remove_types (&real->u.writer);
2525 _dbus_string_free (str);
2529 #ifndef DBUS_DISABLE_CHECKS
2531 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2533 if (!_dbus_message_iter_check (iter))
2536 if (iter->message->locked)
2538 _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)\n");
2544 #endif /* DBUS_DISABLE_CHECKS */
2546 #ifdef HAVE_UNIX_FD_PASSING
2548 expand_fd_array(DBusMessage *m,
2553 /* This makes space for adding n new fds to the array and returns a
2554 pointer to the place were the first fd should be put. */
2556 if (m->n_unix_fds + n > m->n_unix_fds_allocated)
2561 /* Make twice as much space as necessary */
2562 k = (m->n_unix_fds + n) * 2;
2564 /* Allocate at least four */
2568 p = dbus_realloc(m->unix_fds, k * sizeof(int));
2573 m->n_unix_fds_allocated = k;
2576 return m->unix_fds + m->n_unix_fds;
2581 * Appends a basic-typed value to the message. The basic types are the
2582 * non-container types such as integer and string.
2584 * The "value" argument should be the address of a basic-typed value.
2585 * So for string, const char**. For integer, dbus_int32_t*.
2587 * For Unix file descriptors this function will internally duplicate
2588 * the descriptor you passed in. Hence you may close the descriptor
2589 * immediately after this call.
2591 * @todo If this fails due to lack of memory, the message is hosed and
2592 * you have to start over building the whole message.
2594 * @param iter the append iterator
2595 * @param type the type of the value
2596 * @param value the address of the value
2597 * @returns #FALSE if not enough memory
2600 dbus_message_iter_append_basic (DBusMessageIter *iter,
2604 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2607 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2608 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2609 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2610 _dbus_return_val_if_fail (value != NULL, FALSE);
2612 #ifndef DBUS_DISABLE_CHECKS
2615 const char * const *string_p;
2616 const dbus_bool_t *bool_p;
2618 case DBUS_TYPE_STRING:
2620 _dbus_return_val_if_fail (_dbus_check_is_valid_utf8 (*string_p), FALSE);
2623 case DBUS_TYPE_OBJECT_PATH:
2625 _dbus_return_val_if_fail (_dbus_check_is_valid_path (*string_p), FALSE);
2628 case DBUS_TYPE_SIGNATURE:
2630 _dbus_return_val_if_fail (_dbus_check_is_valid_signature (*string_p), FALSE);
2633 case DBUS_TYPE_BOOLEAN:
2635 _dbus_return_val_if_fail (*bool_p == 0 || *bool_p == 1, FALSE);
2640 /* nothing to check, all possible values are allowed */
2645 if (!_dbus_message_iter_open_signature (real))
2648 if (type == DBUS_TYPE_UNIX_FD)
2650 #ifdef HAVE_UNIX_FD_PASSING
2654 /* First step, include the fd in the fd list of this message */
2655 if (!(fds = expand_fd_array(real->message, 1)))
2658 *fds = _dbus_dup(*(int*) value, NULL);
2662 u = real->message->n_unix_fds;
2664 /* Second step, write the index to the fd */
2665 if (!(ret = _dbus_type_writer_write_basic (&real->u.writer, DBUS_TYPE_UNIX_FD, &u))) {
2666 _dbus_close(*fds, NULL);
2670 real->message->n_unix_fds += 1;
2673 /* Final step, update the header accordingly */
2674 ret = _dbus_header_set_field_basic (&real->message->header,
2675 DBUS_HEADER_FIELD_UNIX_FDS,
2679 /* If any of these operations fail the message is
2680 hosed. However, no memory or fds should be leaked since what
2681 has been added to message has been added to the message, and
2682 can hence be accounted for when the message is being
2690 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
2693 if (!_dbus_message_iter_close_signature (real))
2700 * Appends a block of fixed-length values to an array. The
2701 * fixed-length types are all basic types that are not string-like. So
2702 * int32, double, bool, etc. (Unix file descriptors however are not
2703 * supported.) You must call dbus_message_iter_open_container() to
2704 * open an array of values before calling this function. You may call
2705 * this function multiple times (and intermixed with calls to
2706 * dbus_message_iter_append_basic()) for the same array.
2708 * The "value" argument should be the address of the array. So for
2709 * integer, "dbus_int32_t**" is expected for example.
2711 * @warning in C, given "int array[]", "&array == array" (the
2712 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2713 * So if you're using an array instead of a pointer you have to create
2714 * a pointer variable, assign the array to it, then take the address
2715 * of the pointer variable.
2717 * const dbus_int32_t array[] = { 1, 2, 3 };
2718 * const dbus_int32_t *v_ARRAY = array;
2719 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
2720 * fprintf (stderr, "No memory!\n");
2722 * For strings it works to write const char *array = "Hello" and then
2723 * use &array though.
2725 * @todo If this fails due to lack of memory, the message is hosed and
2726 * you have to start over building the whole message.
2728 * @param iter the append iterator
2729 * @param element_type the type of the array elements
2730 * @param value the address of the array
2731 * @param n_elements the number of elements to append
2732 * @returns #FALSE if not enough memory
2735 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
2740 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2743 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2744 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2745 _dbus_return_val_if_fail (dbus_type_is_fixed (element_type) && element_type != DBUS_TYPE_UNIX_FD, FALSE);
2746 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
2747 _dbus_return_val_if_fail (value != NULL, FALSE);
2748 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
2749 _dbus_return_val_if_fail (n_elements <=
2750 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
2753 #ifndef DBUS_DISABLE_CHECKS
2754 if (element_type == DBUS_TYPE_BOOLEAN)
2756 const dbus_bool_t * const *bools = value;
2759 for (i = 0; i < n_elements; i++)
2761 _dbus_return_val_if_fail ((*bools)[i] == 0 || (*bools)[i] == 1, FALSE);
2766 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
2772 * Appends a container-typed value to the message; you are required to
2773 * append the contents of the container using the returned
2774 * sub-iterator, and then call
2775 * dbus_message_iter_close_container(). Container types are for
2776 * example struct, variant, and array. For variants, the
2777 * contained_signature should be the type of the single value inside
2778 * the variant. For structs and dict entries, contained_signature
2779 * should be #NULL; it will be set to whatever types you write into
2780 * the struct. For arrays, contained_signature should be the type of
2781 * the array elements.
2783 * @todo If this fails due to lack of memory, the message is hosed and
2784 * you have to start over building the whole message.
2786 * @param iter the append iterator
2787 * @param type the type of the value
2788 * @param contained_signature the type of container contents
2789 * @param sub sub-iterator to initialize
2790 * @returns #FALSE if not enough memory
2793 dbus_message_iter_open_container (DBusMessageIter *iter,
2795 const char *contained_signature,
2796 DBusMessageIter *sub)
2798 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2799 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2800 DBusString contained_str;
2802 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2803 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2804 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
2805 _dbus_return_val_if_fail (sub != NULL, FALSE);
2806 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
2807 contained_signature == NULL) ||
2808 (type == DBUS_TYPE_DICT_ENTRY &&
2809 contained_signature == NULL) ||
2810 (type == DBUS_TYPE_VARIANT &&
2811 contained_signature != NULL) ||
2812 (type == DBUS_TYPE_ARRAY &&
2813 contained_signature != NULL), FALSE);
2815 /* this would fail if the contained_signature is a dict entry, since
2816 * dict entries are invalid signatures standalone (they must be in
2819 _dbus_return_val_if_fail ((type == DBUS_TYPE_ARRAY && contained_signature && *contained_signature == DBUS_DICT_ENTRY_BEGIN_CHAR) ||
2820 (contained_signature == NULL ||
2821 _dbus_check_is_valid_signature (contained_signature)),
2824 if (!_dbus_message_iter_open_signature (real))
2829 if (contained_signature != NULL)
2831 _dbus_string_init_const (&contained_str, contained_signature);
2833 return _dbus_type_writer_recurse (&real->u.writer,
2836 &real_sub->u.writer);
2840 return _dbus_type_writer_recurse (&real->u.writer,
2843 &real_sub->u.writer);
2849 * Closes a container-typed value appended to the message; may write
2850 * out more information to the message known only after the entire
2851 * container is written, and may free resources created by
2852 * dbus_message_iter_open_container().
2854 * @todo If this fails due to lack of memory, the message is hosed and
2855 * you have to start over building the whole message.
2857 * @param iter the append iterator
2858 * @param sub sub-iterator to close
2859 * @returns #FALSE if not enough memory
2862 dbus_message_iter_close_container (DBusMessageIter *iter,
2863 DBusMessageIter *sub)
2865 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2866 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2869 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2870 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2871 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
2872 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2874 ret = _dbus_type_writer_unrecurse (&real->u.writer,
2875 &real_sub->u.writer);
2877 if (!_dbus_message_iter_close_signature (real))
2884 * Abandons creation of a contained-typed value and frees resources created
2885 * by dbus_message_iter_open_container(). Once this returns, the message
2886 * is hosed and you have to start over building the whole message.
2888 * This should only be used to abandon creation of a message when you have
2891 * @param iter the append iterator
2892 * @param sub sub-iterator to close
2895 dbus_message_iter_abandon_container (DBusMessageIter *iter,
2896 DBusMessageIter *sub)
2898 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2899 #ifndef DBUS_DISABLE_CHECKS
2900 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2902 _dbus_return_if_fail (_dbus_message_iter_append_check (real));
2903 _dbus_return_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2904 _dbus_return_if_fail (_dbus_message_iter_append_check (real_sub));
2905 _dbus_return_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2908 _dbus_message_iter_abandon_signature (real);
2912 * Sets a flag indicating that the message does not want a reply; if
2913 * this flag is set, the other end of the connection may (but is not
2914 * required to) optimize by not sending method return or error
2915 * replies. If this flag is set, there is no way to know whether the
2916 * message successfully arrived at the remote end. Normally you know a
2917 * message was received when you receive the reply to it.
2919 * The flag is #FALSE by default, that is by default the other end is
2920 * required to reply.
2922 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
2924 * @param message the message
2925 * @param no_reply #TRUE if no reply is desired
2928 dbus_message_set_no_reply (DBusMessage *message,
2929 dbus_bool_t no_reply)
2931 _dbus_return_if_fail (message != NULL);
2932 _dbus_return_if_fail (!message->locked);
2934 _dbus_header_toggle_flag (&message->header,
2935 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
2940 * Returns #TRUE if the message does not expect
2943 * @param message the message
2944 * @returns #TRUE if the message sender isn't waiting for a reply
2947 dbus_message_get_no_reply (DBusMessage *message)
2949 _dbus_return_val_if_fail (message != NULL, FALSE);
2951 return _dbus_header_get_flag (&message->header,
2952 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
2956 * Sets a flag indicating that an owner for the destination name will
2957 * be automatically started before the message is delivered. When this
2958 * flag is set, the message is held until a name owner finishes
2959 * starting up, or fails to start up. In case of failure, the reply
2962 * The flag is set to #TRUE by default, i.e. auto starting is the default.
2964 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
2966 * @param message the message
2967 * @param auto_start #TRUE if auto-starting is desired
2970 dbus_message_set_auto_start (DBusMessage *message,
2971 dbus_bool_t auto_start)
2973 _dbus_return_if_fail (message != NULL);
2974 _dbus_return_if_fail (!message->locked);
2976 _dbus_header_toggle_flag (&message->header,
2977 DBUS_HEADER_FLAG_NO_AUTO_START,
2982 * Returns #TRUE if the message will cause an owner for
2983 * destination name to be auto-started.
2985 * @param message the message
2986 * @returns #TRUE if the message will use auto-start
2989 dbus_message_get_auto_start (DBusMessage *message)
2991 _dbus_return_val_if_fail (message != NULL, FALSE);
2993 return !_dbus_header_get_flag (&message->header,
2994 DBUS_HEADER_FLAG_NO_AUTO_START);
2999 * Sets the object path this message is being sent to (for
3000 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
3001 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
3003 * The path must contain only valid characters as defined
3004 * in the D-Bus specification.
3006 * @param message the message
3007 * @param object_path the path or #NULL to unset
3008 * @returns #FALSE if not enough memory
3011 dbus_message_set_path (DBusMessage *message,
3012 const char *object_path)
3014 _dbus_return_val_if_fail (message != NULL, FALSE);
3015 _dbus_return_val_if_fail (!message->locked, FALSE);
3016 _dbus_return_val_if_fail (object_path == NULL ||
3017 _dbus_check_is_valid_path (object_path),
3020 return set_or_delete_string_field (message,
3021 DBUS_HEADER_FIELD_PATH,
3022 DBUS_TYPE_OBJECT_PATH,
3027 * Gets the object path this message is being sent to (for
3028 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
3029 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3031 * See also dbus_message_get_path_decomposed().
3033 * The returned string becomes invalid if the message is
3034 * modified, since it points into the wire-marshaled message data.
3036 * @param message the message
3037 * @returns the path (should not be freed) or #NULL
3040 dbus_message_get_path (DBusMessage *message)
3044 _dbus_return_val_if_fail (message != NULL, NULL);
3046 v = NULL; /* in case field doesn't exist */
3047 _dbus_header_get_field_basic (&message->header,
3048 DBUS_HEADER_FIELD_PATH,
3049 DBUS_TYPE_OBJECT_PATH,
3055 * Checks if the message has a particular object path. The object
3056 * path is the destination object for a method call or the emitting
3057 * object for a signal.
3059 * @param message the message
3060 * @param path the path name
3061 * @returns #TRUE if there is a path field in the header
3064 dbus_message_has_path (DBusMessage *message,
3067 const char *msg_path;
3068 msg_path = dbus_message_get_path (message);
3070 if (msg_path == NULL)
3081 if (strcmp (msg_path, path) == 0)
3088 * Gets the object path this message is being sent to
3089 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3090 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
3091 * format (one array element per path component).
3092 * Free the returned array with dbus_free_string_array().
3094 * An empty but non-NULL path array means the path "/".
3095 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
3096 * and the path "/" becomes { NULL }.
3098 * See also dbus_message_get_path().
3100 * @todo this could be optimized by using the len from the message
3101 * instead of calling strlen() again
3103 * @param message the message
3104 * @param path place to store allocated array of path components; #NULL set here if no path field exists
3105 * @returns #FALSE if no memory to allocate the array
3108 dbus_message_get_path_decomposed (DBusMessage *message,
3113 _dbus_return_val_if_fail (message != NULL, FALSE);
3114 _dbus_return_val_if_fail (path != NULL, FALSE);
3118 v = dbus_message_get_path (message);
3121 if (!_dbus_decompose_path (v, strlen (v),
3129 * Sets the interface this message is being sent to
3130 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
3131 * the interface a signal is being emitted from
3132 * (for DBUS_MESSAGE_TYPE_SIGNAL).
3134 * The interface name must contain only valid characters as defined
3135 * in the D-Bus specification.
3137 * @param message the message
3138 * @param iface the interface or #NULL to unset
3139 * @returns #FALSE if not enough memory
3142 dbus_message_set_interface (DBusMessage *message,
3145 _dbus_return_val_if_fail (message != NULL, FALSE);
3146 _dbus_return_val_if_fail (!message->locked, FALSE);
3147 _dbus_return_val_if_fail (iface == NULL ||
3148 _dbus_check_is_valid_interface (iface),
3151 return set_or_delete_string_field (message,
3152 DBUS_HEADER_FIELD_INTERFACE,
3158 * Gets the interface this message is being sent to
3159 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3160 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
3161 * The interface name is fully-qualified (namespaced).
3162 * Returns #NULL if none.
3164 * The returned string becomes invalid if the message is
3165 * modified, since it points into the wire-marshaled message data.
3167 * @param message the message
3168 * @returns the message interface (should not be freed) or #NULL
3171 dbus_message_get_interface (DBusMessage *message)
3175 _dbus_return_val_if_fail (message != NULL, NULL);
3177 v = NULL; /* in case field doesn't exist */
3178 _dbus_header_get_field_basic (&message->header,
3179 DBUS_HEADER_FIELD_INTERFACE,
3186 * Checks if the message has an interface
3188 * @param message the message
3189 * @param iface the interface name
3190 * @returns #TRUE if the interface field in the header matches
3193 dbus_message_has_interface (DBusMessage *message,
3196 const char *msg_interface;
3197 msg_interface = dbus_message_get_interface (message);
3199 if (msg_interface == NULL)
3210 if (strcmp (msg_interface, iface) == 0)
3218 * Sets the interface member being invoked
3219 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3220 * (DBUS_MESSAGE_TYPE_SIGNAL).
3222 * The member name must contain only valid characters as defined
3223 * in the D-Bus specification.
3225 * @param message the message
3226 * @param member the member or #NULL to unset
3227 * @returns #FALSE if not enough memory
3230 dbus_message_set_member (DBusMessage *message,
3233 _dbus_return_val_if_fail (message != NULL, FALSE);
3234 _dbus_return_val_if_fail (!message->locked, FALSE);
3235 _dbus_return_val_if_fail (member == NULL ||
3236 _dbus_check_is_valid_member (member),
3239 return set_or_delete_string_field (message,
3240 DBUS_HEADER_FIELD_MEMBER,
3246 * Gets the interface member being invoked
3247 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3248 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3250 * The returned string becomes invalid if the message is
3251 * modified, since it points into the wire-marshaled message data.
3253 * @param message the message
3254 * @returns the member name (should not be freed) or #NULL
3257 dbus_message_get_member (DBusMessage *message)
3261 _dbus_return_val_if_fail (message != NULL, NULL);
3263 v = NULL; /* in case field doesn't exist */
3264 _dbus_header_get_field_basic (&message->header,
3265 DBUS_HEADER_FIELD_MEMBER,
3272 * Checks if the message has an interface member
3274 * @param message the message
3275 * @param member the member name
3276 * @returns #TRUE if there is a member field in the header
3279 dbus_message_has_member (DBusMessage *message,
3282 const char *msg_member;
3283 msg_member = dbus_message_get_member (message);
3285 if (msg_member == NULL)
3296 if (strcmp (msg_member, member) == 0)
3304 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
3305 * The name is fully-qualified (namespaced).
3307 * The error name must contain only valid characters as defined
3308 * in the D-Bus specification.
3310 * @param message the message
3311 * @param error_name the name or #NULL to unset
3312 * @returns #FALSE if not enough memory
3315 dbus_message_set_error_name (DBusMessage *message,
3316 const char *error_name)
3318 _dbus_return_val_if_fail (message != NULL, FALSE);
3319 _dbus_return_val_if_fail (!message->locked, FALSE);
3320 _dbus_return_val_if_fail (error_name == NULL ||
3321 _dbus_check_is_valid_error_name (error_name),
3324 return set_or_delete_string_field (message,
3325 DBUS_HEADER_FIELD_ERROR_NAME,
3331 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
3334 * The returned string becomes invalid if the message is
3335 * modified, since it points into the wire-marshaled message data.
3337 * @param message the message
3338 * @returns the error name (should not be freed) or #NULL
3341 dbus_message_get_error_name (DBusMessage *message)
3345 _dbus_return_val_if_fail (message != NULL, NULL);
3347 v = NULL; /* in case field doesn't exist */
3348 _dbus_header_get_field_basic (&message->header,
3349 DBUS_HEADER_FIELD_ERROR_NAME,
3356 * Sets the message's destination. The destination is the name of
3357 * another connection on the bus and may be either the unique name
3358 * assigned by the bus to each connection, or a well-known name
3359 * specified in advance.
3361 * The destination name must contain only valid characters as defined
3362 * in the D-Bus specification.
3364 * @param message the message
3365 * @param destination the destination name or #NULL to unset
3366 * @returns #FALSE if not enough memory
3369 dbus_message_set_destination (DBusMessage *message,
3370 const char *destination)
3372 _dbus_return_val_if_fail (message != NULL, FALSE);
3373 _dbus_return_val_if_fail (!message->locked, FALSE);
3374 _dbus_return_val_if_fail (destination == NULL ||
3375 _dbus_check_is_valid_bus_name (destination),
3378 return set_or_delete_string_field (message,
3379 DBUS_HEADER_FIELD_DESTINATION,
3385 * Gets the destination of a message or #NULL if there is none set.
3387 * The returned string becomes invalid if the message is
3388 * modified, since it points into the wire-marshaled message data.
3390 * @param message the message
3391 * @returns the message destination (should not be freed) or #NULL
3394 dbus_message_get_destination (DBusMessage *message)
3398 _dbus_return_val_if_fail (message != NULL, NULL);
3400 v = NULL; /* in case field doesn't exist */
3401 _dbus_header_get_field_basic (&message->header,
3402 DBUS_HEADER_FIELD_DESTINATION,
3409 * Sets the message sender.
3411 * The sender must be a valid bus name as defined in the D-Bus
3414 * Usually you don't want to call this. The message bus daemon will
3415 * call it to set the origin of each message. If you aren't implementing
3416 * a message bus daemon you shouldn't need to set the sender.
3418 * @param message the message
3419 * @param sender the sender or #NULL to unset
3420 * @returns #FALSE if not enough memory
3423 dbus_message_set_sender (DBusMessage *message,
3426 _dbus_return_val_if_fail (message != NULL, FALSE);
3427 _dbus_return_val_if_fail (!message->locked, FALSE);
3428 _dbus_return_val_if_fail (sender == NULL ||
3429 _dbus_check_is_valid_bus_name (sender),
3432 return set_or_delete_string_field (message,
3433 DBUS_HEADER_FIELD_SENDER,
3439 * Gets the unique name of the connection which originated this
3440 * message, or #NULL if unknown or inapplicable. The sender is filled
3441 * in by the message bus.
3443 * Note, the returned sender is always the unique bus name.
3444 * Connections may own multiple other bus names, but those
3445 * are not found in the sender field.
3447 * The returned string becomes invalid if the message is
3448 * modified, since it points into the wire-marshaled message data.
3450 * @param message the message
3451 * @returns the unique name of the sender or #NULL
3454 dbus_message_get_sender (DBusMessage *message)
3458 _dbus_return_val_if_fail (message != NULL, NULL);
3460 v = NULL; /* in case field doesn't exist */
3461 _dbus_header_get_field_basic (&message->header,
3462 DBUS_HEADER_FIELD_SENDER,
3469 * Gets the type signature of the message, i.e. the arguments in the
3470 * message payload. The signature includes only "in" arguments for
3471 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
3472 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
3473 * what you might expect (that is, it does not include the signature of the
3474 * entire C++-style method).
3476 * The signature is a string made up of type codes such as
3477 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
3478 * the value of #DBUS_TYPE_INVALID).
3480 * The returned string becomes invalid if the message is
3481 * modified, since it points into the wire-marshaled message data.
3483 * @param message the message
3484 * @returns the type signature
3487 dbus_message_get_signature (DBusMessage *message)
3489 const DBusString *type_str;
3492 _dbus_return_val_if_fail (message != NULL, NULL);
3494 get_const_signature (&message->header, &type_str, &type_pos);
3496 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
3500 _dbus_message_has_type_interface_member (DBusMessage *message,
3507 _dbus_assert (message != NULL);
3508 _dbus_assert (iface != NULL);
3509 _dbus_assert (member != NULL);
3511 if (dbus_message_get_type (message) != type)
3514 /* Optimize by checking the short member name first
3515 * instead of the longer interface name
3518 n = dbus_message_get_member (message);
3520 if (n && strcmp (n, member) == 0)
3522 n = dbus_message_get_interface (message);
3524 if (n == NULL || strcmp (n, iface) == 0)
3532 * Checks whether the message is a method call with the given
3533 * interface and member fields. If the message is not
3534 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
3535 * member field, returns #FALSE. If the interface field is missing,
3536 * then it will be assumed equal to the provided interface. The D-Bus
3537 * protocol allows method callers to leave out the interface name.
3539 * @param message the message
3540 * @param iface the name to check (must not be #NULL)
3541 * @param method the name to check (must not be #NULL)
3543 * @returns #TRUE if the message is the specified method call
3546 dbus_message_is_method_call (DBusMessage *message,
3550 _dbus_return_val_if_fail (message != NULL, FALSE);
3551 _dbus_return_val_if_fail (iface != NULL, FALSE);
3552 _dbus_return_val_if_fail (method != NULL, FALSE);
3553 /* don't check that interface/method are valid since it would be
3554 * expensive, and not catch many common errors
3557 return _dbus_message_has_type_interface_member (message,
3558 DBUS_MESSAGE_TYPE_METHOD_CALL,
3563 * Checks whether the message is a signal with the given interface and
3564 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
3565 * has a different interface or member field, returns #FALSE.
3567 * @param message the message
3568 * @param iface the name to check (must not be #NULL)
3569 * @param signal_name the name to check (must not be #NULL)
3571 * @returns #TRUE if the message is the specified signal
3574 dbus_message_is_signal (DBusMessage *message,
3576 const char *signal_name)
3578 _dbus_return_val_if_fail (message != NULL, FALSE);
3579 _dbus_return_val_if_fail (iface != NULL, FALSE);
3580 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
3581 /* don't check that interface/name are valid since it would be
3582 * expensive, and not catch many common errors
3585 return _dbus_message_has_type_interface_member (message,
3586 DBUS_MESSAGE_TYPE_SIGNAL,
3587 iface, signal_name);
3591 * Checks whether the message is an error reply with the given error
3592 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
3593 * different name, returns #FALSE.
3595 * @param message the message
3596 * @param error_name the name to check (must not be #NULL)
3598 * @returns #TRUE if the message is the specified error
3601 dbus_message_is_error (DBusMessage *message,
3602 const char *error_name)
3606 _dbus_return_val_if_fail (message != NULL, FALSE);
3607 _dbus_return_val_if_fail (error_name != NULL, FALSE);
3608 /* don't check that error_name is valid since it would be expensive,
3609 * and not catch many common errors
3612 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3615 n = dbus_message_get_error_name (message);
3617 if (n && strcmp (n, error_name) == 0)
3624 * Checks whether the message was sent to the given name. If the
3625 * message has no destination specified or has a different
3626 * destination, returns #FALSE.
3628 * @param message the message
3629 * @param name the name to check (must not be #NULL)
3631 * @returns #TRUE if the message has the given destination name
3634 dbus_message_has_destination (DBusMessage *message,
3639 _dbus_return_val_if_fail (message != NULL, FALSE);
3640 _dbus_return_val_if_fail (name != NULL, FALSE);
3641 /* don't check that name is valid since it would be expensive, and
3642 * not catch many common errors
3645 s = dbus_message_get_destination (message);
3647 if (s && strcmp (s, name) == 0)
3654 * Checks whether the message has the given unique name as its sender.
3655 * If the message has no sender specified or has a different sender,
3656 * returns #FALSE. Note that a peer application will always have the
3657 * unique name of the connection as the sender. So you can't use this
3658 * function to see whether a sender owned a well-known name.
3660 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
3663 * @param message the message
3664 * @param name the name to check (must not be #NULL)
3666 * @returns #TRUE if the message has the given sender
3669 dbus_message_has_sender (DBusMessage *message,
3674 _dbus_return_val_if_fail (message != NULL, FALSE);
3675 _dbus_return_val_if_fail (name != NULL, FALSE);
3676 /* don't check that name is valid since it would be expensive, and
3677 * not catch many common errors
3680 s = dbus_message_get_sender (message);
3682 if (s && strcmp (s, name) == 0)
3689 * Checks whether the message has the given signature; see
3690 * dbus_message_get_signature() for more details on what the signature
3693 * @param message the message
3694 * @param signature typecode array
3695 * @returns #TRUE if message has the given signature
3698 dbus_message_has_signature (DBusMessage *message,
3699 const char *signature)
3703 _dbus_return_val_if_fail (message != NULL, FALSE);
3704 _dbus_return_val_if_fail (signature != NULL, FALSE);
3705 /* don't check that signature is valid since it would be expensive,
3706 * and not catch many common errors
3709 s = dbus_message_get_signature (message);
3711 if (s && strcmp (s, signature) == 0)
3718 * Sets a #DBusError based on the contents of the given
3719 * message. The error is only set if the message
3720 * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
3721 * The name of the error is set to the name of the message,
3722 * and the error message is set to the first argument
3723 * if the argument exists and is a string.
3725 * The return value indicates whether the error was set (the error is
3726 * set if and only if the message is an error message). So you can
3727 * check for an error reply and convert it to DBusError in one go:
3729 * if (dbus_set_error_from_message (error, reply))
3735 * @param error the error to set
3736 * @param message the message to set it from
3737 * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
3740 dbus_set_error_from_message (DBusError *error,
3741 DBusMessage *message)
3745 _dbus_return_val_if_fail (message != NULL, FALSE);
3746 _dbus_return_val_if_error_is_set (error, FALSE);
3748 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3752 dbus_message_get_args (message, NULL,
3753 DBUS_TYPE_STRING, &str,
3756 dbus_set_error (error, dbus_message_get_error_name (message),
3757 str ? "%s" : NULL, str);
3763 * Checks whether a message contains unix fds
3765 * @param message the message
3766 * @returns #TRUE if the message contains unix fds
3769 dbus_message_contains_unix_fds(DBusMessage *message)
3771 #ifdef HAVE_UNIX_FD_PASSING
3772 _dbus_assert(message);
3774 return message->n_unix_fds > 0;
3783 * @addtogroup DBusMessageInternals
3789 * The initial buffer size of the message loader.
3791 * @todo this should be based on min header size plus some average
3792 * body size, or something. Or rather, the min header size only, if we
3793 * want to try to read only the header, store that in a DBusMessage,
3794 * then read only the body and store that, etc., depends on
3795 * how we optimize _dbus_message_loader_get_buffer() and what
3796 * the exact message format is.
3798 #define INITIAL_LOADER_DATA_LEN 32
3801 * Creates a new message loader. Returns #NULL if memory can't
3804 * @returns new loader, or #NULL.
3807 _dbus_message_loader_new (void)
3809 DBusMessageLoader *loader;
3811 loader = dbus_new0 (DBusMessageLoader, 1);
3815 loader->refcount = 1;
3817 loader->corrupted = FALSE;
3818 loader->corruption_reason = DBUS_VALID;
3820 /* this can be configured by the app, but defaults to the protocol max */
3821 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
3823 /* We set a very relatively conservative default here since due to how
3824 SCM_RIGHTS works we need to preallocate an fd array of the maximum
3825 number of unix fds we want to receive in advance. A
3826 try-and-reallocate loop is not possible. */
3827 loader->max_message_unix_fds = DBUS_DEFAULT_MESSAGE_UNIX_FDS;
3829 if (!_dbus_string_init (&loader->data))
3835 /* preallocate the buffer for speed, ignore failure */
3836 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
3837 _dbus_string_set_length (&loader->data, 0);
3839 #ifdef HAVE_UNIX_FD_PASSING
3840 loader->unix_fds = NULL;
3841 loader->n_unix_fds = loader->n_unix_fds_allocated = 0;
3842 loader->unix_fds_outstanding = FALSE;
3849 * Increments the reference count of the loader.
3851 * @param loader the loader.
3852 * @returns the loader
3855 _dbus_message_loader_ref (DBusMessageLoader *loader)
3857 loader->refcount += 1;
3863 * Decrements the reference count of the loader and finalizes the
3864 * loader when the count reaches zero.
3866 * @param loader the loader.
3869 _dbus_message_loader_unref (DBusMessageLoader *loader)
3871 loader->refcount -= 1;
3872 if (loader->refcount == 0)
3874 #ifdef HAVE_UNIX_FD_PASSING
3875 close_unix_fds(loader->unix_fds, &loader->n_unix_fds);
3876 dbus_free(loader->unix_fds);
3878 _dbus_list_foreach (&loader->messages,
3879 (DBusForeachFunction) dbus_message_unref,
3881 _dbus_list_clear (&loader->messages);
3882 _dbus_string_free (&loader->data);
3888 * Gets the buffer to use for reading data from the network. Network
3889 * data is read directly into an allocated buffer, which is then used
3890 * in the DBusMessage, to avoid as many extra memcpy's as possible.
3891 * The buffer must always be returned immediately using
3892 * _dbus_message_loader_return_buffer(), even if no bytes are
3893 * successfully read.
3895 * @todo this function can be a lot more clever. For example
3896 * it can probably always return a buffer size to read exactly
3897 * the body of the next message, thus avoiding any memory wastage
3900 * @todo we need to enforce a max length on strings in header fields.
3902 * @param loader the message loader.
3903 * @param buffer the buffer
3906 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
3907 DBusString **buffer)
3909 _dbus_assert (!loader->buffer_outstanding);
3911 *buffer = &loader->data;
3913 loader->buffer_outstanding = TRUE;
3917 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
3918 * indicating to the loader how many bytes of the buffer were filled
3919 * in. This function must always be called, even if no bytes were
3920 * successfully read.
3922 * @param loader the loader.
3923 * @param buffer the buffer.
3924 * @param bytes_read number of bytes that were read into the buffer.
3927 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
3931 _dbus_assert (loader->buffer_outstanding);
3932 _dbus_assert (buffer == &loader->data);
3934 loader->buffer_outstanding = FALSE;
3938 * Gets the buffer to use for reading unix fds from the network.
3940 * This works similar to _dbus_message_loader_get_buffer()
3942 * @param loader the message loader.
3943 * @param fds the array to read fds into
3944 * @param max_n_fds how many fds to read at most
3945 * @return TRUE on success, FALSE on OOM
3948 _dbus_message_loader_get_unix_fds(DBusMessageLoader *loader,
3950 unsigned *max_n_fds)
3952 #ifdef HAVE_UNIX_FD_PASSING
3953 _dbus_assert (!loader->unix_fds_outstanding);
3955 /* Allocate space where we can put the fds we read. We allocate
3956 space for max_message_unix_fds since this is an
3957 upper limit how many fds can be received within a single
3958 message. Since SCM_RIGHTS doesn't allow a reallocate+retry logic
3959 we are allocating the maximum possible array size right from the
3960 beginning. This sucks a bit, however unless SCM_RIGHTS is fixed
3961 there is no better way. */
3963 if (loader->n_unix_fds_allocated < loader->max_message_unix_fds)
3965 int *a = dbus_realloc(loader->unix_fds,
3966 loader->max_message_unix_fds * sizeof(loader->unix_fds[0]));
3971 loader->unix_fds = a;
3972 loader->n_unix_fds_allocated = loader->max_message_unix_fds;
3975 *fds = loader->unix_fds + loader->n_unix_fds;
3976 *max_n_fds = loader->n_unix_fds_allocated - loader->n_unix_fds;
3978 loader->unix_fds_outstanding = TRUE;
3981 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
3987 * Returns a buffer obtained from _dbus_message_loader_get_unix_fds().
3989 * This works similar to _dbus_message_loader_return_buffer()
3991 * @param loader the message loader.
3992 * @param fds the array fds were read into
3993 * @param n_fds how many fds were read
3997 _dbus_message_loader_return_unix_fds(DBusMessageLoader *loader,
4001 #ifdef HAVE_UNIX_FD_PASSING
4002 _dbus_assert(loader->unix_fds_outstanding);
4003 _dbus_assert(loader->unix_fds + loader->n_unix_fds == fds);
4004 _dbus_assert(loader->n_unix_fds + n_fds <= loader->n_unix_fds_allocated);
4006 loader->n_unix_fds += n_fds;
4007 loader->unix_fds_outstanding = FALSE;
4009 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
4014 * FIXME when we move the header out of the buffer, that memmoves all
4015 * buffered messages. Kind of crappy.
4017 * Also we copy the header and body, which is kind of crappy. To
4018 * avoid this, we have to allow header and body to be in a single
4019 * memory block, which is good for messages we read and bad for
4020 * messages we are creating. But we could move_len() the buffer into
4021 * this single memory block, and move_len() will just swap the buffers
4022 * if you're moving the entire buffer replacing the dest string.
4024 * We could also have the message loader tell the transport how many
4025 * bytes to read; so it would first ask for some arbitrary number like
4026 * 256, then if the message was incomplete it would use the
4027 * header/body len to ask for exactly the size of the message (or
4028 * blocks the size of a typical kernel buffer for the socket). That
4029 * way we don't get trailing bytes in the buffer that have to be
4030 * memmoved. Though I suppose we also don't have a chance of reading a
4031 * bunch of small messages at once, so the optimization may be stupid.
4033 * Another approach would be to keep a "start" index into
4034 * loader->data and only delete it occasionally, instead of after
4035 * each message is loaded.
4037 * load_message() returns FALSE if not enough memory OR the loader was corrupted
4040 load_message (DBusMessageLoader *loader,
4041 DBusMessage *message,
4043 int fields_array_len,
4048 DBusValidity validity;
4049 const DBusString *type_str;
4051 DBusValidationMode mode;
4052 dbus_uint32_t n_unix_fds = 0;
4054 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
4059 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
4062 /* 1. VALIDATE AND COPY OVER HEADER */
4063 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
4064 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
4066 if (!_dbus_header_load (&message->header,
4074 _dbus_string_get_length (&loader->data)))
4076 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
4078 /* assert here so we can catch any code that still uses DBUS_VALID to indicate
4079 oom errors. They should use DBUS_VALIDITY_UNKNOWN_OOM_ERROR instead */
4080 _dbus_assert (validity != DBUS_VALID);
4082 if (validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
4086 loader->corrupted = TRUE;
4087 loader->corruption_reason = validity;
4092 _dbus_assert (validity == DBUS_VALID);
4094 /* 2. VALIDATE BODY */
4095 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
4097 get_const_signature (&message->header, &type_str, &type_pos);
4099 /* Because the bytes_remaining arg is NULL, this validates that the
4100 * body is the right length
4102 validity = _dbus_validate_body_with_reason (type_str,
4109 if (validity != DBUS_VALID)
4111 _dbus_verbose ("Failed to validate message body code %d\n", validity);
4113 loader->corrupted = TRUE;
4114 loader->corruption_reason = validity;
4120 /* 3. COPY OVER UNIX FDS */
4121 _dbus_header_get_field_basic(&message->header,
4122 DBUS_HEADER_FIELD_UNIX_FDS,
4126 #ifdef HAVE_UNIX_FD_PASSING
4128 if (n_unix_fds > loader->n_unix_fds)
4130 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
4131 n_unix_fds, loader->n_unix_fds);
4133 loader->corrupted = TRUE;
4134 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4138 /* If this was a recycled message there might still be
4139 some memory allocated for the fds */
4140 dbus_free(message->unix_fds);
4144 message->unix_fds = _dbus_memdup(loader->unix_fds, n_unix_fds * sizeof(message->unix_fds[0]));
4145 if (message->unix_fds == NULL)
4147 _dbus_verbose ("Failed to allocate file descriptor array\n");
4152 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
4153 loader->n_unix_fds -= n_unix_fds;
4154 memmove(loader->unix_fds + n_unix_fds, loader->unix_fds, loader->n_unix_fds);
4157 message->unix_fds = NULL;
4163 _dbus_verbose ("Hmm, message claims to come with file descriptors "
4164 "but that's not supported on our platform, disconnecting.\n");
4166 loader->corrupted = TRUE;
4167 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4173 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
4175 if (!_dbus_list_append (&loader->messages, message))
4177 _dbus_verbose ("Failed to append new message to loader queue\n");
4182 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
4183 _dbus_assert (_dbus_string_get_length (&loader->data) >=
4184 (header_len + body_len));
4186 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
4188 _dbus_verbose ("Failed to move body into new message\n");
4193 _dbus_string_delete (&loader->data, 0, header_len + body_len);
4195 /* don't waste more than 2k of memory */
4196 _dbus_string_compact (&loader->data, 2048);
4198 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
4199 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
4201 _dbus_verbose ("Loaded message %p\n", message);
4203 _dbus_assert (!oom);
4204 _dbus_assert (!loader->corrupted);
4205 _dbus_assert (loader->messages != NULL);
4206 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4214 /* does nothing if the message isn't in the list */
4215 _dbus_list_remove_last (&loader->messages, message);
4218 _dbus_assert (!loader->corrupted);
4220 _dbus_assert (loader->corrupted);
4222 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
4228 * Converts buffered data into messages, if we have enough data. If
4229 * we don't have enough data, does nothing.
4231 * @todo we need to check that the proper named header fields exist
4232 * for each message type.
4234 * @todo If a message has unknown type, we should probably eat it
4235 * right here rather than passing it out to applications. However
4236 * it's not an error to see messages of unknown type.
4238 * @param loader the loader.
4239 * @returns #TRUE if we had enough memory to finish.
4242 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
4244 while (!loader->corrupted &&
4245 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
4247 DBusValidity validity;
4248 int byte_order, fields_array_len, header_len, body_len;
4250 if (_dbus_header_have_message_untrusted (loader->max_message_size,
4257 _dbus_string_get_length (&loader->data)))
4259 DBusMessage *message;
4261 _dbus_assert (validity == DBUS_VALID);
4263 message = dbus_message_new_empty_header ();
4264 if (message == NULL)
4267 if (!load_message (loader, message,
4268 byte_order, fields_array_len,
4269 header_len, body_len))
4271 dbus_message_unref (message);
4272 /* load_message() returns false if corrupted or OOM; if
4273 * corrupted then return TRUE for not OOM
4275 return loader->corrupted;
4278 _dbus_assert (loader->messages != NULL);
4279 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4283 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
4285 if (validity != DBUS_VALID)
4287 loader->corrupted = TRUE;
4288 loader->corruption_reason = validity;
4298 * Peeks at first loaded message, returns #NULL if no messages have
4301 * @param loader the loader.
4302 * @returns the next message, or #NULL if none.
4305 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
4307 if (loader->messages)
4308 return loader->messages->data;
4314 * Pops a loaded message (passing ownership of the message
4315 * to the caller). Returns #NULL if no messages have been
4318 * @param loader the loader.
4319 * @returns the next message, or #NULL if none.
4322 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
4324 return _dbus_list_pop_first (&loader->messages);
4328 * Pops a loaded message inside a list link (passing ownership of the
4329 * message and link to the caller). Returns #NULL if no messages have
4332 * @param loader the loader.
4333 * @returns the next message link, or #NULL if none.
4336 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
4338 return _dbus_list_pop_first_link (&loader->messages);
4342 * Returns a popped message link, used to undo a pop.
4344 * @param loader the loader
4345 * @param link the link with a message in it
4348 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
4351 _dbus_list_prepend_link (&loader->messages, link);
4355 * Checks whether the loader is confused due to bad data.
4356 * If messages are received that are invalid, the
4357 * loader gets confused and gives up permanently.
4358 * This state is called "corrupted."
4360 * @param loader the loader
4361 * @returns #TRUE if the loader is hosed.
4364 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
4366 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4367 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4368 return loader->corrupted;
4372 * Checks what kind of bad data confused the loader.
4374 * @param loader the loader
4375 * @returns why the loader is hosed, or DBUS_VALID if it isn't.
4378 _dbus_message_loader_get_corruption_reason (DBusMessageLoader *loader)
4380 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4381 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4383 return loader->corruption_reason;
4387 * Sets the maximum size message we allow.
4389 * @param loader the loader
4390 * @param size the max message size in bytes
4393 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
4396 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
4398 _dbus_verbose ("clamping requested max message size %ld to %d\n",
4399 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
4400 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4402 loader->max_message_size = size;
4406 * Gets the maximum allowed message size in bytes.
4408 * @param loader the loader
4409 * @returns max size in bytes
4412 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
4414 return loader->max_message_size;
4418 * Sets the maximum unix fds per message we allow.
4420 * @param loader the loader
4421 * @param n the max number of unix fds in a message
4424 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader,
4427 if (n > DBUS_MAXIMUM_MESSAGE_UNIX_FDS)
4429 _dbus_verbose ("clamping requested max message unix_fds %ld to %d\n",
4430 n, DBUS_MAXIMUM_MESSAGE_UNIX_FDS);
4431 n = DBUS_MAXIMUM_MESSAGE_UNIX_FDS;
4433 loader->max_message_unix_fds = n;
4437 * Gets the maximum allowed number of unix fds per message
4439 * @param loader the loader
4440 * @returns max unix fds
4443 _dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
4445 return loader->max_message_unix_fds;
4448 static DBusDataSlotAllocator slot_allocator =
4449 _DBUS_DATA_SLOT_ALLOCATOR_INIT (_DBUS_LOCK_NAME (message_slots));
4452 * Allocates an integer ID to be used for storing application-specific
4453 * data on any DBusMessage. The allocated ID may then be used
4454 * with dbus_message_set_data() and dbus_message_get_data().
4455 * The passed-in slot must be initialized to -1, and is filled in
4456 * with the slot ID. If the passed-in slot is not -1, it's assumed
4457 * to be already allocated, and its refcount is incremented.
4459 * The allocated slot is global, i.e. all DBusMessage objects will
4460 * have a slot with the given integer ID reserved.
4462 * @param slot_p address of a global variable storing the slot
4463 * @returns #FALSE on failure (no memory)
4466 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
4468 return _dbus_data_slot_allocator_alloc (&slot_allocator,
4473 * Deallocates a global ID for message data slots.
4474 * dbus_message_get_data() and dbus_message_set_data() may no
4475 * longer be used with this slot. Existing data stored on existing
4476 * DBusMessage objects will be freed when the message is
4477 * finalized, but may not be retrieved (and may only be replaced if
4478 * someone else reallocates the slot). When the refcount on the
4479 * passed-in slot reaches 0, it is set to -1.
4481 * @param slot_p address storing the slot to deallocate
4484 dbus_message_free_data_slot (dbus_int32_t *slot_p)
4486 _dbus_return_if_fail (*slot_p >= 0);
4488 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
4492 * Stores a pointer on a DBusMessage, along
4493 * with an optional function to be used for freeing
4494 * the data when the data is set again, or when
4495 * the message is finalized. The slot number
4496 * must have been allocated with dbus_message_allocate_data_slot().
4498 * @param message the message
4499 * @param slot the slot number
4500 * @param data the data to store
4501 * @param free_data_func finalizer function for the data
4502 * @returns #TRUE if there was enough memory to store the data
4505 dbus_message_set_data (DBusMessage *message,
4508 DBusFreeFunction free_data_func)
4510 DBusFreeFunction old_free_func;
4514 _dbus_return_val_if_fail (message != NULL, FALSE);
4515 _dbus_return_val_if_fail (slot >= 0, FALSE);
4517 retval = _dbus_data_slot_list_set (&slot_allocator,
4518 &message->slot_list,
4519 slot, data, free_data_func,
4520 &old_free_func, &old_data);
4524 /* Do the actual free outside the message lock */
4526 (* old_free_func) (old_data);
4533 * Retrieves data previously set with dbus_message_set_data().
4534 * The slot must still be allocated (must not have been freed).
4536 * @param message the message
4537 * @param slot the slot to get data from
4538 * @returns the data, or #NULL if not found
4541 dbus_message_get_data (DBusMessage *message,
4546 _dbus_return_val_if_fail (message != NULL, NULL);
4548 res = _dbus_data_slot_list_get (&slot_allocator,
4549 &message->slot_list,
4556 * Utility function to convert a machine-readable (not translated)
4557 * string into a D-Bus message type.
4560 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
4561 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
4562 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
4563 * "error" -> DBUS_MESSAGE_TYPE_ERROR
4564 * anything else -> DBUS_MESSAGE_TYPE_INVALID
4569 dbus_message_type_from_string (const char *type_str)
4571 if (strcmp (type_str, "method_call") == 0)
4572 return DBUS_MESSAGE_TYPE_METHOD_CALL;
4573 if (strcmp (type_str, "method_return") == 0)
4574 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
4575 else if (strcmp (type_str, "signal") == 0)
4576 return DBUS_MESSAGE_TYPE_SIGNAL;
4577 else if (strcmp (type_str, "error") == 0)
4578 return DBUS_MESSAGE_TYPE_ERROR;
4580 return DBUS_MESSAGE_TYPE_INVALID;
4584 * Utility function to convert a D-Bus message type into a
4585 * machine-readable string (not translated).
4588 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
4589 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
4590 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
4591 * DBUS_MESSAGE_TYPE_ERROR -> "error"
4592 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
4597 dbus_message_type_to_string (int type)
4601 case DBUS_MESSAGE_TYPE_METHOD_CALL:
4602 return "method_call";
4603 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
4604 return "method_return";
4605 case DBUS_MESSAGE_TYPE_SIGNAL:
4607 case DBUS_MESSAGE_TYPE_ERROR:
4615 * Turn a DBusMessage into the marshalled form as described in the D-Bus
4618 * Generally, this function is only useful for encapsulating D-Bus messages in
4619 * a different protocol.
4621 * @param msg the DBusMessage
4622 * @param marshalled_data_p the location to save the marshalled form to
4623 * @param len_p the location to save the length of the marshalled form to
4624 * @returns #FALSE if there was not enough memory
4627 dbus_message_marshal (DBusMessage *msg,
4628 char **marshalled_data_p,
4632 dbus_bool_t was_locked;
4634 _dbus_return_val_if_fail (msg != NULL, FALSE);
4635 _dbus_return_val_if_fail (marshalled_data_p != NULL, FALSE);
4636 _dbus_return_val_if_fail (len_p != NULL, FALSE);
4638 if (!_dbus_string_init (&tmp))
4641 /* Ensure the message is locked, to ensure the length header is filled in. */
4642 was_locked = msg->locked;
4645 dbus_message_lock (msg);
4647 if (!_dbus_string_copy (&(msg->header.data), 0, &tmp, 0))
4650 *len_p = _dbus_string_get_length (&tmp);
4652 if (!_dbus_string_copy (&(msg->body), 0, &tmp, *len_p))
4655 *len_p = _dbus_string_get_length (&tmp);
4657 if (!_dbus_string_steal_data (&tmp, marshalled_data_p))
4660 _dbus_string_free (&tmp);
4663 msg->locked = FALSE;
4668 _dbus_string_free (&tmp);
4671 msg->locked = FALSE;
4677 * Demarshal a D-Bus message from the format described in the D-Bus
4680 * Generally, this function is only useful for encapsulating D-Bus messages in
4681 * a different protocol.
4683 * @param str the marshalled DBusMessage
4684 * @param len the length of str
4685 * @param error the location to save errors to
4686 * @returns #NULL if there was an error
4689 dbus_message_demarshal (const char *str,
4693 DBusMessageLoader *loader;
4697 _dbus_return_val_if_fail (str != NULL, NULL);
4699 loader = _dbus_message_loader_new ();
4704 _dbus_message_loader_get_buffer (loader, &buffer);
4705 _dbus_string_append_len (buffer, str, len);
4706 _dbus_message_loader_return_buffer (loader, buffer, len);
4708 if (!_dbus_message_loader_queue_messages (loader))
4711 if (_dbus_message_loader_get_is_corrupted (loader))
4714 msg = _dbus_message_loader_pop_message (loader);
4719 _dbus_message_loader_unref (loader);
4723 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS, "Message is corrupted (%s)",
4724 _dbus_validity_to_error_message (loader->corruption_reason));
4725 _dbus_message_loader_unref (loader);
4729 _DBUS_SET_OOM (error);
4730 _dbus_message_loader_unref (loader);
4735 * Returns the number of bytes required to be in the buffer to demarshal a
4738 * Generally, this function is only useful for encapsulating D-Bus messages in
4739 * a different protocol.
4741 * @param buf data to be marshalled
4742 * @param len the length of @p buf
4743 * @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
4747 dbus_message_demarshal_bytes_needed(const char *buf,
4751 int byte_order, fields_array_len, header_len, body_len;
4752 DBusValidity validity = DBUS_VALID;
4755 if (!buf || len < DBUS_MINIMUM_HEADER_SIZE)
4758 if (len > DBUS_MAXIMUM_MESSAGE_LENGTH)
4759 len = DBUS_MAXIMUM_MESSAGE_LENGTH;
4760 _dbus_string_init_const_len (&str, buf, len);
4762 validity = DBUS_VALID;
4764 = _dbus_header_have_message_untrusted(DBUS_MAXIMUM_MESSAGE_LENGTH,
4765 &validity, &byte_order,
4771 _dbus_string_free (&str);
4773 if (validity == DBUS_VALID)
4775 _dbus_assert (have_message || (header_len + body_len) > len);
4776 (void) have_message; /* unused unless asserting */
4777 return header_len + body_len;
4781 return -1; /* broken! */
4787 /* tests in dbus-message-util.c */