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;
400 dbus_message_unlock (DBusMessage *message)
402 message->locked = FALSE;
406 set_or_delete_string_field (DBusMessage *message,
412 return _dbus_header_delete_field (&message->header, field);
414 return _dbus_header_set_field_basic (&message->header,
421 /* Probably we don't need to use this */
423 * Sets the signature of the message, i.e. the arguments in the
424 * message payload. The signature includes only "in" arguments for
425 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
426 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
427 * what you might expect (it does not include the signature of the
428 * entire C++-style method).
430 * The signature is a string made up of type codes such as
431 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
432 * the value of #DBUS_TYPE_INVALID). The macros such as
433 * #DBUS_TYPE_INT32 evaluate to integers; to assemble a signature you
434 * may find it useful to use the string forms, such as
435 * #DBUS_TYPE_INT32_AS_STRING.
437 * An "unset" or #NULL signature is considered the same as an empty
438 * signature. In fact dbus_message_get_signature() will never return
441 * @param message the message
442 * @param signature the type signature or #NULL to unset
443 * @returns #FALSE if no memory
446 _dbus_message_set_signature (DBusMessage *message,
447 const char *signature)
449 _dbus_return_val_if_fail (message != NULL, FALSE);
450 _dbus_return_val_if_fail (!message->locked, FALSE);
451 _dbus_return_val_if_fail (signature == NULL ||
452 _dbus_check_is_valid_signature (signature));
453 /* can't delete the signature if you have a message body */
454 _dbus_return_val_if_fail (_dbus_string_get_length (&message->body) == 0 ||
457 return set_or_delete_string_field (message,
458 DBUS_HEADER_FIELD_SIGNATURE,
466 * We cache some DBusMessage to reduce the overhead of allocating
467 * them. In my profiling this consistently made about an 8%
468 * difference. It avoids the malloc for the message, the malloc for
469 * the slot list, the malloc for the header string and body string,
470 * and the associated free() calls. It does introduce another global
471 * lock which could be a performance issue in certain cases.
473 * For the echo client/server the round trip time goes from around
474 * .000077 to .000069 with the message cache on my laptop. The sysprof
475 * change is as follows (numbers are cumulative percentage):
477 * with message cache implemented as array as it is now (0.000069 per):
478 * new_empty_header 1.46
479 * mutex_lock 0.56 # i.e. _DBUS_LOCK(message_cache)
485 * mutex_lock 0.33 # i.e. _DBUS_LOCK(message_cache)
488 * with message cache implemented as list (0.000070 per roundtrip):
489 * new_empty_header 2.72
490 * list_pop_first 1.88
494 * without cache (0.000077 per roundtrip):
495 * new_empty_header 6.7
496 * string_init_preallocated 3.43
505 * If you implement the message_cache with a list, the primary reason
506 * it's slower is that you add another thread lock (on the DBusList
510 /** Avoid caching huge messages */
511 #define MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE
513 /** Avoid caching too many messages */
514 #define MAX_MESSAGE_CACHE_SIZE 5
516 /* Protected by _DBUS_LOCK (message_cache) */
517 static DBusMessage *message_cache[MAX_MESSAGE_CACHE_SIZE];
518 static int message_cache_count = 0;
519 static dbus_bool_t message_cache_shutdown_registered = FALSE;
522 dbus_message_cache_shutdown (void *data)
526 if (!_DBUS_LOCK (message_cache))
527 _dbus_assert_not_reached ("we would have initialized global locks "
528 "before registering a shutdown function");
531 while (i < MAX_MESSAGE_CACHE_SIZE)
533 if (message_cache[i])
534 dbus_message_finalize (message_cache[i]);
539 message_cache_count = 0;
540 message_cache_shutdown_registered = FALSE;
542 _DBUS_UNLOCK (message_cache);
546 * Tries to get a message from the message cache. The retrieved
547 * message will have junk in it, so it still needs to be cleared out
548 * in dbus_message_new_empty_header()
550 * @returns the message, or #NULL if none cached
553 dbus_message_get_cached (void)
555 DBusMessage *message;
560 if (!_DBUS_LOCK (message_cache))
562 /* we'd have initialized global locks before caching anything,
563 * so there can't be anything in the cache */
567 _dbus_assert (message_cache_count >= 0);
569 if (message_cache_count == 0)
571 _DBUS_UNLOCK (message_cache);
575 /* This is not necessarily true unless count > 0, and
576 * message_cache is uninitialized until the shutdown is
579 _dbus_assert (message_cache_shutdown_registered);
582 while (i < MAX_MESSAGE_CACHE_SIZE)
584 if (message_cache[i])
586 message = message_cache[i];
587 message_cache[i] = NULL;
588 message_cache_count -= 1;
593 _dbus_assert (message_cache_count >= 0);
594 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
595 _dbus_assert (message != NULL);
597 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
599 _dbus_assert (message->counters == NULL);
601 _DBUS_UNLOCK (message_cache);
606 #ifdef HAVE_UNIX_FD_PASSING
608 close_unix_fds(int *fds, unsigned *n_fds)
618 for (i = 0; i < *n_fds; i++)
620 if (!_dbus_close(fds[i], &e))
622 _dbus_warn("Failed to close file descriptor: %s\n", e.message);
629 /* We don't free the array here, in case we can recycle it later */
634 free_counter (void *element,
637 DBusCounter *counter = element;
638 DBusMessage *message = data;
640 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
641 #ifdef HAVE_UNIX_FD_PASSING
642 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
645 _dbus_counter_notify (counter);
646 _dbus_counter_unref (counter);
650 * Tries to cache a message, otherwise finalize it.
652 * @param message the message
655 dbus_message_cache_or_finalize (DBusMessage *message)
657 dbus_bool_t was_cached;
660 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
662 /* This calls application code and has to be done first thing
663 * without holding the lock
665 _dbus_data_slot_list_clear (&message->slot_list);
667 _dbus_list_foreach (&message->counters,
668 free_counter, message);
669 _dbus_list_clear (&message->counters);
671 #ifdef HAVE_UNIX_FD_PASSING
672 close_unix_fds(message->unix_fds, &message->n_unix_fds);
677 if (!_DBUS_LOCK (message_cache))
679 /* The only way to get a non-null message goes through
680 * dbus_message_get_cached() which takes the lock. */
681 _dbus_assert_not_reached ("we would have initialized global locks "
682 "the first time we constructed a message");
685 if (!message_cache_shutdown_registered)
687 _dbus_assert (message_cache_count == 0);
689 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
693 while (i < MAX_MESSAGE_CACHE_SIZE)
695 message_cache[i] = NULL;
699 message_cache_shutdown_registered = TRUE;
702 _dbus_assert (message_cache_count >= 0);
704 if (!_dbus_enable_message_cache ())
707 if ((_dbus_string_get_length (&message->header.data) +
708 _dbus_string_get_length (&message->body)) >
709 MAX_MESSAGE_SIZE_TO_CACHE)
712 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
715 /* Find empty slot */
717 while (message_cache[i] != NULL)
720 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
722 _dbus_assert (message_cache[i] == NULL);
723 message_cache[i] = message;
724 message_cache_count += 1;
726 #ifndef DBUS_DISABLE_CHECKS
727 message->in_cache = TRUE;
731 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
733 _DBUS_UNLOCK (message_cache);
736 dbus_message_finalize (message);
739 #if defined(DBUS_ENABLE_CHECKS) || defined(DBUS_ENABLE_ASSERT)
741 _dbus_message_iter_check (DBusMessageRealIter *iter)
747 _dbus_warn_check_failed ("dbus message iterator is NULL\n");
751 byte_order = _dbus_header_get_byte_order (&iter->message->header);
753 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
755 if (iter->u.reader.byte_order != byte_order)
757 _dbus_warn_check_failed ("dbus message changed byte order since iterator was created\n");
760 /* because we swap the message into compiler order when you init an iter */
761 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
763 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
765 if (iter->u.writer.byte_order != byte_order)
767 _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created\n");
770 /* because we swap the message into compiler order when you init an iter */
771 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
775 _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted\n");
779 if (iter->changed_stamp != iter->message->changed_stamp)
781 _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
787 #endif /* DBUS_ENABLE_CHECKS || DBUS_ENABLE_ASSERT */
790 * Implementation of the varargs arg-getting functions.
791 * dbus_message_get_args() is the place to go for complete
794 * @todo This may leak memory and file descriptors if parsing fails. See #21259
796 * @see dbus_message_get_args
797 * @param iter the message iter
798 * @param error error to be filled in
799 * @param first_arg_type type of the first argument
800 * @param var_args return location for first argument, followed by list of type/location pairs
801 * @returns #FALSE if error was set
804 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
809 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
810 int spec_type, msg_type, i;
813 _dbus_assert (_dbus_message_iter_check (real));
817 spec_type = first_arg_type;
820 while (spec_type != DBUS_TYPE_INVALID)
822 msg_type = dbus_message_iter_get_arg_type (iter);
824 if (msg_type != spec_type)
826 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
827 "Argument %d is specified to be of type \"%s\", but "
828 "is actually of type \"%s\"\n", i,
829 _dbus_type_to_string (spec_type),
830 _dbus_type_to_string (msg_type));
835 if (spec_type == DBUS_TYPE_UNIX_FD)
837 #ifdef HAVE_UNIX_FD_PASSING
841 pfd = va_arg (var_args, int*);
844 _dbus_type_reader_read_basic(&real->u.reader, &idx);
846 if (idx.u32 >= real->message->n_unix_fds)
848 dbus_set_error (error, DBUS_ERROR_INCONSISTENT_MESSAGE,
849 "Message refers to file descriptor at index %i,"
850 "but has only %i descriptors attached.\n",
852 real->message->n_unix_fds);
856 if ((nfd = _dbus_dup(real->message->unix_fds[idx.u32], error)) < 0)
861 dbus_set_error (error, DBUS_ERROR_NOT_SUPPORTED,
862 "Platform does not support file desciptor passing.\n");
866 else if (dbus_type_is_basic (spec_type))
870 ptr = va_arg (var_args, DBusBasicValue*);
872 _dbus_assert (ptr != NULL);
874 _dbus_type_reader_read_basic (&real->u.reader,
877 else if (spec_type == DBUS_TYPE_ARRAY)
880 int spec_element_type;
881 const DBusBasicValue **ptr;
883 DBusTypeReader array;
885 spec_element_type = va_arg (var_args, int);
886 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
888 if (spec_element_type != element_type)
890 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
891 "Argument %d is specified to be an array of \"%s\", but "
892 "is actually an array of \"%s\"\n",
894 _dbus_type_to_string (spec_element_type),
895 _dbus_type_to_string (element_type));
900 if (dbus_type_is_fixed (spec_element_type) &&
901 element_type != DBUS_TYPE_UNIX_FD)
903 ptr = va_arg (var_args, const DBusBasicValue**);
904 n_elements_p = va_arg (var_args, int*);
906 _dbus_assert (ptr != NULL);
907 _dbus_assert (n_elements_p != NULL);
909 _dbus_type_reader_recurse (&real->u.reader, &array);
911 _dbus_type_reader_read_fixed_multi (&array,
912 (void *) ptr, n_elements_p);
914 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
920 str_array_p = va_arg (var_args, char***);
921 n_elements_p = va_arg (var_args, int*);
923 _dbus_assert (str_array_p != NULL);
924 _dbus_assert (n_elements_p != NULL);
926 /* Count elements in the array */
927 _dbus_type_reader_recurse (&real->u.reader, &array);
930 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
933 _dbus_type_reader_next (&array);
936 str_array = dbus_new0 (char*, n_elements + 1);
937 if (str_array == NULL)
939 _DBUS_SET_OOM (error);
943 /* Now go through and dup each string */
944 _dbus_type_reader_recurse (&real->u.reader, &array);
947 while (i < n_elements)
950 _dbus_type_reader_read_basic (&array,
953 str_array[i] = _dbus_strdup (s);
954 if (str_array[i] == NULL)
956 dbus_free_string_array (str_array);
957 _DBUS_SET_OOM (error);
963 if (!_dbus_type_reader_next (&array))
964 _dbus_assert (i == n_elements);
967 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
968 _dbus_assert (i == n_elements);
969 _dbus_assert (str_array[i] == NULL);
971 *str_array_p = str_array;
972 *n_elements_p = n_elements;
974 #ifndef DBUS_DISABLE_CHECKS
977 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
978 _DBUS_FUNCTION_NAME);
983 #ifndef DBUS_DISABLE_CHECKS
986 _dbus_warn ("you can only read arrays and basic types with %s for now\n",
987 _DBUS_FUNCTION_NAME);
992 spec_type = va_arg (var_args, int);
993 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
995 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
996 "Message has only %d arguments, but more were expected", i);
1013 * @defgroup DBusMessage DBusMessage
1015 * @brief Message to be sent or received over a #DBusConnection.
1017 * A DBusMessage is the most basic unit of communication over a
1018 * DBusConnection. A DBusConnection represents a stream of messages
1019 * received from a remote application, and a stream of messages
1020 * sent to a remote application.
1022 * A message has a message type, returned from
1023 * dbus_message_get_type(). This indicates whether the message is a
1024 * method call, a reply to a method call, a signal, or an error reply.
1026 * A message has header fields such as the sender, destination, method
1027 * or signal name, and so forth. DBusMessage has accessor functions for
1028 * these, such as dbus_message_get_member().
1030 * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
1031 * and dbus_message_is_error() check several header fields at once and are
1032 * slightly more efficient than checking the header fields with individual
1033 * accessor functions.
1035 * Finally, a message has arguments. The number and types of arguments
1036 * are in the message's signature header field (accessed with
1037 * dbus_message_get_signature()). Simple argument values are usually
1038 * retrieved with dbus_message_get_args() but more complex values such
1039 * as structs may require the use of #DBusMessageIter.
1041 * The D-Bus specification goes into some more detail about header fields and
1048 * @typedef DBusMessage
1050 * Opaque data type representing a message received from or to be
1051 * sent to another application.
1055 * Returns the serial of a message or 0 if none has been specified.
1056 * The message's serial number is provided by the application sending
1057 * the message and is used to identify replies to this message.
1059 * All messages received on a connection will have a serial provided
1060 * by the remote application.
1062 * For messages you're sending, dbus_connection_send() will assign a
1063 * serial and return it to you.
1065 * @param message the message
1066 * @returns the serial
1069 dbus_message_get_serial (DBusMessage *message)
1071 _dbus_return_val_if_fail (message != NULL, 0);
1073 return _dbus_header_get_serial (&message->header);
1077 * Sets the reply serial of a message (the serial of the message this
1080 * @param message the message
1081 * @param reply_serial the serial we're replying to
1082 * @returns #FALSE if not enough memory
1085 dbus_message_set_reply_serial (DBusMessage *message,
1086 dbus_uint32_t reply_serial)
1088 _dbus_return_val_if_fail (message != NULL, FALSE);
1089 _dbus_return_val_if_fail (!message->locked, FALSE);
1090 _dbus_return_val_if_fail (reply_serial != 0, FALSE); /* 0 is invalid */
1092 return _dbus_header_set_field_basic (&message->header,
1093 DBUS_HEADER_FIELD_REPLY_SERIAL,
1099 * Returns the serial that the message is a reply to or 0 if none.
1101 * @param message the message
1102 * @returns the reply serial
1105 dbus_message_get_reply_serial (DBusMessage *message)
1107 dbus_uint32_t v_UINT32;
1109 _dbus_return_val_if_fail (message != NULL, 0);
1111 if (_dbus_header_get_field_basic (&message->header,
1112 DBUS_HEADER_FIELD_REPLY_SERIAL,
1121 dbus_message_finalize (DBusMessage *message)
1123 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1125 /* This calls application callbacks! */
1126 _dbus_data_slot_list_free (&message->slot_list);
1128 _dbus_list_foreach (&message->counters,
1129 free_counter, message);
1130 _dbus_list_clear (&message->counters);
1132 _dbus_header_free (&message->header);
1133 _dbus_string_free (&message->body);
1135 #ifdef HAVE_UNIX_FD_PASSING
1136 close_unix_fds(message->unix_fds, &message->n_unix_fds);
1137 dbus_free(message->unix_fds);
1140 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1142 dbus_free (message);
1146 dbus_message_new_empty_header (void)
1148 DBusMessage *message;
1149 dbus_bool_t from_cache;
1151 message = dbus_message_get_cached ();
1153 if (message != NULL)
1160 message = dbus_new0 (DBusMessage, 1);
1161 if (message == NULL)
1163 #ifndef DBUS_DISABLE_CHECKS
1164 message->generation = _dbus_current_generation;
1167 #ifdef HAVE_UNIX_FD_PASSING
1168 message->unix_fds = NULL;
1169 message->n_unix_fds_allocated = 0;
1173 _dbus_atomic_inc (&message->refcount);
1175 _dbus_message_trace_ref (message, 0, 1, "new_empty_header");
1177 message->locked = FALSE;
1178 #ifndef DBUS_DISABLE_CHECKS
1179 message->in_cache = FALSE;
1181 message->counters = NULL;
1182 message->size_counter_delta = 0;
1183 message->changed_stamp = 0;
1185 #ifdef HAVE_UNIX_FD_PASSING
1186 message->n_unix_fds = 0;
1187 message->n_unix_fds_allocated = 0;
1188 message->unix_fd_counter_delta = 0;
1192 _dbus_data_slot_list_init (&message->slot_list);
1196 _dbus_header_reinit (&message->header);
1197 _dbus_string_set_length (&message->body, 0);
1201 if (!_dbus_header_init (&message->header))
1203 dbus_free (message);
1207 if (!_dbus_string_init_preallocated (&message->body, 32))
1209 _dbus_header_free (&message->header);
1210 dbus_free (message);
1219 * Constructs a new message of the given message type.
1220 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
1221 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
1223 * Usually you want to use dbus_message_new_method_call(),
1224 * dbus_message_new_method_return(), dbus_message_new_signal(),
1225 * or dbus_message_new_error() instead.
1227 * @param message_type type of message
1228 * @returns new message or #NULL if no memory
1231 dbus_message_new (int message_type)
1233 DBusMessage *message;
1235 _dbus_return_val_if_fail (message_type != DBUS_MESSAGE_TYPE_INVALID, NULL);
1237 message = dbus_message_new_empty_header ();
1238 if (message == NULL)
1241 if (!_dbus_header_create (&message->header,
1242 DBUS_COMPILER_BYTE_ORDER,
1244 NULL, NULL, NULL, NULL, NULL))
1246 dbus_message_unref (message);
1254 * Constructs a new message to invoke a method on a remote
1255 * object. Returns #NULL if memory can't be allocated for the
1256 * message. The destination may be #NULL in which case no destination
1257 * is set; this is appropriate when using D-Bus in a peer-to-peer
1258 * context (no message bus). The interface may be #NULL, which means
1259 * that if multiple methods with the given name exist it is undefined
1260 * which one will be invoked.
1262 * The path and method names may not be #NULL.
1264 * Destination, path, interface, and method name can't contain
1265 * any invalid characters (see the D-Bus specification).
1267 * @param destination name that the message should be sent to or #NULL
1268 * @param path object path the message should be sent to
1269 * @param iface interface to invoke method on, or #NULL
1270 * @param method method to invoke
1272 * @returns a new DBusMessage, free with dbus_message_unref()
1275 dbus_message_new_method_call (const char *destination,
1280 DBusMessage *message;
1282 _dbus_return_val_if_fail (path != NULL, NULL);
1283 _dbus_return_val_if_fail (method != NULL, NULL);
1284 _dbus_return_val_if_fail (destination == NULL ||
1285 _dbus_check_is_valid_bus_name (destination), NULL);
1286 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1287 _dbus_return_val_if_fail (iface == NULL ||
1288 _dbus_check_is_valid_interface (iface), NULL);
1289 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
1291 message = dbus_message_new_empty_header ();
1292 if (message == NULL)
1295 if (!_dbus_header_create (&message->header,
1296 DBUS_COMPILER_BYTE_ORDER,
1297 DBUS_MESSAGE_TYPE_METHOD_CALL,
1298 destination, path, iface, method, NULL))
1300 dbus_message_unref (message);
1308 * Constructs a message that is a reply to a method call. Returns
1309 * #NULL if memory can't be allocated for the message.
1311 * @param method_call the message being replied to
1312 * @returns a new DBusMessage, free with dbus_message_unref()
1315 dbus_message_new_method_return (DBusMessage *method_call)
1317 DBusMessage *message;
1320 _dbus_return_val_if_fail (method_call != NULL, NULL);
1322 sender = dbus_message_get_sender (method_call);
1324 /* sender is allowed to be null here in peer-to-peer case */
1326 message = dbus_message_new_empty_header ();
1327 if (message == NULL)
1330 if (!_dbus_header_create (&message->header,
1331 DBUS_COMPILER_BYTE_ORDER,
1332 DBUS_MESSAGE_TYPE_METHOD_RETURN,
1333 sender, NULL, NULL, NULL, NULL))
1335 dbus_message_unref (message);
1339 dbus_message_set_no_reply (message, TRUE);
1341 if (!dbus_message_set_reply_serial (message,
1342 dbus_message_get_serial (method_call)))
1344 dbus_message_unref (message);
1352 * Constructs a new message representing a signal emission. Returns
1353 * #NULL if memory can't be allocated for the message. A signal is
1354 * identified by its originating object path, interface, and the name
1357 * Path, interface, and signal name must all be valid (the D-Bus
1358 * specification defines the syntax of these fields).
1360 * @param path the path to the object emitting the signal
1361 * @param iface the interface the signal is emitted from
1362 * @param name name of the signal
1363 * @returns a new DBusMessage, free with dbus_message_unref()
1366 dbus_message_new_signal (const char *path,
1370 DBusMessage *message;
1372 _dbus_return_val_if_fail (path != NULL, NULL);
1373 _dbus_return_val_if_fail (iface != NULL, NULL);
1374 _dbus_return_val_if_fail (name != NULL, NULL);
1375 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1376 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (iface), NULL);
1377 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
1379 message = dbus_message_new_empty_header ();
1380 if (message == NULL)
1383 if (!_dbus_header_create (&message->header,
1384 DBUS_COMPILER_BYTE_ORDER,
1385 DBUS_MESSAGE_TYPE_SIGNAL,
1386 NULL, path, iface, name, NULL))
1388 dbus_message_unref (message);
1392 dbus_message_set_no_reply (message, TRUE);
1398 * Creates a new message that is an error reply to another message.
1399 * Error replies are most common in response to method calls, but
1400 * can be returned in reply to any message.
1402 * The error name must be a valid error name according to the syntax
1403 * given in the D-Bus specification. If you don't want to make
1404 * up an error name just use #DBUS_ERROR_FAILED.
1406 * @param reply_to the message we're replying to
1407 * @param error_name the error name
1408 * @param error_message the error message string (or #NULL for none, but please give a message)
1409 * @returns a new error message object, free with dbus_message_unref()
1412 dbus_message_new_error (DBusMessage *reply_to,
1413 const char *error_name,
1414 const char *error_message)
1416 DBusMessage *message;
1418 DBusMessageIter iter;
1420 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1421 _dbus_return_val_if_fail (error_name != NULL, NULL);
1422 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1424 sender = dbus_message_get_sender (reply_to);
1426 /* sender may be NULL for non-message-bus case or
1427 * when the message bus is dealing with an unregistered
1430 message = dbus_message_new_empty_header ();
1431 if (message == NULL)
1434 if (!_dbus_header_create (&message->header,
1435 DBUS_COMPILER_BYTE_ORDER,
1436 DBUS_MESSAGE_TYPE_ERROR,
1437 sender, NULL, NULL, NULL, error_name))
1439 dbus_message_unref (message);
1443 dbus_message_set_no_reply (message, TRUE);
1445 if (!dbus_message_set_reply_serial (message,
1446 dbus_message_get_serial (reply_to)))
1448 dbus_message_unref (message);
1452 if (error_message != NULL)
1454 dbus_message_iter_init_append (message, &iter);
1455 if (!dbus_message_iter_append_basic (&iter,
1459 dbus_message_unref (message);
1468 * Creates a new message that is an error reply to another message, allowing
1469 * you to use printf formatting.
1471 * See dbus_message_new_error() for details - this function is the same
1472 * aside from the printf formatting.
1474 * @todo add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to
1475 * public header, see DBUS_DEPRECATED for an example)
1477 * @param reply_to the original message
1478 * @param error_name the error name
1479 * @param error_format the error message format as with printf
1480 * @param ... format string arguments
1481 * @returns a new error message
1484 dbus_message_new_error_printf (DBusMessage *reply_to,
1485 const char *error_name,
1486 const char *error_format,
1491 DBusMessage *message;
1493 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1494 _dbus_return_val_if_fail (error_name != NULL, NULL);
1495 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1497 if (!_dbus_string_init (&str))
1500 va_start (args, error_format);
1502 if (_dbus_string_append_printf_valist (&str, error_format, args))
1503 message = dbus_message_new_error (reply_to, error_name,
1504 _dbus_string_get_const_data (&str));
1508 _dbus_string_free (&str);
1517 * Creates a new message that is an exact replica of the message
1518 * specified, except that its refcount is set to 1, its message serial
1519 * is reset to 0, and if the original message was "locked" (in the
1520 * outgoing message queue and thus not modifiable) the new message
1521 * will not be locked.
1523 * @todo This function can't be used in programs that try to recover from OOM errors.
1525 * @param message the message
1526 * @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.
1529 dbus_message_copy (const DBusMessage *message)
1531 DBusMessage *retval;
1533 _dbus_return_val_if_fail (message != NULL, NULL);
1535 retval = dbus_new0 (DBusMessage, 1);
1539 _dbus_atomic_inc (&retval->refcount);
1541 retval->locked = FALSE;
1542 #ifndef DBUS_DISABLE_CHECKS
1543 retval->generation = message->generation;
1546 if (!_dbus_header_copy (&message->header, &retval->header))
1552 if (!_dbus_string_init_preallocated (&retval->body,
1553 _dbus_string_get_length (&message->body)))
1555 _dbus_header_free (&retval->header);
1560 if (!_dbus_string_copy (&message->body, 0,
1564 #ifdef HAVE_UNIX_FD_PASSING
1565 retval->unix_fds = dbus_new(int, message->n_unix_fds);
1566 if (retval->unix_fds == NULL && message->n_unix_fds > 0)
1569 retval->n_unix_fds_allocated = message->n_unix_fds;
1571 for (retval->n_unix_fds = 0;
1572 retval->n_unix_fds < message->n_unix_fds;
1573 retval->n_unix_fds++)
1575 retval->unix_fds[retval->n_unix_fds] = _dbus_dup(message->unix_fds[retval->n_unix_fds], NULL);
1577 if (retval->unix_fds[retval->n_unix_fds] < 0)
1583 _dbus_message_trace_ref (retval, 0, 1, "copy");
1587 _dbus_header_free (&retval->header);
1588 _dbus_string_free (&retval->body);
1590 #ifdef HAVE_UNIX_FD_PASSING
1591 close_unix_fds(retval->unix_fds, &retval->n_unix_fds);
1592 dbus_free(retval->unix_fds);
1602 * Increments the reference count of a DBusMessage.
1604 * @param message the message
1605 * @returns the message
1606 * @see dbus_message_unref
1609 dbus_message_ref (DBusMessage *message)
1611 dbus_int32_t old_refcount;
1613 _dbus_return_val_if_fail (message != NULL, NULL);
1614 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1615 _dbus_return_val_if_fail (!message->in_cache, NULL);
1617 old_refcount = _dbus_atomic_inc (&message->refcount);
1618 _dbus_assert (old_refcount >= 1);
1619 _dbus_message_trace_ref (message, old_refcount, old_refcount + 1, "ref");
1625 * Decrements the reference count of a DBusMessage, freeing the
1626 * message if the count reaches 0.
1628 * @param message the message
1629 * @see dbus_message_ref
1632 dbus_message_unref (DBusMessage *message)
1634 dbus_int32_t old_refcount;
1636 _dbus_return_if_fail (message != NULL);
1637 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1638 _dbus_return_if_fail (!message->in_cache);
1640 old_refcount = _dbus_atomic_dec (&message->refcount);
1642 _dbus_assert (old_refcount >= 1);
1644 _dbus_message_trace_ref (message, old_refcount, old_refcount - 1, "unref");
1646 if (old_refcount == 1)
1648 /* Calls application callbacks! */
1649 dbus_message_cache_or_finalize (message);
1654 * Gets the type of a message. Types include
1655 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1656 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1657 * types are allowed and all code must silently ignore messages of
1658 * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
1660 * @param message the message
1661 * @returns the type of the message
1664 dbus_message_get_type (DBusMessage *message)
1666 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1668 return _dbus_header_get_message_type (&message->header);
1672 * Appends fields to a message given a variable argument list. The
1673 * variable argument list should contain the type of each argument
1674 * followed by the value to append. Appendable types are basic types,
1675 * and arrays of fixed-length basic types (except arrays of Unix file
1676 * descriptors). To append variable-length basic types, or any more
1677 * complex value, you have to use an iterator rather than this
1680 * To append a basic type, specify its type code followed by the
1681 * address of the value. For example:
1685 * dbus_int32_t v_INT32 = 42;
1686 * const char *v_STRING = "Hello World";
1687 * dbus_message_append_args (message,
1688 * DBUS_TYPE_INT32, &v_INT32,
1689 * DBUS_TYPE_STRING, &v_STRING,
1690 * DBUS_TYPE_INVALID);
1693 * To append an array of fixed-length basic types (except Unix file
1694 * descriptors), pass in the DBUS_TYPE_ARRAY typecode, the element
1695 * typecode, the address of the array pointer, and a 32-bit integer
1696 * giving the number of elements in the array. So for example: @code
1697 * const dbus_int32_t array[] = { 1, 2, 3 }; const dbus_int32_t
1698 * *v_ARRAY = array; dbus_message_append_args (message,
1699 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3, DBUS_TYPE_INVALID);
1702 * This function does not support arrays of Unix file descriptors. If
1703 * you need those you need to manually recurse into the array.
1705 * For Unix file descriptors this function will internally duplicate
1706 * the descriptor you passed in. Hence you may close the descriptor
1707 * immediately after this call.
1709 * @warning in C, given "int array[]", "&array == array" (the
1710 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
1711 * So if you're using an array instead of a pointer you have to create
1712 * a pointer variable, assign the array to it, then take the address
1713 * of the pointer variable. For strings it works to write
1714 * const char *array = "Hello" and then use &array though.
1716 * The last argument to this function must be #DBUS_TYPE_INVALID,
1717 * marking the end of the argument list. If you don't do this
1718 * then libdbus won't know to stop and will read invalid memory.
1720 * String/signature/path arrays should be passed in as "const char***
1721 * address_of_array" and "int n_elements"
1723 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1725 * @todo If this fails due to lack of memory, the message is hosed and
1726 * you have to start over building the whole message.
1728 * @param message the message
1729 * @param first_arg_type type of the first argument
1730 * @param ... value of first argument, list of additional type-value pairs
1731 * @returns #TRUE on success
1734 dbus_message_append_args (DBusMessage *message,
1741 _dbus_return_val_if_fail (message != NULL, FALSE);
1743 va_start (var_args, first_arg_type);
1744 retval = dbus_message_append_args_valist (message,
1753 * Like dbus_message_append_args() but takes a va_list for use by language bindings.
1755 * @todo for now, if this function fails due to OOM it will leave
1756 * the message half-written and you have to discard the message
1759 * @see dbus_message_append_args.
1760 * @param message the message
1761 * @param first_arg_type type of first argument
1762 * @param var_args value of first argument, then list of type/value pairs
1763 * @returns #TRUE on success
1766 dbus_message_append_args_valist (DBusMessage *message,
1771 DBusMessageIter iter;
1773 _dbus_return_val_if_fail (message != NULL, FALSE);
1775 type = first_arg_type;
1777 dbus_message_iter_init_append (message, &iter);
1779 while (type != DBUS_TYPE_INVALID)
1781 if (dbus_type_is_basic (type))
1783 const DBusBasicValue *value;
1784 value = va_arg (var_args, const DBusBasicValue*);
1786 if (!dbus_message_iter_append_basic (&iter,
1791 else if (type == DBUS_TYPE_ARRAY)
1794 DBusMessageIter array;
1797 element_type = va_arg (var_args, int);
1799 buf[0] = element_type;
1801 if (!dbus_message_iter_open_container (&iter,
1807 if (dbus_type_is_fixed (element_type) &&
1808 element_type != DBUS_TYPE_UNIX_FD)
1810 const DBusBasicValue **value;
1813 value = va_arg (var_args, const DBusBasicValue**);
1814 n_elements = va_arg (var_args, int);
1816 if (!dbus_message_iter_append_fixed_array (&array,
1820 dbus_message_iter_abandon_container (&iter, &array);
1824 else if (_DBUS_TYPE_IS_STRINGLIKE (element_type))
1826 const char ***value_p;
1831 value_p = va_arg (var_args, const char***);
1832 n_elements = va_arg (var_args, int);
1837 while (i < n_elements)
1839 if (!dbus_message_iter_append_basic (&array,
1842 dbus_message_iter_abandon_container (&iter, &array);
1850 _dbus_warn ("arrays of %s can't be appended with %s for now\n",
1851 _dbus_type_to_string (element_type),
1852 _DBUS_FUNCTION_NAME);
1856 if (!dbus_message_iter_close_container (&iter, &array))
1859 #ifndef DBUS_DISABLE_CHECKS
1862 _dbus_warn ("type %s isn't supported yet in %s\n",
1863 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
1868 type = va_arg (var_args, int);
1878 * Gets arguments from a message given a variable argument list. The
1879 * supported types include those supported by
1880 * dbus_message_append_args(); that is, basic types and arrays of
1881 * fixed-length basic types. The arguments are the same as they would
1882 * be for dbus_message_iter_get_basic() or
1883 * dbus_message_iter_get_fixed_array().
1885 * In addition to those types, arrays of string, object path, and
1886 * signature are supported; but these are returned as allocated memory
1887 * and must be freed with dbus_free_string_array(), while the other
1888 * types are returned as const references. To get a string array
1889 * pass in "char ***array_location" and "int *n_elements".
1891 * Similar to dbus_message_get_fixed_array() this function does not
1892 * support arrays of type DBUS_TYPE_UNIX_FD. If you need to parse
1893 * messages with arrays of Unix file descriptors you need to recurse
1894 * into the array manually.
1896 * Unix file descriptors that are read with this function will have
1897 * the FD_CLOEXEC flag set. If you need them without this flag set,
1898 * make sure to unset it with fcntl().
1900 * The variable argument list should contain the type of the argument
1901 * followed by a pointer to where the value should be stored. The list
1902 * is terminated with #DBUS_TYPE_INVALID.
1904 * Except for string arrays, the returned values are constant; do not
1905 * free them. They point into the #DBusMessage.
1907 * If the requested arguments are not present, or do not have the
1908 * requested types, then an error will be set.
1910 * If more arguments than requested are present, the requested
1911 * arguments are returned and the extra arguments are ignored.
1913 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1915 * @param message the message
1916 * @param error error to be filled in on failure
1917 * @param first_arg_type the first argument type
1918 * @param ... location for first argument value, then list of type-location pairs
1919 * @returns #FALSE if the error was set
1922 dbus_message_get_args (DBusMessage *message,
1930 _dbus_return_val_if_fail (message != NULL, FALSE);
1931 _dbus_return_val_if_error_is_set (error, FALSE);
1933 va_start (var_args, first_arg_type);
1934 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
1941 * Like dbus_message_get_args but takes a va_list for use by language bindings.
1943 * @see dbus_message_get_args
1944 * @param message the message
1945 * @param error error to be filled in
1946 * @param first_arg_type type of the first argument
1947 * @param var_args return location for first argument, followed by list of type/location pairs
1948 * @returns #FALSE if error was set
1951 dbus_message_get_args_valist (DBusMessage *message,
1956 DBusMessageIter iter;
1958 _dbus_return_val_if_fail (message != NULL, FALSE);
1959 _dbus_return_val_if_error_is_set (error, FALSE);
1961 dbus_message_iter_init (message, &iter);
1962 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
1966 _dbus_message_iter_init_common (DBusMessage *message,
1967 DBusMessageRealIter *real,
1970 _dbus_assert (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
1972 /* Since the iterator will read or write who-knows-what from the
1973 * message, we need to get in the right byte order
1975 ensure_byte_order (message);
1977 real->message = message;
1978 real->changed_stamp = message->changed_stamp;
1979 real->iter_type = iter_type;
1980 real->sig_refcount = 0;
1984 * Initializes a #DBusMessageIter for reading the arguments of the
1985 * message passed in.
1987 * When possible, dbus_message_get_args() is much more convenient.
1988 * Some types of argument can only be read with #DBusMessageIter
1991 * The easiest way to iterate is like this:
1993 * dbus_message_iter_init (message, &iter);
1994 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
1995 * dbus_message_iter_next (&iter);
1998 * #DBusMessageIter contains no allocated memory; it need not be
1999 * freed, and can be copied by assignment or memcpy().
2001 * @param message the message
2002 * @param iter pointer to an iterator to initialize
2003 * @returns #FALSE if the message has no arguments
2006 dbus_message_iter_init (DBusMessage *message,
2007 DBusMessageIter *iter)
2009 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2010 const DBusString *type_str;
2013 _dbus_return_val_if_fail (message != NULL, FALSE);
2014 _dbus_return_val_if_fail (iter != NULL, FALSE);
2016 get_const_signature (&message->header, &type_str, &type_pos);
2018 _dbus_message_iter_init_common (message, real,
2019 DBUS_MESSAGE_ITER_TYPE_READER);
2021 _dbus_type_reader_init (&real->u.reader,
2022 _dbus_header_get_byte_order (&message->header),
2027 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
2031 * Checks if an iterator has any more fields.
2033 * @param iter the message iter
2034 * @returns #TRUE if there are more fields following
2037 dbus_message_iter_has_next (DBusMessageIter *iter)
2039 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2041 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2042 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2044 return _dbus_type_reader_has_next (&real->u.reader);
2048 * Moves the iterator to the next field, if any. If there's no next
2049 * field, returns #FALSE. If the iterator moves forward, returns
2052 * @param iter the message iter
2053 * @returns #TRUE if the iterator was moved to the next field
2056 dbus_message_iter_next (DBusMessageIter *iter)
2058 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2060 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2061 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2063 return _dbus_type_reader_next (&real->u.reader);
2067 * Returns the argument type of the argument that the message iterator
2068 * points to. If the iterator is at the end of the message, returns
2069 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
2072 * dbus_message_iter_init (message, &iter);
2073 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2074 * dbus_message_iter_next (&iter);
2077 * @param iter the message iter
2078 * @returns the argument type
2081 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
2083 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2085 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2086 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2088 return _dbus_type_reader_get_current_type (&real->u.reader);
2092 * Returns the element type of the array that the message iterator
2093 * points to. Note that you need to check that the iterator points to
2094 * an array prior to using this function.
2096 * @param iter the message iter
2097 * @returns the array element type
2100 dbus_message_iter_get_element_type (DBusMessageIter *iter)
2102 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2104 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2105 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
2106 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
2108 return _dbus_type_reader_get_element_type (&real->u.reader);
2112 * Recurses into a container value when reading values from a message,
2113 * initializing a sub-iterator to use for traversing the child values
2116 * Note that this recurses into a value, not a type, so you can only
2117 * recurse if the value exists. The main implication of this is that
2118 * if you have for example an empty array of array of int32, you can
2119 * recurse into the outermost array, but it will have no values, so
2120 * you won't be able to recurse further. There's no array of int32 to
2123 * If a container is an array of fixed-length types (except Unix file
2124 * descriptors), it is much more efficient to use
2125 * dbus_message_iter_get_fixed_array() to get the whole array in one
2126 * shot, rather than individually walking over the array elements.
2128 * Be sure you have somehow checked that
2129 * dbus_message_iter_get_arg_type() matches the type you are expecting
2130 * to recurse into. Results of this function are undefined if there is
2131 * no container to recurse into at the current iterator position.
2133 * @param iter the message iterator
2134 * @param sub the sub-iterator to initialize
2137 dbus_message_iter_recurse (DBusMessageIter *iter,
2138 DBusMessageIter *sub)
2140 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2141 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2143 _dbus_return_if_fail (_dbus_message_iter_check (real));
2144 _dbus_return_if_fail (sub != NULL);
2147 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
2151 * Returns the current signature of a message iterator. This
2152 * is useful primarily for dealing with variants; one can
2153 * recurse into a variant and determine the signature of
2154 * the variant's value.
2156 * The returned string must be freed with dbus_free().
2158 * @param iter the message iterator
2159 * @returns the contained signature, or NULL if out of memory
2162 dbus_message_iter_get_signature (DBusMessageIter *iter)
2164 const DBusString *sig;
2168 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2170 _dbus_return_val_if_fail (_dbus_message_iter_check (real), NULL);
2172 if (!_dbus_string_init (&retstr))
2175 _dbus_type_reader_get_signature (&real->u.reader, &sig,
2177 if (!_dbus_string_append_len (&retstr,
2178 _dbus_string_get_const_data (sig) + start,
2181 if (!_dbus_string_steal_data (&retstr, &ret))
2183 _dbus_string_free (&retstr);
2188 * Reads a basic-typed value from the message iterator.
2189 * Basic types are the non-containers such as integer and string.
2191 * The value argument should be the address of a location to store
2192 * the returned value. So for int32 it should be a "dbus_int32_t*"
2193 * and for string a "const char**". The returned value is
2194 * by reference and should not be freed.
2196 * This call duplicates Unix file descriptors when reading them. It is
2197 * your job to close them when you don't need them anymore.
2199 * Unix file descriptors that are read with this function will have
2200 * the FD_CLOEXEC flag set. If you need them without this flag set,
2201 * make sure to unset it with fcntl().
2203 * Be sure you have somehow checked that
2204 * dbus_message_iter_get_arg_type() matches the type you are
2205 * expecting, or you'll crash when you try to use an integer as a
2206 * string or something.
2208 * To read any container type (array, struct, dict) you will need to
2209 * recurse into the container with dbus_message_iter_recurse(). If
2210 * the container is an array of fixed-length values (except Unix file
2211 * descriptors), you can get all the array elements at once with
2212 * dbus_message_iter_get_fixed_array(). Otherwise, you have to iterate
2213 * over the container's contents one value at a time.
2215 * All basic-typed values are guaranteed to fit in a #DBusBasicValue,
2216 * so in versions of libdbus that have that type, you can write code like this:
2219 * DBusBasicValue value;
2221 * dbus_message_iter_get_basic (&read_iter, &value);
2222 * type = dbus_message_iter_get_arg_type (&read_iter);
2223 * dbus_message_iter_append_basic (&write_iter, type, &value);
2226 * (All D-Bus basic types are either numeric and 8 bytes or smaller, or
2227 * behave like a string; so in older versions of libdbus, DBusBasicValue
2228 * can be replaced with union { char *string; unsigned char bytes[8]; },
2231 * @param iter the iterator
2232 * @param value location to store the value
2235 dbus_message_iter_get_basic (DBusMessageIter *iter,
2238 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2240 _dbus_return_if_fail (_dbus_message_iter_check (real));
2241 _dbus_return_if_fail (value != NULL);
2243 if (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_UNIX_FD)
2245 #ifdef HAVE_UNIX_FD_PASSING
2248 _dbus_type_reader_read_basic(&real->u.reader, &idx);
2250 if (idx.u32 >= real->message->n_unix_fds) {
2251 /* Hmm, we cannot really signal an error here, so let's make
2252 sure to return an invalid fd. */
2253 *((int*) value) = -1;
2257 *((int*) value) = _dbus_dup(real->message->unix_fds[idx.u32], NULL);
2259 *((int*) value) = -1;
2264 _dbus_type_reader_read_basic (&real->u.reader,
2270 * Returns the number of bytes in the array as marshaled in the wire
2271 * protocol. The iterator must currently be inside an array-typed
2274 * This function is deprecated on the grounds that it is stupid. Why
2275 * would you want to know how many bytes are in the array as marshaled
2276 * in the wire protocol? For now, use the n_elements returned from
2277 * dbus_message_iter_get_fixed_array() instead, or iterate over the
2278 * array values and count them.
2280 * @todo introduce a variant of this get_n_elements that returns
2281 * the number of elements, though with a non-fixed array it will not
2282 * be very efficient, so maybe it's not good.
2284 * @param iter the iterator
2285 * @returns the number of bytes in the array
2288 dbus_message_iter_get_array_len (DBusMessageIter *iter)
2290 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2292 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2294 return _dbus_type_reader_get_array_length (&real->u.reader);
2298 * Reads a block of fixed-length values from the message iterator.
2299 * Fixed-length values are those basic types that are not string-like,
2300 * such as integers, bool, double. The returned block will be from the
2301 * current position in the array until the end of the array.
2303 * There is one exception here: although DBUS_TYPE_UNIX_FD is
2304 * considered a 'fixed' type arrays of this type may not be read with
2307 * The message iter should be "in" the array (that is, you recurse into the
2308 * array, and then you call dbus_message_iter_get_fixed_array() on the
2309 * "sub-iterator" created by dbus_message_iter_recurse()).
2311 * The value argument should be the address of a location to store the
2312 * returned array. So for int32 it should be a "const dbus_int32_t**"
2313 * The returned value is by reference and should not be freed.
2315 * This function should only be used if dbus_type_is_fixed() returns
2316 * #TRUE for the element type.
2318 * If an array's elements are not fixed in size, you have to recurse
2319 * into the array with dbus_message_iter_recurse() and read the
2320 * elements one by one.
2322 * Because the array is not copied, this function runs in constant
2323 * time and is fast; it's much preferred over walking the entire array
2324 * with an iterator. (However, you can always use
2325 * dbus_message_iter_recurse(), even for fixed-length types;
2326 * dbus_message_iter_get_fixed_array() is just an optimization.)
2328 * @param iter the iterator
2329 * @param value location to store the block
2330 * @param n_elements number of elements in the block
2333 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
2337 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2338 #ifndef DBUS_DISABLE_CHECKS
2339 int subtype = _dbus_type_reader_get_current_type(&real->u.reader);
2341 _dbus_return_if_fail (_dbus_message_iter_check (real));
2342 _dbus_return_if_fail (value != NULL);
2343 _dbus_return_if_fail ((subtype == DBUS_TYPE_INVALID) ||
2344 (dbus_type_is_fixed (subtype) && subtype != DBUS_TYPE_UNIX_FD));
2347 _dbus_type_reader_read_fixed_multi (&real->u.reader,
2352 * Initializes a #DBusMessageIter for appending arguments to the end
2355 * @todo If appending any of the arguments fails due to lack of
2356 * memory, the message is hosed and you have to start over building
2357 * the whole message.
2359 * @param message the message
2360 * @param iter pointer to an iterator to initialize
2363 dbus_message_iter_init_append (DBusMessage *message,
2364 DBusMessageIter *iter)
2366 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2368 _dbus_return_if_fail (message != NULL);
2369 _dbus_return_if_fail (iter != NULL);
2371 _dbus_message_iter_init_common (message, real,
2372 DBUS_MESSAGE_ITER_TYPE_WRITER);
2374 /* We create the signature string and point iterators at it "on demand"
2375 * when a value is actually appended. That means that init() never fails
2378 _dbus_type_writer_init_types_delayed (&real->u.writer,
2379 _dbus_header_get_byte_order (&message->header),
2381 _dbus_string_get_length (&message->body));
2385 * Creates a temporary signature string containing the current
2386 * signature, stores it in the iterator, and points the iterator to
2387 * the end of it. Used any time we write to the message.
2389 * @param real an iterator without a type_str
2390 * @returns #FALSE if no memory
2393 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
2396 const DBusString *current_sig;
2397 int current_sig_pos;
2399 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2401 if (real->u.writer.type_str != NULL)
2403 _dbus_assert (real->sig_refcount > 0);
2404 real->sig_refcount += 1;
2408 str = dbus_new (DBusString, 1);
2412 if (!_dbus_header_get_field_raw (&real->message->header,
2413 DBUS_HEADER_FIELD_SIGNATURE,
2414 ¤t_sig, ¤t_sig_pos))
2421 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
2422 current_sig_pos += 1; /* move on to sig data */
2424 if (!_dbus_string_init_preallocated (str, current_len + 4))
2430 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
2433 _dbus_string_free (str);
2440 if (!_dbus_string_init_preallocated (str, 4))
2447 real->sig_refcount = 1;
2449 _dbus_type_writer_add_types (&real->u.writer,
2450 str, _dbus_string_get_length (str));
2455 * Sets the new signature as the message signature, frees the
2456 * signature string, and marks the iterator as not having a type_str
2457 * anymore. Frees the signature even if it fails, so you can't
2458 * really recover from failure. Kinda busted.
2460 * @param real an iterator without a type_str
2461 * @returns #FALSE if no memory
2464 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2467 const char *v_STRING;
2470 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2471 _dbus_assert (real->u.writer.type_str != NULL);
2472 _dbus_assert (real->sig_refcount > 0);
2474 real->sig_refcount -= 1;
2476 if (real->sig_refcount > 0)
2478 _dbus_assert (real->sig_refcount == 0);
2482 str = real->u.writer.type_str;
2484 v_STRING = _dbus_string_get_const_data (str);
2485 if (!_dbus_header_set_field_basic (&real->message->header,
2486 DBUS_HEADER_FIELD_SIGNATURE,
2487 DBUS_TYPE_SIGNATURE,
2491 _dbus_type_writer_remove_types (&real->u.writer);
2492 _dbus_string_free (str);
2499 * Frees the signature string and marks the iterator as not having a
2500 * type_str anymore. Since the new signature is not set, the message
2501 * will generally be hosed after this is called.
2503 * @param real an iterator without a type_str
2506 _dbus_message_iter_abandon_signature (DBusMessageRealIter *real)
2510 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2511 _dbus_assert (real->u.writer.type_str != NULL);
2512 _dbus_assert (real->sig_refcount > 0);
2514 real->sig_refcount -= 1;
2516 if (real->sig_refcount > 0)
2518 _dbus_assert (real->sig_refcount == 0);
2520 str = real->u.writer.type_str;
2522 _dbus_type_writer_remove_types (&real->u.writer);
2523 _dbus_string_free (str);
2527 #ifndef DBUS_DISABLE_CHECKS
2529 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2531 if (!_dbus_message_iter_check (iter))
2534 if (iter->message->locked)
2536 _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)\n");
2542 #endif /* DBUS_DISABLE_CHECKS */
2544 #ifdef HAVE_UNIX_FD_PASSING
2546 expand_fd_array(DBusMessage *m,
2551 /* This makes space for adding n new fds to the array and returns a
2552 pointer to the place were the first fd should be put. */
2554 if (m->n_unix_fds + n > m->n_unix_fds_allocated)
2559 /* Make twice as much space as necessary */
2560 k = (m->n_unix_fds + n) * 2;
2562 /* Allocate at least four */
2566 p = dbus_realloc(m->unix_fds, k * sizeof(int));
2571 m->n_unix_fds_allocated = k;
2574 return m->unix_fds + m->n_unix_fds;
2579 * Appends a basic-typed value to the message. The basic types are the
2580 * non-container types such as integer and string.
2582 * The "value" argument should be the address of a basic-typed value.
2583 * So for string, const char**. For integer, dbus_int32_t*.
2585 * For Unix file descriptors this function will internally duplicate
2586 * the descriptor you passed in. Hence you may close the descriptor
2587 * immediately after this call.
2589 * @todo If this fails due to lack of memory, the message is hosed and
2590 * you have to start over building the whole message.
2592 * @param iter the append iterator
2593 * @param type the type of the value
2594 * @param value the address of the value
2595 * @returns #FALSE if not enough memory
2598 dbus_message_iter_append_basic (DBusMessageIter *iter,
2602 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2605 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2606 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2607 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2608 _dbus_return_val_if_fail (value != NULL, FALSE);
2610 #ifndef DBUS_DISABLE_CHECKS
2613 const char * const *string_p;
2614 const dbus_bool_t *bool_p;
2616 case DBUS_TYPE_STRING:
2618 _dbus_return_val_if_fail (_dbus_check_is_valid_utf8 (*string_p), FALSE);
2621 case DBUS_TYPE_OBJECT_PATH:
2623 _dbus_return_val_if_fail (_dbus_check_is_valid_path (*string_p), FALSE);
2626 case DBUS_TYPE_SIGNATURE:
2628 _dbus_return_val_if_fail (_dbus_check_is_valid_signature (*string_p), FALSE);
2631 case DBUS_TYPE_BOOLEAN:
2633 _dbus_return_val_if_fail (*bool_p == 0 || *bool_p == 1, FALSE);
2638 /* nothing to check, all possible values are allowed */
2643 if (!_dbus_message_iter_open_signature (real))
2646 if (type == DBUS_TYPE_UNIX_FD)
2648 #ifdef HAVE_UNIX_FD_PASSING
2652 /* First step, include the fd in the fd list of this message */
2653 if (!(fds = expand_fd_array(real->message, 1)))
2656 *fds = _dbus_dup(*(int*) value, NULL);
2660 u = real->message->n_unix_fds;
2662 /* Second step, write the index to the fd */
2663 if (!(ret = _dbus_type_writer_write_basic (&real->u.writer, DBUS_TYPE_UNIX_FD, &u))) {
2664 _dbus_close(*fds, NULL);
2668 real->message->n_unix_fds += 1;
2671 /* Final step, update the header accordingly */
2672 ret = _dbus_header_set_field_basic (&real->message->header,
2673 DBUS_HEADER_FIELD_UNIX_FDS,
2677 /* If any of these operations fail the message is
2678 hosed. However, no memory or fds should be leaked since what
2679 has been added to message has been added to the message, and
2680 can hence be accounted for when the message is being
2688 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
2691 if (!_dbus_message_iter_close_signature (real))
2698 * Appends a block of fixed-length values to an array. The
2699 * fixed-length types are all basic types that are not string-like. So
2700 * int32, double, bool, etc. (Unix file descriptors however are not
2701 * supported.) You must call dbus_message_iter_open_container() to
2702 * open an array of values before calling this function. You may call
2703 * this function multiple times (and intermixed with calls to
2704 * dbus_message_iter_append_basic()) for the same array.
2706 * The "value" argument should be the address of the array. So for
2707 * integer, "dbus_int32_t**" is expected for example.
2709 * @warning in C, given "int array[]", "&array == array" (the
2710 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2711 * So if you're using an array instead of a pointer you have to create
2712 * a pointer variable, assign the array to it, then take the address
2713 * of the pointer variable.
2715 * const dbus_int32_t array[] = { 1, 2, 3 };
2716 * const dbus_int32_t *v_ARRAY = array;
2717 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
2718 * fprintf (stderr, "No memory!\n");
2720 * For strings it works to write const char *array = "Hello" and then
2721 * use &array though.
2723 * @todo If this fails due to lack of memory, the message is hosed and
2724 * you have to start over building the whole message.
2726 * @param iter the append iterator
2727 * @param element_type the type of the array elements
2728 * @param value the address of the array
2729 * @param n_elements the number of elements to append
2730 * @returns #FALSE if not enough memory
2733 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
2738 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2741 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2742 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2743 _dbus_return_val_if_fail (dbus_type_is_fixed (element_type) && element_type != DBUS_TYPE_UNIX_FD, FALSE);
2744 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
2745 _dbus_return_val_if_fail (value != NULL, FALSE);
2746 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
2747 _dbus_return_val_if_fail (n_elements <=
2748 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
2751 #ifndef DBUS_DISABLE_CHECKS
2752 if (element_type == DBUS_TYPE_BOOLEAN)
2754 const dbus_bool_t * const *bools = value;
2757 for (i = 0; i < n_elements; i++)
2759 _dbus_return_val_if_fail ((*bools)[i] == 0 || (*bools)[i] == 1, FALSE);
2764 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
2770 * Appends a container-typed value to the message; you are required to
2771 * append the contents of the container using the returned
2772 * sub-iterator, and then call
2773 * dbus_message_iter_close_container(). Container types are for
2774 * example struct, variant, and array. For variants, the
2775 * contained_signature should be the type of the single value inside
2776 * the variant. For structs and dict entries, contained_signature
2777 * should be #NULL; it will be set to whatever types you write into
2778 * the struct. For arrays, contained_signature should be the type of
2779 * the array elements.
2781 * @todo If this fails due to lack of memory, the message is hosed and
2782 * you have to start over building the whole message.
2784 * @param iter the append iterator
2785 * @param type the type of the value
2786 * @param contained_signature the type of container contents
2787 * @param sub sub-iterator to initialize
2788 * @returns #FALSE if not enough memory
2791 dbus_message_iter_open_container (DBusMessageIter *iter,
2793 const char *contained_signature,
2794 DBusMessageIter *sub)
2796 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2797 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2798 DBusString contained_str;
2800 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2801 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2802 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
2803 _dbus_return_val_if_fail (sub != NULL, FALSE);
2804 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
2805 contained_signature == NULL) ||
2806 (type == DBUS_TYPE_DICT_ENTRY &&
2807 contained_signature == NULL) ||
2808 (type == DBUS_TYPE_VARIANT &&
2809 contained_signature != NULL) ||
2810 (type == DBUS_TYPE_ARRAY &&
2811 contained_signature != NULL), FALSE);
2813 /* this would fail if the contained_signature is a dict entry, since
2814 * dict entries are invalid signatures standalone (they must be in
2817 _dbus_return_val_if_fail ((type == DBUS_TYPE_ARRAY && contained_signature && *contained_signature == DBUS_DICT_ENTRY_BEGIN_CHAR) ||
2818 (contained_signature == NULL ||
2819 _dbus_check_is_valid_signature (contained_signature)),
2822 if (!_dbus_message_iter_open_signature (real))
2827 if (contained_signature != NULL)
2829 _dbus_string_init_const (&contained_str, contained_signature);
2831 return _dbus_type_writer_recurse (&real->u.writer,
2834 &real_sub->u.writer);
2838 return _dbus_type_writer_recurse (&real->u.writer,
2841 &real_sub->u.writer);
2847 * Closes a container-typed value appended to the message; may write
2848 * out more information to the message known only after the entire
2849 * container is written, and may free resources created by
2850 * dbus_message_iter_open_container().
2852 * @todo If this fails due to lack of memory, the message is hosed and
2853 * you have to start over building the whole message.
2855 * @param iter the append iterator
2856 * @param sub sub-iterator to close
2857 * @returns #FALSE if not enough memory
2860 dbus_message_iter_close_container (DBusMessageIter *iter,
2861 DBusMessageIter *sub)
2863 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2864 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2867 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2868 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2869 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
2870 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2872 ret = _dbus_type_writer_unrecurse (&real->u.writer,
2873 &real_sub->u.writer);
2875 if (!_dbus_message_iter_close_signature (real))
2882 * Abandons creation of a contained-typed value and frees resources created
2883 * by dbus_message_iter_open_container(). Once this returns, the message
2884 * is hosed and you have to start over building the whole message.
2886 * This should only be used to abandon creation of a message when you have
2889 * @param iter the append iterator
2890 * @param sub sub-iterator to close
2893 dbus_message_iter_abandon_container (DBusMessageIter *iter,
2894 DBusMessageIter *sub)
2896 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2897 #ifndef DBUS_DISABLE_CHECKS
2898 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2900 _dbus_return_if_fail (_dbus_message_iter_append_check (real));
2901 _dbus_return_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2902 _dbus_return_if_fail (_dbus_message_iter_append_check (real_sub));
2903 _dbus_return_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2906 _dbus_message_iter_abandon_signature (real);
2910 * Sets a flag indicating that the message does not want a reply; if
2911 * this flag is set, the other end of the connection may (but is not
2912 * required to) optimize by not sending method return or error
2913 * replies. If this flag is set, there is no way to know whether the
2914 * message successfully arrived at the remote end. Normally you know a
2915 * message was received when you receive the reply to it.
2917 * The flag is #FALSE by default, that is by default the other end is
2918 * required to reply.
2920 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
2922 * @param message the message
2923 * @param no_reply #TRUE if no reply is desired
2926 dbus_message_set_no_reply (DBusMessage *message,
2927 dbus_bool_t no_reply)
2929 _dbus_return_if_fail (message != NULL);
2930 _dbus_return_if_fail (!message->locked);
2932 _dbus_header_toggle_flag (&message->header,
2933 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
2938 * Returns #TRUE if the message does not expect
2941 * @param message the message
2942 * @returns #TRUE if the message sender isn't waiting for a reply
2945 dbus_message_get_no_reply (DBusMessage *message)
2947 _dbus_return_val_if_fail (message != NULL, FALSE);
2949 return _dbus_header_get_flag (&message->header,
2950 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
2954 * Sets a flag indicating that an owner for the destination name will
2955 * be automatically started before the message is delivered. When this
2956 * flag is set, the message is held until a name owner finishes
2957 * starting up, or fails to start up. In case of failure, the reply
2960 * The flag is set to #TRUE by default, i.e. auto starting is the default.
2962 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
2964 * @param message the message
2965 * @param auto_start #TRUE if auto-starting is desired
2968 dbus_message_set_auto_start (DBusMessage *message,
2969 dbus_bool_t auto_start)
2971 _dbus_return_if_fail (message != NULL);
2972 _dbus_return_if_fail (!message->locked);
2974 _dbus_header_toggle_flag (&message->header,
2975 DBUS_HEADER_FLAG_NO_AUTO_START,
2980 * Returns #TRUE if the message will cause an owner for
2981 * destination name to be auto-started.
2983 * @param message the message
2984 * @returns #TRUE if the message will use auto-start
2987 dbus_message_get_auto_start (DBusMessage *message)
2989 _dbus_return_val_if_fail (message != NULL, FALSE);
2991 return !_dbus_header_get_flag (&message->header,
2992 DBUS_HEADER_FLAG_NO_AUTO_START);
2997 * Sets the object path this message is being sent to (for
2998 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
2999 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
3001 * The path must contain only valid characters as defined
3002 * in the D-Bus specification.
3004 * @param message the message
3005 * @param object_path the path or #NULL to unset
3006 * @returns #FALSE if not enough memory
3009 dbus_message_set_path (DBusMessage *message,
3010 const char *object_path)
3012 _dbus_return_val_if_fail (message != NULL, FALSE);
3013 _dbus_return_val_if_fail (!message->locked, FALSE);
3014 _dbus_return_val_if_fail (object_path == NULL ||
3015 _dbus_check_is_valid_path (object_path),
3018 return set_or_delete_string_field (message,
3019 DBUS_HEADER_FIELD_PATH,
3020 DBUS_TYPE_OBJECT_PATH,
3025 * Gets the object path this message is being sent to (for
3026 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
3027 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3029 * See also dbus_message_get_path_decomposed().
3031 * The returned string becomes invalid if the message is
3032 * modified, since it points into the wire-marshaled message data.
3034 * @param message the message
3035 * @returns the path (should not be freed) or #NULL
3038 dbus_message_get_path (DBusMessage *message)
3042 _dbus_return_val_if_fail (message != NULL, NULL);
3044 v = NULL; /* in case field doesn't exist */
3045 _dbus_header_get_field_basic (&message->header,
3046 DBUS_HEADER_FIELD_PATH,
3047 DBUS_TYPE_OBJECT_PATH,
3053 * Checks if the message has a particular object path. The object
3054 * path is the destination object for a method call or the emitting
3055 * object for a signal.
3057 * @param message the message
3058 * @param path the path name
3059 * @returns #TRUE if there is a path field in the header
3062 dbus_message_has_path (DBusMessage *message,
3065 const char *msg_path;
3066 msg_path = dbus_message_get_path (message);
3068 if (msg_path == NULL)
3079 if (strcmp (msg_path, path) == 0)
3086 * Gets the object path this message is being sent to
3087 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3088 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
3089 * format (one array element per path component).
3090 * Free the returned array with dbus_free_string_array().
3092 * An empty but non-NULL path array means the path "/".
3093 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
3094 * and the path "/" becomes { NULL }.
3096 * See also dbus_message_get_path().
3098 * @todo this could be optimized by using the len from the message
3099 * instead of calling strlen() again
3101 * @param message the message
3102 * @param path place to store allocated array of path components; #NULL set here if no path field exists
3103 * @returns #FALSE if no memory to allocate the array
3106 dbus_message_get_path_decomposed (DBusMessage *message,
3111 _dbus_return_val_if_fail (message != NULL, FALSE);
3112 _dbus_return_val_if_fail (path != NULL, FALSE);
3116 v = dbus_message_get_path (message);
3119 if (!_dbus_decompose_path (v, strlen (v),
3127 * Sets the interface this message is being sent to
3128 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
3129 * the interface a signal is being emitted from
3130 * (for DBUS_MESSAGE_TYPE_SIGNAL).
3132 * The interface name must contain only valid characters as defined
3133 * in the D-Bus specification.
3135 * @param message the message
3136 * @param iface the interface or #NULL to unset
3137 * @returns #FALSE if not enough memory
3140 dbus_message_set_interface (DBusMessage *message,
3143 _dbus_return_val_if_fail (message != NULL, FALSE);
3144 _dbus_return_val_if_fail (!message->locked, FALSE);
3145 _dbus_return_val_if_fail (iface == NULL ||
3146 _dbus_check_is_valid_interface (iface),
3149 return set_or_delete_string_field (message,
3150 DBUS_HEADER_FIELD_INTERFACE,
3156 * Gets the interface this message is being sent to
3157 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3158 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
3159 * The interface name is fully-qualified (namespaced).
3160 * Returns #NULL if none.
3162 * The returned string becomes invalid if the message is
3163 * modified, since it points into the wire-marshaled message data.
3165 * @param message the message
3166 * @returns the message interface (should not be freed) or #NULL
3169 dbus_message_get_interface (DBusMessage *message)
3173 _dbus_return_val_if_fail (message != NULL, NULL);
3175 v = NULL; /* in case field doesn't exist */
3176 _dbus_header_get_field_basic (&message->header,
3177 DBUS_HEADER_FIELD_INTERFACE,
3184 * Checks if the message has an interface
3186 * @param message the message
3187 * @param iface the interface name
3188 * @returns #TRUE if the interface field in the header matches
3191 dbus_message_has_interface (DBusMessage *message,
3194 const char *msg_interface;
3195 msg_interface = dbus_message_get_interface (message);
3197 if (msg_interface == NULL)
3208 if (strcmp (msg_interface, iface) == 0)
3216 * Sets the interface member being invoked
3217 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3218 * (DBUS_MESSAGE_TYPE_SIGNAL).
3220 * The member name must contain only valid characters as defined
3221 * in the D-Bus specification.
3223 * @param message the message
3224 * @param member the member or #NULL to unset
3225 * @returns #FALSE if not enough memory
3228 dbus_message_set_member (DBusMessage *message,
3231 _dbus_return_val_if_fail (message != NULL, FALSE);
3232 _dbus_return_val_if_fail (!message->locked, FALSE);
3233 _dbus_return_val_if_fail (member == NULL ||
3234 _dbus_check_is_valid_member (member),
3237 return set_or_delete_string_field (message,
3238 DBUS_HEADER_FIELD_MEMBER,
3244 * Gets the interface member being invoked
3245 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3246 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3248 * The returned string becomes invalid if the message is
3249 * modified, since it points into the wire-marshaled message data.
3251 * @param message the message
3252 * @returns the member name (should not be freed) or #NULL
3255 dbus_message_get_member (DBusMessage *message)
3259 _dbus_return_val_if_fail (message != NULL, NULL);
3261 v = NULL; /* in case field doesn't exist */
3262 _dbus_header_get_field_basic (&message->header,
3263 DBUS_HEADER_FIELD_MEMBER,
3270 * Checks if the message has an interface member
3272 * @param message the message
3273 * @param member the member name
3274 * @returns #TRUE if there is a member field in the header
3277 dbus_message_has_member (DBusMessage *message,
3280 const char *msg_member;
3281 msg_member = dbus_message_get_member (message);
3283 if (msg_member == NULL)
3294 if (strcmp (msg_member, member) == 0)
3302 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
3303 * The name is fully-qualified (namespaced).
3305 * The error name must contain only valid characters as defined
3306 * in the D-Bus specification.
3308 * @param message the message
3309 * @param error_name the name or #NULL to unset
3310 * @returns #FALSE if not enough memory
3313 dbus_message_set_error_name (DBusMessage *message,
3314 const char *error_name)
3316 _dbus_return_val_if_fail (message != NULL, FALSE);
3317 _dbus_return_val_if_fail (!message->locked, FALSE);
3318 _dbus_return_val_if_fail (error_name == NULL ||
3319 _dbus_check_is_valid_error_name (error_name),
3322 return set_or_delete_string_field (message,
3323 DBUS_HEADER_FIELD_ERROR_NAME,
3329 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
3332 * The returned string becomes invalid if the message is
3333 * modified, since it points into the wire-marshaled message data.
3335 * @param message the message
3336 * @returns the error name (should not be freed) or #NULL
3339 dbus_message_get_error_name (DBusMessage *message)
3343 _dbus_return_val_if_fail (message != NULL, NULL);
3345 v = NULL; /* in case field doesn't exist */
3346 _dbus_header_get_field_basic (&message->header,
3347 DBUS_HEADER_FIELD_ERROR_NAME,
3354 * Sets the message's destination. The destination is the name of
3355 * another connection on the bus and may be either the unique name
3356 * assigned by the bus to each connection, or a well-known name
3357 * specified in advance.
3359 * The destination name must contain only valid characters as defined
3360 * in the D-Bus specification.
3362 * @param message the message
3363 * @param destination the destination name or #NULL to unset
3364 * @returns #FALSE if not enough memory
3367 dbus_message_set_destination (DBusMessage *message,
3368 const char *destination)
3370 _dbus_return_val_if_fail (message != NULL, FALSE);
3371 _dbus_return_val_if_fail (!message->locked, FALSE);
3372 _dbus_return_val_if_fail (destination == NULL ||
3373 _dbus_check_is_valid_bus_name (destination),
3376 return set_or_delete_string_field (message,
3377 DBUS_HEADER_FIELD_DESTINATION,
3383 * Gets the destination of a message or #NULL if there is none set.
3385 * The returned string becomes invalid if the message is
3386 * modified, since it points into the wire-marshaled message data.
3388 * @param message the message
3389 * @returns the message destination (should not be freed) or #NULL
3392 dbus_message_get_destination (DBusMessage *message)
3396 _dbus_return_val_if_fail (message != NULL, NULL);
3398 v = NULL; /* in case field doesn't exist */
3399 _dbus_header_get_field_basic (&message->header,
3400 DBUS_HEADER_FIELD_DESTINATION,
3407 * Sets the message sender.
3409 * The sender must be a valid bus name as defined in the D-Bus
3412 * Usually you don't want to call this. The message bus daemon will
3413 * call it to set the origin of each message. If you aren't implementing
3414 * a message bus daemon you shouldn't need to set the sender.
3416 * @param message the message
3417 * @param sender the sender or #NULL to unset
3418 * @returns #FALSE if not enough memory
3421 dbus_message_set_sender (DBusMessage *message,
3424 _dbus_return_val_if_fail (message != NULL, FALSE);
3425 _dbus_return_val_if_fail (!message->locked, FALSE);
3426 _dbus_return_val_if_fail (sender == NULL ||
3427 _dbus_check_is_valid_bus_name (sender),
3430 return set_or_delete_string_field (message,
3431 DBUS_HEADER_FIELD_SENDER,
3437 * Gets the unique name of the connection which originated this
3438 * message, or #NULL if unknown or inapplicable. The sender is filled
3439 * in by the message bus.
3441 * Note, the returned sender is always the unique bus name.
3442 * Connections may own multiple other bus names, but those
3443 * are not found in the sender field.
3445 * The returned string becomes invalid if the message is
3446 * modified, since it points into the wire-marshaled message data.
3448 * @param message the message
3449 * @returns the unique name of the sender or #NULL
3452 dbus_message_get_sender (DBusMessage *message)
3456 _dbus_return_val_if_fail (message != NULL, NULL);
3458 v = NULL; /* in case field doesn't exist */
3459 _dbus_header_get_field_basic (&message->header,
3460 DBUS_HEADER_FIELD_SENDER,
3467 * Gets the type signature of the message, i.e. the arguments in the
3468 * message payload. The signature includes only "in" arguments for
3469 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
3470 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
3471 * what you might expect (that is, it does not include the signature of the
3472 * entire C++-style method).
3474 * The signature is a string made up of type codes such as
3475 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
3476 * the value of #DBUS_TYPE_INVALID).
3478 * The returned string becomes invalid if the message is
3479 * modified, since it points into the wire-marshaled message data.
3481 * @param message the message
3482 * @returns the type signature
3485 dbus_message_get_signature (DBusMessage *message)
3487 const DBusString *type_str;
3490 _dbus_return_val_if_fail (message != NULL, NULL);
3492 get_const_signature (&message->header, &type_str, &type_pos);
3494 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
3498 _dbus_message_has_type_interface_member (DBusMessage *message,
3505 _dbus_assert (message != NULL);
3506 _dbus_assert (iface != NULL);
3507 _dbus_assert (member != NULL);
3509 if (dbus_message_get_type (message) != type)
3512 /* Optimize by checking the short member name first
3513 * instead of the longer interface name
3516 n = dbus_message_get_member (message);
3518 if (n && strcmp (n, member) == 0)
3520 n = dbus_message_get_interface (message);
3522 if (n == NULL || strcmp (n, iface) == 0)
3530 * Checks whether the message is a method call with the given
3531 * interface and member fields. If the message is not
3532 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
3533 * member field, returns #FALSE. If the interface field is missing,
3534 * then it will be assumed equal to the provided interface. The D-Bus
3535 * protocol allows method callers to leave out the interface name.
3537 * @param message the message
3538 * @param iface the name to check (must not be #NULL)
3539 * @param method the name to check (must not be #NULL)
3541 * @returns #TRUE if the message is the specified method call
3544 dbus_message_is_method_call (DBusMessage *message,
3548 _dbus_return_val_if_fail (message != NULL, FALSE);
3549 _dbus_return_val_if_fail (iface != NULL, FALSE);
3550 _dbus_return_val_if_fail (method != NULL, FALSE);
3551 /* don't check that interface/method are valid since it would be
3552 * expensive, and not catch many common errors
3555 return _dbus_message_has_type_interface_member (message,
3556 DBUS_MESSAGE_TYPE_METHOD_CALL,
3561 * Checks whether the message is a signal with the given interface and
3562 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
3563 * has a different interface or member field, returns #FALSE.
3565 * @param message the message
3566 * @param iface the name to check (must not be #NULL)
3567 * @param signal_name the name to check (must not be #NULL)
3569 * @returns #TRUE if the message is the specified signal
3572 dbus_message_is_signal (DBusMessage *message,
3574 const char *signal_name)
3576 _dbus_return_val_if_fail (message != NULL, FALSE);
3577 _dbus_return_val_if_fail (iface != NULL, FALSE);
3578 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
3579 /* don't check that interface/name are valid since it would be
3580 * expensive, and not catch many common errors
3583 return _dbus_message_has_type_interface_member (message,
3584 DBUS_MESSAGE_TYPE_SIGNAL,
3585 iface, signal_name);
3589 * Checks whether the message is an error reply with the given error
3590 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
3591 * different name, returns #FALSE.
3593 * @param message the message
3594 * @param error_name the name to check (must not be #NULL)
3596 * @returns #TRUE if the message is the specified error
3599 dbus_message_is_error (DBusMessage *message,
3600 const char *error_name)
3604 _dbus_return_val_if_fail (message != NULL, FALSE);
3605 _dbus_return_val_if_fail (error_name != NULL, FALSE);
3606 /* don't check that error_name is valid since it would be expensive,
3607 * and not catch many common errors
3610 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3613 n = dbus_message_get_error_name (message);
3615 if (n && strcmp (n, error_name) == 0)
3622 * Checks whether the message was sent to the given name. If the
3623 * message has no destination specified or has a different
3624 * destination, returns #FALSE.
3626 * @param message the message
3627 * @param name the name to check (must not be #NULL)
3629 * @returns #TRUE if the message has the given destination name
3632 dbus_message_has_destination (DBusMessage *message,
3637 _dbus_return_val_if_fail (message != NULL, FALSE);
3638 _dbus_return_val_if_fail (name != NULL, FALSE);
3639 /* don't check that name is valid since it would be expensive, and
3640 * not catch many common errors
3643 s = dbus_message_get_destination (message);
3645 if (s && strcmp (s, name) == 0)
3652 * Checks whether the message has the given unique name as its sender.
3653 * If the message has no sender specified or has a different sender,
3654 * returns #FALSE. Note that a peer application will always have the
3655 * unique name of the connection as the sender. So you can't use this
3656 * function to see whether a sender owned a well-known name.
3658 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
3661 * @param message the message
3662 * @param name the name to check (must not be #NULL)
3664 * @returns #TRUE if the message has the given sender
3667 dbus_message_has_sender (DBusMessage *message,
3672 _dbus_return_val_if_fail (message != NULL, FALSE);
3673 _dbus_return_val_if_fail (name != NULL, FALSE);
3674 /* don't check that name is valid since it would be expensive, and
3675 * not catch many common errors
3678 s = dbus_message_get_sender (message);
3680 if (s && strcmp (s, name) == 0)
3687 * Checks whether the message has the given signature; see
3688 * dbus_message_get_signature() for more details on what the signature
3691 * @param message the message
3692 * @param signature typecode array
3693 * @returns #TRUE if message has the given signature
3696 dbus_message_has_signature (DBusMessage *message,
3697 const char *signature)
3701 _dbus_return_val_if_fail (message != NULL, FALSE);
3702 _dbus_return_val_if_fail (signature != NULL, FALSE);
3703 /* don't check that signature is valid since it would be expensive,
3704 * and not catch many common errors
3707 s = dbus_message_get_signature (message);
3709 if (s && strcmp (s, signature) == 0)
3716 * Sets a #DBusError based on the contents of the given
3717 * message. The error is only set if the message
3718 * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
3719 * The name of the error is set to the name of the message,
3720 * and the error message is set to the first argument
3721 * if the argument exists and is a string.
3723 * The return value indicates whether the error was set (the error is
3724 * set if and only if the message is an error message). So you can
3725 * check for an error reply and convert it to DBusError in one go:
3727 * if (dbus_set_error_from_message (error, reply))
3733 * @param error the error to set
3734 * @param message the message to set it from
3735 * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
3738 dbus_set_error_from_message (DBusError *error,
3739 DBusMessage *message)
3743 _dbus_return_val_if_fail (message != NULL, FALSE);
3744 _dbus_return_val_if_error_is_set (error, FALSE);
3746 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3750 dbus_message_get_args (message, NULL,
3751 DBUS_TYPE_STRING, &str,
3754 dbus_set_error (error, dbus_message_get_error_name (message),
3755 str ? "%s" : NULL, str);
3761 * Checks whether a message contains unix fds
3763 * @param message the message
3764 * @returns #TRUE if the message contains unix fds
3767 dbus_message_contains_unix_fds(DBusMessage *message)
3769 #ifdef HAVE_UNIX_FD_PASSING
3770 _dbus_assert(message);
3772 return message->n_unix_fds > 0;
3781 * @addtogroup DBusMessageInternals
3787 * The initial buffer size of the message loader.
3789 * @todo this should be based on min header size plus some average
3790 * body size, or something. Or rather, the min header size only, if we
3791 * want to try to read only the header, store that in a DBusMessage,
3792 * then read only the body and store that, etc., depends on
3793 * how we optimize _dbus_message_loader_get_buffer() and what
3794 * the exact message format is.
3796 #define INITIAL_LOADER_DATA_LEN 32
3799 * Creates a new message loader. Returns #NULL if memory can't
3802 * @returns new loader, or #NULL.
3805 _dbus_message_loader_new (void)
3807 DBusMessageLoader *loader;
3809 loader = dbus_new0 (DBusMessageLoader, 1);
3813 loader->refcount = 1;
3815 loader->corrupted = FALSE;
3816 loader->corruption_reason = DBUS_VALID;
3818 /* this can be configured by the app, but defaults to the protocol max */
3819 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
3821 /* We set a very relatively conservative default here since due to how
3822 SCM_RIGHTS works we need to preallocate an fd array of the maximum
3823 number of unix fds we want to receive in advance. A
3824 try-and-reallocate loop is not possible. */
3825 loader->max_message_unix_fds = DBUS_DEFAULT_MESSAGE_UNIX_FDS;
3827 if (!_dbus_string_init (&loader->data))
3833 /* preallocate the buffer for speed, ignore failure */
3834 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
3835 _dbus_string_set_length (&loader->data, 0);
3837 #ifdef HAVE_UNIX_FD_PASSING
3838 loader->unix_fds = NULL;
3839 loader->n_unix_fds = loader->n_unix_fds_allocated = 0;
3840 loader->unix_fds_outstanding = FALSE;
3847 * Increments the reference count of the loader.
3849 * @param loader the loader.
3850 * @returns the loader
3853 _dbus_message_loader_ref (DBusMessageLoader *loader)
3855 loader->refcount += 1;
3861 * Decrements the reference count of the loader and finalizes the
3862 * loader when the count reaches zero.
3864 * @param loader the loader.
3867 _dbus_message_loader_unref (DBusMessageLoader *loader)
3869 loader->refcount -= 1;
3870 if (loader->refcount == 0)
3872 #ifdef HAVE_UNIX_FD_PASSING
3873 close_unix_fds(loader->unix_fds, &loader->n_unix_fds);
3874 dbus_free(loader->unix_fds);
3876 _dbus_list_foreach (&loader->messages,
3877 (DBusForeachFunction) dbus_message_unref,
3879 _dbus_list_clear (&loader->messages);
3880 _dbus_string_free (&loader->data);
3886 * Gets the buffer to use for reading data from the network. Network
3887 * data is read directly into an allocated buffer, which is then used
3888 * in the DBusMessage, to avoid as many extra memcpy's as possible.
3889 * The buffer must always be returned immediately using
3890 * _dbus_message_loader_return_buffer(), even if no bytes are
3891 * successfully read.
3893 * @todo this function can be a lot more clever. For example
3894 * it can probably always return a buffer size to read exactly
3895 * the body of the next message, thus avoiding any memory wastage
3898 * @todo we need to enforce a max length on strings in header fields.
3900 * @param loader the message loader.
3901 * @param buffer the buffer
3904 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
3905 DBusString **buffer)
3907 _dbus_assert (!loader->buffer_outstanding);
3909 *buffer = &loader->data;
3911 loader->buffer_outstanding = TRUE;
3915 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
3916 * indicating to the loader how many bytes of the buffer were filled
3917 * in. This function must always be called, even if no bytes were
3918 * successfully read.
3920 * @param loader the loader.
3921 * @param buffer the buffer.
3922 * @param bytes_read number of bytes that were read into the buffer.
3925 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
3929 _dbus_assert (loader->buffer_outstanding);
3930 _dbus_assert (buffer == &loader->data);
3932 loader->buffer_outstanding = FALSE;
3936 * Gets the buffer to use for reading unix fds from the network.
3938 * This works similar to _dbus_message_loader_get_buffer()
3940 * @param loader the message loader.
3941 * @param fds the array to read fds into
3942 * @param max_n_fds how many fds to read at most
3943 * @return TRUE on success, FALSE on OOM
3946 _dbus_message_loader_get_unix_fds(DBusMessageLoader *loader,
3948 unsigned *max_n_fds)
3950 #ifdef HAVE_UNIX_FD_PASSING
3951 _dbus_assert (!loader->unix_fds_outstanding);
3953 /* Allocate space where we can put the fds we read. We allocate
3954 space for max_message_unix_fds since this is an
3955 upper limit how many fds can be received within a single
3956 message. Since SCM_RIGHTS doesn't allow a reallocate+retry logic
3957 we are allocating the maximum possible array size right from the
3958 beginning. This sucks a bit, however unless SCM_RIGHTS is fixed
3959 there is no better way. */
3961 if (loader->n_unix_fds_allocated < loader->max_message_unix_fds)
3963 int *a = dbus_realloc(loader->unix_fds,
3964 loader->max_message_unix_fds * sizeof(loader->unix_fds[0]));
3969 loader->unix_fds = a;
3970 loader->n_unix_fds_allocated = loader->max_message_unix_fds;
3973 *fds = loader->unix_fds + loader->n_unix_fds;
3974 *max_n_fds = loader->n_unix_fds_allocated - loader->n_unix_fds;
3976 loader->unix_fds_outstanding = TRUE;
3979 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
3985 * Returns a buffer obtained from _dbus_message_loader_get_unix_fds().
3987 * This works similar to _dbus_message_loader_return_buffer()
3989 * @param loader the message loader.
3990 * @param fds the array fds were read into
3991 * @param n_fds how many fds were read
3995 _dbus_message_loader_return_unix_fds(DBusMessageLoader *loader,
3999 #ifdef HAVE_UNIX_FD_PASSING
4000 _dbus_assert(loader->unix_fds_outstanding);
4001 _dbus_assert(loader->unix_fds + loader->n_unix_fds == fds);
4002 _dbus_assert(loader->n_unix_fds + n_fds <= loader->n_unix_fds_allocated);
4004 loader->n_unix_fds += n_fds;
4005 loader->unix_fds_outstanding = FALSE;
4007 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
4012 * FIXME when we move the header out of the buffer, that memmoves all
4013 * buffered messages. Kind of crappy.
4015 * Also we copy the header and body, which is kind of crappy. To
4016 * avoid this, we have to allow header and body to be in a single
4017 * memory block, which is good for messages we read and bad for
4018 * messages we are creating. But we could move_len() the buffer into
4019 * this single memory block, and move_len() will just swap the buffers
4020 * if you're moving the entire buffer replacing the dest string.
4022 * We could also have the message loader tell the transport how many
4023 * bytes to read; so it would first ask for some arbitrary number like
4024 * 256, then if the message was incomplete it would use the
4025 * header/body len to ask for exactly the size of the message (or
4026 * blocks the size of a typical kernel buffer for the socket). That
4027 * way we don't get trailing bytes in the buffer that have to be
4028 * memmoved. Though I suppose we also don't have a chance of reading a
4029 * bunch of small messages at once, so the optimization may be stupid.
4031 * Another approach would be to keep a "start" index into
4032 * loader->data and only delete it occasionally, instead of after
4033 * each message is loaded.
4035 * load_message() returns FALSE if not enough memory OR the loader was corrupted
4038 load_message (DBusMessageLoader *loader,
4039 DBusMessage *message,
4041 int fields_array_len,
4046 DBusValidity validity;
4047 const DBusString *type_str;
4049 DBusValidationMode mode;
4050 dbus_uint32_t n_unix_fds = 0;
4052 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
4057 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
4060 /* 1. VALIDATE AND COPY OVER HEADER */
4061 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
4062 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
4064 if (!_dbus_header_load (&message->header,
4072 _dbus_string_get_length (&loader->data)))
4074 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
4076 /* assert here so we can catch any code that still uses DBUS_VALID to indicate
4077 oom errors. They should use DBUS_VALIDITY_UNKNOWN_OOM_ERROR instead */
4078 _dbus_assert (validity != DBUS_VALID);
4080 if (validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
4084 loader->corrupted = TRUE;
4085 loader->corruption_reason = validity;
4090 _dbus_assert (validity == DBUS_VALID);
4092 /* 2. VALIDATE BODY */
4093 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
4095 get_const_signature (&message->header, &type_str, &type_pos);
4097 /* Because the bytes_remaining arg is NULL, this validates that the
4098 * body is the right length
4100 validity = _dbus_validate_body_with_reason (type_str,
4107 if (validity != DBUS_VALID)
4109 _dbus_verbose ("Failed to validate message body code %d\n", validity);
4111 loader->corrupted = TRUE;
4112 loader->corruption_reason = validity;
4118 /* 3. COPY OVER UNIX FDS */
4119 _dbus_header_get_field_basic(&message->header,
4120 DBUS_HEADER_FIELD_UNIX_FDS,
4124 #ifdef HAVE_UNIX_FD_PASSING
4126 if (n_unix_fds > loader->n_unix_fds)
4128 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
4129 n_unix_fds, loader->n_unix_fds);
4131 loader->corrupted = TRUE;
4132 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4136 /* If this was a recycled message there might still be
4137 some memory allocated for the fds */
4138 dbus_free(message->unix_fds);
4142 message->unix_fds = _dbus_memdup(loader->unix_fds, n_unix_fds * sizeof(message->unix_fds[0]));
4143 if (message->unix_fds == NULL)
4145 _dbus_verbose ("Failed to allocate file descriptor array\n");
4150 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
4151 loader->n_unix_fds -= n_unix_fds;
4152 memmove(loader->unix_fds + n_unix_fds, loader->unix_fds, loader->n_unix_fds);
4155 message->unix_fds = NULL;
4161 _dbus_verbose ("Hmm, message claims to come with file descriptors "
4162 "but that's not supported on our platform, disconnecting.\n");
4164 loader->corrupted = TRUE;
4165 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4171 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
4173 if (!_dbus_list_append (&loader->messages, message))
4175 _dbus_verbose ("Failed to append new message to loader queue\n");
4180 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
4181 _dbus_assert (_dbus_string_get_length (&loader->data) >=
4182 (header_len + body_len));
4184 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
4186 _dbus_verbose ("Failed to move body into new message\n");
4191 _dbus_string_delete (&loader->data, 0, header_len + body_len);
4193 /* don't waste more than 2k of memory */
4194 _dbus_string_compact (&loader->data, 2048);
4196 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
4197 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
4199 _dbus_verbose ("Loaded message %p\n", message);
4201 _dbus_assert (!oom);
4202 _dbus_assert (!loader->corrupted);
4203 _dbus_assert (loader->messages != NULL);
4204 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4212 /* does nothing if the message isn't in the list */
4213 _dbus_list_remove_last (&loader->messages, message);
4216 _dbus_assert (!loader->corrupted);
4218 _dbus_assert (loader->corrupted);
4220 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
4226 * Converts buffered data into messages, if we have enough data. If
4227 * we don't have enough data, does nothing.
4229 * @todo we need to check that the proper named header fields exist
4230 * for each message type.
4232 * @todo If a message has unknown type, we should probably eat it
4233 * right here rather than passing it out to applications. However
4234 * it's not an error to see messages of unknown type.
4236 * @param loader the loader.
4237 * @returns #TRUE if we had enough memory to finish.
4240 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
4242 while (!loader->corrupted &&
4243 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
4245 DBusValidity validity;
4246 int byte_order, fields_array_len, header_len, body_len;
4248 if (_dbus_header_have_message_untrusted (loader->max_message_size,
4255 _dbus_string_get_length (&loader->data)))
4257 DBusMessage *message;
4259 _dbus_assert (validity == DBUS_VALID);
4261 message = dbus_message_new_empty_header ();
4262 if (message == NULL)
4265 if (!load_message (loader, message,
4266 byte_order, fields_array_len,
4267 header_len, body_len))
4269 dbus_message_unref (message);
4270 /* load_message() returns false if corrupted or OOM; if
4271 * corrupted then return TRUE for not OOM
4273 return loader->corrupted;
4276 _dbus_assert (loader->messages != NULL);
4277 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4281 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
4283 if (validity != DBUS_VALID)
4285 loader->corrupted = TRUE;
4286 loader->corruption_reason = validity;
4296 * Peeks at first loaded message, returns #NULL if no messages have
4299 * @param loader the loader.
4300 * @returns the next message, or #NULL if none.
4303 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
4305 if (loader->messages)
4306 return loader->messages->data;
4312 * Pops a loaded message (passing ownership of the message
4313 * to the caller). Returns #NULL if no messages have been
4316 * @param loader the loader.
4317 * @returns the next message, or #NULL if none.
4320 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
4322 return _dbus_list_pop_first (&loader->messages);
4326 * Pops a loaded message inside a list link (passing ownership of the
4327 * message and link to the caller). Returns #NULL if no messages have
4330 * @param loader the loader.
4331 * @returns the next message link, or #NULL if none.
4334 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
4336 return _dbus_list_pop_first_link (&loader->messages);
4340 * Returns a popped message link, used to undo a pop.
4342 * @param loader the loader
4343 * @param link the link with a message in it
4346 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
4349 _dbus_list_prepend_link (&loader->messages, link);
4353 * Checks whether the loader is confused due to bad data.
4354 * If messages are received that are invalid, the
4355 * loader gets confused and gives up permanently.
4356 * This state is called "corrupted."
4358 * @param loader the loader
4359 * @returns #TRUE if the loader is hosed.
4362 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
4364 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4365 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4366 return loader->corrupted;
4370 * Checks what kind of bad data confused the loader.
4372 * @param loader the loader
4373 * @returns why the loader is hosed, or DBUS_VALID if it isn't.
4376 _dbus_message_loader_get_corruption_reason (DBusMessageLoader *loader)
4378 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4379 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4381 return loader->corruption_reason;
4385 * Sets the maximum size message we allow.
4387 * @param loader the loader
4388 * @param size the max message size in bytes
4391 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
4394 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
4396 _dbus_verbose ("clamping requested max message size %ld to %d\n",
4397 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
4398 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4400 loader->max_message_size = size;
4404 * Gets the maximum allowed message size in bytes.
4406 * @param loader the loader
4407 * @returns max size in bytes
4410 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
4412 return loader->max_message_size;
4416 * Sets the maximum unix fds per message we allow.
4418 * @param loader the loader
4419 * @param n the max number of unix fds in a message
4422 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader,
4425 if (n > DBUS_MAXIMUM_MESSAGE_UNIX_FDS)
4427 _dbus_verbose ("clamping requested max message unix_fds %ld to %d\n",
4428 n, DBUS_MAXIMUM_MESSAGE_UNIX_FDS);
4429 n = DBUS_MAXIMUM_MESSAGE_UNIX_FDS;
4431 loader->max_message_unix_fds = n;
4435 * Gets the maximum allowed number of unix fds per message
4437 * @param loader the loader
4438 * @returns max unix fds
4441 _dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
4443 return loader->max_message_unix_fds;
4446 static DBusDataSlotAllocator slot_allocator =
4447 _DBUS_DATA_SLOT_ALLOCATOR_INIT (_DBUS_LOCK_NAME (message_slots));
4450 * Allocates an integer ID to be used for storing application-specific
4451 * data on any DBusMessage. The allocated ID may then be used
4452 * with dbus_message_set_data() and dbus_message_get_data().
4453 * The passed-in slot must be initialized to -1, and is filled in
4454 * with the slot ID. If the passed-in slot is not -1, it's assumed
4455 * to be already allocated, and its refcount is incremented.
4457 * The allocated slot is global, i.e. all DBusMessage objects will
4458 * have a slot with the given integer ID reserved.
4460 * @param slot_p address of a global variable storing the slot
4461 * @returns #FALSE on failure (no memory)
4464 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
4466 return _dbus_data_slot_allocator_alloc (&slot_allocator,
4471 * Deallocates a global ID for message data slots.
4472 * dbus_message_get_data() and dbus_message_set_data() may no
4473 * longer be used with this slot. Existing data stored on existing
4474 * DBusMessage objects will be freed when the message is
4475 * finalized, but may not be retrieved (and may only be replaced if
4476 * someone else reallocates the slot). When the refcount on the
4477 * passed-in slot reaches 0, it is set to -1.
4479 * @param slot_p address storing the slot to deallocate
4482 dbus_message_free_data_slot (dbus_int32_t *slot_p)
4484 _dbus_return_if_fail (*slot_p >= 0);
4486 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
4490 * Stores a pointer on a DBusMessage, along
4491 * with an optional function to be used for freeing
4492 * the data when the data is set again, or when
4493 * the message is finalized. The slot number
4494 * must have been allocated with dbus_message_allocate_data_slot().
4496 * @param message the message
4497 * @param slot the slot number
4498 * @param data the data to store
4499 * @param free_data_func finalizer function for the data
4500 * @returns #TRUE if there was enough memory to store the data
4503 dbus_message_set_data (DBusMessage *message,
4506 DBusFreeFunction free_data_func)
4508 DBusFreeFunction old_free_func;
4512 _dbus_return_val_if_fail (message != NULL, FALSE);
4513 _dbus_return_val_if_fail (slot >= 0, FALSE);
4515 retval = _dbus_data_slot_list_set (&slot_allocator,
4516 &message->slot_list,
4517 slot, data, free_data_func,
4518 &old_free_func, &old_data);
4522 /* Do the actual free outside the message lock */
4524 (* old_free_func) (old_data);
4531 * Retrieves data previously set with dbus_message_set_data().
4532 * The slot must still be allocated (must not have been freed).
4534 * @param message the message
4535 * @param slot the slot to get data from
4536 * @returns the data, or #NULL if not found
4539 dbus_message_get_data (DBusMessage *message,
4544 _dbus_return_val_if_fail (message != NULL, NULL);
4546 res = _dbus_data_slot_list_get (&slot_allocator,
4547 &message->slot_list,
4554 * Utility function to convert a machine-readable (not translated)
4555 * string into a D-Bus message type.
4558 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
4559 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
4560 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
4561 * "error" -> DBUS_MESSAGE_TYPE_ERROR
4562 * anything else -> DBUS_MESSAGE_TYPE_INVALID
4567 dbus_message_type_from_string (const char *type_str)
4569 if (strcmp (type_str, "method_call") == 0)
4570 return DBUS_MESSAGE_TYPE_METHOD_CALL;
4571 if (strcmp (type_str, "method_return") == 0)
4572 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
4573 else if (strcmp (type_str, "signal") == 0)
4574 return DBUS_MESSAGE_TYPE_SIGNAL;
4575 else if (strcmp (type_str, "error") == 0)
4576 return DBUS_MESSAGE_TYPE_ERROR;
4578 return DBUS_MESSAGE_TYPE_INVALID;
4582 * Utility function to convert a D-Bus message type into a
4583 * machine-readable string (not translated).
4586 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
4587 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
4588 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
4589 * DBUS_MESSAGE_TYPE_ERROR -> "error"
4590 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
4595 dbus_message_type_to_string (int type)
4599 case DBUS_MESSAGE_TYPE_METHOD_CALL:
4600 return "method_call";
4601 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
4602 return "method_return";
4603 case DBUS_MESSAGE_TYPE_SIGNAL:
4605 case DBUS_MESSAGE_TYPE_ERROR:
4613 * Turn a DBusMessage into the marshalled form as described in the D-Bus
4616 * Generally, this function is only useful for encapsulating D-Bus messages in
4617 * a different protocol.
4619 * @param msg the DBusMessage
4620 * @param marshalled_data_p the location to save the marshalled form to
4621 * @param len_p the location to save the length of the marshalled form to
4622 * @returns #FALSE if there was not enough memory
4625 dbus_message_marshal (DBusMessage *msg,
4626 char **marshalled_data_p,
4630 dbus_bool_t was_locked;
4632 _dbus_return_val_if_fail (msg != NULL, FALSE);
4633 _dbus_return_val_if_fail (marshalled_data_p != NULL, FALSE);
4634 _dbus_return_val_if_fail (len_p != NULL, FALSE);
4636 if (!_dbus_string_init (&tmp))
4639 /* Ensure the message is locked, to ensure the length header is filled in. */
4640 was_locked = msg->locked;
4643 dbus_message_lock (msg);
4645 if (!_dbus_string_copy (&(msg->header.data), 0, &tmp, 0))
4648 *len_p = _dbus_string_get_length (&tmp);
4650 if (!_dbus_string_copy (&(msg->body), 0, &tmp, *len_p))
4653 *len_p = _dbus_string_get_length (&tmp);
4655 if (!_dbus_string_steal_data (&tmp, marshalled_data_p))
4658 _dbus_string_free (&tmp);
4661 msg->locked = FALSE;
4666 _dbus_string_free (&tmp);
4669 msg->locked = FALSE;
4675 * Demarshal a D-Bus message from the format described in the D-Bus
4678 * Generally, this function is only useful for encapsulating D-Bus messages in
4679 * a different protocol.
4681 * @param str the marshalled DBusMessage
4682 * @param len the length of str
4683 * @param error the location to save errors to
4684 * @returns #NULL if there was an error
4687 dbus_message_demarshal (const char *str,
4691 DBusMessageLoader *loader;
4695 _dbus_return_val_if_fail (str != NULL, NULL);
4697 loader = _dbus_message_loader_new ();
4702 _dbus_message_loader_get_buffer (loader, &buffer);
4703 _dbus_string_append_len (buffer, str, len);
4704 _dbus_message_loader_return_buffer (loader, buffer, len);
4706 if (!_dbus_message_loader_queue_messages (loader))
4709 if (_dbus_message_loader_get_is_corrupted (loader))
4712 msg = _dbus_message_loader_pop_message (loader);
4717 _dbus_message_loader_unref (loader);
4721 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS, "Message is corrupted (%s)",
4722 _dbus_validity_to_error_message (loader->corruption_reason));
4723 _dbus_message_loader_unref (loader);
4727 _DBUS_SET_OOM (error);
4728 _dbus_message_loader_unref (loader);
4733 * Returns the number of bytes required to be in the buffer to demarshal a
4736 * Generally, this function is only useful for encapsulating D-Bus messages in
4737 * a different protocol.
4739 * @param buf data to be marshalled
4740 * @param len the length of @p buf
4741 * @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
4745 dbus_message_demarshal_bytes_needed(const char *buf,
4749 int byte_order, fields_array_len, header_len, body_len;
4750 DBusValidity validity = DBUS_VALID;
4753 if (!buf || len < DBUS_MINIMUM_HEADER_SIZE)
4756 if (len > DBUS_MAXIMUM_MESSAGE_LENGTH)
4757 len = DBUS_MAXIMUM_MESSAGE_LENGTH;
4758 _dbus_string_init_const_len (&str, buf, len);
4760 validity = DBUS_VALID;
4762 = _dbus_header_have_message_untrusted(DBUS_MAXIMUM_MESSAGE_LENGTH,
4763 &validity, &byte_order,
4769 _dbus_string_free (&str);
4771 if (validity == DBUS_VALID)
4773 _dbus_assert (have_message || (header_len + body_len) > len);
4774 (void) have_message; /* unused unless asserting */
4775 return header_len + body_len;
4779 return -1; /* broken! */
4785 /* tests in dbus-message-util.c */