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 * Layout of a DBusMessageIter on the stack in dbus 1.10.0. This is no
141 * longer used, but for ABI compatibility we need to assert that the
142 * new layout is the same size.
148 dbus_uint32_t dummy3;
160 } DBusMessageIter_1_10_0;
163 get_const_signature (DBusHeader *header,
164 const DBusString **type_str_p,
167 if (_dbus_header_get_field_raw (header,
168 DBUS_HEADER_FIELD_SIGNATURE,
172 *type_pos_p += 1; /* skip the signature length which is 1 byte */
176 *type_str_p = &_dbus_empty_signature_str;
182 * Swaps the message to compiler byte order if required
184 * @param message the message
187 _dbus_message_byteswap (DBusMessage *message)
189 const DBusString *type_str;
193 byte_order = _dbus_header_get_byte_order (&message->header);
195 if (byte_order == DBUS_COMPILER_BYTE_ORDER)
198 _dbus_verbose ("Swapping message into compiler byte order\n");
200 get_const_signature (&message->header, &type_str, &type_pos);
202 _dbus_marshal_byteswap (type_str, type_pos,
204 DBUS_COMPILER_BYTE_ORDER,
207 _dbus_header_byteswap (&message->header, DBUS_COMPILER_BYTE_ORDER);
208 _dbus_assert (_dbus_header_get_byte_order (&message->header) ==
209 DBUS_COMPILER_BYTE_ORDER);
212 /** byte-swap the message if it doesn't match our byte order.
213 * Called only when we need the message in our own byte order,
214 * normally when reading arrays of integers or doubles.
215 * Otherwise should not be called since it would do needless
218 #define ensure_byte_order(message) _dbus_message_byteswap (message)
221 * Gets the data to be sent over the network for this message.
222 * The header and then the body should be written out.
223 * This function is guaranteed to always return the same
224 * data once a message is locked (with dbus_message_lock()).
226 * @param message the message.
227 * @param header return location for message header data.
228 * @param body return location for message body data.
231 _dbus_message_get_network_data (DBusMessage *message,
232 const DBusString **header,
233 const DBusString **body)
235 _dbus_assert (message->locked);
237 *header = &message->header.data;
238 *body = &message->body;
242 * Gets the unix fds to be sent over the network for this message.
243 * This function is guaranteed to always return the same data once a
244 * message is locked (with dbus_message_lock()).
246 * @param message the message.
247 * @param fds return location of unix fd array
248 * @param n_fds return number of entries in array
250 void _dbus_message_get_unix_fds(DBusMessage *message,
254 _dbus_assert (message->locked);
256 #ifdef HAVE_UNIX_FD_PASSING
257 *fds = message->unix_fds;
258 *n_fds = message->n_unix_fds;
266 * Sets the serial number of a message.
267 * This can only be done once on a message.
269 * DBusConnection will automatically set the serial to an appropriate value
270 * when the message is sent; this function is only needed when encapsulating
271 * messages in another protocol, or otherwise bypassing DBusConnection.
273 * @param message the message
274 * @param serial the serial
277 dbus_message_set_serial (DBusMessage *message,
278 dbus_uint32_t serial)
280 _dbus_return_if_fail (message != NULL);
281 _dbus_return_if_fail (!message->locked);
283 _dbus_header_set_serial (&message->header, serial);
287 * Adds a counter to be incremented immediately with the size/unix fds
288 * of this message, and decremented by the size/unix fds of this
289 * message when this message if finalized. The link contains a
290 * counter with its refcount already incremented, but the counter
291 * itself not incremented. Ownership of link and counter refcount is
292 * passed to the message.
294 * This function may be called with locks held. As a result, the counter's
295 * notify function is not called; the caller is expected to either call
296 * _dbus_counter_notify() on the counter when they are no longer holding
297 * locks, or take the same action that would be taken by the notify function.
299 * @param message the message
300 * @param link link with counter as data
303 _dbus_message_add_counter_link (DBusMessage *message,
306 /* right now we don't recompute the delta when message
307 * size changes, and that's OK for current purposes
308 * I think, but could be important to change later.
309 * Do recompute it whenever there are no outstanding counters,
310 * since it's basically free.
312 if (message->counters == NULL)
314 message->size_counter_delta =
315 _dbus_string_get_length (&message->header.data) +
316 _dbus_string_get_length (&message->body);
318 #ifdef HAVE_UNIX_FD_PASSING
319 message->unix_fd_counter_delta = message->n_unix_fds;
323 _dbus_verbose ("message has size %ld\n",
324 message->size_counter_delta);
328 _dbus_list_append_link (&message->counters, link);
330 _dbus_counter_adjust_size (link->data, message->size_counter_delta);
332 #ifdef HAVE_UNIX_FD_PASSING
333 _dbus_counter_adjust_unix_fd (link->data, message->unix_fd_counter_delta);
338 * Adds a counter to be incremented immediately with the size/unix fds
339 * of this message, and decremented by the size/unix fds of this
340 * message when this message if finalized.
342 * This function may be called with locks held. As a result, the counter's
343 * notify function is not called; the caller is expected to either call
344 * _dbus_counter_notify() on the counter when they are no longer holding
345 * locks, or take the same action that would be taken by the notify function.
347 * @param message the message
348 * @param counter the counter
349 * @returns #FALSE if no memory
352 _dbus_message_add_counter (DBusMessage *message,
353 DBusCounter *counter)
357 link = _dbus_list_alloc_link (counter);
361 _dbus_counter_ref (counter);
362 _dbus_message_add_counter_link (message, link);
368 * Removes a counter tracking the size/unix fds of this message, and
369 * decrements the counter by the size/unix fds of this message.
371 * @param message the message
372 * @param counter the counter
375 _dbus_message_remove_counter (DBusMessage *message,
376 DBusCounter *counter)
380 link = _dbus_list_find_last (&message->counters,
382 _dbus_assert (link != NULL);
384 _dbus_list_remove_link (&message->counters, link);
386 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
388 #ifdef HAVE_UNIX_FD_PASSING
389 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
392 _dbus_counter_notify (counter);
393 _dbus_counter_unref (counter);
397 * Locks a message. Allows checking that applications don't keep a
398 * reference to a message in the outgoing queue and change it
399 * underneath us. Messages are locked when they enter the outgoing
400 * queue (dbus_connection_send_message()), and the library complains
401 * if the message is modified while locked. This function may also
402 * called externally, for applications wrapping D-Bus in another protocol.
404 * @param message the message to lock.
407 dbus_message_lock (DBusMessage *message)
409 if (!message->locked)
411 _dbus_header_update_lengths (&message->header,
412 _dbus_string_get_length (&message->body));
414 /* must have a signature if you have a body */
415 _dbus_assert (_dbus_string_get_length (&message->body) == 0 ||
416 dbus_message_get_signature (message) != NULL);
418 message->locked = TRUE;
423 set_or_delete_string_field (DBusMessage *message,
429 return _dbus_header_delete_field (&message->header, field);
431 return _dbus_header_set_field_basic (&message->header,
438 /* Probably we don't need to use this */
440 * Sets the signature of the message, i.e. the arguments in the
441 * message payload. The signature includes only "in" arguments for
442 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
443 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
444 * what you might expect (it does not include the signature of the
445 * entire C++-style method).
447 * The signature is a string made up of type codes such as
448 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
449 * the value of #DBUS_TYPE_INVALID). The macros such as
450 * #DBUS_TYPE_INT32 evaluate to integers; to assemble a signature you
451 * may find it useful to use the string forms, such as
452 * #DBUS_TYPE_INT32_AS_STRING.
454 * An "unset" or #NULL signature is considered the same as an empty
455 * signature. In fact dbus_message_get_signature() will never return
458 * @param message the message
459 * @param signature the type signature or #NULL to unset
460 * @returns #FALSE if no memory
463 _dbus_message_set_signature (DBusMessage *message,
464 const char *signature)
466 _dbus_return_val_if_fail (message != NULL, FALSE);
467 _dbus_return_val_if_fail (!message->locked, FALSE);
468 _dbus_return_val_if_fail (signature == NULL ||
469 _dbus_check_is_valid_signature (signature));
470 /* can't delete the signature if you have a message body */
471 _dbus_return_val_if_fail (_dbus_string_get_length (&message->body) == 0 ||
474 return set_or_delete_string_field (message,
475 DBUS_HEADER_FIELD_SIGNATURE,
483 * We cache some DBusMessage to reduce the overhead of allocating
484 * them. In my profiling this consistently made about an 8%
485 * difference. It avoids the malloc for the message, the malloc for
486 * the slot list, the malloc for the header string and body string,
487 * and the associated free() calls. It does introduce another global
488 * lock which could be a performance issue in certain cases.
490 * For the echo client/server the round trip time goes from around
491 * .000077 to .000069 with the message cache on my laptop. The sysprof
492 * change is as follows (numbers are cumulative percentage):
494 * with message cache implemented as array as it is now (0.000069 per):
495 * new_empty_header 1.46
496 * mutex_lock 0.56 # i.e. _DBUS_LOCK(message_cache)
502 * mutex_lock 0.33 # i.e. _DBUS_LOCK(message_cache)
505 * with message cache implemented as list (0.000070 per roundtrip):
506 * new_empty_header 2.72
507 * list_pop_first 1.88
511 * without cache (0.000077 per roundtrip):
512 * new_empty_header 6.7
513 * string_init_preallocated 3.43
522 * If you implement the message_cache with a list, the primary reason
523 * it's slower is that you add another thread lock (on the DBusList
527 /** Avoid caching huge messages */
528 #define MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE
530 /** Avoid caching too many messages */
531 #define MAX_MESSAGE_CACHE_SIZE 5
533 /* Protected by _DBUS_LOCK (message_cache) */
534 static DBusMessage *message_cache[MAX_MESSAGE_CACHE_SIZE];
535 static int message_cache_count = 0;
536 static dbus_bool_t message_cache_shutdown_registered = FALSE;
539 dbus_message_cache_shutdown (void *data)
543 if (!_DBUS_LOCK (message_cache))
544 _dbus_assert_not_reached ("we would have initialized global locks "
545 "before registering a shutdown function");
548 while (i < MAX_MESSAGE_CACHE_SIZE)
550 if (message_cache[i])
551 dbus_message_finalize (message_cache[i]);
556 message_cache_count = 0;
557 message_cache_shutdown_registered = FALSE;
559 _DBUS_UNLOCK (message_cache);
563 * Tries to get a message from the message cache. The retrieved
564 * message will have junk in it, so it still needs to be cleared out
565 * in dbus_message_new_empty_header()
567 * @returns the message, or #NULL if none cached
570 dbus_message_get_cached (void)
572 DBusMessage *message;
577 if (!_DBUS_LOCK (message_cache))
579 /* we'd have initialized global locks before caching anything,
580 * so there can't be anything in the cache */
584 _dbus_assert (message_cache_count >= 0);
586 if (message_cache_count == 0)
588 _DBUS_UNLOCK (message_cache);
592 /* This is not necessarily true unless count > 0, and
593 * message_cache is uninitialized until the shutdown is
596 _dbus_assert (message_cache_shutdown_registered);
599 while (i < MAX_MESSAGE_CACHE_SIZE)
601 if (message_cache[i])
603 message = message_cache[i];
604 message_cache[i] = NULL;
605 message_cache_count -= 1;
610 _dbus_assert (message_cache_count >= 0);
611 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
612 _dbus_assert (message != NULL);
614 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
616 _dbus_assert (message->counters == NULL);
618 _DBUS_UNLOCK (message_cache);
623 #ifdef HAVE_UNIX_FD_PASSING
625 close_unix_fds(int *fds, unsigned *n_fds)
635 for (i = 0; i < *n_fds; i++)
637 if (!_dbus_close(fds[i], &e))
639 _dbus_warn("Failed to close file descriptor: %s\n", e.message);
646 /* We don't free the array here, in case we can recycle it later */
651 free_counter (void *element,
654 DBusCounter *counter = element;
655 DBusMessage *message = data;
657 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
658 #ifdef HAVE_UNIX_FD_PASSING
659 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
662 _dbus_counter_notify (counter);
663 _dbus_counter_unref (counter);
667 * Tries to cache a message, otherwise finalize it.
669 * @param message the message
672 dbus_message_cache_or_finalize (DBusMessage *message)
674 dbus_bool_t was_cached;
677 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
679 /* This calls application code and has to be done first thing
680 * without holding the lock
682 _dbus_data_slot_list_clear (&message->slot_list);
684 _dbus_list_foreach (&message->counters,
685 free_counter, message);
686 _dbus_list_clear (&message->counters);
688 #ifdef HAVE_UNIX_FD_PASSING
689 close_unix_fds(message->unix_fds, &message->n_unix_fds);
694 if (!_DBUS_LOCK (message_cache))
696 /* The only way to get a non-null message goes through
697 * dbus_message_get_cached() which takes the lock. */
698 _dbus_assert_not_reached ("we would have initialized global locks "
699 "the first time we constructed a message");
702 if (!message_cache_shutdown_registered)
704 _dbus_assert (message_cache_count == 0);
706 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
710 while (i < MAX_MESSAGE_CACHE_SIZE)
712 message_cache[i] = NULL;
716 message_cache_shutdown_registered = TRUE;
719 _dbus_assert (message_cache_count >= 0);
721 if (!_dbus_enable_message_cache ())
724 if ((_dbus_string_get_length (&message->header.data) +
725 _dbus_string_get_length (&message->body)) >
726 MAX_MESSAGE_SIZE_TO_CACHE)
729 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
732 /* Find empty slot */
734 while (message_cache[i] != NULL)
737 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
739 _dbus_assert (message_cache[i] == NULL);
740 message_cache[i] = message;
741 message_cache_count += 1;
743 #ifndef DBUS_DISABLE_CHECKS
744 message->in_cache = TRUE;
748 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
750 _DBUS_UNLOCK (message_cache);
753 dbus_message_finalize (message);
756 #if defined(DBUS_ENABLE_CHECKS) || defined(DBUS_ENABLE_ASSERT)
758 _dbus_message_iter_check (DBusMessageRealIter *iter)
764 _dbus_warn_check_failed ("dbus message iterator is NULL\n");
768 byte_order = _dbus_header_get_byte_order (&iter->message->header);
770 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
772 if (iter->u.reader.byte_order != byte_order)
774 _dbus_warn_check_failed ("dbus message changed byte order since iterator was created\n");
777 /* because we swap the message into compiler order when you init an iter */
778 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
780 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
782 if (iter->u.writer.byte_order != byte_order)
784 _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created\n");
787 /* because we swap the message into compiler order when you init an iter */
788 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
792 _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted\n");
796 if (iter->changed_stamp != iter->message->changed_stamp)
798 _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
804 #endif /* DBUS_ENABLE_CHECKS || DBUS_ENABLE_ASSERT */
807 * Implementation of the varargs arg-getting functions.
808 * dbus_message_get_args() is the place to go for complete
811 * @see dbus_message_get_args
812 * @param iter the message iter
813 * @param error error to be filled in
814 * @param first_arg_type type of the first argument
815 * @param var_args return location for first argument, followed by list of type/location pairs
816 * @returns #FALSE if error was set
819 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
824 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
825 int spec_type, msg_type, i, j;
829 _dbus_assert (_dbus_message_iter_check (real));
833 spec_type = first_arg_type;
836 /* copy var_args first, then we can do another iteration over it to
837 * free memory and close unix fds if parse failed at some point.
839 DBUS_VA_COPY (copy_args, var_args);
841 while (spec_type != DBUS_TYPE_INVALID)
843 msg_type = dbus_message_iter_get_arg_type (iter);
845 if (msg_type != spec_type)
847 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
848 "Argument %d is specified to be of type \"%s\", but "
849 "is actually of type \"%s\"\n", i,
850 _dbus_type_to_string (spec_type),
851 _dbus_type_to_string (msg_type));
856 if (spec_type == DBUS_TYPE_UNIX_FD)
858 #ifdef HAVE_UNIX_FD_PASSING
862 pfd = va_arg (var_args, int*);
865 _dbus_type_reader_read_basic(&real->u.reader, &idx);
867 if (idx.u32 >= real->message->n_unix_fds)
869 dbus_set_error (error, DBUS_ERROR_INCONSISTENT_MESSAGE,
870 "Message refers to file descriptor at index %i,"
871 "but has only %i descriptors attached.\n",
873 real->message->n_unix_fds);
877 if ((nfd = _dbus_dup(real->message->unix_fds[idx.u32], error)) < 0)
882 dbus_set_error (error, DBUS_ERROR_NOT_SUPPORTED,
883 "Platform does not support file desciptor passing.\n");
887 else if (dbus_type_is_basic (spec_type))
891 ptr = va_arg (var_args, DBusBasicValue*);
893 _dbus_assert (ptr != NULL);
895 _dbus_type_reader_read_basic (&real->u.reader,
898 else if (spec_type == DBUS_TYPE_ARRAY)
901 int spec_element_type;
902 const DBusBasicValue **ptr;
904 DBusTypeReader array;
906 spec_element_type = va_arg (var_args, int);
907 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
909 if (spec_element_type != element_type)
911 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
912 "Argument %d is specified to be an array of \"%s\", but "
913 "is actually an array of \"%s\"\n",
915 _dbus_type_to_string (spec_element_type),
916 _dbus_type_to_string (element_type));
921 if (dbus_type_is_fixed (spec_element_type) &&
922 element_type != DBUS_TYPE_UNIX_FD)
924 ptr = va_arg (var_args, const DBusBasicValue**);
925 n_elements_p = va_arg (var_args, int*);
927 _dbus_assert (ptr != NULL);
928 _dbus_assert (n_elements_p != NULL);
930 _dbus_type_reader_recurse (&real->u.reader, &array);
932 _dbus_type_reader_read_fixed_multi (&array,
933 (void *) ptr, n_elements_p);
935 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
941 str_array_p = va_arg (var_args, char***);
942 n_elements_p = va_arg (var_args, int*);
944 _dbus_assert (str_array_p != NULL);
945 _dbus_assert (n_elements_p != NULL);
947 /* Count elements in the array */
948 _dbus_type_reader_recurse (&real->u.reader, &array);
951 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
954 _dbus_type_reader_next (&array);
957 str_array = dbus_new0 (char*, n_elements + 1);
958 if (str_array == NULL)
960 _DBUS_SET_OOM (error);
964 /* Now go through and dup each string */
965 _dbus_type_reader_recurse (&real->u.reader, &array);
968 while (j < n_elements)
971 _dbus_type_reader_read_basic (&array,
974 str_array[j] = _dbus_strdup (s);
975 if (str_array[j] == NULL)
977 dbus_free_string_array (str_array);
978 _DBUS_SET_OOM (error);
984 if (!_dbus_type_reader_next (&array))
985 _dbus_assert (j == n_elements);
988 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
989 _dbus_assert (j == n_elements);
990 _dbus_assert (str_array[j] == NULL);
992 *str_array_p = str_array;
993 *n_elements_p = n_elements;
995 #ifndef DBUS_DISABLE_CHECKS
998 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
999 _DBUS_FUNCTION_NAME);
1004 #ifndef DBUS_DISABLE_CHECKS
1007 _dbus_warn ("you can only read arrays and basic types with %s for now\n",
1008 _DBUS_FUNCTION_NAME);
1013 /* how many arguments already handled */
1016 spec_type = va_arg (var_args, int);
1017 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
1019 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
1020 "Message has only %d arguments, but more were expected", i);
1028 /* there may memory or unix fd leak in the above iteration if parse failed.
1029 * so we have another iteration over copy_args to free memory and close
1034 spec_type = first_arg_type;
1039 if (spec_type == DBUS_TYPE_UNIX_FD)
1041 #ifdef HAVE_UNIX_FD_PASSING
1044 pfd = va_arg (copy_args, int *);
1048 _dbus_close (*pfd, NULL);
1053 else if (dbus_type_is_basic (spec_type))
1055 /* move the index forward */
1056 va_arg (copy_args, DBusBasicValue *);
1058 else if (spec_type == DBUS_TYPE_ARRAY)
1060 int spec_element_type;
1062 spec_element_type = va_arg (copy_args, int);
1063 if (dbus_type_is_fixed (spec_element_type))
1065 /* move the index forward */
1066 va_arg (copy_args, const DBusBasicValue **);
1067 va_arg (copy_args, int *);
1069 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
1071 char ***str_array_p;
1073 str_array_p = va_arg (copy_args, char ***);
1074 /* move the index forward */
1075 va_arg (copy_args, int *);
1076 _dbus_assert (str_array_p != NULL);
1077 dbus_free_string_array (*str_array_p);
1078 *str_array_p = NULL;
1082 spec_type = va_arg (copy_args, int);
1094 * @defgroup DBusMessage DBusMessage
1096 * @brief Message to be sent or received over a #DBusConnection.
1098 * A DBusMessage is the most basic unit of communication over a
1099 * DBusConnection. A DBusConnection represents a stream of messages
1100 * received from a remote application, and a stream of messages
1101 * sent to a remote application.
1103 * A message has a message type, returned from
1104 * dbus_message_get_type(). This indicates whether the message is a
1105 * method call, a reply to a method call, a signal, or an error reply.
1107 * A message has header fields such as the sender, destination, method
1108 * or signal name, and so forth. DBusMessage has accessor functions for
1109 * these, such as dbus_message_get_member().
1111 * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
1112 * and dbus_message_is_error() check several header fields at once and are
1113 * slightly more efficient than checking the header fields with individual
1114 * accessor functions.
1116 * Finally, a message has arguments. The number and types of arguments
1117 * are in the message's signature header field (accessed with
1118 * dbus_message_get_signature()). Simple argument values are usually
1119 * retrieved with dbus_message_get_args() but more complex values such
1120 * as structs may require the use of #DBusMessageIter.
1122 * The D-Bus specification goes into some more detail about header fields and
1129 * @typedef DBusMessage
1131 * Opaque data type representing a message received from or to be
1132 * sent to another application.
1136 * Returns the serial of a message or 0 if none has been specified.
1137 * The message's serial number is provided by the application sending
1138 * the message and is used to identify replies to this message.
1140 * All messages received on a connection will have a serial provided
1141 * by the remote application.
1143 * For messages you're sending, dbus_connection_send() will assign a
1144 * serial and return it to you.
1146 * @param message the message
1147 * @returns the serial
1150 dbus_message_get_serial (DBusMessage *message)
1152 _dbus_return_val_if_fail (message != NULL, 0);
1154 return _dbus_header_get_serial (&message->header);
1158 * Sets the reply serial of a message (the serial of the message this
1161 * @param message the message
1162 * @param reply_serial the serial we're replying to
1163 * @returns #FALSE if not enough memory
1166 dbus_message_set_reply_serial (DBusMessage *message,
1167 dbus_uint32_t reply_serial)
1169 _dbus_return_val_if_fail (message != NULL, FALSE);
1170 _dbus_return_val_if_fail (!message->locked, FALSE);
1171 _dbus_return_val_if_fail (reply_serial != 0, FALSE); /* 0 is invalid */
1173 return _dbus_header_set_field_basic (&message->header,
1174 DBUS_HEADER_FIELD_REPLY_SERIAL,
1180 * Returns the serial that the message is a reply to or 0 if none.
1182 * @param message the message
1183 * @returns the reply serial
1186 dbus_message_get_reply_serial (DBusMessage *message)
1188 dbus_uint32_t v_UINT32;
1190 _dbus_return_val_if_fail (message != NULL, 0);
1192 if (_dbus_header_get_field_basic (&message->header,
1193 DBUS_HEADER_FIELD_REPLY_SERIAL,
1202 dbus_message_finalize (DBusMessage *message)
1204 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1206 /* This calls application callbacks! */
1207 _dbus_data_slot_list_free (&message->slot_list);
1209 _dbus_list_foreach (&message->counters,
1210 free_counter, message);
1211 _dbus_list_clear (&message->counters);
1213 _dbus_header_free (&message->header);
1214 _dbus_string_free (&message->body);
1216 #ifdef HAVE_UNIX_FD_PASSING
1217 close_unix_fds(message->unix_fds, &message->n_unix_fds);
1218 dbus_free(message->unix_fds);
1221 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1223 dbus_free (message);
1227 dbus_message_new_empty_header (void)
1229 DBusMessage *message;
1230 dbus_bool_t from_cache;
1232 message = dbus_message_get_cached ();
1234 if (message != NULL)
1241 message = dbus_new0 (DBusMessage, 1);
1242 if (message == NULL)
1244 #ifndef DBUS_DISABLE_CHECKS
1245 message->generation = _dbus_current_generation;
1248 #ifdef HAVE_UNIX_FD_PASSING
1249 message->unix_fds = NULL;
1250 message->n_unix_fds_allocated = 0;
1254 _dbus_atomic_inc (&message->refcount);
1256 _dbus_message_trace_ref (message, 0, 1, "new_empty_header");
1258 message->locked = FALSE;
1259 #ifndef DBUS_DISABLE_CHECKS
1260 message->in_cache = FALSE;
1262 message->counters = NULL;
1263 message->size_counter_delta = 0;
1264 message->changed_stamp = 0;
1266 #ifdef HAVE_UNIX_FD_PASSING
1267 message->n_unix_fds = 0;
1268 message->n_unix_fds_allocated = 0;
1269 message->unix_fd_counter_delta = 0;
1273 _dbus_data_slot_list_init (&message->slot_list);
1277 _dbus_header_reinit (&message->header);
1278 _dbus_string_set_length (&message->body, 0);
1282 if (!_dbus_header_init (&message->header))
1284 dbus_free (message);
1288 if (!_dbus_string_init_preallocated (&message->body, 32))
1290 _dbus_header_free (&message->header);
1291 dbus_free (message);
1300 * Constructs a new message of the given message type.
1301 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
1302 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
1304 * Usually you want to use dbus_message_new_method_call(),
1305 * dbus_message_new_method_return(), dbus_message_new_signal(),
1306 * or dbus_message_new_error() instead.
1308 * @param message_type type of message
1309 * @returns new message or #NULL if no memory
1312 dbus_message_new (int message_type)
1314 DBusMessage *message;
1316 _dbus_return_val_if_fail (message_type != DBUS_MESSAGE_TYPE_INVALID, NULL);
1318 message = dbus_message_new_empty_header ();
1319 if (message == NULL)
1322 if (!_dbus_header_create (&message->header,
1323 DBUS_COMPILER_BYTE_ORDER,
1325 NULL, NULL, NULL, NULL, NULL))
1327 dbus_message_unref (message);
1335 * Constructs a new message to invoke a method on a remote
1336 * object. Returns #NULL if memory can't be allocated for the
1337 * message. The destination may be #NULL in which case no destination
1338 * is set; this is appropriate when using D-Bus in a peer-to-peer
1339 * context (no message bus). The interface may be #NULL, which means
1340 * that if multiple methods with the given name exist it is undefined
1341 * which one will be invoked.
1343 * The path and method names may not be #NULL.
1345 * Destination, path, interface, and method name can't contain
1346 * any invalid characters (see the D-Bus specification).
1348 * @param destination name that the message should be sent to or #NULL
1349 * @param path object path the message should be sent to
1350 * @param iface interface to invoke method on, or #NULL
1351 * @param method method to invoke
1353 * @returns a new DBusMessage, free with dbus_message_unref()
1356 dbus_message_new_method_call (const char *destination,
1361 DBusMessage *message;
1363 _dbus_return_val_if_fail (path != NULL, NULL);
1364 _dbus_return_val_if_fail (method != NULL, NULL);
1365 _dbus_return_val_if_fail (destination == NULL ||
1366 _dbus_check_is_valid_bus_name (destination), NULL);
1367 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1368 _dbus_return_val_if_fail (iface == NULL ||
1369 _dbus_check_is_valid_interface (iface), NULL);
1370 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
1372 message = dbus_message_new_empty_header ();
1373 if (message == NULL)
1376 if (!_dbus_header_create (&message->header,
1377 DBUS_COMPILER_BYTE_ORDER,
1378 DBUS_MESSAGE_TYPE_METHOD_CALL,
1379 destination, path, iface, method, NULL))
1381 dbus_message_unref (message);
1389 * Constructs a message that is a reply to a method call. Returns
1390 * #NULL if memory can't be allocated for the message.
1392 * @param method_call the message being replied to
1393 * @returns a new DBusMessage, free with dbus_message_unref()
1396 dbus_message_new_method_return (DBusMessage *method_call)
1398 DBusMessage *message;
1401 _dbus_return_val_if_fail (method_call != NULL, NULL);
1403 sender = dbus_message_get_sender (method_call);
1405 /* sender is allowed to be null here in peer-to-peer case */
1407 message = dbus_message_new_empty_header ();
1408 if (message == NULL)
1411 if (!_dbus_header_create (&message->header,
1412 DBUS_COMPILER_BYTE_ORDER,
1413 DBUS_MESSAGE_TYPE_METHOD_RETURN,
1414 sender, NULL, NULL, NULL, NULL))
1416 dbus_message_unref (message);
1420 dbus_message_set_no_reply (message, TRUE);
1422 if (!dbus_message_set_reply_serial (message,
1423 dbus_message_get_serial (method_call)))
1425 dbus_message_unref (message);
1433 * Constructs a new message representing a signal emission. Returns
1434 * #NULL if memory can't be allocated for the message. A signal is
1435 * identified by its originating object path, interface, and the name
1438 * Path, interface, and signal name must all be valid (the D-Bus
1439 * specification defines the syntax of these fields).
1441 * @param path the path to the object emitting the signal
1442 * @param iface the interface the signal is emitted from
1443 * @param name name of the signal
1444 * @returns a new DBusMessage, free with dbus_message_unref()
1447 dbus_message_new_signal (const char *path,
1451 DBusMessage *message;
1453 _dbus_return_val_if_fail (path != NULL, NULL);
1454 _dbus_return_val_if_fail (iface != NULL, NULL);
1455 _dbus_return_val_if_fail (name != NULL, NULL);
1456 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1457 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (iface), NULL);
1458 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
1460 message = dbus_message_new_empty_header ();
1461 if (message == NULL)
1464 if (!_dbus_header_create (&message->header,
1465 DBUS_COMPILER_BYTE_ORDER,
1466 DBUS_MESSAGE_TYPE_SIGNAL,
1467 NULL, path, iface, name, NULL))
1469 dbus_message_unref (message);
1473 dbus_message_set_no_reply (message, TRUE);
1479 * Creates a new message that is an error reply to another message.
1480 * Error replies are most common in response to method calls, but
1481 * can be returned in reply to any message.
1483 * The error name must be a valid error name according to the syntax
1484 * given in the D-Bus specification. If you don't want to make
1485 * up an error name just use #DBUS_ERROR_FAILED.
1487 * @param reply_to the message we're replying to
1488 * @param error_name the error name
1489 * @param error_message the error message string (or #NULL for none, but please give a message)
1490 * @returns a new error message object, free with dbus_message_unref()
1493 dbus_message_new_error (DBusMessage *reply_to,
1494 const char *error_name,
1495 const char *error_message)
1497 DBusMessage *message;
1499 DBusMessageIter iter;
1501 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1502 _dbus_return_val_if_fail (error_name != NULL, NULL);
1503 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1505 sender = dbus_message_get_sender (reply_to);
1507 /* sender may be NULL for non-message-bus case or
1508 * when the message bus is dealing with an unregistered
1511 message = dbus_message_new_empty_header ();
1512 if (message == NULL)
1515 if (!_dbus_header_create (&message->header,
1516 DBUS_COMPILER_BYTE_ORDER,
1517 DBUS_MESSAGE_TYPE_ERROR,
1518 sender, NULL, NULL, NULL, error_name))
1520 dbus_message_unref (message);
1524 dbus_message_set_no_reply (message, TRUE);
1526 if (!dbus_message_set_reply_serial (message,
1527 dbus_message_get_serial (reply_to)))
1529 dbus_message_unref (message);
1533 if (error_message != NULL)
1535 dbus_message_iter_init_append (message, &iter);
1536 if (!dbus_message_iter_append_basic (&iter,
1540 dbus_message_unref (message);
1549 * Creates a new message that is an error reply to another message, allowing
1550 * you to use printf formatting.
1552 * See dbus_message_new_error() for details - this function is the same
1553 * aside from the printf formatting.
1555 * @todo add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to
1556 * public header, see DBUS_DEPRECATED for an example)
1558 * @param reply_to the original message
1559 * @param error_name the error name
1560 * @param error_format the error message format as with printf
1561 * @param ... format string arguments
1562 * @returns a new error message
1565 dbus_message_new_error_printf (DBusMessage *reply_to,
1566 const char *error_name,
1567 const char *error_format,
1572 DBusMessage *message;
1574 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1575 _dbus_return_val_if_fail (error_name != NULL, NULL);
1576 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1578 if (!_dbus_string_init (&str))
1581 va_start (args, error_format);
1583 if (_dbus_string_append_printf_valist (&str, error_format, args))
1584 message = dbus_message_new_error (reply_to, error_name,
1585 _dbus_string_get_const_data (&str));
1589 _dbus_string_free (&str);
1598 * Creates a new message that is an exact replica of the message
1599 * specified, except that its refcount is set to 1, its message serial
1600 * is reset to 0, and if the original message was "locked" (in the
1601 * outgoing message queue and thus not modifiable) the new message
1602 * will not be locked.
1604 * @todo This function can't be used in programs that try to recover from OOM errors.
1606 * @param message the message
1607 * @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.
1610 dbus_message_copy (const DBusMessage *message)
1612 DBusMessage *retval;
1614 _dbus_return_val_if_fail (message != NULL, NULL);
1616 retval = dbus_new0 (DBusMessage, 1);
1620 _dbus_atomic_inc (&retval->refcount);
1622 retval->locked = FALSE;
1623 #ifndef DBUS_DISABLE_CHECKS
1624 retval->generation = message->generation;
1627 if (!_dbus_header_copy (&message->header, &retval->header))
1633 if (!_dbus_string_init_preallocated (&retval->body,
1634 _dbus_string_get_length (&message->body)))
1636 _dbus_header_free (&retval->header);
1641 if (!_dbus_string_copy (&message->body, 0,
1645 #ifdef HAVE_UNIX_FD_PASSING
1646 retval->unix_fds = dbus_new(int, message->n_unix_fds);
1647 if (retval->unix_fds == NULL && message->n_unix_fds > 0)
1650 retval->n_unix_fds_allocated = message->n_unix_fds;
1652 for (retval->n_unix_fds = 0;
1653 retval->n_unix_fds < message->n_unix_fds;
1654 retval->n_unix_fds++)
1656 retval->unix_fds[retval->n_unix_fds] = _dbus_dup(message->unix_fds[retval->n_unix_fds], NULL);
1658 if (retval->unix_fds[retval->n_unix_fds] < 0)
1664 _dbus_message_trace_ref (retval, 0, 1, "copy");
1668 _dbus_header_free (&retval->header);
1669 _dbus_string_free (&retval->body);
1671 #ifdef HAVE_UNIX_FD_PASSING
1672 close_unix_fds(retval->unix_fds, &retval->n_unix_fds);
1673 dbus_free(retval->unix_fds);
1683 * Increments the reference count of a DBusMessage.
1685 * @param message the message
1686 * @returns the message
1687 * @see dbus_message_unref
1690 dbus_message_ref (DBusMessage *message)
1692 dbus_int32_t old_refcount;
1694 _dbus_return_val_if_fail (message != NULL, NULL);
1695 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1696 _dbus_return_val_if_fail (!message->in_cache, NULL);
1698 old_refcount = _dbus_atomic_inc (&message->refcount);
1699 _dbus_assert (old_refcount >= 1);
1700 _dbus_message_trace_ref (message, old_refcount, old_refcount + 1, "ref");
1706 * Decrements the reference count of a DBusMessage, freeing the
1707 * message if the count reaches 0.
1709 * @param message the message
1710 * @see dbus_message_ref
1713 dbus_message_unref (DBusMessage *message)
1715 dbus_int32_t old_refcount;
1717 _dbus_return_if_fail (message != NULL);
1718 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1719 _dbus_return_if_fail (!message->in_cache);
1721 old_refcount = _dbus_atomic_dec (&message->refcount);
1723 _dbus_assert (old_refcount >= 1);
1725 _dbus_message_trace_ref (message, old_refcount, old_refcount - 1, "unref");
1727 if (old_refcount == 1)
1729 /* Calls application callbacks! */
1730 dbus_message_cache_or_finalize (message);
1735 * Gets the type of a message. Types include
1736 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1737 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1738 * types are allowed and all code must silently ignore messages of
1739 * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
1741 * @param message the message
1742 * @returns the type of the message
1745 dbus_message_get_type (DBusMessage *message)
1747 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1749 return _dbus_header_get_message_type (&message->header);
1753 * Appends fields to a message given a variable argument list. The
1754 * variable argument list should contain the type of each argument
1755 * followed by the value to append. Appendable types are basic types,
1756 * and arrays of fixed-length basic types (except arrays of Unix file
1757 * descriptors). To append variable-length basic types, or any more
1758 * complex value, you have to use an iterator rather than this
1761 * To append a basic type, specify its type code followed by the
1762 * address of the value. For example:
1766 * dbus_int32_t v_INT32 = 42;
1767 * const char *v_STRING = "Hello World";
1768 * dbus_message_append_args (message,
1769 * DBUS_TYPE_INT32, &v_INT32,
1770 * DBUS_TYPE_STRING, &v_STRING,
1771 * DBUS_TYPE_INVALID);
1774 * To append an array of fixed-length basic types (except Unix file
1775 * descriptors), pass in the DBUS_TYPE_ARRAY typecode, the element
1776 * typecode, the address of the array pointer, and a 32-bit integer
1777 * giving the number of elements in the array. So for example: @code
1778 * const dbus_int32_t array[] = { 1, 2, 3 }; const dbus_int32_t
1779 * *v_ARRAY = array; dbus_message_append_args (message,
1780 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3, DBUS_TYPE_INVALID);
1783 * This function does not support arrays of Unix file descriptors. If
1784 * you need those you need to manually recurse into the array.
1786 * For Unix file descriptors this function will internally duplicate
1787 * the descriptor you passed in. Hence you may close the descriptor
1788 * immediately after this call.
1790 * @warning in C, given "int array[]", "&array == array" (the
1791 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
1792 * So if you're using an array instead of a pointer you have to create
1793 * a pointer variable, assign the array to it, then take the address
1794 * of the pointer variable. For strings it works to write
1795 * const char *array = "Hello" and then use &array though.
1797 * The last argument to this function must be #DBUS_TYPE_INVALID,
1798 * marking the end of the argument list. If you don't do this
1799 * then libdbus won't know to stop and will read invalid memory.
1801 * String/signature/path arrays should be passed in as "const char***
1802 * address_of_array" and "int n_elements"
1804 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1806 * @todo If this fails due to lack of memory, the message is hosed and
1807 * you have to start over building the whole message.
1809 * @param message the message
1810 * @param first_arg_type type of the first argument
1811 * @param ... value of first argument, list of additional type-value pairs
1812 * @returns #TRUE on success
1815 dbus_message_append_args (DBusMessage *message,
1822 _dbus_return_val_if_fail (message != NULL, FALSE);
1824 va_start (var_args, first_arg_type);
1825 retval = dbus_message_append_args_valist (message,
1834 * Like dbus_message_append_args() but takes a va_list for use by language bindings.
1836 * @todo for now, if this function fails due to OOM it will leave
1837 * the message half-written and you have to discard the message
1840 * @see dbus_message_append_args.
1841 * @param message the message
1842 * @param first_arg_type type of first argument
1843 * @param var_args value of first argument, then list of type/value pairs
1844 * @returns #TRUE on success
1847 dbus_message_append_args_valist (DBusMessage *message,
1852 DBusMessageIter iter;
1854 _dbus_return_val_if_fail (message != NULL, FALSE);
1856 type = first_arg_type;
1858 dbus_message_iter_init_append (message, &iter);
1860 while (type != DBUS_TYPE_INVALID)
1862 if (dbus_type_is_basic (type))
1864 const DBusBasicValue *value;
1865 value = va_arg (var_args, const DBusBasicValue*);
1867 if (!dbus_message_iter_append_basic (&iter,
1872 else if (type == DBUS_TYPE_ARRAY)
1875 DBusMessageIter array;
1878 element_type = va_arg (var_args, int);
1880 buf[0] = element_type;
1882 if (!dbus_message_iter_open_container (&iter,
1888 if (dbus_type_is_fixed (element_type) &&
1889 element_type != DBUS_TYPE_UNIX_FD)
1891 const DBusBasicValue **value;
1894 value = va_arg (var_args, const DBusBasicValue**);
1895 n_elements = va_arg (var_args, int);
1897 if (!dbus_message_iter_append_fixed_array (&array,
1901 dbus_message_iter_abandon_container (&iter, &array);
1905 else if (_DBUS_TYPE_IS_STRINGLIKE (element_type))
1907 const char ***value_p;
1912 value_p = va_arg (var_args, const char***);
1913 n_elements = va_arg (var_args, int);
1918 while (i < n_elements)
1920 if (!dbus_message_iter_append_basic (&array,
1923 dbus_message_iter_abandon_container (&iter, &array);
1931 _dbus_warn ("arrays of %s can't be appended with %s for now\n",
1932 _dbus_type_to_string (element_type),
1933 _DBUS_FUNCTION_NAME);
1937 if (!dbus_message_iter_close_container (&iter, &array))
1940 #ifndef DBUS_DISABLE_CHECKS
1943 _dbus_warn ("type %s isn't supported yet in %s\n",
1944 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
1949 type = va_arg (var_args, int);
1959 * Gets arguments from a message given a variable argument list. The
1960 * supported types include those supported by
1961 * dbus_message_append_args(); that is, basic types and arrays of
1962 * fixed-length basic types. The arguments are the same as they would
1963 * be for dbus_message_iter_get_basic() or
1964 * dbus_message_iter_get_fixed_array().
1966 * In addition to those types, arrays of string, object path, and
1967 * signature are supported; but these are returned as allocated memory
1968 * and must be freed with dbus_free_string_array(), while the other
1969 * types are returned as const references. To get a string array
1970 * pass in "char ***array_location" and "int *n_elements".
1972 * Similar to dbus_message_get_fixed_array() this function does not
1973 * support arrays of type DBUS_TYPE_UNIX_FD. If you need to parse
1974 * messages with arrays of Unix file descriptors you need to recurse
1975 * into the array manually.
1977 * Unix file descriptors that are read with this function will have
1978 * the FD_CLOEXEC flag set. If you need them without this flag set,
1979 * make sure to unset it with fcntl().
1981 * The variable argument list should contain the type of the argument
1982 * followed by a pointer to where the value should be stored. The list
1983 * is terminated with #DBUS_TYPE_INVALID.
1985 * Except for string arrays, the returned values are constant; do not
1986 * free them. They point into the #DBusMessage.
1988 * If the requested arguments are not present, or do not have the
1989 * requested types, then an error will be set.
1991 * If more arguments than requested are present, the requested
1992 * arguments are returned and the extra arguments are ignored.
1994 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1996 * @param message the message
1997 * @param error error to be filled in on failure
1998 * @param first_arg_type the first argument type
1999 * @param ... location for first argument value, then list of type-location pairs
2000 * @returns #FALSE if the error was set
2003 dbus_message_get_args (DBusMessage *message,
2011 _dbus_return_val_if_fail (message != NULL, FALSE);
2012 _dbus_return_val_if_error_is_set (error, FALSE);
2014 va_start (var_args, first_arg_type);
2015 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
2022 * Like dbus_message_get_args but takes a va_list for use by language bindings.
2024 * @see dbus_message_get_args
2025 * @param message the message
2026 * @param error error to be filled in
2027 * @param first_arg_type type of the first argument
2028 * @param var_args return location for first argument, followed by list of type/location pairs
2029 * @returns #FALSE if error was set
2032 dbus_message_get_args_valist (DBusMessage *message,
2037 DBusMessageIter iter;
2039 _dbus_return_val_if_fail (message != NULL, FALSE);
2040 _dbus_return_val_if_error_is_set (error, FALSE);
2042 dbus_message_iter_init (message, &iter);
2043 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
2047 _dbus_message_iter_init_common (DBusMessage *message,
2048 DBusMessageRealIter *real,
2051 /* If these static assertions fail on your platform, report it as a bug. */
2052 _DBUS_STATIC_ASSERT (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
2053 _DBUS_STATIC_ASSERT (_DBUS_ALIGNOF (DBusMessageRealIter) <=
2054 _DBUS_ALIGNOF (DBusMessageIter));
2055 /* A failure of these two assertions would indicate that we've broken
2056 * ABI on this platform since 1.10.0. */
2057 _DBUS_STATIC_ASSERT (sizeof (DBusMessageIter_1_10_0) ==
2058 sizeof (DBusMessageIter));
2059 _DBUS_STATIC_ASSERT (_DBUS_ALIGNOF (DBusMessageIter_1_10_0) ==
2060 _DBUS_ALIGNOF (DBusMessageIter));
2061 /* If this static assertion fails, it means the DBusMessageIter struct
2062 * is not "packed", which might result in "iter = other_iter" not copying
2064 _DBUS_STATIC_ASSERT (sizeof (DBusMessageIter) ==
2065 4 * sizeof (void *) + sizeof (dbus_uint32_t) + 9 * sizeof (int));
2067 /* Since the iterator will read or write who-knows-what from the
2068 * message, we need to get in the right byte order
2070 ensure_byte_order (message);
2072 real->message = message;
2073 real->changed_stamp = message->changed_stamp;
2074 real->iter_type = iter_type;
2075 real->sig_refcount = 0;
2079 * Initializes a #DBusMessageIter for reading the arguments of the
2080 * message passed in.
2082 * When possible, dbus_message_get_args() is much more convenient.
2083 * Some types of argument can only be read with #DBusMessageIter
2086 * The easiest way to iterate is like this:
2088 * dbus_message_iter_init (message, &iter);
2089 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2090 * dbus_message_iter_next (&iter);
2093 * #DBusMessageIter contains no allocated memory; it need not be
2094 * freed, and can be copied by assignment or memcpy().
2096 * @param message the message
2097 * @param iter pointer to an iterator to initialize
2098 * @returns #FALSE if the message has no arguments
2101 dbus_message_iter_init (DBusMessage *message,
2102 DBusMessageIter *iter)
2104 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2105 const DBusString *type_str;
2108 _dbus_return_val_if_fail (message != NULL, FALSE);
2109 _dbus_return_val_if_fail (iter != NULL, FALSE);
2111 get_const_signature (&message->header, &type_str, &type_pos);
2113 _dbus_message_iter_init_common (message, real,
2114 DBUS_MESSAGE_ITER_TYPE_READER);
2116 _dbus_type_reader_init (&real->u.reader,
2117 _dbus_header_get_byte_order (&message->header),
2122 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
2126 * Checks if an iterator has any more fields.
2128 * @param iter the message iter
2129 * @returns #TRUE if there are more fields following
2132 dbus_message_iter_has_next (DBusMessageIter *iter)
2134 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2136 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2137 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2139 return _dbus_type_reader_has_next (&real->u.reader);
2143 * Moves the iterator to the next field, if any. If there's no next
2144 * field, returns #FALSE. If the iterator moves forward, returns
2147 * @param iter the message iter
2148 * @returns #TRUE if the iterator was moved to the next field
2151 dbus_message_iter_next (DBusMessageIter *iter)
2153 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2155 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2156 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2158 return _dbus_type_reader_next (&real->u.reader);
2162 * Returns the argument type of the argument that the message iterator
2163 * points to. If the iterator is at the end of the message, returns
2164 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
2167 * dbus_message_iter_init (message, &iter);
2168 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2169 * dbus_message_iter_next (&iter);
2172 * @param iter the message iter
2173 * @returns the argument type
2176 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
2178 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2180 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2181 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2183 return _dbus_type_reader_get_current_type (&real->u.reader);
2187 * Returns the element type of the array that the message iterator
2188 * points to. Note that you need to check that the iterator points to
2189 * an array prior to using this function.
2191 * @param iter the message iter
2192 * @returns the array element type
2195 dbus_message_iter_get_element_type (DBusMessageIter *iter)
2197 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2199 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2200 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
2201 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
2203 return _dbus_type_reader_get_element_type (&real->u.reader);
2207 * Recurses into a container value when reading values from a message,
2208 * initializing a sub-iterator to use for traversing the child values
2211 * Note that this recurses into a value, not a type, so you can only
2212 * recurse if the value exists. The main implication of this is that
2213 * if you have for example an empty array of array of int32, you can
2214 * recurse into the outermost array, but it will have no values, so
2215 * you won't be able to recurse further. There's no array of int32 to
2218 * If a container is an array of fixed-length types (except Unix file
2219 * descriptors), it is much more efficient to use
2220 * dbus_message_iter_get_fixed_array() to get the whole array in one
2221 * shot, rather than individually walking over the array elements.
2223 * Be sure you have somehow checked that
2224 * dbus_message_iter_get_arg_type() matches the type you are expecting
2225 * to recurse into. Results of this function are undefined if there is
2226 * no container to recurse into at the current iterator position.
2228 * @param iter the message iterator
2229 * @param sub the sub-iterator to initialize
2232 dbus_message_iter_recurse (DBusMessageIter *iter,
2233 DBusMessageIter *sub)
2235 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2236 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2238 _dbus_return_if_fail (_dbus_message_iter_check (real));
2239 _dbus_return_if_fail (sub != NULL);
2242 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
2246 * Returns the current signature of a message iterator. This
2247 * is useful primarily for dealing with variants; one can
2248 * recurse into a variant and determine the signature of
2249 * the variant's value.
2251 * The returned string must be freed with dbus_free().
2253 * @param iter the message iterator
2254 * @returns the contained signature, or NULL if out of memory
2257 dbus_message_iter_get_signature (DBusMessageIter *iter)
2259 const DBusString *sig;
2263 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2265 _dbus_return_val_if_fail (_dbus_message_iter_check (real), NULL);
2267 if (!_dbus_string_init (&retstr))
2270 _dbus_type_reader_get_signature (&real->u.reader, &sig,
2272 if (!_dbus_string_append_len (&retstr,
2273 _dbus_string_get_const_data (sig) + start,
2276 if (!_dbus_string_steal_data (&retstr, &ret))
2278 _dbus_string_free (&retstr);
2283 * Reads a basic-typed value from the message iterator.
2284 * Basic types are the non-containers such as integer and string.
2286 * The value argument should be the address of a location to store
2287 * the returned value. So for int32 it should be a "dbus_int32_t*"
2288 * and for string a "const char**". The returned value is
2289 * by reference and should not be freed.
2291 * This call duplicates Unix file descriptors when reading them. It is
2292 * your job to close them when you don't need them anymore.
2294 * Unix file descriptors that are read with this function will have
2295 * the FD_CLOEXEC flag set. If you need them without this flag set,
2296 * make sure to unset it with fcntl().
2298 * Be sure you have somehow checked that
2299 * dbus_message_iter_get_arg_type() matches the type you are
2300 * expecting, or you'll crash when you try to use an integer as a
2301 * string or something.
2303 * To read any container type (array, struct, dict) you will need to
2304 * recurse into the container with dbus_message_iter_recurse(). If
2305 * the container is an array of fixed-length values (except Unix file
2306 * descriptors), you can get all the array elements at once with
2307 * dbus_message_iter_get_fixed_array(). Otherwise, you have to iterate
2308 * over the container's contents one value at a time.
2310 * All basic-typed values are guaranteed to fit in a #DBusBasicValue,
2311 * so in versions of libdbus that have that type, you can write code like this:
2314 * DBusBasicValue value;
2316 * dbus_message_iter_get_basic (&read_iter, &value);
2317 * type = dbus_message_iter_get_arg_type (&read_iter);
2318 * dbus_message_iter_append_basic (&write_iter, type, &value);
2321 * (All D-Bus basic types are either numeric and 8 bytes or smaller, or
2322 * behave like a string; so in older versions of libdbus, DBusBasicValue
2323 * can be replaced with union { char *string; unsigned char bytes[8]; },
2326 * @param iter the iterator
2327 * @param value location to store the value
2330 dbus_message_iter_get_basic (DBusMessageIter *iter,
2333 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2335 _dbus_return_if_fail (_dbus_message_iter_check (real));
2336 _dbus_return_if_fail (value != NULL);
2338 if (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_UNIX_FD)
2340 #ifdef HAVE_UNIX_FD_PASSING
2343 _dbus_type_reader_read_basic(&real->u.reader, &idx);
2345 if (idx.u32 >= real->message->n_unix_fds) {
2346 /* Hmm, we cannot really signal an error here, so let's make
2347 sure to return an invalid fd. */
2348 *((int*) value) = -1;
2352 *((int*) value) = _dbus_dup(real->message->unix_fds[idx.u32], NULL);
2354 *((int*) value) = -1;
2359 _dbus_type_reader_read_basic (&real->u.reader,
2365 * Returns the number of elements in the array-typed value pointed
2366 * to by the iterator.
2367 * Note that this function is O(1) for arrays of fixed-size types
2368 * but O(n) for arrays of variable-length types such as strings,
2369 * so it may be a bad idea to use it.
2371 * @param iter the iterator
2372 * @returns the number of elements in the array
2375 dbus_message_iter_get_element_count (DBusMessageIter *iter)
2377 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2378 DBusTypeReader array;
2382 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2383 _dbus_return_val_if_fail (_dbus_type_reader_get_current_type (&real->u.reader)
2384 == DBUS_TYPE_ARRAY, 0);
2386 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
2387 _dbus_type_reader_recurse (&real->u.reader, &array);
2388 if (dbus_type_is_fixed (element_type))
2390 int alignment = _dbus_type_get_alignment (element_type);
2391 int total_len = _dbus_type_reader_get_array_length (&array);
2392 n_elements = total_len / alignment;
2396 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
2399 _dbus_type_reader_next (&array);
2407 * Returns the number of bytes in the array as marshaled in the wire
2408 * protocol. The iterator must currently be inside an array-typed
2411 * This function is deprecated on the grounds that it is stupid. Why
2412 * would you want to know how many bytes are in the array as marshaled
2413 * in the wire protocol? Use dbus_message_iter_get_element_count() instead.
2415 * @param iter the iterator
2416 * @returns the number of bytes in the array
2419 dbus_message_iter_get_array_len (DBusMessageIter *iter)
2421 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2423 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2425 return _dbus_type_reader_get_array_length (&real->u.reader);
2429 * Reads a block of fixed-length values from the message iterator.
2430 * Fixed-length values are those basic types that are not string-like,
2431 * such as integers, bool, double. The returned block will be from the
2432 * current position in the array until the end of the array.
2434 * There is one exception here: although DBUS_TYPE_UNIX_FD is
2435 * considered a 'fixed' type arrays of this type may not be read with
2438 * The message iter should be "in" the array (that is, you recurse into the
2439 * array, and then you call dbus_message_iter_get_fixed_array() on the
2440 * "sub-iterator" created by dbus_message_iter_recurse()).
2442 * The value argument should be the address of a location to store the
2443 * returned array. So for int32 it should be a "const dbus_int32_t**"
2444 * The returned value is by reference and should not be freed.
2446 * This function should only be used if dbus_type_is_fixed() returns
2447 * #TRUE for the element type.
2449 * If an array's elements are not fixed in size, you have to recurse
2450 * into the array with dbus_message_iter_recurse() and read the
2451 * elements one by one.
2453 * Because the array is not copied, this function runs in constant
2454 * time and is fast; it's much preferred over walking the entire array
2455 * with an iterator. (However, you can always use
2456 * dbus_message_iter_recurse(), even for fixed-length types;
2457 * dbus_message_iter_get_fixed_array() is just an optimization.)
2459 * @param iter the iterator
2460 * @param value location to store the block
2461 * @param n_elements number of elements in the block
2464 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
2468 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2469 #ifndef DBUS_DISABLE_CHECKS
2470 int subtype = _dbus_type_reader_get_current_type(&real->u.reader);
2472 _dbus_return_if_fail (_dbus_message_iter_check (real));
2473 _dbus_return_if_fail (value != NULL);
2474 _dbus_return_if_fail ((subtype == DBUS_TYPE_INVALID) ||
2475 (dbus_type_is_fixed (subtype) && subtype != DBUS_TYPE_UNIX_FD));
2478 _dbus_type_reader_read_fixed_multi (&real->u.reader,
2483 * Initializes a #DBusMessageIter for appending arguments to the end
2486 * @todo If appending any of the arguments fails due to lack of
2487 * memory, the message is hosed and you have to start over building
2488 * the whole message.
2490 * @param message the message
2491 * @param iter pointer to an iterator to initialize
2494 dbus_message_iter_init_append (DBusMessage *message,
2495 DBusMessageIter *iter)
2497 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2499 _dbus_return_if_fail (message != NULL);
2500 _dbus_return_if_fail (iter != NULL);
2502 _dbus_message_iter_init_common (message, real,
2503 DBUS_MESSAGE_ITER_TYPE_WRITER);
2505 /* We create the signature string and point iterators at it "on demand"
2506 * when a value is actually appended. That means that init() never fails
2509 _dbus_type_writer_init_types_delayed (&real->u.writer,
2510 _dbus_header_get_byte_order (&message->header),
2512 _dbus_string_get_length (&message->body));
2516 * Creates a temporary signature string containing the current
2517 * signature, stores it in the iterator, and points the iterator to
2518 * the end of it. Used any time we write to the message.
2520 * @param real an iterator without a type_str
2521 * @returns #FALSE if no memory
2524 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
2527 const DBusString *current_sig;
2528 int current_sig_pos;
2530 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2532 if (real->u.writer.type_str != NULL)
2534 _dbus_assert (real->sig_refcount > 0);
2535 real->sig_refcount += 1;
2539 str = dbus_new (DBusString, 1);
2543 if (!_dbus_header_get_field_raw (&real->message->header,
2544 DBUS_HEADER_FIELD_SIGNATURE,
2545 ¤t_sig, ¤t_sig_pos))
2552 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
2553 current_sig_pos += 1; /* move on to sig data */
2555 if (!_dbus_string_init_preallocated (str, current_len + 4))
2561 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
2564 _dbus_string_free (str);
2571 if (!_dbus_string_init_preallocated (str, 4))
2578 real->sig_refcount = 1;
2580 _dbus_type_writer_add_types (&real->u.writer,
2581 str, _dbus_string_get_length (str));
2586 * Sets the new signature as the message signature, frees the
2587 * signature string, and marks the iterator as not having a type_str
2588 * anymore. Frees the signature even if it fails, so you can't
2589 * really recover from failure. Kinda busted.
2591 * @param real an iterator without a type_str
2592 * @returns #FALSE if no memory
2595 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2598 const char *v_STRING;
2601 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2602 _dbus_assert (real->u.writer.type_str != NULL);
2603 _dbus_assert (real->sig_refcount > 0);
2605 real->sig_refcount -= 1;
2607 if (real->sig_refcount > 0)
2609 _dbus_assert (real->sig_refcount == 0);
2613 str = real->u.writer.type_str;
2615 v_STRING = _dbus_string_get_const_data (str);
2616 if (!_dbus_header_set_field_basic (&real->message->header,
2617 DBUS_HEADER_FIELD_SIGNATURE,
2618 DBUS_TYPE_SIGNATURE,
2622 _dbus_type_writer_remove_types (&real->u.writer);
2623 _dbus_string_free (str);
2630 * Frees the signature string and marks the iterator as not having a
2631 * type_str anymore. Since the new signature is not set, the message
2632 * will generally be hosed after this is called.
2634 * @param real an iterator without a type_str
2637 _dbus_message_iter_abandon_signature (DBusMessageRealIter *real)
2641 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2642 _dbus_assert (real->u.writer.type_str != NULL);
2643 _dbus_assert (real->sig_refcount > 0);
2645 real->sig_refcount -= 1;
2647 if (real->sig_refcount > 0)
2649 _dbus_assert (real->sig_refcount == 0);
2651 str = real->u.writer.type_str;
2653 _dbus_type_writer_remove_types (&real->u.writer);
2654 _dbus_string_free (str);
2658 #ifndef DBUS_DISABLE_CHECKS
2660 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2662 if (!_dbus_message_iter_check (iter))
2665 if (iter->message->locked)
2667 _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)\n");
2673 #endif /* DBUS_DISABLE_CHECKS */
2675 #ifdef HAVE_UNIX_FD_PASSING
2677 expand_fd_array(DBusMessage *m,
2682 /* This makes space for adding n new fds to the array and returns a
2683 pointer to the place were the first fd should be put. */
2685 if (m->n_unix_fds + n > m->n_unix_fds_allocated)
2690 /* Make twice as much space as necessary */
2691 k = (m->n_unix_fds + n) * 2;
2693 /* Allocate at least four */
2697 p = dbus_realloc(m->unix_fds, k * sizeof(int));
2702 m->n_unix_fds_allocated = k;
2705 return m->unix_fds + m->n_unix_fds;
2710 * Appends a basic-typed value to the message. The basic types are the
2711 * non-container types such as integer and string.
2713 * The "value" argument should be the address of a basic-typed value.
2714 * So for string, const char**. For integer, dbus_int32_t*.
2716 * For Unix file descriptors this function will internally duplicate
2717 * the descriptor you passed in. Hence you may close the descriptor
2718 * immediately after this call.
2720 * @todo If this fails due to lack of memory, the message is hosed and
2721 * you have to start over building the whole message.
2723 * @param iter the append iterator
2724 * @param type the type of the value
2725 * @param value the address of the value
2726 * @returns #FALSE if not enough memory
2729 dbus_message_iter_append_basic (DBusMessageIter *iter,
2733 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2736 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2737 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2738 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2739 _dbus_return_val_if_fail (value != NULL, FALSE);
2741 #ifndef DBUS_DISABLE_CHECKS
2744 const char * const *string_p;
2745 const dbus_bool_t *bool_p;
2747 case DBUS_TYPE_STRING:
2749 _dbus_return_val_if_fail (_dbus_check_is_valid_utf8 (*string_p), FALSE);
2752 case DBUS_TYPE_OBJECT_PATH:
2754 _dbus_return_val_if_fail (_dbus_check_is_valid_path (*string_p), FALSE);
2757 case DBUS_TYPE_SIGNATURE:
2759 _dbus_return_val_if_fail (_dbus_check_is_valid_signature (*string_p), FALSE);
2762 case DBUS_TYPE_BOOLEAN:
2764 _dbus_return_val_if_fail (*bool_p == 0 || *bool_p == 1, FALSE);
2769 /* nothing to check, all possible values are allowed */
2774 if (!_dbus_message_iter_open_signature (real))
2777 if (type == DBUS_TYPE_UNIX_FD)
2779 #ifdef HAVE_UNIX_FD_PASSING
2783 /* First step, include the fd in the fd list of this message */
2784 if (!(fds = expand_fd_array(real->message, 1)))
2787 *fds = _dbus_dup(*(int*) value, NULL);
2791 u = real->message->n_unix_fds;
2793 /* Second step, write the index to the fd */
2794 if (!(ret = _dbus_type_writer_write_basic (&real->u.writer, DBUS_TYPE_UNIX_FD, &u))) {
2795 _dbus_close(*fds, NULL);
2799 real->message->n_unix_fds += 1;
2802 /* Final step, update the header accordingly */
2803 ret = _dbus_header_set_field_basic (&real->message->header,
2804 DBUS_HEADER_FIELD_UNIX_FDS,
2808 /* If any of these operations fail the message is
2809 hosed. However, no memory or fds should be leaked since what
2810 has been added to message has been added to the message, and
2811 can hence be accounted for when the message is being
2819 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
2822 if (!_dbus_message_iter_close_signature (real))
2829 * Appends a block of fixed-length values to an array. The
2830 * fixed-length types are all basic types that are not string-like. So
2831 * int32, double, bool, etc. (Unix file descriptors however are not
2832 * supported.) You must call dbus_message_iter_open_container() to
2833 * open an array of values before calling this function. You may call
2834 * this function multiple times (and intermixed with calls to
2835 * dbus_message_iter_append_basic()) for the same array.
2837 * The "value" argument should be the address of the array. So for
2838 * integer, "dbus_int32_t**" is expected for example.
2840 * @warning in C, given "int array[]", "&array == array" (the
2841 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2842 * So if you're using an array instead of a pointer you have to create
2843 * a pointer variable, assign the array to it, then take the address
2844 * of the pointer variable.
2846 * const dbus_int32_t array[] = { 1, 2, 3 };
2847 * const dbus_int32_t *v_ARRAY = array;
2848 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
2849 * fprintf (stderr, "No memory!\n");
2851 * For strings it works to write const char *array = "Hello" and then
2852 * use &array though.
2854 * @todo If this fails due to lack of memory, the message is hosed and
2855 * you have to start over building the whole message.
2857 * @param iter the append iterator
2858 * @param element_type the type of the array elements
2859 * @param value the address of the array
2860 * @param n_elements the number of elements to append
2861 * @returns #FALSE if not enough memory
2864 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
2869 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2872 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2873 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2874 _dbus_return_val_if_fail (dbus_type_is_fixed (element_type) && element_type != DBUS_TYPE_UNIX_FD, FALSE);
2875 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
2876 _dbus_return_val_if_fail (value != NULL, FALSE);
2877 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
2878 _dbus_return_val_if_fail (n_elements <=
2879 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
2882 #ifndef DBUS_DISABLE_CHECKS
2883 if (element_type == DBUS_TYPE_BOOLEAN)
2885 const dbus_bool_t * const *bools = value;
2888 for (i = 0; i < n_elements; i++)
2890 _dbus_return_val_if_fail ((*bools)[i] == 0 || (*bools)[i] == 1, FALSE);
2895 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
2901 * Appends a container-typed value to the message; you are required to
2902 * append the contents of the container using the returned
2903 * sub-iterator, and then call
2904 * dbus_message_iter_close_container(). Container types are for
2905 * example struct, variant, and array. For variants, the
2906 * contained_signature should be the type of the single value inside
2907 * the variant. For structs and dict entries, contained_signature
2908 * should be #NULL; it will be set to whatever types you write into
2909 * the struct. For arrays, contained_signature should be the type of
2910 * the array elements.
2912 * @todo If this fails due to lack of memory, the message is hosed and
2913 * you have to start over building the whole message.
2915 * @param iter the append iterator
2916 * @param type the type of the value
2917 * @param contained_signature the type of container contents
2918 * @param sub sub-iterator to initialize
2919 * @returns #FALSE if not enough memory
2922 dbus_message_iter_open_container (DBusMessageIter *iter,
2924 const char *contained_signature,
2925 DBusMessageIter *sub)
2927 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2928 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2929 DBusString contained_str;
2931 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2932 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2933 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
2934 _dbus_return_val_if_fail (sub != NULL, FALSE);
2935 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
2936 contained_signature == NULL) ||
2937 (type == DBUS_TYPE_DICT_ENTRY &&
2938 contained_signature == NULL) ||
2939 (type == DBUS_TYPE_VARIANT &&
2940 contained_signature != NULL) ||
2941 (type == DBUS_TYPE_ARRAY &&
2942 contained_signature != NULL), FALSE);
2944 /* this would fail if the contained_signature is a dict entry, since
2945 * dict entries are invalid signatures standalone (they must be in
2948 _dbus_return_val_if_fail ((type == DBUS_TYPE_ARRAY && contained_signature && *contained_signature == DBUS_DICT_ENTRY_BEGIN_CHAR) ||
2949 (contained_signature == NULL ||
2950 _dbus_check_is_valid_signature (contained_signature)),
2953 if (!_dbus_message_iter_open_signature (real))
2958 if (contained_signature != NULL)
2960 _dbus_string_init_const (&contained_str, contained_signature);
2962 return _dbus_type_writer_recurse (&real->u.writer,
2965 &real_sub->u.writer);
2969 return _dbus_type_writer_recurse (&real->u.writer,
2972 &real_sub->u.writer);
2978 * Closes a container-typed value appended to the message; may write
2979 * out more information to the message known only after the entire
2980 * container is written, and may free resources created by
2981 * dbus_message_iter_open_container().
2983 * @todo If this fails due to lack of memory, the message is hosed and
2984 * you have to start over building the whole message.
2986 * @param iter the append iterator
2987 * @param sub sub-iterator to close
2988 * @returns #FALSE if not enough memory
2991 dbus_message_iter_close_container (DBusMessageIter *iter,
2992 DBusMessageIter *sub)
2994 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2995 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2998 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2999 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
3000 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
3001 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
3003 ret = _dbus_type_writer_unrecurse (&real->u.writer,
3004 &real_sub->u.writer);
3006 if (!_dbus_message_iter_close_signature (real))
3013 * Abandons creation of a contained-typed value and frees resources created
3014 * by dbus_message_iter_open_container(). Once this returns, the message
3015 * is hosed and you have to start over building the whole message.
3017 * This should only be used to abandon creation of a message when you have
3020 * @param iter the append iterator
3021 * @param sub sub-iterator to close
3024 dbus_message_iter_abandon_container (DBusMessageIter *iter,
3025 DBusMessageIter *sub)
3027 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
3028 #ifndef DBUS_DISABLE_CHECKS
3029 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
3031 _dbus_return_if_fail (_dbus_message_iter_append_check (real));
3032 _dbus_return_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
3033 _dbus_return_if_fail (_dbus_message_iter_append_check (real_sub));
3034 _dbus_return_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
3037 _dbus_message_iter_abandon_signature (real);
3041 * Sets a flag indicating that the message does not want a reply; if
3042 * this flag is set, the other end of the connection may (but is not
3043 * required to) optimize by not sending method return or error
3044 * replies. If this flag is set, there is no way to know whether the
3045 * message successfully arrived at the remote end. Normally you know a
3046 * message was received when you receive the reply to it.
3048 * The flag is #FALSE by default, that is by default the other end is
3049 * required to reply.
3051 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
3053 * @param message the message
3054 * @param no_reply #TRUE if no reply is desired
3057 dbus_message_set_no_reply (DBusMessage *message,
3058 dbus_bool_t no_reply)
3060 _dbus_return_if_fail (message != NULL);
3061 _dbus_return_if_fail (!message->locked);
3063 _dbus_header_toggle_flag (&message->header,
3064 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
3069 * Returns #TRUE if the message does not expect
3072 * @param message the message
3073 * @returns #TRUE if the message sender isn't waiting for a reply
3076 dbus_message_get_no_reply (DBusMessage *message)
3078 _dbus_return_val_if_fail (message != NULL, FALSE);
3080 return _dbus_header_get_flag (&message->header,
3081 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
3085 * Sets a flag indicating that an owner for the destination name will
3086 * be automatically started before the message is delivered. When this
3087 * flag is set, the message is held until a name owner finishes
3088 * starting up, or fails to start up. In case of failure, the reply
3091 * The flag is set to #TRUE by default, i.e. auto starting is the default.
3093 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
3095 * @param message the message
3096 * @param auto_start #TRUE if auto-starting is desired
3099 dbus_message_set_auto_start (DBusMessage *message,
3100 dbus_bool_t auto_start)
3102 _dbus_return_if_fail (message != NULL);
3103 _dbus_return_if_fail (!message->locked);
3105 _dbus_header_toggle_flag (&message->header,
3106 DBUS_HEADER_FLAG_NO_AUTO_START,
3111 * Returns #TRUE if the message will cause an owner for
3112 * destination name to be auto-started.
3114 * @param message the message
3115 * @returns #TRUE if the message will use auto-start
3118 dbus_message_get_auto_start (DBusMessage *message)
3120 _dbus_return_val_if_fail (message != NULL, FALSE);
3122 return !_dbus_header_get_flag (&message->header,
3123 DBUS_HEADER_FLAG_NO_AUTO_START);
3128 * Sets the object path this message is being sent to (for
3129 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
3130 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
3132 * The path must contain only valid characters as defined
3133 * in the D-Bus specification.
3135 * @param message the message
3136 * @param object_path the path or #NULL to unset
3137 * @returns #FALSE if not enough memory
3140 dbus_message_set_path (DBusMessage *message,
3141 const char *object_path)
3143 _dbus_return_val_if_fail (message != NULL, FALSE);
3144 _dbus_return_val_if_fail (!message->locked, FALSE);
3145 _dbus_return_val_if_fail (object_path == NULL ||
3146 _dbus_check_is_valid_path (object_path),
3149 return set_or_delete_string_field (message,
3150 DBUS_HEADER_FIELD_PATH,
3151 DBUS_TYPE_OBJECT_PATH,
3156 * Gets the object path this message is being sent to (for
3157 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
3158 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3160 * See also dbus_message_get_path_decomposed().
3162 * The returned string becomes invalid if the message is
3163 * modified, since it points into the wire-marshaled message data.
3165 * @param message the message
3166 * @returns the path (should not be freed) or #NULL
3169 dbus_message_get_path (DBusMessage *message)
3173 _dbus_return_val_if_fail (message != NULL, NULL);
3175 v = NULL; /* in case field doesn't exist */
3176 _dbus_header_get_field_basic (&message->header,
3177 DBUS_HEADER_FIELD_PATH,
3178 DBUS_TYPE_OBJECT_PATH,
3184 * Checks if the message has a particular object path. The object
3185 * path is the destination object for a method call or the emitting
3186 * object for a signal.
3188 * @param message the message
3189 * @param path the path name
3190 * @returns #TRUE if there is a path field in the header
3193 dbus_message_has_path (DBusMessage *message,
3196 const char *msg_path;
3197 msg_path = dbus_message_get_path (message);
3199 if (msg_path == NULL)
3210 if (strcmp (msg_path, path) == 0)
3217 * Gets the object path this message is being sent to
3218 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3219 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
3220 * format (one array element per path component).
3221 * Free the returned array with dbus_free_string_array().
3223 * An empty but non-NULL path array means the path "/".
3224 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
3225 * and the path "/" becomes { NULL }.
3227 * See also dbus_message_get_path().
3229 * @todo this could be optimized by using the len from the message
3230 * instead of calling strlen() again
3232 * @param message the message
3233 * @param path place to store allocated array of path components; #NULL set here if no path field exists
3234 * @returns #FALSE if no memory to allocate the array
3237 dbus_message_get_path_decomposed (DBusMessage *message,
3242 _dbus_return_val_if_fail (message != NULL, FALSE);
3243 _dbus_return_val_if_fail (path != NULL, FALSE);
3247 v = dbus_message_get_path (message);
3250 if (!_dbus_decompose_path (v, strlen (v),
3258 * Sets the interface this message is being sent to
3259 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
3260 * the interface a signal is being emitted from
3261 * (for DBUS_MESSAGE_TYPE_SIGNAL).
3263 * The interface name must contain only valid characters as defined
3264 * in the D-Bus specification.
3266 * @param message the message
3267 * @param iface the interface or #NULL to unset
3268 * @returns #FALSE if not enough memory
3271 dbus_message_set_interface (DBusMessage *message,
3274 _dbus_return_val_if_fail (message != NULL, FALSE);
3275 _dbus_return_val_if_fail (!message->locked, FALSE);
3276 _dbus_return_val_if_fail (iface == NULL ||
3277 _dbus_check_is_valid_interface (iface),
3280 return set_or_delete_string_field (message,
3281 DBUS_HEADER_FIELD_INTERFACE,
3287 * Gets the interface this message is being sent to
3288 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3289 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
3290 * The interface name is fully-qualified (namespaced).
3291 * Returns #NULL if none.
3293 * The returned string becomes invalid if the message is
3294 * modified, since it points into the wire-marshaled message data.
3296 * @param message the message
3297 * @returns the message interface (should not be freed) or #NULL
3300 dbus_message_get_interface (DBusMessage *message)
3304 _dbus_return_val_if_fail (message != NULL, NULL);
3306 v = NULL; /* in case field doesn't exist */
3307 _dbus_header_get_field_basic (&message->header,
3308 DBUS_HEADER_FIELD_INTERFACE,
3315 * Checks if the message has an interface
3317 * @param message the message
3318 * @param iface the interface name
3319 * @returns #TRUE if the interface field in the header matches
3322 dbus_message_has_interface (DBusMessage *message,
3325 const char *msg_interface;
3326 msg_interface = dbus_message_get_interface (message);
3328 if (msg_interface == NULL)
3339 if (strcmp (msg_interface, iface) == 0)
3347 * Sets the interface member being invoked
3348 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3349 * (DBUS_MESSAGE_TYPE_SIGNAL).
3351 * The member name must contain only valid characters as defined
3352 * in the D-Bus specification.
3354 * @param message the message
3355 * @param member the member or #NULL to unset
3356 * @returns #FALSE if not enough memory
3359 dbus_message_set_member (DBusMessage *message,
3362 _dbus_return_val_if_fail (message != NULL, FALSE);
3363 _dbus_return_val_if_fail (!message->locked, FALSE);
3364 _dbus_return_val_if_fail (member == NULL ||
3365 _dbus_check_is_valid_member (member),
3368 return set_or_delete_string_field (message,
3369 DBUS_HEADER_FIELD_MEMBER,
3375 * Gets the interface member being invoked
3376 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3377 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3379 * The returned string becomes invalid if the message is
3380 * modified, since it points into the wire-marshaled message data.
3382 * @param message the message
3383 * @returns the member name (should not be freed) or #NULL
3386 dbus_message_get_member (DBusMessage *message)
3390 _dbus_return_val_if_fail (message != NULL, NULL);
3392 v = NULL; /* in case field doesn't exist */
3393 _dbus_header_get_field_basic (&message->header,
3394 DBUS_HEADER_FIELD_MEMBER,
3401 * Checks if the message has an interface member
3403 * @param message the message
3404 * @param member the member name
3405 * @returns #TRUE if there is a member field in the header
3408 dbus_message_has_member (DBusMessage *message,
3411 const char *msg_member;
3412 msg_member = dbus_message_get_member (message);
3414 if (msg_member == NULL)
3425 if (strcmp (msg_member, member) == 0)
3433 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
3434 * The name is fully-qualified (namespaced).
3436 * The error name must contain only valid characters as defined
3437 * in the D-Bus specification.
3439 * @param message the message
3440 * @param error_name the name or #NULL to unset
3441 * @returns #FALSE if not enough memory
3444 dbus_message_set_error_name (DBusMessage *message,
3445 const char *error_name)
3447 _dbus_return_val_if_fail (message != NULL, FALSE);
3448 _dbus_return_val_if_fail (!message->locked, FALSE);
3449 _dbus_return_val_if_fail (error_name == NULL ||
3450 _dbus_check_is_valid_error_name (error_name),
3453 return set_or_delete_string_field (message,
3454 DBUS_HEADER_FIELD_ERROR_NAME,
3460 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
3463 * The returned string becomes invalid if the message is
3464 * modified, since it points into the wire-marshaled message data.
3466 * @param message the message
3467 * @returns the error name (should not be freed) or #NULL
3470 dbus_message_get_error_name (DBusMessage *message)
3474 _dbus_return_val_if_fail (message != NULL, NULL);
3476 v = NULL; /* in case field doesn't exist */
3477 _dbus_header_get_field_basic (&message->header,
3478 DBUS_HEADER_FIELD_ERROR_NAME,
3485 * Sets the message's destination. The destination is the name of
3486 * another connection on the bus and may be either the unique name
3487 * assigned by the bus to each connection, or a well-known name
3488 * specified in advance.
3490 * The destination name must contain only valid characters as defined
3491 * in the D-Bus specification.
3493 * @param message the message
3494 * @param destination the destination name or #NULL to unset
3495 * @returns #FALSE if not enough memory
3498 dbus_message_set_destination (DBusMessage *message,
3499 const char *destination)
3501 _dbus_return_val_if_fail (message != NULL, FALSE);
3502 _dbus_return_val_if_fail (!message->locked, FALSE);
3503 _dbus_return_val_if_fail (destination == NULL ||
3504 _dbus_check_is_valid_bus_name (destination),
3507 return set_or_delete_string_field (message,
3508 DBUS_HEADER_FIELD_DESTINATION,
3514 * Gets the destination of a message or #NULL if there is none set.
3516 * The returned string becomes invalid if the message is
3517 * modified, since it points into the wire-marshaled message data.
3519 * @param message the message
3520 * @returns the message destination (should not be freed) or #NULL
3523 dbus_message_get_destination (DBusMessage *message)
3527 _dbus_return_val_if_fail (message != NULL, NULL);
3529 v = NULL; /* in case field doesn't exist */
3530 _dbus_header_get_field_basic (&message->header,
3531 DBUS_HEADER_FIELD_DESTINATION,
3538 * Sets the message sender.
3540 * The sender must be a valid bus name as defined in the D-Bus
3543 * Usually you don't want to call this. The message bus daemon will
3544 * call it to set the origin of each message. If you aren't implementing
3545 * a message bus daemon you shouldn't need to set the sender.
3547 * @param message the message
3548 * @param sender the sender or #NULL to unset
3549 * @returns #FALSE if not enough memory
3552 dbus_message_set_sender (DBusMessage *message,
3555 _dbus_return_val_if_fail (message != NULL, FALSE);
3556 _dbus_return_val_if_fail (!message->locked, FALSE);
3557 _dbus_return_val_if_fail (sender == NULL ||
3558 _dbus_check_is_valid_bus_name (sender),
3561 return set_or_delete_string_field (message,
3562 DBUS_HEADER_FIELD_SENDER,
3568 * Gets the unique name of the connection which originated this
3569 * message, or #NULL if unknown or inapplicable. The sender is filled
3570 * in by the message bus.
3572 * Note, the returned sender is always the unique bus name.
3573 * Connections may own multiple other bus names, but those
3574 * are not found in the sender field.
3576 * The returned string becomes invalid if the message is
3577 * modified, since it points into the wire-marshaled message data.
3579 * @param message the message
3580 * @returns the unique name of the sender or #NULL
3583 dbus_message_get_sender (DBusMessage *message)
3587 _dbus_return_val_if_fail (message != NULL, NULL);
3589 v = NULL; /* in case field doesn't exist */
3590 _dbus_header_get_field_basic (&message->header,
3591 DBUS_HEADER_FIELD_SENDER,
3598 * Gets the type signature of the message, i.e. the arguments in the
3599 * message payload. The signature includes only "in" arguments for
3600 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
3601 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
3602 * what you might expect (that is, it does not include the signature of the
3603 * entire C++-style method).
3605 * The signature is a string made up of type codes such as
3606 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
3607 * the value of #DBUS_TYPE_INVALID).
3609 * The returned string becomes invalid if the message is
3610 * modified, since it points into the wire-marshaled message data.
3612 * @param message the message
3613 * @returns the type signature
3616 dbus_message_get_signature (DBusMessage *message)
3618 const DBusString *type_str;
3621 _dbus_return_val_if_fail (message != NULL, NULL);
3623 get_const_signature (&message->header, &type_str, &type_pos);
3625 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
3629 _dbus_message_has_type_interface_member (DBusMessage *message,
3636 _dbus_assert (message != NULL);
3637 _dbus_assert (iface != NULL);
3638 _dbus_assert (member != NULL);
3640 if (dbus_message_get_type (message) != type)
3643 /* Optimize by checking the short member name first
3644 * instead of the longer interface name
3647 n = dbus_message_get_member (message);
3649 if (n && strcmp (n, member) == 0)
3651 n = dbus_message_get_interface (message);
3653 if (n == NULL || strcmp (n, iface) == 0)
3661 * Checks whether the message is a method call with the given
3662 * interface and member fields. If the message is not
3663 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
3664 * member field, returns #FALSE. If the interface field is missing,
3665 * then it will be assumed equal to the provided interface. The D-Bus
3666 * protocol allows method callers to leave out the interface name.
3668 * @param message the message
3669 * @param iface the name to check (must not be #NULL)
3670 * @param method the name to check (must not be #NULL)
3672 * @returns #TRUE if the message is the specified method call
3675 dbus_message_is_method_call (DBusMessage *message,
3679 _dbus_return_val_if_fail (message != NULL, FALSE);
3680 _dbus_return_val_if_fail (iface != NULL, FALSE);
3681 _dbus_return_val_if_fail (method != NULL, FALSE);
3682 /* don't check that interface/method are valid since it would be
3683 * expensive, and not catch many common errors
3686 return _dbus_message_has_type_interface_member (message,
3687 DBUS_MESSAGE_TYPE_METHOD_CALL,
3692 * Checks whether the message is a signal with the given interface and
3693 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
3694 * has a different interface or member field, returns #FALSE.
3696 * @param message the message
3697 * @param iface the name to check (must not be #NULL)
3698 * @param signal_name the name to check (must not be #NULL)
3700 * @returns #TRUE if the message is the specified signal
3703 dbus_message_is_signal (DBusMessage *message,
3705 const char *signal_name)
3707 _dbus_return_val_if_fail (message != NULL, FALSE);
3708 _dbus_return_val_if_fail (iface != NULL, FALSE);
3709 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
3710 /* don't check that interface/name are valid since it would be
3711 * expensive, and not catch many common errors
3714 return _dbus_message_has_type_interface_member (message,
3715 DBUS_MESSAGE_TYPE_SIGNAL,
3716 iface, signal_name);
3720 * Checks whether the message is an error reply with the given error
3721 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
3722 * different name, returns #FALSE.
3724 * @param message the message
3725 * @param error_name the name to check (must not be #NULL)
3727 * @returns #TRUE if the message is the specified error
3730 dbus_message_is_error (DBusMessage *message,
3731 const char *error_name)
3735 _dbus_return_val_if_fail (message != NULL, FALSE);
3736 _dbus_return_val_if_fail (error_name != NULL, FALSE);
3737 /* don't check that error_name is valid since it would be expensive,
3738 * and not catch many common errors
3741 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3744 n = dbus_message_get_error_name (message);
3746 if (n && strcmp (n, error_name) == 0)
3753 * Checks whether the message was sent to the given name. If the
3754 * message has no destination specified or has a different
3755 * destination, returns #FALSE.
3757 * @param message the message
3758 * @param name the name to check (must not be #NULL)
3760 * @returns #TRUE if the message has the given destination name
3763 dbus_message_has_destination (DBusMessage *message,
3768 _dbus_return_val_if_fail (message != NULL, FALSE);
3769 _dbus_return_val_if_fail (name != NULL, FALSE);
3770 /* don't check that name is valid since it would be expensive, and
3771 * not catch many common errors
3774 s = dbus_message_get_destination (message);
3776 if (s && strcmp (s, name) == 0)
3783 * Checks whether the message has the given unique name as its sender.
3784 * If the message has no sender specified or has a different sender,
3785 * returns #FALSE. Note that a peer application will always have the
3786 * unique name of the connection as the sender. So you can't use this
3787 * function to see whether a sender owned a well-known name.
3789 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
3792 * @param message the message
3793 * @param name the name to check (must not be #NULL)
3795 * @returns #TRUE if the message has the given sender
3798 dbus_message_has_sender (DBusMessage *message,
3803 _dbus_return_val_if_fail (message != NULL, FALSE);
3804 _dbus_return_val_if_fail (name != NULL, FALSE);
3805 /* don't check that name is valid since it would be expensive, and
3806 * not catch many common errors
3809 s = dbus_message_get_sender (message);
3811 if (s && strcmp (s, name) == 0)
3818 * Checks whether the message has the given signature; see
3819 * dbus_message_get_signature() for more details on what the signature
3822 * @param message the message
3823 * @param signature typecode array
3824 * @returns #TRUE if message has the given signature
3827 dbus_message_has_signature (DBusMessage *message,
3828 const char *signature)
3832 _dbus_return_val_if_fail (message != NULL, FALSE);
3833 _dbus_return_val_if_fail (signature != NULL, FALSE);
3834 /* don't check that signature is valid since it would be expensive,
3835 * and not catch many common errors
3838 s = dbus_message_get_signature (message);
3840 if (s && strcmp (s, signature) == 0)
3847 * Sets a #DBusError based on the contents of the given
3848 * message. The error is only set if the message
3849 * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
3850 * The name of the error is set to the name of the message,
3851 * and the error message is set to the first argument
3852 * if the argument exists and is a string.
3854 * The return value indicates whether the error was set (the error is
3855 * set if and only if the message is an error message). So you can
3856 * check for an error reply and convert it to DBusError in one go:
3858 * if (dbus_set_error_from_message (error, reply))
3864 * @param error the error to set
3865 * @param message the message to set it from
3866 * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
3869 dbus_set_error_from_message (DBusError *error,
3870 DBusMessage *message)
3874 _dbus_return_val_if_fail (message != NULL, FALSE);
3875 _dbus_return_val_if_error_is_set (error, FALSE);
3877 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3881 dbus_message_get_args (message, NULL,
3882 DBUS_TYPE_STRING, &str,
3885 dbus_set_error (error, dbus_message_get_error_name (message),
3886 str ? "%s" : NULL, str);
3892 * Checks whether a message contains unix fds
3894 * @param message the message
3895 * @returns #TRUE if the message contains unix fds
3898 dbus_message_contains_unix_fds(DBusMessage *message)
3900 #ifdef HAVE_UNIX_FD_PASSING
3901 _dbus_assert(message);
3903 return message->n_unix_fds > 0;
3912 * @addtogroup DBusMessageInternals
3918 * The initial buffer size of the message loader.
3920 * @todo this should be based on min header size plus some average
3921 * body size, or something. Or rather, the min header size only, if we
3922 * want to try to read only the header, store that in a DBusMessage,
3923 * then read only the body and store that, etc., depends on
3924 * how we optimize _dbus_message_loader_get_buffer() and what
3925 * the exact message format is.
3927 #define INITIAL_LOADER_DATA_LEN 32
3930 * Creates a new message loader. Returns #NULL if memory can't
3933 * @returns new loader, or #NULL.
3936 _dbus_message_loader_new (void)
3938 DBusMessageLoader *loader;
3940 loader = dbus_new0 (DBusMessageLoader, 1);
3944 loader->refcount = 1;
3946 loader->corrupted = FALSE;
3947 loader->corruption_reason = DBUS_VALID;
3949 /* this can be configured by the app, but defaults to the protocol max */
3950 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
3952 /* We set a very relatively conservative default here since due to how
3953 SCM_RIGHTS works we need to preallocate an fd array of the maximum
3954 number of unix fds we want to receive in advance. A
3955 try-and-reallocate loop is not possible. */
3956 loader->max_message_unix_fds = DBUS_DEFAULT_MESSAGE_UNIX_FDS;
3958 if (!_dbus_string_init (&loader->data))
3964 /* preallocate the buffer for speed, ignore failure */
3965 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
3966 _dbus_string_set_length (&loader->data, 0);
3968 #ifdef HAVE_UNIX_FD_PASSING
3969 loader->unix_fds = NULL;
3970 loader->n_unix_fds = loader->n_unix_fds_allocated = 0;
3971 loader->unix_fds_outstanding = FALSE;
3978 * Increments the reference count of the loader.
3980 * @param loader the loader.
3981 * @returns the loader
3984 _dbus_message_loader_ref (DBusMessageLoader *loader)
3986 loader->refcount += 1;
3992 * Decrements the reference count of the loader and finalizes the
3993 * loader when the count reaches zero.
3995 * @param loader the loader.
3998 _dbus_message_loader_unref (DBusMessageLoader *loader)
4000 loader->refcount -= 1;
4001 if (loader->refcount == 0)
4003 #ifdef HAVE_UNIX_FD_PASSING
4004 close_unix_fds(loader->unix_fds, &loader->n_unix_fds);
4005 dbus_free(loader->unix_fds);
4007 _dbus_list_foreach (&loader->messages,
4008 (DBusForeachFunction) dbus_message_unref,
4010 _dbus_list_clear (&loader->messages);
4011 _dbus_string_free (&loader->data);
4017 * Gets the buffer to use for reading data from the network. Network
4018 * data is read directly into an allocated buffer, which is then used
4019 * in the DBusMessage, to avoid as many extra memcpy's as possible.
4020 * The buffer must always be returned immediately using
4021 * _dbus_message_loader_return_buffer(), even if no bytes are
4022 * successfully read.
4024 * @todo this function can be a lot more clever. For example
4025 * it can probably always return a buffer size to read exactly
4026 * the body of the next message, thus avoiding any memory wastage
4029 * @todo we need to enforce a max length on strings in header fields.
4031 * @param loader the message loader.
4032 * @param buffer the buffer
4035 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
4036 DBusString **buffer)
4038 _dbus_assert (!loader->buffer_outstanding);
4040 *buffer = &loader->data;
4042 loader->buffer_outstanding = TRUE;
4046 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
4047 * indicating to the loader how many bytes of the buffer were filled
4048 * in. This function must always be called, even if no bytes were
4049 * successfully read.
4051 * @param loader the loader.
4052 * @param buffer the buffer.
4055 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
4058 _dbus_assert (loader->buffer_outstanding);
4059 _dbus_assert (buffer == &loader->data);
4061 loader->buffer_outstanding = FALSE;
4065 * Gets the buffer to use for reading unix fds from the network.
4067 * This works similar to _dbus_message_loader_get_buffer()
4069 * @param loader the message loader.
4070 * @param fds the array to read fds into
4071 * @param max_n_fds how many fds to read at most
4072 * @return TRUE on success, FALSE on OOM
4075 _dbus_message_loader_get_unix_fds(DBusMessageLoader *loader,
4077 unsigned *max_n_fds)
4079 #ifdef HAVE_UNIX_FD_PASSING
4080 _dbus_assert (!loader->unix_fds_outstanding);
4082 /* Allocate space where we can put the fds we read. We allocate
4083 space for max_message_unix_fds since this is an
4084 upper limit how many fds can be received within a single
4085 message. Since SCM_RIGHTS doesn't allow a reallocate+retry logic
4086 we are allocating the maximum possible array size right from the
4087 beginning. This sucks a bit, however unless SCM_RIGHTS is fixed
4088 there is no better way. */
4090 if (loader->n_unix_fds_allocated < loader->max_message_unix_fds)
4092 int *a = dbus_realloc(loader->unix_fds,
4093 loader->max_message_unix_fds * sizeof(loader->unix_fds[0]));
4098 loader->unix_fds = a;
4099 loader->n_unix_fds_allocated = loader->max_message_unix_fds;
4102 *fds = loader->unix_fds + loader->n_unix_fds;
4103 *max_n_fds = loader->n_unix_fds_allocated - loader->n_unix_fds;
4105 loader->unix_fds_outstanding = TRUE;
4108 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
4114 * Returns a buffer obtained from _dbus_message_loader_get_unix_fds().
4116 * This works similar to _dbus_message_loader_return_buffer()
4118 * @param loader the message loader.
4119 * @param fds the array fds were read into
4120 * @param n_fds how many fds were read
4124 _dbus_message_loader_return_unix_fds(DBusMessageLoader *loader,
4128 #ifdef HAVE_UNIX_FD_PASSING
4129 _dbus_assert(loader->unix_fds_outstanding);
4130 _dbus_assert(loader->unix_fds + loader->n_unix_fds == fds);
4131 _dbus_assert(loader->n_unix_fds + n_fds <= loader->n_unix_fds_allocated);
4133 loader->n_unix_fds += n_fds;
4134 loader->unix_fds_outstanding = FALSE;
4136 if (n_fds && loader->unix_fds_change)
4137 loader->unix_fds_change (loader->unix_fds_change_data);
4139 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
4144 * FIXME when we move the header out of the buffer, that memmoves all
4145 * buffered messages. Kind of crappy.
4147 * Also we copy the header and body, which is kind of crappy. To
4148 * avoid this, we have to allow header and body to be in a single
4149 * memory block, which is good for messages we read and bad for
4150 * messages we are creating. But we could move_len() the buffer into
4151 * this single memory block, and move_len() will just swap the buffers
4152 * if you're moving the entire buffer replacing the dest string.
4154 * We could also have the message loader tell the transport how many
4155 * bytes to read; so it would first ask for some arbitrary number like
4156 * 256, then if the message was incomplete it would use the
4157 * header/body len to ask for exactly the size of the message (or
4158 * blocks the size of a typical kernel buffer for the socket). That
4159 * way we don't get trailing bytes in the buffer that have to be
4160 * memmoved. Though I suppose we also don't have a chance of reading a
4161 * bunch of small messages at once, so the optimization may be stupid.
4163 * Another approach would be to keep a "start" index into
4164 * loader->data and only delete it occasionally, instead of after
4165 * each message is loaded.
4167 * load_message() returns FALSE if not enough memory OR the loader was corrupted
4170 load_message (DBusMessageLoader *loader,
4171 DBusMessage *message,
4173 int fields_array_len,
4178 DBusValidity validity;
4179 const DBusString *type_str;
4181 DBusValidationMode mode;
4182 dbus_uint32_t n_unix_fds = 0;
4184 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
4189 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
4192 /* 1. VALIDATE AND COPY OVER HEADER */
4193 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
4194 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
4196 if (!_dbus_header_load (&message->header,
4204 _dbus_string_get_length (&loader->data)))
4206 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
4208 /* assert here so we can catch any code that still uses DBUS_VALID to indicate
4209 oom errors. They should use DBUS_VALIDITY_UNKNOWN_OOM_ERROR instead */
4210 _dbus_assert (validity != DBUS_VALID);
4212 if (validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
4216 loader->corrupted = TRUE;
4217 loader->corruption_reason = validity;
4222 _dbus_assert (validity == DBUS_VALID);
4224 /* 2. VALIDATE BODY */
4225 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
4227 get_const_signature (&message->header, &type_str, &type_pos);
4229 /* Because the bytes_remaining arg is NULL, this validates that the
4230 * body is the right length
4232 validity = _dbus_validate_body_with_reason (type_str,
4239 if (validity != DBUS_VALID)
4241 _dbus_verbose ("Failed to validate message body code %d\n", validity);
4243 loader->corrupted = TRUE;
4244 loader->corruption_reason = validity;
4250 /* 3. COPY OVER UNIX FDS */
4251 _dbus_header_get_field_basic(&message->header,
4252 DBUS_HEADER_FIELD_UNIX_FDS,
4256 #ifdef HAVE_UNIX_FD_PASSING
4258 if (n_unix_fds > loader->n_unix_fds)
4260 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
4261 n_unix_fds, loader->n_unix_fds);
4263 loader->corrupted = TRUE;
4264 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4268 /* If this was a recycled message there might still be
4269 some memory allocated for the fds */
4270 dbus_free(message->unix_fds);
4274 message->unix_fds = _dbus_memdup(loader->unix_fds, n_unix_fds * sizeof(message->unix_fds[0]));
4275 if (message->unix_fds == NULL)
4277 _dbus_verbose ("Failed to allocate file descriptor array\n");
4282 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
4283 loader->n_unix_fds -= n_unix_fds;
4284 memmove (loader->unix_fds, loader->unix_fds + n_unix_fds, loader->n_unix_fds * sizeof (loader->unix_fds[0]));
4286 if (loader->unix_fds_change)
4287 loader->unix_fds_change (loader->unix_fds_change_data);
4290 message->unix_fds = NULL;
4296 _dbus_verbose ("Hmm, message claims to come with file descriptors "
4297 "but that's not supported on our platform, disconnecting.\n");
4299 loader->corrupted = TRUE;
4300 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4306 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
4308 if (!_dbus_list_append (&loader->messages, message))
4310 _dbus_verbose ("Failed to append new message to loader queue\n");
4315 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
4316 _dbus_assert (_dbus_string_get_length (&loader->data) >=
4317 (header_len + body_len));
4319 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
4321 _dbus_verbose ("Failed to move body into new message\n");
4326 _dbus_string_delete (&loader->data, 0, header_len + body_len);
4328 /* don't waste more than 2k of memory */
4329 _dbus_string_compact (&loader->data, 2048);
4331 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
4332 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
4334 _dbus_verbose ("Loaded message %p\n", message);
4336 _dbus_assert (!oom);
4337 _dbus_assert (!loader->corrupted);
4338 _dbus_assert (loader->messages != NULL);
4339 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4347 /* does nothing if the message isn't in the list */
4348 _dbus_list_remove_last (&loader->messages, message);
4351 _dbus_assert (!loader->corrupted);
4353 _dbus_assert (loader->corrupted);
4355 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
4361 * Converts buffered data into messages, if we have enough data. If
4362 * we don't have enough data, does nothing.
4364 * @todo we need to check that the proper named header fields exist
4365 * for each message type.
4367 * @todo If a message has unknown type, we should probably eat it
4368 * right here rather than passing it out to applications. However
4369 * it's not an error to see messages of unknown type.
4371 * @param loader the loader.
4372 * @returns #TRUE if we had enough memory to finish.
4375 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
4377 while (!loader->corrupted &&
4378 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
4380 DBusValidity validity;
4381 int byte_order, fields_array_len, header_len, body_len;
4383 if (_dbus_header_have_message_untrusted (loader->max_message_size,
4390 _dbus_string_get_length (&loader->data)))
4392 DBusMessage *message;
4394 _dbus_assert (validity == DBUS_VALID);
4396 message = dbus_message_new_empty_header ();
4397 if (message == NULL)
4400 if (!load_message (loader, message,
4401 byte_order, fields_array_len,
4402 header_len, body_len))
4404 dbus_message_unref (message);
4405 /* load_message() returns false if corrupted or OOM; if
4406 * corrupted then return TRUE for not OOM
4408 return loader->corrupted;
4411 _dbus_assert (loader->messages != NULL);
4412 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4416 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
4418 if (validity != DBUS_VALID)
4420 loader->corrupted = TRUE;
4421 loader->corruption_reason = validity;
4431 * Peeks at first loaded message, returns #NULL if no messages have
4434 * @param loader the loader.
4435 * @returns the next message, or #NULL if none.
4438 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
4440 if (loader->messages)
4441 return loader->messages->data;
4447 * Pops a loaded message (passing ownership of the message
4448 * to the caller). Returns #NULL if no messages have been
4451 * @param loader the loader.
4452 * @returns the next message, or #NULL if none.
4455 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
4457 return _dbus_list_pop_first (&loader->messages);
4461 * Pops a loaded message inside a list link (passing ownership of the
4462 * message and link to the caller). Returns #NULL if no messages have
4465 * @param loader the loader.
4466 * @returns the next message link, or #NULL if none.
4469 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
4471 return _dbus_list_pop_first_link (&loader->messages);
4475 * Returns a popped message link, used to undo a pop.
4477 * @param loader the loader
4478 * @param link the link with a message in it
4481 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
4484 _dbus_list_prepend_link (&loader->messages, link);
4488 * Checks whether the loader is confused due to bad data.
4489 * If messages are received that are invalid, the
4490 * loader gets confused and gives up permanently.
4491 * This state is called "corrupted."
4493 * @param loader the loader
4494 * @returns #TRUE if the loader is hosed.
4497 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
4499 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4500 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4501 return loader->corrupted;
4505 * Checks what kind of bad data confused the loader.
4507 * @param loader the loader
4508 * @returns why the loader is hosed, or DBUS_VALID if it isn't.
4511 _dbus_message_loader_get_corruption_reason (DBusMessageLoader *loader)
4513 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4514 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4516 return loader->corruption_reason;
4520 * Sets the maximum size message we allow.
4522 * @param loader the loader
4523 * @param size the max message size in bytes
4526 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
4529 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
4531 _dbus_verbose ("clamping requested max message size %ld to %d\n",
4532 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
4533 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4535 loader->max_message_size = size;
4539 * Gets the maximum allowed message size in bytes.
4541 * @param loader the loader
4542 * @returns max size in bytes
4545 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
4547 return loader->max_message_size;
4551 * Sets the maximum unix fds per message we allow.
4553 * @param loader the loader
4554 * @param n the max number of unix fds in a message
4557 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader,
4560 if (n > DBUS_MAXIMUM_MESSAGE_UNIX_FDS)
4562 _dbus_verbose ("clamping requested max message unix_fds %ld to %d\n",
4563 n, DBUS_MAXIMUM_MESSAGE_UNIX_FDS);
4564 n = DBUS_MAXIMUM_MESSAGE_UNIX_FDS;
4566 loader->max_message_unix_fds = n;
4570 * Gets the maximum allowed number of unix fds per message
4572 * @param loader the loader
4573 * @returns max unix fds
4576 _dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
4578 return loader->max_message_unix_fds;
4582 * Return how many file descriptors are pending in the loader
4584 * @param loader the loader
4587 _dbus_message_loader_get_pending_fds_count (DBusMessageLoader *loader)
4589 #ifdef HAVE_UNIX_FD_PASSING
4590 return loader->n_unix_fds;
4597 * Register a function to be called whenever the number of pending file
4598 * descriptors in the loader change.
4600 * @param loader the loader
4601 * @param callback the callback
4602 * @param data the data for the callback
4605 _dbus_message_loader_set_pending_fds_function (DBusMessageLoader *loader,
4606 void (* callback) (void *),
4609 #ifdef HAVE_UNIX_FD_PASSING
4610 loader->unix_fds_change = callback;
4611 loader->unix_fds_change_data = data;
4615 static DBusDataSlotAllocator slot_allocator =
4616 _DBUS_DATA_SLOT_ALLOCATOR_INIT (_DBUS_LOCK_NAME (message_slots));
4619 * Allocates an integer ID to be used for storing application-specific
4620 * data on any DBusMessage. The allocated ID may then be used
4621 * with dbus_message_set_data() and dbus_message_get_data().
4622 * The passed-in slot must be initialized to -1, and is filled in
4623 * with the slot ID. If the passed-in slot is not -1, it's assumed
4624 * to be already allocated, and its refcount is incremented.
4626 * The allocated slot is global, i.e. all DBusMessage objects will
4627 * have a slot with the given integer ID reserved.
4629 * @param slot_p address of a global variable storing the slot
4630 * @returns #FALSE on failure (no memory)
4633 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
4635 return _dbus_data_slot_allocator_alloc (&slot_allocator,
4640 * Deallocates a global ID for message data slots.
4641 * dbus_message_get_data() and dbus_message_set_data() may no
4642 * longer be used with this slot. Existing data stored on existing
4643 * DBusMessage objects will be freed when the message is
4644 * finalized, but may not be retrieved (and may only be replaced if
4645 * someone else reallocates the slot). When the refcount on the
4646 * passed-in slot reaches 0, it is set to -1.
4648 * @param slot_p address storing the slot to deallocate
4651 dbus_message_free_data_slot (dbus_int32_t *slot_p)
4653 _dbus_return_if_fail (*slot_p >= 0);
4655 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
4659 * Stores a pointer on a DBusMessage, along
4660 * with an optional function to be used for freeing
4661 * the data when the data is set again, or when
4662 * the message is finalized. The slot number
4663 * must have been allocated with dbus_message_allocate_data_slot().
4665 * @param message the message
4666 * @param slot the slot number
4667 * @param data the data to store
4668 * @param free_data_func finalizer function for the data
4669 * @returns #TRUE if there was enough memory to store the data
4672 dbus_message_set_data (DBusMessage *message,
4675 DBusFreeFunction free_data_func)
4677 DBusFreeFunction old_free_func;
4681 _dbus_return_val_if_fail (message != NULL, FALSE);
4682 _dbus_return_val_if_fail (slot >= 0, FALSE);
4684 retval = _dbus_data_slot_list_set (&slot_allocator,
4685 &message->slot_list,
4686 slot, data, free_data_func,
4687 &old_free_func, &old_data);
4691 /* Do the actual free outside the message lock */
4693 (* old_free_func) (old_data);
4700 * Retrieves data previously set with dbus_message_set_data().
4701 * The slot must still be allocated (must not have been freed).
4703 * @param message the message
4704 * @param slot the slot to get data from
4705 * @returns the data, or #NULL if not found
4708 dbus_message_get_data (DBusMessage *message,
4713 _dbus_return_val_if_fail (message != NULL, NULL);
4715 res = _dbus_data_slot_list_get (&slot_allocator,
4716 &message->slot_list,
4723 * Utility function to convert a machine-readable (not translated)
4724 * string into a D-Bus message type.
4727 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
4728 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
4729 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
4730 * "error" -> DBUS_MESSAGE_TYPE_ERROR
4731 * anything else -> DBUS_MESSAGE_TYPE_INVALID
4736 dbus_message_type_from_string (const char *type_str)
4738 if (strcmp (type_str, "method_call") == 0)
4739 return DBUS_MESSAGE_TYPE_METHOD_CALL;
4740 if (strcmp (type_str, "method_return") == 0)
4741 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
4742 else if (strcmp (type_str, "signal") == 0)
4743 return DBUS_MESSAGE_TYPE_SIGNAL;
4744 else if (strcmp (type_str, "error") == 0)
4745 return DBUS_MESSAGE_TYPE_ERROR;
4747 return DBUS_MESSAGE_TYPE_INVALID;
4751 * Utility function to convert a D-Bus message type into a
4752 * machine-readable string (not translated).
4755 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
4756 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
4757 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
4758 * DBUS_MESSAGE_TYPE_ERROR -> "error"
4759 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
4764 dbus_message_type_to_string (int type)
4768 case DBUS_MESSAGE_TYPE_METHOD_CALL:
4769 return "method_call";
4770 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
4771 return "method_return";
4772 case DBUS_MESSAGE_TYPE_SIGNAL:
4774 case DBUS_MESSAGE_TYPE_ERROR:
4782 * Turn a DBusMessage into the marshalled form as described in the D-Bus
4785 * Generally, this function is only useful for encapsulating D-Bus messages in
4786 * a different protocol.
4788 * @param msg the DBusMessage
4789 * @param marshalled_data_p the location to save the marshalled form to
4790 * @param len_p the location to save the length of the marshalled form to
4791 * @returns #FALSE if there was not enough memory
4794 dbus_message_marshal (DBusMessage *msg,
4795 char **marshalled_data_p,
4799 dbus_bool_t was_locked;
4801 _dbus_return_val_if_fail (msg != NULL, FALSE);
4802 _dbus_return_val_if_fail (marshalled_data_p != NULL, FALSE);
4803 _dbus_return_val_if_fail (len_p != NULL, FALSE);
4805 if (!_dbus_string_init (&tmp))
4808 /* Ensure the message is locked, to ensure the length header is filled in. */
4809 was_locked = msg->locked;
4812 dbus_message_lock (msg);
4814 if (!_dbus_string_copy (&(msg->header.data), 0, &tmp, 0))
4817 *len_p = _dbus_string_get_length (&tmp);
4819 if (!_dbus_string_copy (&(msg->body), 0, &tmp, *len_p))
4822 *len_p = _dbus_string_get_length (&tmp);
4824 if (!_dbus_string_steal_data (&tmp, marshalled_data_p))
4827 _dbus_string_free (&tmp);
4830 msg->locked = FALSE;
4835 _dbus_string_free (&tmp);
4838 msg->locked = FALSE;
4844 * Demarshal a D-Bus message from the format described in the D-Bus
4847 * Generally, this function is only useful for encapsulating D-Bus messages in
4848 * a different protocol.
4850 * @param str the marshalled DBusMessage
4851 * @param len the length of str
4852 * @param error the location to save errors to
4853 * @returns #NULL if there was an error
4856 dbus_message_demarshal (const char *str,
4860 DBusMessageLoader *loader;
4864 _dbus_return_val_if_fail (str != NULL, NULL);
4866 loader = _dbus_message_loader_new ();
4871 _dbus_message_loader_get_buffer (loader, &buffer);
4873 if (!_dbus_string_append_len (buffer, str, len))
4876 _dbus_message_loader_return_buffer (loader, buffer);
4878 if (!_dbus_message_loader_queue_messages (loader))
4881 if (_dbus_message_loader_get_is_corrupted (loader))
4884 msg = _dbus_message_loader_pop_message (loader);
4889 _dbus_message_loader_unref (loader);
4893 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS, "Message is corrupted (%s)",
4894 _dbus_validity_to_error_message (loader->corruption_reason));
4895 _dbus_message_loader_unref (loader);
4899 _DBUS_SET_OOM (error);
4900 _dbus_message_loader_unref (loader);
4905 * Returns the number of bytes required to be in the buffer to demarshal a
4908 * Generally, this function is only useful for encapsulating D-Bus messages in
4909 * a different protocol.
4911 * @param buf data to be marshalled
4912 * @param len the length of @p buf
4913 * @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
4917 dbus_message_demarshal_bytes_needed(const char *buf,
4921 int byte_order, fields_array_len, header_len, body_len;
4922 DBusValidity validity = DBUS_VALID;
4925 if (!buf || len < DBUS_MINIMUM_HEADER_SIZE)
4928 if (len > DBUS_MAXIMUM_MESSAGE_LENGTH)
4929 len = DBUS_MAXIMUM_MESSAGE_LENGTH;
4930 _dbus_string_init_const_len (&str, buf, len);
4932 validity = DBUS_VALID;
4934 = _dbus_header_have_message_untrusted(DBUS_MAXIMUM_MESSAGE_LENGTH,
4935 &validity, &byte_order,
4941 _dbus_string_free (&str);
4943 if (validity == DBUS_VALID)
4945 _dbus_assert (have_message || (header_len + body_len) > len);
4946 (void) have_message; /* unused unless asserting */
4947 return header_len + body_len;
4951 return -1; /* broken! */
4956 * Sets a flag indicating that the caller of the method is prepared
4957 * to wait for interactive authorization to take place (for instance
4958 * via Polkit) before the actual method is processed.
4960 * The flag is #FALSE by default; that is, by default the other end is
4961 * expected to make any authorization decisions non-interactively
4962 * and promptly. It may use the error
4963 * #DBUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED to signal that
4964 * authorization failed, but could have succeeded if this flag had
4967 * For messages whose type is not #DBUS_MESSAGE_TYPE_METHOD_CALL,
4968 * this flag is meaningless and should not be set.
4970 * On the protocol level this toggles
4971 * #DBUS_HEADER_FLAG_ALLOW_INTERACTIVE_AUTHORIZATION.
4973 * @param message the message
4974 * @param allow #TRUE if interactive authorization is acceptable
4977 dbus_message_set_allow_interactive_authorization (DBusMessage *message,
4980 _dbus_return_if_fail (message != NULL);
4981 _dbus_return_if_fail (!message->locked);
4983 _dbus_header_toggle_flag (&message->header,
4984 DBUS_HEADER_FLAG_ALLOW_INTERACTIVE_AUTHORIZATION,
4989 * Returns whether the flag controlled by
4990 * dbus_message_set_allow_interactive_authorization() has been set.
4992 * @param message the message
4995 dbus_message_get_allow_interactive_authorization (DBusMessage *message)
4997 _dbus_return_val_if_fail (message != NULL, FALSE);
4999 return _dbus_header_get_flag (&message->header,
5000 DBUS_HEADER_FLAG_ALLOW_INTERACTIVE_AUTHORIZATION);
5005 /* tests in dbus-message-util.c */