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"
37 #ifdef HAVE_UNIX_FD_PASSING
38 #include "dbus-sysdeps.h"
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 set_or_delete_string_field (DBusMessage *message,
406 return _dbus_header_delete_field (&message->header, field);
408 return _dbus_header_set_field_basic (&message->header,
415 /* Probably we don't need to use this */
417 * Sets the signature of the message, i.e. the arguments in the
418 * message payload. The signature includes only "in" arguments for
419 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
420 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
421 * what you might expect (it does not include the signature of the
422 * entire C++-style method).
424 * The signature is a string made up of type codes such as
425 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
426 * the value of #DBUS_TYPE_INVALID). The macros such as
427 * #DBUS_TYPE_INT32 evaluate to integers; to assemble a signature you
428 * may find it useful to use the string forms, such as
429 * #DBUS_TYPE_INT32_AS_STRING.
431 * An "unset" or #NULL signature is considered the same as an empty
432 * signature. In fact dbus_message_get_signature() will never return
435 * @param message the message
436 * @param signature the type signature or #NULL to unset
437 * @returns #FALSE if no memory
440 _dbus_message_set_signature (DBusMessage *message,
441 const char *signature)
443 _dbus_return_val_if_fail (message != NULL, FALSE);
444 _dbus_return_val_if_fail (!message->locked, FALSE);
445 _dbus_return_val_if_fail (signature == NULL ||
446 _dbus_check_is_valid_signature (signature));
447 /* can't delete the signature if you have a message body */
448 _dbus_return_val_if_fail (_dbus_string_get_length (&message->body) == 0 ||
451 return set_or_delete_string_field (message,
452 DBUS_HEADER_FIELD_SIGNATURE,
460 * We cache some DBusMessage to reduce the overhead of allocating
461 * them. In my profiling this consistently made about an 8%
462 * difference. It avoids the malloc for the message, the malloc for
463 * the slot list, the malloc for the header string and body string,
464 * and the associated free() calls. It does introduce another global
465 * lock which could be a performance issue in certain cases.
467 * For the echo client/server the round trip time goes from around
468 * .000077 to .000069 with the message cache on my laptop. The sysprof
469 * change is as follows (numbers are cumulative percentage):
471 * with message cache implemented as array as it is now (0.000069 per):
472 * new_empty_header 1.46
473 * mutex_lock 0.56 # i.e. _DBUS_LOCK(message_cache)
479 * mutex_lock 0.33 # i.e. _DBUS_LOCK(message_cache)
482 * with message cache implemented as list (0.000070 per roundtrip):
483 * new_empty_header 2.72
484 * list_pop_first 1.88
488 * without cache (0.000077 per roundtrip):
489 * new_empty_header 6.7
490 * string_init_preallocated 3.43
499 * If you implement the message_cache with a list, the primary reason
500 * it's slower is that you add another thread lock (on the DBusList
504 /** Avoid caching huge messages */
505 #define MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE
507 /** Avoid caching too many messages */
508 #define MAX_MESSAGE_CACHE_SIZE 5
510 /* Protected by _DBUS_LOCK (message_cache) */
511 static DBusMessage *message_cache[MAX_MESSAGE_CACHE_SIZE];
512 static int message_cache_count = 0;
513 static dbus_bool_t message_cache_shutdown_registered = FALSE;
516 dbus_message_cache_shutdown (void *data)
520 if (!_DBUS_LOCK (message_cache))
521 _dbus_assert_not_reached ("we would have initialized global locks "
522 "before registering a shutdown function");
525 while (i < MAX_MESSAGE_CACHE_SIZE)
527 if (message_cache[i])
528 dbus_message_finalize (message_cache[i]);
533 message_cache_count = 0;
534 message_cache_shutdown_registered = FALSE;
536 _DBUS_UNLOCK (message_cache);
540 * Tries to get a message from the message cache. The retrieved
541 * message will have junk in it, so it still needs to be cleared out
542 * in dbus_message_new_empty_header()
544 * @returns the message, or #NULL if none cached
547 dbus_message_get_cached (void)
549 DBusMessage *message;
554 if (!_DBUS_LOCK (message_cache))
556 /* we'd have initialized global locks before caching anything,
557 * so there can't be anything in the cache */
561 _dbus_assert (message_cache_count >= 0);
563 if (message_cache_count == 0)
565 _DBUS_UNLOCK (message_cache);
569 /* This is not necessarily true unless count > 0, and
570 * message_cache is uninitialized until the shutdown is
573 _dbus_assert (message_cache_shutdown_registered);
576 while (i < MAX_MESSAGE_CACHE_SIZE)
578 if (message_cache[i])
580 message = message_cache[i];
581 message_cache[i] = NULL;
582 message_cache_count -= 1;
587 _dbus_assert (message_cache_count >= 0);
588 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
589 _dbus_assert (message != NULL);
591 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
593 _dbus_assert (message->counters == NULL);
595 _DBUS_UNLOCK (message_cache);
600 #ifdef HAVE_UNIX_FD_PASSING
602 close_unix_fds(int *fds, unsigned *n_fds)
612 for (i = 0; i < *n_fds; i++)
614 if (!_dbus_close(fds[i], &e))
616 _dbus_warn("Failed to close file descriptor: %s\n", e.message);
623 /* We don't free the array here, in case we can recycle it later */
628 free_counter (void *element,
631 DBusCounter *counter = element;
632 DBusMessage *message = data;
634 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
635 #ifdef HAVE_UNIX_FD_PASSING
636 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
639 _dbus_counter_notify (counter);
640 _dbus_counter_unref (counter);
644 * Tries to cache a message, otherwise finalize it.
646 * @param message the message
649 dbus_message_cache_or_finalize (DBusMessage *message)
651 dbus_bool_t was_cached;
654 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
656 /* This calls application code and has to be done first thing
657 * without holding the lock
659 _dbus_data_slot_list_clear (&message->slot_list);
661 _dbus_list_foreach (&message->counters,
662 free_counter, message);
663 _dbus_list_clear (&message->counters);
665 #ifdef HAVE_UNIX_FD_PASSING
666 close_unix_fds(message->unix_fds, &message->n_unix_fds);
671 if (!_DBUS_LOCK (message_cache))
673 /* The only way to get a non-null message goes through
674 * dbus_message_get_cached() which takes the lock. */
675 _dbus_assert_not_reached ("we would have initialized global locks "
676 "the first time we constructed a message");
679 if (!message_cache_shutdown_registered)
681 _dbus_assert (message_cache_count == 0);
683 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
687 while (i < MAX_MESSAGE_CACHE_SIZE)
689 message_cache[i] = NULL;
693 message_cache_shutdown_registered = TRUE;
696 _dbus_assert (message_cache_count >= 0);
698 if (!_dbus_enable_message_cache ())
701 if ((_dbus_string_get_length (&message->header.data) +
702 _dbus_string_get_length (&message->body)) >
703 MAX_MESSAGE_SIZE_TO_CACHE)
706 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
709 /* Find empty slot */
711 while (message_cache[i] != NULL)
714 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
716 _dbus_assert (message_cache[i] == NULL);
717 message_cache[i] = message;
718 message_cache_count += 1;
720 #ifndef DBUS_DISABLE_CHECKS
721 message->in_cache = TRUE;
725 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
727 _DBUS_UNLOCK (message_cache);
730 dbus_message_finalize (message);
733 #if defined(DBUS_ENABLE_CHECKS) || defined(DBUS_ENABLE_ASSERT)
735 _dbus_message_iter_check (DBusMessageRealIter *iter)
741 _dbus_warn_check_failed ("dbus message iterator is NULL\n");
745 byte_order = _dbus_header_get_byte_order (&iter->message->header);
747 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
749 if (iter->u.reader.byte_order != byte_order)
751 _dbus_warn_check_failed ("dbus message changed byte order since iterator was created\n");
754 /* because we swap the message into compiler order when you init an iter */
755 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
757 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
759 if (iter->u.writer.byte_order != byte_order)
761 _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created\n");
764 /* because we swap the message into compiler order when you init an iter */
765 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
769 _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted\n");
773 if (iter->changed_stamp != iter->message->changed_stamp)
775 _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
781 #endif /* DBUS_ENABLE_CHECKS || DBUS_ENABLE_ASSERT */
784 * Implementation of the varargs arg-getting functions.
785 * dbus_message_get_args() is the place to go for complete
788 * @see dbus_message_get_args
789 * @param iter the message iter
790 * @param error error to be filled in
791 * @param first_arg_type type of the first argument
792 * @param var_args return location for first argument, followed by list of type/location pairs
793 * @returns #FALSE if error was set
796 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
801 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
802 int spec_type, msg_type, i, j;
806 _dbus_assert (_dbus_message_iter_check (real));
810 spec_type = first_arg_type;
813 /* copy var_args first, then we can do another iteration over it to
814 * free memory and close unix fds if parse failed at some point.
816 DBUS_VA_COPY (copy_args, var_args);
818 while (spec_type != DBUS_TYPE_INVALID)
820 msg_type = dbus_message_iter_get_arg_type (iter);
822 if (msg_type != spec_type)
824 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
825 "Argument %d is specified to be of type \"%s\", but "
826 "is actually of type \"%s\"\n", i,
827 _dbus_type_to_string (spec_type),
828 _dbus_type_to_string (msg_type));
833 if (spec_type == DBUS_TYPE_UNIX_FD)
835 #ifdef HAVE_UNIX_FD_PASSING
839 pfd = va_arg (var_args, int*);
842 _dbus_type_reader_read_basic(&real->u.reader, &idx);
844 if (idx.u32 >= real->message->n_unix_fds)
846 dbus_set_error (error, DBUS_ERROR_INCONSISTENT_MESSAGE,
847 "Message refers to file descriptor at index %i,"
848 "but has only %i descriptors attached.\n",
850 real->message->n_unix_fds);
854 if ((nfd = _dbus_dup(real->message->unix_fds[idx.u32], error)) < 0)
859 dbus_set_error (error, DBUS_ERROR_NOT_SUPPORTED,
860 "Platform does not support file desciptor passing.\n");
864 else if (dbus_type_is_basic (spec_type))
868 ptr = va_arg (var_args, DBusBasicValue*);
870 _dbus_assert (ptr != NULL);
872 _dbus_type_reader_read_basic (&real->u.reader,
875 else if (spec_type == DBUS_TYPE_ARRAY)
878 int spec_element_type;
879 const DBusBasicValue **ptr;
881 DBusTypeReader array;
883 spec_element_type = va_arg (var_args, int);
884 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
886 if (spec_element_type != element_type)
888 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
889 "Argument %d is specified to be an array of \"%s\", but "
890 "is actually an array of \"%s\"\n",
892 _dbus_type_to_string (spec_element_type),
893 _dbus_type_to_string (element_type));
898 if (dbus_type_is_fixed (spec_element_type) &&
899 element_type != DBUS_TYPE_UNIX_FD)
901 ptr = va_arg (var_args, const DBusBasicValue**);
902 n_elements_p = va_arg (var_args, int*);
904 _dbus_assert (ptr != NULL);
905 _dbus_assert (n_elements_p != NULL);
907 _dbus_type_reader_recurse (&real->u.reader, &array);
909 _dbus_type_reader_read_fixed_multi (&array,
910 (void *) ptr, n_elements_p);
912 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
918 str_array_p = va_arg (var_args, char***);
919 n_elements_p = va_arg (var_args, int*);
921 _dbus_assert (str_array_p != NULL);
922 _dbus_assert (n_elements_p != NULL);
924 /* Count elements in the array */
925 _dbus_type_reader_recurse (&real->u.reader, &array);
928 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
931 _dbus_type_reader_next (&array);
934 str_array = dbus_new0 (char*, n_elements + 1);
935 if (str_array == NULL)
937 _DBUS_SET_OOM (error);
941 /* Now go through and dup each string */
942 _dbus_type_reader_recurse (&real->u.reader, &array);
945 while (j < n_elements)
948 _dbus_type_reader_read_basic (&array,
951 str_array[j] = _dbus_strdup (s);
952 if (str_array[j] == NULL)
954 dbus_free_string_array (str_array);
955 _DBUS_SET_OOM (error);
961 if (!_dbus_type_reader_next (&array))
962 _dbus_assert (j == n_elements);
965 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
966 _dbus_assert (j == n_elements);
967 _dbus_assert (str_array[j] == NULL);
969 *str_array_p = str_array;
970 *n_elements_p = n_elements;
972 #ifndef DBUS_DISABLE_CHECKS
975 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
976 _DBUS_FUNCTION_NAME);
981 #ifndef DBUS_DISABLE_CHECKS
984 _dbus_warn ("you can only read arrays and basic types with %s for now\n",
985 _DBUS_FUNCTION_NAME);
990 /* how many arguments already handled */
993 spec_type = va_arg (var_args, int);
994 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
996 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
997 "Message has only %d arguments, but more were expected", i);
1005 /* there may memory or unix fd leak in the above iteration if parse failed.
1006 * so we have another iteration over copy_args to free memory and close
1011 spec_type = first_arg_type;
1016 if (spec_type == DBUS_TYPE_UNIX_FD)
1018 #ifdef HAVE_UNIX_FD_PASSING
1021 pfd = va_arg (copy_args, int *);
1025 _dbus_close (*pfd, NULL);
1030 else if (dbus_type_is_basic (spec_type))
1032 /* move the index forward */
1033 va_arg (copy_args, DBusBasicValue *);
1035 else if (spec_type == DBUS_TYPE_ARRAY)
1037 int spec_element_type;
1039 spec_element_type = va_arg (copy_args, int);
1040 if (dbus_type_is_fixed (spec_element_type))
1042 /* move the index forward */
1043 va_arg (copy_args, const DBusBasicValue **);
1044 va_arg (copy_args, int *);
1046 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
1048 char ***str_array_p;
1050 str_array_p = va_arg (copy_args, char ***);
1051 /* move the index forward */
1052 va_arg (copy_args, int *);
1053 _dbus_assert (str_array_p != NULL);
1054 dbus_free_string_array (*str_array_p);
1055 *str_array_p = NULL;
1059 spec_type = va_arg (copy_args, int);
1071 * @defgroup DBusMessage DBusMessage
1073 * @brief Message to be sent or received over a #DBusConnection.
1075 * A DBusMessage is the most basic unit of communication over a
1076 * DBusConnection. A DBusConnection represents a stream of messages
1077 * received from a remote application, and a stream of messages
1078 * sent to a remote application.
1080 * A message has a message type, returned from
1081 * dbus_message_get_type(). This indicates whether the message is a
1082 * method call, a reply to a method call, a signal, or an error reply.
1084 * A message has header fields such as the sender, destination, method
1085 * or signal name, and so forth. DBusMessage has accessor functions for
1086 * these, such as dbus_message_get_member().
1088 * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
1089 * and dbus_message_is_error() check several header fields at once and are
1090 * slightly more efficient than checking the header fields with individual
1091 * accessor functions.
1093 * Finally, a message has arguments. The number and types of arguments
1094 * are in the message's signature header field (accessed with
1095 * dbus_message_get_signature()). Simple argument values are usually
1096 * retrieved with dbus_message_get_args() but more complex values such
1097 * as structs may require the use of #DBusMessageIter.
1099 * The D-Bus specification goes into some more detail about header fields and
1106 * @typedef DBusMessage
1108 * Opaque data type representing a message received from or to be
1109 * sent to another application.
1113 * Returns the serial of a message or 0 if none has been specified.
1114 * The message's serial number is provided by the application sending
1115 * the message and is used to identify replies to this message.
1117 * All messages received on a connection will have a serial provided
1118 * by the remote application.
1120 * For messages you're sending, dbus_connection_send() will assign a
1121 * serial and return it to you.
1123 * @param message the message
1124 * @returns the serial
1127 dbus_message_get_serial (DBusMessage *message)
1129 _dbus_return_val_if_fail (message != NULL, 0);
1131 return _dbus_header_get_serial (&message->header);
1135 * Sets the reply serial of a message (the serial of the message this
1138 * @param message the message
1139 * @param reply_serial the serial we're replying to
1140 * @returns #FALSE if not enough memory
1143 dbus_message_set_reply_serial (DBusMessage *message,
1144 dbus_uint32_t reply_serial)
1146 _dbus_return_val_if_fail (message != NULL, FALSE);
1147 _dbus_return_val_if_fail (!message->locked, FALSE);
1148 _dbus_return_val_if_fail (reply_serial != 0, FALSE); /* 0 is invalid */
1150 return _dbus_header_set_field_basic (&message->header,
1151 DBUS_HEADER_FIELD_REPLY_SERIAL,
1157 * Returns the serial that the message is a reply to or 0 if none.
1159 * @param message the message
1160 * @returns the reply serial
1163 dbus_message_get_reply_serial (DBusMessage *message)
1165 dbus_uint32_t v_UINT32;
1167 _dbus_return_val_if_fail (message != NULL, 0);
1169 if (_dbus_header_get_field_basic (&message->header,
1170 DBUS_HEADER_FIELD_REPLY_SERIAL,
1179 dbus_message_finalize (DBusMessage *message)
1181 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1183 /* This calls application callbacks! */
1184 _dbus_data_slot_list_free (&message->slot_list);
1186 _dbus_list_foreach (&message->counters,
1187 free_counter, message);
1188 _dbus_list_clear (&message->counters);
1190 _dbus_header_free (&message->header);
1191 _dbus_string_free (&message->body);
1193 #ifdef HAVE_UNIX_FD_PASSING
1194 close_unix_fds(message->unix_fds, &message->n_unix_fds);
1195 dbus_free(message->unix_fds);
1198 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1200 dbus_free (message);
1204 dbus_message_new_empty_header (void)
1206 DBusMessage *message;
1207 dbus_bool_t from_cache;
1209 message = dbus_message_get_cached ();
1211 if (message != NULL)
1218 message = dbus_new0 (DBusMessage, 1);
1219 if (message == NULL)
1221 #ifndef DBUS_DISABLE_CHECKS
1222 message->generation = _dbus_current_generation;
1225 #ifdef HAVE_UNIX_FD_PASSING
1226 message->unix_fds = NULL;
1227 message->n_unix_fds_allocated = 0;
1231 _dbus_atomic_inc (&message->refcount);
1233 _dbus_message_trace_ref (message, 0, 1, "new_empty_header");
1235 message->locked = FALSE;
1236 #ifndef DBUS_DISABLE_CHECKS
1237 message->in_cache = FALSE;
1239 message->counters = NULL;
1240 message->size_counter_delta = 0;
1241 message->changed_stamp = 0;
1243 #ifdef HAVE_UNIX_FD_PASSING
1244 message->n_unix_fds = 0;
1245 message->n_unix_fds_allocated = 0;
1246 message->unix_fd_counter_delta = 0;
1250 _dbus_data_slot_list_init (&message->slot_list);
1254 _dbus_header_reinit (&message->header);
1255 _dbus_string_set_length (&message->body, 0);
1259 if (!_dbus_header_init (&message->header))
1261 dbus_free (message);
1265 if (!_dbus_string_init_preallocated (&message->body, 32))
1267 _dbus_header_free (&message->header);
1268 dbus_free (message);
1277 * Constructs a new message of the given message type.
1278 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
1279 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
1281 * Usually you want to use dbus_message_new_method_call(),
1282 * dbus_message_new_method_return(), dbus_message_new_signal(),
1283 * or dbus_message_new_error() instead.
1285 * @param message_type type of message
1286 * @returns new message or #NULL if no memory
1289 dbus_message_new (int message_type)
1291 DBusMessage *message;
1293 _dbus_return_val_if_fail (message_type != DBUS_MESSAGE_TYPE_INVALID, NULL);
1295 message = dbus_message_new_empty_header ();
1296 if (message == NULL)
1299 if (!_dbus_header_create (&message->header,
1300 DBUS_COMPILER_BYTE_ORDER,
1302 NULL, NULL, NULL, NULL, NULL))
1304 dbus_message_unref (message);
1312 * Constructs a new message to invoke a method on a remote
1313 * object. Returns #NULL if memory can't be allocated for the
1314 * message. The destination may be #NULL in which case no destination
1315 * is set; this is appropriate when using D-Bus in a peer-to-peer
1316 * context (no message bus). The interface may be #NULL, which means
1317 * that if multiple methods with the given name exist it is undefined
1318 * which one will be invoked.
1320 * The path and method names may not be #NULL.
1322 * Destination, path, interface, and method name can't contain
1323 * any invalid characters (see the D-Bus specification).
1325 * @param destination name that the message should be sent to or #NULL
1326 * @param path object path the message should be sent to
1327 * @param iface interface to invoke method on, or #NULL
1328 * @param method method to invoke
1330 * @returns a new DBusMessage, free with dbus_message_unref()
1333 dbus_message_new_method_call (const char *destination,
1338 DBusMessage *message;
1340 _dbus_return_val_if_fail (path != NULL, NULL);
1341 _dbus_return_val_if_fail (method != NULL, NULL);
1342 _dbus_return_val_if_fail (destination == NULL ||
1343 _dbus_check_is_valid_bus_name (destination), NULL);
1344 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1345 _dbus_return_val_if_fail (iface == NULL ||
1346 _dbus_check_is_valid_interface (iface), NULL);
1347 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
1349 message = dbus_message_new_empty_header ();
1350 if (message == NULL)
1353 if (!_dbus_header_create (&message->header,
1354 DBUS_COMPILER_BYTE_ORDER,
1355 DBUS_MESSAGE_TYPE_METHOD_CALL,
1356 destination, path, iface, method, NULL))
1358 dbus_message_unref (message);
1366 * Constructs a message that is a reply to a method call. Returns
1367 * #NULL if memory can't be allocated for the message.
1369 * @param method_call the message being replied to
1370 * @returns a new DBusMessage, free with dbus_message_unref()
1373 dbus_message_new_method_return (DBusMessage *method_call)
1375 DBusMessage *message;
1378 _dbus_return_val_if_fail (method_call != NULL, NULL);
1380 sender = dbus_message_get_sender (method_call);
1382 /* sender is allowed to be null here in peer-to-peer case */
1384 message = dbus_message_new_empty_header ();
1385 if (message == NULL)
1388 if (!_dbus_header_create (&message->header,
1389 DBUS_COMPILER_BYTE_ORDER,
1390 DBUS_MESSAGE_TYPE_METHOD_RETURN,
1391 sender, NULL, NULL, NULL, NULL))
1393 dbus_message_unref (message);
1397 dbus_message_set_no_reply (message, TRUE);
1399 if (!dbus_message_set_reply_serial (message,
1400 dbus_message_get_serial (method_call)))
1402 dbus_message_unref (message);
1410 * Constructs a new message representing a signal emission. Returns
1411 * #NULL if memory can't be allocated for the message. A signal is
1412 * identified by its originating object path, interface, and the name
1415 * Path, interface, and signal name must all be valid (the D-Bus
1416 * specification defines the syntax of these fields).
1418 * @param path the path to the object emitting the signal
1419 * @param iface the interface the signal is emitted from
1420 * @param name name of the signal
1421 * @returns a new DBusMessage, free with dbus_message_unref()
1424 dbus_message_new_signal (const char *path,
1428 DBusMessage *message;
1430 _dbus_return_val_if_fail (path != NULL, NULL);
1431 _dbus_return_val_if_fail (iface != NULL, NULL);
1432 _dbus_return_val_if_fail (name != NULL, NULL);
1433 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1434 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (iface), NULL);
1435 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
1437 message = dbus_message_new_empty_header ();
1438 if (message == NULL)
1441 if (!_dbus_header_create (&message->header,
1442 DBUS_COMPILER_BYTE_ORDER,
1443 DBUS_MESSAGE_TYPE_SIGNAL,
1444 NULL, path, iface, name, NULL))
1446 dbus_message_unref (message);
1450 dbus_message_set_no_reply (message, TRUE);
1456 * Creates a new message that is an error reply to another message.
1457 * Error replies are most common in response to method calls, but
1458 * can be returned in reply to any message.
1460 * The error name must be a valid error name according to the syntax
1461 * given in the D-Bus specification. If you don't want to make
1462 * up an error name just use #DBUS_ERROR_FAILED.
1464 * @param reply_to the message we're replying to
1465 * @param error_name the error name
1466 * @param error_message the error message string (or #NULL for none, but please give a message)
1467 * @returns a new error message object, free with dbus_message_unref()
1470 dbus_message_new_error (DBusMessage *reply_to,
1471 const char *error_name,
1472 const char *error_message)
1474 DBusMessage *message;
1476 DBusMessageIter iter;
1478 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1479 _dbus_return_val_if_fail (error_name != NULL, NULL);
1480 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1482 sender = dbus_message_get_sender (reply_to);
1484 /* sender may be NULL for non-message-bus case or
1485 * when the message bus is dealing with an unregistered
1488 message = dbus_message_new_empty_header ();
1489 if (message == NULL)
1492 if (!_dbus_header_create (&message->header,
1493 DBUS_COMPILER_BYTE_ORDER,
1494 DBUS_MESSAGE_TYPE_ERROR,
1495 sender, NULL, NULL, NULL, error_name))
1497 dbus_message_unref (message);
1501 dbus_message_set_no_reply (message, TRUE);
1503 if (!dbus_message_set_reply_serial (message,
1504 dbus_message_get_serial (reply_to)))
1506 dbus_message_unref (message);
1510 if (error_message != NULL)
1512 dbus_message_iter_init_append (message, &iter);
1513 if (!dbus_message_iter_append_basic (&iter,
1517 dbus_message_unref (message);
1526 * Creates a new message that is an error reply to another message, allowing
1527 * you to use printf formatting.
1529 * See dbus_message_new_error() for details - this function is the same
1530 * aside from the printf formatting.
1532 * @todo add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to
1533 * public header, see DBUS_DEPRECATED for an example)
1535 * @param reply_to the original message
1536 * @param error_name the error name
1537 * @param error_format the error message format as with printf
1538 * @param ... format string arguments
1539 * @returns a new error message
1542 dbus_message_new_error_printf (DBusMessage *reply_to,
1543 const char *error_name,
1544 const char *error_format,
1549 DBusMessage *message;
1551 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1552 _dbus_return_val_if_fail (error_name != NULL, NULL);
1553 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1555 if (!_dbus_string_init (&str))
1558 va_start (args, error_format);
1560 if (_dbus_string_append_printf_valist (&str, error_format, args))
1561 message = dbus_message_new_error (reply_to, error_name,
1562 _dbus_string_get_const_data (&str));
1566 _dbus_string_free (&str);
1575 * Creates a new message that is an exact replica of the message
1576 * specified, except that its refcount is set to 1, its message serial
1577 * is reset to 0, and if the original message was "locked" (in the
1578 * outgoing message queue and thus not modifiable) the new message
1579 * will not be locked.
1581 * @todo This function can't be used in programs that try to recover from OOM errors.
1583 * @param message the message
1584 * @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.
1587 dbus_message_copy (const DBusMessage *message)
1589 DBusMessage *retval;
1591 _dbus_return_val_if_fail (message != NULL, NULL);
1593 retval = dbus_new0 (DBusMessage, 1);
1597 _dbus_atomic_inc (&retval->refcount);
1599 retval->locked = FALSE;
1600 #ifndef DBUS_DISABLE_CHECKS
1601 retval->generation = message->generation;
1604 if (!_dbus_header_copy (&message->header, &retval->header))
1610 if (!_dbus_string_init_preallocated (&retval->body,
1611 _dbus_string_get_length (&message->body)))
1613 _dbus_header_free (&retval->header);
1618 if (!_dbus_string_copy (&message->body, 0,
1622 #ifdef HAVE_UNIX_FD_PASSING
1623 retval->unix_fds = dbus_new(int, message->n_unix_fds);
1624 if (retval->unix_fds == NULL && message->n_unix_fds > 0)
1627 retval->n_unix_fds_allocated = message->n_unix_fds;
1629 for (retval->n_unix_fds = 0;
1630 retval->n_unix_fds < message->n_unix_fds;
1631 retval->n_unix_fds++)
1633 retval->unix_fds[retval->n_unix_fds] = _dbus_dup(message->unix_fds[retval->n_unix_fds], NULL);
1635 if (retval->unix_fds[retval->n_unix_fds] < 0)
1641 _dbus_message_trace_ref (retval, 0, 1, "copy");
1645 _dbus_header_free (&retval->header);
1646 _dbus_string_free (&retval->body);
1648 #ifdef HAVE_UNIX_FD_PASSING
1649 close_unix_fds(retval->unix_fds, &retval->n_unix_fds);
1650 dbus_free(retval->unix_fds);
1660 * Increments the reference count of a DBusMessage.
1662 * @param message the message
1663 * @returns the message
1664 * @see dbus_message_unref
1667 dbus_message_ref (DBusMessage *message)
1669 dbus_int32_t old_refcount;
1671 _dbus_return_val_if_fail (message != NULL, NULL);
1672 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1673 _dbus_return_val_if_fail (!message->in_cache, NULL);
1675 old_refcount = _dbus_atomic_inc (&message->refcount);
1676 _dbus_assert (old_refcount >= 1);
1677 _dbus_message_trace_ref (message, old_refcount, old_refcount + 1, "ref");
1683 * Decrements the reference count of a DBusMessage, freeing the
1684 * message if the count reaches 0.
1686 * @param message the message
1687 * @see dbus_message_ref
1690 dbus_message_unref (DBusMessage *message)
1692 dbus_int32_t old_refcount;
1694 _dbus_return_if_fail (message != NULL);
1695 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1696 _dbus_return_if_fail (!message->in_cache);
1698 old_refcount = _dbus_atomic_dec (&message->refcount);
1700 _dbus_assert (old_refcount >= 1);
1702 _dbus_message_trace_ref (message, old_refcount, old_refcount - 1, "unref");
1704 if (old_refcount == 1)
1706 /* Calls application callbacks! */
1707 dbus_message_cache_or_finalize (message);
1712 * Gets the type of a message. Types include
1713 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1714 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1715 * types are allowed and all code must silently ignore messages of
1716 * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
1718 * @param message the message
1719 * @returns the type of the message
1722 dbus_message_get_type (DBusMessage *message)
1724 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1726 return _dbus_header_get_message_type (&message->header);
1730 * Appends fields to a message given a variable argument list. The
1731 * variable argument list should contain the type of each argument
1732 * followed by the value to append. Appendable types are basic types,
1733 * and arrays of fixed-length basic types (except arrays of Unix file
1734 * descriptors). To append variable-length basic types, or any more
1735 * complex value, you have to use an iterator rather than this
1738 * To append a basic type, specify its type code followed by the
1739 * address of the value. For example:
1743 * dbus_int32_t v_INT32 = 42;
1744 * const char *v_STRING = "Hello World";
1745 * dbus_message_append_args (message,
1746 * DBUS_TYPE_INT32, &v_INT32,
1747 * DBUS_TYPE_STRING, &v_STRING,
1748 * DBUS_TYPE_INVALID);
1751 * To append an array of fixed-length basic types (except Unix file
1752 * descriptors), pass in the DBUS_TYPE_ARRAY typecode, the element
1753 * typecode, the address of the array pointer, and a 32-bit integer
1754 * giving the number of elements in the array. So for example: @code
1755 * const dbus_int32_t array[] = { 1, 2, 3 }; const dbus_int32_t
1756 * *v_ARRAY = array; dbus_message_append_args (message,
1757 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3, DBUS_TYPE_INVALID);
1760 * This function does not support arrays of Unix file descriptors. If
1761 * you need those you need to manually recurse into the array.
1763 * For Unix file descriptors this function will internally duplicate
1764 * the descriptor you passed in. Hence you may close the descriptor
1765 * immediately after this call.
1767 * @warning in C, given "int array[]", "&array == array" (the
1768 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
1769 * So if you're using an array instead of a pointer you have to create
1770 * a pointer variable, assign the array to it, then take the address
1771 * of the pointer variable. For strings it works to write
1772 * const char *array = "Hello" and then use &array though.
1774 * The last argument to this function must be #DBUS_TYPE_INVALID,
1775 * marking the end of the argument list. If you don't do this
1776 * then libdbus won't know to stop and will read invalid memory.
1778 * String/signature/path arrays should be passed in as "const char***
1779 * address_of_array" and "int n_elements"
1781 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1783 * @todo If this fails due to lack of memory, the message is hosed and
1784 * you have to start over building the whole message.
1786 * @param message the message
1787 * @param first_arg_type type of the first argument
1788 * @param ... value of first argument, list of additional type-value pairs
1789 * @returns #TRUE on success
1792 dbus_message_append_args (DBusMessage *message,
1799 _dbus_return_val_if_fail (message != NULL, FALSE);
1801 va_start (var_args, first_arg_type);
1802 retval = dbus_message_append_args_valist (message,
1811 * Like dbus_message_append_args() but takes a va_list for use by language bindings.
1813 * @todo for now, if this function fails due to OOM it will leave
1814 * the message half-written and you have to discard the message
1817 * @see dbus_message_append_args.
1818 * @param message the message
1819 * @param first_arg_type type of first argument
1820 * @param var_args value of first argument, then list of type/value pairs
1821 * @returns #TRUE on success
1824 dbus_message_append_args_valist (DBusMessage *message,
1829 DBusMessageIter iter;
1831 _dbus_return_val_if_fail (message != NULL, FALSE);
1833 type = first_arg_type;
1835 dbus_message_iter_init_append (message, &iter);
1837 while (type != DBUS_TYPE_INVALID)
1839 if (dbus_type_is_basic (type))
1841 const DBusBasicValue *value;
1842 value = va_arg (var_args, const DBusBasicValue*);
1844 if (!dbus_message_iter_append_basic (&iter,
1849 else if (type == DBUS_TYPE_ARRAY)
1852 DBusMessageIter array;
1855 element_type = va_arg (var_args, int);
1857 buf[0] = element_type;
1859 if (!dbus_message_iter_open_container (&iter,
1865 if (dbus_type_is_fixed (element_type) &&
1866 element_type != DBUS_TYPE_UNIX_FD)
1868 const DBusBasicValue **value;
1871 value = va_arg (var_args, const DBusBasicValue**);
1872 n_elements = va_arg (var_args, int);
1874 if (!dbus_message_iter_append_fixed_array (&array,
1878 dbus_message_iter_abandon_container (&iter, &array);
1882 else if (_DBUS_TYPE_IS_STRINGLIKE (element_type))
1884 const char ***value_p;
1889 value_p = va_arg (var_args, const char***);
1890 n_elements = va_arg (var_args, int);
1895 while (i < n_elements)
1897 if (!dbus_message_iter_append_basic (&array,
1900 dbus_message_iter_abandon_container (&iter, &array);
1908 _dbus_warn ("arrays of %s can't be appended with %s for now\n",
1909 _dbus_type_to_string (element_type),
1910 _DBUS_FUNCTION_NAME);
1914 if (!dbus_message_iter_close_container (&iter, &array))
1917 #ifndef DBUS_DISABLE_CHECKS
1920 _dbus_warn ("type %s isn't supported yet in %s\n",
1921 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
1926 type = va_arg (var_args, int);
1936 * Gets arguments from a message given a variable argument list. The
1937 * supported types include those supported by
1938 * dbus_message_append_args(); that is, basic types and arrays of
1939 * fixed-length basic types. The arguments are the same as they would
1940 * be for dbus_message_iter_get_basic() or
1941 * dbus_message_iter_get_fixed_array().
1943 * In addition to those types, arrays of string, object path, and
1944 * signature are supported; but these are returned as allocated memory
1945 * and must be freed with dbus_free_string_array(), while the other
1946 * types are returned as const references. To get a string array
1947 * pass in "char ***array_location" and "int *n_elements".
1949 * Similar to dbus_message_get_fixed_array() this function does not
1950 * support arrays of type DBUS_TYPE_UNIX_FD. If you need to parse
1951 * messages with arrays of Unix file descriptors you need to recurse
1952 * into the array manually.
1954 * Unix file descriptors that are read with this function will have
1955 * the FD_CLOEXEC flag set. If you need them without this flag set,
1956 * make sure to unset it with fcntl().
1958 * The variable argument list should contain the type of the argument
1959 * followed by a pointer to where the value should be stored. The list
1960 * is terminated with #DBUS_TYPE_INVALID.
1962 * Except for string arrays, the returned values are constant; do not
1963 * free them. They point into the #DBusMessage.
1965 * If the requested arguments are not present, or do not have the
1966 * requested types, then an error will be set.
1968 * If more arguments than requested are present, the requested
1969 * arguments are returned and the extra arguments are ignored.
1971 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1973 * @param message the message
1974 * @param error error to be filled in on failure
1975 * @param first_arg_type the first argument type
1976 * @param ... location for first argument value, then list of type-location pairs
1977 * @returns #FALSE if the error was set
1980 dbus_message_get_args (DBusMessage *message,
1988 _dbus_return_val_if_fail (message != NULL, FALSE);
1989 _dbus_return_val_if_error_is_set (error, FALSE);
1991 va_start (var_args, first_arg_type);
1992 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
1999 * Like dbus_message_get_args but takes a va_list for use by language bindings.
2001 * @see dbus_message_get_args
2002 * @param message the message
2003 * @param error error to be filled in
2004 * @param first_arg_type type of the first argument
2005 * @param var_args return location for first argument, followed by list of type/location pairs
2006 * @returns #FALSE if error was set
2009 dbus_message_get_args_valist (DBusMessage *message,
2014 DBusMessageIter iter;
2016 _dbus_return_val_if_fail (message != NULL, FALSE);
2017 _dbus_return_val_if_error_is_set (error, FALSE);
2019 dbus_message_iter_init (message, &iter);
2020 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
2024 _dbus_message_iter_init_common (DBusMessage *message,
2025 DBusMessageRealIter *real,
2028 _dbus_assert (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
2030 /* Since the iterator will read or write who-knows-what from the
2031 * message, we need to get in the right byte order
2033 ensure_byte_order (message);
2035 real->message = message;
2036 real->changed_stamp = message->changed_stamp;
2037 real->iter_type = iter_type;
2038 real->sig_refcount = 0;
2042 * Initializes a #DBusMessageIter for reading the arguments of the
2043 * message passed in.
2045 * When possible, dbus_message_get_args() is much more convenient.
2046 * Some types of argument can only be read with #DBusMessageIter
2049 * The easiest way to iterate is like this:
2051 * dbus_message_iter_init (message, &iter);
2052 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2053 * dbus_message_iter_next (&iter);
2056 * #DBusMessageIter contains no allocated memory; it need not be
2057 * freed, and can be copied by assignment or memcpy().
2059 * @param message the message
2060 * @param iter pointer to an iterator to initialize
2061 * @returns #FALSE if the message has no arguments
2064 dbus_message_iter_init (DBusMessage *message,
2065 DBusMessageIter *iter)
2067 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2068 const DBusString *type_str;
2071 _dbus_return_val_if_fail (message != NULL, FALSE);
2072 _dbus_return_val_if_fail (iter != NULL, FALSE);
2074 get_const_signature (&message->header, &type_str, &type_pos);
2076 _dbus_message_iter_init_common (message, real,
2077 DBUS_MESSAGE_ITER_TYPE_READER);
2079 _dbus_type_reader_init (&real->u.reader,
2080 _dbus_header_get_byte_order (&message->header),
2085 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
2089 * Checks if an iterator has any more fields.
2091 * @param iter the message iter
2092 * @returns #TRUE if there are more fields following
2095 dbus_message_iter_has_next (DBusMessageIter *iter)
2097 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2099 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2100 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2102 return _dbus_type_reader_has_next (&real->u.reader);
2106 * Moves the iterator to the next field, if any. If there's no next
2107 * field, returns #FALSE. If the iterator moves forward, returns
2110 * @param iter the message iter
2111 * @returns #TRUE if the iterator was moved to the next field
2114 dbus_message_iter_next (DBusMessageIter *iter)
2116 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2118 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2119 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2121 return _dbus_type_reader_next (&real->u.reader);
2125 * Returns the argument type of the argument that the message iterator
2126 * points to. If the iterator is at the end of the message, returns
2127 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
2130 * dbus_message_iter_init (message, &iter);
2131 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2132 * dbus_message_iter_next (&iter);
2135 * @param iter the message iter
2136 * @returns the argument type
2139 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
2141 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2143 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2144 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2146 return _dbus_type_reader_get_current_type (&real->u.reader);
2150 * Returns the element type of the array that the message iterator
2151 * points to. Note that you need to check that the iterator points to
2152 * an array prior to using this function.
2154 * @param iter the message iter
2155 * @returns the array element type
2158 dbus_message_iter_get_element_type (DBusMessageIter *iter)
2160 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2162 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2163 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
2164 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
2166 return _dbus_type_reader_get_element_type (&real->u.reader);
2170 * Recurses into a container value when reading values from a message,
2171 * initializing a sub-iterator to use for traversing the child values
2174 * Note that this recurses into a value, not a type, so you can only
2175 * recurse if the value exists. The main implication of this is that
2176 * if you have for example an empty array of array of int32, you can
2177 * recurse into the outermost array, but it will have no values, so
2178 * you won't be able to recurse further. There's no array of int32 to
2181 * If a container is an array of fixed-length types (except Unix file
2182 * descriptors), it is much more efficient to use
2183 * dbus_message_iter_get_fixed_array() to get the whole array in one
2184 * shot, rather than individually walking over the array elements.
2186 * Be sure you have somehow checked that
2187 * dbus_message_iter_get_arg_type() matches the type you are expecting
2188 * to recurse into. Results of this function are undefined if there is
2189 * no container to recurse into at the current iterator position.
2191 * @param iter the message iterator
2192 * @param sub the sub-iterator to initialize
2195 dbus_message_iter_recurse (DBusMessageIter *iter,
2196 DBusMessageIter *sub)
2198 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2199 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2201 _dbus_return_if_fail (_dbus_message_iter_check (real));
2202 _dbus_return_if_fail (sub != NULL);
2205 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
2209 * Returns the current signature of a message iterator. This
2210 * is useful primarily for dealing with variants; one can
2211 * recurse into a variant and determine the signature of
2212 * the variant's value.
2214 * The returned string must be freed with dbus_free().
2216 * @param iter the message iterator
2217 * @returns the contained signature, or NULL if out of memory
2220 dbus_message_iter_get_signature (DBusMessageIter *iter)
2222 const DBusString *sig;
2226 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2228 _dbus_return_val_if_fail (_dbus_message_iter_check (real), NULL);
2230 if (!_dbus_string_init (&retstr))
2233 _dbus_type_reader_get_signature (&real->u.reader, &sig,
2235 if (!_dbus_string_append_len (&retstr,
2236 _dbus_string_get_const_data (sig) + start,
2239 if (!_dbus_string_steal_data (&retstr, &ret))
2241 _dbus_string_free (&retstr);
2246 * Reads a basic-typed value from the message iterator.
2247 * Basic types are the non-containers such as integer and string.
2249 * The value argument should be the address of a location to store
2250 * the returned value. So for int32 it should be a "dbus_int32_t*"
2251 * and for string a "const char**". The returned value is
2252 * by reference and should not be freed.
2254 * This call duplicates Unix file descriptors when reading them. It is
2255 * your job to close them when you don't need them anymore.
2257 * Unix file descriptors that are read with this function will have
2258 * the FD_CLOEXEC flag set. If you need them without this flag set,
2259 * make sure to unset it with fcntl().
2261 * Be sure you have somehow checked that
2262 * dbus_message_iter_get_arg_type() matches the type you are
2263 * expecting, or you'll crash when you try to use an integer as a
2264 * string or something.
2266 * To read any container type (array, struct, dict) you will need to
2267 * recurse into the container with dbus_message_iter_recurse(). If
2268 * the container is an array of fixed-length values (except Unix file
2269 * descriptors), you can get all the array elements at once with
2270 * dbus_message_iter_get_fixed_array(). Otherwise, you have to iterate
2271 * over the container's contents one value at a time.
2273 * All basic-typed values are guaranteed to fit in a #DBusBasicValue,
2274 * so in versions of libdbus that have that type, you can write code like this:
2277 * DBusBasicValue value;
2279 * dbus_message_iter_get_basic (&read_iter, &value);
2280 * type = dbus_message_iter_get_arg_type (&read_iter);
2281 * dbus_message_iter_append_basic (&write_iter, type, &value);
2284 * (All D-Bus basic types are either numeric and 8 bytes or smaller, or
2285 * behave like a string; so in older versions of libdbus, DBusBasicValue
2286 * can be replaced with union { char *string; unsigned char bytes[8]; },
2289 * @param iter the iterator
2290 * @param value location to store the value
2293 dbus_message_iter_get_basic (DBusMessageIter *iter,
2296 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2298 _dbus_return_if_fail (_dbus_message_iter_check (real));
2299 _dbus_return_if_fail (value != NULL);
2301 if (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_UNIX_FD)
2303 #ifdef HAVE_UNIX_FD_PASSING
2306 _dbus_type_reader_read_basic(&real->u.reader, &idx);
2308 if (idx.u32 >= real->message->n_unix_fds) {
2309 /* Hmm, we cannot really signal an error here, so let's make
2310 sure to return an invalid fd. */
2311 *((int*) value) = -1;
2315 *((int*) value) = _dbus_dup(real->message->unix_fds[idx.u32], NULL);
2317 *((int*) value) = -1;
2322 _dbus_type_reader_read_basic (&real->u.reader,
2328 * Returns the number of bytes in the array as marshaled in the wire
2329 * protocol. The iterator must currently be inside an array-typed
2332 * This function is deprecated on the grounds that it is stupid. Why
2333 * would you want to know how many bytes are in the array as marshaled
2334 * in the wire protocol? For now, use the n_elements returned from
2335 * dbus_message_iter_get_fixed_array() instead, or iterate over the
2336 * array values and count them.
2338 * @todo introduce a variant of this get_n_elements that returns
2339 * the number of elements, though with a non-fixed array it will not
2340 * be very efficient, so maybe it's not good.
2342 * @param iter the iterator
2343 * @returns the number of bytes in the array
2346 dbus_message_iter_get_array_len (DBusMessageIter *iter)
2348 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2350 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2352 return _dbus_type_reader_get_array_length (&real->u.reader);
2356 * Reads a block of fixed-length values from the message iterator.
2357 * Fixed-length values are those basic types that are not string-like,
2358 * such as integers, bool, double. The returned block will be from the
2359 * current position in the array until the end of the array.
2361 * There is one exception here: although DBUS_TYPE_UNIX_FD is
2362 * considered a 'fixed' type arrays of this type may not be read with
2365 * The message iter should be "in" the array (that is, you recurse into the
2366 * array, and then you call dbus_message_iter_get_fixed_array() on the
2367 * "sub-iterator" created by dbus_message_iter_recurse()).
2369 * The value argument should be the address of a location to store the
2370 * returned array. So for int32 it should be a "const dbus_int32_t**"
2371 * The returned value is by reference and should not be freed.
2373 * This function should only be used if dbus_type_is_fixed() returns
2374 * #TRUE for the element type.
2376 * If an array's elements are not fixed in size, you have to recurse
2377 * into the array with dbus_message_iter_recurse() and read the
2378 * elements one by one.
2380 * Because the array is not copied, this function runs in constant
2381 * time and is fast; it's much preferred over walking the entire array
2382 * with an iterator. (However, you can always use
2383 * dbus_message_iter_recurse(), even for fixed-length types;
2384 * dbus_message_iter_get_fixed_array() is just an optimization.)
2386 * @param iter the iterator
2387 * @param value location to store the block
2388 * @param n_elements number of elements in the block
2391 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
2395 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2396 #ifndef DBUS_DISABLE_CHECKS
2397 int subtype = _dbus_type_reader_get_current_type(&real->u.reader);
2399 _dbus_return_if_fail (_dbus_message_iter_check (real));
2400 _dbus_return_if_fail (value != NULL);
2401 _dbus_return_if_fail ((subtype == DBUS_TYPE_INVALID) ||
2402 (dbus_type_is_fixed (subtype) && subtype != DBUS_TYPE_UNIX_FD));
2405 _dbus_type_reader_read_fixed_multi (&real->u.reader,
2410 * Initializes a #DBusMessageIter for appending arguments to the end
2413 * @todo If appending any of the arguments fails due to lack of
2414 * memory, the message is hosed and you have to start over building
2415 * the whole message.
2417 * @param message the message
2418 * @param iter pointer to an iterator to initialize
2421 dbus_message_iter_init_append (DBusMessage *message,
2422 DBusMessageIter *iter)
2424 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2426 _dbus_return_if_fail (message != NULL);
2427 _dbus_return_if_fail (iter != NULL);
2429 _dbus_message_iter_init_common (message, real,
2430 DBUS_MESSAGE_ITER_TYPE_WRITER);
2432 /* We create the signature string and point iterators at it "on demand"
2433 * when a value is actually appended. That means that init() never fails
2436 _dbus_type_writer_init_types_delayed (&real->u.writer,
2437 _dbus_header_get_byte_order (&message->header),
2439 _dbus_string_get_length (&message->body));
2443 * Creates a temporary signature string containing the current
2444 * signature, stores it in the iterator, and points the iterator to
2445 * the end of it. Used any time we write to the message.
2447 * @param real an iterator without a type_str
2448 * @returns #FALSE if no memory
2451 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
2454 const DBusString *current_sig;
2455 int current_sig_pos;
2457 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2459 if (real->u.writer.type_str != NULL)
2461 _dbus_assert (real->sig_refcount > 0);
2462 real->sig_refcount += 1;
2466 str = dbus_new (DBusString, 1);
2470 if (!_dbus_header_get_field_raw (&real->message->header,
2471 DBUS_HEADER_FIELD_SIGNATURE,
2472 ¤t_sig, ¤t_sig_pos))
2479 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
2480 current_sig_pos += 1; /* move on to sig data */
2482 if (!_dbus_string_init_preallocated (str, current_len + 4))
2488 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
2491 _dbus_string_free (str);
2498 if (!_dbus_string_init_preallocated (str, 4))
2505 real->sig_refcount = 1;
2507 _dbus_type_writer_add_types (&real->u.writer,
2508 str, _dbus_string_get_length (str));
2513 * Sets the new signature as the message signature, frees the
2514 * signature string, and marks the iterator as not having a type_str
2515 * anymore. Frees the signature even if it fails, so you can't
2516 * really recover from failure. Kinda busted.
2518 * @param real an iterator without a type_str
2519 * @returns #FALSE if no memory
2522 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2525 const char *v_STRING;
2528 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2529 _dbus_assert (real->u.writer.type_str != NULL);
2530 _dbus_assert (real->sig_refcount > 0);
2532 real->sig_refcount -= 1;
2534 if (real->sig_refcount > 0)
2536 _dbus_assert (real->sig_refcount == 0);
2540 str = real->u.writer.type_str;
2542 v_STRING = _dbus_string_get_const_data (str);
2543 if (!_dbus_header_set_field_basic (&real->message->header,
2544 DBUS_HEADER_FIELD_SIGNATURE,
2545 DBUS_TYPE_SIGNATURE,
2549 _dbus_type_writer_remove_types (&real->u.writer);
2550 _dbus_string_free (str);
2557 * Frees the signature string and marks the iterator as not having a
2558 * type_str anymore. Since the new signature is not set, the message
2559 * will generally be hosed after this is called.
2561 * @param real an iterator without a type_str
2564 _dbus_message_iter_abandon_signature (DBusMessageRealIter *real)
2568 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2569 _dbus_assert (real->u.writer.type_str != NULL);
2570 _dbus_assert (real->sig_refcount > 0);
2572 real->sig_refcount -= 1;
2574 if (real->sig_refcount > 0)
2576 _dbus_assert (real->sig_refcount == 0);
2578 str = real->u.writer.type_str;
2580 _dbus_type_writer_remove_types (&real->u.writer);
2581 _dbus_string_free (str);
2585 #ifndef DBUS_DISABLE_CHECKS
2587 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2589 if (!_dbus_message_iter_check (iter))
2592 if (iter->message->locked)
2594 _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)\n");
2600 #endif /* DBUS_DISABLE_CHECKS */
2602 #ifdef HAVE_UNIX_FD_PASSING
2604 expand_fd_array(DBusMessage *m,
2609 /* This makes space for adding n new fds to the array and returns a
2610 pointer to the place were the first fd should be put. */
2612 if (m->n_unix_fds + n > m->n_unix_fds_allocated)
2617 /* Make twice as much space as necessary */
2618 k = (m->n_unix_fds + n) * 2;
2620 /* Allocate at least four */
2624 p = dbus_realloc(m->unix_fds, k * sizeof(int));
2629 m->n_unix_fds_allocated = k;
2632 return m->unix_fds + m->n_unix_fds;
2637 * Appends a basic-typed value to the message. The basic types are the
2638 * non-container types such as integer and string.
2640 * The "value" argument should be the address of a basic-typed value.
2641 * So for string, const char**. For integer, dbus_int32_t*.
2643 * For Unix file descriptors this function will internally duplicate
2644 * the descriptor you passed in. Hence you may close the descriptor
2645 * immediately after this call.
2647 * @todo If this fails due to lack of memory, the message is hosed and
2648 * you have to start over building the whole message.
2650 * @param iter the append iterator
2651 * @param type the type of the value
2652 * @param value the address of the value
2653 * @returns #FALSE if not enough memory
2656 dbus_message_iter_append_basic (DBusMessageIter *iter,
2660 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2663 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2664 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2665 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2666 _dbus_return_val_if_fail (value != NULL, FALSE);
2668 #ifndef DBUS_DISABLE_CHECKS
2671 const char * const *string_p;
2672 const dbus_bool_t *bool_p;
2674 case DBUS_TYPE_STRING:
2676 _dbus_return_val_if_fail (_dbus_check_is_valid_utf8 (*string_p), FALSE);
2679 case DBUS_TYPE_OBJECT_PATH:
2681 _dbus_return_val_if_fail (_dbus_check_is_valid_path (*string_p), FALSE);
2684 case DBUS_TYPE_SIGNATURE:
2686 _dbus_return_val_if_fail (_dbus_check_is_valid_signature (*string_p), FALSE);
2689 case DBUS_TYPE_BOOLEAN:
2691 _dbus_return_val_if_fail (*bool_p == 0 || *bool_p == 1, FALSE);
2696 /* nothing to check, all possible values are allowed */
2701 if (!_dbus_message_iter_open_signature (real))
2704 if (type == DBUS_TYPE_UNIX_FD)
2706 #ifdef HAVE_UNIX_FD_PASSING
2710 /* First step, include the fd in the fd list of this message */
2711 if (!(fds = expand_fd_array(real->message, 1)))
2714 *fds = _dbus_dup(*(int*) value, NULL);
2718 u = real->message->n_unix_fds;
2720 /* Second step, write the index to the fd */
2721 if (!(ret = _dbus_type_writer_write_basic (&real->u.writer, DBUS_TYPE_UNIX_FD, &u))) {
2722 _dbus_close(*fds, NULL);
2726 real->message->n_unix_fds += 1;
2729 /* Final step, update the header accordingly */
2730 ret = _dbus_header_set_field_basic (&real->message->header,
2731 DBUS_HEADER_FIELD_UNIX_FDS,
2735 /* If any of these operations fail the message is
2736 hosed. However, no memory or fds should be leaked since what
2737 has been added to message has been added to the message, and
2738 can hence be accounted for when the message is being
2746 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
2749 if (!_dbus_message_iter_close_signature (real))
2756 * Appends a block of fixed-length values to an array. The
2757 * fixed-length types are all basic types that are not string-like. So
2758 * int32, double, bool, etc. (Unix file descriptors however are not
2759 * supported.) You must call dbus_message_iter_open_container() to
2760 * open an array of values before calling this function. You may call
2761 * this function multiple times (and intermixed with calls to
2762 * dbus_message_iter_append_basic()) for the same array.
2764 * The "value" argument should be the address of the array. So for
2765 * integer, "dbus_int32_t**" is expected for example.
2767 * @warning in C, given "int array[]", "&array == array" (the
2768 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2769 * So if you're using an array instead of a pointer you have to create
2770 * a pointer variable, assign the array to it, then take the address
2771 * of the pointer variable.
2773 * const dbus_int32_t array[] = { 1, 2, 3 };
2774 * const dbus_int32_t *v_ARRAY = array;
2775 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
2776 * fprintf (stderr, "No memory!\n");
2778 * For strings it works to write const char *array = "Hello" and then
2779 * use &array though.
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 element_type the type of the array elements
2786 * @param value the address of the array
2787 * @param n_elements the number of elements to append
2788 * @returns #FALSE if not enough memory
2791 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
2796 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2799 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2800 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2801 _dbus_return_val_if_fail (dbus_type_is_fixed (element_type) && element_type != DBUS_TYPE_UNIX_FD, FALSE);
2802 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
2803 _dbus_return_val_if_fail (value != NULL, FALSE);
2804 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
2805 _dbus_return_val_if_fail (n_elements <=
2806 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
2809 #ifndef DBUS_DISABLE_CHECKS
2810 if (element_type == DBUS_TYPE_BOOLEAN)
2812 const dbus_bool_t * const *bools = value;
2815 for (i = 0; i < n_elements; i++)
2817 _dbus_return_val_if_fail ((*bools)[i] == 0 || (*bools)[i] == 1, FALSE);
2822 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
2828 * Appends a container-typed value to the message; you are required to
2829 * append the contents of the container using the returned
2830 * sub-iterator, and then call
2831 * dbus_message_iter_close_container(). Container types are for
2832 * example struct, variant, and array. For variants, the
2833 * contained_signature should be the type of the single value inside
2834 * the variant. For structs and dict entries, contained_signature
2835 * should be #NULL; it will be set to whatever types you write into
2836 * the struct. For arrays, contained_signature should be the type of
2837 * the array elements.
2839 * @todo If this fails due to lack of memory, the message is hosed and
2840 * you have to start over building the whole message.
2842 * @param iter the append iterator
2843 * @param type the type of the value
2844 * @param contained_signature the type of container contents
2845 * @param sub sub-iterator to initialize
2846 * @returns #FALSE if not enough memory
2849 dbus_message_iter_open_container (DBusMessageIter *iter,
2851 const char *contained_signature,
2852 DBusMessageIter *sub)
2854 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2855 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2856 DBusString contained_str;
2858 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2859 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2860 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
2861 _dbus_return_val_if_fail (sub != NULL, FALSE);
2862 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
2863 contained_signature == NULL) ||
2864 (type == DBUS_TYPE_DICT_ENTRY &&
2865 contained_signature == NULL) ||
2866 (type == DBUS_TYPE_VARIANT &&
2867 contained_signature != NULL) ||
2868 (type == DBUS_TYPE_ARRAY &&
2869 contained_signature != NULL), FALSE);
2871 /* this would fail if the contained_signature is a dict entry, since
2872 * dict entries are invalid signatures standalone (they must be in
2875 _dbus_return_val_if_fail ((type == DBUS_TYPE_ARRAY && contained_signature && *contained_signature == DBUS_DICT_ENTRY_BEGIN_CHAR) ||
2876 (contained_signature == NULL ||
2877 _dbus_check_is_valid_signature (contained_signature)),
2880 if (!_dbus_message_iter_open_signature (real))
2885 if (contained_signature != NULL)
2887 _dbus_string_init_const (&contained_str, contained_signature);
2889 return _dbus_type_writer_recurse (&real->u.writer,
2892 &real_sub->u.writer);
2896 return _dbus_type_writer_recurse (&real->u.writer,
2899 &real_sub->u.writer);
2905 * Closes a container-typed value appended to the message; may write
2906 * out more information to the message known only after the entire
2907 * container is written, and may free resources created by
2908 * dbus_message_iter_open_container().
2910 * @todo If this fails due to lack of memory, the message is hosed and
2911 * you have to start over building the whole message.
2913 * @param iter the append iterator
2914 * @param sub sub-iterator to close
2915 * @returns #FALSE if not enough memory
2918 dbus_message_iter_close_container (DBusMessageIter *iter,
2919 DBusMessageIter *sub)
2921 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2922 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2925 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2926 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2927 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
2928 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2930 ret = _dbus_type_writer_unrecurse (&real->u.writer,
2931 &real_sub->u.writer);
2933 if (!_dbus_message_iter_close_signature (real))
2940 * Abandons creation of a contained-typed value and frees resources created
2941 * by dbus_message_iter_open_container(). Once this returns, the message
2942 * is hosed and you have to start over building the whole message.
2944 * This should only be used to abandon creation of a message when you have
2947 * @param iter the append iterator
2948 * @param sub sub-iterator to close
2951 dbus_message_iter_abandon_container (DBusMessageIter *iter,
2952 DBusMessageIter *sub)
2954 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2955 #ifndef DBUS_DISABLE_CHECKS
2956 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2958 _dbus_return_if_fail (_dbus_message_iter_append_check (real));
2959 _dbus_return_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2960 _dbus_return_if_fail (_dbus_message_iter_append_check (real_sub));
2961 _dbus_return_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2964 _dbus_message_iter_abandon_signature (real);
2968 * Sets a flag indicating that the message does not want a reply; if
2969 * this flag is set, the other end of the connection may (but is not
2970 * required to) optimize by not sending method return or error
2971 * replies. If this flag is set, there is no way to know whether the
2972 * message successfully arrived at the remote end. Normally you know a
2973 * message was received when you receive the reply to it.
2975 * The flag is #FALSE by default, that is by default the other end is
2976 * required to reply.
2978 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
2980 * @param message the message
2981 * @param no_reply #TRUE if no reply is desired
2984 dbus_message_set_no_reply (DBusMessage *message,
2985 dbus_bool_t no_reply)
2987 _dbus_return_if_fail (message != NULL);
2988 _dbus_return_if_fail (!message->locked);
2990 _dbus_header_toggle_flag (&message->header,
2991 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
2996 * Returns #TRUE if the message does not expect
2999 * @param message the message
3000 * @returns #TRUE if the message sender isn't waiting for a reply
3003 dbus_message_get_no_reply (DBusMessage *message)
3005 _dbus_return_val_if_fail (message != NULL, FALSE);
3007 return _dbus_header_get_flag (&message->header,
3008 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
3012 * Sets a flag indicating that an owner for the destination name will
3013 * be automatically started before the message is delivered. When this
3014 * flag is set, the message is held until a name owner finishes
3015 * starting up, or fails to start up. In case of failure, the reply
3018 * The flag is set to #TRUE by default, i.e. auto starting is the default.
3020 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
3022 * @param message the message
3023 * @param auto_start #TRUE if auto-starting is desired
3026 dbus_message_set_auto_start (DBusMessage *message,
3027 dbus_bool_t auto_start)
3029 _dbus_return_if_fail (message != NULL);
3030 _dbus_return_if_fail (!message->locked);
3032 _dbus_header_toggle_flag (&message->header,
3033 DBUS_HEADER_FLAG_NO_AUTO_START,
3038 * Returns #TRUE if the message will cause an owner for
3039 * destination name to be auto-started.
3041 * @param message the message
3042 * @returns #TRUE if the message will use auto-start
3045 dbus_message_get_auto_start (DBusMessage *message)
3047 _dbus_return_val_if_fail (message != NULL, FALSE);
3049 return !_dbus_header_get_flag (&message->header,
3050 DBUS_HEADER_FLAG_NO_AUTO_START);
3055 * Sets the object path this message is being sent to (for
3056 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
3057 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
3059 * The path must contain only valid characters as defined
3060 * in the D-Bus specification.
3062 * @param message the message
3063 * @param object_path the path or #NULL to unset
3064 * @returns #FALSE if not enough memory
3067 dbus_message_set_path (DBusMessage *message,
3068 const char *object_path)
3070 _dbus_return_val_if_fail (message != NULL, FALSE);
3071 _dbus_return_val_if_fail (!message->locked, FALSE);
3072 _dbus_return_val_if_fail (object_path == NULL ||
3073 _dbus_check_is_valid_path (object_path),
3076 return set_or_delete_string_field (message,
3077 DBUS_HEADER_FIELD_PATH,
3078 DBUS_TYPE_OBJECT_PATH,
3083 * Gets the object path this message is being sent to (for
3084 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
3085 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3087 * See also dbus_message_get_path_decomposed().
3089 * The returned string becomes invalid if the message is
3090 * modified, since it points into the wire-marshaled message data.
3092 * @param message the message
3093 * @returns the path (should not be freed) or #NULL
3096 dbus_message_get_path (DBusMessage *message)
3100 _dbus_return_val_if_fail (message != NULL, NULL);
3102 v = NULL; /* in case field doesn't exist */
3103 _dbus_header_get_field_basic (&message->header,
3104 DBUS_HEADER_FIELD_PATH,
3105 DBUS_TYPE_OBJECT_PATH,
3111 * Checks if the message has a particular object path. The object
3112 * path is the destination object for a method call or the emitting
3113 * object for a signal.
3115 * @param message the message
3116 * @param path the path name
3117 * @returns #TRUE if there is a path field in the header
3120 dbus_message_has_path (DBusMessage *message,
3123 const char *msg_path;
3124 msg_path = dbus_message_get_path (message);
3126 if (msg_path == NULL)
3137 if (strcmp (msg_path, path) == 0)
3144 * Gets the object path this message is being sent to
3145 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3146 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
3147 * format (one array element per path component).
3148 * Free the returned array with dbus_free_string_array().
3150 * An empty but non-NULL path array means the path "/".
3151 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
3152 * and the path "/" becomes { NULL }.
3154 * See also dbus_message_get_path().
3156 * @todo this could be optimized by using the len from the message
3157 * instead of calling strlen() again
3159 * @param message the message
3160 * @param path place to store allocated array of path components; #NULL set here if no path field exists
3161 * @returns #FALSE if no memory to allocate the array
3164 dbus_message_get_path_decomposed (DBusMessage *message,
3169 _dbus_return_val_if_fail (message != NULL, FALSE);
3170 _dbus_return_val_if_fail (path != NULL, FALSE);
3174 v = dbus_message_get_path (message);
3177 if (!_dbus_decompose_path (v, strlen (v),
3185 * Sets the interface this message is being sent to
3186 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
3187 * the interface a signal is being emitted from
3188 * (for DBUS_MESSAGE_TYPE_SIGNAL).
3190 * The interface name must contain only valid characters as defined
3191 * in the D-Bus specification.
3193 * @param message the message
3194 * @param iface the interface or #NULL to unset
3195 * @returns #FALSE if not enough memory
3198 dbus_message_set_interface (DBusMessage *message,
3201 _dbus_return_val_if_fail (message != NULL, FALSE);
3202 _dbus_return_val_if_fail (!message->locked, FALSE);
3203 _dbus_return_val_if_fail (iface == NULL ||
3204 _dbus_check_is_valid_interface (iface),
3207 return set_or_delete_string_field (message,
3208 DBUS_HEADER_FIELD_INTERFACE,
3214 * Gets the interface this message is being sent to
3215 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3216 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
3217 * The interface name is fully-qualified (namespaced).
3218 * Returns #NULL if none.
3220 * The returned string becomes invalid if the message is
3221 * modified, since it points into the wire-marshaled message data.
3223 * @param message the message
3224 * @returns the message interface (should not be freed) or #NULL
3227 dbus_message_get_interface (DBusMessage *message)
3231 _dbus_return_val_if_fail (message != NULL, NULL);
3233 v = NULL; /* in case field doesn't exist */
3234 _dbus_header_get_field_basic (&message->header,
3235 DBUS_HEADER_FIELD_INTERFACE,
3242 * Checks if the message has an interface
3244 * @param message the message
3245 * @param iface the interface name
3246 * @returns #TRUE if the interface field in the header matches
3249 dbus_message_has_interface (DBusMessage *message,
3252 const char *msg_interface;
3253 msg_interface = dbus_message_get_interface (message);
3255 if (msg_interface == NULL)
3266 if (strcmp (msg_interface, iface) == 0)
3274 * Sets the interface member being invoked
3275 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3276 * (DBUS_MESSAGE_TYPE_SIGNAL).
3278 * The member name must contain only valid characters as defined
3279 * in the D-Bus specification.
3281 * @param message the message
3282 * @param member the member or #NULL to unset
3283 * @returns #FALSE if not enough memory
3286 dbus_message_set_member (DBusMessage *message,
3289 _dbus_return_val_if_fail (message != NULL, FALSE);
3290 _dbus_return_val_if_fail (!message->locked, FALSE);
3291 _dbus_return_val_if_fail (member == NULL ||
3292 _dbus_check_is_valid_member (member),
3295 return set_or_delete_string_field (message,
3296 DBUS_HEADER_FIELD_MEMBER,
3302 * Gets the interface member being invoked
3303 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3304 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3306 * The returned string becomes invalid if the message is
3307 * modified, since it points into the wire-marshaled message data.
3309 * @param message the message
3310 * @returns the member name (should not be freed) or #NULL
3313 dbus_message_get_member (DBusMessage *message)
3317 _dbus_return_val_if_fail (message != NULL, NULL);
3319 v = NULL; /* in case field doesn't exist */
3320 _dbus_header_get_field_basic (&message->header,
3321 DBUS_HEADER_FIELD_MEMBER,
3328 * Checks if the message has an interface member
3330 * @param message the message
3331 * @param member the member name
3332 * @returns #TRUE if there is a member field in the header
3335 dbus_message_has_member (DBusMessage *message,
3338 const char *msg_member;
3339 msg_member = dbus_message_get_member (message);
3341 if (msg_member == NULL)
3352 if (strcmp (msg_member, member) == 0)
3360 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
3361 * The name is fully-qualified (namespaced).
3363 * The error name must contain only valid characters as defined
3364 * in the D-Bus specification.
3366 * @param message the message
3367 * @param error_name the name or #NULL to unset
3368 * @returns #FALSE if not enough memory
3371 dbus_message_set_error_name (DBusMessage *message,
3372 const char *error_name)
3374 _dbus_return_val_if_fail (message != NULL, FALSE);
3375 _dbus_return_val_if_fail (!message->locked, FALSE);
3376 _dbus_return_val_if_fail (error_name == NULL ||
3377 _dbus_check_is_valid_error_name (error_name),
3380 return set_or_delete_string_field (message,
3381 DBUS_HEADER_FIELD_ERROR_NAME,
3387 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
3390 * The returned string becomes invalid if the message is
3391 * modified, since it points into the wire-marshaled message data.
3393 * @param message the message
3394 * @returns the error name (should not be freed) or #NULL
3397 dbus_message_get_error_name (DBusMessage *message)
3401 _dbus_return_val_if_fail (message != NULL, NULL);
3403 v = NULL; /* in case field doesn't exist */
3404 _dbus_header_get_field_basic (&message->header,
3405 DBUS_HEADER_FIELD_ERROR_NAME,
3412 * Sets the message's destination. The destination is the name of
3413 * another connection on the bus and may be either the unique name
3414 * assigned by the bus to each connection, or a well-known name
3415 * specified in advance.
3417 * The destination name must contain only valid characters as defined
3418 * in the D-Bus specification.
3420 * @param message the message
3421 * @param destination the destination name or #NULL to unset
3422 * @returns #FALSE if not enough memory
3425 dbus_message_set_destination (DBusMessage *message,
3426 const char *destination)
3428 _dbus_return_val_if_fail (message != NULL, FALSE);
3429 _dbus_return_val_if_fail (!message->locked, FALSE);
3430 _dbus_return_val_if_fail (destination == NULL ||
3431 _dbus_check_is_valid_bus_name (destination),
3434 return set_or_delete_string_field (message,
3435 DBUS_HEADER_FIELD_DESTINATION,
3441 * Gets the destination of a message or #NULL if there is none set.
3443 * The returned string becomes invalid if the message is
3444 * modified, since it points into the wire-marshaled message data.
3446 * @param message the message
3447 * @returns the message destination (should not be freed) or #NULL
3450 dbus_message_get_destination (DBusMessage *message)
3454 _dbus_return_val_if_fail (message != NULL, NULL);
3456 v = NULL; /* in case field doesn't exist */
3457 _dbus_header_get_field_basic (&message->header,
3458 DBUS_HEADER_FIELD_DESTINATION,
3465 * Sets the message sender.
3467 * The sender must be a valid bus name as defined in the D-Bus
3470 * Usually you don't want to call this. The message bus daemon will
3471 * call it to set the origin of each message. If you aren't implementing
3472 * a message bus daemon you shouldn't need to set the sender.
3474 * @param message the message
3475 * @param sender the sender or #NULL to unset
3476 * @returns #FALSE if not enough memory
3479 dbus_message_set_sender (DBusMessage *message,
3482 _dbus_return_val_if_fail (message != NULL, FALSE);
3483 _dbus_return_val_if_fail (!message->locked, FALSE);
3484 _dbus_return_val_if_fail (sender == NULL ||
3485 _dbus_check_is_valid_bus_name (sender),
3488 return set_or_delete_string_field (message,
3489 DBUS_HEADER_FIELD_SENDER,
3495 * Gets the unique name of the connection which originated this
3496 * message, or #NULL if unknown or inapplicable. The sender is filled
3497 * in by the message bus.
3499 * Note, the returned sender is always the unique bus name.
3500 * Connections may own multiple other bus names, but those
3501 * are not found in the sender field.
3503 * The returned string becomes invalid if the message is
3504 * modified, since it points into the wire-marshaled message data.
3506 * @param message the message
3507 * @returns the unique name of the sender or #NULL
3510 dbus_message_get_sender (DBusMessage *message)
3514 _dbus_return_val_if_fail (message != NULL, NULL);
3516 v = NULL; /* in case field doesn't exist */
3517 _dbus_header_get_field_basic (&message->header,
3518 DBUS_HEADER_FIELD_SENDER,
3525 * Gets the type signature of the message, i.e. the arguments in the
3526 * message payload. The signature includes only "in" arguments for
3527 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
3528 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
3529 * what you might expect (that is, it does not include the signature of the
3530 * entire C++-style method).
3532 * The signature is a string made up of type codes such as
3533 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
3534 * the value of #DBUS_TYPE_INVALID).
3536 * The returned string becomes invalid if the message is
3537 * modified, since it points into the wire-marshaled message data.
3539 * @param message the message
3540 * @returns the type signature
3543 dbus_message_get_signature (DBusMessage *message)
3545 const DBusString *type_str;
3548 _dbus_return_val_if_fail (message != NULL, NULL);
3550 get_const_signature (&message->header, &type_str, &type_pos);
3552 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
3556 _dbus_message_has_type_interface_member (DBusMessage *message,
3563 _dbus_assert (message != NULL);
3564 _dbus_assert (iface != NULL);
3565 _dbus_assert (member != NULL);
3567 if (dbus_message_get_type (message) != type)
3570 /* Optimize by checking the short member name first
3571 * instead of the longer interface name
3574 n = dbus_message_get_member (message);
3576 if (n && strcmp (n, member) == 0)
3578 n = dbus_message_get_interface (message);
3580 if (n == NULL || strcmp (n, iface) == 0)
3588 * Checks whether the message is a method call with the given
3589 * interface and member fields. If the message is not
3590 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
3591 * member field, returns #FALSE. If the interface field is missing,
3592 * then it will be assumed equal to the provided interface. The D-Bus
3593 * protocol allows method callers to leave out the interface name.
3595 * @param message the message
3596 * @param iface the name to check (must not be #NULL)
3597 * @param method the name to check (must not be #NULL)
3599 * @returns #TRUE if the message is the specified method call
3602 dbus_message_is_method_call (DBusMessage *message,
3606 _dbus_return_val_if_fail (message != NULL, FALSE);
3607 _dbus_return_val_if_fail (iface != NULL, FALSE);
3608 _dbus_return_val_if_fail (method != NULL, FALSE);
3609 /* don't check that interface/method are valid since it would be
3610 * expensive, and not catch many common errors
3613 return _dbus_message_has_type_interface_member (message,
3614 DBUS_MESSAGE_TYPE_METHOD_CALL,
3619 * Checks whether the message is a signal with the given interface and
3620 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
3621 * has a different interface or member field, returns #FALSE.
3623 * @param message the message
3624 * @param iface the name to check (must not be #NULL)
3625 * @param signal_name the name to check (must not be #NULL)
3627 * @returns #TRUE if the message is the specified signal
3630 dbus_message_is_signal (DBusMessage *message,
3632 const char *signal_name)
3634 _dbus_return_val_if_fail (message != NULL, FALSE);
3635 _dbus_return_val_if_fail (iface != NULL, FALSE);
3636 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
3637 /* don't check that interface/name are valid since it would be
3638 * expensive, and not catch many common errors
3641 return _dbus_message_has_type_interface_member (message,
3642 DBUS_MESSAGE_TYPE_SIGNAL,
3643 iface, signal_name);
3647 * Checks whether the message is an error reply with the given error
3648 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
3649 * different name, returns #FALSE.
3651 * @param message the message
3652 * @param error_name the name to check (must not be #NULL)
3654 * @returns #TRUE if the message is the specified error
3657 dbus_message_is_error (DBusMessage *message,
3658 const char *error_name)
3662 _dbus_return_val_if_fail (message != NULL, FALSE);
3663 _dbus_return_val_if_fail (error_name != NULL, FALSE);
3664 /* don't check that error_name is valid since it would be expensive,
3665 * and not catch many common errors
3668 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3671 n = dbus_message_get_error_name (message);
3673 if (n && strcmp (n, error_name) == 0)
3680 * Checks whether the message was sent to the given name. If the
3681 * message has no destination specified or has a different
3682 * destination, returns #FALSE.
3684 * @param message the message
3685 * @param name the name to check (must not be #NULL)
3687 * @returns #TRUE if the message has the given destination name
3690 dbus_message_has_destination (DBusMessage *message,
3695 _dbus_return_val_if_fail (message != NULL, FALSE);
3696 _dbus_return_val_if_fail (name != NULL, FALSE);
3697 /* don't check that name is valid since it would be expensive, and
3698 * not catch many common errors
3701 s = dbus_message_get_destination (message);
3703 if (s && strcmp (s, name) == 0)
3710 * Checks whether the message has the given unique name as its sender.
3711 * If the message has no sender specified or has a different sender,
3712 * returns #FALSE. Note that a peer application will always have the
3713 * unique name of the connection as the sender. So you can't use this
3714 * function to see whether a sender owned a well-known name.
3716 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
3719 * @param message the message
3720 * @param name the name to check (must not be #NULL)
3722 * @returns #TRUE if the message has the given sender
3725 dbus_message_has_sender (DBusMessage *message,
3730 _dbus_return_val_if_fail (message != NULL, FALSE);
3731 _dbus_return_val_if_fail (name != NULL, FALSE);
3732 /* don't check that name is valid since it would be expensive, and
3733 * not catch many common errors
3736 s = dbus_message_get_sender (message);
3738 if (s && strcmp (s, name) == 0)
3745 * Checks whether the message has the given signature; see
3746 * dbus_message_get_signature() for more details on what the signature
3749 * @param message the message
3750 * @param signature typecode array
3751 * @returns #TRUE if message has the given signature
3754 dbus_message_has_signature (DBusMessage *message,
3755 const char *signature)
3759 _dbus_return_val_if_fail (message != NULL, FALSE);
3760 _dbus_return_val_if_fail (signature != NULL, FALSE);
3761 /* don't check that signature is valid since it would be expensive,
3762 * and not catch many common errors
3765 s = dbus_message_get_signature (message);
3767 if (s && strcmp (s, signature) == 0)
3774 * Sets a #DBusError based on the contents of the given
3775 * message. The error is only set if the message
3776 * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
3777 * The name of the error is set to the name of the message,
3778 * and the error message is set to the first argument
3779 * if the argument exists and is a string.
3781 * The return value indicates whether the error was set (the error is
3782 * set if and only if the message is an error message). So you can
3783 * check for an error reply and convert it to DBusError in one go:
3785 * if (dbus_set_error_from_message (error, reply))
3791 * @param error the error to set
3792 * @param message the message to set it from
3793 * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
3796 dbus_set_error_from_message (DBusError *error,
3797 DBusMessage *message)
3801 _dbus_return_val_if_fail (message != NULL, FALSE);
3802 _dbus_return_val_if_error_is_set (error, FALSE);
3804 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3808 dbus_message_get_args (message, NULL,
3809 DBUS_TYPE_STRING, &str,
3812 dbus_set_error (error, dbus_message_get_error_name (message),
3813 str ? "%s" : NULL, str);
3819 * Checks whether a message contains unix fds
3821 * @param message the message
3822 * @returns #TRUE if the message contains unix fds
3825 dbus_message_contains_unix_fds(DBusMessage *message)
3827 #ifdef HAVE_UNIX_FD_PASSING
3828 _dbus_assert(message);
3830 return message->n_unix_fds > 0;
3839 * @addtogroup DBusMessageInternals
3845 * The initial buffer size of the message loader.
3847 * @todo this should be based on min header size plus some average
3848 * body size, or something. Or rather, the min header size only, if we
3849 * want to try to read only the header, store that in a DBusMessage,
3850 * then read only the body and store that, etc., depends on
3851 * how we optimize _dbus_message_loader_get_buffer() and what
3852 * the exact message format is.
3854 #define INITIAL_LOADER_DATA_LEN 32
3857 * Creates a new message loader. Returns #NULL if memory can't
3860 * @returns new loader, or #NULL.
3863 _dbus_message_loader_new (void)
3865 DBusMessageLoader *loader;
3867 loader = dbus_new0 (DBusMessageLoader, 1);
3871 loader->refcount = 1;
3873 loader->corrupted = FALSE;
3874 loader->corruption_reason = DBUS_VALID;
3876 /* this can be configured by the app, but defaults to the protocol max */
3877 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
3879 /* We set a very relatively conservative default here since due to how
3880 SCM_RIGHTS works we need to preallocate an fd array of the maximum
3881 number of unix fds we want to receive in advance. A
3882 try-and-reallocate loop is not possible. */
3883 loader->max_message_unix_fds = DBUS_DEFAULT_MESSAGE_UNIX_FDS;
3885 if (!_dbus_string_init (&loader->data))
3891 /* preallocate the buffer for speed, ignore failure */
3892 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
3893 _dbus_string_set_length (&loader->data, 0);
3895 #ifdef HAVE_UNIX_FD_PASSING
3896 loader->unix_fds = NULL;
3897 loader->n_unix_fds = loader->n_unix_fds_allocated = 0;
3898 loader->unix_fds_outstanding = FALSE;
3905 * Increments the reference count of the loader.
3907 * @param loader the loader.
3908 * @returns the loader
3911 _dbus_message_loader_ref (DBusMessageLoader *loader)
3913 loader->refcount += 1;
3919 * Decrements the reference count of the loader and finalizes the
3920 * loader when the count reaches zero.
3922 * @param loader the loader.
3925 _dbus_message_loader_unref (DBusMessageLoader *loader)
3927 loader->refcount -= 1;
3928 if (loader->refcount == 0)
3930 #ifdef HAVE_UNIX_FD_PASSING
3931 close_unix_fds(loader->unix_fds, &loader->n_unix_fds);
3932 dbus_free(loader->unix_fds);
3934 _dbus_list_foreach (&loader->messages,
3935 (DBusForeachFunction) dbus_message_unref,
3937 _dbus_list_clear (&loader->messages);
3938 _dbus_string_free (&loader->data);
3944 * Gets the buffer to use for reading data from the network. Network
3945 * data is read directly into an allocated buffer, which is then used
3946 * in the DBusMessage, to avoid as many extra memcpy's as possible.
3947 * The buffer must always be returned immediately using
3948 * _dbus_message_loader_return_buffer(), even if no bytes are
3949 * successfully read.
3951 * @todo this function can be a lot more clever. For example
3952 * it can probably always return a buffer size to read exactly
3953 * the body of the next message, thus avoiding any memory wastage
3956 * @todo we need to enforce a max length on strings in header fields.
3958 * @param loader the message loader.
3959 * @param buffer the buffer
3962 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
3963 DBusString **buffer)
3965 _dbus_assert (!loader->buffer_outstanding);
3967 *buffer = &loader->data;
3969 loader->buffer_outstanding = TRUE;
3973 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
3974 * indicating to the loader how many bytes of the buffer were filled
3975 * in. This function must always be called, even if no bytes were
3976 * successfully read.
3978 * @param loader the loader.
3979 * @param buffer the buffer.
3982 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
3985 _dbus_assert (loader->buffer_outstanding);
3986 _dbus_assert (buffer == &loader->data);
3988 loader->buffer_outstanding = FALSE;
3992 * Gets the buffer to use for reading unix fds from the network.
3994 * This works similar to _dbus_message_loader_get_buffer()
3996 * @param loader the message loader.
3997 * @param fds the array to read fds into
3998 * @param max_n_fds how many fds to read at most
3999 * @return TRUE on success, FALSE on OOM
4002 _dbus_message_loader_get_unix_fds(DBusMessageLoader *loader,
4004 unsigned *max_n_fds)
4006 #ifdef HAVE_UNIX_FD_PASSING
4007 _dbus_assert (!loader->unix_fds_outstanding);
4009 /* Allocate space where we can put the fds we read. We allocate
4010 space for max_message_unix_fds since this is an
4011 upper limit how many fds can be received within a single
4012 message. Since SCM_RIGHTS doesn't allow a reallocate+retry logic
4013 we are allocating the maximum possible array size right from the
4014 beginning. This sucks a bit, however unless SCM_RIGHTS is fixed
4015 there is no better way. */
4017 if (loader->n_unix_fds_allocated < loader->max_message_unix_fds)
4019 int *a = dbus_realloc(loader->unix_fds,
4020 loader->max_message_unix_fds * sizeof(loader->unix_fds[0]));
4025 loader->unix_fds = a;
4026 loader->n_unix_fds_allocated = loader->max_message_unix_fds;
4029 *fds = loader->unix_fds + loader->n_unix_fds;
4030 *max_n_fds = loader->n_unix_fds_allocated - loader->n_unix_fds;
4032 loader->unix_fds_outstanding = TRUE;
4035 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
4041 * Returns a buffer obtained from _dbus_message_loader_get_unix_fds().
4043 * This works similar to _dbus_message_loader_return_buffer()
4045 * @param loader the message loader.
4046 * @param fds the array fds were read into
4047 * @param n_fds how many fds were read
4051 _dbus_message_loader_return_unix_fds(DBusMessageLoader *loader,
4055 #ifdef HAVE_UNIX_FD_PASSING
4056 _dbus_assert(loader->unix_fds_outstanding);
4057 _dbus_assert(loader->unix_fds + loader->n_unix_fds == fds);
4058 _dbus_assert(loader->n_unix_fds + n_fds <= loader->n_unix_fds_allocated);
4060 loader->n_unix_fds += n_fds;
4061 loader->unix_fds_outstanding = FALSE;
4063 if (n_fds && loader->unix_fds_change)
4064 loader->unix_fds_change (loader->unix_fds_change_data);
4066 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
4071 * FIXME when we move the header out of the buffer, that memmoves all
4072 * buffered messages. Kind of crappy.
4074 * Also we copy the header and body, which is kind of crappy. To
4075 * avoid this, we have to allow header and body to be in a single
4076 * memory block, which is good for messages we read and bad for
4077 * messages we are creating. But we could move_len() the buffer into
4078 * this single memory block, and move_len() will just swap the buffers
4079 * if you're moving the entire buffer replacing the dest string.
4081 * We could also have the message loader tell the transport how many
4082 * bytes to read; so it would first ask for some arbitrary number like
4083 * 256, then if the message was incomplete it would use the
4084 * header/body len to ask for exactly the size of the message (or
4085 * blocks the size of a typical kernel buffer for the socket). That
4086 * way we don't get trailing bytes in the buffer that have to be
4087 * memmoved. Though I suppose we also don't have a chance of reading a
4088 * bunch of small messages at once, so the optimization may be stupid.
4090 * Another approach would be to keep a "start" index into
4091 * loader->data and only delete it occasionally, instead of after
4092 * each message is loaded.
4094 * load_message() returns FALSE if not enough memory OR the loader was corrupted
4097 load_message (DBusMessageLoader *loader,
4098 DBusMessage *message,
4100 int fields_array_len,
4105 DBusValidity validity;
4106 const DBusString *type_str;
4108 DBusValidationMode mode;
4109 dbus_uint32_t n_unix_fds = 0;
4111 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
4116 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
4119 /* 1. VALIDATE AND COPY OVER HEADER */
4120 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
4121 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
4123 if (!_dbus_header_load (&message->header,
4131 _dbus_string_get_length (&loader->data)))
4133 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
4135 /* assert here so we can catch any code that still uses DBUS_VALID to indicate
4136 oom errors. They should use DBUS_VALIDITY_UNKNOWN_OOM_ERROR instead */
4137 _dbus_assert (validity != DBUS_VALID);
4139 if (validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
4143 loader->corrupted = TRUE;
4144 loader->corruption_reason = validity;
4149 _dbus_assert (validity == DBUS_VALID);
4151 /* 2. VALIDATE BODY */
4152 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
4154 get_const_signature (&message->header, &type_str, &type_pos);
4156 /* Because the bytes_remaining arg is NULL, this validates that the
4157 * body is the right length
4159 validity = _dbus_validate_body_with_reason (type_str,
4166 if (validity != DBUS_VALID)
4168 _dbus_verbose ("Failed to validate message body code %d\n", validity);
4170 loader->corrupted = TRUE;
4171 loader->corruption_reason = validity;
4177 /* 3. COPY OVER UNIX FDS */
4178 _dbus_header_get_field_basic(&message->header,
4179 DBUS_HEADER_FIELD_UNIX_FDS,
4183 #ifdef HAVE_UNIX_FD_PASSING
4185 if (n_unix_fds > loader->n_unix_fds)
4187 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
4188 n_unix_fds, loader->n_unix_fds);
4190 loader->corrupted = TRUE;
4191 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4195 /* If this was a recycled message there might still be
4196 some memory allocated for the fds */
4197 dbus_free(message->unix_fds);
4201 message->unix_fds = _dbus_memdup(loader->unix_fds, n_unix_fds * sizeof(message->unix_fds[0]));
4202 if (message->unix_fds == NULL)
4204 _dbus_verbose ("Failed to allocate file descriptor array\n");
4209 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
4210 loader->n_unix_fds -= n_unix_fds;
4211 memmove (loader->unix_fds, loader->unix_fds + n_unix_fds, loader->n_unix_fds * sizeof (loader->unix_fds[0]));
4213 if (loader->unix_fds_change)
4214 loader->unix_fds_change (loader->unix_fds_change_data);
4217 message->unix_fds = NULL;
4223 _dbus_verbose ("Hmm, message claims to come with file descriptors "
4224 "but that's not supported on our platform, disconnecting.\n");
4226 loader->corrupted = TRUE;
4227 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4233 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
4235 if (!_dbus_list_append (&loader->messages, message))
4237 _dbus_verbose ("Failed to append new message to loader queue\n");
4242 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
4243 _dbus_assert (_dbus_string_get_length (&loader->data) >=
4244 (header_len + body_len));
4246 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
4248 _dbus_verbose ("Failed to move body into new message\n");
4253 _dbus_string_delete (&loader->data, 0, header_len + body_len);
4255 /* don't waste more than 2k of memory */
4256 _dbus_string_compact (&loader->data, 2048);
4258 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
4259 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
4261 _dbus_verbose ("Loaded message %p\n", message);
4263 _dbus_assert (!oom);
4264 _dbus_assert (!loader->corrupted);
4265 _dbus_assert (loader->messages != NULL);
4266 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4274 /* does nothing if the message isn't in the list */
4275 _dbus_list_remove_last (&loader->messages, message);
4278 _dbus_assert (!loader->corrupted);
4280 _dbus_assert (loader->corrupted);
4282 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
4288 * Converts buffered data into messages, if we have enough data. If
4289 * we don't have enough data, does nothing.
4291 * @todo we need to check that the proper named header fields exist
4292 * for each message type.
4294 * @todo If a message has unknown type, we should probably eat it
4295 * right here rather than passing it out to applications. However
4296 * it's not an error to see messages of unknown type.
4298 * @param loader the loader.
4299 * @returns #TRUE if we had enough memory to finish.
4302 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
4304 while (!loader->corrupted &&
4305 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
4307 DBusValidity validity;
4308 int byte_order, fields_array_len, header_len, body_len;
4310 if (_dbus_header_have_message_untrusted (loader->max_message_size,
4317 _dbus_string_get_length (&loader->data)))
4319 DBusMessage *message;
4321 _dbus_assert (validity == DBUS_VALID);
4323 message = dbus_message_new_empty_header ();
4324 if (message == NULL)
4327 if (!load_message (loader, message,
4328 byte_order, fields_array_len,
4329 header_len, body_len))
4331 dbus_message_unref (message);
4332 /* load_message() returns false if corrupted or OOM; if
4333 * corrupted then return TRUE for not OOM
4335 return loader->corrupted;
4338 _dbus_assert (loader->messages != NULL);
4339 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4343 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
4345 if (validity != DBUS_VALID)
4347 loader->corrupted = TRUE;
4348 loader->corruption_reason = validity;
4358 * Peeks at first loaded message, returns #NULL if no messages have
4361 * @param loader the loader.
4362 * @returns the next message, or #NULL if none.
4365 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
4367 if (loader->messages)
4368 return loader->messages->data;
4374 * Pops a loaded message (passing ownership of the message
4375 * to the caller). Returns #NULL if no messages have been
4378 * @param loader the loader.
4379 * @returns the next message, or #NULL if none.
4382 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
4384 return _dbus_list_pop_first (&loader->messages);
4388 * Pops a loaded message inside a list link (passing ownership of the
4389 * message and link to the caller). Returns #NULL if no messages have
4392 * @param loader the loader.
4393 * @returns the next message link, or #NULL if none.
4396 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
4398 return _dbus_list_pop_first_link (&loader->messages);
4402 * Returns a popped message link, used to undo a pop.
4404 * @param loader the loader
4405 * @param link the link with a message in it
4408 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
4411 _dbus_list_prepend_link (&loader->messages, link);
4415 * Checks whether the loader is confused due to bad data.
4416 * If messages are received that are invalid, the
4417 * loader gets confused and gives up permanently.
4418 * This state is called "corrupted."
4420 * @param loader the loader
4421 * @returns #TRUE if the loader is hosed.
4424 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
4426 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4427 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4428 return loader->corrupted;
4432 * Checks what kind of bad data confused the loader.
4434 * @param loader the loader
4435 * @returns why the loader is hosed, or DBUS_VALID if it isn't.
4438 _dbus_message_loader_get_corruption_reason (DBusMessageLoader *loader)
4440 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4441 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4443 return loader->corruption_reason;
4447 * Sets the maximum size message we allow.
4449 * @param loader the loader
4450 * @param size the max message size in bytes
4453 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
4456 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
4458 _dbus_verbose ("clamping requested max message size %ld to %d\n",
4459 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
4460 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4462 loader->max_message_size = size;
4466 * Gets the maximum allowed message size in bytes.
4468 * @param loader the loader
4469 * @returns max size in bytes
4472 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
4474 return loader->max_message_size;
4478 * Sets the maximum unix fds per message we allow.
4480 * @param loader the loader
4481 * @param n the max number of unix fds in a message
4484 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader,
4487 if (n > DBUS_MAXIMUM_MESSAGE_UNIX_FDS)
4489 _dbus_verbose ("clamping requested max message unix_fds %ld to %d\n",
4490 n, DBUS_MAXIMUM_MESSAGE_UNIX_FDS);
4491 n = DBUS_MAXIMUM_MESSAGE_UNIX_FDS;
4493 loader->max_message_unix_fds = n;
4497 * Gets the maximum allowed number of unix fds per message
4499 * @param loader the loader
4500 * @returns max unix fds
4503 _dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
4505 return loader->max_message_unix_fds;
4509 * Return how many file descriptors are pending in the loader
4511 * @param loader the loader
4514 _dbus_message_loader_get_pending_fds_count (DBusMessageLoader *loader)
4516 #ifdef HAVE_UNIX_FD_PASSING
4517 return loader->n_unix_fds;
4524 * Register a function to be called whenever the number of pending file
4525 * descriptors in the loader change.
4527 * @param loader the loader
4528 * @param callback the callback
4529 * @param data the data for the callback
4532 _dbus_message_loader_set_pending_fds_function (DBusMessageLoader *loader,
4533 void (* callback) (void *),
4536 #ifdef HAVE_UNIX_FD_PASSING
4537 loader->unix_fds_change = callback;
4538 loader->unix_fds_change_data = data;
4542 static DBusDataSlotAllocator slot_allocator =
4543 _DBUS_DATA_SLOT_ALLOCATOR_INIT (_DBUS_LOCK_NAME (message_slots));
4546 * Allocates an integer ID to be used for storing application-specific
4547 * data on any DBusMessage. The allocated ID may then be used
4548 * with dbus_message_set_data() and dbus_message_get_data().
4549 * The passed-in slot must be initialized to -1, and is filled in
4550 * with the slot ID. If the passed-in slot is not -1, it's assumed
4551 * to be already allocated, and its refcount is incremented.
4553 * The allocated slot is global, i.e. all DBusMessage objects will
4554 * have a slot with the given integer ID reserved.
4556 * @param slot_p address of a global variable storing the slot
4557 * @returns #FALSE on failure (no memory)
4560 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
4562 return _dbus_data_slot_allocator_alloc (&slot_allocator,
4567 * Deallocates a global ID for message data slots.
4568 * dbus_message_get_data() and dbus_message_set_data() may no
4569 * longer be used with this slot. Existing data stored on existing
4570 * DBusMessage objects will be freed when the message is
4571 * finalized, but may not be retrieved (and may only be replaced if
4572 * someone else reallocates the slot). When the refcount on the
4573 * passed-in slot reaches 0, it is set to -1.
4575 * @param slot_p address storing the slot to deallocate
4578 dbus_message_free_data_slot (dbus_int32_t *slot_p)
4580 _dbus_return_if_fail (*slot_p >= 0);
4582 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
4586 * Stores a pointer on a DBusMessage, along
4587 * with an optional function to be used for freeing
4588 * the data when the data is set again, or when
4589 * the message is finalized. The slot number
4590 * must have been allocated with dbus_message_allocate_data_slot().
4592 * @param message the message
4593 * @param slot the slot number
4594 * @param data the data to store
4595 * @param free_data_func finalizer function for the data
4596 * @returns #TRUE if there was enough memory to store the data
4599 dbus_message_set_data (DBusMessage *message,
4602 DBusFreeFunction free_data_func)
4604 DBusFreeFunction old_free_func;
4608 _dbus_return_val_if_fail (message != NULL, FALSE);
4609 _dbus_return_val_if_fail (slot >= 0, FALSE);
4611 retval = _dbus_data_slot_list_set (&slot_allocator,
4612 &message->slot_list,
4613 slot, data, free_data_func,
4614 &old_free_func, &old_data);
4618 /* Do the actual free outside the message lock */
4620 (* old_free_func) (old_data);
4627 * Retrieves data previously set with dbus_message_set_data().
4628 * The slot must still be allocated (must not have been freed).
4630 * @param message the message
4631 * @param slot the slot to get data from
4632 * @returns the data, or #NULL if not found
4635 dbus_message_get_data (DBusMessage *message,
4640 _dbus_return_val_if_fail (message != NULL, NULL);
4642 res = _dbus_data_slot_list_get (&slot_allocator,
4643 &message->slot_list,
4650 * Utility function to convert a machine-readable (not translated)
4651 * string into a D-Bus message type.
4654 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
4655 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
4656 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
4657 * "error" -> DBUS_MESSAGE_TYPE_ERROR
4658 * anything else -> DBUS_MESSAGE_TYPE_INVALID
4663 dbus_message_type_from_string (const char *type_str)
4665 if (strcmp (type_str, "method_call") == 0)
4666 return DBUS_MESSAGE_TYPE_METHOD_CALL;
4667 if (strcmp (type_str, "method_return") == 0)
4668 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
4669 else if (strcmp (type_str, "signal") == 0)
4670 return DBUS_MESSAGE_TYPE_SIGNAL;
4671 else if (strcmp (type_str, "error") == 0)
4672 return DBUS_MESSAGE_TYPE_ERROR;
4674 return DBUS_MESSAGE_TYPE_INVALID;
4678 * Utility function to convert a D-Bus message type into a
4679 * machine-readable string (not translated).
4682 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
4683 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
4684 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
4685 * DBUS_MESSAGE_TYPE_ERROR -> "error"
4686 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
4691 dbus_message_type_to_string (int type)
4695 case DBUS_MESSAGE_TYPE_METHOD_CALL:
4696 return "method_call";
4697 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
4698 return "method_return";
4699 case DBUS_MESSAGE_TYPE_SIGNAL:
4701 case DBUS_MESSAGE_TYPE_ERROR:
4709 * Turn a DBusMessage into the marshalled form as described in the D-Bus
4712 * Generally, this function is only useful for encapsulating D-Bus messages in
4713 * a different protocol.
4715 * @param msg the DBusMessage
4716 * @param marshalled_data_p the location to save the marshalled form to
4717 * @param len_p the location to save the length of the marshalled form to
4718 * @returns #FALSE if there was not enough memory
4721 dbus_message_marshal (DBusMessage *msg,
4722 char **marshalled_data_p,
4726 dbus_bool_t was_locked;
4728 _dbus_return_val_if_fail (msg != NULL, FALSE);
4729 _dbus_return_val_if_fail (marshalled_data_p != NULL, FALSE);
4730 _dbus_return_val_if_fail (len_p != NULL, FALSE);
4732 if (!_dbus_string_init (&tmp))
4735 /* Ensure the message is locked, to ensure the length header is filled in. */
4736 was_locked = msg->locked;
4739 dbus_message_lock (msg);
4741 if (!_dbus_string_copy (&(msg->header.data), 0, &tmp, 0))
4744 *len_p = _dbus_string_get_length (&tmp);
4746 if (!_dbus_string_copy (&(msg->body), 0, &tmp, *len_p))
4749 *len_p = _dbus_string_get_length (&tmp);
4751 if (!_dbus_string_steal_data (&tmp, marshalled_data_p))
4754 _dbus_string_free (&tmp);
4757 msg->locked = FALSE;
4762 _dbus_string_free (&tmp);
4765 msg->locked = FALSE;
4771 * Demarshal a D-Bus message from the format described in the D-Bus
4774 * Generally, this function is only useful for encapsulating D-Bus messages in
4775 * a different protocol.
4777 * @param str the marshalled DBusMessage
4778 * @param len the length of str
4779 * @param error the location to save errors to
4780 * @returns #NULL if there was an error
4783 dbus_message_demarshal (const char *str,
4787 DBusMessageLoader *loader;
4791 _dbus_return_val_if_fail (str != NULL, NULL);
4793 loader = _dbus_message_loader_new ();
4798 _dbus_message_loader_get_buffer (loader, &buffer);
4800 if (!_dbus_string_append_len (buffer, str, len))
4803 _dbus_message_loader_return_buffer (loader, buffer);
4805 if (!_dbus_message_loader_queue_messages (loader))
4808 if (_dbus_message_loader_get_is_corrupted (loader))
4811 msg = _dbus_message_loader_pop_message (loader);
4816 _dbus_message_loader_unref (loader);
4820 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS, "Message is corrupted (%s)",
4821 _dbus_validity_to_error_message (loader->corruption_reason));
4822 _dbus_message_loader_unref (loader);
4826 _DBUS_SET_OOM (error);
4827 _dbus_message_loader_unref (loader);
4832 * Returns the number of bytes required to be in the buffer to demarshal a
4835 * Generally, this function is only useful for encapsulating D-Bus messages in
4836 * a different protocol.
4838 * @param buf data to be marshalled
4839 * @param len the length of @p buf
4840 * @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
4844 dbus_message_demarshal_bytes_needed(const char *buf,
4848 int byte_order, fields_array_len, header_len, body_len;
4849 DBusValidity validity = DBUS_VALID;
4852 if (!buf || len < DBUS_MINIMUM_HEADER_SIZE)
4855 if (len > DBUS_MAXIMUM_MESSAGE_LENGTH)
4856 len = DBUS_MAXIMUM_MESSAGE_LENGTH;
4857 _dbus_string_init_const_len (&str, buf, len);
4859 validity = DBUS_VALID;
4861 = _dbus_header_have_message_untrusted(DBUS_MAXIMUM_MESSAGE_LENGTH,
4862 &validity, &byte_order,
4868 _dbus_string_free (&str);
4870 if (validity == DBUS_VALID)
4872 _dbus_assert (have_message || (header_len + body_len) > len);
4873 (void) have_message; /* unused unless asserting */
4874 return header_len + body_len;
4878 return -1; /* broken! */
4884 /* tests in dbus-message-util.c */