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 static void dbus_message_finalize (DBusMessage *message);
46 * @defgroup DBusMessageInternals DBusMessage implementation details
47 * @ingroup DBusInternals
48 * @brief DBusMessage private implementation details.
50 * The guts of DBusMessage and its methods.
55 /* Not thread locked, but strictly const/read-only so should be OK
57 /** An static string representing an empty signature */
58 _DBUS_STRING_DEFINE_STATIC(_dbus_empty_signature_str, "");
60 /* these have wacky values to help trap uninitialized iterators;
61 * but has to fit in 3 bits
64 DBUS_MESSAGE_ITER_TYPE_READER = 3,
65 DBUS_MESSAGE_ITER_TYPE_WRITER = 7
68 /** typedef for internals of message iterator */
69 typedef struct DBusMessageRealIter DBusMessageRealIter;
72 * @brief Internals of DBusMessageIter
74 * Object representing a position in a message. All fields are internal.
76 struct DBusMessageRealIter
78 DBusMessage *message; /**< Message used */
79 dbus_uint32_t changed_stamp : CHANGED_STAMP_BITS; /**< stamp to detect invalid iters */
80 dbus_uint32_t iter_type : 3; /**< whether this is a reader or writer iter */
81 dbus_uint32_t sig_refcount : 8; /**< depth of open_signature() */
84 DBusTypeWriter writer; /**< writer */
85 DBusTypeReader reader; /**< reader */
86 } u; /**< the type writer or reader that does all the work */
90 get_const_signature (DBusHeader *header,
91 const DBusString **type_str_p,
94 if (_dbus_header_get_field_raw (header,
95 DBUS_HEADER_FIELD_SIGNATURE,
99 *type_pos_p += 1; /* skip the signature length which is 1 byte */
103 *type_str_p = &_dbus_empty_signature_str;
109 * Swaps the message to compiler byte order if required
111 * @param message the message
114 _dbus_message_byteswap (DBusMessage *message)
116 const DBusString *type_str;
120 byte_order = _dbus_header_get_byte_order (&message->header);
122 if (byte_order == DBUS_COMPILER_BYTE_ORDER)
125 _dbus_verbose ("Swapping message into compiler byte order\n");
127 get_const_signature (&message->header, &type_str, &type_pos);
129 _dbus_marshal_byteswap (type_str, type_pos,
131 DBUS_COMPILER_BYTE_ORDER,
134 _dbus_header_byteswap (&message->header, DBUS_COMPILER_BYTE_ORDER);
135 _dbus_assert (_dbus_header_get_byte_order (&message->header) ==
136 DBUS_COMPILER_BYTE_ORDER);
139 /** byte-swap the message if it doesn't match our byte order.
140 * Called only when we need the message in our own byte order,
141 * normally when reading arrays of integers or doubles.
142 * Otherwise should not be called since it would do needless
145 #define ensure_byte_order(message) _dbus_message_byteswap (message)
148 * Gets the data to be sent over the network for this message.
149 * The header and then the body should be written out.
150 * This function is guaranteed to always return the same
151 * data once a message is locked (with dbus_message_lock()).
153 * @param message the message.
154 * @param header return location for message header data.
155 * @param body return location for message body data.
158 _dbus_message_get_network_data (DBusMessage *message,
159 const DBusString **header,
160 const DBusString **body)
162 _dbus_assert (message->locked);
164 *header = &message->header.data;
165 *body = &message->body;
169 * Gets the unix fds to be sent over the network for this message.
170 * This function is guaranteed to always return the same data once a
171 * message is locked (with dbus_message_lock()).
173 * @param message the message.
174 * @param fds return location of unix fd array
175 * @param n_fds return number of entries in array
177 void _dbus_message_get_unix_fds(DBusMessage *message,
181 _dbus_assert (message->locked);
183 #ifdef HAVE_UNIX_FD_PASSING
184 *fds = message->unix_fds;
185 *n_fds = message->n_unix_fds;
193 * Sets the serial number of a message.
194 * This can only be done once on a message.
196 * DBusConnection will automatically set the serial to an appropriate value
197 * when the message is sent; this function is only needed when encapsulating
198 * messages in another protocol, or otherwise bypassing DBusConnection.
200 * @param message the message
201 * @param serial the serial
204 dbus_message_set_serial (DBusMessage *message,
205 dbus_uint32_t serial)
207 _dbus_return_if_fail (message != NULL);
208 _dbus_return_if_fail (!message->locked);
210 _dbus_header_set_serial (&message->header, serial);
214 * Adds a counter to be incremented immediately with the size/unix fds
215 * of this message, and decremented by the size/unix fds of this
216 * message when this message if finalized. The link contains a
217 * counter with its refcount already incremented, but the counter
218 * itself not incremented. Ownership of link and counter refcount is
219 * passed to the message.
221 * This function may be called with locks held. As a result, the counter's
222 * notify function is not called; the caller is expected to either call
223 * _dbus_counter_notify() on the counter when they are no longer holding
224 * locks, or take the same action that would be taken by the notify function.
226 * @param message the message
227 * @param link link with counter as data
230 _dbus_message_add_counter_link (DBusMessage *message,
233 /* right now we don't recompute the delta when message
234 * size changes, and that's OK for current purposes
235 * I think, but could be important to change later.
236 * Do recompute it whenever there are no outstanding counters,
237 * since it's basically free.
239 if (message->counters == NULL)
241 message->size_counter_delta =
242 _dbus_string_get_length (&message->header.data) +
243 _dbus_string_get_length (&message->body);
245 #ifdef HAVE_UNIX_FD_PASSING
246 message->unix_fd_counter_delta = message->n_unix_fds;
250 _dbus_verbose ("message has size %ld\n",
251 message->size_counter_delta);
255 _dbus_list_append_link (&message->counters, link);
257 _dbus_counter_adjust_size (link->data, message->size_counter_delta);
259 #ifdef HAVE_UNIX_FD_PASSING
260 _dbus_counter_adjust_unix_fd (link->data, message->unix_fd_counter_delta);
265 * Adds a counter to be incremented immediately with the size/unix fds
266 * of this message, and decremented by the size/unix fds of this
267 * message when this message if finalized.
269 * This function may be called with locks held. As a result, the counter's
270 * notify function is not called; the caller is expected to either call
271 * _dbus_counter_notify() on the counter when they are no longer holding
272 * locks, or take the same action that would be taken by the notify function.
274 * @param message the message
275 * @param counter the counter
276 * @returns #FALSE if no memory
279 _dbus_message_add_counter (DBusMessage *message,
280 DBusCounter *counter)
284 link = _dbus_list_alloc_link (counter);
288 _dbus_counter_ref (counter);
289 _dbus_message_add_counter_link (message, link);
295 * Removes a counter tracking the size/unix fds of this message, and
296 * decrements the counter by the size/unix fds of this message.
298 * @param message the message
299 * @param counter the counter
302 _dbus_message_remove_counter (DBusMessage *message,
303 DBusCounter *counter)
307 link = _dbus_list_find_last (&message->counters,
309 _dbus_assert (link != NULL);
311 _dbus_list_remove_link (&message->counters, link);
313 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
315 #ifdef HAVE_UNIX_FD_PASSING
316 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
319 _dbus_counter_notify (counter);
320 _dbus_counter_unref (counter);
324 * Locks a message. Allows checking that applications don't keep a
325 * reference to a message in the outgoing queue and change it
326 * underneath us. Messages are locked when they enter the outgoing
327 * queue (dbus_connection_send_message()), and the library complains
328 * if the message is modified while locked. This function may also
329 * called externally, for applications wrapping D-Bus in another protocol.
331 * @param message the message to lock.
334 dbus_message_lock (DBusMessage *message)
336 if (!message->locked)
338 _dbus_header_update_lengths (&message->header,
339 _dbus_string_get_length (&message->body));
341 /* must have a signature if you have a body */
342 _dbus_assert (_dbus_string_get_length (&message->body) == 0 ||
343 dbus_message_get_signature (message) != NULL);
345 message->locked = TRUE;
350 set_or_delete_string_field (DBusMessage *message,
356 return _dbus_header_delete_field (&message->header, field);
358 return _dbus_header_set_field_basic (&message->header,
365 /* Probably we don't need to use this */
367 * Sets the signature of the message, i.e. the arguments in the
368 * message payload. The signature includes only "in" arguments for
369 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
370 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
371 * what you might expect (it does not include the signature of the
372 * entire C++-style method).
374 * The signature is a string made up of type codes such as
375 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
376 * the value of #DBUS_TYPE_INVALID). The macros such as
377 * #DBUS_TYPE_INT32 evaluate to integers; to assemble a signature you
378 * may find it useful to use the string forms, such as
379 * #DBUS_TYPE_INT32_AS_STRING.
381 * An "unset" or #NULL signature is considered the same as an empty
382 * signature. In fact dbus_message_get_signature() will never return
385 * @param message the message
386 * @param signature the type signature or #NULL to unset
387 * @returns #FALSE if no memory
390 _dbus_message_set_signature (DBusMessage *message,
391 const char *signature)
393 _dbus_return_val_if_fail (message != NULL, FALSE);
394 _dbus_return_val_if_fail (!message->locked, FALSE);
395 _dbus_return_val_if_fail (signature == NULL ||
396 _dbus_check_is_valid_signature (signature));
397 /* can't delete the signature if you have a message body */
398 _dbus_return_val_if_fail (_dbus_string_get_length (&message->body) == 0 ||
401 return set_or_delete_string_field (message,
402 DBUS_HEADER_FIELD_SIGNATURE,
410 * We cache some DBusMessage to reduce the overhead of allocating
411 * them. In my profiling this consistently made about an 8%
412 * difference. It avoids the malloc for the message, the malloc for
413 * the slot list, the malloc for the header string and body string,
414 * and the associated free() calls. It does introduce another global
415 * lock which could be a performance issue in certain cases.
417 * For the echo client/server the round trip time goes from around
418 * .000077 to .000069 with the message cache on my laptop. The sysprof
419 * change is as follows (numbers are cumulative percentage):
421 * with message cache implemented as array as it is now (0.000069 per):
422 * new_empty_header 1.46
423 * mutex_lock 0.56 # i.e. _DBUS_LOCK(message_cache)
429 * mutex_lock 0.33 # i.e. _DBUS_LOCK(message_cache)
432 * with message cache implemented as list (0.000070 per roundtrip):
433 * new_empty_header 2.72
434 * list_pop_first 1.88
438 * without cache (0.000077 per roundtrip):
439 * new_empty_header 6.7
440 * string_init_preallocated 3.43
449 * If you implement the message_cache with a list, the primary reason
450 * it's slower is that you add another thread lock (on the DBusList
454 /** Avoid caching huge messages */
455 #define MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE
457 /** Avoid caching too many messages */
458 #define MAX_MESSAGE_CACHE_SIZE 5
460 _DBUS_DEFINE_GLOBAL_LOCK (message_cache);
461 static DBusMessage *message_cache[MAX_MESSAGE_CACHE_SIZE];
462 static int message_cache_count = 0;
463 static dbus_bool_t message_cache_shutdown_registered = FALSE;
466 dbus_message_cache_shutdown (void *data)
470 _DBUS_LOCK (message_cache);
473 while (i < MAX_MESSAGE_CACHE_SIZE)
475 if (message_cache[i])
476 dbus_message_finalize (message_cache[i]);
481 message_cache_count = 0;
482 message_cache_shutdown_registered = FALSE;
484 _DBUS_UNLOCK (message_cache);
488 * Tries to get a message from the message cache. The retrieved
489 * message will have junk in it, so it still needs to be cleared out
490 * in dbus_message_new_empty_header()
492 * @returns the message, or #NULL if none cached
495 dbus_message_get_cached (void)
497 DBusMessage *message;
502 _DBUS_LOCK (message_cache);
504 _dbus_assert (message_cache_count >= 0);
506 if (message_cache_count == 0)
508 _DBUS_UNLOCK (message_cache);
512 /* This is not necessarily true unless count > 0, and
513 * message_cache is uninitialized until the shutdown is
516 _dbus_assert (message_cache_shutdown_registered);
519 while (i < MAX_MESSAGE_CACHE_SIZE)
521 if (message_cache[i])
523 message = message_cache[i];
524 message_cache[i] = NULL;
525 message_cache_count -= 1;
530 _dbus_assert (message_cache_count >= 0);
531 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
532 _dbus_assert (message != NULL);
534 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
536 _dbus_assert (message->counters == NULL);
538 _DBUS_UNLOCK (message_cache);
543 #ifdef HAVE_UNIX_FD_PASSING
545 close_unix_fds(int *fds, unsigned *n_fds)
555 for (i = 0; i < *n_fds; i++)
557 if (!_dbus_close(fds[i], &e))
559 _dbus_warn("Failed to close file descriptor: %s\n", e.message);
566 /* We don't free the array here, in case we can recycle it later */
571 free_counter (void *element,
574 DBusCounter *counter = element;
575 DBusMessage *message = data;
577 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
578 #ifdef HAVE_UNIX_FD_PASSING
579 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
582 _dbus_counter_notify (counter);
583 _dbus_counter_unref (counter);
587 * Tries to cache a message, otherwise finalize it.
589 * @param message the message
592 dbus_message_cache_or_finalize (DBusMessage *message)
594 dbus_bool_t was_cached;
597 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
599 /* This calls application code and has to be done first thing
600 * without holding the lock
602 _dbus_data_slot_list_clear (&message->slot_list);
604 _dbus_list_foreach (&message->counters,
605 free_counter, message);
606 _dbus_list_clear (&message->counters);
608 #ifdef HAVE_UNIX_FD_PASSING
609 close_unix_fds(message->unix_fds, &message->n_unix_fds);
614 _DBUS_LOCK (message_cache);
616 if (!message_cache_shutdown_registered)
618 _dbus_assert (message_cache_count == 0);
620 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
624 while (i < MAX_MESSAGE_CACHE_SIZE)
626 message_cache[i] = NULL;
630 message_cache_shutdown_registered = TRUE;
633 _dbus_assert (message_cache_count >= 0);
635 if ((_dbus_string_get_length (&message->header.data) +
636 _dbus_string_get_length (&message->body)) >
637 MAX_MESSAGE_SIZE_TO_CACHE)
640 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
643 /* Find empty slot */
645 while (message_cache[i] != NULL)
648 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
650 _dbus_assert (message_cache[i] == NULL);
651 message_cache[i] = message;
652 message_cache_count += 1;
654 #ifndef DBUS_DISABLE_CHECKS
655 message->in_cache = TRUE;
659 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
661 _DBUS_UNLOCK (message_cache);
664 dbus_message_finalize (message);
667 #ifndef DBUS_DISABLE_CHECKS
669 _dbus_message_iter_check (DBusMessageRealIter *iter)
675 _dbus_warn_check_failed ("dbus message iterator is NULL\n");
679 byte_order = _dbus_header_get_byte_order (&iter->message->header);
681 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
683 if (iter->u.reader.byte_order != byte_order)
685 _dbus_warn_check_failed ("dbus message changed byte order since iterator was created\n");
688 /* because we swap the message into compiler order when you init an iter */
689 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
691 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
693 if (iter->u.writer.byte_order != byte_order)
695 _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created\n");
698 /* because we swap the message into compiler order when you init an iter */
699 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
703 _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted\n");
707 if (iter->changed_stamp != iter->message->changed_stamp)
709 _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
715 #endif /* DBUS_DISABLE_CHECKS */
718 * Implementation of the varargs arg-getting functions.
719 * dbus_message_get_args() is the place to go for complete
722 * @todo This may leak memory and file descriptors if parsing fails. See #21259
724 * @see dbus_message_get_args
725 * @param iter the message iter
726 * @param error error to be filled in
727 * @param first_arg_type type of the first argument
728 * @param var_args return location for first argument, followed by list of type/location pairs
729 * @returns #FALSE if error was set
732 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
737 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
738 int spec_type, msg_type, i;
741 _dbus_assert (_dbus_message_iter_check (real));
745 spec_type = first_arg_type;
748 while (spec_type != DBUS_TYPE_INVALID)
750 msg_type = dbus_message_iter_get_arg_type (iter);
752 if (msg_type != spec_type)
754 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
755 "Argument %d is specified to be of type \"%s\", but "
756 "is actually of type \"%s\"\n", i,
757 _dbus_type_to_string (spec_type),
758 _dbus_type_to_string (msg_type));
763 if (spec_type == DBUS_TYPE_UNIX_FD)
765 #ifdef HAVE_UNIX_FD_PASSING
769 pfd = va_arg (var_args, int*);
772 _dbus_type_reader_read_basic(&real->u.reader, &idx);
774 if (idx.u32 >= real->message->n_unix_fds)
776 dbus_set_error (error, DBUS_ERROR_INCONSISTENT_MESSAGE,
777 "Message refers to file descriptor at index %i,"
778 "but has only %i descriptors attached.\n",
780 real->message->n_unix_fds);
784 if ((nfd = _dbus_dup(real->message->unix_fds[idx.u32], error)) < 0)
789 dbus_set_error (error, DBUS_ERROR_NOT_SUPPORTED,
790 "Platform does not support file desciptor passing.\n");
794 else if (dbus_type_is_basic (spec_type))
798 ptr = va_arg (var_args, DBusBasicValue*);
800 _dbus_assert (ptr != NULL);
802 _dbus_type_reader_read_basic (&real->u.reader,
805 else if (spec_type == DBUS_TYPE_ARRAY)
808 int spec_element_type;
809 const DBusBasicValue **ptr;
811 DBusTypeReader array;
813 spec_element_type = va_arg (var_args, int);
814 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
816 if (spec_element_type != element_type)
818 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
819 "Argument %d is specified to be an array of \"%s\", but "
820 "is actually an array of \"%s\"\n",
822 _dbus_type_to_string (spec_element_type),
823 _dbus_type_to_string (element_type));
828 if (dbus_type_is_fixed (spec_element_type) &&
829 element_type != DBUS_TYPE_UNIX_FD)
831 ptr = va_arg (var_args, const DBusBasicValue**);
832 n_elements_p = va_arg (var_args, int*);
834 _dbus_assert (ptr != NULL);
835 _dbus_assert (n_elements_p != NULL);
837 _dbus_type_reader_recurse (&real->u.reader, &array);
839 _dbus_type_reader_read_fixed_multi (&array,
840 (void *) ptr, n_elements_p);
842 else if (spec_element_type == DBUS_TYPE_STRING ||
843 spec_element_type == DBUS_TYPE_SIGNATURE ||
844 spec_element_type == DBUS_TYPE_OBJECT_PATH)
850 str_array_p = va_arg (var_args, char***);
851 n_elements_p = va_arg (var_args, int*);
853 _dbus_assert (str_array_p != NULL);
854 _dbus_assert (n_elements_p != NULL);
856 /* Count elements in the array */
857 _dbus_type_reader_recurse (&real->u.reader, &array);
860 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
863 _dbus_type_reader_next (&array);
866 str_array = dbus_new0 (char*, n_elements + 1);
867 if (str_array == NULL)
869 _DBUS_SET_OOM (error);
873 /* Now go through and dup each string */
874 _dbus_type_reader_recurse (&real->u.reader, &array);
877 while (i < n_elements)
880 _dbus_type_reader_read_basic (&array,
883 str_array[i] = _dbus_strdup (s);
884 if (str_array[i] == NULL)
886 dbus_free_string_array (str_array);
887 _DBUS_SET_OOM (error);
893 if (!_dbus_type_reader_next (&array))
894 _dbus_assert (i == n_elements);
897 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
898 _dbus_assert (i == n_elements);
899 _dbus_assert (str_array[i] == NULL);
901 *str_array_p = str_array;
902 *n_elements_p = n_elements;
904 #ifndef DBUS_DISABLE_CHECKS
907 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
908 _DBUS_FUNCTION_NAME);
913 #ifndef DBUS_DISABLE_CHECKS
916 _dbus_warn ("you can only read arrays and basic types with %s for now\n",
917 _DBUS_FUNCTION_NAME);
922 spec_type = va_arg (var_args, int);
923 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
925 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
926 "Message has only %d arguments, but more were expected", i);
943 * @defgroup DBusMessage DBusMessage
945 * @brief Message to be sent or received over a #DBusConnection.
947 * A DBusMessage is the most basic unit of communication over a
948 * DBusConnection. A DBusConnection represents a stream of messages
949 * received from a remote application, and a stream of messages
950 * sent to a remote application.
952 * A message has a message type, returned from
953 * dbus_message_get_type(). This indicates whether the message is a
954 * method call, a reply to a method call, a signal, or an error reply.
956 * A message has header fields such as the sender, destination, method
957 * or signal name, and so forth. DBusMessage has accessor functions for
958 * these, such as dbus_message_get_member().
960 * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
961 * and dbus_message_is_error() check several header fields at once and are
962 * slightly more efficient than checking the header fields with individual
963 * accessor functions.
965 * Finally, a message has arguments. The number and types of arguments
966 * are in the message's signature header field (accessed with
967 * dbus_message_get_signature()). Simple argument values are usually
968 * retrieved with dbus_message_get_args() but more complex values such
969 * as structs may require the use of #DBusMessageIter.
971 * The D-Bus specification goes into some more detail about header fields and
978 * @typedef DBusMessage
980 * Opaque data type representing a message received from or to be
981 * sent to another application.
985 * Returns the serial of a message or 0 if none has been specified.
986 * The message's serial number is provided by the application sending
987 * the message and is used to identify replies to this message.
989 * All messages received on a connection will have a serial provided
990 * by the remote application.
992 * For messages you're sending, dbus_connection_send() will assign a
993 * serial and return it to you.
995 * @param message the message
996 * @returns the serial
999 dbus_message_get_serial (DBusMessage *message)
1001 _dbus_return_val_if_fail (message != NULL, 0);
1003 return _dbus_header_get_serial (&message->header);
1007 * Sets the reply serial of a message (the serial of the message this
1010 * @param message the message
1011 * @param reply_serial the serial we're replying to
1012 * @returns #FALSE if not enough memory
1015 dbus_message_set_reply_serial (DBusMessage *message,
1016 dbus_uint32_t reply_serial)
1018 _dbus_return_val_if_fail (message != NULL, FALSE);
1019 _dbus_return_val_if_fail (!message->locked, FALSE);
1020 _dbus_return_val_if_fail (reply_serial != 0, FALSE); /* 0 is invalid */
1022 return _dbus_header_set_field_basic (&message->header,
1023 DBUS_HEADER_FIELD_REPLY_SERIAL,
1029 * Returns the serial that the message is a reply to or 0 if none.
1031 * @param message the message
1032 * @returns the reply serial
1035 dbus_message_get_reply_serial (DBusMessage *message)
1037 dbus_uint32_t v_UINT32;
1039 _dbus_return_val_if_fail (message != NULL, 0);
1041 if (_dbus_header_get_field_basic (&message->header,
1042 DBUS_HEADER_FIELD_REPLY_SERIAL,
1051 dbus_message_finalize (DBusMessage *message)
1053 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1055 /* This calls application callbacks! */
1056 _dbus_data_slot_list_free (&message->slot_list);
1058 _dbus_list_foreach (&message->counters,
1059 free_counter, message);
1060 _dbus_list_clear (&message->counters);
1062 _dbus_header_free (&message->header);
1063 _dbus_string_free (&message->body);
1065 #ifdef HAVE_UNIX_FD_PASSING
1066 close_unix_fds(message->unix_fds, &message->n_unix_fds);
1067 dbus_free(message->unix_fds);
1070 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1072 dbus_free (message);
1076 dbus_message_new_empty_header (void)
1078 DBusMessage *message;
1079 dbus_bool_t from_cache;
1081 message = dbus_message_get_cached ();
1083 if (message != NULL)
1090 message = dbus_new0 (DBusMessage, 1);
1091 if (message == NULL)
1093 #ifndef DBUS_DISABLE_CHECKS
1094 message->generation = _dbus_current_generation;
1097 #ifdef HAVE_UNIX_FD_PASSING
1098 message->unix_fds = NULL;
1099 message->n_unix_fds_allocated = 0;
1103 _dbus_atomic_inc (&message->refcount);
1105 message->locked = FALSE;
1106 #ifndef DBUS_DISABLE_CHECKS
1107 message->in_cache = FALSE;
1109 message->counters = NULL;
1110 message->size_counter_delta = 0;
1111 message->changed_stamp = 0;
1113 #ifdef HAVE_UNIX_FD_PASSING
1114 message->n_unix_fds = 0;
1115 message->n_unix_fds_allocated = 0;
1116 message->unix_fd_counter_delta = 0;
1120 _dbus_data_slot_list_init (&message->slot_list);
1124 _dbus_header_reinit (&message->header);
1125 _dbus_string_set_length (&message->body, 0);
1129 if (!_dbus_header_init (&message->header))
1131 dbus_free (message);
1135 if (!_dbus_string_init_preallocated (&message->body, 32))
1137 _dbus_header_free (&message->header);
1138 dbus_free (message);
1147 * Constructs a new message of the given message type.
1148 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
1149 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
1151 * Usually you want to use dbus_message_new_method_call(),
1152 * dbus_message_new_method_return(), dbus_message_new_signal(),
1153 * or dbus_message_new_error() instead.
1155 * @param message_type type of message
1156 * @returns new message or #NULL if no memory
1159 dbus_message_new (int message_type)
1161 DBusMessage *message;
1163 _dbus_return_val_if_fail (message_type != DBUS_MESSAGE_TYPE_INVALID, NULL);
1165 message = dbus_message_new_empty_header ();
1166 if (message == NULL)
1169 if (!_dbus_header_create (&message->header,
1170 DBUS_COMPILER_BYTE_ORDER,
1172 NULL, NULL, NULL, NULL, NULL))
1174 dbus_message_unref (message);
1182 * Constructs a new message to invoke a method on a remote
1183 * object. Returns #NULL if memory can't be allocated for the
1184 * message. The destination may be #NULL in which case no destination
1185 * is set; this is appropriate when using D-Bus in a peer-to-peer
1186 * context (no message bus). The interface may be #NULL, which means
1187 * that if multiple methods with the given name exist it is undefined
1188 * which one will be invoked.
1190 * The path and method names may not be #NULL.
1192 * Destination, path, interface, and method name can't contain
1193 * any invalid characters (see the D-Bus specification).
1195 * @param destination name that the message should be sent to or #NULL
1196 * @param path object path the message should be sent to
1197 * @param interface interface to invoke method on, or #NULL
1198 * @param method method to invoke
1200 * @returns a new DBusMessage, free with dbus_message_unref()
1203 dbus_message_new_method_call (const char *destination,
1205 const char *interface,
1208 DBusMessage *message;
1210 _dbus_return_val_if_fail (path != NULL, NULL);
1211 _dbus_return_val_if_fail (method != NULL, NULL);
1212 _dbus_return_val_if_fail (destination == NULL ||
1213 _dbus_check_is_valid_bus_name (destination), NULL);
1214 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1215 _dbus_return_val_if_fail (interface == NULL ||
1216 _dbus_check_is_valid_interface (interface), NULL);
1217 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
1219 message = dbus_message_new_empty_header ();
1220 if (message == NULL)
1223 if (!_dbus_header_create (&message->header,
1224 DBUS_COMPILER_BYTE_ORDER,
1225 DBUS_MESSAGE_TYPE_METHOD_CALL,
1226 destination, path, interface, method, NULL))
1228 dbus_message_unref (message);
1236 * Constructs a message that is a reply to a method call. Returns
1237 * #NULL if memory can't be allocated for the message.
1239 * @param method_call the message being replied to
1240 * @returns a new DBusMessage, free with dbus_message_unref()
1243 dbus_message_new_method_return (DBusMessage *method_call)
1245 DBusMessage *message;
1248 _dbus_return_val_if_fail (method_call != NULL, NULL);
1250 sender = dbus_message_get_sender (method_call);
1252 /* sender is allowed to be null here in peer-to-peer case */
1254 message = dbus_message_new_empty_header ();
1255 if (message == NULL)
1258 if (!_dbus_header_create (&message->header,
1259 DBUS_COMPILER_BYTE_ORDER,
1260 DBUS_MESSAGE_TYPE_METHOD_RETURN,
1261 sender, NULL, NULL, NULL, NULL))
1263 dbus_message_unref (message);
1267 dbus_message_set_no_reply (message, TRUE);
1269 if (!dbus_message_set_reply_serial (message,
1270 dbus_message_get_serial (method_call)))
1272 dbus_message_unref (message);
1280 * Constructs a new message representing a signal emission. Returns
1281 * #NULL if memory can't be allocated for the message. A signal is
1282 * identified by its originating object path, interface, and the name
1285 * Path, interface, and signal name must all be valid (the D-Bus
1286 * specification defines the syntax of these fields).
1288 * @param path the path to the object emitting the signal
1289 * @param interface the interface the signal is emitted from
1290 * @param name name of the signal
1291 * @returns a new DBusMessage, free with dbus_message_unref()
1294 dbus_message_new_signal (const char *path,
1295 const char *interface,
1298 DBusMessage *message;
1300 _dbus_return_val_if_fail (path != NULL, NULL);
1301 _dbus_return_val_if_fail (interface != NULL, NULL);
1302 _dbus_return_val_if_fail (name != NULL, NULL);
1303 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1304 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (interface), NULL);
1305 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
1307 message = dbus_message_new_empty_header ();
1308 if (message == NULL)
1311 if (!_dbus_header_create (&message->header,
1312 DBUS_COMPILER_BYTE_ORDER,
1313 DBUS_MESSAGE_TYPE_SIGNAL,
1314 NULL, path, interface, name, NULL))
1316 dbus_message_unref (message);
1320 dbus_message_set_no_reply (message, TRUE);
1326 * Creates a new message that is an error reply to another message.
1327 * Error replies are most common in response to method calls, but
1328 * can be returned in reply to any message.
1330 * The error name must be a valid error name according to the syntax
1331 * given in the D-Bus specification. If you don't want to make
1332 * up an error name just use #DBUS_ERROR_FAILED.
1334 * @param reply_to the message we're replying to
1335 * @param error_name the error name
1336 * @param error_message the error message string (or #NULL for none, but please give a message)
1337 * @returns a new error message object, free with dbus_message_unref()
1340 dbus_message_new_error (DBusMessage *reply_to,
1341 const char *error_name,
1342 const char *error_message)
1344 DBusMessage *message;
1346 DBusMessageIter iter;
1348 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1349 _dbus_return_val_if_fail (error_name != NULL, NULL);
1350 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1352 sender = dbus_message_get_sender (reply_to);
1354 /* sender may be NULL for non-message-bus case or
1355 * when the message bus is dealing with an unregistered
1358 message = dbus_message_new_empty_header ();
1359 if (message == NULL)
1362 if (!_dbus_header_create (&message->header,
1363 DBUS_COMPILER_BYTE_ORDER,
1364 DBUS_MESSAGE_TYPE_ERROR,
1365 sender, NULL, NULL, NULL, error_name))
1367 dbus_message_unref (message);
1371 dbus_message_set_no_reply (message, TRUE);
1373 if (!dbus_message_set_reply_serial (message,
1374 dbus_message_get_serial (reply_to)))
1376 dbus_message_unref (message);
1380 if (error_message != NULL)
1382 dbus_message_iter_init_append (message, &iter);
1383 if (!dbus_message_iter_append_basic (&iter,
1387 dbus_message_unref (message);
1396 * Creates a new message that is an error reply to another message, allowing
1397 * you to use printf formatting.
1399 * See dbus_message_new_error() for details - this function is the same
1400 * aside from the printf formatting.
1402 * @todo add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to
1403 * public header, see DBUS_DEPRECATED for an example)
1405 * @param reply_to the original message
1406 * @param error_name the error name
1407 * @param error_format the error message format as with printf
1408 * @param ... format string arguments
1409 * @returns a new error message
1412 dbus_message_new_error_printf (DBusMessage *reply_to,
1413 const char *error_name,
1414 const char *error_format,
1419 DBusMessage *message;
1421 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1422 _dbus_return_val_if_fail (error_name != NULL, NULL);
1423 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1425 if (!_dbus_string_init (&str))
1428 va_start (args, error_format);
1430 if (_dbus_string_append_printf_valist (&str, error_format, args))
1431 message = dbus_message_new_error (reply_to, error_name,
1432 _dbus_string_get_const_data (&str));
1436 _dbus_string_free (&str);
1445 * Creates a new message that is an exact replica of the message
1446 * specified, except that its refcount is set to 1, its message serial
1447 * is reset to 0, and if the original message was "locked" (in the
1448 * outgoing message queue and thus not modifiable) the new message
1449 * will not be locked.
1451 * @todo This function can't be used in programs that try to recover from OOM errors.
1453 * @param message the message
1454 * @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.
1457 dbus_message_copy (const DBusMessage *message)
1459 DBusMessage *retval;
1461 _dbus_return_val_if_fail (message != NULL, NULL);
1463 retval = dbus_new0 (DBusMessage, 1);
1467 _dbus_atomic_inc (&retval->refcount);
1469 retval->locked = FALSE;
1470 #ifndef DBUS_DISABLE_CHECKS
1471 retval->generation = message->generation;
1474 if (!_dbus_header_copy (&message->header, &retval->header))
1480 if (!_dbus_string_init_preallocated (&retval->body,
1481 _dbus_string_get_length (&message->body)))
1483 _dbus_header_free (&retval->header);
1488 if (!_dbus_string_copy (&message->body, 0,
1492 #ifdef HAVE_UNIX_FD_PASSING
1493 retval->unix_fds = dbus_new(int, message->n_unix_fds);
1494 if (retval->unix_fds == NULL && message->n_unix_fds > 0)
1497 retval->n_unix_fds_allocated = message->n_unix_fds;
1499 for (retval->n_unix_fds = 0;
1500 retval->n_unix_fds < message->n_unix_fds;
1501 retval->n_unix_fds++)
1503 retval->unix_fds[retval->n_unix_fds] = _dbus_dup(message->unix_fds[retval->n_unix_fds], NULL);
1505 if (retval->unix_fds[retval->n_unix_fds] < 0)
1514 _dbus_header_free (&retval->header);
1515 _dbus_string_free (&retval->body);
1517 #ifdef HAVE_UNIX_FD_PASSING
1518 close_unix_fds(retval->unix_fds, &retval->n_unix_fds);
1519 dbus_free(retval->unix_fds);
1529 * Increments the reference count of a DBusMessage.
1531 * @param message the message
1532 * @returns the message
1533 * @see dbus_message_unref
1536 dbus_message_ref (DBusMessage *message)
1538 #ifndef DBUS_DISABLE_ASSERT
1539 dbus_int32_t old_refcount;
1542 _dbus_return_val_if_fail (message != NULL, NULL);
1543 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1544 _dbus_return_val_if_fail (!message->in_cache, NULL);
1546 #ifdef DBUS_DISABLE_ASSERT
1547 _dbus_atomic_inc (&message->refcount);
1549 old_refcount = _dbus_atomic_inc (&message->refcount);
1550 _dbus_assert (old_refcount >= 1);
1557 * Decrements the reference count of a DBusMessage, freeing the
1558 * message if the count reaches 0.
1560 * @param message the message
1561 * @see dbus_message_ref
1564 dbus_message_unref (DBusMessage *message)
1566 dbus_int32_t old_refcount;
1568 _dbus_return_if_fail (message != NULL);
1569 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1570 _dbus_return_if_fail (!message->in_cache);
1572 old_refcount = _dbus_atomic_dec (&message->refcount);
1574 _dbus_assert (old_refcount >= 1);
1576 if (old_refcount == 1)
1578 /* Calls application callbacks! */
1579 dbus_message_cache_or_finalize (message);
1584 * Gets the type of a message. Types include
1585 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1586 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1587 * types are allowed and all code must silently ignore messages of
1588 * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
1590 * @param message the message
1591 * @returns the type of the message
1594 dbus_message_get_type (DBusMessage *message)
1596 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1598 return _dbus_header_get_message_type (&message->header);
1602 * Appends fields to a message given a variable argument list. The
1603 * variable argument list should contain the type of each argument
1604 * followed by the value to append. Appendable types are basic types,
1605 * and arrays of fixed-length basic types (except arrays of Unix file
1606 * descriptors). To append variable-length basic types, or any more
1607 * complex value, you have to use an iterator rather than this
1610 * To append a basic type, specify its type code followed by the
1611 * address of the value. For example:
1615 * dbus_int32_t v_INT32 = 42;
1616 * const char *v_STRING = "Hello World";
1617 * dbus_message_append_args (message,
1618 * DBUS_TYPE_INT32, &v_INT32,
1619 * DBUS_TYPE_STRING, &v_STRING,
1620 * DBUS_TYPE_INVALID);
1623 * To append an array of fixed-length basic types (except Unix file
1624 * descriptors), pass in the DBUS_TYPE_ARRAY typecode, the element
1625 * typecode, the address of the array pointer, and a 32-bit integer
1626 * giving the number of elements in the array. So for example: @code
1627 * const dbus_int32_t array[] = { 1, 2, 3 }; const dbus_int32_t
1628 * *v_ARRAY = array; dbus_message_append_args (message,
1629 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3, DBUS_TYPE_INVALID);
1632 * This function does not support arrays of Unix file descriptors. If
1633 * you need those you need to manually recurse into the array.
1635 * For Unix file descriptors this function will internally duplicate
1636 * the descriptor you passed in. Hence you may close the descriptor
1637 * immediately after this call.
1639 * @warning in C, given "int array[]", "&array == array" (the
1640 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
1641 * So if you're using an array instead of a pointer you have to create
1642 * a pointer variable, assign the array to it, then take the address
1643 * of the pointer variable. For strings it works to write
1644 * const char *array = "Hello" and then use &array though.
1646 * The last argument to this function must be #DBUS_TYPE_INVALID,
1647 * marking the end of the argument list. If you don't do this
1648 * then libdbus won't know to stop and will read invalid memory.
1650 * String/signature/path arrays should be passed in as "const char***
1651 * address_of_array" and "int n_elements"
1653 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1655 * @todo If this fails due to lack of memory, the message is hosed and
1656 * you have to start over building the whole message.
1658 * @param message the message
1659 * @param first_arg_type type of the first argument
1660 * @param ... value of first argument, list of additional type-value pairs
1661 * @returns #TRUE on success
1664 dbus_message_append_args (DBusMessage *message,
1671 _dbus_return_val_if_fail (message != NULL, FALSE);
1673 va_start (var_args, first_arg_type);
1674 retval = dbus_message_append_args_valist (message,
1683 * Like dbus_message_append_args() but takes a va_list for use by language bindings.
1685 * @todo for now, if this function fails due to OOM it will leave
1686 * the message half-written and you have to discard the message
1689 * @see dbus_message_append_args.
1690 * @param message the message
1691 * @param first_arg_type type of first argument
1692 * @param var_args value of first argument, then list of type/value pairs
1693 * @returns #TRUE on success
1696 dbus_message_append_args_valist (DBusMessage *message,
1701 DBusMessageIter iter;
1703 _dbus_return_val_if_fail (message != NULL, FALSE);
1705 type = first_arg_type;
1707 dbus_message_iter_init_append (message, &iter);
1709 while (type != DBUS_TYPE_INVALID)
1711 if (dbus_type_is_basic (type))
1713 const DBusBasicValue *value;
1714 value = va_arg (var_args, const DBusBasicValue*);
1716 if (!dbus_message_iter_append_basic (&iter,
1721 else if (type == DBUS_TYPE_ARRAY)
1724 DBusMessageIter array;
1727 element_type = va_arg (var_args, int);
1729 buf[0] = element_type;
1731 if (!dbus_message_iter_open_container (&iter,
1737 if (dbus_type_is_fixed (element_type) &&
1738 element_type != DBUS_TYPE_UNIX_FD)
1740 const DBusBasicValue **value;
1743 value = va_arg (var_args, const DBusBasicValue**);
1744 n_elements = va_arg (var_args, int);
1746 if (!dbus_message_iter_append_fixed_array (&array,
1750 dbus_message_iter_abandon_container (&iter, &array);
1754 else if (element_type == DBUS_TYPE_STRING ||
1755 element_type == DBUS_TYPE_SIGNATURE ||
1756 element_type == DBUS_TYPE_OBJECT_PATH)
1758 const char ***value_p;
1763 value_p = va_arg (var_args, const char***);
1764 n_elements = va_arg (var_args, int);
1769 while (i < n_elements)
1771 if (!dbus_message_iter_append_basic (&array,
1774 dbus_message_iter_abandon_container (&iter, &array);
1782 _dbus_warn ("arrays of %s can't be appended with %s for now\n",
1783 _dbus_type_to_string (element_type),
1784 _DBUS_FUNCTION_NAME);
1788 if (!dbus_message_iter_close_container (&iter, &array))
1791 #ifndef DBUS_DISABLE_CHECKS
1794 _dbus_warn ("type %s isn't supported yet in %s\n",
1795 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
1800 type = va_arg (var_args, int);
1810 * Gets arguments from a message given a variable argument list. The
1811 * supported types include those supported by
1812 * dbus_message_append_args(); that is, basic types and arrays of
1813 * fixed-length basic types. The arguments are the same as they would
1814 * be for dbus_message_iter_get_basic() or
1815 * dbus_message_iter_get_fixed_array().
1817 * In addition to those types, arrays of string, object path, and
1818 * signature are supported; but these are returned as allocated memory
1819 * and must be freed with dbus_free_string_array(), while the other
1820 * types are returned as const references. To get a string array
1821 * pass in "char ***array_location" and "int *n_elements".
1823 * Similar to dbus_message_get_fixed_array() this function does not
1824 * support arrays of type DBUS_TYPE_UNIX_FD. If you need to parse
1825 * messages with arrays of Unix file descriptors you need to recurse
1826 * into the array manually.
1828 * Unix file descriptors that are read with this function will have
1829 * the FD_CLOEXEC flag set. If you need them without this flag set,
1830 * make sure to unset it with fcntl().
1832 * The variable argument list should contain the type of the argument
1833 * followed by a pointer to where the value should be stored. The list
1834 * is terminated with #DBUS_TYPE_INVALID.
1836 * Except for string arrays, the returned values are constant; do not
1837 * free them. They point into the #DBusMessage.
1839 * If the requested arguments are not present, or do not have the
1840 * requested types, then an error will be set.
1842 * If more arguments than requested are present, the requested
1843 * arguments are returned and the extra arguments are ignored.
1845 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1847 * @param message the message
1848 * @param error error to be filled in on failure
1849 * @param first_arg_type the first argument type
1850 * @param ... location for first argument value, then list of type-location pairs
1851 * @returns #FALSE if the error was set
1854 dbus_message_get_args (DBusMessage *message,
1862 _dbus_return_val_if_fail (message != NULL, FALSE);
1863 _dbus_return_val_if_error_is_set (error, FALSE);
1865 va_start (var_args, first_arg_type);
1866 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
1873 * Like dbus_message_get_args but takes a va_list for use by language bindings.
1875 * @see dbus_message_get_args
1876 * @param message the message
1877 * @param error error to be filled in
1878 * @param first_arg_type type of the first argument
1879 * @param var_args return location for first argument, followed by list of type/location pairs
1880 * @returns #FALSE if error was set
1883 dbus_message_get_args_valist (DBusMessage *message,
1888 DBusMessageIter iter;
1890 _dbus_return_val_if_fail (message != NULL, FALSE);
1891 _dbus_return_val_if_error_is_set (error, FALSE);
1893 dbus_message_iter_init (message, &iter);
1894 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
1898 _dbus_message_iter_init_common (DBusMessage *message,
1899 DBusMessageRealIter *real,
1902 _dbus_assert (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
1904 /* Since the iterator will read or write who-knows-what from the
1905 * message, we need to get in the right byte order
1907 ensure_byte_order (message);
1909 real->message = message;
1910 real->changed_stamp = message->changed_stamp;
1911 real->iter_type = iter_type;
1912 real->sig_refcount = 0;
1916 * Initializes a #DBusMessageIter for reading the arguments of the
1917 * message passed in.
1919 * When possible, dbus_message_get_args() is much more convenient.
1920 * Some types of argument can only be read with #DBusMessageIter
1923 * The easiest way to iterate is like this:
1925 * dbus_message_iter_init (message, &iter);
1926 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
1927 * dbus_message_iter_next (&iter);
1930 * #DBusMessageIter contains no allocated memory; it need not be
1931 * freed, and can be copied by assignment or memcpy().
1933 * @param message the message
1934 * @param iter pointer to an iterator to initialize
1935 * @returns #FALSE if the message has no arguments
1938 dbus_message_iter_init (DBusMessage *message,
1939 DBusMessageIter *iter)
1941 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1942 const DBusString *type_str;
1945 _dbus_return_val_if_fail (message != NULL, FALSE);
1946 _dbus_return_val_if_fail (iter != NULL, FALSE);
1948 get_const_signature (&message->header, &type_str, &type_pos);
1950 _dbus_message_iter_init_common (message, real,
1951 DBUS_MESSAGE_ITER_TYPE_READER);
1953 _dbus_type_reader_init (&real->u.reader,
1954 _dbus_header_get_byte_order (&message->header),
1959 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
1963 * Checks if an iterator has any more fields.
1965 * @param iter the message iter
1966 * @returns #TRUE if there are more fields following
1969 dbus_message_iter_has_next (DBusMessageIter *iter)
1971 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1973 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
1974 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
1976 return _dbus_type_reader_has_next (&real->u.reader);
1980 * Moves the iterator to the next field, if any. If there's no next
1981 * field, returns #FALSE. If the iterator moves forward, returns
1984 * @param iter the message iter
1985 * @returns #TRUE if the iterator was moved to the next field
1988 dbus_message_iter_next (DBusMessageIter *iter)
1990 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1992 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
1993 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
1995 return _dbus_type_reader_next (&real->u.reader);
1999 * Returns the argument type of the argument that the message iterator
2000 * points to. If the iterator is at the end of the message, returns
2001 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
2004 * dbus_message_iter_init (message, &iter);
2005 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2006 * dbus_message_iter_next (&iter);
2009 * @param iter the message iter
2010 * @returns the argument type
2013 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
2015 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2017 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2018 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2020 return _dbus_type_reader_get_current_type (&real->u.reader);
2024 * Returns the element type of the array that the message iterator
2025 * points to. Note that you need to check that the iterator points to
2026 * an array prior to using this function.
2028 * @param iter the message iter
2029 * @returns the array element type
2032 dbus_message_iter_get_element_type (DBusMessageIter *iter)
2034 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2036 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2037 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
2038 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
2040 return _dbus_type_reader_get_element_type (&real->u.reader);
2044 * Recurses into a container value when reading values from a message,
2045 * initializing a sub-iterator to use for traversing the child values
2048 * Note that this recurses into a value, not a type, so you can only
2049 * recurse if the value exists. The main implication of this is that
2050 * if you have for example an empty array of array of int32, you can
2051 * recurse into the outermost array, but it will have no values, so
2052 * you won't be able to recurse further. There's no array of int32 to
2055 * If a container is an array of fixed-length types (except Unix file
2056 * descriptors), it is much more efficient to use
2057 * dbus_message_iter_get_fixed_array() to get the whole array in one
2058 * shot, rather than individually walking over the array elements.
2060 * Be sure you have somehow checked that
2061 * dbus_message_iter_get_arg_type() matches the type you are expecting
2062 * to recurse into. Results of this function are undefined if there is
2063 * no container to recurse into at the current iterator position.
2065 * @param iter the message iterator
2066 * @param sub the sub-iterator to initialize
2069 dbus_message_iter_recurse (DBusMessageIter *iter,
2070 DBusMessageIter *sub)
2072 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2073 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2075 _dbus_return_if_fail (_dbus_message_iter_check (real));
2076 _dbus_return_if_fail (sub != NULL);
2079 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
2083 * Returns the current signature of a message iterator. This
2084 * is useful primarily for dealing with variants; one can
2085 * recurse into a variant and determine the signature of
2086 * the variant's value.
2088 * The returned string must be freed with dbus_free().
2090 * @param iter the message iterator
2091 * @returns the contained signature, or NULL if out of memory
2094 dbus_message_iter_get_signature (DBusMessageIter *iter)
2096 const DBusString *sig;
2100 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2102 _dbus_return_val_if_fail (_dbus_message_iter_check (real), NULL);
2104 if (!_dbus_string_init (&retstr))
2107 _dbus_type_reader_get_signature (&real->u.reader, &sig,
2109 if (!_dbus_string_append_len (&retstr,
2110 _dbus_string_get_const_data (sig) + start,
2113 if (!_dbus_string_steal_data (&retstr, &ret))
2115 _dbus_string_free (&retstr);
2120 * Reads a basic-typed value from the message iterator.
2121 * Basic types are the non-containers such as integer and string.
2123 * The value argument should be the address of a location to store
2124 * the returned value. So for int32 it should be a "dbus_int32_t*"
2125 * and for string a "const char**". The returned value is
2126 * by reference and should not be freed.
2128 * This call duplicates Unix file descriptors when reading them. It is
2129 * your job to close them when you don't need them anymore.
2131 * Unix file descriptors that are read with this function will have
2132 * the FD_CLOEXEC flag set. If you need them without this flag set,
2133 * make sure to unset it with fcntl().
2135 * Be sure you have somehow checked that
2136 * dbus_message_iter_get_arg_type() matches the type you are
2137 * expecting, or you'll crash when you try to use an integer as a
2138 * string or something.
2140 * To read any container type (array, struct, dict) you will need to
2141 * recurse into the container with dbus_message_iter_recurse(). If
2142 * the container is an array of fixed-length values (except Unix file
2143 * descriptors), you can get all the array elements at once with
2144 * dbus_message_iter_get_fixed_array(). Otherwise, you have to iterate
2145 * over the container's contents one value at a time.
2147 * All basic-typed values are guaranteed to fit in 8 bytes. So you can
2148 * write code like this:
2151 * dbus_uint64_t value;
2153 * dbus_message_iter_get_basic (&read_iter, &value);
2154 * type = dbus_message_iter_get_arg_type (&read_iter);
2155 * dbus_message_iter_append_basic (&write_iter, type, &value);
2158 * On some really obscure platforms dbus_uint64_t might not exist, if
2159 * you need to worry about this you will know. dbus_uint64_t is just
2160 * one example of a type that's large enough to hold any possible
2161 * value, you could use a struct or char[8] instead if you like.
2163 * @param iter the iterator
2164 * @param value location to store the value
2167 dbus_message_iter_get_basic (DBusMessageIter *iter,
2170 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2172 _dbus_return_if_fail (_dbus_message_iter_check (real));
2173 _dbus_return_if_fail (value != NULL);
2175 if (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_UNIX_FD)
2177 #ifdef HAVE_UNIX_FD_PASSING
2180 _dbus_type_reader_read_basic(&real->u.reader, &idx);
2182 if (idx.u32 >= real->message->n_unix_fds) {
2183 /* Hmm, we cannot really signal an error here, so let's make
2184 sure to return an invalid fd. */
2185 *((int*) value) = -1;
2189 *((int*) value) = _dbus_dup(real->message->unix_fds[idx.u32], NULL);
2191 *((int*) value) = -1;
2196 _dbus_type_reader_read_basic (&real->u.reader,
2202 * Returns the number of bytes in the array as marshaled in the wire
2203 * protocol. The iterator must currently be inside an array-typed
2206 * This function is deprecated on the grounds that it is stupid. Why
2207 * would you want to know how many bytes are in the array as marshaled
2208 * in the wire protocol? For now, use the n_elements returned from
2209 * dbus_message_iter_get_fixed_array() instead, or iterate over the
2210 * array values and count them.
2212 * @todo introduce a variant of this get_n_elements that returns
2213 * the number of elements, though with a non-fixed array it will not
2214 * be very efficient, so maybe it's not good.
2216 * @param iter the iterator
2217 * @returns the number of bytes in the array
2220 dbus_message_iter_get_array_len (DBusMessageIter *iter)
2222 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2224 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2226 return _dbus_type_reader_get_array_length (&real->u.reader);
2230 * Reads a block of fixed-length values from the message iterator.
2231 * Fixed-length values are those basic types that are not string-like,
2232 * such as integers, bool, double. The returned block will be from the
2233 * current position in the array until the end of the array.
2235 * There is one exception here: although DBUS_TYPE_UNIX_FD is
2236 * considered a 'fixed' type arrays of this type may not be read with
2239 * The message iter should be "in" the array (that is, you recurse into the
2240 * array, and then you call dbus_message_iter_get_fixed_array() on the
2241 * "sub-iterator" created by dbus_message_iter_recurse()).
2243 * The value argument should be the address of a location to store the
2244 * returned array. So for int32 it should be a "const dbus_int32_t**"
2245 * The returned value is by reference and should not be freed.
2247 * This function should only be used if dbus_type_is_fixed() returns
2248 * #TRUE for the element type.
2250 * If an array's elements are not fixed in size, you have to recurse
2251 * into the array with dbus_message_iter_recurse() and read the
2252 * elements one by one.
2254 * Because the array is not copied, this function runs in constant
2255 * time and is fast; it's much preferred over walking the entire array
2256 * with an iterator. (However, you can always use
2257 * dbus_message_iter_recurse(), even for fixed-length types;
2258 * dbus_message_iter_get_fixed_array() is just an optimization.)
2260 * @param iter the iterator
2261 * @param value location to store the block
2262 * @param n_elements number of elements in the block
2265 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
2269 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2270 int subtype = _dbus_type_reader_get_current_type(&real->u.reader);
2272 _dbus_return_if_fail (_dbus_message_iter_check (real));
2273 _dbus_return_if_fail (value != NULL);
2274 _dbus_return_if_fail ((subtype == DBUS_TYPE_INVALID) ||
2275 (dbus_type_is_fixed (subtype) && subtype != DBUS_TYPE_UNIX_FD));
2277 _dbus_type_reader_read_fixed_multi (&real->u.reader,
2282 * Initializes a #DBusMessageIter for appending arguments to the end
2285 * @todo If appending any of the arguments fails due to lack of
2286 * memory, the message is hosed and you have to start over building
2287 * the whole message.
2289 * @param message the message
2290 * @param iter pointer to an iterator to initialize
2293 dbus_message_iter_init_append (DBusMessage *message,
2294 DBusMessageIter *iter)
2296 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2298 _dbus_return_if_fail (message != NULL);
2299 _dbus_return_if_fail (iter != NULL);
2301 _dbus_message_iter_init_common (message, real,
2302 DBUS_MESSAGE_ITER_TYPE_WRITER);
2304 /* We create the signature string and point iterators at it "on demand"
2305 * when a value is actually appended. That means that init() never fails
2308 _dbus_type_writer_init_types_delayed (&real->u.writer,
2309 _dbus_header_get_byte_order (&message->header),
2311 _dbus_string_get_length (&message->body));
2315 * Creates a temporary signature string containing the current
2316 * signature, stores it in the iterator, and points the iterator to
2317 * the end of it. Used any time we write to the message.
2319 * @param real an iterator without a type_str
2320 * @returns #FALSE if no memory
2323 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
2326 const DBusString *current_sig;
2327 int current_sig_pos;
2329 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2331 if (real->u.writer.type_str != NULL)
2333 _dbus_assert (real->sig_refcount > 0);
2334 real->sig_refcount += 1;
2338 str = dbus_new (DBusString, 1);
2342 if (!_dbus_header_get_field_raw (&real->message->header,
2343 DBUS_HEADER_FIELD_SIGNATURE,
2344 ¤t_sig, ¤t_sig_pos))
2351 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
2352 current_sig_pos += 1; /* move on to sig data */
2354 if (!_dbus_string_init_preallocated (str, current_len + 4))
2360 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
2363 _dbus_string_free (str);
2370 if (!_dbus_string_init_preallocated (str, 4))
2377 real->sig_refcount = 1;
2379 _dbus_type_writer_add_types (&real->u.writer,
2380 str, _dbus_string_get_length (str));
2385 * Sets the new signature as the message signature, frees the
2386 * signature string, and marks the iterator as not having a type_str
2387 * anymore. Frees the signature even if it fails, so you can't
2388 * really recover from failure. Kinda busted.
2390 * @param real an iterator without a type_str
2391 * @returns #FALSE if no memory
2394 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2397 const char *v_STRING;
2400 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2401 _dbus_assert (real->u.writer.type_str != NULL);
2402 _dbus_assert (real->sig_refcount > 0);
2404 real->sig_refcount -= 1;
2406 if (real->sig_refcount > 0)
2408 _dbus_assert (real->sig_refcount == 0);
2412 str = real->u.writer.type_str;
2414 v_STRING = _dbus_string_get_const_data (str);
2415 if (!_dbus_header_set_field_basic (&real->message->header,
2416 DBUS_HEADER_FIELD_SIGNATURE,
2417 DBUS_TYPE_SIGNATURE,
2421 _dbus_type_writer_remove_types (&real->u.writer);
2422 _dbus_string_free (str);
2429 * Frees the signature string and marks the iterator as not having a
2430 * type_str anymore. Since the new signature is not set, the message
2431 * will generally be hosed after this is called.
2433 * @param real an iterator without a type_str
2436 _dbus_message_iter_abandon_signature (DBusMessageRealIter *real)
2440 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2441 _dbus_assert (real->u.writer.type_str != NULL);
2442 _dbus_assert (real->sig_refcount > 0);
2444 real->sig_refcount -= 1;
2446 if (real->sig_refcount > 0)
2448 _dbus_assert (real->sig_refcount == 0);
2450 str = real->u.writer.type_str;
2452 _dbus_type_writer_remove_types (&real->u.writer);
2453 _dbus_string_free (str);
2457 #ifndef DBUS_DISABLE_CHECKS
2459 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2461 if (!_dbus_message_iter_check (iter))
2464 if (iter->message->locked)
2466 _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)\n");
2472 #endif /* DBUS_DISABLE_CHECKS */
2474 #ifdef HAVE_UNIX_FD_PASSING
2476 expand_fd_array(DBusMessage *m,
2481 /* This makes space for adding n new fds to the array and returns a
2482 pointer to the place were the first fd should be put. */
2484 if (m->n_unix_fds + n > m->n_unix_fds_allocated)
2489 /* Make twice as much space as necessary */
2490 k = (m->n_unix_fds + n) * 2;
2492 /* Allocate at least four */
2496 p = dbus_realloc(m->unix_fds, k * sizeof(int));
2501 m->n_unix_fds_allocated = k;
2504 return m->unix_fds + m->n_unix_fds;
2509 * Appends a basic-typed value to the message. The basic types are the
2510 * non-container types such as integer and string.
2512 * The "value" argument should be the address of a basic-typed value.
2513 * So for string, const char**. For integer, dbus_int32_t*.
2515 * For Unix file descriptors this function will internally duplicate
2516 * the descriptor you passed in. Hence you may close the descriptor
2517 * immediately after this call.
2519 * @todo If this fails due to lack of memory, the message is hosed and
2520 * you have to start over building the whole message.
2522 * @param iter the append iterator
2523 * @param type the type of the value
2524 * @param value the address of the value
2525 * @returns #FALSE if not enough memory
2528 dbus_message_iter_append_basic (DBusMessageIter *iter,
2532 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2535 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2536 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2537 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2538 _dbus_return_val_if_fail (value != NULL, FALSE);
2540 #ifndef DBUS_DISABLE_CHECKS
2543 const char * const *string_p;
2544 const dbus_bool_t *bool_p;
2546 case DBUS_TYPE_STRING:
2548 _dbus_return_val_if_fail (_dbus_check_is_valid_utf8 (*string_p), FALSE);
2551 case DBUS_TYPE_OBJECT_PATH:
2553 _dbus_return_val_if_fail (_dbus_check_is_valid_path (*string_p), FALSE);
2556 case DBUS_TYPE_SIGNATURE:
2558 _dbus_return_val_if_fail (_dbus_check_is_valid_signature (*string_p), FALSE);
2561 case DBUS_TYPE_BOOLEAN:
2563 _dbus_return_val_if_fail (*bool_p == 0 || *bool_p == 1, FALSE);
2568 /* nothing to check, all possible values are allowed */
2573 if (!_dbus_message_iter_open_signature (real))
2576 if (type == DBUS_TYPE_UNIX_FD)
2578 #ifdef HAVE_UNIX_FD_PASSING
2582 /* First step, include the fd in the fd list of this message */
2583 if (!(fds = expand_fd_array(real->message, 1)))
2586 *fds = _dbus_dup(*(int*) value, NULL);
2590 u = real->message->n_unix_fds;
2592 /* Second step, write the index to the fd */
2593 if (!(ret = _dbus_type_writer_write_basic (&real->u.writer, DBUS_TYPE_UNIX_FD, &u))) {
2594 _dbus_close(*fds, NULL);
2598 real->message->n_unix_fds += 1;
2601 /* Final step, update the header accordingly */
2602 ret = _dbus_header_set_field_basic (&real->message->header,
2603 DBUS_HEADER_FIELD_UNIX_FDS,
2607 /* If any of these operations fail the message is
2608 hosed. However, no memory or fds should be leaked since what
2609 has been added to message has been added to the message, and
2610 can hence be accounted for when the message is being
2618 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
2621 if (!_dbus_message_iter_close_signature (real))
2628 * Appends a block of fixed-length values to an array. The
2629 * fixed-length types are all basic types that are not string-like. So
2630 * int32, double, bool, etc. (Unix file descriptors however are not
2631 * supported.) You must call dbus_message_iter_open_container() to
2632 * open an array of values before calling this function. You may call
2633 * this function multiple times (and intermixed with calls to
2634 * dbus_message_iter_append_basic()) for the same array.
2636 * The "value" argument should be the address of the array. So for
2637 * integer, "dbus_int32_t**" is expected for example.
2639 * @warning in C, given "int array[]", "&array == array" (the
2640 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2641 * So if you're using an array instead of a pointer you have to create
2642 * a pointer variable, assign the array to it, then take the address
2643 * of the pointer variable.
2645 * const dbus_int32_t array[] = { 1, 2, 3 };
2646 * const dbus_int32_t *v_ARRAY = array;
2647 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
2648 * fprintf (stderr, "No memory!\n");
2650 * For strings it works to write const char *array = "Hello" and then
2651 * use &array though.
2653 * @todo If this fails due to lack of memory, the message is hosed and
2654 * you have to start over building the whole message.
2656 * @param iter the append iterator
2657 * @param element_type the type of the array elements
2658 * @param value the address of the array
2659 * @param n_elements the number of elements to append
2660 * @returns #FALSE if not enough memory
2663 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
2668 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2671 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2672 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2673 _dbus_return_val_if_fail (dbus_type_is_fixed (element_type) && element_type != DBUS_TYPE_UNIX_FD, FALSE);
2674 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
2675 _dbus_return_val_if_fail (value != NULL, FALSE);
2676 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
2677 _dbus_return_val_if_fail (n_elements <=
2678 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
2681 #ifndef DBUS_DISABLE_CHECKS
2682 if (element_type == DBUS_TYPE_BOOLEAN)
2684 const dbus_bool_t * const *bools = value;
2687 for (i = 0; i < n_elements; i++)
2689 _dbus_return_val_if_fail ((*bools)[i] == 0 || (*bools)[i] == 1, FALSE);
2694 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
2700 * Appends a container-typed value to the message; you are required to
2701 * append the contents of the container using the returned
2702 * sub-iterator, and then call
2703 * dbus_message_iter_close_container(). Container types are for
2704 * example struct, variant, and array. For variants, the
2705 * contained_signature should be the type of the single value inside
2706 * the variant. For structs and dict entries, contained_signature
2707 * should be #NULL; it will be set to whatever types you write into
2708 * the struct. For arrays, contained_signature should be the type of
2709 * the array elements.
2711 * @todo If this fails due to lack of memory, the message is hosed and
2712 * you have to start over building the whole message.
2714 * @param iter the append iterator
2715 * @param type the type of the value
2716 * @param contained_signature the type of container contents
2717 * @param sub sub-iterator to initialize
2718 * @returns #FALSE if not enough memory
2721 dbus_message_iter_open_container (DBusMessageIter *iter,
2723 const char *contained_signature,
2724 DBusMessageIter *sub)
2726 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2727 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2728 DBusString contained_str;
2730 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2731 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2732 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
2733 _dbus_return_val_if_fail (sub != NULL, FALSE);
2734 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
2735 contained_signature == NULL) ||
2736 (type == DBUS_TYPE_DICT_ENTRY &&
2737 contained_signature == NULL) ||
2738 (type == DBUS_TYPE_VARIANT &&
2739 contained_signature != NULL) ||
2740 (type == DBUS_TYPE_ARRAY &&
2741 contained_signature != NULL), FALSE);
2743 /* this would fail if the contained_signature is a dict entry, since
2744 * dict entries are invalid signatures standalone (they must be in
2747 _dbus_return_val_if_fail ((type == DBUS_TYPE_ARRAY && contained_signature && *contained_signature == DBUS_DICT_ENTRY_BEGIN_CHAR) ||
2748 (contained_signature == NULL ||
2749 _dbus_check_is_valid_signature (contained_signature)),
2752 if (!_dbus_message_iter_open_signature (real))
2757 if (contained_signature != NULL)
2759 _dbus_string_init_const (&contained_str, contained_signature);
2761 return _dbus_type_writer_recurse (&real->u.writer,
2764 &real_sub->u.writer);
2768 return _dbus_type_writer_recurse (&real->u.writer,
2771 &real_sub->u.writer);
2777 * Closes a container-typed value appended to the message; may write
2778 * out more information to the message known only after the entire
2779 * container is written, and may free resources created by
2780 * dbus_message_iter_open_container().
2782 * @todo If this fails due to lack of memory, the message is hosed and
2783 * you have to start over building the whole message.
2785 * @param iter the append iterator
2786 * @param sub sub-iterator to close
2787 * @returns #FALSE if not enough memory
2790 dbus_message_iter_close_container (DBusMessageIter *iter,
2791 DBusMessageIter *sub)
2793 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2794 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2797 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2798 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2799 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
2800 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2802 ret = _dbus_type_writer_unrecurse (&real->u.writer,
2803 &real_sub->u.writer);
2805 if (!_dbus_message_iter_close_signature (real))
2812 * Abandons creation of a contained-typed value and frees resources created
2813 * by dbus_message_iter_open_container(). Once this returns, the message
2814 * is hosed and you have to start over building the whole message.
2816 * This should only be used to abandon creation of a message when you have
2819 * @param iter the append iterator
2820 * @param sub sub-iterator to close
2823 dbus_message_iter_abandon_container (DBusMessageIter *iter,
2824 DBusMessageIter *sub)
2826 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2827 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2829 _dbus_return_if_fail (_dbus_message_iter_append_check (real));
2830 _dbus_return_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2831 _dbus_return_if_fail (_dbus_message_iter_append_check (real_sub));
2832 _dbus_return_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2834 _dbus_message_iter_abandon_signature (real);
2838 * Sets a flag indicating that the message does not want a reply; if
2839 * this flag is set, the other end of the connection may (but is not
2840 * required to) optimize by not sending method return or error
2841 * replies. If this flag is set, there is no way to know whether the
2842 * message successfully arrived at the remote end. Normally you know a
2843 * message was received when you receive the reply to it.
2845 * The flag is #FALSE by default, that is by default the other end is
2846 * required to reply.
2848 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
2850 * @param message the message
2851 * @param no_reply #TRUE if no reply is desired
2854 dbus_message_set_no_reply (DBusMessage *message,
2855 dbus_bool_t no_reply)
2857 _dbus_return_if_fail (message != NULL);
2858 _dbus_return_if_fail (!message->locked);
2860 _dbus_header_toggle_flag (&message->header,
2861 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
2866 * Returns #TRUE if the message does not expect
2869 * @param message the message
2870 * @returns #TRUE if the message sender isn't waiting for a reply
2873 dbus_message_get_no_reply (DBusMessage *message)
2875 _dbus_return_val_if_fail (message != NULL, FALSE);
2877 return _dbus_header_get_flag (&message->header,
2878 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
2882 * Sets a flag indicating that an owner for the destination name will
2883 * be automatically started before the message is delivered. When this
2884 * flag is set, the message is held until a name owner finishes
2885 * starting up, or fails to start up. In case of failure, the reply
2888 * The flag is set to #TRUE by default, i.e. auto starting is the default.
2890 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
2892 * @param message the message
2893 * @param auto_start #TRUE if auto-starting is desired
2896 dbus_message_set_auto_start (DBusMessage *message,
2897 dbus_bool_t auto_start)
2899 _dbus_return_if_fail (message != NULL);
2900 _dbus_return_if_fail (!message->locked);
2902 _dbus_header_toggle_flag (&message->header,
2903 DBUS_HEADER_FLAG_NO_AUTO_START,
2908 * Returns #TRUE if the message will cause an owner for
2909 * destination name to be auto-started.
2911 * @param message the message
2912 * @returns #TRUE if the message will use auto-start
2915 dbus_message_get_auto_start (DBusMessage *message)
2917 _dbus_return_val_if_fail (message != NULL, FALSE);
2919 return !_dbus_header_get_flag (&message->header,
2920 DBUS_HEADER_FLAG_NO_AUTO_START);
2925 * Sets the object path this message is being sent to (for
2926 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
2927 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
2929 * The path must contain only valid characters as defined
2930 * in the D-Bus specification.
2932 * @param message the message
2933 * @param object_path the path or #NULL to unset
2934 * @returns #FALSE if not enough memory
2937 dbus_message_set_path (DBusMessage *message,
2938 const char *object_path)
2940 _dbus_return_val_if_fail (message != NULL, FALSE);
2941 _dbus_return_val_if_fail (!message->locked, FALSE);
2942 _dbus_return_val_if_fail (object_path == NULL ||
2943 _dbus_check_is_valid_path (object_path),
2946 return set_or_delete_string_field (message,
2947 DBUS_HEADER_FIELD_PATH,
2948 DBUS_TYPE_OBJECT_PATH,
2953 * Gets the object path this message is being sent to (for
2954 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
2955 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
2957 * See also dbus_message_get_path_decomposed().
2959 * The returned string becomes invalid if the message is
2960 * modified, since it points into the wire-marshaled message data.
2962 * @param message the message
2963 * @returns the path (should not be freed) or #NULL
2966 dbus_message_get_path (DBusMessage *message)
2970 _dbus_return_val_if_fail (message != NULL, NULL);
2972 v = NULL; /* in case field doesn't exist */
2973 _dbus_header_get_field_basic (&message->header,
2974 DBUS_HEADER_FIELD_PATH,
2975 DBUS_TYPE_OBJECT_PATH,
2981 * Checks if the message has a particular object path. The object
2982 * path is the destination object for a method call or the emitting
2983 * object for a signal.
2985 * @param message the message
2986 * @param path the path name
2987 * @returns #TRUE if there is a path field in the header
2990 dbus_message_has_path (DBusMessage *message,
2993 const char *msg_path;
2994 msg_path = dbus_message_get_path (message);
2996 if (msg_path == NULL)
3007 if (strcmp (msg_path, path) == 0)
3014 * Gets the object path this message is being sent to
3015 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3016 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
3017 * format (one array element per path component).
3018 * Free the returned array with dbus_free_string_array().
3020 * An empty but non-NULL path array means the path "/".
3021 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
3022 * and the path "/" becomes { NULL }.
3024 * See also dbus_message_get_path().
3026 * @todo this could be optimized by using the len from the message
3027 * instead of calling strlen() again
3029 * @param message the message
3030 * @param path place to store allocated array of path components; #NULL set here if no path field exists
3031 * @returns #FALSE if no memory to allocate the array
3034 dbus_message_get_path_decomposed (DBusMessage *message,
3039 _dbus_return_val_if_fail (message != NULL, FALSE);
3040 _dbus_return_val_if_fail (path != NULL, FALSE);
3044 v = dbus_message_get_path (message);
3047 if (!_dbus_decompose_path (v, strlen (v),
3055 * Sets the interface this message is being sent to
3056 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
3057 * the interface a signal is being emitted from
3058 * (for DBUS_MESSAGE_TYPE_SIGNAL).
3060 * The interface name must contain only valid characters as defined
3061 * in the D-Bus specification.
3063 * @param message the message
3064 * @param interface the interface or #NULL to unset
3065 * @returns #FALSE if not enough memory
3068 dbus_message_set_interface (DBusMessage *message,
3069 const char *interface)
3071 _dbus_return_val_if_fail (message != NULL, FALSE);
3072 _dbus_return_val_if_fail (!message->locked, FALSE);
3073 _dbus_return_val_if_fail (interface == NULL ||
3074 _dbus_check_is_valid_interface (interface),
3077 return set_or_delete_string_field (message,
3078 DBUS_HEADER_FIELD_INTERFACE,
3084 * Gets the interface this message is being sent to
3085 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3086 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
3087 * The interface name is fully-qualified (namespaced).
3088 * Returns #NULL if none.
3090 * The returned string becomes invalid if the message is
3091 * modified, since it points into the wire-marshaled message data.
3093 * @param message the message
3094 * @returns the message interface (should not be freed) or #NULL
3097 dbus_message_get_interface (DBusMessage *message)
3101 _dbus_return_val_if_fail (message != NULL, NULL);
3103 v = NULL; /* in case field doesn't exist */
3104 _dbus_header_get_field_basic (&message->header,
3105 DBUS_HEADER_FIELD_INTERFACE,
3112 * Checks if the message has an interface
3114 * @param message the message
3115 * @param interface the interface name
3116 * @returns #TRUE if the interface field in the header matches
3119 dbus_message_has_interface (DBusMessage *message,
3120 const char *interface)
3122 const char *msg_interface;
3123 msg_interface = dbus_message_get_interface (message);
3125 if (msg_interface == NULL)
3127 if (interface == NULL)
3133 if (interface == NULL)
3136 if (strcmp (msg_interface, interface) == 0)
3144 * Sets the interface member being invoked
3145 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3146 * (DBUS_MESSAGE_TYPE_SIGNAL).
3148 * The member name must contain only valid characters as defined
3149 * in the D-Bus specification.
3151 * @param message the message
3152 * @param member the member or #NULL to unset
3153 * @returns #FALSE if not enough memory
3156 dbus_message_set_member (DBusMessage *message,
3159 _dbus_return_val_if_fail (message != NULL, FALSE);
3160 _dbus_return_val_if_fail (!message->locked, FALSE);
3161 _dbus_return_val_if_fail (member == NULL ||
3162 _dbus_check_is_valid_member (member),
3165 return set_or_delete_string_field (message,
3166 DBUS_HEADER_FIELD_MEMBER,
3172 * Gets the interface member being invoked
3173 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3174 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3176 * The returned string becomes invalid if the message is
3177 * modified, since it points into the wire-marshaled message data.
3179 * @param message the message
3180 * @returns the member name (should not be freed) or #NULL
3183 dbus_message_get_member (DBusMessage *message)
3187 _dbus_return_val_if_fail (message != NULL, NULL);
3189 v = NULL; /* in case field doesn't exist */
3190 _dbus_header_get_field_basic (&message->header,
3191 DBUS_HEADER_FIELD_MEMBER,
3198 * Checks if the message has an interface member
3200 * @param message the message
3201 * @param member the member name
3202 * @returns #TRUE if there is a member field in the header
3205 dbus_message_has_member (DBusMessage *message,
3208 const char *msg_member;
3209 msg_member = dbus_message_get_member (message);
3211 if (msg_member == NULL)
3222 if (strcmp (msg_member, member) == 0)
3230 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
3231 * The name is fully-qualified (namespaced).
3233 * The error name must contain only valid characters as defined
3234 * in the D-Bus specification.
3236 * @param message the message
3237 * @param error_name the name or #NULL to unset
3238 * @returns #FALSE if not enough memory
3241 dbus_message_set_error_name (DBusMessage *message,
3242 const char *error_name)
3244 _dbus_return_val_if_fail (message != NULL, FALSE);
3245 _dbus_return_val_if_fail (!message->locked, FALSE);
3246 _dbus_return_val_if_fail (error_name == NULL ||
3247 _dbus_check_is_valid_error_name (error_name),
3250 return set_or_delete_string_field (message,
3251 DBUS_HEADER_FIELD_ERROR_NAME,
3257 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
3260 * The returned string becomes invalid if the message is
3261 * modified, since it points into the wire-marshaled message data.
3263 * @param message the message
3264 * @returns the error name (should not be freed) or #NULL
3267 dbus_message_get_error_name (DBusMessage *message)
3271 _dbus_return_val_if_fail (message != NULL, NULL);
3273 v = NULL; /* in case field doesn't exist */
3274 _dbus_header_get_field_basic (&message->header,
3275 DBUS_HEADER_FIELD_ERROR_NAME,
3282 * Sets the message's destination. The destination is the name of
3283 * another connection on the bus and may be either the unique name
3284 * assigned by the bus to each connection, or a well-known name
3285 * specified in advance.
3287 * The destination name must contain only valid characters as defined
3288 * in the D-Bus specification.
3290 * @param message the message
3291 * @param destination the destination name or #NULL to unset
3292 * @returns #FALSE if not enough memory
3295 dbus_message_set_destination (DBusMessage *message,
3296 const char *destination)
3298 _dbus_return_val_if_fail (message != NULL, FALSE);
3299 _dbus_return_val_if_fail (!message->locked, FALSE);
3300 _dbus_return_val_if_fail (destination == NULL ||
3301 _dbus_check_is_valid_bus_name (destination),
3304 return set_or_delete_string_field (message,
3305 DBUS_HEADER_FIELD_DESTINATION,
3311 * Gets the destination of a message or #NULL if there is none set.
3313 * The returned string becomes invalid if the message is
3314 * modified, since it points into the wire-marshaled message data.
3316 * @param message the message
3317 * @returns the message destination (should not be freed) or #NULL
3320 dbus_message_get_destination (DBusMessage *message)
3324 _dbus_return_val_if_fail (message != NULL, NULL);
3326 v = NULL; /* in case field doesn't exist */
3327 _dbus_header_get_field_basic (&message->header,
3328 DBUS_HEADER_FIELD_DESTINATION,
3335 * Sets the message sender.
3337 * The sender must be a valid bus name as defined in the D-Bus
3340 * Usually you don't want to call this. The message bus daemon will
3341 * call it to set the origin of each message. If you aren't implementing
3342 * a message bus daemon you shouldn't need to set the sender.
3344 * @param message the message
3345 * @param sender the sender or #NULL to unset
3346 * @returns #FALSE if not enough memory
3349 dbus_message_set_sender (DBusMessage *message,
3352 _dbus_return_val_if_fail (message != NULL, FALSE);
3353 _dbus_return_val_if_fail (!message->locked, FALSE);
3354 _dbus_return_val_if_fail (sender == NULL ||
3355 _dbus_check_is_valid_bus_name (sender),
3358 return set_or_delete_string_field (message,
3359 DBUS_HEADER_FIELD_SENDER,
3365 * Gets the unique name of the connection which originated this
3366 * message, or #NULL if unknown or inapplicable. The sender is filled
3367 * in by the message bus.
3369 * Note, the returned sender is always the unique bus name.
3370 * Connections may own multiple other bus names, but those
3371 * are not found in the sender field.
3373 * The returned string becomes invalid if the message is
3374 * modified, since it points into the wire-marshaled message data.
3376 * @param message the message
3377 * @returns the unique name of the sender or #NULL
3380 dbus_message_get_sender (DBusMessage *message)
3384 _dbus_return_val_if_fail (message != NULL, NULL);
3386 v = NULL; /* in case field doesn't exist */
3387 _dbus_header_get_field_basic (&message->header,
3388 DBUS_HEADER_FIELD_SENDER,
3395 * Gets the type signature of the message, i.e. the arguments in the
3396 * message payload. The signature includes only "in" arguments for
3397 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
3398 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
3399 * what you might expect (that is, it does not include the signature of the
3400 * entire C++-style method).
3402 * The signature is a string made up of type codes such as
3403 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
3404 * the value of #DBUS_TYPE_INVALID).
3406 * The returned string becomes invalid if the message is
3407 * modified, since it points into the wire-marshaled message data.
3409 * @param message the message
3410 * @returns the type signature
3413 dbus_message_get_signature (DBusMessage *message)
3415 const DBusString *type_str;
3418 _dbus_return_val_if_fail (message != NULL, NULL);
3420 get_const_signature (&message->header, &type_str, &type_pos);
3422 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
3426 _dbus_message_has_type_interface_member (DBusMessage *message,
3428 const char *interface,
3433 _dbus_assert (message != NULL);
3434 _dbus_assert (interface != NULL);
3435 _dbus_assert (member != NULL);
3437 if (dbus_message_get_type (message) != type)
3440 /* Optimize by checking the short member name first
3441 * instead of the longer interface name
3444 n = dbus_message_get_member (message);
3446 if (n && strcmp (n, member) == 0)
3448 n = dbus_message_get_interface (message);
3450 if (n == NULL || strcmp (n, interface) == 0)
3458 * Checks whether the message is a method call with the given
3459 * interface and member fields. If the message is not
3460 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
3461 * member field, returns #FALSE. If the interface field is missing,
3462 * then it will be assumed equal to the provided interface. The D-Bus
3463 * protocol allows method callers to leave out the interface name.
3465 * @param message the message
3466 * @param interface the name to check (must not be #NULL)
3467 * @param method the name to check (must not be #NULL)
3469 * @returns #TRUE if the message is the specified method call
3472 dbus_message_is_method_call (DBusMessage *message,
3473 const char *interface,
3476 _dbus_return_val_if_fail (message != NULL, FALSE);
3477 _dbus_return_val_if_fail (interface != NULL, FALSE);
3478 _dbus_return_val_if_fail (method != NULL, FALSE);
3479 /* don't check that interface/method are valid since it would be
3480 * expensive, and not catch many common errors
3483 return _dbus_message_has_type_interface_member (message,
3484 DBUS_MESSAGE_TYPE_METHOD_CALL,
3489 * Checks whether the message is a signal with the given interface and
3490 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
3491 * has a different interface or member field, returns #FALSE.
3493 * @param message the message
3494 * @param interface the name to check (must not be #NULL)
3495 * @param signal_name the name to check (must not be #NULL)
3497 * @returns #TRUE if the message is the specified signal
3500 dbus_message_is_signal (DBusMessage *message,
3501 const char *interface,
3502 const char *signal_name)
3504 _dbus_return_val_if_fail (message != NULL, FALSE);
3505 _dbus_return_val_if_fail (interface != NULL, FALSE);
3506 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
3507 /* don't check that interface/name are valid since it would be
3508 * expensive, and not catch many common errors
3511 return _dbus_message_has_type_interface_member (message,
3512 DBUS_MESSAGE_TYPE_SIGNAL,
3513 interface, signal_name);
3517 * Checks whether the message is an error reply with the given error
3518 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
3519 * different name, returns #FALSE.
3521 * @param message the message
3522 * @param error_name the name to check (must not be #NULL)
3524 * @returns #TRUE if the message is the specified error
3527 dbus_message_is_error (DBusMessage *message,
3528 const char *error_name)
3532 _dbus_return_val_if_fail (message != NULL, FALSE);
3533 _dbus_return_val_if_fail (error_name != NULL, FALSE);
3534 /* don't check that error_name is valid since it would be expensive,
3535 * and not catch many common errors
3538 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3541 n = dbus_message_get_error_name (message);
3543 if (n && strcmp (n, error_name) == 0)
3550 * Checks whether the message was sent to the given name. If the
3551 * message has no destination specified or has a different
3552 * destination, returns #FALSE.
3554 * @param message the message
3555 * @param name the name to check (must not be #NULL)
3557 * @returns #TRUE if the message has the given destination name
3560 dbus_message_has_destination (DBusMessage *message,
3565 _dbus_return_val_if_fail (message != NULL, FALSE);
3566 _dbus_return_val_if_fail (name != NULL, FALSE);
3567 /* don't check that name is valid since it would be expensive, and
3568 * not catch many common errors
3571 s = dbus_message_get_destination (message);
3573 if (s && strcmp (s, name) == 0)
3580 * Checks whether the message has the given unique name as its sender.
3581 * If the message has no sender specified or has a different sender,
3582 * returns #FALSE. Note that a peer application will always have the
3583 * unique name of the connection as the sender. So you can't use this
3584 * function to see whether a sender owned a well-known name.
3586 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
3589 * @param message the message
3590 * @param name the name to check (must not be #NULL)
3592 * @returns #TRUE if the message has the given sender
3595 dbus_message_has_sender (DBusMessage *message,
3600 _dbus_return_val_if_fail (message != NULL, FALSE);
3601 _dbus_return_val_if_fail (name != NULL, FALSE);
3602 /* don't check that name is valid since it would be expensive, and
3603 * not catch many common errors
3606 s = dbus_message_get_sender (message);
3608 if (s && strcmp (s, name) == 0)
3615 * Checks whether the message has the given signature; see
3616 * dbus_message_get_signature() for more details on what the signature
3619 * @param message the message
3620 * @param signature typecode array
3621 * @returns #TRUE if message has the given signature
3624 dbus_message_has_signature (DBusMessage *message,
3625 const char *signature)
3629 _dbus_return_val_if_fail (message != NULL, FALSE);
3630 _dbus_return_val_if_fail (signature != NULL, FALSE);
3631 /* don't check that signature is valid since it would be expensive,
3632 * and not catch many common errors
3635 s = dbus_message_get_signature (message);
3637 if (s && strcmp (s, signature) == 0)
3644 * Sets a #DBusError based on the contents of the given
3645 * message. The error is only set if the message
3646 * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
3647 * The name of the error is set to the name of the message,
3648 * and the error message is set to the first argument
3649 * if the argument exists and is a string.
3651 * The return value indicates whether the error was set (the error is
3652 * set if and only if the message is an error message). So you can
3653 * check for an error reply and convert it to DBusError in one go:
3655 * if (dbus_set_error_from_message (error, reply))
3661 * @param error the error to set
3662 * @param message the message to set it from
3663 * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
3666 dbus_set_error_from_message (DBusError *error,
3667 DBusMessage *message)
3671 _dbus_return_val_if_fail (message != NULL, FALSE);
3672 _dbus_return_val_if_error_is_set (error, FALSE);
3674 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3678 dbus_message_get_args (message, NULL,
3679 DBUS_TYPE_STRING, &str,
3682 dbus_set_error (error, dbus_message_get_error_name (message),
3683 str ? "%s" : NULL, str);
3689 * Checks whether a message contains unix fds
3691 * @param message the message
3692 * @returns #TRUE if the message contains unix fds
3695 dbus_message_contains_unix_fds(DBusMessage *message)
3697 #ifdef HAVE_UNIX_FD_PASSING
3698 _dbus_assert(message);
3700 return message->n_unix_fds > 0;
3709 * @addtogroup DBusMessageInternals
3715 * The initial buffer size of the message loader.
3717 * @todo this should be based on min header size plus some average
3718 * body size, or something. Or rather, the min header size only, if we
3719 * want to try to read only the header, store that in a DBusMessage,
3720 * then read only the body and store that, etc., depends on
3721 * how we optimize _dbus_message_loader_get_buffer() and what
3722 * the exact message format is.
3724 #define INITIAL_LOADER_DATA_LEN 32
3727 * Creates a new message loader. Returns #NULL if memory can't
3730 * @returns new loader, or #NULL.
3733 _dbus_message_loader_new (void)
3735 DBusMessageLoader *loader;
3737 loader = dbus_new0 (DBusMessageLoader, 1);
3741 loader->refcount = 1;
3743 loader->corrupted = FALSE;
3744 loader->corruption_reason = DBUS_VALID;
3746 /* this can be configured by the app, but defaults to the protocol max */
3747 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
3749 /* We set a very relatively conservative default here since due to how
3750 SCM_RIGHTS works we need to preallocate an fd array of the maximum
3751 number of unix fds we want to receive in advance. A
3752 try-and-reallocate loop is not possible. */
3753 loader->max_message_unix_fds = 1024;
3755 if (!_dbus_string_init (&loader->data))
3761 /* preallocate the buffer for speed, ignore failure */
3762 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
3763 _dbus_string_set_length (&loader->data, 0);
3765 #ifdef HAVE_UNIX_FD_PASSING
3766 loader->unix_fds = NULL;
3767 loader->n_unix_fds = loader->n_unix_fds_allocated = 0;
3768 loader->unix_fds_outstanding = FALSE;
3775 * Increments the reference count of the loader.
3777 * @param loader the loader.
3778 * @returns the loader
3781 _dbus_message_loader_ref (DBusMessageLoader *loader)
3783 loader->refcount += 1;
3789 * Decrements the reference count of the loader and finalizes the
3790 * loader when the count reaches zero.
3792 * @param loader the loader.
3795 _dbus_message_loader_unref (DBusMessageLoader *loader)
3797 loader->refcount -= 1;
3798 if (loader->refcount == 0)
3800 #ifdef HAVE_UNIX_FD_PASSING
3801 close_unix_fds(loader->unix_fds, &loader->n_unix_fds);
3802 dbus_free(loader->unix_fds);
3804 _dbus_list_foreach (&loader->messages,
3805 (DBusForeachFunction) dbus_message_unref,
3807 _dbus_list_clear (&loader->messages);
3808 _dbus_string_free (&loader->data);
3814 * Gets the buffer to use for reading data from the network. Network
3815 * data is read directly into an allocated buffer, which is then used
3816 * in the DBusMessage, to avoid as many extra memcpy's as possible.
3817 * The buffer must always be returned immediately using
3818 * _dbus_message_loader_return_buffer(), even if no bytes are
3819 * successfully read.
3821 * @todo this function can be a lot more clever. For example
3822 * it can probably always return a buffer size to read exactly
3823 * the body of the next message, thus avoiding any memory wastage
3826 * @todo we need to enforce a max length on strings in header fields.
3828 * @param loader the message loader.
3829 * @param buffer the buffer
3832 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
3833 DBusString **buffer)
3835 _dbus_assert (!loader->buffer_outstanding);
3837 *buffer = &loader->data;
3839 loader->buffer_outstanding = TRUE;
3843 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
3844 * indicating to the loader how many bytes of the buffer were filled
3845 * in. This function must always be called, even if no bytes were
3846 * successfully read.
3848 * @param loader the loader.
3849 * @param buffer the buffer.
3850 * @param bytes_read number of bytes that were read into the buffer.
3853 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
3857 _dbus_assert (loader->buffer_outstanding);
3858 _dbus_assert (buffer == &loader->data);
3860 loader->buffer_outstanding = FALSE;
3864 * Gets the buffer to use for reading unix fds from the network.
3866 * This works similar to _dbus_message_loader_get_buffer()
3868 * @param loader the message loader.
3869 * @param fds the array to read fds into
3870 * @param max_n_fds how many fds to read at most
3871 * @return TRUE on success, FALSE on OOM
3874 _dbus_message_loader_get_unix_fds(DBusMessageLoader *loader,
3876 unsigned *max_n_fds)
3878 #ifdef HAVE_UNIX_FD_PASSING
3879 _dbus_assert (!loader->unix_fds_outstanding);
3881 /* Allocate space where we can put the fds we read. We allocate
3882 space for max_message_unix_fds since this is an
3883 upper limit how many fds can be received within a single
3884 message. Since SCM_RIGHTS doesn't allow a reallocate+retry logic
3885 we are allocating the maximum possible array size right from the
3886 beginning. This sucks a bit, however unless SCM_RIGHTS is fixed
3887 there is no better way. */
3889 if (loader->n_unix_fds_allocated < loader->max_message_unix_fds)
3891 int *a = dbus_realloc(loader->unix_fds,
3892 loader->max_message_unix_fds * sizeof(loader->unix_fds[0]));
3897 loader->unix_fds = a;
3898 loader->n_unix_fds_allocated = loader->max_message_unix_fds;
3901 *fds = loader->unix_fds + loader->n_unix_fds;
3902 *max_n_fds = loader->n_unix_fds_allocated - loader->n_unix_fds;
3904 loader->unix_fds_outstanding = TRUE;
3907 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
3913 * Returns a buffer obtained from _dbus_message_loader_get_unix_fds().
3915 * This works similar to _dbus_message_loader_return_buffer()
3917 * @param loader the message loader.
3918 * @param fds the array fds were read into
3919 * @param max_n_fds how many fds were read
3923 _dbus_message_loader_return_unix_fds(DBusMessageLoader *loader,
3927 #ifdef HAVE_UNIX_FD_PASSING
3928 _dbus_assert(loader->unix_fds_outstanding);
3929 _dbus_assert(loader->unix_fds + loader->n_unix_fds == fds);
3930 _dbus_assert(loader->n_unix_fds + n_fds <= loader->n_unix_fds_allocated);
3932 loader->n_unix_fds += n_fds;
3933 loader->unix_fds_outstanding = FALSE;
3935 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
3940 * FIXME when we move the header out of the buffer, that memmoves all
3941 * buffered messages. Kind of crappy.
3943 * Also we copy the header and body, which is kind of crappy. To
3944 * avoid this, we have to allow header and body to be in a single
3945 * memory block, which is good for messages we read and bad for
3946 * messages we are creating. But we could move_len() the buffer into
3947 * this single memory block, and move_len() will just swap the buffers
3948 * if you're moving the entire buffer replacing the dest string.
3950 * We could also have the message loader tell the transport how many
3951 * bytes to read; so it would first ask for some arbitrary number like
3952 * 256, then if the message was incomplete it would use the
3953 * header/body len to ask for exactly the size of the message (or
3954 * blocks the size of a typical kernel buffer for the socket). That
3955 * way we don't get trailing bytes in the buffer that have to be
3956 * memmoved. Though I suppose we also don't have a chance of reading a
3957 * bunch of small messages at once, so the optimization may be stupid.
3959 * Another approach would be to keep a "start" index into
3960 * loader->data and only delete it occasionally, instead of after
3961 * each message is loaded.
3963 * load_message() returns FALSE if not enough memory OR the loader was corrupted
3966 load_message (DBusMessageLoader *loader,
3967 DBusMessage *message,
3969 int fields_array_len,
3974 DBusValidity validity;
3975 const DBusString *type_str;
3977 DBusValidationMode mode;
3978 dbus_uint32_t n_unix_fds = 0;
3980 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
3985 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
3988 /* 1. VALIDATE AND COPY OVER HEADER */
3989 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
3990 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
3992 if (!_dbus_header_load (&message->header,
4000 _dbus_string_get_length (&loader->data)))
4002 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
4004 /* assert here so we can catch any code that still uses DBUS_VALID to indicate
4005 oom errors. They should use DBUS_VALIDITY_UNKNOWN_OOM_ERROR instead */
4006 _dbus_assert (validity != DBUS_VALID);
4008 if (validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
4012 loader->corrupted = TRUE;
4013 loader->corruption_reason = validity;
4018 _dbus_assert (validity == DBUS_VALID);
4020 /* 2. VALIDATE BODY */
4021 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
4023 get_const_signature (&message->header, &type_str, &type_pos);
4025 /* Because the bytes_remaining arg is NULL, this validates that the
4026 * body is the right length
4028 validity = _dbus_validate_body_with_reason (type_str,
4035 if (validity != DBUS_VALID)
4037 _dbus_verbose ("Failed to validate message body code %d\n", validity);
4039 loader->corrupted = TRUE;
4040 loader->corruption_reason = validity;
4046 /* 3. COPY OVER UNIX FDS */
4047 _dbus_header_get_field_basic(&message->header,
4048 DBUS_HEADER_FIELD_UNIX_FDS,
4052 #ifdef HAVE_UNIX_FD_PASSING
4054 if (n_unix_fds > loader->n_unix_fds)
4056 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
4057 n_unix_fds, loader->n_unix_fds);
4059 loader->corrupted = TRUE;
4060 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4064 /* If this was a recycled message there might still be
4065 some memory allocated for the fds */
4066 dbus_free(message->unix_fds);
4070 message->unix_fds = _dbus_memdup(loader->unix_fds, n_unix_fds * sizeof(message->unix_fds[0]));
4071 if (message->unix_fds == NULL)
4073 _dbus_verbose ("Failed to allocate file descriptor array\n");
4078 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
4079 loader->n_unix_fds -= n_unix_fds;
4080 memmove(loader->unix_fds + n_unix_fds, loader->unix_fds, loader->n_unix_fds);
4083 message->unix_fds = NULL;
4089 _dbus_verbose ("Hmm, message claims to come with file descriptors "
4090 "but that's not supported on our platform, disconnecting.\n");
4092 loader->corrupted = TRUE;
4093 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4099 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
4101 if (!_dbus_list_append (&loader->messages, message))
4103 _dbus_verbose ("Failed to append new message to loader queue\n");
4108 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
4109 _dbus_assert (_dbus_string_get_length (&loader->data) >=
4110 (header_len + body_len));
4112 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
4114 _dbus_verbose ("Failed to move body into new message\n");
4119 _dbus_string_delete (&loader->data, 0, header_len + body_len);
4121 /* don't waste more than 2k of memory */
4122 _dbus_string_compact (&loader->data, 2048);
4124 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
4125 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
4127 _dbus_verbose ("Loaded message %p\n", message);
4129 _dbus_assert (!oom);
4130 _dbus_assert (!loader->corrupted);
4131 _dbus_assert (loader->messages != NULL);
4132 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4140 /* does nothing if the message isn't in the list */
4141 _dbus_list_remove_last (&loader->messages, message);
4144 _dbus_assert (!loader->corrupted);
4146 _dbus_assert (loader->corrupted);
4148 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
4154 * Converts buffered data into messages, if we have enough data. If
4155 * we don't have enough data, does nothing.
4157 * @todo we need to check that the proper named header fields exist
4158 * for each message type.
4160 * @todo If a message has unknown type, we should probably eat it
4161 * right here rather than passing it out to applications. However
4162 * it's not an error to see messages of unknown type.
4164 * @param loader the loader.
4165 * @returns #TRUE if we had enough memory to finish.
4168 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
4170 while (!loader->corrupted &&
4171 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
4173 DBusValidity validity;
4174 int byte_order, fields_array_len, header_len, body_len;
4176 if (_dbus_header_have_message_untrusted (loader->max_message_size,
4183 _dbus_string_get_length (&loader->data)))
4185 DBusMessage *message;
4187 _dbus_assert (validity == DBUS_VALID);
4189 message = dbus_message_new_empty_header ();
4190 if (message == NULL)
4193 if (!load_message (loader, message,
4194 byte_order, fields_array_len,
4195 header_len, body_len))
4197 dbus_message_unref (message);
4198 /* load_message() returns false if corrupted or OOM; if
4199 * corrupted then return TRUE for not OOM
4201 return loader->corrupted;
4204 _dbus_assert (loader->messages != NULL);
4205 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4209 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
4211 if (validity != DBUS_VALID)
4213 loader->corrupted = TRUE;
4214 loader->corruption_reason = validity;
4224 * Peeks at first loaded message, returns #NULL if no messages have
4227 * @param loader the loader.
4228 * @returns the next message, or #NULL if none.
4231 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
4233 if (loader->messages)
4234 return loader->messages->data;
4240 * Pops a loaded message (passing ownership of the message
4241 * to the caller). Returns #NULL if no messages have been
4244 * @param loader the loader.
4245 * @returns the next message, or #NULL if none.
4248 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
4250 return _dbus_list_pop_first (&loader->messages);
4254 * Pops a loaded message inside a list link (passing ownership of the
4255 * message and link to the caller). Returns #NULL if no messages have
4258 * @param loader the loader.
4259 * @returns the next message link, or #NULL if none.
4262 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
4264 return _dbus_list_pop_first_link (&loader->messages);
4268 * Returns a popped message link, used to undo a pop.
4270 * @param loader the loader
4271 * @param link the link with a message in it
4274 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
4277 _dbus_list_prepend_link (&loader->messages, link);
4281 * Checks whether the loader is confused due to bad data.
4282 * If messages are received that are invalid, the
4283 * loader gets confused and gives up permanently.
4284 * This state is called "corrupted."
4286 * @param loader the loader
4287 * @returns #TRUE if the loader is hosed.
4290 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
4292 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4293 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4294 return loader->corrupted;
4298 * Checks what kind of bad data confused the loader.
4300 * @param loader the loader
4301 * @returns why the loader is hosed, or DBUS_VALID if it isn't.
4304 _dbus_message_loader_get_corruption_reason (DBusMessageLoader *loader)
4306 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4307 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4309 return loader->corruption_reason;
4313 * Sets the maximum size message we allow.
4315 * @param loader the loader
4316 * @param size the max message size in bytes
4319 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
4322 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
4324 _dbus_verbose ("clamping requested max message size %ld to %d\n",
4325 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
4326 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4328 loader->max_message_size = size;
4332 * Gets the maximum allowed message size in bytes.
4334 * @param loader the loader
4335 * @returns max size in bytes
4338 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
4340 return loader->max_message_size;
4344 * Sets the maximum unix fds per message we allow.
4346 * @param loader the loader
4347 * @param size the max number of unix fds in a message
4350 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader,
4353 if (n > DBUS_MAXIMUM_MESSAGE_UNIX_FDS)
4355 _dbus_verbose ("clamping requested max message unix_fds %ld to %d\n",
4356 n, DBUS_MAXIMUM_MESSAGE_UNIX_FDS);
4357 n = DBUS_MAXIMUM_MESSAGE_UNIX_FDS;
4359 loader->max_message_unix_fds = n;
4363 * Gets the maximum allowed number of unix fds per message
4365 * @param loader the loader
4366 * @returns max unix fds
4369 _dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
4371 return loader->max_message_unix_fds;
4374 static DBusDataSlotAllocator slot_allocator;
4375 _DBUS_DEFINE_GLOBAL_LOCK (message_slots);
4378 * Allocates an integer ID to be used for storing application-specific
4379 * data on any DBusMessage. The allocated ID may then be used
4380 * with dbus_message_set_data() and dbus_message_get_data().
4381 * The passed-in slot must be initialized to -1, and is filled in
4382 * with the slot ID. If the passed-in slot is not -1, it's assumed
4383 * to be already allocated, and its refcount is incremented.
4385 * The allocated slot is global, i.e. all DBusMessage objects will
4386 * have a slot with the given integer ID reserved.
4388 * @param slot_p address of a global variable storing the slot
4389 * @returns #FALSE on failure (no memory)
4392 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
4394 return _dbus_data_slot_allocator_alloc (&slot_allocator,
4395 &_DBUS_LOCK_NAME (message_slots),
4400 * Deallocates a global ID for message data slots.
4401 * dbus_message_get_data() and dbus_message_set_data() may no
4402 * longer be used with this slot. Existing data stored on existing
4403 * DBusMessage objects will be freed when the message is
4404 * finalized, but may not be retrieved (and may only be replaced if
4405 * someone else reallocates the slot). When the refcount on the
4406 * passed-in slot reaches 0, it is set to -1.
4408 * @param slot_p address storing the slot to deallocate
4411 dbus_message_free_data_slot (dbus_int32_t *slot_p)
4413 _dbus_return_if_fail (*slot_p >= 0);
4415 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
4419 * Stores a pointer on a DBusMessage, along
4420 * with an optional function to be used for freeing
4421 * the data when the data is set again, or when
4422 * the message is finalized. The slot number
4423 * must have been allocated with dbus_message_allocate_data_slot().
4425 * @param message the message
4426 * @param slot the slot number
4427 * @param data the data to store
4428 * @param free_data_func finalizer function for the data
4429 * @returns #TRUE if there was enough memory to store the data
4432 dbus_message_set_data (DBusMessage *message,
4435 DBusFreeFunction free_data_func)
4437 DBusFreeFunction old_free_func;
4441 _dbus_return_val_if_fail (message != NULL, FALSE);
4442 _dbus_return_val_if_fail (slot >= 0, FALSE);
4444 retval = _dbus_data_slot_list_set (&slot_allocator,
4445 &message->slot_list,
4446 slot, data, free_data_func,
4447 &old_free_func, &old_data);
4451 /* Do the actual free outside the message lock */
4453 (* old_free_func) (old_data);
4460 * Retrieves data previously set with dbus_message_set_data().
4461 * The slot must still be allocated (must not have been freed).
4463 * @param message the message
4464 * @param slot the slot to get data from
4465 * @returns the data, or #NULL if not found
4468 dbus_message_get_data (DBusMessage *message,
4473 _dbus_return_val_if_fail (message != NULL, NULL);
4475 res = _dbus_data_slot_list_get (&slot_allocator,
4476 &message->slot_list,
4483 * Utility function to convert a machine-readable (not translated)
4484 * string into a D-Bus message type.
4487 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
4488 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
4489 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
4490 * "error" -> DBUS_MESSAGE_TYPE_ERROR
4491 * anything else -> DBUS_MESSAGE_TYPE_INVALID
4496 dbus_message_type_from_string (const char *type_str)
4498 if (strcmp (type_str, "method_call") == 0)
4499 return DBUS_MESSAGE_TYPE_METHOD_CALL;
4500 if (strcmp (type_str, "method_return") == 0)
4501 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
4502 else if (strcmp (type_str, "signal") == 0)
4503 return DBUS_MESSAGE_TYPE_SIGNAL;
4504 else if (strcmp (type_str, "error") == 0)
4505 return DBUS_MESSAGE_TYPE_ERROR;
4507 return DBUS_MESSAGE_TYPE_INVALID;
4511 * Utility function to convert a D-Bus message type into a
4512 * machine-readable string (not translated).
4515 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
4516 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
4517 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
4518 * DBUS_MESSAGE_TYPE_ERROR -> "error"
4519 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
4524 dbus_message_type_to_string (int type)
4528 case DBUS_MESSAGE_TYPE_METHOD_CALL:
4529 return "method_call";
4530 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
4531 return "method_return";
4532 case DBUS_MESSAGE_TYPE_SIGNAL:
4534 case DBUS_MESSAGE_TYPE_ERROR:
4542 * Turn a DBusMessage into the marshalled form as described in the D-Bus
4545 * Generally, this function is only useful for encapsulating D-Bus messages in
4546 * a different protocol.
4548 * @param msg the DBusMessage
4549 * @param marshalled_data_p the location to save the marshalled form to
4550 * @param len_p the location to save the length of the marshalled form to
4551 * @returns #FALSE if there was not enough memory
4554 dbus_message_marshal (DBusMessage *msg,
4555 char **marshalled_data_p,
4559 dbus_bool_t was_locked;
4561 _dbus_return_val_if_fail (msg != NULL, FALSE);
4562 _dbus_return_val_if_fail (marshalled_data_p != NULL, FALSE);
4563 _dbus_return_val_if_fail (len_p != NULL, FALSE);
4565 if (!_dbus_string_init (&tmp))
4568 /* Ensure the message is locked, to ensure the length header is filled in. */
4569 was_locked = msg->locked;
4572 dbus_message_lock (msg);
4574 if (!_dbus_string_copy (&(msg->header.data), 0, &tmp, 0))
4577 *len_p = _dbus_string_get_length (&tmp);
4579 if (!_dbus_string_copy (&(msg->body), 0, &tmp, *len_p))
4582 *len_p = _dbus_string_get_length (&tmp);
4584 if (!_dbus_string_steal_data (&tmp, marshalled_data_p))
4587 _dbus_string_free (&tmp);
4590 msg->locked = FALSE;
4595 _dbus_string_free (&tmp);
4598 msg->locked = FALSE;
4604 * Demarshal a D-Bus message from the format described in the D-Bus
4607 * Generally, this function is only useful for encapsulating D-Bus messages in
4608 * a different protocol.
4610 * @param str the marshalled DBusMessage
4611 * @param len the length of str
4612 * @param error the location to save errors to
4613 * @returns #NULL if there was an error
4616 dbus_message_demarshal (const char *str,
4620 DBusMessageLoader *loader;
4624 _dbus_return_val_if_fail (str != NULL, NULL);
4626 loader = _dbus_message_loader_new ();
4631 _dbus_message_loader_get_buffer (loader, &buffer);
4632 _dbus_string_append_len (buffer, str, len);
4633 _dbus_message_loader_return_buffer (loader, buffer, len);
4635 if (!_dbus_message_loader_queue_messages (loader))
4638 if (_dbus_message_loader_get_is_corrupted (loader))
4641 msg = _dbus_message_loader_pop_message (loader);
4646 _dbus_message_loader_unref (loader);
4650 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS, "Message is corrupted (%s)",
4651 _dbus_validity_to_error_message (loader->corruption_reason));
4652 _dbus_message_loader_unref (loader);
4656 _DBUS_SET_OOM (error);
4657 _dbus_message_loader_unref (loader);
4662 * Returns the number of bytes required to be in the buffer to demarshal a
4665 * Generally, this function is only useful for encapsulating D-Bus messages in
4666 * a different protocol.
4668 * @param str data to be marshalled
4669 * @param len the length of str
4670 * @param error the location to save errors to
4671 * @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
4675 dbus_message_demarshal_bytes_needed(const char *buf,
4679 int byte_order, fields_array_len, header_len, body_len;
4680 DBusValidity validity = DBUS_VALID;
4683 if (!buf || len < DBUS_MINIMUM_HEADER_SIZE)
4686 if (len > DBUS_MAXIMUM_MESSAGE_LENGTH)
4687 len = DBUS_MAXIMUM_MESSAGE_LENGTH;
4688 _dbus_string_init_const_len (&str, buf, len);
4690 validity = DBUS_VALID;
4692 = _dbus_header_have_message_untrusted(DBUS_MAXIMUM_MESSAGE_LENGTH,
4693 &validity, &byte_order,
4699 _dbus_string_free (&str);
4701 if (validity == DBUS_VALID)
4703 _dbus_assert (have_message || (header_len + body_len) > len);
4704 return header_len + body_len;
4708 return -1; /* broken! */
4714 /* tests in dbus-message-util.c */