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_BUILD_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 _DBUS_DEFINE_GLOBAL_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 _DBUS_LOCK (message_cache);
522 while (i < MAX_MESSAGE_CACHE_SIZE)
524 if (message_cache[i])
525 dbus_message_finalize (message_cache[i]);
530 message_cache_count = 0;
531 message_cache_shutdown_registered = FALSE;
533 _DBUS_UNLOCK (message_cache);
537 * Tries to get a message from the message cache. The retrieved
538 * message will have junk in it, so it still needs to be cleared out
539 * in dbus_message_new_empty_header()
541 * @returns the message, or #NULL if none cached
544 dbus_message_get_cached (void)
546 DBusMessage *message;
551 _DBUS_LOCK (message_cache);
553 _dbus_assert (message_cache_count >= 0);
555 if (message_cache_count == 0)
557 _DBUS_UNLOCK (message_cache);
561 /* This is not necessarily true unless count > 0, and
562 * message_cache is uninitialized until the shutdown is
565 _dbus_assert (message_cache_shutdown_registered);
568 while (i < MAX_MESSAGE_CACHE_SIZE)
570 if (message_cache[i])
572 message = message_cache[i];
573 message_cache[i] = NULL;
574 message_cache_count -= 1;
579 _dbus_assert (message_cache_count >= 0);
580 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
581 _dbus_assert (message != NULL);
583 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
585 _dbus_assert (message->counters == NULL);
587 _DBUS_UNLOCK (message_cache);
592 #ifdef HAVE_UNIX_FD_PASSING
594 close_unix_fds(int *fds, unsigned *n_fds)
604 for (i = 0; i < *n_fds; i++)
606 if (!_dbus_close(fds[i], &e))
608 _dbus_warn("Failed to close file descriptor: %s\n", e.message);
615 /* We don't free the array here, in case we can recycle it later */
620 free_counter (void *element,
623 DBusCounter *counter = element;
624 DBusMessage *message = data;
626 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
627 #ifdef HAVE_UNIX_FD_PASSING
628 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
631 _dbus_counter_notify (counter);
632 _dbus_counter_unref (counter);
636 * Tries to cache a message, otherwise finalize it.
638 * @param message the message
641 dbus_message_cache_or_finalize (DBusMessage *message)
643 dbus_bool_t was_cached;
646 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
648 /* This calls application code and has to be done first thing
649 * without holding the lock
651 _dbus_data_slot_list_clear (&message->slot_list);
653 _dbus_list_foreach (&message->counters,
654 free_counter, message);
655 _dbus_list_clear (&message->counters);
657 #ifdef HAVE_UNIX_FD_PASSING
658 close_unix_fds(message->unix_fds, &message->n_unix_fds);
663 _DBUS_LOCK (message_cache);
665 if (!message_cache_shutdown_registered)
667 _dbus_assert (message_cache_count == 0);
669 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
673 while (i < MAX_MESSAGE_CACHE_SIZE)
675 message_cache[i] = NULL;
679 message_cache_shutdown_registered = TRUE;
682 _dbus_assert (message_cache_count >= 0);
684 if (!_dbus_enable_message_cache ())
687 if ((_dbus_string_get_length (&message->header.data) +
688 _dbus_string_get_length (&message->body)) >
689 MAX_MESSAGE_SIZE_TO_CACHE)
692 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
695 /* Find empty slot */
697 while (message_cache[i] != NULL)
700 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
702 _dbus_assert (message_cache[i] == NULL);
703 message_cache[i] = message;
704 message_cache_count += 1;
706 #ifndef DBUS_DISABLE_CHECKS
707 message->in_cache = TRUE;
711 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
713 _DBUS_UNLOCK (message_cache);
716 dbus_message_finalize (message);
719 #ifndef DBUS_DISABLE_CHECKS
721 _dbus_message_iter_check (DBusMessageRealIter *iter)
727 _dbus_warn_check_failed ("dbus message iterator is NULL\n");
731 byte_order = _dbus_header_get_byte_order (&iter->message->header);
733 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
735 if (iter->u.reader.byte_order != byte_order)
737 _dbus_warn_check_failed ("dbus message changed byte order since iterator was created\n");
740 /* because we swap the message into compiler order when you init an iter */
741 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
743 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
745 if (iter->u.writer.byte_order != byte_order)
747 _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created\n");
750 /* because we swap the message into compiler order when you init an iter */
751 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
755 _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted\n");
759 if (iter->changed_stamp != iter->message->changed_stamp)
761 _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
767 #endif /* DBUS_DISABLE_CHECKS */
770 * Implementation of the varargs arg-getting functions.
771 * dbus_message_get_args() is the place to go for complete
774 * @todo This may leak memory and file descriptors if parsing fails. See #21259
776 * @see dbus_message_get_args
777 * @param iter the message iter
778 * @param error error to be filled in
779 * @param first_arg_type type of the first argument
780 * @param var_args return location for first argument, followed by list of type/location pairs
781 * @returns #FALSE if error was set
784 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
789 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
790 int spec_type, msg_type, i;
793 _dbus_assert (_dbus_message_iter_check (real));
797 spec_type = first_arg_type;
800 while (spec_type != DBUS_TYPE_INVALID)
802 msg_type = dbus_message_iter_get_arg_type (iter);
804 if (msg_type != spec_type)
806 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
807 "Argument %d is specified to be of type \"%s\", but "
808 "is actually of type \"%s\"\n", i,
809 _dbus_type_to_string (spec_type),
810 _dbus_type_to_string (msg_type));
815 if (spec_type == DBUS_TYPE_UNIX_FD)
817 #ifdef HAVE_UNIX_FD_PASSING
821 pfd = va_arg (var_args, int*);
824 _dbus_type_reader_read_basic(&real->u.reader, &idx);
826 if (idx.u32 >= real->message->n_unix_fds)
828 dbus_set_error (error, DBUS_ERROR_INCONSISTENT_MESSAGE,
829 "Message refers to file descriptor at index %i,"
830 "but has only %i descriptors attached.\n",
832 real->message->n_unix_fds);
836 if ((nfd = _dbus_dup(real->message->unix_fds[idx.u32], error)) < 0)
841 dbus_set_error (error, DBUS_ERROR_NOT_SUPPORTED,
842 "Platform does not support file desciptor passing.\n");
846 else if (dbus_type_is_basic (spec_type))
850 ptr = va_arg (var_args, DBusBasicValue*);
852 _dbus_assert (ptr != NULL);
854 _dbus_type_reader_read_basic (&real->u.reader,
857 else if (spec_type == DBUS_TYPE_ARRAY)
860 int spec_element_type;
861 const DBusBasicValue **ptr;
863 DBusTypeReader array;
865 spec_element_type = va_arg (var_args, int);
866 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
868 if (spec_element_type != element_type)
870 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
871 "Argument %d is specified to be an array of \"%s\", but "
872 "is actually an array of \"%s\"\n",
874 _dbus_type_to_string (spec_element_type),
875 _dbus_type_to_string (element_type));
880 if (dbus_type_is_fixed (spec_element_type) &&
881 element_type != DBUS_TYPE_UNIX_FD)
883 ptr = va_arg (var_args, const DBusBasicValue**);
884 n_elements_p = va_arg (var_args, int*);
886 _dbus_assert (ptr != NULL);
887 _dbus_assert (n_elements_p != NULL);
889 _dbus_type_reader_recurse (&real->u.reader, &array);
891 _dbus_type_reader_read_fixed_multi (&array,
892 (void *) ptr, n_elements_p);
894 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
900 str_array_p = va_arg (var_args, char***);
901 n_elements_p = va_arg (var_args, int*);
903 _dbus_assert (str_array_p != NULL);
904 _dbus_assert (n_elements_p != NULL);
906 /* Count elements in the array */
907 _dbus_type_reader_recurse (&real->u.reader, &array);
910 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
913 _dbus_type_reader_next (&array);
916 str_array = dbus_new0 (char*, n_elements + 1);
917 if (str_array == NULL)
919 _DBUS_SET_OOM (error);
923 /* Now go through and dup each string */
924 _dbus_type_reader_recurse (&real->u.reader, &array);
927 while (i < n_elements)
930 _dbus_type_reader_read_basic (&array,
933 str_array[i] = _dbus_strdup (s);
934 if (str_array[i] == NULL)
936 dbus_free_string_array (str_array);
937 _DBUS_SET_OOM (error);
943 if (!_dbus_type_reader_next (&array))
944 _dbus_assert (i == n_elements);
947 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
948 _dbus_assert (i == n_elements);
949 _dbus_assert (str_array[i] == NULL);
951 *str_array_p = str_array;
952 *n_elements_p = n_elements;
954 #ifndef DBUS_DISABLE_CHECKS
957 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
958 _DBUS_FUNCTION_NAME);
963 #ifndef DBUS_DISABLE_CHECKS
966 _dbus_warn ("you can only read arrays and basic types with %s for now\n",
967 _DBUS_FUNCTION_NAME);
972 spec_type = va_arg (var_args, int);
973 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
975 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
976 "Message has only %d arguments, but more were expected", i);
993 * @defgroup DBusMessage DBusMessage
995 * @brief Message to be sent or received over a #DBusConnection.
997 * A DBusMessage is the most basic unit of communication over a
998 * DBusConnection. A DBusConnection represents a stream of messages
999 * received from a remote application, and a stream of messages
1000 * sent to a remote application.
1002 * A message has a message type, returned from
1003 * dbus_message_get_type(). This indicates whether the message is a
1004 * method call, a reply to a method call, a signal, or an error reply.
1006 * A message has header fields such as the sender, destination, method
1007 * or signal name, and so forth. DBusMessage has accessor functions for
1008 * these, such as dbus_message_get_member().
1010 * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
1011 * and dbus_message_is_error() check several header fields at once and are
1012 * slightly more efficient than checking the header fields with individual
1013 * accessor functions.
1015 * Finally, a message has arguments. The number and types of arguments
1016 * are in the message's signature header field (accessed with
1017 * dbus_message_get_signature()). Simple argument values are usually
1018 * retrieved with dbus_message_get_args() but more complex values such
1019 * as structs may require the use of #DBusMessageIter.
1021 * The D-Bus specification goes into some more detail about header fields and
1028 * @typedef DBusMessage
1030 * Opaque data type representing a message received from or to be
1031 * sent to another application.
1035 * Returns the serial of a message or 0 if none has been specified.
1036 * The message's serial number is provided by the application sending
1037 * the message and is used to identify replies to this message.
1039 * All messages received on a connection will have a serial provided
1040 * by the remote application.
1042 * For messages you're sending, dbus_connection_send() will assign a
1043 * serial and return it to you.
1045 * @param message the message
1046 * @returns the serial
1049 dbus_message_get_serial (DBusMessage *message)
1051 _dbus_return_val_if_fail (message != NULL, 0);
1053 return _dbus_header_get_serial (&message->header);
1057 * Sets the reply serial of a message (the serial of the message this
1060 * @param message the message
1061 * @param reply_serial the serial we're replying to
1062 * @returns #FALSE if not enough memory
1065 dbus_message_set_reply_serial (DBusMessage *message,
1066 dbus_uint32_t reply_serial)
1068 _dbus_return_val_if_fail (message != NULL, FALSE);
1069 _dbus_return_val_if_fail (!message->locked, FALSE);
1070 _dbus_return_val_if_fail (reply_serial != 0, FALSE); /* 0 is invalid */
1072 return _dbus_header_set_field_basic (&message->header,
1073 DBUS_HEADER_FIELD_REPLY_SERIAL,
1079 * Returns the serial that the message is a reply to or 0 if none.
1081 * @param message the message
1082 * @returns the reply serial
1085 dbus_message_get_reply_serial (DBusMessage *message)
1087 dbus_uint32_t v_UINT32;
1089 _dbus_return_val_if_fail (message != NULL, 0);
1091 if (_dbus_header_get_field_basic (&message->header,
1092 DBUS_HEADER_FIELD_REPLY_SERIAL,
1101 dbus_message_finalize (DBusMessage *message)
1103 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1105 /* This calls application callbacks! */
1106 _dbus_data_slot_list_free (&message->slot_list);
1108 _dbus_list_foreach (&message->counters,
1109 free_counter, message);
1110 _dbus_list_clear (&message->counters);
1112 _dbus_header_free (&message->header);
1113 _dbus_string_free (&message->body);
1115 #ifdef HAVE_UNIX_FD_PASSING
1116 close_unix_fds(message->unix_fds, &message->n_unix_fds);
1117 dbus_free(message->unix_fds);
1120 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1122 dbus_free (message);
1126 dbus_message_new_empty_header (void)
1128 DBusMessage *message;
1129 dbus_bool_t from_cache;
1131 message = dbus_message_get_cached ();
1133 if (message != NULL)
1140 message = dbus_new0 (DBusMessage, 1);
1141 if (message == NULL)
1143 #ifndef DBUS_DISABLE_CHECKS
1144 message->generation = _dbus_current_generation;
1147 #ifdef HAVE_UNIX_FD_PASSING
1148 message->unix_fds = NULL;
1149 message->n_unix_fds_allocated = 0;
1153 _dbus_atomic_inc (&message->refcount);
1155 _dbus_message_trace_ref (message, 0, 1, "new_empty_header");
1157 message->locked = FALSE;
1158 #ifndef DBUS_DISABLE_CHECKS
1159 message->in_cache = FALSE;
1161 message->counters = NULL;
1162 message->size_counter_delta = 0;
1163 message->changed_stamp = 0;
1165 #ifdef HAVE_UNIX_FD_PASSING
1166 message->n_unix_fds = 0;
1167 message->n_unix_fds_allocated = 0;
1168 message->unix_fd_counter_delta = 0;
1172 _dbus_data_slot_list_init (&message->slot_list);
1176 _dbus_header_reinit (&message->header);
1177 _dbus_string_set_length (&message->body, 0);
1181 if (!_dbus_header_init (&message->header))
1183 dbus_free (message);
1187 if (!_dbus_string_init_preallocated (&message->body, 32))
1189 _dbus_header_free (&message->header);
1190 dbus_free (message);
1199 * Constructs a new message of the given message type.
1200 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
1201 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
1203 * Usually you want to use dbus_message_new_method_call(),
1204 * dbus_message_new_method_return(), dbus_message_new_signal(),
1205 * or dbus_message_new_error() instead.
1207 * @param message_type type of message
1208 * @returns new message or #NULL if no memory
1211 dbus_message_new (int message_type)
1213 DBusMessage *message;
1215 _dbus_return_val_if_fail (message_type != DBUS_MESSAGE_TYPE_INVALID, NULL);
1217 message = dbus_message_new_empty_header ();
1218 if (message == NULL)
1221 if (!_dbus_header_create (&message->header,
1222 DBUS_COMPILER_BYTE_ORDER,
1224 NULL, NULL, NULL, NULL, NULL))
1226 dbus_message_unref (message);
1234 * Constructs a new message to invoke a method on a remote
1235 * object. Returns #NULL if memory can't be allocated for the
1236 * message. The destination may be #NULL in which case no destination
1237 * is set; this is appropriate when using D-Bus in a peer-to-peer
1238 * context (no message bus). The interface may be #NULL, which means
1239 * that if multiple methods with the given name exist it is undefined
1240 * which one will be invoked.
1242 * The path and method names may not be #NULL.
1244 * Destination, path, interface, and method name can't contain
1245 * any invalid characters (see the D-Bus specification).
1247 * @param destination name that the message should be sent to or #NULL
1248 * @param path object path the message should be sent to
1249 * @param interface interface to invoke method on, or #NULL
1250 * @param method method to invoke
1252 * @returns a new DBusMessage, free with dbus_message_unref()
1255 dbus_message_new_method_call (const char *destination,
1257 const char *interface,
1260 DBusMessage *message;
1262 _dbus_return_val_if_fail (path != NULL, NULL);
1263 _dbus_return_val_if_fail (method != NULL, NULL);
1264 _dbus_return_val_if_fail (destination == NULL ||
1265 _dbus_check_is_valid_bus_name (destination), NULL);
1266 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1267 _dbus_return_val_if_fail (interface == NULL ||
1268 _dbus_check_is_valid_interface (interface), NULL);
1269 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
1271 message = dbus_message_new_empty_header ();
1272 if (message == NULL)
1275 if (!_dbus_header_create (&message->header,
1276 DBUS_COMPILER_BYTE_ORDER,
1277 DBUS_MESSAGE_TYPE_METHOD_CALL,
1278 destination, path, interface, method, NULL))
1280 dbus_message_unref (message);
1288 * Constructs a message that is a reply to a method call. Returns
1289 * #NULL if memory can't be allocated for the message.
1291 * @param method_call the message being replied to
1292 * @returns a new DBusMessage, free with dbus_message_unref()
1295 dbus_message_new_method_return (DBusMessage *method_call)
1297 DBusMessage *message;
1300 _dbus_return_val_if_fail (method_call != NULL, NULL);
1302 sender = dbus_message_get_sender (method_call);
1304 /* sender is allowed to be null here in peer-to-peer case */
1306 message = dbus_message_new_empty_header ();
1307 if (message == NULL)
1310 if (!_dbus_header_create (&message->header,
1311 DBUS_COMPILER_BYTE_ORDER,
1312 DBUS_MESSAGE_TYPE_METHOD_RETURN,
1313 sender, NULL, NULL, NULL, NULL))
1315 dbus_message_unref (message);
1319 dbus_message_set_no_reply (message, TRUE);
1321 if (!dbus_message_set_reply_serial (message,
1322 dbus_message_get_serial (method_call)))
1324 dbus_message_unref (message);
1332 * Constructs a new message representing a signal emission. Returns
1333 * #NULL if memory can't be allocated for the message. A signal is
1334 * identified by its originating object path, interface, and the name
1337 * Path, interface, and signal name must all be valid (the D-Bus
1338 * specification defines the syntax of these fields).
1340 * @param path the path to the object emitting the signal
1341 * @param interface the interface the signal is emitted from
1342 * @param name name of the signal
1343 * @returns a new DBusMessage, free with dbus_message_unref()
1346 dbus_message_new_signal (const char *path,
1347 const char *interface,
1350 DBusMessage *message;
1352 _dbus_return_val_if_fail (path != NULL, NULL);
1353 _dbus_return_val_if_fail (interface != NULL, NULL);
1354 _dbus_return_val_if_fail (name != NULL, NULL);
1355 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1356 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (interface), NULL);
1357 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
1359 message = dbus_message_new_empty_header ();
1360 if (message == NULL)
1363 if (!_dbus_header_create (&message->header,
1364 DBUS_COMPILER_BYTE_ORDER,
1365 DBUS_MESSAGE_TYPE_SIGNAL,
1366 NULL, path, interface, name, NULL))
1368 dbus_message_unref (message);
1372 dbus_message_set_no_reply (message, TRUE);
1378 * Creates a new message that is an error reply to another message.
1379 * Error replies are most common in response to method calls, but
1380 * can be returned in reply to any message.
1382 * The error name must be a valid error name according to the syntax
1383 * given in the D-Bus specification. If you don't want to make
1384 * up an error name just use #DBUS_ERROR_FAILED.
1386 * @param reply_to the message we're replying to
1387 * @param error_name the error name
1388 * @param error_message the error message string (or #NULL for none, but please give a message)
1389 * @returns a new error message object, free with dbus_message_unref()
1392 dbus_message_new_error (DBusMessage *reply_to,
1393 const char *error_name,
1394 const char *error_message)
1396 DBusMessage *message;
1398 DBusMessageIter iter;
1400 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1401 _dbus_return_val_if_fail (error_name != NULL, NULL);
1402 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1404 sender = dbus_message_get_sender (reply_to);
1406 /* sender may be NULL for non-message-bus case or
1407 * when the message bus is dealing with an unregistered
1410 message = dbus_message_new_empty_header ();
1411 if (message == NULL)
1414 if (!_dbus_header_create (&message->header,
1415 DBUS_COMPILER_BYTE_ORDER,
1416 DBUS_MESSAGE_TYPE_ERROR,
1417 sender, NULL, NULL, NULL, error_name))
1419 dbus_message_unref (message);
1423 dbus_message_set_no_reply (message, TRUE);
1425 if (!dbus_message_set_reply_serial (message,
1426 dbus_message_get_serial (reply_to)))
1428 dbus_message_unref (message);
1432 if (error_message != NULL)
1434 dbus_message_iter_init_append (message, &iter);
1435 if (!dbus_message_iter_append_basic (&iter,
1439 dbus_message_unref (message);
1448 * Creates a new message that is an error reply to another message, allowing
1449 * you to use printf formatting.
1451 * See dbus_message_new_error() for details - this function is the same
1452 * aside from the printf formatting.
1454 * @todo add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to
1455 * public header, see DBUS_DEPRECATED for an example)
1457 * @param reply_to the original message
1458 * @param error_name the error name
1459 * @param error_format the error message format as with printf
1460 * @param ... format string arguments
1461 * @returns a new error message
1464 dbus_message_new_error_printf (DBusMessage *reply_to,
1465 const char *error_name,
1466 const char *error_format,
1471 DBusMessage *message;
1473 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1474 _dbus_return_val_if_fail (error_name != NULL, NULL);
1475 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1477 if (!_dbus_string_init (&str))
1480 va_start (args, error_format);
1482 if (_dbus_string_append_printf_valist (&str, error_format, args))
1483 message = dbus_message_new_error (reply_to, error_name,
1484 _dbus_string_get_const_data (&str));
1488 _dbus_string_free (&str);
1497 * Creates a new message that is an exact replica of the message
1498 * specified, except that its refcount is set to 1, its message serial
1499 * is reset to 0, and if the original message was "locked" (in the
1500 * outgoing message queue and thus not modifiable) the new message
1501 * will not be locked.
1503 * @todo This function can't be used in programs that try to recover from OOM errors.
1505 * @param message the message
1506 * @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.
1509 dbus_message_copy (const DBusMessage *message)
1511 DBusMessage *retval;
1513 _dbus_return_val_if_fail (message != NULL, NULL);
1515 retval = dbus_new0 (DBusMessage, 1);
1519 _dbus_atomic_inc (&retval->refcount);
1521 retval->locked = FALSE;
1522 #ifndef DBUS_DISABLE_CHECKS
1523 retval->generation = message->generation;
1526 if (!_dbus_header_copy (&message->header, &retval->header))
1532 if (!_dbus_string_init_preallocated (&retval->body,
1533 _dbus_string_get_length (&message->body)))
1535 _dbus_header_free (&retval->header);
1540 if (!_dbus_string_copy (&message->body, 0,
1544 #ifdef HAVE_UNIX_FD_PASSING
1545 retval->unix_fds = dbus_new(int, message->n_unix_fds);
1546 if (retval->unix_fds == NULL && message->n_unix_fds > 0)
1549 retval->n_unix_fds_allocated = message->n_unix_fds;
1551 for (retval->n_unix_fds = 0;
1552 retval->n_unix_fds < message->n_unix_fds;
1553 retval->n_unix_fds++)
1555 retval->unix_fds[retval->n_unix_fds] = _dbus_dup(message->unix_fds[retval->n_unix_fds], NULL);
1557 if (retval->unix_fds[retval->n_unix_fds] < 0)
1563 _dbus_message_trace_ref (retval, 0, 1, "copy");
1567 _dbus_header_free (&retval->header);
1568 _dbus_string_free (&retval->body);
1570 #ifdef HAVE_UNIX_FD_PASSING
1571 close_unix_fds(retval->unix_fds, &retval->n_unix_fds);
1572 dbus_free(retval->unix_fds);
1582 * Increments the reference count of a DBusMessage.
1584 * @param message the message
1585 * @returns the message
1586 * @see dbus_message_unref
1589 dbus_message_ref (DBusMessage *message)
1591 dbus_int32_t old_refcount;
1593 _dbus_return_val_if_fail (message != NULL, NULL);
1594 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1595 _dbus_return_val_if_fail (!message->in_cache, NULL);
1597 old_refcount = _dbus_atomic_inc (&message->refcount);
1598 _dbus_assert (old_refcount >= 1);
1599 _dbus_message_trace_ref (message, old_refcount, old_refcount + 1, "ref");
1605 * Decrements the reference count of a DBusMessage, freeing the
1606 * message if the count reaches 0.
1608 * @param message the message
1609 * @see dbus_message_ref
1612 dbus_message_unref (DBusMessage *message)
1614 dbus_int32_t old_refcount;
1616 _dbus_return_if_fail (message != NULL);
1617 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1618 _dbus_return_if_fail (!message->in_cache);
1620 old_refcount = _dbus_atomic_dec (&message->refcount);
1622 _dbus_assert (old_refcount >= 1);
1624 _dbus_message_trace_ref (message, old_refcount, old_refcount - 1, "unref");
1626 if (old_refcount == 1)
1628 /* Calls application callbacks! */
1629 dbus_message_cache_or_finalize (message);
1634 * Gets the type of a message. Types include
1635 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1636 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1637 * types are allowed and all code must silently ignore messages of
1638 * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
1640 * @param message the message
1641 * @returns the type of the message
1644 dbus_message_get_type (DBusMessage *message)
1646 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1648 return _dbus_header_get_message_type (&message->header);
1652 * Appends fields to a message given a variable argument list. The
1653 * variable argument list should contain the type of each argument
1654 * followed by the value to append. Appendable types are basic types,
1655 * and arrays of fixed-length basic types (except arrays of Unix file
1656 * descriptors). To append variable-length basic types, or any more
1657 * complex value, you have to use an iterator rather than this
1660 * To append a basic type, specify its type code followed by the
1661 * address of the value. For example:
1665 * dbus_int32_t v_INT32 = 42;
1666 * const char *v_STRING = "Hello World";
1667 * dbus_message_append_args (message,
1668 * DBUS_TYPE_INT32, &v_INT32,
1669 * DBUS_TYPE_STRING, &v_STRING,
1670 * DBUS_TYPE_INVALID);
1673 * To append an array of fixed-length basic types (except Unix file
1674 * descriptors), pass in the DBUS_TYPE_ARRAY typecode, the element
1675 * typecode, the address of the array pointer, and a 32-bit integer
1676 * giving the number of elements in the array. So for example: @code
1677 * const dbus_int32_t array[] = { 1, 2, 3 }; const dbus_int32_t
1678 * *v_ARRAY = array; dbus_message_append_args (message,
1679 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3, DBUS_TYPE_INVALID);
1682 * This function does not support arrays of Unix file descriptors. If
1683 * you need those you need to manually recurse into the array.
1685 * For Unix file descriptors this function will internally duplicate
1686 * the descriptor you passed in. Hence you may close the descriptor
1687 * immediately after this call.
1689 * @warning in C, given "int array[]", "&array == array" (the
1690 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
1691 * So if you're using an array instead of a pointer you have to create
1692 * a pointer variable, assign the array to it, then take the address
1693 * of the pointer variable. For strings it works to write
1694 * const char *array = "Hello" and then use &array though.
1696 * The last argument to this function must be #DBUS_TYPE_INVALID,
1697 * marking the end of the argument list. If you don't do this
1698 * then libdbus won't know to stop and will read invalid memory.
1700 * String/signature/path arrays should be passed in as "const char***
1701 * address_of_array" and "int n_elements"
1703 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1705 * @todo If this fails due to lack of memory, the message is hosed and
1706 * you have to start over building the whole message.
1708 * @param message the message
1709 * @param first_arg_type type of the first argument
1710 * @param ... value of first argument, list of additional type-value pairs
1711 * @returns #TRUE on success
1714 dbus_message_append_args (DBusMessage *message,
1721 _dbus_return_val_if_fail (message != NULL, FALSE);
1723 va_start (var_args, first_arg_type);
1724 retval = dbus_message_append_args_valist (message,
1733 * Like dbus_message_append_args() but takes a va_list for use by language bindings.
1735 * @todo for now, if this function fails due to OOM it will leave
1736 * the message half-written and you have to discard the message
1739 * @see dbus_message_append_args.
1740 * @param message the message
1741 * @param first_arg_type type of first argument
1742 * @param var_args value of first argument, then list of type/value pairs
1743 * @returns #TRUE on success
1746 dbus_message_append_args_valist (DBusMessage *message,
1751 DBusMessageIter iter;
1753 _dbus_return_val_if_fail (message != NULL, FALSE);
1755 type = first_arg_type;
1757 dbus_message_iter_init_append (message, &iter);
1759 while (type != DBUS_TYPE_INVALID)
1761 if (dbus_type_is_basic (type))
1763 const DBusBasicValue *value;
1764 value = va_arg (var_args, const DBusBasicValue*);
1766 if (!dbus_message_iter_append_basic (&iter,
1771 else if (type == DBUS_TYPE_ARRAY)
1774 DBusMessageIter array;
1777 element_type = va_arg (var_args, int);
1779 buf[0] = element_type;
1781 if (!dbus_message_iter_open_container (&iter,
1787 if (dbus_type_is_fixed (element_type) &&
1788 element_type != DBUS_TYPE_UNIX_FD)
1790 const DBusBasicValue **value;
1793 value = va_arg (var_args, const DBusBasicValue**);
1794 n_elements = va_arg (var_args, int);
1796 if (!dbus_message_iter_append_fixed_array (&array,
1800 dbus_message_iter_abandon_container (&iter, &array);
1804 else if (_DBUS_TYPE_IS_STRINGLIKE (element_type))
1806 const char ***value_p;
1811 value_p = va_arg (var_args, const char***);
1812 n_elements = va_arg (var_args, int);
1817 while (i < n_elements)
1819 if (!dbus_message_iter_append_basic (&array,
1822 dbus_message_iter_abandon_container (&iter, &array);
1830 _dbus_warn ("arrays of %s can't be appended with %s for now\n",
1831 _dbus_type_to_string (element_type),
1832 _DBUS_FUNCTION_NAME);
1836 if (!dbus_message_iter_close_container (&iter, &array))
1839 #ifndef DBUS_DISABLE_CHECKS
1842 _dbus_warn ("type %s isn't supported yet in %s\n",
1843 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
1848 type = va_arg (var_args, int);
1858 * Gets arguments from a message given a variable argument list. The
1859 * supported types include those supported by
1860 * dbus_message_append_args(); that is, basic types and arrays of
1861 * fixed-length basic types. The arguments are the same as they would
1862 * be for dbus_message_iter_get_basic() or
1863 * dbus_message_iter_get_fixed_array().
1865 * In addition to those types, arrays of string, object path, and
1866 * signature are supported; but these are returned as allocated memory
1867 * and must be freed with dbus_free_string_array(), while the other
1868 * types are returned as const references. To get a string array
1869 * pass in "char ***array_location" and "int *n_elements".
1871 * Similar to dbus_message_get_fixed_array() this function does not
1872 * support arrays of type DBUS_TYPE_UNIX_FD. If you need to parse
1873 * messages with arrays of Unix file descriptors you need to recurse
1874 * into the array manually.
1876 * Unix file descriptors that are read with this function will have
1877 * the FD_CLOEXEC flag set. If you need them without this flag set,
1878 * make sure to unset it with fcntl().
1880 * The variable argument list should contain the type of the argument
1881 * followed by a pointer to where the value should be stored. The list
1882 * is terminated with #DBUS_TYPE_INVALID.
1884 * Except for string arrays, the returned values are constant; do not
1885 * free them. They point into the #DBusMessage.
1887 * If the requested arguments are not present, or do not have the
1888 * requested types, then an error will be set.
1890 * If more arguments than requested are present, the requested
1891 * arguments are returned and the extra arguments are ignored.
1893 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1895 * @param message the message
1896 * @param error error to be filled in on failure
1897 * @param first_arg_type the first argument type
1898 * @param ... location for first argument value, then list of type-location pairs
1899 * @returns #FALSE if the error was set
1902 dbus_message_get_args (DBusMessage *message,
1910 _dbus_return_val_if_fail (message != NULL, FALSE);
1911 _dbus_return_val_if_error_is_set (error, FALSE);
1913 va_start (var_args, first_arg_type);
1914 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
1921 * Like dbus_message_get_args but takes a va_list for use by language bindings.
1923 * @see dbus_message_get_args
1924 * @param message the message
1925 * @param error error to be filled in
1926 * @param first_arg_type type of the first argument
1927 * @param var_args return location for first argument, followed by list of type/location pairs
1928 * @returns #FALSE if error was set
1931 dbus_message_get_args_valist (DBusMessage *message,
1936 DBusMessageIter iter;
1938 _dbus_return_val_if_fail (message != NULL, FALSE);
1939 _dbus_return_val_if_error_is_set (error, FALSE);
1941 dbus_message_iter_init (message, &iter);
1942 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
1946 _dbus_message_iter_init_common (DBusMessage *message,
1947 DBusMessageRealIter *real,
1950 _dbus_assert (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
1952 /* Since the iterator will read or write who-knows-what from the
1953 * message, we need to get in the right byte order
1955 ensure_byte_order (message);
1957 real->message = message;
1958 real->changed_stamp = message->changed_stamp;
1959 real->iter_type = iter_type;
1960 real->sig_refcount = 0;
1964 * Initializes a #DBusMessageIter for reading the arguments of the
1965 * message passed in.
1967 * When possible, dbus_message_get_args() is much more convenient.
1968 * Some types of argument can only be read with #DBusMessageIter
1971 * The easiest way to iterate is like this:
1973 * dbus_message_iter_init (message, &iter);
1974 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
1975 * dbus_message_iter_next (&iter);
1978 * #DBusMessageIter contains no allocated memory; it need not be
1979 * freed, and can be copied by assignment or memcpy().
1981 * @param message the message
1982 * @param iter pointer to an iterator to initialize
1983 * @returns #FALSE if the message has no arguments
1986 dbus_message_iter_init (DBusMessage *message,
1987 DBusMessageIter *iter)
1989 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1990 const DBusString *type_str;
1993 _dbus_return_val_if_fail (message != NULL, FALSE);
1994 _dbus_return_val_if_fail (iter != NULL, FALSE);
1996 get_const_signature (&message->header, &type_str, &type_pos);
1998 _dbus_message_iter_init_common (message, real,
1999 DBUS_MESSAGE_ITER_TYPE_READER);
2001 _dbus_type_reader_init (&real->u.reader,
2002 _dbus_header_get_byte_order (&message->header),
2007 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
2011 * Checks if an iterator has any more fields.
2013 * @param iter the message iter
2014 * @returns #TRUE if there are more fields following
2017 dbus_message_iter_has_next (DBusMessageIter *iter)
2019 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2021 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2022 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2024 return _dbus_type_reader_has_next (&real->u.reader);
2028 * Moves the iterator to the next field, if any. If there's no next
2029 * field, returns #FALSE. If the iterator moves forward, returns
2032 * @param iter the message iter
2033 * @returns #TRUE if the iterator was moved to the next field
2036 dbus_message_iter_next (DBusMessageIter *iter)
2038 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2040 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2041 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2043 return _dbus_type_reader_next (&real->u.reader);
2047 * Returns the argument type of the argument that the message iterator
2048 * points to. If the iterator is at the end of the message, returns
2049 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
2052 * dbus_message_iter_init (message, &iter);
2053 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2054 * dbus_message_iter_next (&iter);
2057 * @param iter the message iter
2058 * @returns the argument type
2061 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
2063 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2065 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2066 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2068 return _dbus_type_reader_get_current_type (&real->u.reader);
2072 * Returns the element type of the array that the message iterator
2073 * points to. Note that you need to check that the iterator points to
2074 * an array prior to using this function.
2076 * @param iter the message iter
2077 * @returns the array element type
2080 dbus_message_iter_get_element_type (DBusMessageIter *iter)
2082 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2084 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2085 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
2086 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
2088 return _dbus_type_reader_get_element_type (&real->u.reader);
2092 * Recurses into a container value when reading values from a message,
2093 * initializing a sub-iterator to use for traversing the child values
2096 * Note that this recurses into a value, not a type, so you can only
2097 * recurse if the value exists. The main implication of this is that
2098 * if you have for example an empty array of array of int32, you can
2099 * recurse into the outermost array, but it will have no values, so
2100 * you won't be able to recurse further. There's no array of int32 to
2103 * If a container is an array of fixed-length types (except Unix file
2104 * descriptors), it is much more efficient to use
2105 * dbus_message_iter_get_fixed_array() to get the whole array in one
2106 * shot, rather than individually walking over the array elements.
2108 * Be sure you have somehow checked that
2109 * dbus_message_iter_get_arg_type() matches the type you are expecting
2110 * to recurse into. Results of this function are undefined if there is
2111 * no container to recurse into at the current iterator position.
2113 * @param iter the message iterator
2114 * @param sub the sub-iterator to initialize
2117 dbus_message_iter_recurse (DBusMessageIter *iter,
2118 DBusMessageIter *sub)
2120 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2121 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2123 _dbus_return_if_fail (_dbus_message_iter_check (real));
2124 _dbus_return_if_fail (sub != NULL);
2127 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
2131 * Returns the current signature of a message iterator. This
2132 * is useful primarily for dealing with variants; one can
2133 * recurse into a variant and determine the signature of
2134 * the variant's value.
2136 * The returned string must be freed with dbus_free().
2138 * @param iter the message iterator
2139 * @returns the contained signature, or NULL if out of memory
2142 dbus_message_iter_get_signature (DBusMessageIter *iter)
2144 const DBusString *sig;
2148 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2150 _dbus_return_val_if_fail (_dbus_message_iter_check (real), NULL);
2152 if (!_dbus_string_init (&retstr))
2155 _dbus_type_reader_get_signature (&real->u.reader, &sig,
2157 if (!_dbus_string_append_len (&retstr,
2158 _dbus_string_get_const_data (sig) + start,
2161 if (!_dbus_string_steal_data (&retstr, &ret))
2163 _dbus_string_free (&retstr);
2168 * Reads a basic-typed value from the message iterator.
2169 * Basic types are the non-containers such as integer and string.
2171 * The value argument should be the address of a location to store
2172 * the returned value. So for int32 it should be a "dbus_int32_t*"
2173 * and for string a "const char**". The returned value is
2174 * by reference and should not be freed.
2176 * This call duplicates Unix file descriptors when reading them. It is
2177 * your job to close them when you don't need them anymore.
2179 * Unix file descriptors that are read with this function will have
2180 * the FD_CLOEXEC flag set. If you need them without this flag set,
2181 * make sure to unset it with fcntl().
2183 * Be sure you have somehow checked that
2184 * dbus_message_iter_get_arg_type() matches the type you are
2185 * expecting, or you'll crash when you try to use an integer as a
2186 * string or something.
2188 * To read any container type (array, struct, dict) you will need to
2189 * recurse into the container with dbus_message_iter_recurse(). If
2190 * the container is an array of fixed-length values (except Unix file
2191 * descriptors), you can get all the array elements at once with
2192 * dbus_message_iter_get_fixed_array(). Otherwise, you have to iterate
2193 * over the container's contents one value at a time.
2195 * All basic-typed values are guaranteed to fit in a #DBusBasicValue,
2196 * so in versions of libdbus that have that type, you can write code like this:
2199 * DBusBasicValue value;
2201 * dbus_message_iter_get_basic (&read_iter, &value);
2202 * type = dbus_message_iter_get_arg_type (&read_iter);
2203 * dbus_message_iter_append_basic (&write_iter, type, &value);
2206 * (All D-Bus basic types are either numeric and 8 bytes or smaller, or
2207 * behave like a string; so in older versions of libdbus, DBusBasicValue
2208 * can be replaced with union { char *string; unsigned char bytes[8]; },
2211 * @param iter the iterator
2212 * @param value location to store the value
2215 dbus_message_iter_get_basic (DBusMessageIter *iter,
2218 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2220 _dbus_return_if_fail (_dbus_message_iter_check (real));
2221 _dbus_return_if_fail (value != NULL);
2223 if (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_UNIX_FD)
2225 #ifdef HAVE_UNIX_FD_PASSING
2228 _dbus_type_reader_read_basic(&real->u.reader, &idx);
2230 if (idx.u32 >= real->message->n_unix_fds) {
2231 /* Hmm, we cannot really signal an error here, so let's make
2232 sure to return an invalid fd. */
2233 *((int*) value) = -1;
2237 *((int*) value) = _dbus_dup(real->message->unix_fds[idx.u32], NULL);
2239 *((int*) value) = -1;
2244 _dbus_type_reader_read_basic (&real->u.reader,
2250 * Returns the number of bytes in the array as marshaled in the wire
2251 * protocol. The iterator must currently be inside an array-typed
2254 * This function is deprecated on the grounds that it is stupid. Why
2255 * would you want to know how many bytes are in the array as marshaled
2256 * in the wire protocol? For now, use the n_elements returned from
2257 * dbus_message_iter_get_fixed_array() instead, or iterate over the
2258 * array values and count them.
2260 * @todo introduce a variant of this get_n_elements that returns
2261 * the number of elements, though with a non-fixed array it will not
2262 * be very efficient, so maybe it's not good.
2264 * @param iter the iterator
2265 * @returns the number of bytes in the array
2268 dbus_message_iter_get_array_len (DBusMessageIter *iter)
2270 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2272 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2274 return _dbus_type_reader_get_array_length (&real->u.reader);
2278 * Reads a block of fixed-length values from the message iterator.
2279 * Fixed-length values are those basic types that are not string-like,
2280 * such as integers, bool, double. The returned block will be from the
2281 * current position in the array until the end of the array.
2283 * There is one exception here: although DBUS_TYPE_UNIX_FD is
2284 * considered a 'fixed' type arrays of this type may not be read with
2287 * The message iter should be "in" the array (that is, you recurse into the
2288 * array, and then you call dbus_message_iter_get_fixed_array() on the
2289 * "sub-iterator" created by dbus_message_iter_recurse()).
2291 * The value argument should be the address of a location to store the
2292 * returned array. So for int32 it should be a "const dbus_int32_t**"
2293 * The returned value is by reference and should not be freed.
2295 * This function should only be used if dbus_type_is_fixed() returns
2296 * #TRUE for the element type.
2298 * If an array's elements are not fixed in size, you have to recurse
2299 * into the array with dbus_message_iter_recurse() and read the
2300 * elements one by one.
2302 * Because the array is not copied, this function runs in constant
2303 * time and is fast; it's much preferred over walking the entire array
2304 * with an iterator. (However, you can always use
2305 * dbus_message_iter_recurse(), even for fixed-length types;
2306 * dbus_message_iter_get_fixed_array() is just an optimization.)
2308 * @param iter the iterator
2309 * @param value location to store the block
2310 * @param n_elements number of elements in the block
2313 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
2317 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2318 #ifndef DBUS_DISABLE_CHECKS
2319 int subtype = _dbus_type_reader_get_current_type(&real->u.reader);
2321 _dbus_return_if_fail (_dbus_message_iter_check (real));
2322 _dbus_return_if_fail (value != NULL);
2323 _dbus_return_if_fail ((subtype == DBUS_TYPE_INVALID) ||
2324 (dbus_type_is_fixed (subtype) && subtype != DBUS_TYPE_UNIX_FD));
2327 _dbus_type_reader_read_fixed_multi (&real->u.reader,
2332 * Initializes a #DBusMessageIter for appending arguments to the end
2335 * @todo If appending any of the arguments fails due to lack of
2336 * memory, the message is hosed and you have to start over building
2337 * the whole message.
2339 * @param message the message
2340 * @param iter pointer to an iterator to initialize
2343 dbus_message_iter_init_append (DBusMessage *message,
2344 DBusMessageIter *iter)
2346 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2348 _dbus_return_if_fail (message != NULL);
2349 _dbus_return_if_fail (iter != NULL);
2351 _dbus_message_iter_init_common (message, real,
2352 DBUS_MESSAGE_ITER_TYPE_WRITER);
2354 /* We create the signature string and point iterators at it "on demand"
2355 * when a value is actually appended. That means that init() never fails
2358 _dbus_type_writer_init_types_delayed (&real->u.writer,
2359 _dbus_header_get_byte_order (&message->header),
2361 _dbus_string_get_length (&message->body));
2365 * Creates a temporary signature string containing the current
2366 * signature, stores it in the iterator, and points the iterator to
2367 * the end of it. Used any time we write to the message.
2369 * @param real an iterator without a type_str
2370 * @returns #FALSE if no memory
2373 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
2376 const DBusString *current_sig;
2377 int current_sig_pos;
2379 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2381 if (real->u.writer.type_str != NULL)
2383 _dbus_assert (real->sig_refcount > 0);
2384 real->sig_refcount += 1;
2388 str = dbus_new (DBusString, 1);
2392 if (!_dbus_header_get_field_raw (&real->message->header,
2393 DBUS_HEADER_FIELD_SIGNATURE,
2394 ¤t_sig, ¤t_sig_pos))
2401 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
2402 current_sig_pos += 1; /* move on to sig data */
2404 if (!_dbus_string_init_preallocated (str, current_len + 4))
2410 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
2413 _dbus_string_free (str);
2420 if (!_dbus_string_init_preallocated (str, 4))
2427 real->sig_refcount = 1;
2429 _dbus_type_writer_add_types (&real->u.writer,
2430 str, _dbus_string_get_length (str));
2435 * Sets the new signature as the message signature, frees the
2436 * signature string, and marks the iterator as not having a type_str
2437 * anymore. Frees the signature even if it fails, so you can't
2438 * really recover from failure. Kinda busted.
2440 * @param real an iterator without a type_str
2441 * @returns #FALSE if no memory
2444 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2447 const char *v_STRING;
2450 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2451 _dbus_assert (real->u.writer.type_str != NULL);
2452 _dbus_assert (real->sig_refcount > 0);
2454 real->sig_refcount -= 1;
2456 if (real->sig_refcount > 0)
2458 _dbus_assert (real->sig_refcount == 0);
2462 str = real->u.writer.type_str;
2464 v_STRING = _dbus_string_get_const_data (str);
2465 if (!_dbus_header_set_field_basic (&real->message->header,
2466 DBUS_HEADER_FIELD_SIGNATURE,
2467 DBUS_TYPE_SIGNATURE,
2471 _dbus_type_writer_remove_types (&real->u.writer);
2472 _dbus_string_free (str);
2479 * Frees the signature string and marks the iterator as not having a
2480 * type_str anymore. Since the new signature is not set, the message
2481 * will generally be hosed after this is called.
2483 * @param real an iterator without a type_str
2486 _dbus_message_iter_abandon_signature (DBusMessageRealIter *real)
2490 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2491 _dbus_assert (real->u.writer.type_str != NULL);
2492 _dbus_assert (real->sig_refcount > 0);
2494 real->sig_refcount -= 1;
2496 if (real->sig_refcount > 0)
2498 _dbus_assert (real->sig_refcount == 0);
2500 str = real->u.writer.type_str;
2502 _dbus_type_writer_remove_types (&real->u.writer);
2503 _dbus_string_free (str);
2507 #ifndef DBUS_DISABLE_CHECKS
2509 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2511 if (!_dbus_message_iter_check (iter))
2514 if (iter->message->locked)
2516 _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)\n");
2522 #endif /* DBUS_DISABLE_CHECKS */
2524 #ifdef HAVE_UNIX_FD_PASSING
2526 expand_fd_array(DBusMessage *m,
2531 /* This makes space for adding n new fds to the array and returns a
2532 pointer to the place were the first fd should be put. */
2534 if (m->n_unix_fds + n > m->n_unix_fds_allocated)
2539 /* Make twice as much space as necessary */
2540 k = (m->n_unix_fds + n) * 2;
2542 /* Allocate at least four */
2546 p = dbus_realloc(m->unix_fds, k * sizeof(int));
2551 m->n_unix_fds_allocated = k;
2554 return m->unix_fds + m->n_unix_fds;
2559 * Appends a basic-typed value to the message. The basic types are the
2560 * non-container types such as integer and string.
2562 * The "value" argument should be the address of a basic-typed value.
2563 * So for string, const char**. For integer, dbus_int32_t*.
2565 * For Unix file descriptors this function will internally duplicate
2566 * the descriptor you passed in. Hence you may close the descriptor
2567 * immediately after this call.
2569 * @todo If this fails due to lack of memory, the message is hosed and
2570 * you have to start over building the whole message.
2572 * @param iter the append iterator
2573 * @param type the type of the value
2574 * @param value the address of the value
2575 * @returns #FALSE if not enough memory
2578 dbus_message_iter_append_basic (DBusMessageIter *iter,
2582 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2585 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2586 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2587 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2588 _dbus_return_val_if_fail (value != NULL, FALSE);
2590 #ifndef DBUS_DISABLE_CHECKS
2593 const char * const *string_p;
2594 const dbus_bool_t *bool_p;
2596 case DBUS_TYPE_STRING:
2598 _dbus_return_val_if_fail (_dbus_check_is_valid_utf8 (*string_p), FALSE);
2601 case DBUS_TYPE_OBJECT_PATH:
2603 _dbus_return_val_if_fail (_dbus_check_is_valid_path (*string_p), FALSE);
2606 case DBUS_TYPE_SIGNATURE:
2608 _dbus_return_val_if_fail (_dbus_check_is_valid_signature (*string_p), FALSE);
2611 case DBUS_TYPE_BOOLEAN:
2613 _dbus_return_val_if_fail (*bool_p == 0 || *bool_p == 1, FALSE);
2618 /* nothing to check, all possible values are allowed */
2623 if (!_dbus_message_iter_open_signature (real))
2626 if (type == DBUS_TYPE_UNIX_FD)
2628 #ifdef HAVE_UNIX_FD_PASSING
2632 /* First step, include the fd in the fd list of this message */
2633 if (!(fds = expand_fd_array(real->message, 1)))
2636 *fds = _dbus_dup(*(int*) value, NULL);
2640 u = real->message->n_unix_fds;
2642 /* Second step, write the index to the fd */
2643 if (!(ret = _dbus_type_writer_write_basic (&real->u.writer, DBUS_TYPE_UNIX_FD, &u))) {
2644 _dbus_close(*fds, NULL);
2648 real->message->n_unix_fds += 1;
2651 /* Final step, update the header accordingly */
2652 ret = _dbus_header_set_field_basic (&real->message->header,
2653 DBUS_HEADER_FIELD_UNIX_FDS,
2657 /* If any of these operations fail the message is
2658 hosed. However, no memory or fds should be leaked since what
2659 has been added to message has been added to the message, and
2660 can hence be accounted for when the message is being
2668 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
2671 if (!_dbus_message_iter_close_signature (real))
2678 * Appends a block of fixed-length values to an array. The
2679 * fixed-length types are all basic types that are not string-like. So
2680 * int32, double, bool, etc. (Unix file descriptors however are not
2681 * supported.) You must call dbus_message_iter_open_container() to
2682 * open an array of values before calling this function. You may call
2683 * this function multiple times (and intermixed with calls to
2684 * dbus_message_iter_append_basic()) for the same array.
2686 * The "value" argument should be the address of the array. So for
2687 * integer, "dbus_int32_t**" is expected for example.
2689 * @warning in C, given "int array[]", "&array == array" (the
2690 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2691 * So if you're using an array instead of a pointer you have to create
2692 * a pointer variable, assign the array to it, then take the address
2693 * of the pointer variable.
2695 * const dbus_int32_t array[] = { 1, 2, 3 };
2696 * const dbus_int32_t *v_ARRAY = array;
2697 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
2698 * fprintf (stderr, "No memory!\n");
2700 * For strings it works to write const char *array = "Hello" and then
2701 * use &array though.
2703 * @todo If this fails due to lack of memory, the message is hosed and
2704 * you have to start over building the whole message.
2706 * @param iter the append iterator
2707 * @param element_type the type of the array elements
2708 * @param value the address of the array
2709 * @param n_elements the number of elements to append
2710 * @returns #FALSE if not enough memory
2713 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
2718 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2721 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2722 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2723 _dbus_return_val_if_fail (dbus_type_is_fixed (element_type) && element_type != DBUS_TYPE_UNIX_FD, FALSE);
2724 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
2725 _dbus_return_val_if_fail (value != NULL, FALSE);
2726 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
2727 _dbus_return_val_if_fail (n_elements <=
2728 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
2731 #ifndef DBUS_DISABLE_CHECKS
2732 if (element_type == DBUS_TYPE_BOOLEAN)
2734 const dbus_bool_t * const *bools = value;
2737 for (i = 0; i < n_elements; i++)
2739 _dbus_return_val_if_fail ((*bools)[i] == 0 || (*bools)[i] == 1, FALSE);
2744 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
2750 * Appends a container-typed value to the message; you are required to
2751 * append the contents of the container using the returned
2752 * sub-iterator, and then call
2753 * dbus_message_iter_close_container(). Container types are for
2754 * example struct, variant, and array. For variants, the
2755 * contained_signature should be the type of the single value inside
2756 * the variant. For structs and dict entries, contained_signature
2757 * should be #NULL; it will be set to whatever types you write into
2758 * the struct. For arrays, contained_signature should be the type of
2759 * the array elements.
2761 * @todo If this fails due to lack of memory, the message is hosed and
2762 * you have to start over building the whole message.
2764 * @param iter the append iterator
2765 * @param type the type of the value
2766 * @param contained_signature the type of container contents
2767 * @param sub sub-iterator to initialize
2768 * @returns #FALSE if not enough memory
2771 dbus_message_iter_open_container (DBusMessageIter *iter,
2773 const char *contained_signature,
2774 DBusMessageIter *sub)
2776 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2777 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2778 DBusString contained_str;
2780 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2781 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2782 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
2783 _dbus_return_val_if_fail (sub != NULL, FALSE);
2784 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
2785 contained_signature == NULL) ||
2786 (type == DBUS_TYPE_DICT_ENTRY &&
2787 contained_signature == NULL) ||
2788 (type == DBUS_TYPE_VARIANT &&
2789 contained_signature != NULL) ||
2790 (type == DBUS_TYPE_ARRAY &&
2791 contained_signature != NULL), FALSE);
2793 /* this would fail if the contained_signature is a dict entry, since
2794 * dict entries are invalid signatures standalone (they must be in
2797 _dbus_return_val_if_fail ((type == DBUS_TYPE_ARRAY && contained_signature && *contained_signature == DBUS_DICT_ENTRY_BEGIN_CHAR) ||
2798 (contained_signature == NULL ||
2799 _dbus_check_is_valid_signature (contained_signature)),
2802 if (!_dbus_message_iter_open_signature (real))
2807 if (contained_signature != NULL)
2809 _dbus_string_init_const (&contained_str, contained_signature);
2811 return _dbus_type_writer_recurse (&real->u.writer,
2814 &real_sub->u.writer);
2818 return _dbus_type_writer_recurse (&real->u.writer,
2821 &real_sub->u.writer);
2827 * Closes a container-typed value appended to the message; may write
2828 * out more information to the message known only after the entire
2829 * container is written, and may free resources created by
2830 * dbus_message_iter_open_container().
2832 * @todo If this fails due to lack of memory, the message is hosed and
2833 * you have to start over building the whole message.
2835 * @param iter the append iterator
2836 * @param sub sub-iterator to close
2837 * @returns #FALSE if not enough memory
2840 dbus_message_iter_close_container (DBusMessageIter *iter,
2841 DBusMessageIter *sub)
2843 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2844 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2847 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2848 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2849 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
2850 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2852 ret = _dbus_type_writer_unrecurse (&real->u.writer,
2853 &real_sub->u.writer);
2855 if (!_dbus_message_iter_close_signature (real))
2862 * Abandons creation of a contained-typed value and frees resources created
2863 * by dbus_message_iter_open_container(). Once this returns, the message
2864 * is hosed and you have to start over building the whole message.
2866 * This should only be used to abandon creation of a message when you have
2869 * @param iter the append iterator
2870 * @param sub sub-iterator to close
2873 dbus_message_iter_abandon_container (DBusMessageIter *iter,
2874 DBusMessageIter *sub)
2876 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2877 #ifndef DBUS_DISABLE_CHECKS
2878 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2880 _dbus_return_if_fail (_dbus_message_iter_append_check (real));
2881 _dbus_return_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2882 _dbus_return_if_fail (_dbus_message_iter_append_check (real_sub));
2883 _dbus_return_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2886 _dbus_message_iter_abandon_signature (real);
2890 * Sets a flag indicating that the message does not want a reply; if
2891 * this flag is set, the other end of the connection may (but is not
2892 * required to) optimize by not sending method return or error
2893 * replies. If this flag is set, there is no way to know whether the
2894 * message successfully arrived at the remote end. Normally you know a
2895 * message was received when you receive the reply to it.
2897 * The flag is #FALSE by default, that is by default the other end is
2898 * required to reply.
2900 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
2902 * @param message the message
2903 * @param no_reply #TRUE if no reply is desired
2906 dbus_message_set_no_reply (DBusMessage *message,
2907 dbus_bool_t no_reply)
2909 _dbus_return_if_fail (message != NULL);
2910 _dbus_return_if_fail (!message->locked);
2912 _dbus_header_toggle_flag (&message->header,
2913 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
2918 * Returns #TRUE if the message does not expect
2921 * @param message the message
2922 * @returns #TRUE if the message sender isn't waiting for a reply
2925 dbus_message_get_no_reply (DBusMessage *message)
2927 _dbus_return_val_if_fail (message != NULL, FALSE);
2929 return _dbus_header_get_flag (&message->header,
2930 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
2934 * Sets a flag indicating that an owner for the destination name will
2935 * be automatically started before the message is delivered. When this
2936 * flag is set, the message is held until a name owner finishes
2937 * starting up, or fails to start up. In case of failure, the reply
2940 * The flag is set to #TRUE by default, i.e. auto starting is the default.
2942 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
2944 * @param message the message
2945 * @param auto_start #TRUE if auto-starting is desired
2948 dbus_message_set_auto_start (DBusMessage *message,
2949 dbus_bool_t auto_start)
2951 _dbus_return_if_fail (message != NULL);
2952 _dbus_return_if_fail (!message->locked);
2954 _dbus_header_toggle_flag (&message->header,
2955 DBUS_HEADER_FLAG_NO_AUTO_START,
2960 * Returns #TRUE if the message will cause an owner for
2961 * destination name to be auto-started.
2963 * @param message the message
2964 * @returns #TRUE if the message will use auto-start
2967 dbus_message_get_auto_start (DBusMessage *message)
2969 _dbus_return_val_if_fail (message != NULL, FALSE);
2971 return !_dbus_header_get_flag (&message->header,
2972 DBUS_HEADER_FLAG_NO_AUTO_START);
2977 * Sets the object path this message is being sent to (for
2978 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
2979 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
2981 * The path must contain only valid characters as defined
2982 * in the D-Bus specification.
2984 * @param message the message
2985 * @param object_path the path or #NULL to unset
2986 * @returns #FALSE if not enough memory
2989 dbus_message_set_path (DBusMessage *message,
2990 const char *object_path)
2992 _dbus_return_val_if_fail (message != NULL, FALSE);
2993 _dbus_return_val_if_fail (!message->locked, FALSE);
2994 _dbus_return_val_if_fail (object_path == NULL ||
2995 _dbus_check_is_valid_path (object_path),
2998 return set_or_delete_string_field (message,
2999 DBUS_HEADER_FIELD_PATH,
3000 DBUS_TYPE_OBJECT_PATH,
3005 * Gets the object path this message is being sent to (for
3006 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
3007 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3009 * See also dbus_message_get_path_decomposed().
3011 * The returned string becomes invalid if the message is
3012 * modified, since it points into the wire-marshaled message data.
3014 * @param message the message
3015 * @returns the path (should not be freed) or #NULL
3018 dbus_message_get_path (DBusMessage *message)
3022 _dbus_return_val_if_fail (message != NULL, NULL);
3024 v = NULL; /* in case field doesn't exist */
3025 _dbus_header_get_field_basic (&message->header,
3026 DBUS_HEADER_FIELD_PATH,
3027 DBUS_TYPE_OBJECT_PATH,
3033 * Checks if the message has a particular object path. The object
3034 * path is the destination object for a method call or the emitting
3035 * object for a signal.
3037 * @param message the message
3038 * @param path the path name
3039 * @returns #TRUE if there is a path field in the header
3042 dbus_message_has_path (DBusMessage *message,
3045 const char *msg_path;
3046 msg_path = dbus_message_get_path (message);
3048 if (msg_path == NULL)
3059 if (strcmp (msg_path, path) == 0)
3066 * Gets the object path this message is being sent to
3067 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3068 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
3069 * format (one array element per path component).
3070 * Free the returned array with dbus_free_string_array().
3072 * An empty but non-NULL path array means the path "/".
3073 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
3074 * and the path "/" becomes { NULL }.
3076 * See also dbus_message_get_path().
3078 * @todo this could be optimized by using the len from the message
3079 * instead of calling strlen() again
3081 * @param message the message
3082 * @param path place to store allocated array of path components; #NULL set here if no path field exists
3083 * @returns #FALSE if no memory to allocate the array
3086 dbus_message_get_path_decomposed (DBusMessage *message,
3091 _dbus_return_val_if_fail (message != NULL, FALSE);
3092 _dbus_return_val_if_fail (path != NULL, FALSE);
3096 v = dbus_message_get_path (message);
3099 if (!_dbus_decompose_path (v, strlen (v),
3107 * Sets the interface this message is being sent to
3108 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
3109 * the interface a signal is being emitted from
3110 * (for DBUS_MESSAGE_TYPE_SIGNAL).
3112 * The interface name must contain only valid characters as defined
3113 * in the D-Bus specification.
3115 * @param message the message
3116 * @param interface the interface or #NULL to unset
3117 * @returns #FALSE if not enough memory
3120 dbus_message_set_interface (DBusMessage *message,
3121 const char *interface)
3123 _dbus_return_val_if_fail (message != NULL, FALSE);
3124 _dbus_return_val_if_fail (!message->locked, FALSE);
3125 _dbus_return_val_if_fail (interface == NULL ||
3126 _dbus_check_is_valid_interface (interface),
3129 return set_or_delete_string_field (message,
3130 DBUS_HEADER_FIELD_INTERFACE,
3136 * Gets the interface this message is being sent to
3137 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3138 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
3139 * The interface name is fully-qualified (namespaced).
3140 * Returns #NULL if none.
3142 * The returned string becomes invalid if the message is
3143 * modified, since it points into the wire-marshaled message data.
3145 * @param message the message
3146 * @returns the message interface (should not be freed) or #NULL
3149 dbus_message_get_interface (DBusMessage *message)
3153 _dbus_return_val_if_fail (message != NULL, NULL);
3155 v = NULL; /* in case field doesn't exist */
3156 _dbus_header_get_field_basic (&message->header,
3157 DBUS_HEADER_FIELD_INTERFACE,
3164 * Checks if the message has an interface
3166 * @param message the message
3167 * @param interface the interface name
3168 * @returns #TRUE if the interface field in the header matches
3171 dbus_message_has_interface (DBusMessage *message,
3172 const char *interface)
3174 const char *msg_interface;
3175 msg_interface = dbus_message_get_interface (message);
3177 if (msg_interface == NULL)
3179 if (interface == NULL)
3185 if (interface == NULL)
3188 if (strcmp (msg_interface, interface) == 0)
3196 * Sets the interface member being invoked
3197 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3198 * (DBUS_MESSAGE_TYPE_SIGNAL).
3200 * The member name must contain only valid characters as defined
3201 * in the D-Bus specification.
3203 * @param message the message
3204 * @param member the member or #NULL to unset
3205 * @returns #FALSE if not enough memory
3208 dbus_message_set_member (DBusMessage *message,
3211 _dbus_return_val_if_fail (message != NULL, FALSE);
3212 _dbus_return_val_if_fail (!message->locked, FALSE);
3213 _dbus_return_val_if_fail (member == NULL ||
3214 _dbus_check_is_valid_member (member),
3217 return set_or_delete_string_field (message,
3218 DBUS_HEADER_FIELD_MEMBER,
3224 * Gets the interface member being invoked
3225 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3226 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3228 * The returned string becomes invalid if the message is
3229 * modified, since it points into the wire-marshaled message data.
3231 * @param message the message
3232 * @returns the member name (should not be freed) or #NULL
3235 dbus_message_get_member (DBusMessage *message)
3239 _dbus_return_val_if_fail (message != NULL, NULL);
3241 v = NULL; /* in case field doesn't exist */
3242 _dbus_header_get_field_basic (&message->header,
3243 DBUS_HEADER_FIELD_MEMBER,
3250 * Checks if the message has an interface member
3252 * @param message the message
3253 * @param member the member name
3254 * @returns #TRUE if there is a member field in the header
3257 dbus_message_has_member (DBusMessage *message,
3260 const char *msg_member;
3261 msg_member = dbus_message_get_member (message);
3263 if (msg_member == NULL)
3274 if (strcmp (msg_member, member) == 0)
3282 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
3283 * The name is fully-qualified (namespaced).
3285 * The error name must contain only valid characters as defined
3286 * in the D-Bus specification.
3288 * @param message the message
3289 * @param error_name the name or #NULL to unset
3290 * @returns #FALSE if not enough memory
3293 dbus_message_set_error_name (DBusMessage *message,
3294 const char *error_name)
3296 _dbus_return_val_if_fail (message != NULL, FALSE);
3297 _dbus_return_val_if_fail (!message->locked, FALSE);
3298 _dbus_return_val_if_fail (error_name == NULL ||
3299 _dbus_check_is_valid_error_name (error_name),
3302 return set_or_delete_string_field (message,
3303 DBUS_HEADER_FIELD_ERROR_NAME,
3309 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
3312 * The returned string becomes invalid if the message is
3313 * modified, since it points into the wire-marshaled message data.
3315 * @param message the message
3316 * @returns the error name (should not be freed) or #NULL
3319 dbus_message_get_error_name (DBusMessage *message)
3323 _dbus_return_val_if_fail (message != NULL, NULL);
3325 v = NULL; /* in case field doesn't exist */
3326 _dbus_header_get_field_basic (&message->header,
3327 DBUS_HEADER_FIELD_ERROR_NAME,
3334 * Sets the message's destination. The destination is the name of
3335 * another connection on the bus and may be either the unique name
3336 * assigned by the bus to each connection, or a well-known name
3337 * specified in advance.
3339 * The destination name must contain only valid characters as defined
3340 * in the D-Bus specification.
3342 * @param message the message
3343 * @param destination the destination name or #NULL to unset
3344 * @returns #FALSE if not enough memory
3347 dbus_message_set_destination (DBusMessage *message,
3348 const char *destination)
3350 _dbus_return_val_if_fail (message != NULL, FALSE);
3351 _dbus_return_val_if_fail (!message->locked, FALSE);
3352 _dbus_return_val_if_fail (destination == NULL ||
3353 _dbus_check_is_valid_bus_name (destination),
3356 return set_or_delete_string_field (message,
3357 DBUS_HEADER_FIELD_DESTINATION,
3363 * Gets the destination of a message or #NULL if there is none set.
3365 * The returned string becomes invalid if the message is
3366 * modified, since it points into the wire-marshaled message data.
3368 * @param message the message
3369 * @returns the message destination (should not be freed) or #NULL
3372 dbus_message_get_destination (DBusMessage *message)
3376 _dbus_return_val_if_fail (message != NULL, NULL);
3378 v = NULL; /* in case field doesn't exist */
3379 _dbus_header_get_field_basic (&message->header,
3380 DBUS_HEADER_FIELD_DESTINATION,
3387 * Sets the message sender.
3389 * The sender must be a valid bus name as defined in the D-Bus
3392 * Usually you don't want to call this. The message bus daemon will
3393 * call it to set the origin of each message. If you aren't implementing
3394 * a message bus daemon you shouldn't need to set the sender.
3396 * @param message the message
3397 * @param sender the sender or #NULL to unset
3398 * @returns #FALSE if not enough memory
3401 dbus_message_set_sender (DBusMessage *message,
3404 _dbus_return_val_if_fail (message != NULL, FALSE);
3405 _dbus_return_val_if_fail (!message->locked, FALSE);
3406 _dbus_return_val_if_fail (sender == NULL ||
3407 _dbus_check_is_valid_bus_name (sender),
3410 return set_or_delete_string_field (message,
3411 DBUS_HEADER_FIELD_SENDER,
3417 * Gets the unique name of the connection which originated this
3418 * message, or #NULL if unknown or inapplicable. The sender is filled
3419 * in by the message bus.
3421 * Note, the returned sender is always the unique bus name.
3422 * Connections may own multiple other bus names, but those
3423 * are not found in the sender field.
3425 * The returned string becomes invalid if the message is
3426 * modified, since it points into the wire-marshaled message data.
3428 * @param message the message
3429 * @returns the unique name of the sender or #NULL
3432 dbus_message_get_sender (DBusMessage *message)
3436 _dbus_return_val_if_fail (message != NULL, NULL);
3438 v = NULL; /* in case field doesn't exist */
3439 _dbus_header_get_field_basic (&message->header,
3440 DBUS_HEADER_FIELD_SENDER,
3447 * Gets the type signature of the message, i.e. the arguments in the
3448 * message payload. The signature includes only "in" arguments for
3449 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
3450 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
3451 * what you might expect (that is, it does not include the signature of the
3452 * entire C++-style method).
3454 * The signature is a string made up of type codes such as
3455 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
3456 * the value of #DBUS_TYPE_INVALID).
3458 * The returned string becomes invalid if the message is
3459 * modified, since it points into the wire-marshaled message data.
3461 * @param message the message
3462 * @returns the type signature
3465 dbus_message_get_signature (DBusMessage *message)
3467 const DBusString *type_str;
3470 _dbus_return_val_if_fail (message != NULL, NULL);
3472 get_const_signature (&message->header, &type_str, &type_pos);
3474 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
3478 _dbus_message_has_type_interface_member (DBusMessage *message,
3480 const char *interface,
3485 _dbus_assert (message != NULL);
3486 _dbus_assert (interface != NULL);
3487 _dbus_assert (member != NULL);
3489 if (dbus_message_get_type (message) != type)
3492 /* Optimize by checking the short member name first
3493 * instead of the longer interface name
3496 n = dbus_message_get_member (message);
3498 if (n && strcmp (n, member) == 0)
3500 n = dbus_message_get_interface (message);
3502 if (n == NULL || strcmp (n, interface) == 0)
3510 * Checks whether the message is a method call with the given
3511 * interface and member fields. If the message is not
3512 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
3513 * member field, returns #FALSE. If the interface field is missing,
3514 * then it will be assumed equal to the provided interface. The D-Bus
3515 * protocol allows method callers to leave out the interface name.
3517 * @param message the message
3518 * @param interface the name to check (must not be #NULL)
3519 * @param method the name to check (must not be #NULL)
3521 * @returns #TRUE if the message is the specified method call
3524 dbus_message_is_method_call (DBusMessage *message,
3525 const char *interface,
3528 _dbus_return_val_if_fail (message != NULL, FALSE);
3529 _dbus_return_val_if_fail (interface != NULL, FALSE);
3530 _dbus_return_val_if_fail (method != NULL, FALSE);
3531 /* don't check that interface/method are valid since it would be
3532 * expensive, and not catch many common errors
3535 return _dbus_message_has_type_interface_member (message,
3536 DBUS_MESSAGE_TYPE_METHOD_CALL,
3541 * Checks whether the message is a signal with the given interface and
3542 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
3543 * has a different interface or member field, returns #FALSE.
3545 * @param message the message
3546 * @param interface the name to check (must not be #NULL)
3547 * @param signal_name the name to check (must not be #NULL)
3549 * @returns #TRUE if the message is the specified signal
3552 dbus_message_is_signal (DBusMessage *message,
3553 const char *interface,
3554 const char *signal_name)
3556 _dbus_return_val_if_fail (message != NULL, FALSE);
3557 _dbus_return_val_if_fail (interface != NULL, FALSE);
3558 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
3559 /* don't check that interface/name are valid since it would be
3560 * expensive, and not catch many common errors
3563 return _dbus_message_has_type_interface_member (message,
3564 DBUS_MESSAGE_TYPE_SIGNAL,
3565 interface, signal_name);
3569 * Checks whether the message is an error reply with the given error
3570 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
3571 * different name, returns #FALSE.
3573 * @param message the message
3574 * @param error_name the name to check (must not be #NULL)
3576 * @returns #TRUE if the message is the specified error
3579 dbus_message_is_error (DBusMessage *message,
3580 const char *error_name)
3584 _dbus_return_val_if_fail (message != NULL, FALSE);
3585 _dbus_return_val_if_fail (error_name != NULL, FALSE);
3586 /* don't check that error_name is valid since it would be expensive,
3587 * and not catch many common errors
3590 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3593 n = dbus_message_get_error_name (message);
3595 if (n && strcmp (n, error_name) == 0)
3602 * Checks whether the message was sent to the given name. If the
3603 * message has no destination specified or has a different
3604 * destination, returns #FALSE.
3606 * @param message the message
3607 * @param name the name to check (must not be #NULL)
3609 * @returns #TRUE if the message has the given destination name
3612 dbus_message_has_destination (DBusMessage *message,
3617 _dbus_return_val_if_fail (message != NULL, FALSE);
3618 _dbus_return_val_if_fail (name != NULL, FALSE);
3619 /* don't check that name is valid since it would be expensive, and
3620 * not catch many common errors
3623 s = dbus_message_get_destination (message);
3625 if (s && strcmp (s, name) == 0)
3632 * Checks whether the message has the given unique name as its sender.
3633 * If the message has no sender specified or has a different sender,
3634 * returns #FALSE. Note that a peer application will always have the
3635 * unique name of the connection as the sender. So you can't use this
3636 * function to see whether a sender owned a well-known name.
3638 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
3641 * @param message the message
3642 * @param name the name to check (must not be #NULL)
3644 * @returns #TRUE if the message has the given sender
3647 dbus_message_has_sender (DBusMessage *message,
3652 _dbus_return_val_if_fail (message != NULL, FALSE);
3653 _dbus_return_val_if_fail (name != NULL, FALSE);
3654 /* don't check that name is valid since it would be expensive, and
3655 * not catch many common errors
3658 s = dbus_message_get_sender (message);
3660 if (s && strcmp (s, name) == 0)
3667 * Checks whether the message has the given signature; see
3668 * dbus_message_get_signature() for more details on what the signature
3671 * @param message the message
3672 * @param signature typecode array
3673 * @returns #TRUE if message has the given signature
3676 dbus_message_has_signature (DBusMessage *message,
3677 const char *signature)
3681 _dbus_return_val_if_fail (message != NULL, FALSE);
3682 _dbus_return_val_if_fail (signature != NULL, FALSE);
3683 /* don't check that signature is valid since it would be expensive,
3684 * and not catch many common errors
3687 s = dbus_message_get_signature (message);
3689 if (s && strcmp (s, signature) == 0)
3696 * Sets a #DBusError based on the contents of the given
3697 * message. The error is only set if the message
3698 * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
3699 * The name of the error is set to the name of the message,
3700 * and the error message is set to the first argument
3701 * if the argument exists and is a string.
3703 * The return value indicates whether the error was set (the error is
3704 * set if and only if the message is an error message). So you can
3705 * check for an error reply and convert it to DBusError in one go:
3707 * if (dbus_set_error_from_message (error, reply))
3713 * @param error the error to set
3714 * @param message the message to set it from
3715 * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
3718 dbus_set_error_from_message (DBusError *error,
3719 DBusMessage *message)
3723 _dbus_return_val_if_fail (message != NULL, FALSE);
3724 _dbus_return_val_if_error_is_set (error, FALSE);
3726 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3730 dbus_message_get_args (message, NULL,
3731 DBUS_TYPE_STRING, &str,
3734 dbus_set_error (error, dbus_message_get_error_name (message),
3735 str ? "%s" : NULL, str);
3741 * Checks whether a message contains unix fds
3743 * @param message the message
3744 * @returns #TRUE if the message contains unix fds
3747 dbus_message_contains_unix_fds(DBusMessage *message)
3749 #ifdef HAVE_UNIX_FD_PASSING
3750 _dbus_assert(message);
3752 return message->n_unix_fds > 0;
3761 * @addtogroup DBusMessageInternals
3767 * The initial buffer size of the message loader.
3769 * @todo this should be based on min header size plus some average
3770 * body size, or something. Or rather, the min header size only, if we
3771 * want to try to read only the header, store that in a DBusMessage,
3772 * then read only the body and store that, etc., depends on
3773 * how we optimize _dbus_message_loader_get_buffer() and what
3774 * the exact message format is.
3776 #define INITIAL_LOADER_DATA_LEN 32
3779 * Creates a new message loader. Returns #NULL if memory can't
3782 * @returns new loader, or #NULL.
3785 _dbus_message_loader_new (void)
3787 DBusMessageLoader *loader;
3789 loader = dbus_new0 (DBusMessageLoader, 1);
3793 loader->refcount = 1;
3795 loader->corrupted = FALSE;
3796 loader->corruption_reason = DBUS_VALID;
3798 /* this can be configured by the app, but defaults to the protocol max */
3799 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
3801 /* We set a very relatively conservative default here since due to how
3802 SCM_RIGHTS works we need to preallocate an fd array of the maximum
3803 number of unix fds we want to receive in advance. A
3804 try-and-reallocate loop is not possible. */
3805 loader->max_message_unix_fds = 1024;
3807 if (!_dbus_string_init (&loader->data))
3813 /* preallocate the buffer for speed, ignore failure */
3814 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
3815 _dbus_string_set_length (&loader->data, 0);
3817 #ifdef HAVE_UNIX_FD_PASSING
3818 loader->unix_fds = NULL;
3819 loader->n_unix_fds = loader->n_unix_fds_allocated = 0;
3820 loader->unix_fds_outstanding = FALSE;
3827 * Increments the reference count of the loader.
3829 * @param loader the loader.
3830 * @returns the loader
3833 _dbus_message_loader_ref (DBusMessageLoader *loader)
3835 loader->refcount += 1;
3841 * Decrements the reference count of the loader and finalizes the
3842 * loader when the count reaches zero.
3844 * @param loader the loader.
3847 _dbus_message_loader_unref (DBusMessageLoader *loader)
3849 loader->refcount -= 1;
3850 if (loader->refcount == 0)
3852 #ifdef HAVE_UNIX_FD_PASSING
3853 close_unix_fds(loader->unix_fds, &loader->n_unix_fds);
3854 dbus_free(loader->unix_fds);
3856 _dbus_list_foreach (&loader->messages,
3857 (DBusForeachFunction) dbus_message_unref,
3859 _dbus_list_clear (&loader->messages);
3860 _dbus_string_free (&loader->data);
3866 * Gets the buffer to use for reading data from the network. Network
3867 * data is read directly into an allocated buffer, which is then used
3868 * in the DBusMessage, to avoid as many extra memcpy's as possible.
3869 * The buffer must always be returned immediately using
3870 * _dbus_message_loader_return_buffer(), even if no bytes are
3871 * successfully read.
3873 * @todo this function can be a lot more clever. For example
3874 * it can probably always return a buffer size to read exactly
3875 * the body of the next message, thus avoiding any memory wastage
3878 * @todo we need to enforce a max length on strings in header fields.
3880 * @param loader the message loader.
3881 * @param buffer the buffer
3884 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
3885 DBusString **buffer)
3887 _dbus_assert (!loader->buffer_outstanding);
3889 *buffer = &loader->data;
3891 loader->buffer_outstanding = TRUE;
3895 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
3896 * indicating to the loader how many bytes of the buffer were filled
3897 * in. This function must always be called, even if no bytes were
3898 * successfully read.
3900 * @param loader the loader.
3901 * @param buffer the buffer.
3902 * @param bytes_read number of bytes that were read into the buffer.
3905 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
3909 _dbus_assert (loader->buffer_outstanding);
3910 _dbus_assert (buffer == &loader->data);
3912 loader->buffer_outstanding = FALSE;
3916 * Gets the buffer to use for reading unix fds from the network.
3918 * This works similar to _dbus_message_loader_get_buffer()
3920 * @param loader the message loader.
3921 * @param fds the array to read fds into
3922 * @param max_n_fds how many fds to read at most
3923 * @return TRUE on success, FALSE on OOM
3926 _dbus_message_loader_get_unix_fds(DBusMessageLoader *loader,
3928 unsigned *max_n_fds)
3930 #ifdef HAVE_UNIX_FD_PASSING
3931 _dbus_assert (!loader->unix_fds_outstanding);
3933 /* Allocate space where we can put the fds we read. We allocate
3934 space for max_message_unix_fds since this is an
3935 upper limit how many fds can be received within a single
3936 message. Since SCM_RIGHTS doesn't allow a reallocate+retry logic
3937 we are allocating the maximum possible array size right from the
3938 beginning. This sucks a bit, however unless SCM_RIGHTS is fixed
3939 there is no better way. */
3941 if (loader->n_unix_fds_allocated < loader->max_message_unix_fds)
3943 int *a = dbus_realloc(loader->unix_fds,
3944 loader->max_message_unix_fds * sizeof(loader->unix_fds[0]));
3949 loader->unix_fds = a;
3950 loader->n_unix_fds_allocated = loader->max_message_unix_fds;
3953 *fds = loader->unix_fds + loader->n_unix_fds;
3954 *max_n_fds = loader->n_unix_fds_allocated - loader->n_unix_fds;
3956 loader->unix_fds_outstanding = TRUE;
3959 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
3965 * Returns a buffer obtained from _dbus_message_loader_get_unix_fds().
3967 * This works similar to _dbus_message_loader_return_buffer()
3969 * @param loader the message loader.
3970 * @param fds the array fds were read into
3971 * @param max_n_fds how many fds were read
3975 _dbus_message_loader_return_unix_fds(DBusMessageLoader *loader,
3979 #ifdef HAVE_UNIX_FD_PASSING
3980 _dbus_assert(loader->unix_fds_outstanding);
3981 _dbus_assert(loader->unix_fds + loader->n_unix_fds == fds);
3982 _dbus_assert(loader->n_unix_fds + n_fds <= loader->n_unix_fds_allocated);
3984 loader->n_unix_fds += n_fds;
3985 loader->unix_fds_outstanding = FALSE;
3987 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
3992 * FIXME when we move the header out of the buffer, that memmoves all
3993 * buffered messages. Kind of crappy.
3995 * Also we copy the header and body, which is kind of crappy. To
3996 * avoid this, we have to allow header and body to be in a single
3997 * memory block, which is good for messages we read and bad for
3998 * messages we are creating. But we could move_len() the buffer into
3999 * this single memory block, and move_len() will just swap the buffers
4000 * if you're moving the entire buffer replacing the dest string.
4002 * We could also have the message loader tell the transport how many
4003 * bytes to read; so it would first ask for some arbitrary number like
4004 * 256, then if the message was incomplete it would use the
4005 * header/body len to ask for exactly the size of the message (or
4006 * blocks the size of a typical kernel buffer for the socket). That
4007 * way we don't get trailing bytes in the buffer that have to be
4008 * memmoved. Though I suppose we also don't have a chance of reading a
4009 * bunch of small messages at once, so the optimization may be stupid.
4011 * Another approach would be to keep a "start" index into
4012 * loader->data and only delete it occasionally, instead of after
4013 * each message is loaded.
4015 * load_message() returns FALSE if not enough memory OR the loader was corrupted
4018 load_message (DBusMessageLoader *loader,
4019 DBusMessage *message,
4021 int fields_array_len,
4026 DBusValidity validity;
4027 const DBusString *type_str;
4029 DBusValidationMode mode;
4030 dbus_uint32_t n_unix_fds = 0;
4032 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
4037 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
4040 /* 1. VALIDATE AND COPY OVER HEADER */
4041 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
4042 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
4044 if (!_dbus_header_load (&message->header,
4052 _dbus_string_get_length (&loader->data)))
4054 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
4056 /* assert here so we can catch any code that still uses DBUS_VALID to indicate
4057 oom errors. They should use DBUS_VALIDITY_UNKNOWN_OOM_ERROR instead */
4058 _dbus_assert (validity != DBUS_VALID);
4060 if (validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
4064 loader->corrupted = TRUE;
4065 loader->corruption_reason = validity;
4070 _dbus_assert (validity == DBUS_VALID);
4072 /* 2. VALIDATE BODY */
4073 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
4075 get_const_signature (&message->header, &type_str, &type_pos);
4077 /* Because the bytes_remaining arg is NULL, this validates that the
4078 * body is the right length
4080 validity = _dbus_validate_body_with_reason (type_str,
4087 if (validity != DBUS_VALID)
4089 _dbus_verbose ("Failed to validate message body code %d\n", validity);
4091 loader->corrupted = TRUE;
4092 loader->corruption_reason = validity;
4098 /* 3. COPY OVER UNIX FDS */
4099 _dbus_header_get_field_basic(&message->header,
4100 DBUS_HEADER_FIELD_UNIX_FDS,
4104 #ifdef HAVE_UNIX_FD_PASSING
4106 if (n_unix_fds > loader->n_unix_fds)
4108 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
4109 n_unix_fds, loader->n_unix_fds);
4111 loader->corrupted = TRUE;
4112 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4116 /* If this was a recycled message there might still be
4117 some memory allocated for the fds */
4118 dbus_free(message->unix_fds);
4122 message->unix_fds = _dbus_memdup(loader->unix_fds, n_unix_fds * sizeof(message->unix_fds[0]));
4123 if (message->unix_fds == NULL)
4125 _dbus_verbose ("Failed to allocate file descriptor array\n");
4130 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
4131 loader->n_unix_fds -= n_unix_fds;
4132 memmove(loader->unix_fds + n_unix_fds, loader->unix_fds, loader->n_unix_fds);
4135 message->unix_fds = NULL;
4141 _dbus_verbose ("Hmm, message claims to come with file descriptors "
4142 "but that's not supported on our platform, disconnecting.\n");
4144 loader->corrupted = TRUE;
4145 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4151 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
4153 if (!_dbus_list_append (&loader->messages, message))
4155 _dbus_verbose ("Failed to append new message to loader queue\n");
4160 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
4161 _dbus_assert (_dbus_string_get_length (&loader->data) >=
4162 (header_len + body_len));
4164 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
4166 _dbus_verbose ("Failed to move body into new message\n");
4171 _dbus_string_delete (&loader->data, 0, header_len + body_len);
4173 /* don't waste more than 2k of memory */
4174 _dbus_string_compact (&loader->data, 2048);
4176 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
4177 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
4179 _dbus_verbose ("Loaded message %p\n", message);
4181 _dbus_assert (!oom);
4182 _dbus_assert (!loader->corrupted);
4183 _dbus_assert (loader->messages != NULL);
4184 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4192 /* does nothing if the message isn't in the list */
4193 _dbus_list_remove_last (&loader->messages, message);
4196 _dbus_assert (!loader->corrupted);
4198 _dbus_assert (loader->corrupted);
4200 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
4206 * Converts buffered data into messages, if we have enough data. If
4207 * we don't have enough data, does nothing.
4209 * @todo we need to check that the proper named header fields exist
4210 * for each message type.
4212 * @todo If a message has unknown type, we should probably eat it
4213 * right here rather than passing it out to applications. However
4214 * it's not an error to see messages of unknown type.
4216 * @param loader the loader.
4217 * @returns #TRUE if we had enough memory to finish.
4220 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
4222 while (!loader->corrupted &&
4223 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
4225 DBusValidity validity;
4226 int byte_order, fields_array_len, header_len, body_len;
4228 if (_dbus_header_have_message_untrusted (loader->max_message_size,
4235 _dbus_string_get_length (&loader->data)))
4237 DBusMessage *message;
4239 _dbus_assert (validity == DBUS_VALID);
4241 message = dbus_message_new_empty_header ();
4242 if (message == NULL)
4245 if (!load_message (loader, message,
4246 byte_order, fields_array_len,
4247 header_len, body_len))
4249 dbus_message_unref (message);
4250 /* load_message() returns false if corrupted or OOM; if
4251 * corrupted then return TRUE for not OOM
4253 return loader->corrupted;
4256 _dbus_assert (loader->messages != NULL);
4257 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4261 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
4263 if (validity != DBUS_VALID)
4265 loader->corrupted = TRUE;
4266 loader->corruption_reason = validity;
4276 * Peeks at first loaded message, returns #NULL if no messages have
4279 * @param loader the loader.
4280 * @returns the next message, or #NULL if none.
4283 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
4285 if (loader->messages)
4286 return loader->messages->data;
4292 * Pops a loaded message (passing ownership of the message
4293 * to the caller). Returns #NULL if no messages have been
4296 * @param loader the loader.
4297 * @returns the next message, or #NULL if none.
4300 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
4302 return _dbus_list_pop_first (&loader->messages);
4306 * Pops a loaded message inside a list link (passing ownership of the
4307 * message and link to the caller). Returns #NULL if no messages have
4310 * @param loader the loader.
4311 * @returns the next message link, or #NULL if none.
4314 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
4316 return _dbus_list_pop_first_link (&loader->messages);
4320 * Returns a popped message link, used to undo a pop.
4322 * @param loader the loader
4323 * @param link the link with a message in it
4326 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
4329 _dbus_list_prepend_link (&loader->messages, link);
4333 * Checks whether the loader is confused due to bad data.
4334 * If messages are received that are invalid, the
4335 * loader gets confused and gives up permanently.
4336 * This state is called "corrupted."
4338 * @param loader the loader
4339 * @returns #TRUE if the loader is hosed.
4342 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
4344 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4345 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4346 return loader->corrupted;
4350 * Checks what kind of bad data confused the loader.
4352 * @param loader the loader
4353 * @returns why the loader is hosed, or DBUS_VALID if it isn't.
4356 _dbus_message_loader_get_corruption_reason (DBusMessageLoader *loader)
4358 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4359 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4361 return loader->corruption_reason;
4365 * Sets the maximum size message we allow.
4367 * @param loader the loader
4368 * @param size the max message size in bytes
4371 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
4374 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
4376 _dbus_verbose ("clamping requested max message size %ld to %d\n",
4377 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
4378 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4380 loader->max_message_size = size;
4384 * Gets the maximum allowed message size in bytes.
4386 * @param loader the loader
4387 * @returns max size in bytes
4390 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
4392 return loader->max_message_size;
4396 * Sets the maximum unix fds per message we allow.
4398 * @param loader the loader
4399 * @param size the max number of unix fds in a message
4402 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader,
4405 if (n > DBUS_MAXIMUM_MESSAGE_UNIX_FDS)
4407 _dbus_verbose ("clamping requested max message unix_fds %ld to %d\n",
4408 n, DBUS_MAXIMUM_MESSAGE_UNIX_FDS);
4409 n = DBUS_MAXIMUM_MESSAGE_UNIX_FDS;
4411 loader->max_message_unix_fds = n;
4415 * Gets the maximum allowed number of unix fds per message
4417 * @param loader the loader
4418 * @returns max unix fds
4421 _dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
4423 return loader->max_message_unix_fds;
4426 static DBusDataSlotAllocator slot_allocator;
4427 _DBUS_DEFINE_GLOBAL_LOCK (message_slots);
4430 * Allocates an integer ID to be used for storing application-specific
4431 * data on any DBusMessage. The allocated ID may then be used
4432 * with dbus_message_set_data() and dbus_message_get_data().
4433 * The passed-in slot must be initialized to -1, and is filled in
4434 * with the slot ID. If the passed-in slot is not -1, it's assumed
4435 * to be already allocated, and its refcount is incremented.
4437 * The allocated slot is global, i.e. all DBusMessage objects will
4438 * have a slot with the given integer ID reserved.
4440 * @param slot_p address of a global variable storing the slot
4441 * @returns #FALSE on failure (no memory)
4444 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
4446 return _dbus_data_slot_allocator_alloc (&slot_allocator,
4447 &_DBUS_LOCK_NAME (message_slots),
4452 * Deallocates a global ID for message data slots.
4453 * dbus_message_get_data() and dbus_message_set_data() may no
4454 * longer be used with this slot. Existing data stored on existing
4455 * DBusMessage objects will be freed when the message is
4456 * finalized, but may not be retrieved (and may only be replaced if
4457 * someone else reallocates the slot). When the refcount on the
4458 * passed-in slot reaches 0, it is set to -1.
4460 * @param slot_p address storing the slot to deallocate
4463 dbus_message_free_data_slot (dbus_int32_t *slot_p)
4465 _dbus_return_if_fail (*slot_p >= 0);
4467 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
4471 * Stores a pointer on a DBusMessage, along
4472 * with an optional function to be used for freeing
4473 * the data when the data is set again, or when
4474 * the message is finalized. The slot number
4475 * must have been allocated with dbus_message_allocate_data_slot().
4477 * @param message the message
4478 * @param slot the slot number
4479 * @param data the data to store
4480 * @param free_data_func finalizer function for the data
4481 * @returns #TRUE if there was enough memory to store the data
4484 dbus_message_set_data (DBusMessage *message,
4487 DBusFreeFunction free_data_func)
4489 DBusFreeFunction old_free_func;
4493 _dbus_return_val_if_fail (message != NULL, FALSE);
4494 _dbus_return_val_if_fail (slot >= 0, FALSE);
4496 retval = _dbus_data_slot_list_set (&slot_allocator,
4497 &message->slot_list,
4498 slot, data, free_data_func,
4499 &old_free_func, &old_data);
4503 /* Do the actual free outside the message lock */
4505 (* old_free_func) (old_data);
4512 * Retrieves data previously set with dbus_message_set_data().
4513 * The slot must still be allocated (must not have been freed).
4515 * @param message the message
4516 * @param slot the slot to get data from
4517 * @returns the data, or #NULL if not found
4520 dbus_message_get_data (DBusMessage *message,
4525 _dbus_return_val_if_fail (message != NULL, NULL);
4527 res = _dbus_data_slot_list_get (&slot_allocator,
4528 &message->slot_list,
4535 * Utility function to convert a machine-readable (not translated)
4536 * string into a D-Bus message type.
4539 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
4540 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
4541 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
4542 * "error" -> DBUS_MESSAGE_TYPE_ERROR
4543 * anything else -> DBUS_MESSAGE_TYPE_INVALID
4548 dbus_message_type_from_string (const char *type_str)
4550 if (strcmp (type_str, "method_call") == 0)
4551 return DBUS_MESSAGE_TYPE_METHOD_CALL;
4552 if (strcmp (type_str, "method_return") == 0)
4553 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
4554 else if (strcmp (type_str, "signal") == 0)
4555 return DBUS_MESSAGE_TYPE_SIGNAL;
4556 else if (strcmp (type_str, "error") == 0)
4557 return DBUS_MESSAGE_TYPE_ERROR;
4559 return DBUS_MESSAGE_TYPE_INVALID;
4563 * Utility function to convert a D-Bus message type into a
4564 * machine-readable string (not translated).
4567 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
4568 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
4569 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
4570 * DBUS_MESSAGE_TYPE_ERROR -> "error"
4571 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
4576 dbus_message_type_to_string (int type)
4580 case DBUS_MESSAGE_TYPE_METHOD_CALL:
4581 return "method_call";
4582 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
4583 return "method_return";
4584 case DBUS_MESSAGE_TYPE_SIGNAL:
4586 case DBUS_MESSAGE_TYPE_ERROR:
4594 * Turn a DBusMessage into the marshalled form as described in the D-Bus
4597 * Generally, this function is only useful for encapsulating D-Bus messages in
4598 * a different protocol.
4600 * @param msg the DBusMessage
4601 * @param marshalled_data_p the location to save the marshalled form to
4602 * @param len_p the location to save the length of the marshalled form to
4603 * @returns #FALSE if there was not enough memory
4606 dbus_message_marshal (DBusMessage *msg,
4607 char **marshalled_data_p,
4611 dbus_bool_t was_locked;
4613 _dbus_return_val_if_fail (msg != NULL, FALSE);
4614 _dbus_return_val_if_fail (marshalled_data_p != NULL, FALSE);
4615 _dbus_return_val_if_fail (len_p != NULL, FALSE);
4617 if (!_dbus_string_init (&tmp))
4620 /* Ensure the message is locked, to ensure the length header is filled in. */
4621 was_locked = msg->locked;
4624 dbus_message_lock (msg);
4626 if (!_dbus_string_copy (&(msg->header.data), 0, &tmp, 0))
4629 *len_p = _dbus_string_get_length (&tmp);
4631 if (!_dbus_string_copy (&(msg->body), 0, &tmp, *len_p))
4634 *len_p = _dbus_string_get_length (&tmp);
4636 if (!_dbus_string_steal_data (&tmp, marshalled_data_p))
4639 _dbus_string_free (&tmp);
4642 msg->locked = FALSE;
4647 _dbus_string_free (&tmp);
4650 msg->locked = FALSE;
4656 * Demarshal a D-Bus message from the format described in the D-Bus
4659 * Generally, this function is only useful for encapsulating D-Bus messages in
4660 * a different protocol.
4662 * @param str the marshalled DBusMessage
4663 * @param len the length of str
4664 * @param error the location to save errors to
4665 * @returns #NULL if there was an error
4668 dbus_message_demarshal (const char *str,
4672 DBusMessageLoader *loader;
4676 _dbus_return_val_if_fail (str != NULL, NULL);
4678 loader = _dbus_message_loader_new ();
4683 _dbus_message_loader_get_buffer (loader, &buffer);
4684 _dbus_string_append_len (buffer, str, len);
4685 _dbus_message_loader_return_buffer (loader, buffer, len);
4687 if (!_dbus_message_loader_queue_messages (loader))
4690 if (_dbus_message_loader_get_is_corrupted (loader))
4693 msg = _dbus_message_loader_pop_message (loader);
4698 _dbus_message_loader_unref (loader);
4702 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS, "Message is corrupted (%s)",
4703 _dbus_validity_to_error_message (loader->corruption_reason));
4704 _dbus_message_loader_unref (loader);
4708 _DBUS_SET_OOM (error);
4709 _dbus_message_loader_unref (loader);
4714 * Returns the number of bytes required to be in the buffer to demarshal a
4717 * Generally, this function is only useful for encapsulating D-Bus messages in
4718 * a different protocol.
4720 * @param str data to be marshalled
4721 * @param len the length of str
4722 * @param error the location to save errors to
4723 * @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
4727 dbus_message_demarshal_bytes_needed(const char *buf,
4731 int byte_order, fields_array_len, header_len, body_len;
4732 DBusValidity validity = DBUS_VALID;
4735 if (!buf || len < DBUS_MINIMUM_HEADER_SIZE)
4738 if (len > DBUS_MAXIMUM_MESSAGE_LENGTH)
4739 len = DBUS_MAXIMUM_MESSAGE_LENGTH;
4740 _dbus_string_init_const_len (&str, buf, len);
4742 validity = DBUS_VALID;
4744 = _dbus_header_have_message_untrusted(DBUS_MAXIMUM_MESSAGE_LENGTH,
4745 &validity, &byte_order,
4751 _dbus_string_free (&str);
4753 if (validity == DBUS_VALID)
4755 _dbus_assert (have_message || (header_len + body_len) > len);
4756 (void) have_message; /* unused unless asserting */
4757 return header_len + body_len;
4761 return -1; /* broken! */
4767 /* tests in dbus-message-util.c */