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
6 * Copyright (C) 2015 Samsung Electronics
8 * Licensed under the Academic Free License version 2.1
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License
21 * along with this program; if not, write to the Free Software
22 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
27 #include "dbus-internals.h"
28 #include "dbus-marshal-recursive.h"
29 #include "dbus-marshal-validate.h"
30 #include "dbus-marshal-byteswap.h"
31 #include "dbus-marshal-header.h"
32 #include "dbus-signature.h"
33 #include "dbus-message-private.h"
34 #include "dbus-object-tree.h"
35 #include "dbus-memory.h"
36 #include "dbus-list.h"
37 #include "dbus-threads-internal.h"
38 #ifdef HAVE_UNIX_FD_PASSING
39 #include "dbus-sysdeps.h"
40 #include "dbus-sysdeps-unix.h"
42 #include "dbus-marshal-gvariant.h"
43 #include "dbus-protocol-gvariant.h"
47 #define _DBUS_TYPE_IS_STRINGLIKE(type) \
48 (type == DBUS_TYPE_STRING || type == DBUS_TYPE_SIGNATURE || \
49 type == DBUS_TYPE_OBJECT_PATH)
51 static unsigned char _dbus_default_protocol_version = DBUS_MAJOR_PROTOCOL_VERSION; /* DBUS_PROTOCOL_VERSION_GVARIANT; */
52 static dbus_bool_t _dbus_first_bus_open = FALSE;
54 static void protocol_strategy_last_type (int type);
55 static void protocol_strategy_static (int type);
57 typedef void (*DBusProtocolStrategyFunction)(int type);
58 static DBusProtocolStrategyFunction _dbus_protocol_strategy_bus_function = protocol_strategy_last_type;
59 static DBusProtocolStrategyFunction _dbus_protocol_strategy_message_function = protocol_strategy_static;
61 static void dbus_message_finalize (DBusMessage *message);
64 * @defgroup DBusMessageInternals DBusMessage implementation details
65 * @ingroup DBusInternals
66 * @brief DBusMessage private implementation details.
68 * The guts of DBusMessage and its methods.
73 #ifdef DBUS_ENABLE_EMBEDDED_TESTS
75 _dbus_enable_message_cache (void)
77 static int enabled = -1;
81 const char *s = _dbus_getenv ("DBUS_MESSAGE_CACHE");
92 _dbus_warn ("DBUS_MESSAGE_CACHE should be 0 or 1 if set, not '%s'",
100 /* constant expression, should be optimized away */
101 # define _dbus_enable_message_cache() (TRUE)
104 #ifndef _dbus_message_trace_ref
106 _dbus_message_trace_ref (DBusMessage *message,
111 static int enabled = -1;
113 _dbus_trace_ref ("DBusMessage", message, old_refcount, new_refcount, why,
114 "DBUS_MESSAGE_TRACE", &enabled);
118 /* Not thread locked, but strictly const/read-only so should be OK
120 /** An static string representing an empty signature */
121 _DBUS_STRING_DEFINE_STATIC(_dbus_empty_signature_str, "");
123 /* these have wacky values to help trap uninitialized iterators;
124 * but has to fit in 3 bits
127 DBUS_MESSAGE_ITER_TYPE_READER = 3,
128 DBUS_MESSAGE_ITER_TYPE_WRITER = 7
131 /** typedef for internals of message iterator */
132 typedef struct DBusMessageRealIter DBusMessageRealIter;
134 #define BUILD_BUG_ON(condition) ((void)sizeof(char[1 - 2*!!(condition)]))
137 * @brief Internals of DBusMessageIter
139 * Object representing a position in a message. All fields are internal.
141 struct DBusMessageRealIter
143 DBusMessage *message; /**< Message used */
144 dbus_uint32_t changed_stamp : CHANGED_STAMP_BITS; /**< stamp to detect invalid iters */
145 dbus_uint32_t iter_type : 3; /**< whether this is a reader or writer iter */
146 dbus_uint32_t sig_refcount : 8; /**< depth of open_signature() */
149 DBusTypeWriter writer; /**< writer */
150 DBusTypeReader reader; /**< reader */
151 } u; /**< the type writer or reader that does all the work */
155 _dbus_header_is_gvariant (const DBusHeader *header)
157 return (header->protocol_version == DBUS_PROTOCOL_VERSION_GVARIANT);
161 _dbus_message_is_gvariant (const DBusMessage *message)
163 return _dbus_header_is_gvariant (&message->header);
167 _dbus_message_toggle_gvariant (DBusMessage *message, dbus_bool_t gvariant)
169 message->header.protocol_version = gvariant ? DBUS_PROTOCOL_VERSION_GVARIANT : DBUS_MAJOR_PROTOCOL_VERSION;
173 * Layout of a DBusMessageIter on the stack in dbus 1.10.0. This is no
174 * longer used, but for ABI compatibility we need to assert that the
175 * new layout is the same size.
180 dbus_uint32_t dummy3a : 21;
181 dbus_uint32_t dummy3b : 3;
182 dbus_uint32_t dummy3c : 8;
187 dbus_uint32_t dummy1a : 8;
188 dbus_uint32_t dummy1b : 1;
189 dbus_uint32_t dummy1c : 3;
190 dbus_uint32_t dummy1d : 1;
191 dbus_uint32_t dummy1e : 1;
192 dbus_uint32_t dummy1f : 1;
213 dbus_uint32_t dummy1a : 8;
214 dbus_uint32_t dummy1b : 8;
215 dbus_uint32_t dummy1c : 1;
216 dbus_uint32_t dummy1d : 1;
217 dbus_uint32_t dummy1e : 1;
218 dbus_uint32_t dummy1f : 1;
219 dbus_uint32_t dummy1g : 1;
247 } DBusMessageIter_1_10_0;
250 get_const_signature (DBusMessage *message,
251 const DBusString **type_str_p,
254 dbus_bool_t got_signature = FALSE;
255 if (_dbus_message_is_gvariant (message) && message->locked)
257 /* only locked GVariant messages have signatures in the body */
259 * in case of received GVariant message, there may be no signature field in a header,
260 * but in the body. However, it is not nul-terminated.
261 * So, we need to allocate space and put it into message.
262 * It could also happen before, so check message->signature for already existing.
263 * FIXME: That may kinda break oom-safety.
264 * For now - if oom, then return empty signature.
266 if (message->signature == NULL)
269 got_signature = _dbus_message_gvariant_get_signature (message,
273 if (got_signature && type_str_len > 1)
275 message->signature = dbus_new (DBusString, 1);
276 got_signature = got_signature &&
277 _dbus_string_init_preallocated (message->signature, type_str_len - 1);
279 /* we need to copy the signature, but to ensure backward compatibility
280 * it must be stripped off outer parentheses - they are always there */
281 got_signature = got_signature &&
282 _dbus_string_copy_len (*type_str_p, *type_pos_p + 1, type_str_len - 2,
283 message->signature, 0);
284 got_signature = got_signature &&
285 _dbus_string_append_byte (message->signature, 0);
289 got_signature = TRUE;
293 *type_str_p = message->signature;
297 else if (_dbus_header_get_field_raw (&message->header,
298 DBUS_HEADER_FIELD_SIGNATURE,
302 if (!_dbus_message_is_gvariant (message))
303 *type_pos_p += 1; /* skip the signature length which is 1 byte */
304 got_signature = TRUE;
308 *type_str_p = &_dbus_empty_signature_str;
314 * Swaps the message to compiler byte order if required
316 * @param message the message
319 _dbus_message_byteswap (DBusMessage *message)
321 const DBusString *type_str;
325 byte_order = _dbus_header_get_byte_order (&message->header);
327 if (byte_order == DBUS_COMPILER_BYTE_ORDER)
330 _dbus_verbose ("Swapping message into compiler byte order\n");
332 get_const_signature (message, &type_str, &type_pos);
334 _dbus_marshal_byteswap (type_str, type_pos,
336 DBUS_COMPILER_BYTE_ORDER,
339 _dbus_header_byteswap (&message->header, DBUS_COMPILER_BYTE_ORDER);
340 _dbus_assert (_dbus_header_get_byte_order (&message->header) ==
341 DBUS_COMPILER_BYTE_ORDER);
344 /** byte-swap the message if it doesn't match our byte order.
345 * Called only when we need the message in our own byte order,
346 * normally when reading arrays of integers or doubles.
347 * Otherwise should not be called since it would do needless
350 #define ensure_byte_order(message) _dbus_message_byteswap (message)
353 * Gets the data to be sent over the network for this message.
354 * The header and then the body should be written out.
355 * This function is guaranteed to always return the same
356 * data once a message is locked (with dbus_message_lock()).
358 * @param message the message.
359 * @param header return location for message header data.
360 * @param body return location for message body data.
363 _dbus_message_get_network_data (DBusMessage *message,
364 const DBusString **header,
365 const DBusString **body)
367 _dbus_assert (message->locked);
369 *header = &message->header.data;
370 *body = &message->body;
373 void _dbus_message_set_timeout_ms(DBusMessage *message, int timeout_ms) {
374 message->timeout_ms = timeout_ms;
376 int _dbus_message_get_timeout_ms(DBusMessage const *message) {
377 return message->timeout_ms;
381 * Gets the unix fds to be sent over the network for this message.
382 * This function is guaranteed to always return the same data once a
383 * message is locked (with dbus_message_lock()).
385 * @param message the message.
386 * @param fds return location of unix fd array
387 * @param n_fds return number of entries in array
389 void _dbus_message_get_unix_fds(DBusMessage *message,
393 _dbus_assert (message->locked);
395 #ifdef HAVE_UNIX_FD_PASSING
396 *fds = message->unix_fds;
397 *n_fds = message->n_unix_fds;
405 * Sets the serial number of a message.
406 * This can only be done once on a message.
408 * DBusConnection will automatically set the serial to an appropriate value
409 * when the message is sent; this function is only needed when encapsulating
410 * messages in another protocol, or otherwise bypassing DBusConnection.
412 * @param message the message
413 * @param serial the serial
416 dbus_message_set_serial (DBusMessage *message,
417 dbus_uint32_t serial)
419 _dbus_return_if_fail (message != NULL);
420 _dbus_return_if_fail (!message->locked);
422 _dbus_header_set_serial (&message->header, serial);
426 * Adds a counter to be incremented immediately with the size/unix fds
427 * of this message, and decremented by the size/unix fds of this
428 * message when this message if finalized. The link contains a
429 * counter with its refcount already incremented, but the counter
430 * itself not incremented. Ownership of link and counter refcount is
431 * passed to the message.
433 * This function may be called with locks held. As a result, the counter's
434 * notify function is not called; the caller is expected to either call
435 * _dbus_counter_notify() on the counter when they are no longer holding
436 * locks, or take the same action that would be taken by the notify function.
438 * @param message the message
439 * @param link link with counter as data
442 _dbus_message_add_counter_link (DBusMessage *message,
445 /* right now we don't recompute the delta when message
446 * size changes, and that's OK for current purposes
447 * I think, but could be important to change later.
448 * Do recompute it whenever there are no outstanding counters,
449 * since it's basically free.
451 if (message->counters == NULL)
453 message->size_counter_delta =
454 _dbus_string_get_length (&message->header.data) +
455 _dbus_string_get_length (&message->body);
457 #ifdef HAVE_UNIX_FD_PASSING
458 message->unix_fd_counter_delta = message->n_unix_fds;
462 _dbus_verbose ("message has size %ld\n",
463 message->size_counter_delta);
467 _dbus_list_append_link (&message->counters, link);
469 _dbus_counter_adjust_size (link->data, message->size_counter_delta);
471 #ifdef HAVE_UNIX_FD_PASSING
472 _dbus_counter_adjust_unix_fd (link->data, message->unix_fd_counter_delta);
477 * Adds a counter to be incremented immediately with the size/unix fds
478 * of this message, and decremented by the size/unix fds of this
479 * message when this message if finalized.
481 * This function may be called with locks held. As a result, the counter's
482 * notify function is not called; the caller is expected to either call
483 * _dbus_counter_notify() on the counter when they are no longer holding
484 * locks, or take the same action that would be taken by the notify function.
486 * @param message the message
487 * @param counter the counter
488 * @returns #FALSE if no memory
491 _dbus_message_add_counter (DBusMessage *message,
492 DBusCounter *counter)
496 link = _dbus_list_alloc_link (counter);
500 _dbus_counter_ref (counter);
501 _dbus_message_add_counter_link (message, link);
507 * Removes a counter tracking the size/unix fds of this message, and
508 * decrements the counter by the size/unix fds of this message.
510 * @param message the message
511 * @param counter the counter
514 _dbus_message_remove_counter (DBusMessage *message,
515 DBusCounter *counter)
519 link = _dbus_list_find_last (&message->counters,
521 _dbus_assert (link != NULL);
523 _dbus_list_remove_link (&message->counters, link);
525 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
527 #ifdef HAVE_UNIX_FD_PASSING
528 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
531 _dbus_counter_notify (counter);
532 _dbus_counter_unref (counter);
536 * Locks a message. Allows checking that applications don't keep a
537 * reference to a message in the outgoing queue and change it
538 * underneath us. Messages are locked when they enter the outgoing
539 * queue (dbus_connection_send_message()), and the library complains
540 * if the message is modified while locked. This function may also
541 * called externally, for applications wrapping D-Bus in another protocol.
543 * @param message the message to lock.
546 dbus_message_lock (DBusMessage *message)
548 if (!message->locked)
550 if (!_dbus_message_is_gvariant (message))
551 _dbus_header_update_lengths (&message->header,
552 _dbus_string_get_length (&message->body));
554 _dbus_message_finalize_gvariant (message, TRUE);
556 /* must have a signature if you have a body */
557 _dbus_assert (_dbus_string_get_length (&message->body) == 0 ||
558 dbus_message_get_signature (message) != NULL);
560 message->locked = TRUE;
565 set_or_delete_string_field (DBusMessage *message,
571 return _dbus_header_delete_field (&message->header, field);
573 return _dbus_header_set_field_basic (&message->header,
581 * We cache some DBusMessage to reduce the overhead of allocating
582 * them. In my profiling this consistently made about an 8%
583 * difference. It avoids the malloc for the message, the malloc for
584 * the slot list, the malloc for the header string and body string,
585 * and the associated free() calls. It does introduce another global
586 * lock which could be a performance issue in certain cases.
588 * For the echo client/server the round trip time goes from around
589 * .000077 to .000069 with the message cache on my laptop. The sysprof
590 * change is as follows (numbers are cumulative percentage):
592 * with message cache implemented as array as it is now (0.000069 per):
593 * new_empty_header 1.46
594 * mutex_lock 0.56 # i.e. _DBUS_LOCK(message_cache)
600 * mutex_lock 0.33 # i.e. _DBUS_LOCK(message_cache)
603 * with message cache implemented as list (0.000070 per roundtrip):
604 * new_empty_header 2.72
605 * list_pop_first 1.88
609 * without cache (0.000077 per roundtrip):
610 * new_empty_header 6.7
611 * string_init_preallocated 3.43
620 * If you implement the message_cache with a list, the primary reason
621 * it's slower is that you add another thread lock (on the DBusList
625 /** Avoid caching huge messages */
626 #define MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE
628 /** Avoid caching too many messages */
629 #define MAX_MESSAGE_CACHE_SIZE 5
631 /* Protected by _DBUS_LOCK (message_cache) */
632 static DBusMessage *message_cache[MAX_MESSAGE_CACHE_SIZE];
633 static int message_cache_count = 0;
634 static dbus_bool_t message_cache_shutdown_registered = FALSE;
637 dbus_message_cache_shutdown (void *data)
641 if (!_DBUS_LOCK (message_cache))
642 _dbus_assert_not_reached ("we would have initialized global locks "
643 "before registering a shutdown function");
646 while (i < MAX_MESSAGE_CACHE_SIZE)
648 if (message_cache[i])
649 dbus_message_finalize (message_cache[i]);
654 message_cache_count = 0;
655 message_cache_shutdown_registered = FALSE;
657 _DBUS_UNLOCK (message_cache);
661 * Tries to get a message from the message cache. The retrieved
662 * message will have junk in it, so it still needs to be cleared out
663 * in dbus_message_new_empty_header()
665 * @returns the message, or #NULL if none cached
668 dbus_message_get_cached (void)
670 DBusMessage *message;
675 if (!_DBUS_LOCK (message_cache))
677 /* we'd have initialized global locks before caching anything,
678 * so there can't be anything in the cache */
682 _dbus_assert (message_cache_count >= 0);
684 if (message_cache_count == 0)
686 _DBUS_UNLOCK (message_cache);
690 /* This is not necessarily true unless count > 0, and
691 * message_cache is uninitialized until the shutdown is
694 _dbus_assert (message_cache_shutdown_registered);
697 while (i < MAX_MESSAGE_CACHE_SIZE)
699 if (message_cache[i])
701 message = message_cache[i];
702 message_cache[i] = NULL;
703 message_cache_count -= 1;
708 _dbus_assert (message_cache_count >= 0);
709 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
710 _dbus_assert (message != NULL);
712 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
714 _dbus_assert (message->counters == NULL);
716 _DBUS_UNLOCK (message_cache);
721 #ifdef HAVE_UNIX_FD_PASSING
723 close_unix_fds(int *fds, unsigned *n_fds)
733 for (i = 0; i < *n_fds; i++)
735 if (!_dbus_close(fds[i], &e))
737 _dbus_warn("Failed to close file descriptor: %s", e.message);
744 /* We don't free the array here, in case we can recycle it later */
749 free_counter (void *element,
752 DBusCounter *counter = element;
753 DBusMessage *message = data;
755 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
756 #ifdef HAVE_UNIX_FD_PASSING
757 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
760 _dbus_counter_notify (counter);
761 _dbus_counter_unref (counter);
765 * Tries to cache a message, otherwise finalize it.
767 * @param message the message
770 dbus_message_cache_or_finalize (DBusMessage *message)
772 dbus_bool_t was_cached;
775 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
777 /* This calls application code and has to be done first thing
778 * without holding the lock
780 _dbus_data_slot_list_clear (&message->slot_list);
782 _dbus_list_foreach (&message->counters,
783 free_counter, message);
784 _dbus_list_clear (&message->counters);
786 #ifdef HAVE_UNIX_FD_PASSING
787 close_unix_fds(message->unix_fds, &message->n_unix_fds);
790 if (NULL != message->signature)
792 _dbus_string_free (message->signature);
793 dbus_free (message->signature);
794 message->signature = NULL;
797 if (NULL != message->unique_sender)
799 _dbus_string_free (message->unique_sender);
800 dbus_free (message->unique_sender);
801 message->unique_sender = NULL;
806 if (!_DBUS_LOCK (message_cache))
808 /* The only way to get a non-null message goes through
809 * dbus_message_get_cached() which takes the lock. */
810 _dbus_assert_not_reached ("we would have initialized global locks "
811 "the first time we constructed a message");
814 if (!message_cache_shutdown_registered)
816 _dbus_assert (message_cache_count == 0);
818 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
822 while (i < MAX_MESSAGE_CACHE_SIZE)
824 message_cache[i] = NULL;
828 message_cache_shutdown_registered = TRUE;
831 _dbus_assert (message_cache_count >= 0);
833 if (!_dbus_enable_message_cache ())
836 if ((_dbus_string_get_length (&message->header.data) +
837 _dbus_string_get_length (&message->body)) >
838 MAX_MESSAGE_SIZE_TO_CACHE)
841 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
844 /* Find empty slot */
846 while (message_cache[i] != NULL)
849 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
851 _dbus_assert (message_cache[i] == NULL);
852 message_cache[i] = message;
853 message_cache_count += 1;
855 #ifndef DBUS_DISABLE_CHECKS
856 message->in_cache = TRUE;
860 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
862 _DBUS_UNLOCK (message_cache);
865 dbus_message_finalize (message);
869 * Arrange for iter to be something that _dbus_message_iter_check() would
870 * reject as not a valid iterator.
873 _dbus_message_real_iter_zero (DBusMessageRealIter *iter)
875 _dbus_assert (iter != NULL);
877 /* NULL is not, strictly speaking, guaranteed to be all-bits-zero */
878 iter->message = NULL;
882 * Initialize iter as if with #DBUS_MESSAGE_ITER_INIT_CLOSED. The only valid
883 * operation for such an iterator is
884 * dbus_message_iter_abandon_container_if_open(), which does nothing.
887 dbus_message_iter_init_closed (DBusMessageIter *iter)
889 _dbus_return_if_fail (iter != NULL);
890 _dbus_message_real_iter_zero ((DBusMessageRealIter *) iter);
894 _dbus_message_real_iter_is_zeroed (DBusMessageRealIter *iter)
896 return (iter != NULL && iter->message == NULL && iter->changed_stamp == 0 &&
897 iter->iter_type == 0 && iter->sig_refcount == 0);
900 #if defined(DBUS_ENABLE_CHECKS) || defined(DBUS_ENABLE_ASSERT)
902 _dbus_message_iter_check (DBusMessageRealIter *iter)
908 _dbus_warn_check_failed ("dbus message iterator is NULL");
912 if (iter->message == NULL || iter->iter_type == 0)
914 _dbus_warn_check_failed ("dbus message iterator has already been "
915 "closed, or is uninitialized or corrupt");
919 byte_order = _dbus_header_get_byte_order (&iter->message->header);
921 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
923 if (iter->u.reader.byte_order != byte_order)
925 _dbus_warn_check_failed ("dbus message changed byte order since iterator was created");
928 /* because we swap the message into compiler order when you init an iter */
929 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
931 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
933 if (iter->u.writer.byte_order != byte_order)
935 _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created");
938 /* because we swap the message into compiler order when you init an iter */
939 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
943 _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted");
947 if (iter->changed_stamp != iter->message->changed_stamp)
949 _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)");
955 #endif /* DBUS_ENABLE_CHECKS || DBUS_ENABLE_ASSERT */
958 * Implementation of the varargs arg-getting functions.
959 * dbus_message_get_args() is the place to go for complete
962 * @see dbus_message_get_args
963 * @param iter the message iter
964 * @param error error to be filled in
965 * @param first_arg_type type of the first argument
966 * @param var_args return location for first argument, followed by list of type/location pairs
967 * @returns #FALSE if error was set
970 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
975 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
976 int spec_type, msg_type, i, j;
980 _dbus_assert (_dbus_message_iter_check (real));
984 spec_type = first_arg_type;
987 /* copy var_args first, then we can do another iteration over it to
988 * free memory and close unix fds if parse failed at some point.
990 DBUS_VA_COPY (copy_args, var_args);
992 while (spec_type != DBUS_TYPE_INVALID)
994 msg_type = dbus_message_iter_get_arg_type (iter);
996 if (msg_type != spec_type)
998 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
999 "Argument %d is specified to be of type \"%s\", but "
1000 "is actually of type \"%s\"\n", i,
1001 _dbus_type_to_string (spec_type),
1002 _dbus_type_to_string (msg_type));
1007 if (spec_type == DBUS_TYPE_UNIX_FD)
1009 #ifdef HAVE_UNIX_FD_PASSING
1013 pfd = va_arg (var_args, int*);
1016 _dbus_type_reader_read_basic(&real->u.reader, &idx);
1018 if (idx.u32 >= real->message->n_unix_fds)
1020 dbus_set_error (error, DBUS_ERROR_INCONSISTENT_MESSAGE,
1021 "Message refers to file descriptor at index %i,"
1022 "but has only %i descriptors attached.\n",
1024 real->message->n_unix_fds);
1028 if ((nfd = _dbus_dup(real->message->unix_fds[idx.u32], error)) < 0)
1033 dbus_set_error (error, DBUS_ERROR_NOT_SUPPORTED,
1034 "Platform does not support file desciptor passing.\n");
1038 else if (dbus_type_is_basic (spec_type))
1040 DBusBasicValue *ptr;
1042 ptr = va_arg (var_args, DBusBasicValue*);
1044 _dbus_assert (ptr != NULL);
1046 _dbus_type_reader_read_basic (&real->u.reader,
1049 else if (spec_type == DBUS_TYPE_ARRAY)
1052 int spec_element_type;
1053 const DBusBasicValue **ptr;
1055 DBusTypeReader array;
1057 spec_element_type = va_arg (var_args, int);
1058 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
1060 if (spec_element_type != element_type)
1062 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
1063 "Argument %d is specified to be an array of \"%s\", but "
1064 "is actually an array of \"%s\"\n",
1066 _dbus_type_to_string (spec_element_type),
1067 _dbus_type_to_string (element_type));
1072 if (dbus_type_is_fixed (spec_element_type) &&
1073 element_type != DBUS_TYPE_UNIX_FD)
1075 ptr = va_arg (var_args, const DBusBasicValue**);
1076 n_elements_p = va_arg (var_args, int*);
1078 _dbus_assert (ptr != NULL);
1079 _dbus_assert (n_elements_p != NULL);
1081 _dbus_type_reader_recurse (&real->u.reader, &array);
1083 _dbus_type_reader_read_fixed_multi (&array,
1084 (void *) ptr, n_elements_p);
1086 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
1088 char ***str_array_p;
1092 str_array_p = va_arg (var_args, char***);
1093 n_elements_p = va_arg (var_args, int*);
1095 _dbus_assert (str_array_p != NULL);
1096 _dbus_assert (n_elements_p != NULL);
1098 /* Count elements in the array */
1099 _dbus_type_reader_recurse (&real->u.reader, &array);
1102 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
1105 _dbus_type_reader_next (&array);
1108 str_array = dbus_new0 (char*, n_elements + 1);
1109 if (str_array == NULL)
1111 _DBUS_SET_OOM (error);
1115 /* Now go through and dup each string */
1116 _dbus_type_reader_recurse (&real->u.reader, &array);
1119 while (j < n_elements)
1122 _dbus_type_reader_read_basic (&array,
1125 str_array[j] = _dbus_strdup (s);
1126 if (str_array[j] == NULL)
1128 dbus_free_string_array (str_array);
1129 _DBUS_SET_OOM (error);
1135 if (!_dbus_type_reader_next (&array))
1136 _dbus_assert (j == n_elements);
1139 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
1140 _dbus_assert (j == n_elements);
1141 _dbus_assert (str_array[j] == NULL);
1143 *str_array_p = str_array;
1144 *n_elements_p = n_elements;
1146 #ifndef DBUS_DISABLE_CHECKS
1149 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now",
1150 _DBUS_FUNCTION_NAME);
1155 #ifndef DBUS_DISABLE_CHECKS
1158 _dbus_warn ("you can only read arrays and basic types with %s for now",
1159 _DBUS_FUNCTION_NAME);
1164 /* how many arguments already handled */
1167 spec_type = va_arg (var_args, int);
1168 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
1170 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
1171 "Message has only %d arguments, but more were expected", i);
1179 /* there may memory or unix fd leak in the above iteration if parse failed.
1180 * so we have another iteration over copy_args to free memory and close
1185 spec_type = first_arg_type;
1190 if (spec_type == DBUS_TYPE_UNIX_FD)
1192 #ifdef HAVE_UNIX_FD_PASSING
1195 pfd = va_arg (copy_args, int *);
1199 _dbus_close (*pfd, NULL);
1204 else if (dbus_type_is_basic (spec_type))
1206 /* move the index forward */
1207 va_arg (copy_args, DBusBasicValue *);
1209 else if (spec_type == DBUS_TYPE_ARRAY)
1211 int spec_element_type;
1213 spec_element_type = va_arg (copy_args, int);
1214 if (dbus_type_is_fixed (spec_element_type))
1216 /* move the index forward */
1217 va_arg (copy_args, const DBusBasicValue **);
1218 va_arg (copy_args, int *);
1220 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
1222 char ***str_array_p;
1224 str_array_p = va_arg (copy_args, char ***);
1225 /* move the index forward */
1226 va_arg (copy_args, int *);
1227 _dbus_assert (str_array_p != NULL);
1228 dbus_free_string_array (*str_array_p);
1229 *str_array_p = NULL;
1233 spec_type = va_arg (copy_args, int);
1245 * @defgroup DBusMessage DBusMessage
1247 * @brief Message to be sent or received over a #DBusConnection.
1249 * A DBusMessage is the most basic unit of communication over a
1250 * DBusConnection. A DBusConnection represents a stream of messages
1251 * received from a remote application, and a stream of messages
1252 * sent to a remote application.
1254 * A message has a message type, returned from
1255 * dbus_message_get_type(). This indicates whether the message is a
1256 * method call, a reply to a method call, a signal, or an error reply.
1258 * A message has header fields such as the sender, destination, method
1259 * or signal name, and so forth. DBusMessage has accessor functions for
1260 * these, such as dbus_message_get_member().
1262 * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
1263 * and dbus_message_is_error() check several header fields at once and are
1264 * slightly more efficient than checking the header fields with individual
1265 * accessor functions.
1267 * Finally, a message has arguments. The number and types of arguments
1268 * are in the message's signature header field (accessed with
1269 * dbus_message_get_signature()). Simple argument values are usually
1270 * retrieved with dbus_message_get_args() but more complex values such
1271 * as structs may require the use of #DBusMessageIter.
1273 * The D-Bus specification goes into some more detail about header fields and
1280 * @typedef DBusMessage
1282 * Opaque data type representing a message received from or to be
1283 * sent to another application.
1287 * Returns the serial of a message or 0 if none has been specified.
1288 * The message's serial number is provided by the application sending
1289 * the message and is used to identify replies to this message.
1291 * All messages received on a connection will have a serial provided
1292 * by the remote application.
1294 * For messages you're sending, dbus_connection_send() will assign a
1295 * serial and return it to you.
1297 * @param message the message
1298 * @returns the serial
1301 dbus_message_get_serial (DBusMessage *message)
1303 _dbus_return_val_if_fail (message != NULL, 0);
1305 return _dbus_header_get_serial (&message->header);
1309 * Sets the reply serial of a message (the serial of the message this
1312 * @param message the message
1313 * @param reply_serial the serial we're replying to
1314 * @returns #FALSE if not enough memory
1317 dbus_message_set_reply_serial (DBusMessage *message,
1318 dbus_uint32_t reply_serial)
1320 DBusBasicValue value;
1323 _dbus_return_val_if_fail (message != NULL, FALSE);
1324 _dbus_return_val_if_fail (!message->locked, FALSE);
1325 _dbus_return_val_if_fail (reply_serial != 0, FALSE); /* 0 is invalid */
1327 if (_dbus_message_is_gvariant (message))
1329 type = DBUS_TYPE_UINT64;
1330 value.u64 = reply_serial;
1334 type = DBUS_TYPE_UINT32;
1335 value.u32 = reply_serial;
1338 return _dbus_header_set_field_basic (&message->header,
1339 DBUS_HEADER_FIELD_REPLY_SERIAL,
1345 * Returns the serial that the message is a reply to or 0 if none.
1347 * @param message the message
1348 * @returns the reply serial
1351 dbus_message_get_reply_serial (DBusMessage *message)
1353 dbus_uint32_t v_UINT32;
1354 dbus_uint64_t v_UINT64;
1355 int type = DBUS_TYPE_UINT32;
1356 void *value = &v_UINT32;
1358 _dbus_return_val_if_fail (message != NULL, 0);
1360 if (_dbus_message_is_gvariant (message))
1362 type = DBUS_TYPE_UINT64;
1366 if (_dbus_header_get_field_basic (&message->header,
1367 DBUS_HEADER_FIELD_REPLY_SERIAL,
1371 if (_dbus_message_is_gvariant (message))
1381 dbus_message_finalize (DBusMessage *message)
1383 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1385 /* This calls application callbacks! */
1386 _dbus_data_slot_list_free (&message->slot_list);
1388 _dbus_list_foreach (&message->counters,
1389 free_counter, message);
1390 _dbus_list_clear (&message->counters);
1392 _dbus_header_free (&message->header);
1393 _dbus_string_free (&message->body);
1395 #ifdef HAVE_UNIX_FD_PASSING
1396 close_unix_fds(message->unix_fds, &message->n_unix_fds);
1397 dbus_free(message->unix_fds);
1400 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1402 dbus_free (message);
1406 dbus_message_new_empty_header (dbus_bool_t gvariant)
1408 DBusMessage *message;
1409 dbus_bool_t from_cache;
1411 message = dbus_message_get_cached ();
1413 if (message != NULL)
1420 message = dbus_new0 (DBusMessage, 1);
1421 if (message == NULL)
1423 #ifndef DBUS_DISABLE_CHECKS
1424 message->generation = _dbus_current_generation;
1427 #ifdef HAVE_UNIX_FD_PASSING
1428 message->unix_fds = NULL;
1429 message->n_unix_fds_allocated = 0;
1433 _dbus_atomic_inc (&message->refcount);
1435 _dbus_message_trace_ref (message, 0, 1, "new_empty_header");
1437 message->locked = FALSE;
1438 #ifndef DBUS_DISABLE_CHECKS
1439 message->in_cache = FALSE;
1441 message->counters = NULL;
1442 message->size_counter_delta = 0;
1443 message->timeout_ms = -1;
1444 message->changed_stamp = 0;
1446 #ifdef HAVE_UNIX_FD_PASSING
1447 message->n_unix_fds = 0;
1448 message->n_unix_fds_allocated = 0;
1449 message->unix_fd_counter_delta = 0;
1452 _dbus_message_toggle_gvariant (message, gvariant); /* this works only if kdbus is enabled */
1455 _dbus_data_slot_list_init (&message->slot_list);
1459 _dbus_header_reinit (&message->header);
1460 _dbus_string_set_length (&message->body, 0);
1464 if (!_dbus_header_init (&message->header))
1466 dbus_free (message);
1470 if (!_dbus_string_init_preallocated (&message->body, 32))
1472 _dbus_header_free (&message->header);
1473 dbus_free (message);
1478 message->signature = NULL;
1479 message->unique_sender = NULL;
1480 message->gvariant_body_last_offset = GVARIANT_LAST_OFFSET_NOT_SET;
1481 message->gvariant_body_last_pos = 0;
1487 _dbus_message_create_protocol_version (int message_type,
1488 const char *destination,
1490 const char *interface,
1492 const char *error_name,
1493 dbus_bool_t gvariant)
1495 DBusMessage *message;
1497 _dbus_assert (message_type != DBUS_MESSAGE_TYPE_INVALID);
1499 message = dbus_message_new_empty_header (gvariant);
1500 if (message == NULL)
1503 if (!(_dbus_message_is_gvariant(message) ? _dbus_header_gvariant_create : _dbus_header_create) (&message->header,
1504 DBUS_COMPILER_BYTE_ORDER,
1506 destination, path, interface, member, error_name))
1508 dbus_message_unref (message);
1516 _dbus_message_create (int message_type,
1517 const char *destination,
1519 const char *interface,
1521 const char *error_name)
1523 return _dbus_message_create_protocol_version(message_type,
1529 _dbus_default_protocol_version == DBUS_PROTOCOL_VERSION_GVARIANT);
1533 * Constructs a new message of the given message type.
1534 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
1535 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
1537 * Usually you want to use dbus_message_new_method_call(),
1538 * dbus_message_new_method_return(), dbus_message_new_signal(),
1539 * or dbus_message_new_error() instead.
1541 * @param message_type type of message
1542 * @returns new message or #NULL if no memory
1545 dbus_message_new (int message_type)
1547 return _dbus_message_create(message_type,
1548 NULL, NULL, NULL, NULL, NULL);
1552 * Constructs a new message to invoke a method on a remote
1553 * object. Returns #NULL if memory can't be allocated for the
1554 * message. The destination may be #NULL in which case no destination
1555 * is set; this is appropriate when using D-Bus in a peer-to-peer
1556 * context (no message bus). The interface may be #NULL, which means
1557 * that if multiple methods with the given name exist it is undefined
1558 * which one will be invoked.
1560 * The path and method names may not be #NULL.
1562 * Destination, path, interface, and method name can't contain
1563 * any invalid characters (see the D-Bus specification).
1565 * @param destination name that the message should be sent to or #NULL
1566 * @param path object path the message should be sent to
1567 * @param iface interface to invoke method on, or #NULL
1568 * @param method method to invoke
1570 * @returns a new DBusMessage, free with dbus_message_unref()
1573 dbus_message_new_method_call (const char *destination,
1578 _dbus_return_val_if_fail (path != NULL, NULL);
1579 _dbus_return_val_if_fail (method != NULL, NULL);
1580 _dbus_return_val_if_fail (destination == NULL ||
1581 _dbus_check_is_valid_bus_name (destination), NULL);
1582 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1583 _dbus_return_val_if_fail (iface == NULL ||
1584 _dbus_check_is_valid_interface (iface), NULL);
1585 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
1587 return _dbus_message_create(DBUS_MESSAGE_TYPE_METHOD_CALL,
1588 destination, path, iface, method, NULL);
1592 * Constructs a message that is a reply to a method call. Returns
1593 * #NULL if memory can't be allocated for the message.
1595 * @param method_call the message being replied to
1596 * @returns a new DBusMessage, free with dbus_message_unref()
1599 dbus_message_new_method_return (DBusMessage *method_call)
1601 DBusMessage *message;
1604 _dbus_return_val_if_fail (method_call != NULL, NULL);
1606 sender = dbus_message_get_sender (method_call);
1608 /* sender is allowed to be null here in peer-to-peer case */
1610 message = _dbus_message_create (DBUS_MESSAGE_TYPE_METHOD_RETURN,
1611 sender, NULL, NULL, NULL, NULL);
1612 if (message == NULL)
1615 dbus_message_set_no_reply (message, TRUE);
1617 if (!dbus_message_set_reply_serial (message,
1618 dbus_message_get_serial (method_call)))
1620 dbus_message_unref (message);
1628 * Constructs a new message representing a signal emission. Returns
1629 * #NULL if memory can't be allocated for the message. A signal is
1630 * identified by its originating object path, interface, and the name
1633 * Path, interface, and signal name must all be valid (the D-Bus
1634 * specification defines the syntax of these fields).
1636 * @param path the path to the object emitting the signal
1637 * @param iface the interface the signal is emitted from
1638 * @param name name of the signal
1639 * @returns a new DBusMessage, free with dbus_message_unref()
1642 dbus_message_new_signal (const char *path,
1646 DBusMessage *message;
1648 _dbus_return_val_if_fail (path != NULL, NULL);
1649 _dbus_return_val_if_fail (iface != NULL, NULL);
1650 _dbus_return_val_if_fail (name != NULL, NULL);
1651 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1652 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (iface), NULL);
1653 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
1655 message = _dbus_message_create (DBUS_MESSAGE_TYPE_SIGNAL,
1656 NULL, path, iface, name, NULL);
1657 if (message == NULL)
1660 dbus_message_set_no_reply (message, TRUE);
1666 * Creates a new message that is an error reply to another message.
1667 * Error replies are most common in response to method calls, but
1668 * can be returned in reply to any message.
1670 * The error name must be a valid error name according to the syntax
1671 * given in the D-Bus specification. If you don't want to make
1672 * up an error name just use #DBUS_ERROR_FAILED.
1674 * @param reply_to the message we're replying to
1675 * @param error_name the error name
1676 * @param error_message the error message string (or #NULL for none, but please give a message)
1677 * @returns a new error message object, free with dbus_message_unref()
1680 dbus_message_new_error (DBusMessage *reply_to,
1681 const char *error_name,
1682 const char *error_message)
1684 DBusMessage *message;
1686 DBusMessageIter iter;
1688 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1689 _dbus_return_val_if_fail (error_name != NULL, NULL);
1690 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1692 sender = dbus_message_get_sender (reply_to);
1694 /* sender may be NULL for non-message-bus case or
1695 * when the message bus is dealing with an unregistered
1698 message = _dbus_message_create (DBUS_MESSAGE_TYPE_ERROR,
1699 sender, NULL, NULL, NULL, error_name);
1700 if (message == NULL)
1703 dbus_message_set_no_reply (message, TRUE);
1705 if (!dbus_message_set_reply_serial (message,
1706 dbus_message_get_serial (reply_to)))
1708 dbus_message_unref (message);
1712 if (error_message != NULL)
1714 dbus_message_iter_init_append (message, &iter);
1715 if (!dbus_message_iter_append_basic (&iter,
1719 dbus_message_unref (message);
1728 * Creates a new message that is an error reply to another message, allowing
1729 * you to use printf formatting.
1731 * See dbus_message_new_error() for details - this function is the same
1732 * aside from the printf formatting.
1734 * @todo add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to
1735 * public header, see DBUS_DEPRECATED for an example)
1737 * @param reply_to the original message
1738 * @param error_name the error name
1739 * @param error_format the error message format as with printf
1740 * @param ... format string arguments
1741 * @returns a new error message
1744 dbus_message_new_error_printf (DBusMessage *reply_to,
1745 const char *error_name,
1746 const char *error_format,
1751 DBusMessage *message;
1753 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1754 _dbus_return_val_if_fail (error_name != NULL, NULL);
1755 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1757 if (!_dbus_string_init (&str))
1760 va_start (args, error_format);
1762 if (_dbus_string_append_printf_valist (&str, error_format, args))
1763 message = dbus_message_new_error (reply_to, error_name,
1764 _dbus_string_get_const_data (&str));
1768 _dbus_string_free (&str);
1777 * Creates a new message that is an exact replica of the message
1778 * specified, except that its refcount is set to 1, its message serial
1779 * is reset to 0, and if the original message was "locked" (in the
1780 * outgoing message queue and thus not modifiable) the new message
1781 * will not be locked.
1783 * @todo This function can't be used in programs that try to recover from OOM errors.
1785 * @param message the message
1786 * @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.
1789 dbus_message_copy (const DBusMessage *message)
1791 DBusMessage *retval;
1793 _dbus_return_val_if_fail (message != NULL, NULL);
1795 retval = dbus_new0 (DBusMessage, 1);
1799 _dbus_atomic_inc (&retval->refcount);
1801 retval->locked = FALSE;
1802 #ifndef DBUS_DISABLE_CHECKS
1803 retval->generation = message->generation;
1805 _dbus_message_toggle_gvariant (retval, _dbus_message_is_gvariant (message));
1807 if (!_dbus_header_copy (&message->header, &retval->header))
1813 if (!_dbus_string_init_preallocated (&retval->body,
1814 _dbus_string_get_length (&message->body)))
1816 _dbus_header_free (&retval->header);
1821 if (!_dbus_string_copy (&message->body, 0,
1825 #ifdef HAVE_UNIX_FD_PASSING
1826 retval->unix_fds = dbus_new(int, message->n_unix_fds);
1827 if (retval->unix_fds == NULL && message->n_unix_fds > 0)
1830 retval->n_unix_fds_allocated = message->n_unix_fds;
1832 for (retval->n_unix_fds = 0;
1833 retval->n_unix_fds < message->n_unix_fds;
1834 retval->n_unix_fds++)
1836 retval->unix_fds[retval->n_unix_fds] = _dbus_dup(message->unix_fds[retval->n_unix_fds], NULL);
1838 if (retval->unix_fds[retval->n_unix_fds] < 0)
1844 if (_dbus_message_is_gvariant(message))
1846 if (message->locked)
1848 /* This is a copy of locked GVariant message, so temporarily set it
1849 * to locked to correctly extract data. Locked messages contain
1850 * signature in the message body, while in unlocked messages it is
1851 * in the struct DBusMessage in the header.
1853 retval->locked = TRUE;
1854 if (!_dbus_message_gvariant_convert_to_unlocked (retval))
1858 if (message->unique_sender)
1860 retval->unique_sender = dbus_new (DBusString, 1);
1862 if (!retval->unique_sender)
1865 if (!_dbus_string_init_preallocated (retval->unique_sender,
1866 _dbus_string_get_length (message->unique_sender)))
1867 goto failed_copy_unique_sender;
1869 if (!_dbus_string_copy (message->unique_sender, 0, retval->unique_sender, 0))
1870 goto failed_copy_unique_sender;
1874 _dbus_message_trace_ref (retval, 0, 1, "copy");
1877 failed_copy_unique_sender:
1878 _dbus_string_free (retval->unique_sender);
1879 dbus_free (retval->unique_sender);
1882 _dbus_header_free (&retval->header);
1883 _dbus_string_free (&retval->body);
1885 #ifdef HAVE_UNIX_FD_PASSING
1886 close_unix_fds(retval->unix_fds, &retval->n_unix_fds);
1887 dbus_free(retval->unix_fds);
1897 * Increments the reference count of a DBusMessage.
1899 * @param message the message
1900 * @returns the message
1901 * @see dbus_message_unref
1904 dbus_message_ref (DBusMessage *message)
1906 dbus_int32_t old_refcount;
1908 _dbus_return_val_if_fail (message != NULL, NULL);
1909 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1910 _dbus_return_val_if_fail (!message->in_cache, NULL);
1912 old_refcount = _dbus_atomic_inc (&message->refcount);
1913 _dbus_assert (old_refcount >= 1);
1914 _dbus_message_trace_ref (message, old_refcount, old_refcount + 1, "ref");
1920 * Decrements the reference count of a DBusMessage, freeing the
1921 * message if the count reaches 0.
1923 * @param message the message
1924 * @see dbus_message_ref
1927 dbus_message_unref (DBusMessage *message)
1929 dbus_int32_t old_refcount;
1931 _dbus_return_if_fail (message != NULL);
1932 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1933 _dbus_return_if_fail (!message->in_cache);
1935 old_refcount = _dbus_atomic_dec (&message->refcount);
1937 _dbus_assert (old_refcount >= 1);
1939 _dbus_message_trace_ref (message, old_refcount, old_refcount - 1, "unref");
1941 if (old_refcount == 1)
1943 /* Calls application callbacks! */
1944 dbus_message_cache_or_finalize (message);
1949 * Gets the type of a message. Types include
1950 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1951 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1952 * types are allowed and all code must silently ignore messages of
1953 * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
1955 * @param message the message
1956 * @returns the type of the message
1959 dbus_message_get_type (DBusMessage *message)
1961 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1963 return _dbus_header_get_message_type (&message->header);
1967 * Appends fields to a message given a variable argument list. The
1968 * variable argument list should contain the type of each argument
1969 * followed by the value to append. Appendable types are basic types,
1970 * and arrays of fixed-length basic types (except arrays of Unix file
1971 * descriptors). To append variable-length basic types, or any more
1972 * complex value, you have to use an iterator rather than this
1975 * To append a basic type, specify its type code followed by the
1976 * address of the value. For example:
1980 * dbus_int32_t v_INT32 = 42;
1981 * const char *v_STRING = "Hello World";
1982 * dbus_message_append_args (message,
1983 * DBUS_TYPE_INT32, &v_INT32,
1984 * DBUS_TYPE_STRING, &v_STRING,
1985 * DBUS_TYPE_INVALID);
1988 * To append an array of fixed-length basic types (except Unix file
1989 * descriptors), pass in the DBUS_TYPE_ARRAY typecode, the element
1990 * typecode, the address of the array pointer, and a 32-bit integer
1991 * giving the number of elements in the array. So for example:
1995 * const dbus_int32_t array[] = { 1, 2, 3 };
1996 * const dbus_int32_t *v_ARRAY = array;
1997 * dbus_message_append_args (message,
1998 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3,
1999 * DBUS_TYPE_INVALID);
2003 * This function does not support arrays of Unix file descriptors. If
2004 * you need those you need to manually recurse into the array.
2006 * For Unix file descriptors this function will internally duplicate
2007 * the descriptor you passed in. Hence you may close the descriptor
2008 * immediately after this call.
2010 * @warning in C, given "int array[]", "&array == array" (the
2011 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2012 * So if you're using an array instead of a pointer you have to create
2013 * a pointer variable, assign the array to it, then take the address
2014 * of the pointer variable. For strings it works to write
2015 * const char *array = "Hello" and then use &array though.
2017 * The last argument to this function must be #DBUS_TYPE_INVALID,
2018 * marking the end of the argument list. If you don't do this
2019 * then libdbus won't know to stop and will read invalid memory.
2021 * String/signature/path arrays should be passed in as "const char***
2022 * address_of_array" and "int n_elements"
2024 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
2026 * @todo If this fails due to lack of memory, the message is hosed and
2027 * you have to start over building the whole message.
2029 * @param message the message
2030 * @param first_arg_type type of the first argument
2031 * @param ... value of first argument, list of additional type-value pairs
2032 * @returns #TRUE on success
2035 dbus_message_append_args (DBusMessage *message,
2042 _dbus_return_val_if_fail (message != NULL, FALSE);
2044 va_start (var_args, first_arg_type);
2045 retval = dbus_message_append_args_valist (message,
2054 * Like dbus_message_append_args() but takes a va_list for use by language bindings.
2056 * @todo for now, if this function fails due to OOM it will leave
2057 * the message half-written and you have to discard the message
2060 * @see dbus_message_append_args.
2061 * @param message the message
2062 * @param first_arg_type type of first argument
2063 * @param var_args value of first argument, then list of type/value pairs
2064 * @returns #TRUE on success
2067 dbus_message_append_args_valist (DBusMessage *message,
2072 DBusMessageIter iter;
2074 _dbus_return_val_if_fail (message != NULL, FALSE);
2076 type = first_arg_type;
2078 dbus_message_iter_init_append (message, &iter);
2080 while (type != DBUS_TYPE_INVALID)
2082 if (dbus_type_is_basic (type))
2084 const DBusBasicValue *value;
2085 value = va_arg (var_args, const DBusBasicValue*);
2087 if (!dbus_message_iter_append_basic (&iter,
2092 else if (type == DBUS_TYPE_ARRAY)
2095 DBusMessageIter array;
2098 element_type = va_arg (var_args, int);
2100 buf[0] = element_type;
2102 if (!dbus_message_iter_open_container (&iter,
2108 if (dbus_type_is_fixed (element_type) &&
2109 element_type != DBUS_TYPE_UNIX_FD)
2111 const DBusBasicValue **value;
2114 value = va_arg (var_args, const DBusBasicValue**);
2115 n_elements = va_arg (var_args, int);
2117 if (!dbus_message_iter_append_fixed_array (&array,
2121 dbus_message_iter_abandon_container (&iter, &array);
2125 else if (_DBUS_TYPE_IS_STRINGLIKE (element_type))
2127 const char ***value_p;
2132 value_p = va_arg (var_args, const char***);
2133 n_elements = va_arg (var_args, int);
2138 while (i < n_elements)
2140 if (!dbus_message_iter_append_basic (&array,
2143 dbus_message_iter_abandon_container (&iter, &array);
2151 _dbus_warn ("arrays of %s can't be appended with %s for now",
2152 _dbus_type_to_string (element_type),
2153 _DBUS_FUNCTION_NAME);
2154 dbus_message_iter_abandon_container (&iter, &array);
2158 if (!dbus_message_iter_close_container (&iter, &array))
2161 #ifndef DBUS_DISABLE_CHECKS
2164 _dbus_warn ("type %s isn't supported yet in %s",
2165 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
2170 type = va_arg (var_args, int);
2180 * Gets arguments from a message given a variable argument list. The
2181 * supported types include those supported by
2182 * dbus_message_append_args(); that is, basic types and arrays of
2183 * fixed-length basic types. The arguments are the same as they would
2184 * be for dbus_message_iter_get_basic() or
2185 * dbus_message_iter_get_fixed_array().
2187 * In addition to those types, arrays of string, object path, and
2188 * signature are supported; but these are returned as allocated memory
2189 * and must be freed with dbus_free_string_array(), while the other
2190 * types are returned as const references. To get a string array
2191 * pass in "char ***array_location" and "int *n_elements".
2193 * Similar to dbus_message_get_fixed_array() this function does not
2194 * support arrays of type DBUS_TYPE_UNIX_FD. If you need to parse
2195 * messages with arrays of Unix file descriptors you need to recurse
2196 * into the array manually.
2198 * Unix file descriptors that are read with this function will have
2199 * the FD_CLOEXEC flag set. If you need them without this flag set,
2200 * make sure to unset it with fcntl().
2202 * The variable argument list should contain the type of the argument
2203 * followed by a pointer to where the value should be stored. The list
2204 * is terminated with #DBUS_TYPE_INVALID.
2206 * Except for string arrays, the returned values are constant; do not
2207 * free them. They point into the #DBusMessage.
2209 * If the requested arguments are not present, or do not have the
2210 * requested types, then an error will be set.
2212 * If more arguments than requested are present, the requested
2213 * arguments are returned and the extra arguments are ignored.
2215 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
2217 * @param message the message
2218 * @param error error to be filled in on failure
2219 * @param first_arg_type the first argument type
2220 * @param ... location for first argument value, then list of type-location pairs
2221 * @returns #FALSE if the error was set
2224 dbus_message_get_args (DBusMessage *message,
2232 _dbus_return_val_if_fail (message != NULL, FALSE);
2233 _dbus_return_val_if_error_is_set (error, FALSE);
2235 va_start (var_args, first_arg_type);
2236 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
2243 * Like dbus_message_get_args but takes a va_list for use by language bindings.
2245 * @see dbus_message_get_args
2246 * @param message the message
2247 * @param error error to be filled in
2248 * @param first_arg_type type of the first argument
2249 * @param var_args return location for first argument, followed by list of type/location pairs
2250 * @returns #FALSE if error was set
2253 dbus_message_get_args_valist (DBusMessage *message,
2258 DBusMessageIter iter;
2260 _dbus_return_val_if_fail (message != NULL, FALSE);
2261 _dbus_return_val_if_error_is_set (error, FALSE);
2263 dbus_message_iter_init (message, &iter);
2264 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
2268 _dbus_message_iter_init_common (DBusMessage *message,
2269 DBusMessageRealIter *real,
2272 /* If these static assertions fail on your platform, report it as a bug. */
2273 _DBUS_STATIC_ASSERT (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
2274 _DBUS_STATIC_ASSERT (_DBUS_ALIGNOF (DBusMessageRealIter) <=
2275 _DBUS_ALIGNOF (DBusMessageIter));
2276 /* A failure of these two assertions would indicate that we've broken
2277 * ABI on this platform since 1.10.0. */
2278 _DBUS_STATIC_ASSERT (sizeof (DBusMessageIter_1_10_0) ==
2279 sizeof (DBusMessageIter));
2280 _DBUS_STATIC_ASSERT (_DBUS_ALIGNOF (DBusMessageIter_1_10_0) ==
2281 _DBUS_ALIGNOF (DBusMessageIter));
2282 /* If this static assertion fails, it means the DBusMessageIter struct
2283 * is not "packed", which might result in "iter = other_iter" not copying
2285 _DBUS_STATIC_ASSERT (sizeof (DBusMessageIter) ==
2286 10 * sizeof (void *) + sizeof (dbus_uint32_t) + 3 * sizeof (int));
2288 /* Since the iterator will read or write who-knows-what from the
2289 * message, we need to get in the right byte order
2291 ensure_byte_order (message);
2293 real->message = message;
2294 real->changed_stamp = message->changed_stamp;
2295 real->iter_type = iter_type;
2296 real->sig_refcount = 0;
2300 * Initializes a #DBusMessageIter for reading the arguments of the
2301 * message passed in.
2303 * When possible, dbus_message_get_args() is much more convenient.
2304 * Some types of argument can only be read with #DBusMessageIter
2307 * The easiest way to iterate is like this:
2309 * dbus_message_iter_init (message, &iter);
2310 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2311 * dbus_message_iter_next (&iter);
2314 * #DBusMessageIter contains no allocated memory; it need not be
2315 * freed, and can be copied by assignment or memcpy().
2317 * @param message the message
2318 * @param iter pointer to an iterator to initialize
2319 * @returns #FALSE if the message has no arguments
2322 dbus_message_iter_init (DBusMessage *message,
2323 DBusMessageIter *iter)
2325 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2326 const DBusString *type_str;
2329 BUILD_BUG_ON (sizeof(DBusMessageIter) != sizeof(DBusMessageRealIter));
2331 _dbus_return_val_if_fail (message != NULL, FALSE);
2332 _dbus_return_val_if_fail (iter != NULL, FALSE);
2334 get_const_signature (message, &type_str, &type_pos);
2336 _dbus_message_iter_init_common (message, real,
2337 DBUS_MESSAGE_ITER_TYPE_READER);
2339 _dbus_type_reader_init (&real->u.reader,
2340 _dbus_header_get_byte_order (&message->header),
2345 if (_dbus_message_is_gvariant (message))
2346 _dbus_type_reader_gvariant_init (&real->u.reader, message);
2348 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
2352 * Checks if an iterator has any more fields.
2354 * @param iter the message iter
2355 * @returns #TRUE if there are more fields following
2358 dbus_message_iter_has_next (DBusMessageIter *iter)
2360 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2362 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2363 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2365 return _dbus_type_reader_has_next (&real->u.reader);
2369 * Moves the iterator to the next field, if any. If there's no next
2370 * field, returns #FALSE. If the iterator moves forward, returns
2373 * @param iter the message iter
2374 * @returns #TRUE if the iterator was moved to the next field
2377 dbus_message_iter_next (DBusMessageIter *iter)
2379 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2381 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2382 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2384 return _dbus_type_reader_next (&real->u.reader);
2388 * Returns the argument type of the argument that the message iterator
2389 * points to. If the iterator is at the end of the message, returns
2390 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
2393 * dbus_message_iter_init (message, &iter);
2394 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2395 * dbus_message_iter_next (&iter);
2398 * @param iter the message iter
2399 * @returns the argument type
2402 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
2404 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2406 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2407 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2409 return _dbus_type_reader_get_current_type (&real->u.reader);
2413 * Returns the element type of the array that the message iterator
2414 * points to. Note that you need to check that the iterator points to
2415 * an array prior to using this function.
2417 * @param iter the message iter
2418 * @returns the array element type
2421 dbus_message_iter_get_element_type (DBusMessageIter *iter)
2423 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2425 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2426 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
2427 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
2429 return _dbus_type_reader_get_element_type (&real->u.reader);
2433 * Recurses into a container value when reading values from a message,
2434 * initializing a sub-iterator to use for traversing the child values
2437 * Note that this recurses into a value, not a type, so you can only
2438 * recurse if the value exists. The main implication of this is that
2439 * if you have for example an empty array of array of int32, you can
2440 * recurse into the outermost array, but it will have no values, so
2441 * you won't be able to recurse further. There's no array of int32 to
2444 * If a container is an array of fixed-length types (except Unix file
2445 * descriptors), it is much more efficient to use
2446 * dbus_message_iter_get_fixed_array() to get the whole array in one
2447 * shot, rather than individually walking over the array elements.
2449 * Be sure you have somehow checked that
2450 * dbus_message_iter_get_arg_type() matches the type you are expecting
2451 * to recurse into. Results of this function are undefined if there is
2452 * no container to recurse into at the current iterator position.
2454 * @param iter the message iterator
2455 * @param sub the sub-iterator to initialize
2458 dbus_message_iter_recurse (DBusMessageIter *iter,
2459 DBusMessageIter *sub)
2461 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2462 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2464 _dbus_return_if_fail (_dbus_message_iter_check (real));
2465 _dbus_return_if_fail (sub != NULL);
2468 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
2472 * Returns the current signature of a message iterator. This
2473 * is useful primarily for dealing with variants; one can
2474 * recurse into a variant and determine the signature of
2475 * the variant's value.
2477 * The returned string must be freed with dbus_free().
2479 * @param iter the message iterator
2480 * @returns the contained signature, or NULL if out of memory
2483 dbus_message_iter_get_signature (DBusMessageIter *iter)
2485 const DBusString *sig;
2489 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2491 _dbus_return_val_if_fail (_dbus_message_iter_check (real), NULL);
2493 if (!_dbus_string_init (&retstr))
2496 _dbus_type_reader_get_signature (&real->u.reader, &sig,
2498 if (!_dbus_string_append_len (&retstr,
2499 _dbus_string_get_const_data (sig) + start,
2502 if (!_dbus_string_steal_data (&retstr, &ret))
2504 _dbus_string_free (&retstr);
2509 * Reads a basic-typed value from the message iterator.
2510 * Basic types are the non-containers such as integer and string.
2512 * The value argument should be the address of a location to store
2513 * the returned value. So for int32 it should be a "dbus_int32_t*"
2514 * and for string a "const char**". The returned value is
2515 * by reference and should not be freed.
2517 * This call duplicates Unix file descriptors when reading them. It is
2518 * your job to close them when you don't need them anymore.
2520 * Unix file descriptors that are read with this function will have
2521 * the FD_CLOEXEC flag set. If you need them without this flag set,
2522 * make sure to unset it with fcntl().
2524 * Be sure you have somehow checked that
2525 * dbus_message_iter_get_arg_type() matches the type you are
2526 * expecting, or you'll crash when you try to use an integer as a
2527 * string or something.
2529 * To read any container type (array, struct, dict) you will need to
2530 * recurse into the container with dbus_message_iter_recurse(). If
2531 * the container is an array of fixed-length values (except Unix file
2532 * descriptors), you can get all the array elements at once with
2533 * dbus_message_iter_get_fixed_array(). Otherwise, you have to iterate
2534 * over the container's contents one value at a time.
2536 * All basic-typed values are guaranteed to fit in a #DBusBasicValue,
2537 * so in versions of libdbus that have that type, you can write code like this:
2540 * DBusBasicValue value;
2542 * dbus_message_iter_get_basic (&read_iter, &value);
2543 * type = dbus_message_iter_get_arg_type (&read_iter);
2544 * dbus_message_iter_append_basic (&write_iter, type, &value);
2547 * (All D-Bus basic types are either numeric and 8 bytes or smaller, or
2548 * behave like a string; so in older versions of libdbus, DBusBasicValue
2549 * can be replaced with union { char *string; unsigned char bytes[8]; },
2552 * @param iter the iterator
2553 * @param value location to store the value
2556 dbus_message_iter_get_basic (DBusMessageIter *iter,
2559 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2561 _dbus_return_if_fail (_dbus_message_iter_check (real));
2562 _dbus_return_if_fail (value != NULL);
2564 if (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_UNIX_FD)
2566 #ifdef HAVE_UNIX_FD_PASSING
2569 _dbus_type_reader_read_basic(&real->u.reader, &idx);
2571 if (idx.u32 >= real->message->n_unix_fds) {
2572 /* Hmm, we cannot really signal an error here, so let's make
2573 sure to return an invalid fd. */
2574 *((int*) value) = -1;
2578 *((int*) value) = _dbus_dup(real->message->unix_fds[idx.u32], NULL);
2580 *((int*) value) = -1;
2585 _dbus_type_reader_read_basic (&real->u.reader,
2591 * Returns the number of elements in the array-typed value pointed
2592 * to by the iterator.
2593 * Note that this function is O(1) for arrays of fixed-size types
2594 * but O(n) for arrays of variable-length types such as strings,
2595 * so it may be a bad idea to use it.
2597 * @param iter the iterator
2598 * @returns the number of elements in the array
2601 dbus_message_iter_get_element_count (DBusMessageIter *iter)
2603 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2604 DBusTypeReader array;
2608 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2609 _dbus_return_val_if_fail (_dbus_type_reader_get_current_type (&real->u.reader)
2610 == DBUS_TYPE_ARRAY, 0);
2612 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
2613 _dbus_type_reader_recurse (&real->u.reader, &array);
2614 if (dbus_type_is_fixed (element_type))
2616 int alignment = _dbus_type_get_alignment (element_type);
2617 int total_len = _dbus_type_reader_get_array_length (&array);
2618 n_elements = total_len / alignment;
2622 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
2625 _dbus_type_reader_next (&array);
2633 * Returns the number of bytes in the array as marshaled in the wire
2634 * protocol. The iterator must currently be inside an array-typed
2637 * This function is deprecated on the grounds that it is stupid. Why
2638 * would you want to know how many bytes are in the array as marshaled
2639 * in the wire protocol? Use dbus_message_iter_get_element_count() instead.
2641 * @param iter the iterator
2642 * @returns the number of bytes in the array
2645 dbus_message_iter_get_array_len (DBusMessageIter *iter)
2647 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2649 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2651 return _dbus_type_reader_get_array_length (&real->u.reader);
2655 * Reads a block of fixed-length values from the message iterator.
2656 * Fixed-length values are those basic types that are not string-like,
2657 * such as integers, bool, double. The returned block will be from the
2658 * current position in the array until the end of the array.
2660 * There is one exception here: although DBUS_TYPE_UNIX_FD is
2661 * considered a 'fixed' type arrays of this type may not be read with
2664 * The message iter should be "in" the array (that is, you recurse into the
2665 * array, and then you call dbus_message_iter_get_fixed_array() on the
2666 * "sub-iterator" created by dbus_message_iter_recurse()).
2668 * The value argument should be the address of a location to store the
2669 * returned array. So for int32 it should be a "const dbus_int32_t**"
2670 * The returned value is by reference and should not be freed.
2672 * This function should only be used if dbus_type_is_fixed() returns
2673 * #TRUE for the element type.
2675 * If an array's elements are not fixed in size, you have to recurse
2676 * into the array with dbus_message_iter_recurse() and read the
2677 * elements one by one.
2679 * Because the array is not copied, this function runs in constant
2680 * time and is fast; it's much preferred over walking the entire array
2681 * with an iterator. (However, you can always use
2682 * dbus_message_iter_recurse(), even for fixed-length types;
2683 * dbus_message_iter_get_fixed_array() is just an optimization.)
2685 * @param iter the iterator
2686 * @param value location to store the block
2687 * @param n_elements number of elements in the block
2690 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
2694 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2695 #ifndef DBUS_DISABLE_CHECKS
2696 int subtype = _dbus_type_reader_get_current_type(&real->u.reader);
2698 _dbus_return_if_fail (_dbus_message_iter_check (real));
2699 _dbus_return_if_fail (value != NULL);
2700 _dbus_return_if_fail ((subtype == DBUS_TYPE_INVALID) ||
2701 (dbus_type_is_fixed (subtype) && subtype != DBUS_TYPE_UNIX_FD));
2704 _dbus_type_reader_read_fixed_multi (&real->u.reader,
2709 * Initializes a #DBusMessageIter for appending arguments to the end
2712 * @todo If appending any of the arguments fails due to lack of
2713 * memory, the message is hosed and you have to start over building
2714 * the whole message.
2716 * @param message the message
2717 * @param iter pointer to an iterator to initialize
2720 dbus_message_iter_init_append (DBusMessage *message,
2721 DBusMessageIter *iter)
2723 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2725 _dbus_return_if_fail (message != NULL);
2726 _dbus_return_if_fail (iter != NULL);
2728 _dbus_message_iter_init_common (message, real,
2729 DBUS_MESSAGE_ITER_TYPE_WRITER);
2731 /* We create the signature string and point iterators at it "on demand"
2732 * when a value is actually appended. That means that init() never fails
2735 _dbus_type_writer_gvariant_init_types_delayed (
2737 _dbus_header_get_byte_order (&message->header),
2739 _dbus_string_get_length (&message->body),
2740 _dbus_message_is_gvariant (message),
2741 &message->gvariant_body_last_offset,
2742 &message->gvariant_body_last_pos);
2746 * Creates a temporary signature string containing the current
2747 * signature, stores it in the iterator, and points the iterator to
2748 * the end of it. Used any time we write to the message.
2750 * @param real an iterator without a type_str
2751 * @returns #FALSE if no memory
2754 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
2757 const DBusString *current_sig;
2758 int current_sig_pos;
2760 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2762 if (real->u.writer.type_str != NULL)
2764 _dbus_assert (real->sig_refcount > 0);
2765 real->sig_refcount += 1;
2769 str = dbus_new (DBusString, 1);
2773 if (!_dbus_header_get_field_raw (&real->message->header,
2774 DBUS_HEADER_FIELD_SIGNATURE,
2775 ¤t_sig, ¤t_sig_pos))
2781 int additional_size_for_len = 0;
2783 if (!real->u.writer.gvariant)
2785 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
2786 current_sig_pos += 1; /* move on to sig data */
2787 additional_size_for_len = 4;
2791 /* GVariant has no length field, simply string */
2792 current_len = strlen (_dbus_string_get_const_data (current_sig) + current_sig_pos);
2795 if (!_dbus_string_init_preallocated (str, current_len + additional_size_for_len))
2801 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
2804 _dbus_string_free (str);
2811 if (!_dbus_string_init_preallocated (str, 4))
2818 real->sig_refcount = 1;
2820 /* If this assertion failed, then str would be neither stored in u.writer
2821 * nor freed by this function, resulting in a memory leak. */
2822 _dbus_assert (real->u.writer.type_str == NULL);
2823 _dbus_type_writer_add_types (&real->u.writer,
2824 str, _dbus_string_get_length (str));
2829 * Sets the new signature as the message signature, frees the
2830 * signature string, and marks the iterator as not having a type_str
2831 * anymore. Frees the signature even if it fails, so you can't
2832 * really recover from failure. Kinda busted.
2834 * @param real an iterator without a type_str
2835 * @returns #FALSE if no memory
2838 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2841 const char *v_STRING;
2844 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2845 _dbus_assert (real->u.writer.type_str != NULL);
2846 _dbus_assert (real->sig_refcount > 0);
2848 real->sig_refcount -= 1;
2850 if (real->sig_refcount > 0)
2852 _dbus_assert (real->sig_refcount == 0);
2856 str = real->u.writer.type_str;
2858 v_STRING = _dbus_string_get_const_data (str);
2859 if (!_dbus_header_set_field_basic (&real->message->header,
2860 DBUS_HEADER_FIELD_SIGNATURE,
2861 DBUS_TYPE_SIGNATURE,
2865 _dbus_type_writer_remove_types (&real->u.writer);
2866 _dbus_string_free (str);
2873 * Frees the signature string and marks the iterator as not having a
2874 * type_str anymore. Since the new signature is not set, the message
2875 * will generally be hosed after this is called.
2877 * @param real an iterator without a type_str
2880 _dbus_message_iter_abandon_signature (DBusMessageRealIter *real)
2884 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2885 _dbus_assert (real->u.writer.type_str != NULL);
2886 _dbus_assert (real->sig_refcount > 0);
2888 real->sig_refcount -= 1;
2890 if (real->sig_refcount > 0)
2892 _dbus_assert (real->sig_refcount == 0);
2894 str = real->u.writer.type_str;
2896 _dbus_type_writer_remove_types (&real->u.writer);
2897 _dbus_string_free (str);
2901 #ifndef DBUS_DISABLE_CHECKS
2903 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2905 if (!_dbus_message_iter_check (iter))
2908 if (iter->message->locked)
2910 _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)");
2916 #endif /* DBUS_DISABLE_CHECKS */
2918 #ifdef HAVE_UNIX_FD_PASSING
2920 expand_fd_array(DBusMessage *m,
2925 /* This makes space for adding n new fds to the array and returns a
2926 pointer to the place were the first fd should be put. */
2928 if (m->n_unix_fds + n > m->n_unix_fds_allocated)
2933 /* Make twice as much space as necessary */
2934 k = (m->n_unix_fds + n) * 2;
2936 /* Allocate at least four */
2940 p = dbus_realloc(m->unix_fds, k * sizeof(int));
2945 m->n_unix_fds_allocated = k;
2948 return m->unix_fds + m->n_unix_fds;
2953 * Appends a basic-typed value to the message. The basic types are the
2954 * non-container types such as integer and string.
2956 * The "value" argument should be the address of a basic-typed value.
2957 * So for string, const char**. For integer, dbus_int32_t*.
2959 * For Unix file descriptors this function will internally duplicate
2960 * the descriptor you passed in. Hence you may close the descriptor
2961 * immediately after this call.
2963 * @todo If this fails due to lack of memory, the message is hosed and
2964 * you have to start over building the whole message.
2966 * @param iter the append iterator
2967 * @param type the type of the value
2968 * @param value the address of the value
2969 * @returns #FALSE if not enough memory
2972 dbus_message_iter_append_basic (DBusMessageIter *iter,
2976 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2979 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2980 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2981 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2982 _dbus_return_val_if_fail (value != NULL, FALSE);
2984 #ifndef DBUS_DISABLE_CHECKS
2988 DBusValidity signature_validity;
2989 const char * const *string_p;
2990 const dbus_bool_t *bool_p;
2992 case DBUS_TYPE_STRING:
2994 _dbus_return_val_if_fail (_dbus_check_is_valid_utf8 (*string_p), FALSE);
2997 case DBUS_TYPE_OBJECT_PATH:
2999 _dbus_return_val_if_fail (_dbus_check_is_valid_path (*string_p), FALSE);
3002 case DBUS_TYPE_SIGNATURE:
3004 _dbus_string_init_const (&str, *string_p);
3005 signature_validity = _dbus_validate_signature_with_reason (&str,
3007 _dbus_string_get_length (&str));
3009 if (signature_validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
3012 _dbus_return_val_if_fail (signature_validity == DBUS_VALID, FALSE);
3015 case DBUS_TYPE_BOOLEAN:
3017 _dbus_return_val_if_fail (*bool_p == 0 || *bool_p == 1, FALSE);
3022 /* nothing to check, all possible values are allowed */
3027 if (!_dbus_message_iter_open_signature (real))
3030 if (type == DBUS_TYPE_UNIX_FD)
3032 #ifdef HAVE_UNIX_FD_PASSING
3038 /* First step, include the fd in the fd list of this message */
3039 if (!(fds = expand_fd_array(real->message, 1)))
3042 *fds = _dbus_dup(*(int*) value, NULL);
3046 u = real->message->n_unix_fds;
3048 /* Second step, write the index to the fd */
3049 if (!(ret = _dbus_type_writer_write_basic (&real->u.writer, DBUS_TYPE_UNIX_FD, &u))) {
3050 _dbus_close(*fds, NULL);
3054 real->message->n_unix_fds += 1;
3057 /* Final step, update the header accordingly */
3058 ret = _dbus_header_set_field_basic (&real->message->header,
3059 DBUS_HEADER_FIELD_UNIX_FDS,
3063 /* If any of these operations fail the message is
3064 hosed. However, no memory or fds should be leaked since what
3065 has been added to message has been added to the message, and
3066 can hence be accounted for when the message is being
3070 /* This is redundant (we could just fall through), but it avoids
3071 * -Wunused-label in builds that don't HAVE_UNIX_FD_PASSING */
3077 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
3081 if (!_dbus_message_iter_close_signature (real))
3088 * Appends a block of fixed-length values to an array. The
3089 * fixed-length types are all basic types that are not string-like. So
3090 * int32, double, bool, etc. (Unix file descriptors however are not
3091 * supported.) You must call dbus_message_iter_open_container() to
3092 * open an array of values before calling this function. You may call
3093 * this function multiple times (and intermixed with calls to
3094 * dbus_message_iter_append_basic()) for the same array.
3096 * The "value" argument should be the address of the array. So for
3097 * integer, "dbus_int32_t**" is expected for example.
3099 * @warning in C, given "int array[]", "&array == array" (the
3100 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
3101 * So if you're using an array instead of a pointer you have to create
3102 * a pointer variable, assign the array to it, then take the address
3103 * of the pointer variable.
3105 * const dbus_int32_t array[] = { 1, 2, 3 };
3106 * const dbus_int32_t *v_ARRAY = array;
3107 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
3108 * fprintf (stderr, "No memory!\n");
3110 * For strings it works to write const char *array = "Hello" and then
3111 * use &array though.
3113 * @todo If this fails due to lack of memory, the message is hosed and
3114 * you have to start over building the whole message.
3116 * @param iter the append iterator
3117 * @param element_type the type of the array elements
3118 * @param value the address of the array
3119 * @param n_elements the number of elements to append
3120 * @returns #FALSE if not enough memory
3123 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
3128 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
3131 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
3132 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
3133 _dbus_return_val_if_fail (dbus_type_is_fixed (element_type) && element_type != DBUS_TYPE_UNIX_FD, FALSE);
3134 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
3135 _dbus_return_val_if_fail (value != NULL, FALSE);
3136 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
3137 _dbus_return_val_if_fail (n_elements <=
3138 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
3141 #ifndef DBUS_DISABLE_CHECKS
3142 if (element_type == DBUS_TYPE_BOOLEAN)
3144 const dbus_bool_t * const *bools = value;
3147 for (i = 0; i < n_elements; i++)
3149 _dbus_return_val_if_fail ((*bools)[i] == 0 || (*bools)[i] == 1, FALSE);
3154 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
3160 * Appends a container-typed value to the message. On success, you are
3161 * required to append the contents of the container using the returned
3162 * sub-iterator, and then call
3163 * dbus_message_iter_close_container(). Container types are for
3164 * example struct, variant, and array. For variants, the
3165 * contained_signature should be the type of the single value inside
3166 * the variant. For structs and dict entries, contained_signature
3167 * should be #NULL; it will be set to whatever types you write into
3168 * the struct. For arrays, contained_signature should be the type of
3169 * the array elements.
3171 * @todo If this fails due to lack of memory, the message is hosed and
3172 * you have to start over building the whole message.
3174 * If this function fails, the sub-iterator remains invalid, and must
3175 * not be closed with dbus_message_iter_close_container() or abandoned
3176 * with dbus_message_iter_abandon_container(). However, after this
3177 * function has either succeeded or failed, it is valid to call
3178 * dbus_message_iter_abandon_container_if_open().
3180 * @param iter the append iterator
3181 * @param type the type of the value
3182 * @param contained_signature the type of container contents
3183 * @param sub sub-iterator to initialize
3184 * @returns #FALSE if not enough memory
3187 dbus_message_iter_open_container (DBusMessageIter *iter,
3189 const char *contained_signature,
3190 DBusMessageIter *sub)
3192 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
3193 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
3194 DBusString contained_str;
3195 DBusValidity contained_signature_validity;
3198 _dbus_return_val_if_fail (sub != NULL, FALSE);
3199 /* Do our best to make sure the sub-iterator doesn't contain something
3200 * valid-looking on failure */
3201 _dbus_message_real_iter_zero (real_sub);
3203 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
3204 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
3205 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
3206 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
3207 contained_signature == NULL) ||
3208 (type == DBUS_TYPE_DICT_ENTRY &&
3209 contained_signature == NULL) ||
3210 (type == DBUS_TYPE_VARIANT &&
3211 contained_signature != NULL) ||
3212 (type == DBUS_TYPE_ARRAY &&
3213 contained_signature != NULL), FALSE);
3215 /* this would fail if the contained_signature is a dict entry, since
3216 * dict entries are invalid signatures standalone (they must be in
3219 if (contained_signature != NULL)
3221 _dbus_string_init_const (&contained_str, contained_signature);
3222 contained_signature_validity = _dbus_validate_signature_with_reason (&contained_str,
3224 _dbus_string_get_length (&contained_str));
3226 if (contained_signature_validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
3231 /* just some placeholder value */
3232 contained_signature_validity = DBUS_VALID_BUT_INCOMPLETE;
3235 _dbus_return_val_if_fail ((type == DBUS_TYPE_ARRAY && contained_signature && *contained_signature == DBUS_DICT_ENTRY_BEGIN_CHAR) ||
3236 contained_signature == NULL ||
3237 contained_signature_validity == DBUS_VALID,
3240 if (!_dbus_message_iter_open_signature (real))
3246 if (contained_signature != NULL)
3248 _dbus_string_init_const (&contained_str, contained_signature);
3250 ret = _dbus_type_writer_recurse (&real->u.writer,
3253 &real_sub->u.writer);
3257 ret = _dbus_type_writer_recurse (&real->u.writer,
3260 &real_sub->u.writer);
3264 _dbus_message_iter_abandon_signature (real);
3271 * Closes a container-typed value appended to the message; may write
3272 * out more information to the message known only after the entire
3273 * container is written, and may free resources created by
3274 * dbus_message_iter_open_container().
3276 * Even if this function fails due to lack of memory, the sub-iterator sub
3277 * has been closed and invalidated. It must not be closed again with this
3278 * function, or abandoned with dbus_message_iter_abandon_container().
3279 * However, it remains valid to call
3280 * dbus_message_iter_abandon_container_if_open().
3282 * @todo If this fails due to lack of memory, the message is hosed and
3283 * you have to start over building the whole message.
3285 * @param iter the append iterator
3286 * @param sub sub-iterator to close
3287 * @returns #FALSE if not enough memory
3290 dbus_message_iter_close_container (DBusMessageIter *iter,
3291 DBusMessageIter *sub)
3293 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
3294 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
3297 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
3298 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
3299 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
3300 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
3302 ret = _dbus_type_writer_unrecurse (&real->u.writer,
3303 &real_sub->u.writer);
3304 _dbus_message_real_iter_zero (real_sub);
3306 if (!_dbus_message_iter_close_signature (real))
3313 * Abandons creation of a contained-typed value and frees resources created
3314 * by dbus_message_iter_open_container(). Once this returns, the message
3315 * is hosed and you have to start over building the whole message.
3317 * This should only be used to abandon creation of a message when you have
3320 * @param iter the append iterator
3321 * @param sub sub-iterator to close
3324 dbus_message_iter_abandon_container (DBusMessageIter *iter,
3325 DBusMessageIter *sub)
3327 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
3328 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
3330 #ifndef DBUS_DISABLE_CHECKS
3331 _dbus_return_if_fail (_dbus_message_iter_append_check (real));
3332 _dbus_return_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
3333 _dbus_return_if_fail (_dbus_message_iter_append_check (real_sub));
3334 _dbus_return_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
3337 _dbus_message_iter_abandon_signature (real);
3338 _dbus_message_real_iter_zero (real_sub);
3342 * Abandons creation of a contained-typed value and frees resources created
3343 * by dbus_message_iter_open_container(). Once this returns, the message
3344 * is hosed and you have to start over building the whole message.
3346 * Unlike dbus_message_iter_abandon_container(), it is valid to call this
3347 * function on an iterator that was initialized with
3348 * #DBUS_MESSAGE_ITER_INIT_CLOSED, or an iterator that was already closed
3349 * or abandoned. However, it is not valid to call this function on
3350 * uninitialized memory. This is intended to be used in error cleanup
3351 * code paths, similar to this pattern:
3353 * DBusMessageIter outer = DBUS_MESSAGE_ITER_INIT_CLOSED;
3354 * DBusMessageIter inner = DBUS_MESSAGE_ITER_INIT_CLOSED;
3355 * dbus_bool_t result = FALSE;
3357 * if (!dbus_message_iter_open_container (iter, ..., &outer))
3360 * if (!dbus_message_iter_open_container (&outer, ..., &inner))
3363 * if (!dbus_message_iter_append_basic (&inner, ...))
3366 * if (!dbus_message_iter_close_container (&outer, ..., &inner))
3369 * if (!dbus_message_iter_close_container (iter, ..., &outer))
3375 * dbus_message_iter_abandon_container_if_open (&outer, &inner);
3376 * dbus_message_iter_abandon_container_if_open (iter, &outer);
3379 * @param iter the append iterator
3380 * @param sub sub-iterator to close
3383 dbus_message_iter_abandon_container_if_open (DBusMessageIter *iter,
3384 DBusMessageIter *sub)
3386 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
3387 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
3389 /* If both the parent and the child are zeroed out, then either we didn't
3390 * even get as far as successfully recursing into the parent, or we already
3391 * closed both the child and the parent. For example, in the code sample
3392 * in the doc-comment above, this happens for
3393 * abandon_container_if_open (&outer, &inner) if the first open_container
3394 * call failed, or if we reached result = TRUE and fell through. */
3395 if (_dbus_message_real_iter_is_zeroed (real) &&
3396 _dbus_message_real_iter_is_zeroed (real_sub))
3399 #ifndef DBUS_DISABLE_CHECKS
3400 /* If the child is not zeroed out, but the parent is, then something has
3401 * gone horribly wrong (in practice that would probably mean both are
3402 * uninitialized or corrupt, and the parent happens to have ended up
3403 * all-bytes-zero). */
3404 _dbus_return_if_fail (_dbus_message_iter_append_check (real));
3405 _dbus_return_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
3408 /* If the parent is not zeroed out, but the child is, then either we did
3409 * not successfully open the child, or we already closed the child. This
3410 * means we do not own a reference to the parent's signature, so it would
3411 * be wrong to release it; so we must not call abandon_signature() here.
3412 * In the code sample in the doc-comment above, this happens for
3413 * abandon_container_if_open (&outer, &inner) if the second open_container
3414 * call failed, or if the second close_container call failed. */
3415 if (_dbus_message_real_iter_is_zeroed (real_sub))
3418 #ifndef DBUS_DISABLE_CHECKS
3419 _dbus_return_if_fail (_dbus_message_iter_append_check (real_sub));
3420 _dbus_return_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
3423 /* If neither the parent nor the child is zeroed out, then we genuinely
3424 * have an open container; close it. In the code sample in the doc-comment,
3425 * this happens for abandon_container_if_open (&outer, &inner) if the
3426 * append_basic call failed. */
3427 _dbus_message_iter_abandon_signature (real);
3428 _dbus_message_real_iter_zero (real_sub);
3432 * Sets a flag indicating that the message does not want a reply; if
3433 * this flag is set, the other end of the connection may (but is not
3434 * required to) optimize by not sending method return or error
3435 * replies. If this flag is set, there is no way to know whether the
3436 * message successfully arrived at the remote end. Normally you know a
3437 * message was received when you receive the reply to it.
3439 * The flag is #FALSE by default, that is by default the other end is
3440 * required to reply.
3442 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
3444 * @param message the message
3445 * @param no_reply #TRUE if no reply is desired
3448 dbus_message_set_no_reply (DBusMessage *message,
3449 dbus_bool_t no_reply)
3451 _dbus_return_if_fail (message != NULL);
3452 _dbus_return_if_fail (!message->locked);
3454 _dbus_header_toggle_flag (&message->header,
3455 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
3460 * Returns #TRUE if the message does not expect
3463 * @param message the message
3464 * @returns #TRUE if the message sender isn't waiting for a reply
3467 dbus_message_get_no_reply (DBusMessage *message)
3469 _dbus_return_val_if_fail (message != NULL, FALSE);
3471 return _dbus_header_get_flag (&message->header,
3472 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
3476 * Sets a flag indicating that an owner for the destination name will
3477 * be automatically started before the message is delivered. When this
3478 * flag is set, the message is held until a name owner finishes
3479 * starting up, or fails to start up. In case of failure, the reply
3482 * The flag is set to #TRUE by default, i.e. auto starting is the default.
3484 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
3486 * @param message the message
3487 * @param auto_start #TRUE if auto-starting is desired
3490 dbus_message_set_auto_start (DBusMessage *message,
3491 dbus_bool_t auto_start)
3493 _dbus_return_if_fail (message != NULL);
3494 _dbus_return_if_fail (!message->locked);
3496 _dbus_header_toggle_flag (&message->header,
3497 DBUS_HEADER_FLAG_NO_AUTO_START,
3502 * Returns #TRUE if the message will cause an owner for
3503 * destination name to be auto-started.
3505 * @param message the message
3506 * @returns #TRUE if the message will use auto-start
3509 dbus_message_get_auto_start (DBusMessage *message)
3511 _dbus_return_val_if_fail (message != NULL, FALSE);
3513 return !_dbus_header_get_flag (&message->header,
3514 DBUS_HEADER_FLAG_NO_AUTO_START);
3519 * Sets the object path this message is being sent to (for
3520 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
3521 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
3523 * The path must contain only valid characters as defined
3524 * in the D-Bus specification.
3526 * @param message the message
3527 * @param object_path the path or #NULL to unset
3528 * @returns #FALSE if not enough memory
3531 dbus_message_set_path (DBusMessage *message,
3532 const char *object_path)
3534 _dbus_return_val_if_fail (message != NULL, FALSE);
3535 _dbus_return_val_if_fail (!message->locked, FALSE);
3536 _dbus_return_val_if_fail (object_path == NULL ||
3537 _dbus_check_is_valid_path (object_path),
3540 return set_or_delete_string_field (message,
3541 DBUS_HEADER_FIELD_PATH,
3542 DBUS_TYPE_OBJECT_PATH,
3547 * Gets the object path this message is being sent to (for
3548 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
3549 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3551 * See also dbus_message_get_path_decomposed().
3553 * The returned string becomes invalid if the message is
3554 * modified, since it points into the wire-marshaled message data.
3556 * @param message the message
3557 * @returns the path (should not be freed) or #NULL
3560 dbus_message_get_path (DBusMessage *message)
3564 _dbus_return_val_if_fail (message != NULL, NULL);
3566 v = NULL; /* in case field doesn't exist */
3567 _dbus_header_get_field_basic (&message->header,
3568 DBUS_HEADER_FIELD_PATH,
3569 DBUS_TYPE_OBJECT_PATH,
3575 * Checks if the message has a particular object path. The object
3576 * path is the destination object for a method call or the emitting
3577 * object for a signal.
3579 * @param message the message
3580 * @param path the path name
3581 * @returns #TRUE if there is a path field in the header
3584 dbus_message_has_path (DBusMessage *message,
3587 const char *msg_path;
3588 msg_path = dbus_message_get_path (message);
3590 if (msg_path == NULL)
3601 if (strcmp (msg_path, path) == 0)
3608 * Gets the object path this message is being sent to
3609 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3610 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
3611 * format (one array element per path component).
3612 * Free the returned array with dbus_free_string_array().
3614 * An empty but non-NULL path array means the path "/".
3615 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
3616 * and the path "/" becomes { NULL }.
3618 * See also dbus_message_get_path().
3620 * @todo this could be optimized by using the len from the message
3621 * instead of calling strlen() again
3623 * @param message the message
3624 * @param path place to store allocated array of path components; #NULL set here if no path field exists
3625 * @returns #FALSE if no memory to allocate the array
3628 dbus_message_get_path_decomposed (DBusMessage *message,
3633 _dbus_return_val_if_fail (message != NULL, FALSE);
3634 _dbus_return_val_if_fail (path != NULL, FALSE);
3638 v = dbus_message_get_path (message);
3641 if (!_dbus_decompose_path (v, strlen (v),
3649 * Sets the interface this message is being sent to
3650 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
3651 * the interface a signal is being emitted from
3652 * (for DBUS_MESSAGE_TYPE_SIGNAL).
3654 * The interface name must contain only valid characters as defined
3655 * in the D-Bus specification.
3657 * @param message the message
3658 * @param iface the interface or #NULL to unset
3659 * @returns #FALSE if not enough memory
3662 dbus_message_set_interface (DBusMessage *message,
3665 _dbus_return_val_if_fail (message != NULL, FALSE);
3666 _dbus_return_val_if_fail (!message->locked, FALSE);
3667 _dbus_return_val_if_fail (iface == NULL ||
3668 _dbus_check_is_valid_interface (iface),
3671 return set_or_delete_string_field (message,
3672 DBUS_HEADER_FIELD_INTERFACE,
3678 * Gets the interface this message is being sent to
3679 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3680 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
3681 * The interface name is fully-qualified (namespaced).
3682 * Returns #NULL if none.
3684 * The returned string becomes invalid if the message is
3685 * modified, since it points into the wire-marshaled message data.
3687 * @param message the message
3688 * @returns the message interface (should not be freed) or #NULL
3691 dbus_message_get_interface (DBusMessage *message)
3695 _dbus_return_val_if_fail (message != NULL, NULL);
3697 v = NULL; /* in case field doesn't exist */
3698 _dbus_header_get_field_basic (&message->header,
3699 DBUS_HEADER_FIELD_INTERFACE,
3706 * Checks if the message has an interface
3708 * @param message the message
3709 * @param iface the interface name
3710 * @returns #TRUE if the interface field in the header matches
3713 dbus_message_has_interface (DBusMessage *message,
3716 const char *msg_interface;
3717 msg_interface = dbus_message_get_interface (message);
3719 if (msg_interface == NULL)
3730 if (strcmp (msg_interface, iface) == 0)
3738 * Sets the interface member being invoked
3739 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3740 * (DBUS_MESSAGE_TYPE_SIGNAL).
3742 * The member name must contain only valid characters as defined
3743 * in the D-Bus specification.
3745 * @param message the message
3746 * @param member the member or #NULL to unset
3747 * @returns #FALSE if not enough memory
3750 dbus_message_set_member (DBusMessage *message,
3753 _dbus_return_val_if_fail (message != NULL, FALSE);
3754 _dbus_return_val_if_fail (!message->locked, FALSE);
3755 _dbus_return_val_if_fail (member == NULL ||
3756 _dbus_check_is_valid_member (member),
3759 return set_or_delete_string_field (message,
3760 DBUS_HEADER_FIELD_MEMBER,
3766 * Gets the interface member being invoked
3767 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3768 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3770 * The returned string becomes invalid if the message is
3771 * modified, since it points into the wire-marshaled message data.
3773 * @param message the message
3774 * @returns the member name (should not be freed) or #NULL
3777 dbus_message_get_member (DBusMessage *message)
3781 _dbus_return_val_if_fail (message != NULL, NULL);
3783 v = NULL; /* in case field doesn't exist */
3784 _dbus_header_get_field_basic (&message->header,
3785 DBUS_HEADER_FIELD_MEMBER,
3792 * Checks if the message has an interface member
3794 * @param message the message
3795 * @param member the member name
3796 * @returns #TRUE if there is a member field in the header
3799 dbus_message_has_member (DBusMessage *message,
3802 const char *msg_member;
3803 msg_member = dbus_message_get_member (message);
3805 if (msg_member == NULL)
3816 if (strcmp (msg_member, member) == 0)
3824 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
3825 * The name is fully-qualified (namespaced).
3827 * The error name must contain only valid characters as defined
3828 * in the D-Bus specification.
3830 * @param message the message
3831 * @param error_name the name or #NULL to unset
3832 * @returns #FALSE if not enough memory
3835 dbus_message_set_error_name (DBusMessage *message,
3836 const char *error_name)
3838 _dbus_return_val_if_fail (message != NULL, FALSE);
3839 _dbus_return_val_if_fail (!message->locked, FALSE);
3840 _dbus_return_val_if_fail (error_name == NULL ||
3841 _dbus_check_is_valid_error_name (error_name),
3844 return set_or_delete_string_field (message,
3845 DBUS_HEADER_FIELD_ERROR_NAME,
3851 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
3854 * The returned string becomes invalid if the message is
3855 * modified, since it points into the wire-marshaled message data.
3857 * @param message the message
3858 * @returns the error name (should not be freed) or #NULL
3861 dbus_message_get_error_name (DBusMessage *message)
3865 _dbus_return_val_if_fail (message != NULL, NULL);
3867 v = NULL; /* in case field doesn't exist */
3868 _dbus_header_get_field_basic (&message->header,
3869 DBUS_HEADER_FIELD_ERROR_NAME,
3876 * Sets the message's destination. The destination is the name of
3877 * another connection on the bus and may be either the unique name
3878 * assigned by the bus to each connection, or a well-known name
3879 * specified in advance.
3881 * The destination name must contain only valid characters as defined
3882 * in the D-Bus specification.
3884 * @param message the message
3885 * @param destination the destination name or #NULL to unset
3886 * @returns #FALSE if not enough memory
3889 dbus_message_set_destination (DBusMessage *message,
3890 const char *destination)
3892 _dbus_return_val_if_fail (message != NULL, FALSE);
3893 _dbus_return_val_if_fail (!message->locked, FALSE);
3894 _dbus_return_val_if_fail (destination == NULL ||
3895 _dbus_check_is_valid_bus_name (destination),
3898 return set_or_delete_string_field (message,
3899 DBUS_HEADER_FIELD_DESTINATION,
3905 * Gets the destination of a message or #NULL if there is none set.
3907 * The returned string becomes invalid if the message is
3908 * modified, since it points into the wire-marshaled message data.
3910 * @param message the message
3911 * @returns the message destination (should not be freed) or #NULL
3914 dbus_message_get_destination (DBusMessage *message)
3918 _dbus_return_val_if_fail (message != NULL, NULL);
3920 v = NULL; /* in case field doesn't exist */
3921 _dbus_header_get_field_basic (&message->header,
3922 DBUS_HEADER_FIELD_DESTINATION,
3929 * Sets the message sender.
3931 * The sender must be a valid bus name as defined in the D-Bus
3934 * Usually you don't want to call this. The message bus daemon will
3935 * call it to set the origin of each message. If you aren't implementing
3936 * a message bus daemon you shouldn't need to set the sender.
3938 * @param message the message
3939 * @param sender the sender or #NULL to unset
3940 * @returns #FALSE if not enough memory
3943 dbus_message_set_sender (DBusMessage *message,
3946 _dbus_return_val_if_fail (message != NULL, FALSE);
3947 _dbus_return_val_if_fail (!message->locked, FALSE);
3948 _dbus_return_val_if_fail (sender == NULL ||
3949 _dbus_check_is_valid_bus_name (sender),
3952 return set_or_delete_string_field (message,
3953 DBUS_HEADER_FIELD_SENDER,
3959 * Gets the unique name of the connection which originated this
3960 * message, or #NULL if unknown or inapplicable. The sender is filled
3961 * in by the message bus.
3963 * Note, the returned sender is always the unique bus name.
3964 * Connections may own multiple other bus names, but those
3965 * are not found in the sender field.
3967 * The returned string becomes invalid if the message is
3968 * modified, since it points into the wire-marshaled message data.
3970 * @param message the message
3971 * @returns the unique name of the sender or #NULL
3974 dbus_message_get_sender (DBusMessage *message)
3978 _dbus_return_val_if_fail (message != NULL, NULL);
3980 if (NULL != message->unique_sender)
3981 return _dbus_string_get_const_data (message->unique_sender);
3983 v = NULL; /* in case field doesn't exist */
3984 _dbus_header_get_field_basic (&message->header,
3985 DBUS_HEADER_FIELD_SENDER,
3992 * Gets the type signature of the message, i.e. the arguments in the
3993 * message payload. The signature includes only "in" arguments for
3994 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
3995 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
3996 * what you might expect (that is, it does not include the signature of the
3997 * entire C++-style method).
3999 * The signature is a string made up of type codes such as
4000 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
4001 * the value of #DBUS_TYPE_INVALID).
4003 * The returned string becomes invalid if the message is
4004 * modified, since it points into the wire-marshaled message data.
4006 * @param message the message
4007 * @returns the type signature
4010 dbus_message_get_signature (DBusMessage *message)
4012 const DBusString *type_str;
4015 _dbus_return_val_if_fail (message != NULL, NULL);
4017 get_const_signature (message, &type_str, &type_pos);
4019 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
4023 _dbus_message_has_type_interface_member (DBusMessage *message,
4030 _dbus_assert (message != NULL);
4031 _dbus_assert (iface != NULL);
4032 _dbus_assert (member != NULL);
4034 if (dbus_message_get_type (message) != type)
4037 /* Optimize by checking the short member name first
4038 * instead of the longer interface name
4041 n = dbus_message_get_member (message);
4043 if (n && strcmp (n, member) == 0)
4045 n = dbus_message_get_interface (message);
4047 if (n == NULL || strcmp (n, iface) == 0)
4055 * Checks whether the message is a method call with the given
4056 * interface and member fields. If the message is not
4057 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
4058 * member field, returns #FALSE. If the interface field is missing,
4059 * then it will be assumed equal to the provided interface. The D-Bus
4060 * protocol allows method callers to leave out the interface name.
4062 * @param message the message
4063 * @param iface the name to check (must not be #NULL)
4064 * @param method the name to check (must not be #NULL)
4066 * @returns #TRUE if the message is the specified method call
4069 dbus_message_is_method_call (DBusMessage *message,
4073 _dbus_return_val_if_fail (message != NULL, FALSE);
4074 _dbus_return_val_if_fail (iface != NULL, FALSE);
4075 _dbus_return_val_if_fail (method != NULL, FALSE);
4076 /* don't check that interface/method are valid since it would be
4077 * expensive, and not catch many common errors
4080 return _dbus_message_has_type_interface_member (message,
4081 DBUS_MESSAGE_TYPE_METHOD_CALL,
4086 * Checks whether the message is a signal with the given interface and
4087 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
4088 * has a different interface or member field, returns #FALSE.
4090 * @param message the message
4091 * @param iface the name to check (must not be #NULL)
4092 * @param signal_name the name to check (must not be #NULL)
4094 * @returns #TRUE if the message is the specified signal
4097 dbus_message_is_signal (DBusMessage *message,
4099 const char *signal_name)
4101 _dbus_return_val_if_fail (message != NULL, FALSE);
4102 _dbus_return_val_if_fail (iface != NULL, FALSE);
4103 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
4104 /* don't check that interface/name are valid since it would be
4105 * expensive, and not catch many common errors
4108 return _dbus_message_has_type_interface_member (message,
4109 DBUS_MESSAGE_TYPE_SIGNAL,
4110 iface, signal_name);
4114 * Checks whether the message is an error reply with the given error
4115 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
4116 * different name, returns #FALSE.
4118 * @param message the message
4119 * @param error_name the name to check (must not be #NULL)
4121 * @returns #TRUE if the message is the specified error
4124 dbus_message_is_error (DBusMessage *message,
4125 const char *error_name)
4129 _dbus_return_val_if_fail (message != NULL, FALSE);
4130 _dbus_return_val_if_fail (error_name != NULL, FALSE);
4131 /* don't check that error_name is valid since it would be expensive,
4132 * and not catch many common errors
4135 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
4138 n = dbus_message_get_error_name (message);
4140 if (n && strcmp (n, error_name) == 0)
4147 * Checks whether the message was sent to the given name. If the
4148 * message has no destination specified or has a different
4149 * destination, returns #FALSE.
4151 * @param message the message
4152 * @param name the name to check (must not be #NULL)
4154 * @returns #TRUE if the message has the given destination name
4157 dbus_message_has_destination (DBusMessage *message,
4162 _dbus_return_val_if_fail (message != NULL, FALSE);
4163 _dbus_return_val_if_fail (name != NULL, FALSE);
4164 /* don't check that name is valid since it would be expensive, and
4165 * not catch many common errors
4168 s = dbus_message_get_destination (message);
4170 if (s && strcmp (s, name) == 0)
4177 * Checks whether the message has the given unique name as its sender.
4178 * If the message has no sender specified or has a different sender,
4179 * returns #FALSE. Note that a peer application will always have the
4180 * unique name of the connection as the sender. So you can't use this
4181 * function to see whether a sender owned a well-known name.
4183 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
4186 * @param message the message
4187 * @param name the name to check (must not be #NULL)
4189 * @returns #TRUE if the message has the given sender
4192 dbus_message_has_sender (DBusMessage *message,
4197 _dbus_return_val_if_fail (message != NULL, FALSE);
4198 _dbus_return_val_if_fail (name != NULL, FALSE);
4199 /* don't check that name is valid since it would be expensive, and
4200 * not catch many common errors
4203 s = dbus_message_get_sender (message);
4205 if (s && strcmp (s, name) == 0)
4212 * Checks whether the message has the given signature; see
4213 * dbus_message_get_signature() for more details on what the signature
4216 * @param message the message
4217 * @param signature typecode array
4218 * @returns #TRUE if message has the given signature
4221 dbus_message_has_signature (DBusMessage *message,
4222 const char *signature)
4226 _dbus_return_val_if_fail (message != NULL, FALSE);
4227 _dbus_return_val_if_fail (signature != NULL, FALSE);
4228 /* don't check that signature is valid since it would be expensive,
4229 * and not catch many common errors
4232 s = dbus_message_get_signature (message);
4234 if (s && strcmp (s, signature) == 0)
4241 * Sets a #DBusError based on the contents of the given
4242 * message. The error is only set if the message
4243 * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
4244 * The name of the error is set to the name of the message,
4245 * and the error message is set to the first argument
4246 * if the argument exists and is a string.
4248 * The return value indicates whether the error was set (the error is
4249 * set if and only if the message is an error message). So you can
4250 * check for an error reply and convert it to DBusError in one go:
4252 * if (dbus_set_error_from_message (error, reply))
4258 * @param error the error to set
4259 * @param message the message to set it from
4260 * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
4263 dbus_set_error_from_message (DBusError *error,
4264 DBusMessage *message)
4268 _dbus_return_val_if_fail (message != NULL, FALSE);
4269 _dbus_return_val_if_error_is_set (error, FALSE);
4271 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
4275 dbus_message_get_args (message, NULL,
4276 DBUS_TYPE_STRING, &str,
4279 dbus_set_error (error, dbus_message_get_error_name (message),
4280 str ? "%s" : NULL, str);
4286 * Checks whether a message contains unix fds
4288 * @param message the message
4289 * @returns #TRUE if the message contains unix fds
4292 dbus_message_contains_unix_fds(DBusMessage *message)
4294 #ifdef HAVE_UNIX_FD_PASSING
4295 _dbus_assert(message);
4297 return message->n_unix_fds > 0;
4306 * @addtogroup DBusMessageInternals
4312 * The initial buffer size of the message loader.
4314 * @todo this should be based on min header size plus some average
4315 * body size, or something. Or rather, the min header size only, if we
4316 * want to try to read only the header, store that in a DBusMessage,
4317 * then read only the body and store that, etc., depends on
4318 * how we optimize _dbus_message_loader_get_buffer() and what
4319 * the exact message format is.
4321 #define INITIAL_LOADER_DATA_LEN 32
4324 * Creates a new message loader. Returns #NULL if memory can't
4327 * @returns new loader, or #NULL.
4330 _dbus_message_loader_new (void)
4332 DBusMessageLoader *loader;
4334 loader = dbus_new0 (DBusMessageLoader, 1);
4338 loader->refcount = 1;
4340 loader->corrupted = FALSE;
4341 loader->corruption_reason = DBUS_VALID;
4343 /* this can be configured by the app, but defaults to the protocol max */
4344 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4346 /* We set a very relatively conservative default here since due to how
4347 SCM_RIGHTS works we need to preallocate an fd array of the maximum
4348 number of unix fds we want to receive in advance. A
4349 try-and-reallocate loop is not possible. */
4350 loader->max_message_unix_fds = DBUS_DEFAULT_MESSAGE_UNIX_FDS;
4352 if (!_dbus_string_init (&loader->data))
4358 /* preallocate the buffer for speed, ignore failure */
4359 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
4360 _dbus_string_set_length (&loader->data, 0);
4362 #ifdef HAVE_UNIX_FD_PASSING
4363 loader->unix_fds = NULL;
4364 loader->n_unix_fds = loader->n_unix_fds_allocated = 0;
4365 loader->unix_fds_outstanding = FALSE;
4372 * Increments the reference count of the loader.
4374 * @param loader the loader.
4375 * @returns the loader
4378 _dbus_message_loader_ref (DBusMessageLoader *loader)
4380 loader->refcount += 1;
4386 * Decrements the reference count of the loader and finalizes the
4387 * loader when the count reaches zero.
4389 * @param loader the loader.
4392 _dbus_message_loader_unref (DBusMessageLoader *loader)
4394 loader->refcount -= 1;
4395 if (loader->refcount == 0)
4397 #ifdef HAVE_UNIX_FD_PASSING
4398 close_unix_fds(loader->unix_fds, &loader->n_unix_fds);
4399 dbus_free(loader->unix_fds);
4401 _dbus_list_foreach (&loader->messages,
4402 (DBusForeachFunction) dbus_message_unref,
4404 _dbus_list_clear (&loader->messages);
4405 _dbus_string_free (&loader->data);
4411 * Gets the buffer to use for reading data from the network. Network
4412 * data is read directly into an allocated buffer, which is then used
4413 * in the DBusMessage, to avoid as many extra memcpy's as possible.
4414 * The buffer must always be returned immediately using
4415 * _dbus_message_loader_return_buffer(), even if no bytes are
4416 * successfully read.
4418 * @todo this function can be a lot more clever. For example
4419 * it can probably always return a buffer size to read exactly
4420 * the body of the next message, thus avoiding any memory wastage
4423 * @todo we need to enforce a max length on strings in header fields.
4425 * @param loader the message loader.
4426 * @param buffer the buffer
4429 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
4430 DBusString **buffer,
4432 dbus_bool_t *may_read_fds)
4434 _dbus_assert (!loader->buffer_outstanding);
4436 *buffer = &loader->data;
4438 loader->buffer_outstanding = TRUE;
4440 if (max_to_read != NULL)
4442 #ifdef HAVE_UNIX_FD_PASSING
4446 int fields_array_len;
4451 *max_to_read = DBUS_MAXIMUM_MESSAGE_LENGTH;
4452 *may_read_fds = TRUE;
4454 #ifdef HAVE_UNIX_FD_PASSING
4455 /* If we aren't holding onto any fds, we can read as much as we want
4457 if (loader->n_unix_fds == 0)
4460 /* Slow path: we have a message with some fds in it. We don't want
4461 * to start on the next message until this one is out of the way;
4462 * otherwise a legitimate sender can keep us processing messages
4463 * containing fds, until we disconnect it for having had fds pending
4464 * for too long, a limit that is in place to stop malicious senders
4465 * from setting up recursive fd-passing that takes up our quota and
4466 * will never go away. */
4468 remain = _dbus_string_get_length (&loader->data);
4472 DBusValidity validity = DBUS_VALIDITY_UNKNOWN;
4474 dbus_bool_t is_gvariant;
4476 /* If 0 < remain < DBUS_MINIMUM_HEADER_SIZE, then we've had at
4477 * least the first byte of a message, but we don't know how
4478 * much more to read. Only read the rest of the
4479 * DBUS_MINIMUM_HEADER_SIZE for now; then we'll know. */
4480 if (remain < DBUS_MINIMUM_HEADER_SIZE)
4482 *max_to_read = DBUS_MINIMUM_HEADER_SIZE - remain;
4483 *may_read_fds = FALSE;
4487 if (!_dbus_header_have_message_untrusted (loader->max_message_size,
4498 /* If a message in the buffer is invalid, we're going to
4499 * disconnect the sender anyway, so reading an arbitrary amount
4501 if (validity != DBUS_VALID)
4504 /* We have a partial message, with the
4505 * DBUS_MINIMUM_HEADER_SIZE-byte fixed part of the header (which
4506 * lets us work out how much more we need), but no more. Read
4507 * the rest of the message. */
4508 needed = header_len + body_len;
4509 _dbus_assert (needed > remain);
4510 *max_to_read = needed - remain;
4511 *may_read_fds = FALSE;
4515 /* Skip over entire messages until we have less than a message
4517 needed = header_len + body_len;
4518 _dbus_assert (needed > DBUS_MINIMUM_HEADER_SIZE);
4519 _dbus_assert (remain >= needed);
4528 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
4529 * indicating to the loader how many bytes of the buffer were filled
4530 * in. This function must always be called, even if no bytes were
4531 * successfully read.
4533 * @param loader the loader.
4534 * @param buffer the buffer.
4537 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
4540 _dbus_assert (loader->buffer_outstanding);
4541 _dbus_assert (buffer == &loader->data);
4543 loader->buffer_outstanding = FALSE;
4546 #ifdef HAVE_UNIX_FD_PASSING
4548 * Gets the buffer to use for reading unix fds from the network.
4550 * This works similar to _dbus_message_loader_get_buffer()
4552 * @param loader the message loader.
4553 * @param fds the array to read fds into
4554 * @param max_n_fds how many fds to read at most
4555 * @return TRUE on success, FALSE on OOM
4558 _dbus_message_loader_get_unix_fds(DBusMessageLoader *loader,
4560 unsigned *max_n_fds)
4562 _dbus_assert (!loader->unix_fds_outstanding);
4564 /* Allocate space where we can put the fds we read. We allocate
4565 space for max_message_unix_fds since this is an
4566 upper limit how many fds can be received within a single
4567 message. Since SCM_RIGHTS doesn't allow a reallocate+retry logic
4568 we are allocating the maximum possible array size right from the
4569 beginning. This sucks a bit, however unless SCM_RIGHTS is fixed
4570 there is no better way. */
4572 if (loader->n_unix_fds_allocated < loader->max_message_unix_fds)
4574 int *a = dbus_realloc(loader->unix_fds,
4575 loader->max_message_unix_fds * sizeof(loader->unix_fds[0]));
4580 loader->unix_fds = a;
4581 loader->n_unix_fds_allocated = loader->max_message_unix_fds;
4584 *fds = loader->unix_fds + loader->n_unix_fds;
4585 *max_n_fds = loader->n_unix_fds_allocated - loader->n_unix_fds;
4587 loader->unix_fds_outstanding = TRUE;
4592 * Returns a buffer obtained from _dbus_message_loader_get_unix_fds().
4594 * This works similar to _dbus_message_loader_return_buffer()
4596 * @param loader the message loader.
4597 * @param fds the array fds were read into
4598 * @param n_fds how many fds were read
4602 _dbus_message_loader_return_unix_fds(DBusMessageLoader *loader,
4606 _dbus_assert(loader->unix_fds_outstanding);
4607 _dbus_assert(loader->unix_fds + loader->n_unix_fds == fds);
4608 _dbus_assert(loader->n_unix_fds + n_fds <= loader->n_unix_fds_allocated);
4610 loader->n_unix_fds += n_fds;
4611 loader->unix_fds_outstanding = FALSE;
4613 if (n_fds && loader->unix_fds_change)
4614 loader->unix_fds_change (loader->unix_fds_change_data);
4619 * FIXME when we move the header out of the buffer, that memmoves all
4620 * buffered messages. Kind of crappy.
4622 * Also we copy the header and body, which is kind of crappy. To
4623 * avoid this, we have to allow header and body to be in a single
4624 * memory block, which is good for messages we read and bad for
4625 * messages we are creating. But we could move_len() the buffer into
4626 * this single memory block, and move_len() will just swap the buffers
4627 * if you're moving the entire buffer replacing the dest string.
4629 * We could also have the message loader tell the transport how many
4630 * bytes to read; so it would first ask for some arbitrary number like
4631 * 256, then if the message was incomplete it would use the
4632 * header/body len to ask for exactly the size of the message (or
4633 * blocks the size of a typical kernel buffer for the socket). That
4634 * way we don't get trailing bytes in the buffer that have to be
4635 * memmoved. Though I suppose we also don't have a chance of reading a
4636 * bunch of small messages at once, so the optimization may be stupid.
4638 * Another approach would be to keep a "start" index into
4639 * loader->data and only delete it occasionally, instead of after
4640 * each message is loaded.
4642 * load_message() returns FALSE if not enough memory OR the loader was corrupted
4645 load_message (DBusMessageLoader *loader,
4646 DBusMessage *message,
4648 int fields_array_len,
4653 DBusValidity validity;
4654 const DBusString *type_str;
4656 DBusValidationMode mode;
4657 dbus_uint32_t n_unix_fds = 0;
4659 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
4664 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
4667 /* 1. VALIDATE AND COPY OVER HEADER */
4668 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
4669 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
4671 if (!_dbus_header_load (&message->header,
4679 _dbus_string_get_length (&loader->data)))
4681 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
4683 /* assert here so we can catch any code that still uses DBUS_VALID to indicate
4684 oom errors. They should use DBUS_VALIDITY_UNKNOWN_OOM_ERROR instead */
4685 _dbus_assert (validity != DBUS_VALID);
4687 if (validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
4691 loader->corrupted = TRUE;
4692 loader->corruption_reason = validity;
4697 _dbus_assert (validity == DBUS_VALID);
4699 /* 2. VALIDATE BODY */
4700 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
4702 if (_dbus_message_is_gvariant (message))
4706 validity = _dbus_validate_gvariant_body_with_reason (type_str,
4717 get_const_signature (message, &type_str, &type_pos);
4719 /* Because the bytes_remaining arg is NULL, this validates that the
4720 * body is the right length
4723 validity = _dbus_validate_body_with_reason (type_str,
4731 if (validity != DBUS_VALID)
4733 _dbus_verbose ("Failed to validate message body code %d\n", validity);
4735 loader->corrupted = TRUE;
4736 loader->corruption_reason = validity;
4742 /* 3. COPY OVER UNIX FDS */
4743 _dbus_header_get_field_basic(&message->header,
4744 DBUS_HEADER_FIELD_UNIX_FDS,
4748 #ifdef HAVE_UNIX_FD_PASSING
4750 if (n_unix_fds > loader->n_unix_fds)
4752 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
4753 n_unix_fds, loader->n_unix_fds);
4755 loader->corrupted = TRUE;
4756 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4760 /* If this was a recycled message there might still be
4761 some memory allocated for the fds */
4762 dbus_free(message->unix_fds);
4766 message->unix_fds = _dbus_memdup(loader->unix_fds, n_unix_fds * sizeof(message->unix_fds[0]));
4767 if (message->unix_fds == NULL)
4769 _dbus_verbose ("Failed to allocate file descriptor array\n");
4774 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
4775 loader->n_unix_fds -= n_unix_fds;
4776 memmove (loader->unix_fds, loader->unix_fds + n_unix_fds, loader->n_unix_fds * sizeof (loader->unix_fds[0]));
4778 if (loader->unix_fds_change)
4779 loader->unix_fds_change (loader->unix_fds_change_data);
4782 message->unix_fds = NULL;
4788 _dbus_verbose ("Hmm, message claims to come with file descriptors "
4789 "but that's not supported on our platform, disconnecting.\n");
4791 loader->corrupted = TRUE;
4792 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4798 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
4800 if (!_dbus_list_append (&loader->messages, message))
4802 _dbus_verbose ("Failed to append new message to loader queue\n");
4807 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
4808 _dbus_assert (_dbus_string_get_length (&loader->data) >=
4809 (header_len + body_len));
4811 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
4813 _dbus_verbose ("Failed to move body into new message\n");
4818 _dbus_string_delete (&loader->data, 0, header_len + body_len);
4820 /* don't waste more than 2k of memory */
4821 _dbus_string_compact (&loader->data, 2048);
4823 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
4824 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
4826 _dbus_verbose ("Loaded message %p\n", message);
4828 _dbus_assert (!oom);
4829 _dbus_assert (!loader->corrupted);
4830 _dbus_assert (loader->messages != NULL);
4831 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4839 /* does nothing if the message isn't in the list */
4840 _dbus_list_remove_last (&loader->messages, message);
4843 _dbus_assert (!loader->corrupted);
4845 _dbus_assert (loader->corrupted);
4847 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
4853 set_unique_sender (DBusMessage *message, uint64_t unique_sender_id)
4855 if (NULL == message->unique_sender)
4857 message->unique_sender = dbus_new (DBusString, 1);
4858 if (NULL == message->unique_sender)
4861 if (!_dbus_string_init (message->unique_sender))
4865 _dbus_string_set_length (message->unique_sender, 0);
4867 if (!_dbus_string_append_printf (message->unique_sender, ":1.%llu", (unsigned long long)unique_sender_id))
4869 _dbus_string_free (message->unique_sender);
4870 dbus_free (message->unique_sender);
4871 message->unique_sender = NULL;
4879 * Converts buffered data into messages, if we have enough data. If
4880 * we don't have enough data, does nothing.
4882 * @todo we need to check that the proper named header fields exist
4883 * for each message type.
4885 * @todo If a message has unknown type, we should probably eat it
4886 * right here rather than passing it out to applications. However
4887 * it's not an error to see messages of unknown type.
4889 * @param loader the loader.
4890 * @returns #TRUE if we had enough memory to finish.
4893 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
4895 while (!loader->corrupted &&
4896 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
4898 DBusValidity validity;
4899 int byte_order, fields_array_len, header_len, body_len;
4900 dbus_bool_t is_gvariant;
4902 if (_dbus_header_have_message_untrusted (loader->max_message_size,
4909 _dbus_string_get_length (&loader->data),
4912 DBusMessage *message;
4914 _dbus_assert (validity == DBUS_VALID);
4916 message = dbus_message_new_empty_header (is_gvariant);
4917 if (message == NULL)
4920 if (!load_message (loader, message,
4921 byte_order, fields_array_len,
4922 header_len, body_len))
4924 dbus_message_unref (message);
4925 /* load_message() returns false if corrupted or OOM; if
4926 * corrupted then return TRUE for not OOM
4928 return loader->corrupted;
4931 if (_dbus_message_is_gvariant (message))
4933 set_unique_sender (message, _dbus_message_loader_get_unique_sender_id (loader));
4934 message->locked = TRUE;
4937 _dbus_assert (loader->messages != NULL);
4938 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4942 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
4944 if (validity != DBUS_VALID)
4946 loader->corrupted = TRUE;
4947 loader->corruption_reason = validity;
4957 _dbus_decode_kmsg (DBusString *data,
4962 if (_dbus_string_get_length (data) >= DBUS_MINIMUM_HEADER_SIZE)
4965 DBusValidity validity;
4966 int byte_order, fields_array_len, header_len, body_len;
4967 dbus_bool_t is_gvariant;
4969 if (_dbus_header_have_message_untrusted (DBUS_MAXIMUM_MESSAGE_LENGTH,
4976 _dbus_string_get_length (data),
4979 DBusMessage *message;
4980 dbus_uint32_t n_unix_fds = 0;
4981 const DBusString *type_str = NULL;
4984 _dbus_assert (validity == DBUS_VALID);
4986 message = dbus_message_new_empty_header (is_gvariant);
4987 if (message == NULL)
4991 * Validate and copy over header
4993 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
4994 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (data));
4996 if (!_dbus_header_load (&message->header,
4997 DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED,
5004 _dbus_string_get_length (data)))
5006 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
5007 dbus_message_unref (message);
5011 _dbus_assert (validity == DBUS_VALID);
5016 if (_dbus_message_is_gvariant (message))
5018 validity = _dbus_validate_gvariant_body_with_reason (type_str,
5028 _dbus_verbose ("Not valid GVariant dbus message\n");
5029 dbus_message_unref (message);
5033 if (validity != DBUS_VALID)
5035 _dbus_verbose ("Failed to validate message body code %d\n", validity);
5036 dbus_message_unref (message);
5041 * Copy over Unix FDS
5043 _dbus_header_get_field_basic(&message->header,
5044 DBUS_HEADER_FIELD_UNIX_FDS,
5048 #ifdef HAVE_UNIX_FD_PASSING
5050 if (n_unix_fds > n_fds)
5052 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
5053 n_unix_fds, message->n_unix_fds);
5054 dbus_message_unref (message);
5058 /* If this was a recycled message there might still be
5059 some memory allocated for the fds */
5060 dbus_free(message->unix_fds);
5064 message->unix_fds = _dbus_memdup(fds, n_unix_fds * sizeof(message->unix_fds[0]));
5065 if (message->unix_fds == NULL)
5067 _dbus_verbose ("Failed to allocate file descriptor array\n");
5068 dbus_message_unref (message);
5072 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
5075 message->unix_fds = NULL;
5079 _dbus_verbose ("Hmm, message claims to come with file descriptors "
5080 "but that's not supported on our platform, disconnecting.\n");
5081 dbus_message_unref (message);
5087 * Copy over message body
5089 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
5090 _dbus_assert (_dbus_string_get_length (data) >= (header_len + body_len));
5092 if (!_dbus_string_copy_len (data, header_len, body_len, &message->body, 0))
5094 _dbus_verbose ("Failed to move body into new message\n");
5095 dbus_message_unref (message);
5099 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
5100 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
5102 set_unique_sender (message, sender_id);
5103 message->locked = TRUE;
5105 /* Yupi, we have DBusMessage* */
5110 _dbus_verbose ("Data broken with invalid code %d\n", validity);
5112 } /* if _dbus_header_have_message_untrusted() */
5117 _dbus_verbose ("message size < DBUS_MINIMUM_HEADER_SIZE\n");
5119 } /* if DBUS_MINIMUM_HEADER_SIZE */
5123 * Peeks at first loaded message, returns #NULL if no messages have
5126 * @param loader the loader.
5127 * @returns the next message, or #NULL if none.
5130 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
5132 if (loader->messages)
5133 return loader->messages->data;
5139 * Pops a loaded message (passing ownership of the message
5140 * to the caller). Returns #NULL if no messages have been
5143 * @param loader the loader.
5144 * @returns the next message, or #NULL if none.
5147 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
5149 return _dbus_list_pop_first (&loader->messages);
5153 * Pops a loaded message inside a list link (passing ownership of the
5154 * message and link to the caller). Returns #NULL if no messages have
5157 * @param loader the loader.
5158 * @returns the next message link, or #NULL if none.
5161 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
5163 return _dbus_list_pop_first_link (&loader->messages);
5167 * Returns a popped message link, used to undo a pop.
5169 * @param loader the loader
5170 * @param link the link with a message in it
5173 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
5176 _dbus_list_prepend_link (&loader->messages, link);
5180 * Checks whether the loader is confused due to bad data.
5181 * If messages are received that are invalid, the
5182 * loader gets confused and gives up permanently.
5183 * This state is called "corrupted."
5185 * @param loader the loader
5186 * @returns #TRUE if the loader is hosed.
5189 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
5191 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
5192 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
5193 return loader->corrupted;
5197 * Checks what kind of bad data confused the loader.
5199 * @param loader the loader
5200 * @returns why the loader is hosed, or DBUS_VALID if it isn't.
5203 _dbus_message_loader_get_corruption_reason (DBusMessageLoader *loader)
5205 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
5206 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
5208 return loader->corruption_reason;
5212 * Sets the maximum size message we allow.
5214 * @param loader the loader
5215 * @param size the max message size in bytes
5218 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
5221 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
5223 _dbus_verbose ("clamping requested max message size %ld to %d\n",
5224 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
5225 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
5227 loader->max_message_size = size;
5231 * Gets the maximum allowed message size in bytes.
5233 * @param loader the loader
5234 * @returns max size in bytes
5237 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
5239 return loader->max_message_size;
5243 * Sets the maximum unix fds per message we allow.
5245 * @param loader the loader
5246 * @param n the max number of unix fds in a message
5249 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader,
5252 if (n > DBUS_MAXIMUM_MESSAGE_UNIX_FDS)
5254 _dbus_verbose ("clamping requested max message unix_fds %ld to %d\n",
5255 n, DBUS_MAXIMUM_MESSAGE_UNIX_FDS);
5256 n = DBUS_MAXIMUM_MESSAGE_UNIX_FDS;
5258 loader->max_message_unix_fds = n;
5262 * Gets the maximum allowed number of unix fds per message
5264 * @param loader the loader
5265 * @returns max unix fds
5268 _dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
5270 return loader->max_message_unix_fds;
5274 * Return how many file descriptors are pending in the loader
5276 * @param loader the loader
5279 _dbus_message_loader_get_pending_fds_count (DBusMessageLoader *loader)
5281 #ifdef HAVE_UNIX_FD_PASSING
5282 return loader->n_unix_fds;
5289 * Register a function to be called whenever the number of pending file
5290 * descriptors in the loader change.
5292 * @param loader the loader
5293 * @param callback the callback
5294 * @param data the data for the callback
5297 _dbus_message_loader_set_pending_fds_function (DBusMessageLoader *loader,
5298 void (* callback) (void *),
5301 #ifdef HAVE_UNIX_FD_PASSING
5302 loader->unix_fds_change = callback;
5303 loader->unix_fds_change_data = data;
5308 _dbus_message_loader_set_unique_sender_id (DBusMessageLoader *loader,
5311 loader->unique_sender_id = id;
5315 _dbus_message_loader_get_unique_sender_id (DBusMessageLoader *loader)
5317 return loader->unique_sender_id;
5320 static DBusDataSlotAllocator slot_allocator =
5321 _DBUS_DATA_SLOT_ALLOCATOR_INIT (_DBUS_LOCK_NAME (message_slots));
5324 * Allocates an integer ID to be used for storing application-specific
5325 * data on any DBusMessage. The allocated ID may then be used
5326 * with dbus_message_set_data() and dbus_message_get_data().
5327 * The passed-in slot must be initialized to -1, and is filled in
5328 * with the slot ID. If the passed-in slot is not -1, it's assumed
5329 * to be already allocated, and its refcount is incremented.
5331 * The allocated slot is global, i.e. all DBusMessage objects will
5332 * have a slot with the given integer ID reserved.
5334 * @param slot_p address of a global variable storing the slot
5335 * @returns #FALSE on failure (no memory)
5338 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
5340 return _dbus_data_slot_allocator_alloc (&slot_allocator,
5345 * Deallocates a global ID for message data slots.
5346 * dbus_message_get_data() and dbus_message_set_data() may no
5347 * longer be used with this slot. Existing data stored on existing
5348 * DBusMessage objects will be freed when the message is
5349 * finalized, but may not be retrieved (and may only be replaced if
5350 * someone else reallocates the slot). When the refcount on the
5351 * passed-in slot reaches 0, it is set to -1.
5353 * @param slot_p address storing the slot to deallocate
5356 dbus_message_free_data_slot (dbus_int32_t *slot_p)
5358 _dbus_return_if_fail (*slot_p >= 0);
5360 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
5364 * Stores a pointer on a DBusMessage, along
5365 * with an optional function to be used for freeing
5366 * the data when the data is set again, or when
5367 * the message is finalized. The slot number
5368 * must have been allocated with dbus_message_allocate_data_slot().
5370 * @param message the message
5371 * @param slot the slot number
5372 * @param data the data to store
5373 * @param free_data_func finalizer function for the data
5374 * @returns #TRUE if there was enough memory to store the data
5377 dbus_message_set_data (DBusMessage *message,
5380 DBusFreeFunction free_data_func)
5382 DBusFreeFunction old_free_func;
5386 _dbus_return_val_if_fail (message != NULL, FALSE);
5387 _dbus_return_val_if_fail (slot >= 0, FALSE);
5389 retval = _dbus_data_slot_list_set (&slot_allocator,
5390 &message->slot_list,
5391 slot, data, free_data_func,
5392 &old_free_func, &old_data);
5396 /* Do the actual free outside the message lock */
5398 (* old_free_func) (old_data);
5405 * Retrieves data previously set with dbus_message_set_data().
5406 * The slot must still be allocated (must not have been freed).
5408 * @param message the message
5409 * @param slot the slot to get data from
5410 * @returns the data, or #NULL if not found
5413 dbus_message_get_data (DBusMessage *message,
5418 _dbus_return_val_if_fail (message != NULL, NULL);
5420 res = _dbus_data_slot_list_get (&slot_allocator,
5421 &message->slot_list,
5428 * Utility function to convert a machine-readable (not translated)
5429 * string into a D-Bus message type.
5432 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
5433 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
5434 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
5435 * "error" -> DBUS_MESSAGE_TYPE_ERROR
5436 * anything else -> DBUS_MESSAGE_TYPE_INVALID
5441 dbus_message_type_from_string (const char *type_str)
5443 if (strcmp (type_str, "method_call") == 0)
5444 return DBUS_MESSAGE_TYPE_METHOD_CALL;
5445 if (strcmp (type_str, "method_return") == 0)
5446 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
5447 else if (strcmp (type_str, "signal") == 0)
5448 return DBUS_MESSAGE_TYPE_SIGNAL;
5449 else if (strcmp (type_str, "error") == 0)
5450 return DBUS_MESSAGE_TYPE_ERROR;
5452 return DBUS_MESSAGE_TYPE_INVALID;
5456 * Utility function to convert a D-Bus message type into a
5457 * machine-readable string (not translated).
5460 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
5461 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
5462 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
5463 * DBUS_MESSAGE_TYPE_ERROR -> "error"
5464 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
5469 dbus_message_type_to_string (int type)
5473 case DBUS_MESSAGE_TYPE_METHOD_CALL:
5474 return "method_call";
5475 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
5476 return "method_return";
5477 case DBUS_MESSAGE_TYPE_SIGNAL:
5479 case DBUS_MESSAGE_TYPE_ERROR:
5487 * Turn a DBusMessage into the marshalled form as described in the D-Bus
5490 * Generally, this function is only useful for encapsulating D-Bus messages in
5491 * a different protocol.
5493 * @param msg the DBusMessage
5494 * @param marshalled_data_p the location to save the marshalled form to
5495 * @param len_p the location to save the length of the marshalled form to
5496 * @returns #FALSE if there was not enough memory
5499 dbus_message_marshal (DBusMessage *msg,
5500 char **marshalled_data_p,
5504 dbus_bool_t was_locked;
5506 _dbus_return_val_if_fail (msg != NULL, FALSE);
5507 _dbus_return_val_if_fail (marshalled_data_p != NULL, FALSE);
5508 _dbus_return_val_if_fail (len_p != NULL, FALSE);
5510 if (!_dbus_string_init (&tmp))
5513 /* Ensure the message is locked, to ensure the length header is filled in. */
5514 was_locked = msg->locked;
5517 dbus_message_lock (msg);
5519 if (!_dbus_string_copy (&(msg->header.data), 0, &tmp, 0))
5522 *len_p = _dbus_string_get_length (&tmp);
5524 if (!_dbus_string_copy (&(msg->body), 0, &tmp, *len_p))
5527 *len_p = _dbus_string_get_length (&tmp);
5529 if (!_dbus_string_steal_data (&tmp, marshalled_data_p))
5532 _dbus_string_free (&tmp);
5535 msg->locked = FALSE;
5540 _dbus_string_free (&tmp);
5543 msg->locked = FALSE;
5549 * Demarshal a D-Bus message from the format described in the D-Bus
5552 * Generally, this function is only useful for encapsulating D-Bus messages in
5553 * a different protocol.
5555 * @param str the marshalled DBusMessage
5556 * @param len the length of str
5557 * @param error the location to save errors to
5558 * @returns #NULL if there was an error
5561 dbus_message_demarshal (const char *str,
5565 DBusMessageLoader *loader;
5569 _dbus_return_val_if_fail (str != NULL, NULL);
5571 loader = _dbus_message_loader_new ();
5576 _dbus_message_loader_get_buffer (loader, &buffer, NULL, NULL);
5578 if (!_dbus_string_append_len (buffer, str, len))
5581 _dbus_message_loader_return_buffer (loader, buffer);
5583 if (!_dbus_message_loader_queue_messages (loader))
5586 if (_dbus_message_loader_get_is_corrupted (loader))
5589 msg = _dbus_message_loader_pop_message (loader);
5594 _dbus_message_loader_unref (loader);
5598 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS, "Message is corrupted (%s)",
5599 _dbus_validity_to_error_message (loader->corruption_reason));
5600 _dbus_message_loader_unref (loader);
5604 _DBUS_SET_OOM (error);
5605 _dbus_message_loader_unref (loader);
5610 * Returns the number of bytes required to be in the buffer to demarshal a
5613 * Generally, this function is only useful for encapsulating D-Bus messages in
5614 * a different protocol.
5616 * @param buf data to be marshalled
5617 * @param len the length of @p buf
5618 * @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
5622 dbus_message_demarshal_bytes_needed(const char *buf,
5626 int byte_order, fields_array_len, header_len, body_len;
5627 DBusValidity validity = DBUS_VALID;
5629 dbus_bool_t is_gvariant;
5631 if (!buf || len < DBUS_MINIMUM_HEADER_SIZE)
5634 if (len > DBUS_MAXIMUM_MESSAGE_LENGTH)
5635 len = DBUS_MAXIMUM_MESSAGE_LENGTH;
5636 _dbus_string_init_const_len (&str, buf, len);
5638 validity = DBUS_VALID;
5640 = _dbus_header_have_message_untrusted(DBUS_MAXIMUM_MESSAGE_LENGTH,
5641 &validity, &byte_order,
5648 _dbus_string_free (&str);
5650 if (validity == DBUS_VALID)
5652 _dbus_assert (have_message || (header_len + body_len) > len);
5653 (void) have_message; /* unused unless asserting */
5654 return header_len + body_len;
5658 return -1; /* broken! */
5663 _dbus_message_copy_recursive(DBusMessageIter *iter, DBusMessageIter *dest)
5665 dbus_bool_t res = TRUE;
5668 while ((current_type = dbus_message_iter_get_arg_type (iter)) != DBUS_TYPE_INVALID) {
5669 if (dbus_type_is_basic(current_type)) {
5670 DBusBasicValue value;
5671 dbus_message_iter_get_basic (iter, &value);
5672 dbus_message_iter_append_basic (dest, current_type, &value);
5675 DBusMessageIter sub;
5676 DBusMessageIter dest_sub;
5679 dbus_message_iter_recurse (iter, &sub);
5680 if (DBUS_TYPE_VARIANT == current_type)
5681 sig = dbus_message_iter_get_signature (&sub);
5682 else if (DBUS_TYPE_ARRAY == current_type)
5683 sig = dbus_message_iter_get_signature (&sub);
5685 res = res && dbus_message_iter_open_container (dest, current_type, sig, &dest_sub);
5687 res = res && _dbus_message_copy_recursive (&sub, &dest_sub);
5688 res = res && dbus_message_iter_close_container (dest, &dest_sub);
5695 dbus_message_iter_next (iter);
5702 _dbus_on_new_bus (int type)
5704 _dbus_assert (type == DBUS_MAJOR_PROTOCOL_VERSION || type == DBUS_PROTOCOL_VERSION_GVARIANT);
5705 _dbus_protocol_strategy_bus_function (type);
5709 _dbus_on_send_message (int type)
5711 _dbus_assert (type == DBUS_MAJOR_PROTOCOL_VERSION || type == DBUS_PROTOCOL_VERSION_GVARIANT);
5712 _dbus_protocol_strategy_message_function (type);
5716 _dbus_message_remarshal (DBusMessage *message, dbus_bool_t gvariant)
5719 DBusMessageIter iter, ret_iter;
5721 dbus_uint32_t serial;
5724 _dbus_assert (message->locked);
5726 _dbus_on_send_message (gvariant ? DBUS_PROTOCOL_VERSION_GVARIANT : DBUS_MAJOR_PROTOCOL_VERSION);
5728 ret = _dbus_message_create_protocol_version (dbus_message_get_type(message),
5729 dbus_message_get_destination(message),
5730 dbus_message_get_path(message),
5731 dbus_message_get_interface(message),
5732 dbus_message_get_member(message),
5733 dbus_message_get_error_name(message),
5736 dbus_message_iter_init (message, &iter);
5737 dbus_message_iter_init_append (ret, &ret_iter);
5738 if (!_dbus_message_copy_recursive(&iter, &ret_iter))
5741 #ifdef HAVE_UNIX_FD_PASSING
5742 ret->unix_fds = dbus_new(int, message->n_unix_fds);
5743 if (ret->unix_fds == NULL && message->n_unix_fds > 0)
5746 ret->n_unix_fds_allocated = message->n_unix_fds;
5748 for (i = 0; i < message->n_unix_fds; ++i) {
5749 ret->unix_fds[i] = _dbus_dup(message->unix_fds[i], NULL);
5751 if (ret->unix_fds[i] < 0) {
5752 ret->n_unix_fds = i;
5757 ret->n_unix_fds = message->n_unix_fds;
5760 /* Remarshal data in header:
5761 byte order (already set)
5763 flags - only those we understand
5764 version (already set)
5767 fields array (length)
5770 interface (already set)
5771 member (already set)
5772 error name (already set)
5774 destination (already set)
5776 signature (set during copy, but an action needed for conversion to GVariant)
5781 _dbus_header_toggle_flag (&ret->header, DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
5782 _dbus_header_get_flag (&message->header, DBUS_HEADER_FLAG_NO_REPLY_EXPECTED));
5784 _dbus_header_toggle_flag (&ret->header, DBUS_HEADER_FLAG_NO_AUTO_START,
5785 _dbus_header_get_flag (&message->header, DBUS_HEADER_FLAG_NO_AUTO_START));
5787 /* SERIAL / COOKIE */
5788 serial = dbus_message_get_serial (message);
5791 dbus_message_set_serial (ret, serial);
5793 /* Field: REPLY_SERIAL */
5794 serial = dbus_message_get_reply_serial (message);
5796 if (0 != serial && !dbus_message_set_reply_serial (ret, serial))
5800 sender = dbus_message_get_sender (message);
5802 if (NULL != sender && !dbus_message_set_sender (ret, sender))
5807 _dbus_header_update_lengths (&ret->header,
5808 _dbus_string_get_length (&ret->body));
5810 /* Field: SIGNATURE to body; add body offset - this is done with dbus_message_lock() */
5812 dbus_message_lock (ret);
5817 _dbus_header_free (&ret->header);
5818 _dbus_string_free (&ret->body);
5820 #ifdef HAVE_UNIX_FD_PASSING
5823 close_unix_fds(ret->unix_fds, &ret->n_unix_fds);
5824 dbus_free(ret->unix_fds);
5832 dbus_set_protocol_version (unsigned char version)
5834 _dbus_default_protocol_version = version;
5838 protocol_strategy_first_type (int type)
5840 /* change protocol once */
5841 if (!_dbus_first_bus_open)
5843 _dbus_first_bus_open = TRUE;
5844 _dbus_default_protocol_version = type;
5849 protocol_strategy_last_type (int type)
5851 /* change protocol every time it is needed */
5852 if (_dbus_default_protocol_version != type)
5853 _dbus_default_protocol_version = type;
5857 protocol_strategy_static (int type)
5863 dbus_set_default_protocol_strategy (const char *strategy_name)
5865 if (strcmp (strategy_name, "first-bus") == 0)
5867 _dbus_protocol_strategy_bus_function = protocol_strategy_first_type;
5868 _dbus_protocol_strategy_message_function = protocol_strategy_static;
5870 else if (strcmp (strategy_name, "dbus1") == 0)
5872 _dbus_default_protocol_version = DBUS_MAJOR_PROTOCOL_VERSION;
5873 _dbus_protocol_strategy_bus_function = protocol_strategy_static;
5874 _dbus_protocol_strategy_message_function = protocol_strategy_static;
5876 else if (strcmp (strategy_name, "gvariant") == 0)
5878 _dbus_default_protocol_version = DBUS_PROTOCOL_VERSION_GVARIANT;
5879 _dbus_protocol_strategy_bus_function = protocol_strategy_static;
5880 _dbus_protocol_strategy_message_function = protocol_strategy_static;
5882 else if (strcmp (strategy_name, "last-message") == 0)
5884 _dbus_protocol_strategy_bus_function = protocol_strategy_static;
5885 _dbus_protocol_strategy_message_function = protocol_strategy_last_type;
5887 else /* "last-bus" is default strategy */
5889 _dbus_protocol_strategy_bus_function = protocol_strategy_last_type;
5890 _dbus_protocol_strategy_message_function = protocol_strategy_static;
5895 _dbus_generate_local_error_message (dbus_uint32_t serial,
5896 const char *error_name,
5897 const char *error_msg)
5899 DBusMessage *message;
5900 message = dbus_message_new (DBUS_MESSAGE_TYPE_ERROR);
5904 if (!dbus_message_set_error_name (message, error_name))
5906 dbus_message_unref (message);
5911 dbus_message_set_no_reply (message, TRUE);
5913 if (!dbus_message_set_reply_serial (message,
5916 dbus_message_unref (message);
5921 if (error_msg != NULL)
5923 DBusMessageIter iter;
5925 dbus_message_iter_init_append (message, &iter);
5926 if (!dbus_message_iter_append_basic (&iter,
5930 dbus_message_unref (message);
5941 _dbus_message_assure_dbus1 (DBusMessage **message)
5943 if ((*message)->header.protocol_version != DBUS_MAJOR_PROTOCOL_VERSION)
5945 *message = _dbus_message_remarshal (*message, FALSE);
5952 _dbus_message_assure_gvariant (DBusMessage **message)
5954 if ((*message)->header.protocol_version != DBUS_PROTOCOL_VERSION_GVARIANT)
5956 *message = _dbus_message_remarshal (*message, TRUE);
5963 * An opaque data structure containing the serialized form of any single
5964 * D-Bus message item, whose signature is a single complete type.
5966 * (Implementation detail: It's serialized as a single variant.)
5974 * Copy a single D-Bus message item from reader into a
5975 * newly-allocated #DBusVariant.
5977 * For example, if a message contains three string arguments, and reader points
5978 * to the second string, the resulting DBusVariant will have signature
5979 * #DBUS_TYPE_STRING_AS_STRING and contain only that second string.
5981 * @param reader An iterator over message items, pointing to one item to copy
5982 * @returns The variant, or #NULL if out of memory
5985 _dbus_variant_read (DBusMessageIter *reader)
5987 DBusVariant *self = NULL;
5988 /* Points to the single item we will read from the reader */
5989 DBusMessageRealIter *real_reader = (DBusMessageRealIter *) reader;
5990 /* The position in self at which we will write a single variant
5991 * (it is position 0) */
5992 DBusTypeWriter items_writer;
5993 /* The position in self at which we will write a copy of reader
5994 * (it is inside the variant) */
5995 DBusTypeWriter variant_writer;
5997 DBusString variant_signature;
5998 /* Whatever is the signature of the item we will copy from the reader */
5999 DBusString contained_signature;
6000 /* TRUE if self->data needs to be freed */
6001 dbus_bool_t data_inited = FALSE;
6002 /* The type of the item we will read from the reader */
6004 /* The string, start position within that string, and length of the signature
6005 * of the single complete type of the item reader points to */
6006 const DBusString *sig;
6009 _dbus_assert (_dbus_message_iter_check (real_reader));
6010 _dbus_assert (real_reader->iter_type == DBUS_MESSAGE_ITER_TYPE_READER);
6011 _dbus_string_init_const (&variant_signature, DBUS_TYPE_VARIANT_AS_STRING);
6012 type = dbus_message_iter_get_arg_type (reader);
6013 _dbus_type_reader_get_signature (&real_reader->u.reader, &sig, &start, &len);
6015 if (!_dbus_string_init (&contained_signature))
6018 if (!_dbus_string_copy_len (sig, start, len, &contained_signature, 0))
6021 self = dbus_new0 (DBusVariant, 1);
6026 if (!_dbus_string_init (&self->data))
6031 _dbus_type_writer_init_values_only (&items_writer, DBUS_COMPILER_BYTE_ORDER,
6032 &variant_signature, 0, &self->data, 0);
6034 if (!_dbus_type_writer_recurse (&items_writer, DBUS_TYPE_VARIANT,
6035 &contained_signature, 0, &variant_writer))
6038 if (type == DBUS_TYPE_ARRAY)
6040 /* Points to each item in turn inside the array we are copying */
6041 DBusMessageIter array_reader;
6042 /* Same as array_reader */
6043 DBusMessageRealIter *real_array_reader = (DBusMessageRealIter *) &array_reader;
6044 /* The position inside the copied array at which we will write
6045 * the copy of array_reader */
6046 DBusTypeWriter array_writer;
6048 dbus_message_iter_recurse (reader, &array_reader);
6050 if (!_dbus_type_writer_recurse (&variant_writer, type,
6051 &contained_signature, 1, &array_writer))
6054 if (!_dbus_type_writer_write_reader (&array_writer,
6055 &real_array_reader->u.reader))
6058 if (!_dbus_type_writer_unrecurse (&variant_writer, &array_writer))
6061 else if (type == DBUS_TYPE_DICT_ENTRY || type == DBUS_TYPE_VARIANT ||
6062 type == DBUS_TYPE_STRUCT)
6064 /* Points to each item in turn inside the container we are copying */
6065 DBusMessageIter inner_reader;
6066 /* Same as inner_reader */
6067 DBusMessageRealIter *real_inner_reader = (DBusMessageRealIter *) &inner_reader;
6068 /* The position inside the copied container at which we will write the
6069 * copy of inner_reader */
6070 DBusTypeWriter inner_writer;
6072 dbus_message_iter_recurse (reader, &inner_reader);
6074 if (!_dbus_type_writer_recurse (&variant_writer, type, NULL, 0,
6078 if (!_dbus_type_writer_write_reader (&inner_writer,
6079 &real_inner_reader->u.reader))
6082 if (!_dbus_type_writer_unrecurse (&variant_writer, &inner_writer))
6087 DBusBasicValue value;
6089 /* We eliminated all the container types above */
6090 _dbus_assert (dbus_type_is_basic (type));
6092 dbus_message_iter_get_basic (reader, &value);
6094 if (!_dbus_type_writer_write_basic (&variant_writer, type, &value))
6098 _dbus_string_free (&contained_signature);
6105 _dbus_string_free (&self->data);
6110 _dbus_string_free (&contained_signature);
6115 * Return the signature of the item stored in self. It is a single complete
6118 * @param self the variant
6121 _dbus_variant_get_signature (DBusVariant *self)
6126 _dbus_assert (self != NULL);
6128 /* Here we make use of the fact that the serialization of a variant starts
6129 * with the 1-byte length, then that many bytes of signature, then \0. */
6130 len = _dbus_string_get_byte (&self->data, 0);
6131 ret = _dbus_string_get_const_data_len (&self->data, 1, len);
6132 _dbus_assert (strlen (ret) == len);
6137 * Copy the single D-Bus message item from self into writer.
6139 * For example, if writer points into the body of an empty message and self has
6140 * signature #DBUS_TYPE_STRING_AS_STRING, then the message will
6141 * have signature #DBUS_TYPE_STRING_AS_STRING after this function returns
6143 * @param self the variant
6144 * @param writer the place to write the contents of the variant
6145 * @returns #TRUE on success, #FALSE if out of memory
6148 _dbus_variant_write (DBusVariant *self,
6149 DBusMessageIter *writer)
6152 DBusString variant_signature;
6153 /* Points to the single item in self */
6154 DBusTypeReader variant_reader;
6155 /* Points to the single item (of whatever type) inside the variant */
6156 DBusTypeReader reader;
6157 /* The position at which we will copy reader */
6158 DBusMessageRealIter *real_writer = (DBusMessageRealIter *) writer;
6161 _dbus_assert (self != NULL);
6162 _dbus_assert (_dbus_message_iter_append_check (real_writer));
6163 _dbus_assert (real_writer->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
6165 _dbus_string_init_const (&variant_signature, DBUS_TYPE_VARIANT_AS_STRING);
6166 _dbus_type_reader_init (&reader, DBUS_COMPILER_BYTE_ORDER,
6167 &variant_signature, 0, &self->data, 0);
6168 _dbus_type_reader_recurse (&reader, &variant_reader);
6170 if (!_dbus_message_iter_open_signature (real_writer))
6173 ret = _dbus_type_writer_write_reader (&real_writer->u.writer,
6176 if (!_dbus_message_iter_close_signature (real_writer))
6183 _dbus_variant_get_length (DBusVariant *self)
6185 _dbus_assert (self != NULL);
6186 return _dbus_string_get_length (&self->data);
6190 _dbus_variant_peek (DBusVariant *self)
6192 _dbus_assert (self != NULL);
6197 _dbus_variant_free (DBusVariant *self)
6199 _dbus_assert (self != NULL);
6200 _dbus_string_free (&self->data);
6206 /* tests in dbus-message-util.c */