1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 /* dbus-message.c DBusMessage object
4 * Copyright (C) 2002, 2003, 2004, 2005 Red Hat Inc.
5 * Copyright (C) 2002, 2003 CodeFactory AB
7 * Licensed under the Academic Free License version 2.1
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
26 #include "dbus-internals.h"
27 #include "dbus-marshal-recursive.h"
28 #include "dbus-marshal-validate.h"
29 #include "dbus-marshal-byteswap.h"
30 #include "dbus-marshal-header.h"
31 #include "dbus-signature.h"
32 #include "dbus-message-private.h"
33 #include "dbus-object-tree.h"
34 #include "dbus-memory.h"
35 #include "dbus-list.h"
36 #include "dbus-threads-internal.h"
37 #ifdef HAVE_UNIX_FD_PASSING
38 #include "dbus-sysdeps-unix.h"
43 #define _DBUS_TYPE_IS_STRINGLIKE(type) \
44 (type == DBUS_TYPE_STRING || type == DBUS_TYPE_SIGNATURE || \
45 type == DBUS_TYPE_OBJECT_PATH)
47 static void dbus_message_finalize (DBusMessage *message);
50 * @defgroup DBusMessageInternals DBusMessage implementation details
51 * @ingroup DBusInternals
52 * @brief DBusMessage private implementation details.
54 * The guts of DBusMessage and its methods.
59 #ifdef DBUS_ENABLE_EMBEDDED_TESTS
61 _dbus_enable_message_cache (void)
63 static int enabled = -1;
67 const char *s = _dbus_getenv ("DBUS_MESSAGE_CACHE");
78 _dbus_warn ("DBUS_MESSAGE_CACHE should be 0 or 1 if set, not '%s'",
86 /* constant expression, should be optimized away */
87 # define _dbus_enable_message_cache() (TRUE)
90 #ifndef _dbus_message_trace_ref
92 _dbus_message_trace_ref (DBusMessage *message,
97 static int enabled = -1;
99 _dbus_trace_ref ("DBusMessage", message, old_refcount, new_refcount, why,
100 "DBUS_MESSAGE_TRACE", &enabled);
104 /* Not thread locked, but strictly const/read-only so should be OK
106 /** An static string representing an empty signature */
107 _DBUS_STRING_DEFINE_STATIC(_dbus_empty_signature_str, "");
109 /* these have wacky values to help trap uninitialized iterators;
110 * but has to fit in 3 bits
113 DBUS_MESSAGE_ITER_TYPE_READER = 3,
114 DBUS_MESSAGE_ITER_TYPE_WRITER = 7
117 /** typedef for internals of message iterator */
118 typedef struct DBusMessageRealIter DBusMessageRealIter;
121 * @brief Internals of DBusMessageIter
123 * Object representing a position in a message. All fields are internal.
125 struct DBusMessageRealIter
127 DBusMessage *message; /**< Message used */
128 dbus_uint32_t changed_stamp : CHANGED_STAMP_BITS; /**< stamp to detect invalid iters */
129 dbus_uint32_t iter_type : 3; /**< whether this is a reader or writer iter */
130 dbus_uint32_t sig_refcount : 8; /**< depth of open_signature() */
133 DBusTypeWriter writer; /**< writer */
134 DBusTypeReader reader; /**< reader */
135 } u; /**< the type writer or reader that does all the work */
139 get_const_signature (DBusHeader *header,
140 const DBusString **type_str_p,
143 if (_dbus_header_get_field_raw (header,
144 DBUS_HEADER_FIELD_SIGNATURE,
148 *type_pos_p += 1; /* skip the signature length which is 1 byte */
152 *type_str_p = &_dbus_empty_signature_str;
158 * Swaps the message to compiler byte order if required
160 * @param message the message
163 _dbus_message_byteswap (DBusMessage *message)
165 const DBusString *type_str;
169 byte_order = _dbus_header_get_byte_order (&message->header);
171 if (byte_order == DBUS_COMPILER_BYTE_ORDER)
174 _dbus_verbose ("Swapping message into compiler byte order\n");
176 get_const_signature (&message->header, &type_str, &type_pos);
178 _dbus_marshal_byteswap (type_str, type_pos,
180 DBUS_COMPILER_BYTE_ORDER,
183 _dbus_header_byteswap (&message->header, DBUS_COMPILER_BYTE_ORDER);
184 _dbus_assert (_dbus_header_get_byte_order (&message->header) ==
185 DBUS_COMPILER_BYTE_ORDER);
188 /** byte-swap the message if it doesn't match our byte order.
189 * Called only when we need the message in our own byte order,
190 * normally when reading arrays of integers or doubles.
191 * Otherwise should not be called since it would do needless
194 #define ensure_byte_order(message) _dbus_message_byteswap (message)
197 * Gets the data to be sent over the network for this message.
198 * The header and then the body should be written out.
199 * This function is guaranteed to always return the same
200 * data once a message is locked (with dbus_message_lock()).
202 * @param message the message.
203 * @param header return location for message header data.
204 * @param body return location for message body data.
207 _dbus_message_get_network_data (DBusMessage *message,
208 const DBusString **header,
209 const DBusString **body)
211 _dbus_assert (message->locked);
213 *header = &message->header.data;
214 *body = &message->body;
218 * Gets the unix fds to be sent over the network for this message.
219 * This function is guaranteed to always return the same data once a
220 * message is locked (with dbus_message_lock()).
222 * @param message the message.
223 * @param fds return location of unix fd array
224 * @param n_fds return number of entries in array
226 void _dbus_message_get_unix_fds(DBusMessage *message,
230 _dbus_assert (message->locked);
232 #ifdef HAVE_UNIX_FD_PASSING
233 *fds = message->unix_fds;
234 *n_fds = message->n_unix_fds;
242 * Sets the serial number of a message.
243 * This can only be done once on a message.
245 * DBusConnection will automatically set the serial to an appropriate value
246 * when the message is sent; this function is only needed when encapsulating
247 * messages in another protocol, or otherwise bypassing DBusConnection.
249 * @param message the message
250 * @param serial the serial
253 dbus_message_set_serial (DBusMessage *message,
254 dbus_uint32_t serial)
256 _dbus_return_if_fail (message != NULL);
257 _dbus_return_if_fail (!message->locked);
259 _dbus_header_set_serial (&message->header, serial);
263 * Adds a counter to be incremented immediately with the size/unix fds
264 * of this message, and decremented by the size/unix fds of this
265 * message when this message if finalized. The link contains a
266 * counter with its refcount already incremented, but the counter
267 * itself not incremented. Ownership of link and counter refcount is
268 * passed to the message.
270 * This function may be called with locks held. As a result, the counter's
271 * notify function is not called; the caller is expected to either call
272 * _dbus_counter_notify() on the counter when they are no longer holding
273 * locks, or take the same action that would be taken by the notify function.
275 * @param message the message
276 * @param link link with counter as data
279 _dbus_message_add_counter_link (DBusMessage *message,
282 /* right now we don't recompute the delta when message
283 * size changes, and that's OK for current purposes
284 * I think, but could be important to change later.
285 * Do recompute it whenever there are no outstanding counters,
286 * since it's basically free.
288 if (message->counters == NULL)
290 message->size_counter_delta =
291 _dbus_string_get_length (&message->header.data) +
292 _dbus_string_get_length (&message->body);
294 #ifdef HAVE_UNIX_FD_PASSING
295 message->unix_fd_counter_delta = message->n_unix_fds;
299 _dbus_verbose ("message has size %ld\n",
300 message->size_counter_delta);
304 _dbus_list_append_link (&message->counters, link);
306 _dbus_counter_adjust_size (link->data, message->size_counter_delta);
308 #ifdef HAVE_UNIX_FD_PASSING
309 _dbus_counter_adjust_unix_fd (link->data, message->unix_fd_counter_delta);
314 * Adds a counter to be incremented immediately with the size/unix fds
315 * of this message, and decremented by the size/unix fds of this
316 * message when this message if finalized.
318 * This function may be called with locks held. As a result, the counter's
319 * notify function is not called; the caller is expected to either call
320 * _dbus_counter_notify() on the counter when they are no longer holding
321 * locks, or take the same action that would be taken by the notify function.
323 * @param message the message
324 * @param counter the counter
325 * @returns #FALSE if no memory
328 _dbus_message_add_counter (DBusMessage *message,
329 DBusCounter *counter)
333 link = _dbus_list_alloc_link (counter);
337 _dbus_counter_ref (counter);
338 _dbus_message_add_counter_link (message, link);
344 * Removes a counter tracking the size/unix fds of this message, and
345 * decrements the counter by the size/unix fds of this message.
347 * @param message the message
348 * @param counter the counter
351 _dbus_message_remove_counter (DBusMessage *message,
352 DBusCounter *counter)
356 link = _dbus_list_find_last (&message->counters,
358 _dbus_assert (link != NULL);
360 _dbus_list_remove_link (&message->counters, link);
362 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
364 #ifdef HAVE_UNIX_FD_PASSING
365 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
368 _dbus_counter_notify (counter);
369 _dbus_counter_unref (counter);
373 * Locks a message. Allows checking that applications don't keep a
374 * reference to a message in the outgoing queue and change it
375 * underneath us. Messages are locked when they enter the outgoing
376 * queue (dbus_connection_send_message()), and the library complains
377 * if the message is modified while locked. This function may also
378 * called externally, for applications wrapping D-Bus in another protocol.
380 * @param message the message to lock.
383 dbus_message_lock (DBusMessage *message)
385 if (!message->locked)
387 _dbus_header_update_lengths (&message->header,
388 _dbus_string_get_length (&message->body));
390 /* must have a signature if you have a body */
391 _dbus_assert (_dbus_string_get_length (&message->body) == 0 ||
392 dbus_message_get_signature (message) != NULL);
394 message->locked = TRUE;
399 set_or_delete_string_field (DBusMessage *message,
405 return _dbus_header_delete_field (&message->header, field);
407 return _dbus_header_set_field_basic (&message->header,
414 /* Probably we don't need to use this */
416 * Sets the signature of the message, i.e. the arguments in the
417 * message payload. The signature includes only "in" arguments for
418 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
419 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
420 * what you might expect (it does not include the signature of the
421 * entire C++-style method).
423 * The signature is a string made up of type codes such as
424 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
425 * the value of #DBUS_TYPE_INVALID). The macros such as
426 * #DBUS_TYPE_INT32 evaluate to integers; to assemble a signature you
427 * may find it useful to use the string forms, such as
428 * #DBUS_TYPE_INT32_AS_STRING.
430 * An "unset" or #NULL signature is considered the same as an empty
431 * signature. In fact dbus_message_get_signature() will never return
434 * @param message the message
435 * @param signature the type signature or #NULL to unset
436 * @returns #FALSE if no memory
439 _dbus_message_set_signature (DBusMessage *message,
440 const char *signature)
442 _dbus_return_val_if_fail (message != NULL, FALSE);
443 _dbus_return_val_if_fail (!message->locked, FALSE);
444 _dbus_return_val_if_fail (signature == NULL ||
445 _dbus_check_is_valid_signature (signature));
446 /* can't delete the signature if you have a message body */
447 _dbus_return_val_if_fail (_dbus_string_get_length (&message->body) == 0 ||
450 return set_or_delete_string_field (message,
451 DBUS_HEADER_FIELD_SIGNATURE,
459 * We cache some DBusMessage to reduce the overhead of allocating
460 * them. In my profiling this consistently made about an 8%
461 * difference. It avoids the malloc for the message, the malloc for
462 * the slot list, the malloc for the header string and body string,
463 * and the associated free() calls. It does introduce another global
464 * lock which could be a performance issue in certain cases.
466 * For the echo client/server the round trip time goes from around
467 * .000077 to .000069 with the message cache on my laptop. The sysprof
468 * change is as follows (numbers are cumulative percentage):
470 * with message cache implemented as array as it is now (0.000069 per):
471 * new_empty_header 1.46
472 * mutex_lock 0.56 # i.e. _DBUS_LOCK(message_cache)
478 * mutex_lock 0.33 # i.e. _DBUS_LOCK(message_cache)
481 * with message cache implemented as list (0.000070 per roundtrip):
482 * new_empty_header 2.72
483 * list_pop_first 1.88
487 * without cache (0.000077 per roundtrip):
488 * new_empty_header 6.7
489 * string_init_preallocated 3.43
498 * If you implement the message_cache with a list, the primary reason
499 * it's slower is that you add another thread lock (on the DBusList
503 /** Avoid caching huge messages */
504 #define MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE
506 /** Avoid caching too many messages */
507 #define MAX_MESSAGE_CACHE_SIZE 5
509 /* Protected by _DBUS_LOCK (message_cache) */
510 static DBusMessage *message_cache[MAX_MESSAGE_CACHE_SIZE];
511 static int message_cache_count = 0;
512 static dbus_bool_t message_cache_shutdown_registered = FALSE;
515 dbus_message_cache_shutdown (void *data)
519 if (!_DBUS_LOCK (message_cache))
520 _dbus_assert_not_reached ("we would have initialized global locks "
521 "before registering a shutdown function");
524 while (i < MAX_MESSAGE_CACHE_SIZE)
526 if (message_cache[i])
527 dbus_message_finalize (message_cache[i]);
532 message_cache_count = 0;
533 message_cache_shutdown_registered = FALSE;
535 _DBUS_UNLOCK (message_cache);
539 * Tries to get a message from the message cache. The retrieved
540 * message will have junk in it, so it still needs to be cleared out
541 * in dbus_message_new_empty_header()
543 * @returns the message, or #NULL if none cached
546 dbus_message_get_cached (void)
548 DBusMessage *message;
553 if (!_DBUS_LOCK (message_cache))
555 /* we'd have initialized global locks before caching anything,
556 * so there can't be anything in the cache */
560 _dbus_assert (message_cache_count >= 0);
562 if (message_cache_count == 0)
564 _DBUS_UNLOCK (message_cache);
568 /* This is not necessarily true unless count > 0, and
569 * message_cache is uninitialized until the shutdown is
572 _dbus_assert (message_cache_shutdown_registered);
575 while (i < MAX_MESSAGE_CACHE_SIZE)
577 if (message_cache[i])
579 message = message_cache[i];
580 message_cache[i] = NULL;
581 message_cache_count -= 1;
586 _dbus_assert (message_cache_count >= 0);
587 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
588 _dbus_assert (message != NULL);
590 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
592 _dbus_assert (message->counters == NULL);
594 _DBUS_UNLOCK (message_cache);
599 #ifdef HAVE_UNIX_FD_PASSING
601 close_unix_fds(int *fds, unsigned *n_fds)
611 for (i = 0; i < *n_fds; i++)
613 if (!_dbus_close(fds[i], &e))
615 _dbus_warn("Failed to close file descriptor: %s\n", e.message);
622 /* We don't free the array here, in case we can recycle it later */
627 free_counter (void *element,
630 DBusCounter *counter = element;
631 DBusMessage *message = data;
633 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
634 #ifdef HAVE_UNIX_FD_PASSING
635 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
638 _dbus_counter_notify (counter);
639 _dbus_counter_unref (counter);
643 * Tries to cache a message, otherwise finalize it.
645 * @param message the message
648 dbus_message_cache_or_finalize (DBusMessage *message)
650 dbus_bool_t was_cached;
653 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
655 /* This calls application code and has to be done first thing
656 * without holding the lock
658 _dbus_data_slot_list_clear (&message->slot_list);
660 _dbus_list_foreach (&message->counters,
661 free_counter, message);
662 _dbus_list_clear (&message->counters);
664 #ifdef HAVE_UNIX_FD_PASSING
665 close_unix_fds(message->unix_fds, &message->n_unix_fds);
670 if (!_DBUS_LOCK (message_cache))
672 /* The only way to get a non-null message goes through
673 * dbus_message_get_cached() which takes the lock. */
674 _dbus_assert_not_reached ("we would have initialized global locks "
675 "the first time we constructed a message");
678 if (!message_cache_shutdown_registered)
680 _dbus_assert (message_cache_count == 0);
682 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
686 while (i < MAX_MESSAGE_CACHE_SIZE)
688 message_cache[i] = NULL;
692 message_cache_shutdown_registered = TRUE;
695 _dbus_assert (message_cache_count >= 0);
697 if (!_dbus_enable_message_cache ())
700 if ((_dbus_string_get_length (&message->header.data) +
701 _dbus_string_get_length (&message->body)) >
702 MAX_MESSAGE_SIZE_TO_CACHE)
705 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
708 /* Find empty slot */
710 while (message_cache[i] != NULL)
713 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
715 _dbus_assert (message_cache[i] == NULL);
716 message_cache[i] = message;
717 message_cache_count += 1;
719 #ifndef DBUS_DISABLE_CHECKS
720 message->in_cache = TRUE;
724 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
726 _DBUS_UNLOCK (message_cache);
729 dbus_message_finalize (message);
732 #if defined(DBUS_ENABLE_CHECKS) || defined(DBUS_ENABLE_ASSERT)
734 _dbus_message_iter_check (DBusMessageRealIter *iter)
740 _dbus_warn_check_failed ("dbus message iterator is NULL\n");
744 byte_order = _dbus_header_get_byte_order (&iter->message->header);
746 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
748 if (iter->u.reader.byte_order != byte_order)
750 _dbus_warn_check_failed ("dbus message changed byte order since iterator was created\n");
753 /* because we swap the message into compiler order when you init an iter */
754 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
756 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
758 if (iter->u.writer.byte_order != byte_order)
760 _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created\n");
763 /* because we swap the message into compiler order when you init an iter */
764 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
768 _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted\n");
772 if (iter->changed_stamp != iter->message->changed_stamp)
774 _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
780 #endif /* DBUS_ENABLE_CHECKS || DBUS_ENABLE_ASSERT */
783 * Implementation of the varargs arg-getting functions.
784 * dbus_message_get_args() is the place to go for complete
787 * @todo This may leak memory and file descriptors if parsing fails. See #21259
789 * @see dbus_message_get_args
790 * @param iter the message iter
791 * @param error error to be filled in
792 * @param first_arg_type type of the first argument
793 * @param var_args return location for first argument, followed by list of type/location pairs
794 * @returns #FALSE if error was set
797 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
802 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
803 int spec_type, msg_type, i;
806 _dbus_assert (_dbus_message_iter_check (real));
810 spec_type = first_arg_type;
813 while (spec_type != DBUS_TYPE_INVALID)
815 msg_type = dbus_message_iter_get_arg_type (iter);
817 if (msg_type != spec_type)
819 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
820 "Argument %d is specified to be of type \"%s\", but "
821 "is actually of type \"%s\"\n", i,
822 _dbus_type_to_string (spec_type),
823 _dbus_type_to_string (msg_type));
828 if (spec_type == DBUS_TYPE_UNIX_FD)
830 #ifdef HAVE_UNIX_FD_PASSING
834 pfd = va_arg (var_args, int*);
837 _dbus_type_reader_read_basic(&real->u.reader, &idx);
839 if (idx.u32 >= real->message->n_unix_fds)
841 dbus_set_error (error, DBUS_ERROR_INCONSISTENT_MESSAGE,
842 "Message refers to file descriptor at index %i,"
843 "but has only %i descriptors attached.\n",
845 real->message->n_unix_fds);
849 if ((nfd = _dbus_dup(real->message->unix_fds[idx.u32], error)) < 0)
854 dbus_set_error (error, DBUS_ERROR_NOT_SUPPORTED,
855 "Platform does not support file desciptor passing.\n");
859 else if (dbus_type_is_basic (spec_type))
863 ptr = va_arg (var_args, DBusBasicValue*);
865 _dbus_assert (ptr != NULL);
867 _dbus_type_reader_read_basic (&real->u.reader,
870 else if (spec_type == DBUS_TYPE_ARRAY)
873 int spec_element_type;
874 const DBusBasicValue **ptr;
876 DBusTypeReader array;
878 spec_element_type = va_arg (var_args, int);
879 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
881 if (spec_element_type != element_type)
883 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
884 "Argument %d is specified to be an array of \"%s\", but "
885 "is actually an array of \"%s\"\n",
887 _dbus_type_to_string (spec_element_type),
888 _dbus_type_to_string (element_type));
893 if (dbus_type_is_fixed (spec_element_type) &&
894 element_type != DBUS_TYPE_UNIX_FD)
896 ptr = va_arg (var_args, const DBusBasicValue**);
897 n_elements_p = va_arg (var_args, int*);
899 _dbus_assert (ptr != NULL);
900 _dbus_assert (n_elements_p != NULL);
902 _dbus_type_reader_recurse (&real->u.reader, &array);
904 _dbus_type_reader_read_fixed_multi (&array,
905 (void *) ptr, n_elements_p);
907 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
913 str_array_p = va_arg (var_args, char***);
914 n_elements_p = va_arg (var_args, int*);
916 _dbus_assert (str_array_p != NULL);
917 _dbus_assert (n_elements_p != NULL);
919 /* Count elements in the array */
920 _dbus_type_reader_recurse (&real->u.reader, &array);
923 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
926 _dbus_type_reader_next (&array);
929 str_array = dbus_new0 (char*, n_elements + 1);
930 if (str_array == NULL)
932 _DBUS_SET_OOM (error);
936 /* Now go through and dup each string */
937 _dbus_type_reader_recurse (&real->u.reader, &array);
940 while (i < n_elements)
943 _dbus_type_reader_read_basic (&array,
946 str_array[i] = _dbus_strdup (s);
947 if (str_array[i] == NULL)
949 dbus_free_string_array (str_array);
950 _DBUS_SET_OOM (error);
956 if (!_dbus_type_reader_next (&array))
957 _dbus_assert (i == n_elements);
960 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
961 _dbus_assert (i == n_elements);
962 _dbus_assert (str_array[i] == NULL);
964 *str_array_p = str_array;
965 *n_elements_p = n_elements;
967 #ifndef DBUS_DISABLE_CHECKS
970 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
971 _DBUS_FUNCTION_NAME);
976 #ifndef DBUS_DISABLE_CHECKS
979 _dbus_warn ("you can only read arrays and basic types with %s for now\n",
980 _DBUS_FUNCTION_NAME);
985 spec_type = va_arg (var_args, int);
986 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
988 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
989 "Message has only %d arguments, but more were expected", i);
1006 * @defgroup DBusMessage DBusMessage
1008 * @brief Message to be sent or received over a #DBusConnection.
1010 * A DBusMessage is the most basic unit of communication over a
1011 * DBusConnection. A DBusConnection represents a stream of messages
1012 * received from a remote application, and a stream of messages
1013 * sent to a remote application.
1015 * A message has a message type, returned from
1016 * dbus_message_get_type(). This indicates whether the message is a
1017 * method call, a reply to a method call, a signal, or an error reply.
1019 * A message has header fields such as the sender, destination, method
1020 * or signal name, and so forth. DBusMessage has accessor functions for
1021 * these, such as dbus_message_get_member().
1023 * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
1024 * and dbus_message_is_error() check several header fields at once and are
1025 * slightly more efficient than checking the header fields with individual
1026 * accessor functions.
1028 * Finally, a message has arguments. The number and types of arguments
1029 * are in the message's signature header field (accessed with
1030 * dbus_message_get_signature()). Simple argument values are usually
1031 * retrieved with dbus_message_get_args() but more complex values such
1032 * as structs may require the use of #DBusMessageIter.
1034 * The D-Bus specification goes into some more detail about header fields and
1041 * @typedef DBusMessage
1043 * Opaque data type representing a message received from or to be
1044 * sent to another application.
1048 * Returns the serial of a message or 0 if none has been specified.
1049 * The message's serial number is provided by the application sending
1050 * the message and is used to identify replies to this message.
1052 * All messages received on a connection will have a serial provided
1053 * by the remote application.
1055 * For messages you're sending, dbus_connection_send() will assign a
1056 * serial and return it to you.
1058 * @param message the message
1059 * @returns the serial
1062 dbus_message_get_serial (DBusMessage *message)
1064 _dbus_return_val_if_fail (message != NULL, 0);
1066 return _dbus_header_get_serial (&message->header);
1070 * Sets the reply serial of a message (the serial of the message this
1073 * @param message the message
1074 * @param reply_serial the serial we're replying to
1075 * @returns #FALSE if not enough memory
1078 dbus_message_set_reply_serial (DBusMessage *message,
1079 dbus_uint32_t reply_serial)
1081 _dbus_return_val_if_fail (message != NULL, FALSE);
1082 _dbus_return_val_if_fail (!message->locked, FALSE);
1083 _dbus_return_val_if_fail (reply_serial != 0, FALSE); /* 0 is invalid */
1085 return _dbus_header_set_field_basic (&message->header,
1086 DBUS_HEADER_FIELD_REPLY_SERIAL,
1092 * Returns the serial that the message is a reply to or 0 if none.
1094 * @param message the message
1095 * @returns the reply serial
1098 dbus_message_get_reply_serial (DBusMessage *message)
1100 dbus_uint32_t v_UINT32;
1102 _dbus_return_val_if_fail (message != NULL, 0);
1104 if (_dbus_header_get_field_basic (&message->header,
1105 DBUS_HEADER_FIELD_REPLY_SERIAL,
1114 dbus_message_finalize (DBusMessage *message)
1116 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1118 /* This calls application callbacks! */
1119 _dbus_data_slot_list_free (&message->slot_list);
1121 _dbus_list_foreach (&message->counters,
1122 free_counter, message);
1123 _dbus_list_clear (&message->counters);
1125 _dbus_header_free (&message->header);
1126 _dbus_string_free (&message->body);
1128 #ifdef HAVE_UNIX_FD_PASSING
1129 close_unix_fds(message->unix_fds, &message->n_unix_fds);
1130 dbus_free(message->unix_fds);
1133 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1135 dbus_free (message);
1139 dbus_message_new_empty_header (void)
1141 DBusMessage *message;
1142 dbus_bool_t from_cache;
1144 message = dbus_message_get_cached ();
1146 if (message != NULL)
1153 message = dbus_new0 (DBusMessage, 1);
1154 if (message == NULL)
1156 #ifndef DBUS_DISABLE_CHECKS
1157 message->generation = _dbus_current_generation;
1160 #ifdef HAVE_UNIX_FD_PASSING
1161 message->unix_fds = NULL;
1162 message->n_unix_fds_allocated = 0;
1166 _dbus_atomic_inc (&message->refcount);
1168 _dbus_message_trace_ref (message, 0, 1, "new_empty_header");
1170 message->locked = FALSE;
1171 #ifndef DBUS_DISABLE_CHECKS
1172 message->in_cache = FALSE;
1174 message->counters = NULL;
1175 message->size_counter_delta = 0;
1176 message->changed_stamp = 0;
1178 #ifdef HAVE_UNIX_FD_PASSING
1179 message->n_unix_fds = 0;
1180 message->n_unix_fds_allocated = 0;
1181 message->unix_fd_counter_delta = 0;
1185 _dbus_data_slot_list_init (&message->slot_list);
1189 _dbus_header_reinit (&message->header);
1190 _dbus_string_set_length (&message->body, 0);
1194 if (!_dbus_header_init (&message->header))
1196 dbus_free (message);
1200 if (!_dbus_string_init_preallocated (&message->body, 32))
1202 _dbus_header_free (&message->header);
1203 dbus_free (message);
1212 * Constructs a new message of the given message type.
1213 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
1214 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
1216 * Usually you want to use dbus_message_new_method_call(),
1217 * dbus_message_new_method_return(), dbus_message_new_signal(),
1218 * or dbus_message_new_error() instead.
1220 * @param message_type type of message
1221 * @returns new message or #NULL if no memory
1224 dbus_message_new (int message_type)
1226 DBusMessage *message;
1228 _dbus_return_val_if_fail (message_type != DBUS_MESSAGE_TYPE_INVALID, NULL);
1230 message = dbus_message_new_empty_header ();
1231 if (message == NULL)
1234 if (!_dbus_header_create (&message->header,
1235 DBUS_COMPILER_BYTE_ORDER,
1237 NULL, NULL, NULL, NULL, NULL))
1239 dbus_message_unref (message);
1247 * Constructs a new message to invoke a method on a remote
1248 * object. Returns #NULL if memory can't be allocated for the
1249 * message. The destination may be #NULL in which case no destination
1250 * is set; this is appropriate when using D-Bus in a peer-to-peer
1251 * context (no message bus). The interface may be #NULL, which means
1252 * that if multiple methods with the given name exist it is undefined
1253 * which one will be invoked.
1255 * The path and method names may not be #NULL.
1257 * Destination, path, interface, and method name can't contain
1258 * any invalid characters (see the D-Bus specification).
1260 * @param destination name that the message should be sent to or #NULL
1261 * @param path object path the message should be sent to
1262 * @param interface interface to invoke method on, or #NULL
1263 * @param method method to invoke
1265 * @returns a new DBusMessage, free with dbus_message_unref()
1268 dbus_message_new_method_call (const char *destination,
1270 const char *interface,
1273 DBusMessage *message;
1275 _dbus_return_val_if_fail (path != NULL, NULL);
1276 _dbus_return_val_if_fail (method != NULL, NULL);
1277 _dbus_return_val_if_fail (destination == NULL ||
1278 _dbus_check_is_valid_bus_name (destination), NULL);
1279 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1280 _dbus_return_val_if_fail (interface == NULL ||
1281 _dbus_check_is_valid_interface (interface), NULL);
1282 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
1284 message = dbus_message_new_empty_header ();
1285 if (message == NULL)
1288 if (!_dbus_header_create (&message->header,
1289 DBUS_COMPILER_BYTE_ORDER,
1290 DBUS_MESSAGE_TYPE_METHOD_CALL,
1291 destination, path, interface, method, NULL))
1293 dbus_message_unref (message);
1301 * Constructs a message that is a reply to a method call. Returns
1302 * #NULL if memory can't be allocated for the message.
1304 * @param method_call the message being replied to
1305 * @returns a new DBusMessage, free with dbus_message_unref()
1308 dbus_message_new_method_return (DBusMessage *method_call)
1310 DBusMessage *message;
1313 _dbus_return_val_if_fail (method_call != NULL, NULL);
1315 sender = dbus_message_get_sender (method_call);
1317 /* sender is allowed to be null here in peer-to-peer case */
1319 message = dbus_message_new_empty_header ();
1320 if (message == NULL)
1323 if (!_dbus_header_create (&message->header,
1324 DBUS_COMPILER_BYTE_ORDER,
1325 DBUS_MESSAGE_TYPE_METHOD_RETURN,
1326 sender, NULL, NULL, NULL, NULL))
1328 dbus_message_unref (message);
1332 dbus_message_set_no_reply (message, TRUE);
1334 if (!dbus_message_set_reply_serial (message,
1335 dbus_message_get_serial (method_call)))
1337 dbus_message_unref (message);
1345 * Constructs a new message representing a signal emission. Returns
1346 * #NULL if memory can't be allocated for the message. A signal is
1347 * identified by its originating object path, interface, and the name
1350 * Path, interface, and signal name must all be valid (the D-Bus
1351 * specification defines the syntax of these fields).
1353 * @param path the path to the object emitting the signal
1354 * @param interface the interface the signal is emitted from
1355 * @param name name of the signal
1356 * @returns a new DBusMessage, free with dbus_message_unref()
1359 dbus_message_new_signal (const char *path,
1360 const char *interface,
1363 DBusMessage *message;
1365 _dbus_return_val_if_fail (path != NULL, NULL);
1366 _dbus_return_val_if_fail (interface != NULL, NULL);
1367 _dbus_return_val_if_fail (name != NULL, NULL);
1368 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1369 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (interface), NULL);
1370 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
1372 message = dbus_message_new_empty_header ();
1373 if (message == NULL)
1376 if (!_dbus_header_create (&message->header,
1377 DBUS_COMPILER_BYTE_ORDER,
1378 DBUS_MESSAGE_TYPE_SIGNAL,
1379 NULL, path, interface, name, NULL))
1381 dbus_message_unref (message);
1385 dbus_message_set_no_reply (message, TRUE);
1391 * Creates a new message that is an error reply to another message.
1392 * Error replies are most common in response to method calls, but
1393 * can be returned in reply to any message.
1395 * The error name must be a valid error name according to the syntax
1396 * given in the D-Bus specification. If you don't want to make
1397 * up an error name just use #DBUS_ERROR_FAILED.
1399 * @param reply_to the message we're replying to
1400 * @param error_name the error name
1401 * @param error_message the error message string (or #NULL for none, but please give a message)
1402 * @returns a new error message object, free with dbus_message_unref()
1405 dbus_message_new_error (DBusMessage *reply_to,
1406 const char *error_name,
1407 const char *error_message)
1409 DBusMessage *message;
1411 DBusMessageIter iter;
1413 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1414 _dbus_return_val_if_fail (error_name != NULL, NULL);
1415 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1417 sender = dbus_message_get_sender (reply_to);
1419 /* sender may be NULL for non-message-bus case or
1420 * when the message bus is dealing with an unregistered
1423 message = dbus_message_new_empty_header ();
1424 if (message == NULL)
1427 if (!_dbus_header_create (&message->header,
1428 DBUS_COMPILER_BYTE_ORDER,
1429 DBUS_MESSAGE_TYPE_ERROR,
1430 sender, NULL, NULL, NULL, error_name))
1432 dbus_message_unref (message);
1436 dbus_message_set_no_reply (message, TRUE);
1438 if (!dbus_message_set_reply_serial (message,
1439 dbus_message_get_serial (reply_to)))
1441 dbus_message_unref (message);
1445 if (error_message != NULL)
1447 dbus_message_iter_init_append (message, &iter);
1448 if (!dbus_message_iter_append_basic (&iter,
1452 dbus_message_unref (message);
1461 * Creates a new message that is an error reply to another message, allowing
1462 * you to use printf formatting.
1464 * See dbus_message_new_error() for details - this function is the same
1465 * aside from the printf formatting.
1467 * @todo add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to
1468 * public header, see DBUS_DEPRECATED for an example)
1470 * @param reply_to the original message
1471 * @param error_name the error name
1472 * @param error_format the error message format as with printf
1473 * @param ... format string arguments
1474 * @returns a new error message
1477 dbus_message_new_error_printf (DBusMessage *reply_to,
1478 const char *error_name,
1479 const char *error_format,
1484 DBusMessage *message;
1486 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1487 _dbus_return_val_if_fail (error_name != NULL, NULL);
1488 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1490 if (!_dbus_string_init (&str))
1493 va_start (args, error_format);
1495 if (_dbus_string_append_printf_valist (&str, error_format, args))
1496 message = dbus_message_new_error (reply_to, error_name,
1497 _dbus_string_get_const_data (&str));
1501 _dbus_string_free (&str);
1510 * Creates a new message that is an exact replica of the message
1511 * specified, except that its refcount is set to 1, its message serial
1512 * is reset to 0, and if the original message was "locked" (in the
1513 * outgoing message queue and thus not modifiable) the new message
1514 * will not be locked.
1516 * @todo This function can't be used in programs that try to recover from OOM errors.
1518 * @param message the message
1519 * @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.
1522 dbus_message_copy (const DBusMessage *message)
1524 DBusMessage *retval;
1526 _dbus_return_val_if_fail (message != NULL, NULL);
1528 retval = dbus_new0 (DBusMessage, 1);
1532 _dbus_atomic_inc (&retval->refcount);
1534 retval->locked = FALSE;
1535 #ifndef DBUS_DISABLE_CHECKS
1536 retval->generation = message->generation;
1539 if (!_dbus_header_copy (&message->header, &retval->header))
1545 if (!_dbus_string_init_preallocated (&retval->body,
1546 _dbus_string_get_length (&message->body)))
1548 _dbus_header_free (&retval->header);
1553 if (!_dbus_string_copy (&message->body, 0,
1557 #ifdef HAVE_UNIX_FD_PASSING
1558 retval->unix_fds = dbus_new(int, message->n_unix_fds);
1559 if (retval->unix_fds == NULL && message->n_unix_fds > 0)
1562 retval->n_unix_fds_allocated = message->n_unix_fds;
1564 for (retval->n_unix_fds = 0;
1565 retval->n_unix_fds < message->n_unix_fds;
1566 retval->n_unix_fds++)
1568 retval->unix_fds[retval->n_unix_fds] = _dbus_dup(message->unix_fds[retval->n_unix_fds], NULL);
1570 if (retval->unix_fds[retval->n_unix_fds] < 0)
1576 _dbus_message_trace_ref (retval, 0, 1, "copy");
1580 _dbus_header_free (&retval->header);
1581 _dbus_string_free (&retval->body);
1583 #ifdef HAVE_UNIX_FD_PASSING
1584 close_unix_fds(retval->unix_fds, &retval->n_unix_fds);
1585 dbus_free(retval->unix_fds);
1595 * Increments the reference count of a DBusMessage.
1597 * @param message the message
1598 * @returns the message
1599 * @see dbus_message_unref
1602 dbus_message_ref (DBusMessage *message)
1604 dbus_int32_t old_refcount;
1606 _dbus_return_val_if_fail (message != NULL, NULL);
1607 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1608 _dbus_return_val_if_fail (!message->in_cache, NULL);
1610 old_refcount = _dbus_atomic_inc (&message->refcount);
1611 _dbus_assert (old_refcount >= 1);
1612 _dbus_message_trace_ref (message, old_refcount, old_refcount + 1, "ref");
1618 * Decrements the reference count of a DBusMessage, freeing the
1619 * message if the count reaches 0.
1621 * @param message the message
1622 * @see dbus_message_ref
1625 dbus_message_unref (DBusMessage *message)
1627 dbus_int32_t old_refcount;
1629 _dbus_return_if_fail (message != NULL);
1630 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1631 _dbus_return_if_fail (!message->in_cache);
1633 old_refcount = _dbus_atomic_dec (&message->refcount);
1635 _dbus_assert (old_refcount >= 1);
1637 _dbus_message_trace_ref (message, old_refcount, old_refcount - 1, "unref");
1639 if (old_refcount == 1)
1641 /* Calls application callbacks! */
1642 dbus_message_cache_or_finalize (message);
1647 * Gets the type of a message. Types include
1648 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1649 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1650 * types are allowed and all code must silently ignore messages of
1651 * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
1653 * @param message the message
1654 * @returns the type of the message
1657 dbus_message_get_type (DBusMessage *message)
1659 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1661 return _dbus_header_get_message_type (&message->header);
1665 * Appends fields to a message given a variable argument list. The
1666 * variable argument list should contain the type of each argument
1667 * followed by the value to append. Appendable types are basic types,
1668 * and arrays of fixed-length basic types (except arrays of Unix file
1669 * descriptors). To append variable-length basic types, or any more
1670 * complex value, you have to use an iterator rather than this
1673 * To append a basic type, specify its type code followed by the
1674 * address of the value. For example:
1678 * dbus_int32_t v_INT32 = 42;
1679 * const char *v_STRING = "Hello World";
1680 * dbus_message_append_args (message,
1681 * DBUS_TYPE_INT32, &v_INT32,
1682 * DBUS_TYPE_STRING, &v_STRING,
1683 * DBUS_TYPE_INVALID);
1686 * To append an array of fixed-length basic types (except Unix file
1687 * descriptors), pass in the DBUS_TYPE_ARRAY typecode, the element
1688 * typecode, the address of the array pointer, and a 32-bit integer
1689 * giving the number of elements in the array. So for example: @code
1690 * const dbus_int32_t array[] = { 1, 2, 3 }; const dbus_int32_t
1691 * *v_ARRAY = array; dbus_message_append_args (message,
1692 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3, DBUS_TYPE_INVALID);
1695 * This function does not support arrays of Unix file descriptors. If
1696 * you need those you need to manually recurse into the array.
1698 * For Unix file descriptors this function will internally duplicate
1699 * the descriptor you passed in. Hence you may close the descriptor
1700 * immediately after this call.
1702 * @warning in C, given "int array[]", "&array == array" (the
1703 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
1704 * So if you're using an array instead of a pointer you have to create
1705 * a pointer variable, assign the array to it, then take the address
1706 * of the pointer variable. For strings it works to write
1707 * const char *array = "Hello" and then use &array though.
1709 * The last argument to this function must be #DBUS_TYPE_INVALID,
1710 * marking the end of the argument list. If you don't do this
1711 * then libdbus won't know to stop and will read invalid memory.
1713 * String/signature/path arrays should be passed in as "const char***
1714 * address_of_array" and "int n_elements"
1716 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1718 * @todo If this fails due to lack of memory, the message is hosed and
1719 * you have to start over building the whole message.
1721 * @param message the message
1722 * @param first_arg_type type of the first argument
1723 * @param ... value of first argument, list of additional type-value pairs
1724 * @returns #TRUE on success
1727 dbus_message_append_args (DBusMessage *message,
1734 _dbus_return_val_if_fail (message != NULL, FALSE);
1736 va_start (var_args, first_arg_type);
1737 retval = dbus_message_append_args_valist (message,
1746 * Like dbus_message_append_args() but takes a va_list for use by language bindings.
1748 * @todo for now, if this function fails due to OOM it will leave
1749 * the message half-written and you have to discard the message
1752 * @see dbus_message_append_args.
1753 * @param message the message
1754 * @param first_arg_type type of first argument
1755 * @param var_args value of first argument, then list of type/value pairs
1756 * @returns #TRUE on success
1759 dbus_message_append_args_valist (DBusMessage *message,
1764 DBusMessageIter iter;
1766 _dbus_return_val_if_fail (message != NULL, FALSE);
1768 type = first_arg_type;
1770 dbus_message_iter_init_append (message, &iter);
1772 while (type != DBUS_TYPE_INVALID)
1774 if (dbus_type_is_basic (type))
1776 const DBusBasicValue *value;
1777 value = va_arg (var_args, const DBusBasicValue*);
1779 if (!dbus_message_iter_append_basic (&iter,
1784 else if (type == DBUS_TYPE_ARRAY)
1787 DBusMessageIter array;
1790 element_type = va_arg (var_args, int);
1792 buf[0] = element_type;
1794 if (!dbus_message_iter_open_container (&iter,
1800 if (dbus_type_is_fixed (element_type) &&
1801 element_type != DBUS_TYPE_UNIX_FD)
1803 const DBusBasicValue **value;
1806 value = va_arg (var_args, const DBusBasicValue**);
1807 n_elements = va_arg (var_args, int);
1809 if (!dbus_message_iter_append_fixed_array (&array,
1813 dbus_message_iter_abandon_container (&iter, &array);
1817 else if (_DBUS_TYPE_IS_STRINGLIKE (element_type))
1819 const char ***value_p;
1824 value_p = va_arg (var_args, const char***);
1825 n_elements = va_arg (var_args, int);
1830 while (i < n_elements)
1832 if (!dbus_message_iter_append_basic (&array,
1835 dbus_message_iter_abandon_container (&iter, &array);
1843 _dbus_warn ("arrays of %s can't be appended with %s for now\n",
1844 _dbus_type_to_string (element_type),
1845 _DBUS_FUNCTION_NAME);
1849 if (!dbus_message_iter_close_container (&iter, &array))
1852 #ifndef DBUS_DISABLE_CHECKS
1855 _dbus_warn ("type %s isn't supported yet in %s\n",
1856 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
1861 type = va_arg (var_args, int);
1871 * Gets arguments from a message given a variable argument list. The
1872 * supported types include those supported by
1873 * dbus_message_append_args(); that is, basic types and arrays of
1874 * fixed-length basic types. The arguments are the same as they would
1875 * be for dbus_message_iter_get_basic() or
1876 * dbus_message_iter_get_fixed_array().
1878 * In addition to those types, arrays of string, object path, and
1879 * signature are supported; but these are returned as allocated memory
1880 * and must be freed with dbus_free_string_array(), while the other
1881 * types are returned as const references. To get a string array
1882 * pass in "char ***array_location" and "int *n_elements".
1884 * Similar to dbus_message_get_fixed_array() this function does not
1885 * support arrays of type DBUS_TYPE_UNIX_FD. If you need to parse
1886 * messages with arrays of Unix file descriptors you need to recurse
1887 * into the array manually.
1889 * Unix file descriptors that are read with this function will have
1890 * the FD_CLOEXEC flag set. If you need them without this flag set,
1891 * make sure to unset it with fcntl().
1893 * The variable argument list should contain the type of the argument
1894 * followed by a pointer to where the value should be stored. The list
1895 * is terminated with #DBUS_TYPE_INVALID.
1897 * Except for string arrays, the returned values are constant; do not
1898 * free them. They point into the #DBusMessage.
1900 * If the requested arguments are not present, or do not have the
1901 * requested types, then an error will be set.
1903 * If more arguments than requested are present, the requested
1904 * arguments are returned and the extra arguments are ignored.
1906 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1908 * @param message the message
1909 * @param error error to be filled in on failure
1910 * @param first_arg_type the first argument type
1911 * @param ... location for first argument value, then list of type-location pairs
1912 * @returns #FALSE if the error was set
1915 dbus_message_get_args (DBusMessage *message,
1923 _dbus_return_val_if_fail (message != NULL, FALSE);
1924 _dbus_return_val_if_error_is_set (error, FALSE);
1926 va_start (var_args, first_arg_type);
1927 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
1934 * Like dbus_message_get_args but takes a va_list for use by language bindings.
1936 * @see dbus_message_get_args
1937 * @param message the message
1938 * @param error error to be filled in
1939 * @param first_arg_type type of the first argument
1940 * @param var_args return location for first argument, followed by list of type/location pairs
1941 * @returns #FALSE if error was set
1944 dbus_message_get_args_valist (DBusMessage *message,
1949 DBusMessageIter iter;
1951 _dbus_return_val_if_fail (message != NULL, FALSE);
1952 _dbus_return_val_if_error_is_set (error, FALSE);
1954 dbus_message_iter_init (message, &iter);
1955 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
1959 _dbus_message_iter_init_common (DBusMessage *message,
1960 DBusMessageRealIter *real,
1963 _dbus_assert (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
1965 /* Since the iterator will read or write who-knows-what from the
1966 * message, we need to get in the right byte order
1968 ensure_byte_order (message);
1970 real->message = message;
1971 real->changed_stamp = message->changed_stamp;
1972 real->iter_type = iter_type;
1973 real->sig_refcount = 0;
1977 * Initializes a #DBusMessageIter for reading the arguments of the
1978 * message passed in.
1980 * When possible, dbus_message_get_args() is much more convenient.
1981 * Some types of argument can only be read with #DBusMessageIter
1984 * The easiest way to iterate is like this:
1986 * dbus_message_iter_init (message, &iter);
1987 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
1988 * dbus_message_iter_next (&iter);
1991 * #DBusMessageIter contains no allocated memory; it need not be
1992 * freed, and can be copied by assignment or memcpy().
1994 * @param message the message
1995 * @param iter pointer to an iterator to initialize
1996 * @returns #FALSE if the message has no arguments
1999 dbus_message_iter_init (DBusMessage *message,
2000 DBusMessageIter *iter)
2002 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2003 const DBusString *type_str;
2006 _dbus_return_val_if_fail (message != NULL, FALSE);
2007 _dbus_return_val_if_fail (iter != NULL, FALSE);
2009 get_const_signature (&message->header, &type_str, &type_pos);
2011 _dbus_message_iter_init_common (message, real,
2012 DBUS_MESSAGE_ITER_TYPE_READER);
2014 _dbus_type_reader_init (&real->u.reader,
2015 _dbus_header_get_byte_order (&message->header),
2020 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
2024 * Checks if an iterator has any more fields.
2026 * @param iter the message iter
2027 * @returns #TRUE if there are more fields following
2030 dbus_message_iter_has_next (DBusMessageIter *iter)
2032 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2034 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2035 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2037 return _dbus_type_reader_has_next (&real->u.reader);
2041 * Moves the iterator to the next field, if any. If there's no next
2042 * field, returns #FALSE. If the iterator moves forward, returns
2045 * @param iter the message iter
2046 * @returns #TRUE if the iterator was moved to the next field
2049 dbus_message_iter_next (DBusMessageIter *iter)
2051 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2053 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2054 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2056 return _dbus_type_reader_next (&real->u.reader);
2060 * Returns the argument type of the argument that the message iterator
2061 * points to. If the iterator is at the end of the message, returns
2062 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
2065 * dbus_message_iter_init (message, &iter);
2066 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2067 * dbus_message_iter_next (&iter);
2070 * @param iter the message iter
2071 * @returns the argument type
2074 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
2076 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2078 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2079 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2081 return _dbus_type_reader_get_current_type (&real->u.reader);
2085 * Returns the element type of the array that the message iterator
2086 * points to. Note that you need to check that the iterator points to
2087 * an array prior to using this function.
2089 * @param iter the message iter
2090 * @returns the array element type
2093 dbus_message_iter_get_element_type (DBusMessageIter *iter)
2095 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2097 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2098 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
2099 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
2101 return _dbus_type_reader_get_element_type (&real->u.reader);
2105 * Recurses into a container value when reading values from a message,
2106 * initializing a sub-iterator to use for traversing the child values
2109 * Note that this recurses into a value, not a type, so you can only
2110 * recurse if the value exists. The main implication of this is that
2111 * if you have for example an empty array of array of int32, you can
2112 * recurse into the outermost array, but it will have no values, so
2113 * you won't be able to recurse further. There's no array of int32 to
2116 * If a container is an array of fixed-length types (except Unix file
2117 * descriptors), it is much more efficient to use
2118 * dbus_message_iter_get_fixed_array() to get the whole array in one
2119 * shot, rather than individually walking over the array elements.
2121 * Be sure you have somehow checked that
2122 * dbus_message_iter_get_arg_type() matches the type you are expecting
2123 * to recurse into. Results of this function are undefined if there is
2124 * no container to recurse into at the current iterator position.
2126 * @param iter the message iterator
2127 * @param sub the sub-iterator to initialize
2130 dbus_message_iter_recurse (DBusMessageIter *iter,
2131 DBusMessageIter *sub)
2133 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2134 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2136 _dbus_return_if_fail (_dbus_message_iter_check (real));
2137 _dbus_return_if_fail (sub != NULL);
2140 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
2144 * Returns the current signature of a message iterator. This
2145 * is useful primarily for dealing with variants; one can
2146 * recurse into a variant and determine the signature of
2147 * the variant's value.
2149 * The returned string must be freed with dbus_free().
2151 * @param iter the message iterator
2152 * @returns the contained signature, or NULL if out of memory
2155 dbus_message_iter_get_signature (DBusMessageIter *iter)
2157 const DBusString *sig;
2161 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2163 _dbus_return_val_if_fail (_dbus_message_iter_check (real), NULL);
2165 if (!_dbus_string_init (&retstr))
2168 _dbus_type_reader_get_signature (&real->u.reader, &sig,
2170 if (!_dbus_string_append_len (&retstr,
2171 _dbus_string_get_const_data (sig) + start,
2174 if (!_dbus_string_steal_data (&retstr, &ret))
2176 _dbus_string_free (&retstr);
2181 * Reads a basic-typed value from the message iterator.
2182 * Basic types are the non-containers such as integer and string.
2184 * The value argument should be the address of a location to store
2185 * the returned value. So for int32 it should be a "dbus_int32_t*"
2186 * and for string a "const char**". The returned value is
2187 * by reference and should not be freed.
2189 * This call duplicates Unix file descriptors when reading them. It is
2190 * your job to close them when you don't need them anymore.
2192 * Unix file descriptors that are read with this function will have
2193 * the FD_CLOEXEC flag set. If you need them without this flag set,
2194 * make sure to unset it with fcntl().
2196 * Be sure you have somehow checked that
2197 * dbus_message_iter_get_arg_type() matches the type you are
2198 * expecting, or you'll crash when you try to use an integer as a
2199 * string or something.
2201 * To read any container type (array, struct, dict) you will need to
2202 * recurse into the container with dbus_message_iter_recurse(). If
2203 * the container is an array of fixed-length values (except Unix file
2204 * descriptors), you can get all the array elements at once with
2205 * dbus_message_iter_get_fixed_array(). Otherwise, you have to iterate
2206 * over the container's contents one value at a time.
2208 * All basic-typed values are guaranteed to fit in a #DBusBasicValue,
2209 * so in versions of libdbus that have that type, you can write code like this:
2212 * DBusBasicValue value;
2214 * dbus_message_iter_get_basic (&read_iter, &value);
2215 * type = dbus_message_iter_get_arg_type (&read_iter);
2216 * dbus_message_iter_append_basic (&write_iter, type, &value);
2219 * (All D-Bus basic types are either numeric and 8 bytes or smaller, or
2220 * behave like a string; so in older versions of libdbus, DBusBasicValue
2221 * can be replaced with union { char *string; unsigned char bytes[8]; },
2224 * @param iter the iterator
2225 * @param value location to store the value
2228 dbus_message_iter_get_basic (DBusMessageIter *iter,
2231 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2233 _dbus_return_if_fail (_dbus_message_iter_check (real));
2234 _dbus_return_if_fail (value != NULL);
2236 if (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_UNIX_FD)
2238 #ifdef HAVE_UNIX_FD_PASSING
2241 _dbus_type_reader_read_basic(&real->u.reader, &idx);
2243 if (idx.u32 >= real->message->n_unix_fds) {
2244 /* Hmm, we cannot really signal an error here, so let's make
2245 sure to return an invalid fd. */
2246 *((int*) value) = -1;
2250 *((int*) value) = _dbus_dup(real->message->unix_fds[idx.u32], NULL);
2252 *((int*) value) = -1;
2257 _dbus_type_reader_read_basic (&real->u.reader,
2263 * Returns the number of bytes in the array as marshaled in the wire
2264 * protocol. The iterator must currently be inside an array-typed
2267 * This function is deprecated on the grounds that it is stupid. Why
2268 * would you want to know how many bytes are in the array as marshaled
2269 * in the wire protocol? For now, use the n_elements returned from
2270 * dbus_message_iter_get_fixed_array() instead, or iterate over the
2271 * array values and count them.
2273 * @todo introduce a variant of this get_n_elements that returns
2274 * the number of elements, though with a non-fixed array it will not
2275 * be very efficient, so maybe it's not good.
2277 * @param iter the iterator
2278 * @returns the number of bytes in the array
2281 dbus_message_iter_get_array_len (DBusMessageIter *iter)
2283 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2285 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2287 return _dbus_type_reader_get_array_length (&real->u.reader);
2291 * Reads a block of fixed-length values from the message iterator.
2292 * Fixed-length values are those basic types that are not string-like,
2293 * such as integers, bool, double. The returned block will be from the
2294 * current position in the array until the end of the array.
2296 * There is one exception here: although DBUS_TYPE_UNIX_FD is
2297 * considered a 'fixed' type arrays of this type may not be read with
2300 * The message iter should be "in" the array (that is, you recurse into the
2301 * array, and then you call dbus_message_iter_get_fixed_array() on the
2302 * "sub-iterator" created by dbus_message_iter_recurse()).
2304 * The value argument should be the address of a location to store the
2305 * returned array. So for int32 it should be a "const dbus_int32_t**"
2306 * The returned value is by reference and should not be freed.
2308 * This function should only be used if dbus_type_is_fixed() returns
2309 * #TRUE for the element type.
2311 * If an array's elements are not fixed in size, you have to recurse
2312 * into the array with dbus_message_iter_recurse() and read the
2313 * elements one by one.
2315 * Because the array is not copied, this function runs in constant
2316 * time and is fast; it's much preferred over walking the entire array
2317 * with an iterator. (However, you can always use
2318 * dbus_message_iter_recurse(), even for fixed-length types;
2319 * dbus_message_iter_get_fixed_array() is just an optimization.)
2321 * @param iter the iterator
2322 * @param value location to store the block
2323 * @param n_elements number of elements in the block
2326 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
2330 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2331 #ifndef DBUS_DISABLE_CHECKS
2332 int subtype = _dbus_type_reader_get_current_type(&real->u.reader);
2334 _dbus_return_if_fail (_dbus_message_iter_check (real));
2335 _dbus_return_if_fail (value != NULL);
2336 _dbus_return_if_fail ((subtype == DBUS_TYPE_INVALID) ||
2337 (dbus_type_is_fixed (subtype) && subtype != DBUS_TYPE_UNIX_FD));
2340 _dbus_type_reader_read_fixed_multi (&real->u.reader,
2345 * Initializes a #DBusMessageIter for appending arguments to the end
2348 * @todo If appending any of the arguments fails due to lack of
2349 * memory, the message is hosed and you have to start over building
2350 * the whole message.
2352 * @param message the message
2353 * @param iter pointer to an iterator to initialize
2356 dbus_message_iter_init_append (DBusMessage *message,
2357 DBusMessageIter *iter)
2359 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2361 _dbus_return_if_fail (message != NULL);
2362 _dbus_return_if_fail (iter != NULL);
2364 _dbus_message_iter_init_common (message, real,
2365 DBUS_MESSAGE_ITER_TYPE_WRITER);
2367 /* We create the signature string and point iterators at it "on demand"
2368 * when a value is actually appended. That means that init() never fails
2371 _dbus_type_writer_init_types_delayed (&real->u.writer,
2372 _dbus_header_get_byte_order (&message->header),
2374 _dbus_string_get_length (&message->body));
2378 * Creates a temporary signature string containing the current
2379 * signature, stores it in the iterator, and points the iterator to
2380 * the end of it. Used any time we write to the message.
2382 * @param real an iterator without a type_str
2383 * @returns #FALSE if no memory
2386 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
2389 const DBusString *current_sig;
2390 int current_sig_pos;
2392 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2394 if (real->u.writer.type_str != NULL)
2396 _dbus_assert (real->sig_refcount > 0);
2397 real->sig_refcount += 1;
2401 str = dbus_new (DBusString, 1);
2405 if (!_dbus_header_get_field_raw (&real->message->header,
2406 DBUS_HEADER_FIELD_SIGNATURE,
2407 ¤t_sig, ¤t_sig_pos))
2414 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
2415 current_sig_pos += 1; /* move on to sig data */
2417 if (!_dbus_string_init_preallocated (str, current_len + 4))
2423 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
2426 _dbus_string_free (str);
2433 if (!_dbus_string_init_preallocated (str, 4))
2440 real->sig_refcount = 1;
2442 _dbus_type_writer_add_types (&real->u.writer,
2443 str, _dbus_string_get_length (str));
2448 * Sets the new signature as the message signature, frees the
2449 * signature string, and marks the iterator as not having a type_str
2450 * anymore. Frees the signature even if it fails, so you can't
2451 * really recover from failure. Kinda busted.
2453 * @param real an iterator without a type_str
2454 * @returns #FALSE if no memory
2457 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2460 const char *v_STRING;
2463 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2464 _dbus_assert (real->u.writer.type_str != NULL);
2465 _dbus_assert (real->sig_refcount > 0);
2467 real->sig_refcount -= 1;
2469 if (real->sig_refcount > 0)
2471 _dbus_assert (real->sig_refcount == 0);
2475 str = real->u.writer.type_str;
2477 v_STRING = _dbus_string_get_const_data (str);
2478 if (!_dbus_header_set_field_basic (&real->message->header,
2479 DBUS_HEADER_FIELD_SIGNATURE,
2480 DBUS_TYPE_SIGNATURE,
2484 _dbus_type_writer_remove_types (&real->u.writer);
2485 _dbus_string_free (str);
2492 * Frees the signature string and marks the iterator as not having a
2493 * type_str anymore. Since the new signature is not set, the message
2494 * will generally be hosed after this is called.
2496 * @param real an iterator without a type_str
2499 _dbus_message_iter_abandon_signature (DBusMessageRealIter *real)
2503 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2504 _dbus_assert (real->u.writer.type_str != NULL);
2505 _dbus_assert (real->sig_refcount > 0);
2507 real->sig_refcount -= 1;
2509 if (real->sig_refcount > 0)
2511 _dbus_assert (real->sig_refcount == 0);
2513 str = real->u.writer.type_str;
2515 _dbus_type_writer_remove_types (&real->u.writer);
2516 _dbus_string_free (str);
2520 #ifndef DBUS_DISABLE_CHECKS
2522 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2524 if (!_dbus_message_iter_check (iter))
2527 if (iter->message->locked)
2529 _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)\n");
2535 #endif /* DBUS_DISABLE_CHECKS */
2537 #ifdef HAVE_UNIX_FD_PASSING
2539 expand_fd_array(DBusMessage *m,
2544 /* This makes space for adding n new fds to the array and returns a
2545 pointer to the place were the first fd should be put. */
2547 if (m->n_unix_fds + n > m->n_unix_fds_allocated)
2552 /* Make twice as much space as necessary */
2553 k = (m->n_unix_fds + n) * 2;
2555 /* Allocate at least four */
2559 p = dbus_realloc(m->unix_fds, k * sizeof(int));
2564 m->n_unix_fds_allocated = k;
2567 return m->unix_fds + m->n_unix_fds;
2572 * Appends a basic-typed value to the message. The basic types are the
2573 * non-container types such as integer and string.
2575 * The "value" argument should be the address of a basic-typed value.
2576 * So for string, const char**. For integer, dbus_int32_t*.
2578 * For Unix file descriptors this function will internally duplicate
2579 * the descriptor you passed in. Hence you may close the descriptor
2580 * immediately after this call.
2582 * @todo If this fails due to lack of memory, the message is hosed and
2583 * you have to start over building the whole message.
2585 * @param iter the append iterator
2586 * @param type the type of the value
2587 * @param value the address of the value
2588 * @returns #FALSE if not enough memory
2591 dbus_message_iter_append_basic (DBusMessageIter *iter,
2595 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2598 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2599 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2600 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2601 _dbus_return_val_if_fail (value != NULL, FALSE);
2603 #ifndef DBUS_DISABLE_CHECKS
2606 const char * const *string_p;
2607 const dbus_bool_t *bool_p;
2609 case DBUS_TYPE_STRING:
2611 _dbus_return_val_if_fail (_dbus_check_is_valid_utf8 (*string_p), FALSE);
2614 case DBUS_TYPE_OBJECT_PATH:
2616 _dbus_return_val_if_fail (_dbus_check_is_valid_path (*string_p), FALSE);
2619 case DBUS_TYPE_SIGNATURE:
2621 _dbus_return_val_if_fail (_dbus_check_is_valid_signature (*string_p), FALSE);
2624 case DBUS_TYPE_BOOLEAN:
2626 _dbus_return_val_if_fail (*bool_p == 0 || *bool_p == 1, FALSE);
2631 /* nothing to check, all possible values are allowed */
2636 if (!_dbus_message_iter_open_signature (real))
2639 if (type == DBUS_TYPE_UNIX_FD)
2641 #ifdef HAVE_UNIX_FD_PASSING
2645 /* First step, include the fd in the fd list of this message */
2646 if (!(fds = expand_fd_array(real->message, 1)))
2649 *fds = _dbus_dup(*(int*) value, NULL);
2653 u = real->message->n_unix_fds;
2655 /* Second step, write the index to the fd */
2656 if (!(ret = _dbus_type_writer_write_basic (&real->u.writer, DBUS_TYPE_UNIX_FD, &u))) {
2657 _dbus_close(*fds, NULL);
2661 real->message->n_unix_fds += 1;
2664 /* Final step, update the header accordingly */
2665 ret = _dbus_header_set_field_basic (&real->message->header,
2666 DBUS_HEADER_FIELD_UNIX_FDS,
2670 /* If any of these operations fail the message is
2671 hosed. However, no memory or fds should be leaked since what
2672 has been added to message has been added to the message, and
2673 can hence be accounted for when the message is being
2681 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
2684 if (!_dbus_message_iter_close_signature (real))
2691 * Appends a block of fixed-length values to an array. The
2692 * fixed-length types are all basic types that are not string-like. So
2693 * int32, double, bool, etc. (Unix file descriptors however are not
2694 * supported.) You must call dbus_message_iter_open_container() to
2695 * open an array of values before calling this function. You may call
2696 * this function multiple times (and intermixed with calls to
2697 * dbus_message_iter_append_basic()) for the same array.
2699 * The "value" argument should be the address of the array. So for
2700 * integer, "dbus_int32_t**" is expected for example.
2702 * @warning in C, given "int array[]", "&array == array" (the
2703 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2704 * So if you're using an array instead of a pointer you have to create
2705 * a pointer variable, assign the array to it, then take the address
2706 * of the pointer variable.
2708 * const dbus_int32_t array[] = { 1, 2, 3 };
2709 * const dbus_int32_t *v_ARRAY = array;
2710 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
2711 * fprintf (stderr, "No memory!\n");
2713 * For strings it works to write const char *array = "Hello" and then
2714 * use &array though.
2716 * @todo If this fails due to lack of memory, the message is hosed and
2717 * you have to start over building the whole message.
2719 * @param iter the append iterator
2720 * @param element_type the type of the array elements
2721 * @param value the address of the array
2722 * @param n_elements the number of elements to append
2723 * @returns #FALSE if not enough memory
2726 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
2731 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2734 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2735 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2736 _dbus_return_val_if_fail (dbus_type_is_fixed (element_type) && element_type != DBUS_TYPE_UNIX_FD, FALSE);
2737 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
2738 _dbus_return_val_if_fail (value != NULL, FALSE);
2739 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
2740 _dbus_return_val_if_fail (n_elements <=
2741 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
2744 #ifndef DBUS_DISABLE_CHECKS
2745 if (element_type == DBUS_TYPE_BOOLEAN)
2747 const dbus_bool_t * const *bools = value;
2750 for (i = 0; i < n_elements; i++)
2752 _dbus_return_val_if_fail ((*bools)[i] == 0 || (*bools)[i] == 1, FALSE);
2757 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
2763 * Appends a container-typed value to the message; you are required to
2764 * append the contents of the container using the returned
2765 * sub-iterator, and then call
2766 * dbus_message_iter_close_container(). Container types are for
2767 * example struct, variant, and array. For variants, the
2768 * contained_signature should be the type of the single value inside
2769 * the variant. For structs and dict entries, contained_signature
2770 * should be #NULL; it will be set to whatever types you write into
2771 * the struct. For arrays, contained_signature should be the type of
2772 * the array elements.
2774 * @todo If this fails due to lack of memory, the message is hosed and
2775 * you have to start over building the whole message.
2777 * @param iter the append iterator
2778 * @param type the type of the value
2779 * @param contained_signature the type of container contents
2780 * @param sub sub-iterator to initialize
2781 * @returns #FALSE if not enough memory
2784 dbus_message_iter_open_container (DBusMessageIter *iter,
2786 const char *contained_signature,
2787 DBusMessageIter *sub)
2789 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2790 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2791 DBusString contained_str;
2793 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2794 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2795 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
2796 _dbus_return_val_if_fail (sub != NULL, FALSE);
2797 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
2798 contained_signature == NULL) ||
2799 (type == DBUS_TYPE_DICT_ENTRY &&
2800 contained_signature == NULL) ||
2801 (type == DBUS_TYPE_VARIANT &&
2802 contained_signature != NULL) ||
2803 (type == DBUS_TYPE_ARRAY &&
2804 contained_signature != NULL), FALSE);
2806 /* this would fail if the contained_signature is a dict entry, since
2807 * dict entries are invalid signatures standalone (they must be in
2810 _dbus_return_val_if_fail ((type == DBUS_TYPE_ARRAY && contained_signature && *contained_signature == DBUS_DICT_ENTRY_BEGIN_CHAR) ||
2811 (contained_signature == NULL ||
2812 _dbus_check_is_valid_signature (contained_signature)),
2815 if (!_dbus_message_iter_open_signature (real))
2820 if (contained_signature != NULL)
2822 _dbus_string_init_const (&contained_str, contained_signature);
2824 return _dbus_type_writer_recurse (&real->u.writer,
2827 &real_sub->u.writer);
2831 return _dbus_type_writer_recurse (&real->u.writer,
2834 &real_sub->u.writer);
2840 * Closes a container-typed value appended to the message; may write
2841 * out more information to the message known only after the entire
2842 * container is written, and may free resources created by
2843 * dbus_message_iter_open_container().
2845 * @todo If this fails due to lack of memory, the message is hosed and
2846 * you have to start over building the whole message.
2848 * @param iter the append iterator
2849 * @param sub sub-iterator to close
2850 * @returns #FALSE if not enough memory
2853 dbus_message_iter_close_container (DBusMessageIter *iter,
2854 DBusMessageIter *sub)
2856 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2857 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2860 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2861 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2862 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
2863 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2865 ret = _dbus_type_writer_unrecurse (&real->u.writer,
2866 &real_sub->u.writer);
2868 if (!_dbus_message_iter_close_signature (real))
2875 * Abandons creation of a contained-typed value and frees resources created
2876 * by dbus_message_iter_open_container(). Once this returns, the message
2877 * is hosed and you have to start over building the whole message.
2879 * This should only be used to abandon creation of a message when you have
2882 * @param iter the append iterator
2883 * @param sub sub-iterator to close
2886 dbus_message_iter_abandon_container (DBusMessageIter *iter,
2887 DBusMessageIter *sub)
2889 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2890 #ifndef DBUS_DISABLE_CHECKS
2891 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2893 _dbus_return_if_fail (_dbus_message_iter_append_check (real));
2894 _dbus_return_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2895 _dbus_return_if_fail (_dbus_message_iter_append_check (real_sub));
2896 _dbus_return_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2899 _dbus_message_iter_abandon_signature (real);
2903 * Sets a flag indicating that the message does not want a reply; if
2904 * this flag is set, the other end of the connection may (but is not
2905 * required to) optimize by not sending method return or error
2906 * replies. If this flag is set, there is no way to know whether the
2907 * message successfully arrived at the remote end. Normally you know a
2908 * message was received when you receive the reply to it.
2910 * The flag is #FALSE by default, that is by default the other end is
2911 * required to reply.
2913 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
2915 * @param message the message
2916 * @param no_reply #TRUE if no reply is desired
2919 dbus_message_set_no_reply (DBusMessage *message,
2920 dbus_bool_t no_reply)
2922 _dbus_return_if_fail (message != NULL);
2923 _dbus_return_if_fail (!message->locked);
2925 _dbus_header_toggle_flag (&message->header,
2926 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
2931 * Returns #TRUE if the message does not expect
2934 * @param message the message
2935 * @returns #TRUE if the message sender isn't waiting for a reply
2938 dbus_message_get_no_reply (DBusMessage *message)
2940 _dbus_return_val_if_fail (message != NULL, FALSE);
2942 return _dbus_header_get_flag (&message->header,
2943 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
2947 * Sets a flag indicating that an owner for the destination name will
2948 * be automatically started before the message is delivered. When this
2949 * flag is set, the message is held until a name owner finishes
2950 * starting up, or fails to start up. In case of failure, the reply
2953 * The flag is set to #TRUE by default, i.e. auto starting is the default.
2955 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
2957 * @param message the message
2958 * @param auto_start #TRUE if auto-starting is desired
2961 dbus_message_set_auto_start (DBusMessage *message,
2962 dbus_bool_t auto_start)
2964 _dbus_return_if_fail (message != NULL);
2965 _dbus_return_if_fail (!message->locked);
2967 _dbus_header_toggle_flag (&message->header,
2968 DBUS_HEADER_FLAG_NO_AUTO_START,
2973 * Returns #TRUE if the message will cause an owner for
2974 * destination name to be auto-started.
2976 * @param message the message
2977 * @returns #TRUE if the message will use auto-start
2980 dbus_message_get_auto_start (DBusMessage *message)
2982 _dbus_return_val_if_fail (message != NULL, FALSE);
2984 return !_dbus_header_get_flag (&message->header,
2985 DBUS_HEADER_FLAG_NO_AUTO_START);
2990 * Sets the object path this message is being sent to (for
2991 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
2992 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
2994 * The path must contain only valid characters as defined
2995 * in the D-Bus specification.
2997 * @param message the message
2998 * @param object_path the path or #NULL to unset
2999 * @returns #FALSE if not enough memory
3002 dbus_message_set_path (DBusMessage *message,
3003 const char *object_path)
3005 _dbus_return_val_if_fail (message != NULL, FALSE);
3006 _dbus_return_val_if_fail (!message->locked, FALSE);
3007 _dbus_return_val_if_fail (object_path == NULL ||
3008 _dbus_check_is_valid_path (object_path),
3011 return set_or_delete_string_field (message,
3012 DBUS_HEADER_FIELD_PATH,
3013 DBUS_TYPE_OBJECT_PATH,
3018 * Gets the object path this message is being sent to (for
3019 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
3020 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3022 * See also dbus_message_get_path_decomposed().
3024 * The returned string becomes invalid if the message is
3025 * modified, since it points into the wire-marshaled message data.
3027 * @param message the message
3028 * @returns the path (should not be freed) or #NULL
3031 dbus_message_get_path (DBusMessage *message)
3035 _dbus_return_val_if_fail (message != NULL, NULL);
3037 v = NULL; /* in case field doesn't exist */
3038 _dbus_header_get_field_basic (&message->header,
3039 DBUS_HEADER_FIELD_PATH,
3040 DBUS_TYPE_OBJECT_PATH,
3046 * Checks if the message has a particular object path. The object
3047 * path is the destination object for a method call or the emitting
3048 * object for a signal.
3050 * @param message the message
3051 * @param path the path name
3052 * @returns #TRUE if there is a path field in the header
3055 dbus_message_has_path (DBusMessage *message,
3058 const char *msg_path;
3059 msg_path = dbus_message_get_path (message);
3061 if (msg_path == NULL)
3072 if (strcmp (msg_path, path) == 0)
3079 * Gets the object path this message is being sent to
3080 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3081 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
3082 * format (one array element per path component).
3083 * Free the returned array with dbus_free_string_array().
3085 * An empty but non-NULL path array means the path "/".
3086 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
3087 * and the path "/" becomes { NULL }.
3089 * See also dbus_message_get_path().
3091 * @todo this could be optimized by using the len from the message
3092 * instead of calling strlen() again
3094 * @param message the message
3095 * @param path place to store allocated array of path components; #NULL set here if no path field exists
3096 * @returns #FALSE if no memory to allocate the array
3099 dbus_message_get_path_decomposed (DBusMessage *message,
3104 _dbus_return_val_if_fail (message != NULL, FALSE);
3105 _dbus_return_val_if_fail (path != NULL, FALSE);
3109 v = dbus_message_get_path (message);
3112 if (!_dbus_decompose_path (v, strlen (v),
3120 * Sets the interface this message is being sent to
3121 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
3122 * the interface a signal is being emitted from
3123 * (for DBUS_MESSAGE_TYPE_SIGNAL).
3125 * The interface name must contain only valid characters as defined
3126 * in the D-Bus specification.
3128 * @param message the message
3129 * @param interface the interface or #NULL to unset
3130 * @returns #FALSE if not enough memory
3133 dbus_message_set_interface (DBusMessage *message,
3134 const char *interface)
3136 _dbus_return_val_if_fail (message != NULL, FALSE);
3137 _dbus_return_val_if_fail (!message->locked, FALSE);
3138 _dbus_return_val_if_fail (interface == NULL ||
3139 _dbus_check_is_valid_interface (interface),
3142 return set_or_delete_string_field (message,
3143 DBUS_HEADER_FIELD_INTERFACE,
3149 * Gets the interface this message is being sent to
3150 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3151 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
3152 * The interface name is fully-qualified (namespaced).
3153 * Returns #NULL if none.
3155 * The returned string becomes invalid if the message is
3156 * modified, since it points into the wire-marshaled message data.
3158 * @param message the message
3159 * @returns the message interface (should not be freed) or #NULL
3162 dbus_message_get_interface (DBusMessage *message)
3166 _dbus_return_val_if_fail (message != NULL, NULL);
3168 v = NULL; /* in case field doesn't exist */
3169 _dbus_header_get_field_basic (&message->header,
3170 DBUS_HEADER_FIELD_INTERFACE,
3177 * Checks if the message has an interface
3179 * @param message the message
3180 * @param interface the interface name
3181 * @returns #TRUE if the interface field in the header matches
3184 dbus_message_has_interface (DBusMessage *message,
3185 const char *interface)
3187 const char *msg_interface;
3188 msg_interface = dbus_message_get_interface (message);
3190 if (msg_interface == NULL)
3192 if (interface == NULL)
3198 if (interface == NULL)
3201 if (strcmp (msg_interface, interface) == 0)
3209 * Sets the interface member being invoked
3210 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3211 * (DBUS_MESSAGE_TYPE_SIGNAL).
3213 * The member name must contain only valid characters as defined
3214 * in the D-Bus specification.
3216 * @param message the message
3217 * @param member the member or #NULL to unset
3218 * @returns #FALSE if not enough memory
3221 dbus_message_set_member (DBusMessage *message,
3224 _dbus_return_val_if_fail (message != NULL, FALSE);
3225 _dbus_return_val_if_fail (!message->locked, FALSE);
3226 _dbus_return_val_if_fail (member == NULL ||
3227 _dbus_check_is_valid_member (member),
3230 return set_or_delete_string_field (message,
3231 DBUS_HEADER_FIELD_MEMBER,
3237 * Gets the interface member being invoked
3238 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3239 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3241 * The returned string becomes invalid if the message is
3242 * modified, since it points into the wire-marshaled message data.
3244 * @param message the message
3245 * @returns the member name (should not be freed) or #NULL
3248 dbus_message_get_member (DBusMessage *message)
3252 _dbus_return_val_if_fail (message != NULL, NULL);
3254 v = NULL; /* in case field doesn't exist */
3255 _dbus_header_get_field_basic (&message->header,
3256 DBUS_HEADER_FIELD_MEMBER,
3263 * Checks if the message has an interface member
3265 * @param message the message
3266 * @param member the member name
3267 * @returns #TRUE if there is a member field in the header
3270 dbus_message_has_member (DBusMessage *message,
3273 const char *msg_member;
3274 msg_member = dbus_message_get_member (message);
3276 if (msg_member == NULL)
3287 if (strcmp (msg_member, member) == 0)
3295 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
3296 * The name is fully-qualified (namespaced).
3298 * The error name must contain only valid characters as defined
3299 * in the D-Bus specification.
3301 * @param message the message
3302 * @param error_name the name or #NULL to unset
3303 * @returns #FALSE if not enough memory
3306 dbus_message_set_error_name (DBusMessage *message,
3307 const char *error_name)
3309 _dbus_return_val_if_fail (message != NULL, FALSE);
3310 _dbus_return_val_if_fail (!message->locked, FALSE);
3311 _dbus_return_val_if_fail (error_name == NULL ||
3312 _dbus_check_is_valid_error_name (error_name),
3315 return set_or_delete_string_field (message,
3316 DBUS_HEADER_FIELD_ERROR_NAME,
3322 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
3325 * The returned string becomes invalid if the message is
3326 * modified, since it points into the wire-marshaled message data.
3328 * @param message the message
3329 * @returns the error name (should not be freed) or #NULL
3332 dbus_message_get_error_name (DBusMessage *message)
3336 _dbus_return_val_if_fail (message != NULL, NULL);
3338 v = NULL; /* in case field doesn't exist */
3339 _dbus_header_get_field_basic (&message->header,
3340 DBUS_HEADER_FIELD_ERROR_NAME,
3347 * Sets the message's destination. The destination is the name of
3348 * another connection on the bus and may be either the unique name
3349 * assigned by the bus to each connection, or a well-known name
3350 * specified in advance.
3352 * The destination name must contain only valid characters as defined
3353 * in the D-Bus specification.
3355 * @param message the message
3356 * @param destination the destination name or #NULL to unset
3357 * @returns #FALSE if not enough memory
3360 dbus_message_set_destination (DBusMessage *message,
3361 const char *destination)
3363 _dbus_return_val_if_fail (message != NULL, FALSE);
3364 _dbus_return_val_if_fail (!message->locked, FALSE);
3365 _dbus_return_val_if_fail (destination == NULL ||
3366 _dbus_check_is_valid_bus_name (destination),
3369 return set_or_delete_string_field (message,
3370 DBUS_HEADER_FIELD_DESTINATION,
3376 * Gets the destination of a message or #NULL if there is none set.
3378 * The returned string becomes invalid if the message is
3379 * modified, since it points into the wire-marshaled message data.
3381 * @param message the message
3382 * @returns the message destination (should not be freed) or #NULL
3385 dbus_message_get_destination (DBusMessage *message)
3389 _dbus_return_val_if_fail (message != NULL, NULL);
3391 v = NULL; /* in case field doesn't exist */
3392 _dbus_header_get_field_basic (&message->header,
3393 DBUS_HEADER_FIELD_DESTINATION,
3400 * Sets the message sender.
3402 * The sender must be a valid bus name as defined in the D-Bus
3405 * Usually you don't want to call this. The message bus daemon will
3406 * call it to set the origin of each message. If you aren't implementing
3407 * a message bus daemon you shouldn't need to set the sender.
3409 * @param message the message
3410 * @param sender the sender or #NULL to unset
3411 * @returns #FALSE if not enough memory
3414 dbus_message_set_sender (DBusMessage *message,
3417 _dbus_return_val_if_fail (message != NULL, FALSE);
3418 _dbus_return_val_if_fail (!message->locked, FALSE);
3419 _dbus_return_val_if_fail (sender == NULL ||
3420 _dbus_check_is_valid_bus_name (sender),
3423 return set_or_delete_string_field (message,
3424 DBUS_HEADER_FIELD_SENDER,
3430 * Gets the unique name of the connection which originated this
3431 * message, or #NULL if unknown or inapplicable. The sender is filled
3432 * in by the message bus.
3434 * Note, the returned sender is always the unique bus name.
3435 * Connections may own multiple other bus names, but those
3436 * are not found in the sender field.
3438 * The returned string becomes invalid if the message is
3439 * modified, since it points into the wire-marshaled message data.
3441 * @param message the message
3442 * @returns the unique name of the sender or #NULL
3445 dbus_message_get_sender (DBusMessage *message)
3449 _dbus_return_val_if_fail (message != NULL, NULL);
3451 v = NULL; /* in case field doesn't exist */
3452 _dbus_header_get_field_basic (&message->header,
3453 DBUS_HEADER_FIELD_SENDER,
3460 * Gets the type signature of the message, i.e. the arguments in the
3461 * message payload. The signature includes only "in" arguments for
3462 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
3463 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
3464 * what you might expect (that is, it does not include the signature of the
3465 * entire C++-style method).
3467 * The signature is a string made up of type codes such as
3468 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
3469 * the value of #DBUS_TYPE_INVALID).
3471 * The returned string becomes invalid if the message is
3472 * modified, since it points into the wire-marshaled message data.
3474 * @param message the message
3475 * @returns the type signature
3478 dbus_message_get_signature (DBusMessage *message)
3480 const DBusString *type_str;
3483 _dbus_return_val_if_fail (message != NULL, NULL);
3485 get_const_signature (&message->header, &type_str, &type_pos);
3487 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
3491 _dbus_message_has_type_interface_member (DBusMessage *message,
3493 const char *interface,
3498 _dbus_assert (message != NULL);
3499 _dbus_assert (interface != NULL);
3500 _dbus_assert (member != NULL);
3502 if (dbus_message_get_type (message) != type)
3505 /* Optimize by checking the short member name first
3506 * instead of the longer interface name
3509 n = dbus_message_get_member (message);
3511 if (n && strcmp (n, member) == 0)
3513 n = dbus_message_get_interface (message);
3515 if (n == NULL || strcmp (n, interface) == 0)
3523 * Checks whether the message is a method call with the given
3524 * interface and member fields. If the message is not
3525 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
3526 * member field, returns #FALSE. If the interface field is missing,
3527 * then it will be assumed equal to the provided interface. The D-Bus
3528 * protocol allows method callers to leave out the interface name.
3530 * @param message the message
3531 * @param interface the name to check (must not be #NULL)
3532 * @param method the name to check (must not be #NULL)
3534 * @returns #TRUE if the message is the specified method call
3537 dbus_message_is_method_call (DBusMessage *message,
3538 const char *interface,
3541 _dbus_return_val_if_fail (message != NULL, FALSE);
3542 _dbus_return_val_if_fail (interface != NULL, FALSE);
3543 _dbus_return_val_if_fail (method != NULL, FALSE);
3544 /* don't check that interface/method are valid since it would be
3545 * expensive, and not catch many common errors
3548 return _dbus_message_has_type_interface_member (message,
3549 DBUS_MESSAGE_TYPE_METHOD_CALL,
3554 * Checks whether the message is a signal with the given interface and
3555 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
3556 * has a different interface or member field, returns #FALSE.
3558 * @param message the message
3559 * @param interface the name to check (must not be #NULL)
3560 * @param signal_name the name to check (must not be #NULL)
3562 * @returns #TRUE if the message is the specified signal
3565 dbus_message_is_signal (DBusMessage *message,
3566 const char *interface,
3567 const char *signal_name)
3569 _dbus_return_val_if_fail (message != NULL, FALSE);
3570 _dbus_return_val_if_fail (interface != NULL, FALSE);
3571 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
3572 /* don't check that interface/name are valid since it would be
3573 * expensive, and not catch many common errors
3576 return _dbus_message_has_type_interface_member (message,
3577 DBUS_MESSAGE_TYPE_SIGNAL,
3578 interface, signal_name);
3582 * Checks whether the message is an error reply with the given error
3583 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
3584 * different name, returns #FALSE.
3586 * @param message the message
3587 * @param error_name the name to check (must not be #NULL)
3589 * @returns #TRUE if the message is the specified error
3592 dbus_message_is_error (DBusMessage *message,
3593 const char *error_name)
3597 _dbus_return_val_if_fail (message != NULL, FALSE);
3598 _dbus_return_val_if_fail (error_name != NULL, FALSE);
3599 /* don't check that error_name is valid since it would be expensive,
3600 * and not catch many common errors
3603 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3606 n = dbus_message_get_error_name (message);
3608 if (n && strcmp (n, error_name) == 0)
3615 * Checks whether the message was sent to the given name. If the
3616 * message has no destination specified or has a different
3617 * destination, returns #FALSE.
3619 * @param message the message
3620 * @param name the name to check (must not be #NULL)
3622 * @returns #TRUE if the message has the given destination name
3625 dbus_message_has_destination (DBusMessage *message,
3630 _dbus_return_val_if_fail (message != NULL, FALSE);
3631 _dbus_return_val_if_fail (name != NULL, FALSE);
3632 /* don't check that name is valid since it would be expensive, and
3633 * not catch many common errors
3636 s = dbus_message_get_destination (message);
3638 if (s && strcmp (s, name) == 0)
3645 * Checks whether the message has the given unique name as its sender.
3646 * If the message has no sender specified or has a different sender,
3647 * returns #FALSE. Note that a peer application will always have the
3648 * unique name of the connection as the sender. So you can't use this
3649 * function to see whether a sender owned a well-known name.
3651 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
3654 * @param message the message
3655 * @param name the name to check (must not be #NULL)
3657 * @returns #TRUE if the message has the given sender
3660 dbus_message_has_sender (DBusMessage *message,
3665 _dbus_return_val_if_fail (message != NULL, FALSE);
3666 _dbus_return_val_if_fail (name != NULL, FALSE);
3667 /* don't check that name is valid since it would be expensive, and
3668 * not catch many common errors
3671 s = dbus_message_get_sender (message);
3673 if (s && strcmp (s, name) == 0)
3680 * Checks whether the message has the given signature; see
3681 * dbus_message_get_signature() for more details on what the signature
3684 * @param message the message
3685 * @param signature typecode array
3686 * @returns #TRUE if message has the given signature
3689 dbus_message_has_signature (DBusMessage *message,
3690 const char *signature)
3694 _dbus_return_val_if_fail (message != NULL, FALSE);
3695 _dbus_return_val_if_fail (signature != NULL, FALSE);
3696 /* don't check that signature is valid since it would be expensive,
3697 * and not catch many common errors
3700 s = dbus_message_get_signature (message);
3702 if (s && strcmp (s, signature) == 0)
3709 * Sets a #DBusError based on the contents of the given
3710 * message. The error is only set if the message
3711 * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
3712 * The name of the error is set to the name of the message,
3713 * and the error message is set to the first argument
3714 * if the argument exists and is a string.
3716 * The return value indicates whether the error was set (the error is
3717 * set if and only if the message is an error message). So you can
3718 * check for an error reply and convert it to DBusError in one go:
3720 * if (dbus_set_error_from_message (error, reply))
3726 * @param error the error to set
3727 * @param message the message to set it from
3728 * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
3731 dbus_set_error_from_message (DBusError *error,
3732 DBusMessage *message)
3736 _dbus_return_val_if_fail (message != NULL, FALSE);
3737 _dbus_return_val_if_error_is_set (error, FALSE);
3739 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3743 dbus_message_get_args (message, NULL,
3744 DBUS_TYPE_STRING, &str,
3747 dbus_set_error (error, dbus_message_get_error_name (message),
3748 str ? "%s" : NULL, str);
3754 * Checks whether a message contains unix fds
3756 * @param message the message
3757 * @returns #TRUE if the message contains unix fds
3760 dbus_message_contains_unix_fds(DBusMessage *message)
3762 #ifdef HAVE_UNIX_FD_PASSING
3763 _dbus_assert(message);
3765 return message->n_unix_fds > 0;
3774 * @addtogroup DBusMessageInternals
3780 * The initial buffer size of the message loader.
3782 * @todo this should be based on min header size plus some average
3783 * body size, or something. Or rather, the min header size only, if we
3784 * want to try to read only the header, store that in a DBusMessage,
3785 * then read only the body and store that, etc., depends on
3786 * how we optimize _dbus_message_loader_get_buffer() and what
3787 * the exact message format is.
3789 #define INITIAL_LOADER_DATA_LEN 32
3792 * Creates a new message loader. Returns #NULL if memory can't
3795 * @returns new loader, or #NULL.
3798 _dbus_message_loader_new (void)
3800 DBusMessageLoader *loader;
3802 loader = dbus_new0 (DBusMessageLoader, 1);
3806 loader->refcount = 1;
3808 loader->corrupted = FALSE;
3809 loader->corruption_reason = DBUS_VALID;
3811 /* this can be configured by the app, but defaults to the protocol max */
3812 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
3814 /* We set a very relatively conservative default here since due to how
3815 SCM_RIGHTS works we need to preallocate an fd array of the maximum
3816 number of unix fds we want to receive in advance. A
3817 try-and-reallocate loop is not possible. */
3818 loader->max_message_unix_fds = DBUS_DEFAULT_MESSAGE_UNIX_FDS;
3820 if (!_dbus_string_init (&loader->data))
3826 /* preallocate the buffer for speed, ignore failure */
3827 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
3828 _dbus_string_set_length (&loader->data, 0);
3830 #ifdef HAVE_UNIX_FD_PASSING
3831 loader->unix_fds = NULL;
3832 loader->n_unix_fds = loader->n_unix_fds_allocated = 0;
3833 loader->unix_fds_outstanding = FALSE;
3840 * Increments the reference count of the loader.
3842 * @param loader the loader.
3843 * @returns the loader
3846 _dbus_message_loader_ref (DBusMessageLoader *loader)
3848 loader->refcount += 1;
3854 * Decrements the reference count of the loader and finalizes the
3855 * loader when the count reaches zero.
3857 * @param loader the loader.
3860 _dbus_message_loader_unref (DBusMessageLoader *loader)
3862 loader->refcount -= 1;
3863 if (loader->refcount == 0)
3865 #ifdef HAVE_UNIX_FD_PASSING
3866 close_unix_fds(loader->unix_fds, &loader->n_unix_fds);
3867 dbus_free(loader->unix_fds);
3869 _dbus_list_foreach (&loader->messages,
3870 (DBusForeachFunction) dbus_message_unref,
3872 _dbus_list_clear (&loader->messages);
3873 _dbus_string_free (&loader->data);
3879 * Gets the buffer to use for reading data from the network. Network
3880 * data is read directly into an allocated buffer, which is then used
3881 * in the DBusMessage, to avoid as many extra memcpy's as possible.
3882 * The buffer must always be returned immediately using
3883 * _dbus_message_loader_return_buffer(), even if no bytes are
3884 * successfully read.
3886 * @todo this function can be a lot more clever. For example
3887 * it can probably always return a buffer size to read exactly
3888 * the body of the next message, thus avoiding any memory wastage
3891 * @todo we need to enforce a max length on strings in header fields.
3893 * @param loader the message loader.
3894 * @param buffer the buffer
3897 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
3898 DBusString **buffer)
3900 _dbus_assert (!loader->buffer_outstanding);
3902 *buffer = &loader->data;
3904 loader->buffer_outstanding = TRUE;
3908 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
3909 * indicating to the loader how many bytes of the buffer were filled
3910 * in. This function must always be called, even if no bytes were
3911 * successfully read.
3913 * @param loader the loader.
3914 * @param buffer the buffer.
3915 * @param bytes_read number of bytes that were read into the buffer.
3918 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
3922 _dbus_assert (loader->buffer_outstanding);
3923 _dbus_assert (buffer == &loader->data);
3925 loader->buffer_outstanding = FALSE;
3929 * Gets the buffer to use for reading unix fds from the network.
3931 * This works similar to _dbus_message_loader_get_buffer()
3933 * @param loader the message loader.
3934 * @param fds the array to read fds into
3935 * @param max_n_fds how many fds to read at most
3936 * @return TRUE on success, FALSE on OOM
3939 _dbus_message_loader_get_unix_fds(DBusMessageLoader *loader,
3941 unsigned *max_n_fds)
3943 #ifdef HAVE_UNIX_FD_PASSING
3944 _dbus_assert (!loader->unix_fds_outstanding);
3946 /* Allocate space where we can put the fds we read. We allocate
3947 space for max_message_unix_fds since this is an
3948 upper limit how many fds can be received within a single
3949 message. Since SCM_RIGHTS doesn't allow a reallocate+retry logic
3950 we are allocating the maximum possible array size right from the
3951 beginning. This sucks a bit, however unless SCM_RIGHTS is fixed
3952 there is no better way. */
3954 if (loader->n_unix_fds_allocated < loader->max_message_unix_fds)
3956 int *a = dbus_realloc(loader->unix_fds,
3957 loader->max_message_unix_fds * sizeof(loader->unix_fds[0]));
3962 loader->unix_fds = a;
3963 loader->n_unix_fds_allocated = loader->max_message_unix_fds;
3966 *fds = loader->unix_fds + loader->n_unix_fds;
3967 *max_n_fds = loader->n_unix_fds_allocated - loader->n_unix_fds;
3969 loader->unix_fds_outstanding = TRUE;
3972 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
3978 * Returns a buffer obtained from _dbus_message_loader_get_unix_fds().
3980 * This works similar to _dbus_message_loader_return_buffer()
3982 * @param loader the message loader.
3983 * @param fds the array fds were read into
3984 * @param max_n_fds how many fds were read
3988 _dbus_message_loader_return_unix_fds(DBusMessageLoader *loader,
3992 #ifdef HAVE_UNIX_FD_PASSING
3993 _dbus_assert(loader->unix_fds_outstanding);
3994 _dbus_assert(loader->unix_fds + loader->n_unix_fds == fds);
3995 _dbus_assert(loader->n_unix_fds + n_fds <= loader->n_unix_fds_allocated);
3997 loader->n_unix_fds += n_fds;
3998 loader->unix_fds_outstanding = FALSE;
4000 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
4005 * FIXME when we move the header out of the buffer, that memmoves all
4006 * buffered messages. Kind of crappy.
4008 * Also we copy the header and body, which is kind of crappy. To
4009 * avoid this, we have to allow header and body to be in a single
4010 * memory block, which is good for messages we read and bad for
4011 * messages we are creating. But we could move_len() the buffer into
4012 * this single memory block, and move_len() will just swap the buffers
4013 * if you're moving the entire buffer replacing the dest string.
4015 * We could also have the message loader tell the transport how many
4016 * bytes to read; so it would first ask for some arbitrary number like
4017 * 256, then if the message was incomplete it would use the
4018 * header/body len to ask for exactly the size of the message (or
4019 * blocks the size of a typical kernel buffer for the socket). That
4020 * way we don't get trailing bytes in the buffer that have to be
4021 * memmoved. Though I suppose we also don't have a chance of reading a
4022 * bunch of small messages at once, so the optimization may be stupid.
4024 * Another approach would be to keep a "start" index into
4025 * loader->data and only delete it occasionally, instead of after
4026 * each message is loaded.
4028 * load_message() returns FALSE if not enough memory OR the loader was corrupted
4031 load_message (DBusMessageLoader *loader,
4032 DBusMessage *message,
4034 int fields_array_len,
4039 DBusValidity validity;
4040 const DBusString *type_str;
4042 DBusValidationMode mode;
4043 dbus_uint32_t n_unix_fds = 0;
4045 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
4050 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
4053 /* 1. VALIDATE AND COPY OVER HEADER */
4054 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
4055 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
4057 if (!_dbus_header_load (&message->header,
4065 _dbus_string_get_length (&loader->data)))
4067 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
4069 /* assert here so we can catch any code that still uses DBUS_VALID to indicate
4070 oom errors. They should use DBUS_VALIDITY_UNKNOWN_OOM_ERROR instead */
4071 _dbus_assert (validity != DBUS_VALID);
4073 if (validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
4077 loader->corrupted = TRUE;
4078 loader->corruption_reason = validity;
4083 _dbus_assert (validity == DBUS_VALID);
4085 /* 2. VALIDATE BODY */
4086 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
4088 get_const_signature (&message->header, &type_str, &type_pos);
4090 /* Because the bytes_remaining arg is NULL, this validates that the
4091 * body is the right length
4093 validity = _dbus_validate_body_with_reason (type_str,
4100 if (validity != DBUS_VALID)
4102 _dbus_verbose ("Failed to validate message body code %d\n", validity);
4104 loader->corrupted = TRUE;
4105 loader->corruption_reason = validity;
4111 /* 3. COPY OVER UNIX FDS */
4112 _dbus_header_get_field_basic(&message->header,
4113 DBUS_HEADER_FIELD_UNIX_FDS,
4117 #ifdef HAVE_UNIX_FD_PASSING
4119 if (n_unix_fds > loader->n_unix_fds)
4121 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
4122 n_unix_fds, loader->n_unix_fds);
4124 loader->corrupted = TRUE;
4125 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4129 /* If this was a recycled message there might still be
4130 some memory allocated for the fds */
4131 dbus_free(message->unix_fds);
4135 message->unix_fds = _dbus_memdup(loader->unix_fds, n_unix_fds * sizeof(message->unix_fds[0]));
4136 if (message->unix_fds == NULL)
4138 _dbus_verbose ("Failed to allocate file descriptor array\n");
4143 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
4144 loader->n_unix_fds -= n_unix_fds;
4145 memmove(loader->unix_fds + n_unix_fds, loader->unix_fds, loader->n_unix_fds);
4148 message->unix_fds = NULL;
4154 _dbus_verbose ("Hmm, message claims to come with file descriptors "
4155 "but that's not supported on our platform, disconnecting.\n");
4157 loader->corrupted = TRUE;
4158 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4164 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
4166 if (!_dbus_list_append (&loader->messages, message))
4168 _dbus_verbose ("Failed to append new message to loader queue\n");
4173 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
4174 _dbus_assert (_dbus_string_get_length (&loader->data) >=
4175 (header_len + body_len));
4177 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
4179 _dbus_verbose ("Failed to move body into new message\n");
4184 _dbus_string_delete (&loader->data, 0, header_len + body_len);
4186 /* don't waste more than 2k of memory */
4187 _dbus_string_compact (&loader->data, 2048);
4189 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
4190 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
4192 _dbus_verbose ("Loaded message %p\n", message);
4194 _dbus_assert (!oom);
4195 _dbus_assert (!loader->corrupted);
4196 _dbus_assert (loader->messages != NULL);
4197 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4205 /* does nothing if the message isn't in the list */
4206 _dbus_list_remove_last (&loader->messages, message);
4209 _dbus_assert (!loader->corrupted);
4211 _dbus_assert (loader->corrupted);
4213 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
4219 * Converts buffered data into messages, if we have enough data. If
4220 * we don't have enough data, does nothing.
4222 * @todo we need to check that the proper named header fields exist
4223 * for each message type.
4225 * @todo If a message has unknown type, we should probably eat it
4226 * right here rather than passing it out to applications. However
4227 * it's not an error to see messages of unknown type.
4229 * @param loader the loader.
4230 * @returns #TRUE if we had enough memory to finish.
4233 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
4235 while (!loader->corrupted &&
4236 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
4238 DBusValidity validity;
4239 int byte_order, fields_array_len, header_len, body_len;
4241 if (_dbus_header_have_message_untrusted (loader->max_message_size,
4248 _dbus_string_get_length (&loader->data)))
4250 DBusMessage *message;
4252 _dbus_assert (validity == DBUS_VALID);
4254 message = dbus_message_new_empty_header ();
4255 if (message == NULL)
4258 if (!load_message (loader, message,
4259 byte_order, fields_array_len,
4260 header_len, body_len))
4262 dbus_message_unref (message);
4263 /* load_message() returns false if corrupted or OOM; if
4264 * corrupted then return TRUE for not OOM
4266 return loader->corrupted;
4269 _dbus_assert (loader->messages != NULL);
4270 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4274 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
4276 if (validity != DBUS_VALID)
4278 loader->corrupted = TRUE;
4279 loader->corruption_reason = validity;
4289 * Peeks at first loaded message, returns #NULL if no messages have
4292 * @param loader the loader.
4293 * @returns the next message, or #NULL if none.
4296 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
4298 if (loader->messages)
4299 return loader->messages->data;
4305 * Pops a loaded message (passing ownership of the message
4306 * to the caller). Returns #NULL if no messages have been
4309 * @param loader the loader.
4310 * @returns the next message, or #NULL if none.
4313 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
4315 return _dbus_list_pop_first (&loader->messages);
4319 * Pops a loaded message inside a list link (passing ownership of the
4320 * message and link to the caller). Returns #NULL if no messages have
4323 * @param loader the loader.
4324 * @returns the next message link, or #NULL if none.
4327 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
4329 return _dbus_list_pop_first_link (&loader->messages);
4333 * Returns a popped message link, used to undo a pop.
4335 * @param loader the loader
4336 * @param link the link with a message in it
4339 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
4342 _dbus_list_prepend_link (&loader->messages, link);
4346 * Checks whether the loader is confused due to bad data.
4347 * If messages are received that are invalid, the
4348 * loader gets confused and gives up permanently.
4349 * This state is called "corrupted."
4351 * @param loader the loader
4352 * @returns #TRUE if the loader is hosed.
4355 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
4357 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4358 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4359 return loader->corrupted;
4363 * Checks what kind of bad data confused the loader.
4365 * @param loader the loader
4366 * @returns why the loader is hosed, or DBUS_VALID if it isn't.
4369 _dbus_message_loader_get_corruption_reason (DBusMessageLoader *loader)
4371 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4372 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4374 return loader->corruption_reason;
4378 * Sets the maximum size message we allow.
4380 * @param loader the loader
4381 * @param size the max message size in bytes
4384 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
4387 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
4389 _dbus_verbose ("clamping requested max message size %ld to %d\n",
4390 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
4391 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4393 loader->max_message_size = size;
4397 * Gets the maximum allowed message size in bytes.
4399 * @param loader the loader
4400 * @returns max size in bytes
4403 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
4405 return loader->max_message_size;
4409 * Sets the maximum unix fds per message we allow.
4411 * @param loader the loader
4412 * @param size the max number of unix fds in a message
4415 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader,
4418 if (n > DBUS_MAXIMUM_MESSAGE_UNIX_FDS)
4420 _dbus_verbose ("clamping requested max message unix_fds %ld to %d\n",
4421 n, DBUS_MAXIMUM_MESSAGE_UNIX_FDS);
4422 n = DBUS_MAXIMUM_MESSAGE_UNIX_FDS;
4424 loader->max_message_unix_fds = n;
4428 * Gets the maximum allowed number of unix fds per message
4430 * @param loader the loader
4431 * @returns max unix fds
4434 _dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
4436 return loader->max_message_unix_fds;
4439 static DBusDataSlotAllocator slot_allocator =
4440 _DBUS_DATA_SLOT_ALLOCATOR_INIT (_DBUS_LOCK_NAME (message_slots));
4443 * Allocates an integer ID to be used for storing application-specific
4444 * data on any DBusMessage. The allocated ID may then be used
4445 * with dbus_message_set_data() and dbus_message_get_data().
4446 * The passed-in slot must be initialized to -1, and is filled in
4447 * with the slot ID. If the passed-in slot is not -1, it's assumed
4448 * to be already allocated, and its refcount is incremented.
4450 * The allocated slot is global, i.e. all DBusMessage objects will
4451 * have a slot with the given integer ID reserved.
4453 * @param slot_p address of a global variable storing the slot
4454 * @returns #FALSE on failure (no memory)
4457 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
4459 return _dbus_data_slot_allocator_alloc (&slot_allocator,
4464 * Deallocates a global ID for message data slots.
4465 * dbus_message_get_data() and dbus_message_set_data() may no
4466 * longer be used with this slot. Existing data stored on existing
4467 * DBusMessage objects will be freed when the message is
4468 * finalized, but may not be retrieved (and may only be replaced if
4469 * someone else reallocates the slot). When the refcount on the
4470 * passed-in slot reaches 0, it is set to -1.
4472 * @param slot_p address storing the slot to deallocate
4475 dbus_message_free_data_slot (dbus_int32_t *slot_p)
4477 _dbus_return_if_fail (*slot_p >= 0);
4479 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
4483 * Stores a pointer on a DBusMessage, along
4484 * with an optional function to be used for freeing
4485 * the data when the data is set again, or when
4486 * the message is finalized. The slot number
4487 * must have been allocated with dbus_message_allocate_data_slot().
4489 * @param message the message
4490 * @param slot the slot number
4491 * @param data the data to store
4492 * @param free_data_func finalizer function for the data
4493 * @returns #TRUE if there was enough memory to store the data
4496 dbus_message_set_data (DBusMessage *message,
4499 DBusFreeFunction free_data_func)
4501 DBusFreeFunction old_free_func;
4505 _dbus_return_val_if_fail (message != NULL, FALSE);
4506 _dbus_return_val_if_fail (slot >= 0, FALSE);
4508 retval = _dbus_data_slot_list_set (&slot_allocator,
4509 &message->slot_list,
4510 slot, data, free_data_func,
4511 &old_free_func, &old_data);
4515 /* Do the actual free outside the message lock */
4517 (* old_free_func) (old_data);
4524 * Retrieves data previously set with dbus_message_set_data().
4525 * The slot must still be allocated (must not have been freed).
4527 * @param message the message
4528 * @param slot the slot to get data from
4529 * @returns the data, or #NULL if not found
4532 dbus_message_get_data (DBusMessage *message,
4537 _dbus_return_val_if_fail (message != NULL, NULL);
4539 res = _dbus_data_slot_list_get (&slot_allocator,
4540 &message->slot_list,
4547 * Utility function to convert a machine-readable (not translated)
4548 * string into a D-Bus message type.
4551 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
4552 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
4553 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
4554 * "error" -> DBUS_MESSAGE_TYPE_ERROR
4555 * anything else -> DBUS_MESSAGE_TYPE_INVALID
4560 dbus_message_type_from_string (const char *type_str)
4562 if (strcmp (type_str, "method_call") == 0)
4563 return DBUS_MESSAGE_TYPE_METHOD_CALL;
4564 if (strcmp (type_str, "method_return") == 0)
4565 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
4566 else if (strcmp (type_str, "signal") == 0)
4567 return DBUS_MESSAGE_TYPE_SIGNAL;
4568 else if (strcmp (type_str, "error") == 0)
4569 return DBUS_MESSAGE_TYPE_ERROR;
4571 return DBUS_MESSAGE_TYPE_INVALID;
4575 * Utility function to convert a D-Bus message type into a
4576 * machine-readable string (not translated).
4579 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
4580 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
4581 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
4582 * DBUS_MESSAGE_TYPE_ERROR -> "error"
4583 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
4588 dbus_message_type_to_string (int type)
4592 case DBUS_MESSAGE_TYPE_METHOD_CALL:
4593 return "method_call";
4594 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
4595 return "method_return";
4596 case DBUS_MESSAGE_TYPE_SIGNAL:
4598 case DBUS_MESSAGE_TYPE_ERROR:
4606 * Turn a DBusMessage into the marshalled form as described in the D-Bus
4609 * Generally, this function is only useful for encapsulating D-Bus messages in
4610 * a different protocol.
4612 * @param msg the DBusMessage
4613 * @param marshalled_data_p the location to save the marshalled form to
4614 * @param len_p the location to save the length of the marshalled form to
4615 * @returns #FALSE if there was not enough memory
4618 dbus_message_marshal (DBusMessage *msg,
4619 char **marshalled_data_p,
4623 dbus_bool_t was_locked;
4625 _dbus_return_val_if_fail (msg != NULL, FALSE);
4626 _dbus_return_val_if_fail (marshalled_data_p != NULL, FALSE);
4627 _dbus_return_val_if_fail (len_p != NULL, FALSE);
4629 if (!_dbus_string_init (&tmp))
4632 /* Ensure the message is locked, to ensure the length header is filled in. */
4633 was_locked = msg->locked;
4636 dbus_message_lock (msg);
4638 if (!_dbus_string_copy (&(msg->header.data), 0, &tmp, 0))
4641 *len_p = _dbus_string_get_length (&tmp);
4643 if (!_dbus_string_copy (&(msg->body), 0, &tmp, *len_p))
4646 *len_p = _dbus_string_get_length (&tmp);
4648 if (!_dbus_string_steal_data (&tmp, marshalled_data_p))
4651 _dbus_string_free (&tmp);
4654 msg->locked = FALSE;
4659 _dbus_string_free (&tmp);
4662 msg->locked = FALSE;
4668 * Demarshal a D-Bus message from the format described in the D-Bus
4671 * Generally, this function is only useful for encapsulating D-Bus messages in
4672 * a different protocol.
4674 * @param str the marshalled DBusMessage
4675 * @param len the length of str
4676 * @param error the location to save errors to
4677 * @returns #NULL if there was an error
4680 dbus_message_demarshal (const char *str,
4684 DBusMessageLoader *loader;
4688 _dbus_return_val_if_fail (str != NULL, NULL);
4690 loader = _dbus_message_loader_new ();
4695 _dbus_message_loader_get_buffer (loader, &buffer);
4696 _dbus_string_append_len (buffer, str, len);
4697 _dbus_message_loader_return_buffer (loader, buffer, len);
4699 if (!_dbus_message_loader_queue_messages (loader))
4702 if (_dbus_message_loader_get_is_corrupted (loader))
4705 msg = _dbus_message_loader_pop_message (loader);
4710 _dbus_message_loader_unref (loader);
4714 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS, "Message is corrupted (%s)",
4715 _dbus_validity_to_error_message (loader->corruption_reason));
4716 _dbus_message_loader_unref (loader);
4720 _DBUS_SET_OOM (error);
4721 _dbus_message_loader_unref (loader);
4726 * Returns the number of bytes required to be in the buffer to demarshal a
4729 * Generally, this function is only useful for encapsulating D-Bus messages in
4730 * a different protocol.
4732 * @param str data to be marshalled
4733 * @param len the length of str
4734 * @param error the location to save errors to
4735 * @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
4739 dbus_message_demarshal_bytes_needed(const char *buf,
4743 int byte_order, fields_array_len, header_len, body_len;
4744 DBusValidity validity = DBUS_VALID;
4747 if (!buf || len < DBUS_MINIMUM_HEADER_SIZE)
4750 if (len > DBUS_MAXIMUM_MESSAGE_LENGTH)
4751 len = DBUS_MAXIMUM_MESSAGE_LENGTH;
4752 _dbus_string_init_const_len (&str, buf, len);
4754 validity = DBUS_VALID;
4756 = _dbus_header_have_message_untrusted(DBUS_MAXIMUM_MESSAGE_LENGTH,
4757 &validity, &byte_order,
4763 _dbus_string_free (&str);
4765 if (validity == DBUS_VALID)
4767 _dbus_assert (have_message || (header_len + body_len) > len);
4768 (void) have_message; /* unused unless asserting */
4769 return header_len + body_len;
4773 return -1; /* broken! */
4779 /* tests in dbus-message-util.c */