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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
25 #include "dbus-internals.h"
26 #include "dbus-marshal-recursive.h"
27 #include "dbus-marshal-validate.h"
28 #include "dbus-marshal-byteswap.h"
29 #include "dbus-marshal-header.h"
30 #include "dbus-signature.h"
31 #include "dbus-message-private.h"
32 #include "dbus-object-tree.h"
33 #include "dbus-memory.h"
34 #include "dbus-list.h"
35 #include "dbus-threads-internal.h"
36 #ifdef HAVE_UNIX_FD_PASSING
37 #include "dbus-sysdeps-unix.h"
42 static void dbus_message_finalize (DBusMessage *message);
45 * @defgroup DBusMessageInternals DBusMessage implementation details
46 * @ingroup DBusInternals
47 * @brief DBusMessage private implementation details.
49 * The guts of DBusMessage and its methods.
54 /* Not thread locked, but strictly const/read-only so should be OK
56 /** An static string representing an empty signature */
57 _DBUS_STRING_DEFINE_STATIC(_dbus_empty_signature_str, "");
59 /* these have wacky values to help trap uninitialized iterators;
60 * but has to fit in 3 bits
63 DBUS_MESSAGE_ITER_TYPE_READER = 3,
64 DBUS_MESSAGE_ITER_TYPE_WRITER = 7
67 /** typedef for internals of message iterator */
68 typedef struct DBusMessageRealIter DBusMessageRealIter;
71 * @brief Internals of DBusMessageIter
73 * Object representing a position in a message. All fields are internal.
75 struct DBusMessageRealIter
77 DBusMessage *message; /**< Message used */
78 dbus_uint32_t changed_stamp : CHANGED_STAMP_BITS; /**< stamp to detect invalid iters */
79 dbus_uint32_t iter_type : 3; /**< whether this is a reader or writer iter */
80 dbus_uint32_t sig_refcount : 8; /**< depth of open_signature() */
83 DBusTypeWriter writer; /**< writer */
84 DBusTypeReader reader; /**< reader */
85 } u; /**< the type writer or reader that does all the work */
89 get_const_signature (DBusHeader *header,
90 const DBusString **type_str_p,
93 if (_dbus_header_get_field_raw (header,
94 DBUS_HEADER_FIELD_SIGNATURE,
98 *type_pos_p += 1; /* skip the signature length which is 1 byte */
102 *type_str_p = &_dbus_empty_signature_str;
108 * Swaps the message to compiler byte order if required
110 * @param message the message
113 _dbus_message_byteswap (DBusMessage *message)
115 const DBusString *type_str;
118 if (message->byte_order == DBUS_COMPILER_BYTE_ORDER)
121 _dbus_verbose ("Swapping message into compiler byte order\n");
123 get_const_signature (&message->header, &type_str, &type_pos);
125 _dbus_marshal_byteswap (type_str, type_pos,
127 DBUS_COMPILER_BYTE_ORDER,
130 message->byte_order = DBUS_COMPILER_BYTE_ORDER;
132 _dbus_header_byteswap (&message->header, DBUS_COMPILER_BYTE_ORDER);
135 /** byte-swap the message if it doesn't match our byte order.
136 * Called only when we need the message in our own byte order,
137 * normally when reading arrays of integers or doubles.
138 * Otherwise should not be called since it would do needless
141 #define ensure_byte_order(message) \
142 if (message->byte_order != DBUS_COMPILER_BYTE_ORDER) \
143 _dbus_message_byteswap (message)
146 * Gets the data to be sent over the network for this message.
147 * The header and then the body should be written out.
148 * This function is guaranteed to always return the same
149 * data once a message is locked (with dbus_message_lock()).
151 * @param message the message.
152 * @param header return location for message header data.
153 * @param body return location for message body data.
156 _dbus_message_get_network_data (DBusMessage *message,
157 const DBusString **header,
158 const DBusString **body)
160 _dbus_assert (message->locked);
162 *header = &message->header.data;
163 *body = &message->body;
167 * Gets the unix fds to be sent over the network for this message.
168 * This function is guaranteed to always return the same data once a
169 * message is locked (with dbus_message_lock()).
171 * @param message the message.
172 * @param fds return location of unix fd array
173 * @param n_fds return number of entries in array
175 void _dbus_message_get_unix_fds(DBusMessage *message,
179 _dbus_assert (message->locked);
181 #ifdef HAVE_UNIX_FD_PASSING
182 *fds = message->unix_fds;
183 *n_fds = message->n_unix_fds;
191 * Sets the serial number of a message.
192 * This can only be done once on a message.
194 * DBusConnection will automatically set the serial to an appropriate value
195 * when the message is sent; this function is only needed when encapsulating
196 * messages in another protocol, or otherwise bypassing DBusConnection.
198 * @param message the message
199 * @param serial the serial
202 dbus_message_set_serial (DBusMessage *message,
203 dbus_uint32_t serial)
205 _dbus_return_if_fail (message != NULL);
206 _dbus_return_if_fail (!message->locked);
208 _dbus_header_set_serial (&message->header, serial);
212 * Adds a counter to be incremented immediately with the
213 * size of this message, and decremented by the size
214 * of this message when this message if finalized.
215 * The link contains a counter with its refcount already
216 * incremented, but the counter itself not incremented.
217 * Ownership of link and counter refcount is passed to
220 * @param message the message
221 * @param link link with counter as data
224 _dbus_message_add_size_counter_link (DBusMessage *message,
227 /* right now we don't recompute the delta when message
228 * size changes, and that's OK for current purposes
229 * I think, but could be important to change later.
230 * Do recompute it whenever there are no outstanding counters,
231 * since it's basically free.
233 if (message->size_counters == NULL)
235 message->size_counter_delta =
236 _dbus_string_get_length (&message->header.data) +
237 _dbus_string_get_length (&message->body);
240 _dbus_verbose ("message has size %ld\n",
241 message->size_counter_delta);
245 _dbus_list_append_link (&message->size_counters, link);
247 _dbus_counter_adjust (link->data, message->size_counter_delta);
251 * Adds a counter to be incremented immediately with the
252 * size of this message, and decremented by the size
253 * of this message when this message if finalized.
255 * @param message the message
256 * @param counter the counter
257 * @returns #FALSE if no memory
260 _dbus_message_add_size_counter (DBusMessage *message,
261 DBusCounter *counter)
265 link = _dbus_list_alloc_link (counter);
269 _dbus_counter_ref (counter);
270 _dbus_message_add_size_counter_link (message, link);
276 * Removes a counter tracking the size of this message, and decrements
277 * the counter by the size of this message.
279 * @param message the message
280 * @param link_return return the link used
281 * @param counter the counter
284 _dbus_message_remove_size_counter (DBusMessage *message,
285 DBusCounter *counter,
286 DBusList **link_return)
290 link = _dbus_list_find_last (&message->size_counters,
292 _dbus_assert (link != NULL);
294 _dbus_list_unlink (&message->size_counters,
299 _dbus_list_free_link (link);
301 _dbus_counter_adjust (counter, - message->size_counter_delta);
303 _dbus_counter_unref (counter);
307 * Locks a message. Allows checking that applications don't keep a
308 * reference to a message in the outgoing queue and change it
309 * underneath us. Messages are locked when they enter the outgoing
310 * queue (dbus_connection_send_message()), and the library complains
311 * if the message is modified while locked. This function may also
312 * called externally, for applications wrapping D-Bus in another protocol.
314 * @param message the message to lock.
317 dbus_message_lock (DBusMessage *message)
319 if (!message->locked)
321 _dbus_header_update_lengths (&message->header,
322 _dbus_string_get_length (&message->body));
324 /* must have a signature if you have a body */
325 _dbus_assert (_dbus_string_get_length (&message->body) == 0 ||
326 dbus_message_get_signature (message) != NULL);
328 message->locked = TRUE;
333 set_or_delete_string_field (DBusMessage *message,
339 return _dbus_header_delete_field (&message->header, field);
341 return _dbus_header_set_field_basic (&message->header,
348 /* Probably we don't need to use this */
350 * Sets the signature of the message, i.e. the arguments in the
351 * message payload. The signature includes only "in" arguments for
352 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
353 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
354 * what you might expect (it does not include the signature of the
355 * entire C++-style method).
357 * The signature is a string made up of type codes such as
358 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
359 * the value of #DBUS_TYPE_INVALID). The macros such as
360 * #DBUS_TYPE_INT32 evaluate to integers; to assemble a signature you
361 * may find it useful to use the string forms, such as
362 * #DBUS_TYPE_INT32_AS_STRING.
364 * An "unset" or #NULL signature is considered the same as an empty
365 * signature. In fact dbus_message_get_signature() will never return
368 * @param message the message
369 * @param signature the type signature or #NULL to unset
370 * @returns #FALSE if no memory
373 _dbus_message_set_signature (DBusMessage *message,
374 const char *signature)
376 _dbus_return_val_if_fail (message != NULL, FALSE);
377 _dbus_return_val_if_fail (!message->locked, FALSE);
378 _dbus_return_val_if_fail (signature == NULL ||
379 _dbus_check_is_valid_signature (signature));
380 /* can't delete the signature if you have a message body */
381 _dbus_return_val_if_fail (_dbus_string_get_length (&message->body) == 0 ||
384 return set_or_delete_string_field (message,
385 DBUS_HEADER_FIELD_SIGNATURE,
393 * We cache some DBusMessage to reduce the overhead of allocating
394 * them. In my profiling this consistently made about an 8%
395 * difference. It avoids the malloc for the message, the malloc for
396 * the slot list, the malloc for the header string and body string,
397 * and the associated free() calls. It does introduce another global
398 * lock which could be a performance issue in certain cases.
400 * For the echo client/server the round trip time goes from around
401 * .000077 to .000069 with the message cache on my laptop. The sysprof
402 * change is as follows (numbers are cumulative percentage):
404 * with message cache implemented as array as it is now (0.000069 per):
405 * new_empty_header 1.46
406 * mutex_lock 0.56 # i.e. _DBUS_LOCK(message_cache)
412 * mutex_lock 0.33 # i.e. _DBUS_LOCK(message_cache)
415 * with message cache implemented as list (0.000070 per roundtrip):
416 * new_empty_header 2.72
417 * list_pop_first 1.88
421 * without cache (0.000077 per roundtrip):
422 * new_empty_header 6.7
423 * string_init_preallocated 3.43
432 * If you implement the message_cache with a list, the primary reason
433 * it's slower is that you add another thread lock (on the DBusList
437 /** Avoid caching huge messages */
438 #define MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE
440 /** Avoid caching too many messages */
441 #define MAX_MESSAGE_CACHE_SIZE 5
443 _DBUS_DEFINE_GLOBAL_LOCK (message_cache);
444 static DBusMessage *message_cache[MAX_MESSAGE_CACHE_SIZE];
445 static int message_cache_count = 0;
446 static dbus_bool_t message_cache_shutdown_registered = FALSE;
449 dbus_message_cache_shutdown (void *data)
453 _DBUS_LOCK (message_cache);
456 while (i < MAX_MESSAGE_CACHE_SIZE)
458 if (message_cache[i])
459 dbus_message_finalize (message_cache[i]);
464 message_cache_count = 0;
465 message_cache_shutdown_registered = FALSE;
467 _DBUS_UNLOCK (message_cache);
471 * Tries to get a message from the message cache. The retrieved
472 * message will have junk in it, so it still needs to be cleared out
473 * in dbus_message_new_empty_header()
475 * @returns the message, or #NULL if none cached
478 dbus_message_get_cached (void)
480 DBusMessage *message;
485 _DBUS_LOCK (message_cache);
487 _dbus_assert (message_cache_count >= 0);
489 if (message_cache_count == 0)
491 _DBUS_UNLOCK (message_cache);
495 /* This is not necessarily true unless count > 0, and
496 * message_cache is uninitialized until the shutdown is
499 _dbus_assert (message_cache_shutdown_registered);
502 while (i < MAX_MESSAGE_CACHE_SIZE)
504 if (message_cache[i])
506 message = message_cache[i];
507 message_cache[i] = NULL;
508 message_cache_count -= 1;
513 _dbus_assert (message_cache_count >= 0);
514 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
515 _dbus_assert (message != NULL);
517 _dbus_assert (message->refcount.value == 0);
518 _dbus_assert (message->size_counters == NULL);
520 _DBUS_UNLOCK (message_cache);
525 #ifdef HAVE_UNIX_FD_PASSING
527 close_unix_fds(int *fds, unsigned *n_fds)
537 for (i = 0; i < *n_fds; i++)
539 if (!_dbus_close(fds[i], &e))
541 _dbus_warn("Failed to close file descriptor: %s\n", e.message);
548 /* We don't free the array here, in case we can recycle it later */
553 free_size_counter (void *element,
556 DBusCounter *counter = element;
557 DBusMessage *message = data;
559 _dbus_counter_adjust (counter, - message->size_counter_delta);
561 _dbus_counter_unref (counter);
565 * Tries to cache a message, otherwise finalize it.
567 * @param message the message
570 dbus_message_cache_or_finalize (DBusMessage *message)
572 dbus_bool_t was_cached;
575 _dbus_assert (message->refcount.value == 0);
577 /* This calls application code and has to be done first thing
578 * without holding the lock
580 _dbus_data_slot_list_clear (&message->slot_list);
582 _dbus_list_foreach (&message->size_counters,
583 free_size_counter, message);
584 _dbus_list_clear (&message->size_counters);
586 #ifdef HAVE_UNIX_FD_PASSING
587 close_unix_fds(message->unix_fds, &message->n_unix_fds);
592 _DBUS_LOCK (message_cache);
594 if (!message_cache_shutdown_registered)
596 _dbus_assert (message_cache_count == 0);
598 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
602 while (i < MAX_MESSAGE_CACHE_SIZE)
604 message_cache[i] = NULL;
608 message_cache_shutdown_registered = TRUE;
611 _dbus_assert (message_cache_count >= 0);
613 if ((_dbus_string_get_length (&message->header.data) +
614 _dbus_string_get_length (&message->body)) >
615 MAX_MESSAGE_SIZE_TO_CACHE)
618 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
621 /* Find empty slot */
623 while (message_cache[i] != NULL)
626 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
628 _dbus_assert (message_cache[i] == NULL);
629 message_cache[i] = message;
630 message_cache_count += 1;
632 #ifndef DBUS_DISABLE_CHECKS
633 message->in_cache = TRUE;
637 _dbus_assert (message->refcount.value == 0);
639 _DBUS_UNLOCK (message_cache);
642 dbus_message_finalize (message);
645 #ifndef DBUS_DISABLE_CHECKS
647 _dbus_message_iter_check (DBusMessageRealIter *iter)
651 _dbus_warn_check_failed ("dbus message iterator is NULL\n");
655 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
657 if (iter->u.reader.byte_order != iter->message->byte_order)
659 _dbus_warn_check_failed ("dbus message changed byte order since iterator was created\n");
662 /* because we swap the message into compiler order when you init an iter */
663 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
665 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
667 if (iter->u.writer.byte_order != iter->message->byte_order)
669 _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created\n");
672 /* because we swap the message into compiler order when you init an iter */
673 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
677 _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted\n");
681 if (iter->changed_stamp != iter->message->changed_stamp)
683 _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
689 #endif /* DBUS_DISABLE_CHECKS */
692 * Implementation of the varargs arg-getting functions.
693 * dbus_message_get_args() is the place to go for complete
696 * Unix file descriptors that are read with this function will have
697 * the FD_CLOEXEC flag set. If you need them without this flag set,
698 * make sure to unset it with fcntl().
700 * @todo This may leak memory and file descriptors if parsing fails. See #21259
702 * @see dbus_message_get_args
703 * @param iter the message iter
704 * @param error error to be filled in
705 * @param first_arg_type type of the first argument
706 * @param var_args return location for first argument, followed by list of type/location pairs
707 * @returns #FALSE if error was set
710 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
715 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
716 int spec_type, msg_type, i;
719 _dbus_assert (_dbus_message_iter_check (real));
723 spec_type = first_arg_type;
726 while (spec_type != DBUS_TYPE_INVALID)
728 msg_type = dbus_message_iter_get_arg_type (iter);
730 if (msg_type != spec_type)
732 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
733 "Argument %d is specified to be of type \"%s\", but "
734 "is actually of type \"%s\"\n", i,
735 _dbus_type_to_string (spec_type),
736 _dbus_type_to_string (msg_type));
741 if (spec_type == DBUS_TYPE_UNIX_FD)
743 #ifdef HAVE_UNIX_FD_PASSING
747 pfd = va_arg (var_args, int*);
750 _dbus_type_reader_read_basic(&real->u.reader, &idx);
752 if (idx.u32 >= real->message->n_unix_fds)
754 dbus_set_error (error, DBUS_ERROR_INCONSISTENT_MESSAGE,
755 "Message refers to file descriptor at index %i,"
756 "but has only %i descriptors attached.\n",
758 real->message->n_unix_fds);
762 if ((nfd = _dbus_dup(real->message->unix_fds[idx.u32], error)) < 0)
767 dbus_set_error (error, DBUS_ERROR_NOT_SUPPORTED,
768 "Platform does not support file desciptor passing.\n");
772 else if (dbus_type_is_basic (spec_type))
776 ptr = va_arg (var_args, DBusBasicValue*);
778 _dbus_assert (ptr != NULL);
780 _dbus_type_reader_read_basic (&real->u.reader,
783 else if (spec_type == DBUS_TYPE_ARRAY)
786 int spec_element_type;
787 const DBusBasicValue **ptr;
789 DBusTypeReader array;
791 spec_element_type = va_arg (var_args, int);
792 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
794 if (spec_element_type != element_type)
796 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
797 "Argument %d is specified to be an array of \"%s\", but "
798 "is actually an array of \"%s\"\n",
800 _dbus_type_to_string (spec_element_type),
801 _dbus_type_to_string (element_type));
806 if (dbus_type_is_fixed (spec_element_type) &&
807 element_type != DBUS_TYPE_UNIX_FD)
809 ptr = va_arg (var_args, const DBusBasicValue**);
810 n_elements_p = va_arg (var_args, int*);
812 _dbus_assert (ptr != NULL);
813 _dbus_assert (n_elements_p != NULL);
815 _dbus_type_reader_recurse (&real->u.reader, &array);
817 _dbus_type_reader_read_fixed_multi (&array,
820 else if (spec_element_type == DBUS_TYPE_STRING ||
821 spec_element_type == DBUS_TYPE_SIGNATURE ||
822 spec_element_type == DBUS_TYPE_OBJECT_PATH)
828 str_array_p = va_arg (var_args, char***);
829 n_elements_p = va_arg (var_args, int*);
831 _dbus_assert (str_array_p != NULL);
832 _dbus_assert (n_elements_p != NULL);
834 /* Count elements in the array */
835 _dbus_type_reader_recurse (&real->u.reader, &array);
838 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
841 _dbus_type_reader_next (&array);
844 str_array = dbus_new0 (char*, n_elements + 1);
845 if (str_array == NULL)
847 _DBUS_SET_OOM (error);
851 /* Now go through and dup each string */
852 _dbus_type_reader_recurse (&real->u.reader, &array);
855 while (i < n_elements)
858 _dbus_type_reader_read_basic (&array,
861 str_array[i] = _dbus_strdup (s);
862 if (str_array[i] == NULL)
864 dbus_free_string_array (str_array);
865 _DBUS_SET_OOM (error);
871 if (!_dbus_type_reader_next (&array))
872 _dbus_assert (i == n_elements);
875 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
876 _dbus_assert (i == n_elements);
877 _dbus_assert (str_array[i] == NULL);
879 *str_array_p = str_array;
880 *n_elements_p = n_elements;
882 #ifndef DBUS_DISABLE_CHECKS
885 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
886 _DBUS_FUNCTION_NAME);
891 #ifndef DBUS_DISABLE_CHECKS
894 _dbus_warn ("you can only read arrays and basic types with %s for now\n",
895 _DBUS_FUNCTION_NAME);
900 spec_type = va_arg (var_args, int);
901 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
903 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
904 "Message has only %d arguments, but more were expected", i);
921 * @defgroup DBusMessage DBusMessage
923 * @brief Message to be sent or received over a #DBusConnection.
925 * A DBusMessage is the most basic unit of communication over a
926 * DBusConnection. A DBusConnection represents a stream of messages
927 * received from a remote application, and a stream of messages
928 * sent to a remote application.
930 * A message has a message type, returned from
931 * dbus_message_get_type(). This indicates whether the message is a
932 * method call, a reply to a method call, a signal, or an error reply.
934 * A message has header fields such as the sender, destination, method
935 * or signal name, and so forth. DBusMessage has accessor functions for
936 * these, such as dbus_message_get_member().
938 * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
939 * and dbus_message_is_error() check several header fields at once and are
940 * slightly more efficient than checking the header fields with individual
941 * accessor functions.
943 * Finally, a message has arguments. The number and types of arguments
944 * are in the message's signature header field (accessed with
945 * dbus_message_get_signature()). Simple argument values are usually
946 * retrieved with dbus_message_get_args() but more complex values such
947 * as structs may require the use of #DBusMessageIter.
949 * The D-Bus specification goes into some more detail about header fields and
956 * @typedef DBusMessage
958 * Opaque data type representing a message received from or to be
959 * sent to another application.
963 * Returns the serial of a message or 0 if none has been specified.
964 * The message's serial number is provided by the application sending
965 * the message and is used to identify replies to this message.
967 * All messages received on a connection will have a serial provided
968 * by the remote application.
970 * For messages you're sending, dbus_connection_send() will assign a
971 * serial and return it to you.
973 * @param message the message
974 * @returns the serial
977 dbus_message_get_serial (DBusMessage *message)
979 _dbus_return_val_if_fail (message != NULL, 0);
981 return _dbus_header_get_serial (&message->header);
985 * Sets the reply serial of a message (the serial of the message this
988 * @param message the message
989 * @param reply_serial the serial we're replying to
990 * @returns #FALSE if not enough memory
993 dbus_message_set_reply_serial (DBusMessage *message,
994 dbus_uint32_t reply_serial)
996 _dbus_return_val_if_fail (message != NULL, FALSE);
997 _dbus_return_val_if_fail (!message->locked, FALSE);
998 _dbus_return_val_if_fail (reply_serial != 0, FALSE); /* 0 is invalid */
1000 return _dbus_header_set_field_basic (&message->header,
1001 DBUS_HEADER_FIELD_REPLY_SERIAL,
1007 * Returns the serial that the message is a reply to or 0 if none.
1009 * @param message the message
1010 * @returns the reply serial
1013 dbus_message_get_reply_serial (DBusMessage *message)
1015 dbus_uint32_t v_UINT32;
1017 _dbus_return_val_if_fail (message != NULL, 0);
1019 if (_dbus_header_get_field_basic (&message->header,
1020 DBUS_HEADER_FIELD_REPLY_SERIAL,
1029 dbus_message_finalize (DBusMessage *message)
1031 _dbus_assert (message->refcount.value == 0);
1033 /* This calls application callbacks! */
1034 _dbus_data_slot_list_free (&message->slot_list);
1036 _dbus_list_foreach (&message->size_counters,
1037 free_size_counter, message);
1038 _dbus_list_clear (&message->size_counters);
1040 _dbus_header_free (&message->header);
1041 _dbus_string_free (&message->body);
1043 #ifdef HAVE_UNIX_FD_PASSING
1044 close_unix_fds(message->unix_fds, &message->n_unix_fds);
1045 dbus_free(message->unix_fds);
1048 _dbus_assert (message->refcount.value == 0);
1050 dbus_free (message);
1054 dbus_message_new_empty_header (void)
1056 DBusMessage *message;
1057 dbus_bool_t from_cache;
1059 message = dbus_message_get_cached ();
1061 if (message != NULL)
1068 message = dbus_new (DBusMessage, 1);
1069 if (message == NULL)
1071 #ifndef DBUS_DISABLE_CHECKS
1072 message->generation = _dbus_current_generation;
1075 #ifdef HAVE_UNIX_FD_PASSING
1076 message->unix_fds = NULL;
1077 message->n_unix_fds_allocated = 0;
1081 message->refcount.value = 1;
1082 message->byte_order = DBUS_COMPILER_BYTE_ORDER;
1083 message->locked = FALSE;
1084 #ifndef DBUS_DISABLE_CHECKS
1085 message->in_cache = FALSE;
1087 message->size_counters = NULL;
1088 message->size_counter_delta = 0;
1089 message->changed_stamp = 0;
1091 #ifdef HAVE_UNIX_FD_PASSING
1092 message->n_unix_fds = 0;
1096 _dbus_data_slot_list_init (&message->slot_list);
1100 _dbus_header_reinit (&message->header, message->byte_order);
1101 _dbus_string_set_length (&message->body, 0);
1105 if (!_dbus_header_init (&message->header, message->byte_order))
1107 dbus_free (message);
1111 if (!_dbus_string_init_preallocated (&message->body, 32))
1113 _dbus_header_free (&message->header);
1114 dbus_free (message);
1123 * Constructs a new message of the given message type.
1124 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
1125 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
1127 * Usually you want to use dbus_message_new_method_call(),
1128 * dbus_message_new_method_return(), dbus_message_new_signal(),
1129 * or dbus_message_new_error() instead.
1131 * @param message_type type of message
1132 * @returns new message or #NULL if no memory
1135 dbus_message_new (int message_type)
1137 DBusMessage *message;
1139 _dbus_return_val_if_fail (message_type != DBUS_MESSAGE_TYPE_INVALID, NULL);
1141 message = dbus_message_new_empty_header ();
1142 if (message == NULL)
1145 if (!_dbus_header_create (&message->header,
1147 NULL, NULL, NULL, NULL, NULL))
1149 dbus_message_unref (message);
1157 * Constructs a new message to invoke a method on a remote
1158 * object. Returns #NULL if memory can't be allocated for the
1159 * message. The destination may be #NULL in which case no destination
1160 * is set; this is appropriate when using D-Bus in a peer-to-peer
1161 * context (no message bus). The interface may be #NULL, which means
1162 * that if multiple methods with the given name exist it is undefined
1163 * which one will be invoked.
1165 * The path and method names may not be #NULL.
1167 * Destination, path, interface, and method name can't contain
1168 * any invalid characters (see the D-Bus specification).
1170 * @param destination name that the message should be sent to or #NULL
1171 * @param path object path the message should be sent to
1172 * @param interface interface to invoke method on, or #NULL
1173 * @param method method to invoke
1175 * @returns a new DBusMessage, free with dbus_message_unref()
1178 dbus_message_new_method_call (const char *destination,
1180 const char *interface,
1183 DBusMessage *message;
1185 _dbus_return_val_if_fail (path != NULL, NULL);
1186 _dbus_return_val_if_fail (method != NULL, NULL);
1187 _dbus_return_val_if_fail (destination == NULL ||
1188 _dbus_check_is_valid_bus_name (destination), NULL);
1189 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1190 _dbus_return_val_if_fail (interface == NULL ||
1191 _dbus_check_is_valid_interface (interface), NULL);
1192 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
1194 message = dbus_message_new_empty_header ();
1195 if (message == NULL)
1198 if (!_dbus_header_create (&message->header,
1199 DBUS_MESSAGE_TYPE_METHOD_CALL,
1200 destination, path, interface, method, NULL))
1202 dbus_message_unref (message);
1210 * Constructs a message that is a reply to a method call. Returns
1211 * #NULL if memory can't be allocated for the message.
1213 * @param method_call the message being replied to
1214 * @returns a new DBusMessage, free with dbus_message_unref()
1217 dbus_message_new_method_return (DBusMessage *method_call)
1219 DBusMessage *message;
1222 _dbus_return_val_if_fail (method_call != NULL, NULL);
1224 sender = dbus_message_get_sender (method_call);
1226 /* sender is allowed to be null here in peer-to-peer case */
1228 message = dbus_message_new_empty_header ();
1229 if (message == NULL)
1232 if (!_dbus_header_create (&message->header,
1233 DBUS_MESSAGE_TYPE_METHOD_RETURN,
1234 sender, NULL, NULL, NULL, NULL))
1236 dbus_message_unref (message);
1240 dbus_message_set_no_reply (message, TRUE);
1242 if (!dbus_message_set_reply_serial (message,
1243 dbus_message_get_serial (method_call)))
1245 dbus_message_unref (message);
1253 * Constructs a new message representing a signal emission. Returns
1254 * #NULL if memory can't be allocated for the message. A signal is
1255 * identified by its originating object path, interface, and the name
1258 * Path, interface, and signal name must all be valid (the D-Bus
1259 * specification defines the syntax of these fields).
1261 * @param path the path to the object emitting the signal
1262 * @param interface the interface the signal is emitted from
1263 * @param name name of the signal
1264 * @returns a new DBusMessage, free with dbus_message_unref()
1267 dbus_message_new_signal (const char *path,
1268 const char *interface,
1271 DBusMessage *message;
1273 _dbus_return_val_if_fail (path != NULL, NULL);
1274 _dbus_return_val_if_fail (interface != NULL, NULL);
1275 _dbus_return_val_if_fail (name != NULL, NULL);
1276 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1277 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (interface), NULL);
1278 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
1280 message = dbus_message_new_empty_header ();
1281 if (message == NULL)
1284 if (!_dbus_header_create (&message->header,
1285 DBUS_MESSAGE_TYPE_SIGNAL,
1286 NULL, path, interface, name, NULL))
1288 dbus_message_unref (message);
1292 dbus_message_set_no_reply (message, TRUE);
1298 * Creates a new message that is an error reply to another message.
1299 * Error replies are most common in response to method calls, but
1300 * can be returned in reply to any message.
1302 * The error name must be a valid error name according to the syntax
1303 * given in the D-Bus specification. If you don't want to make
1304 * up an error name just use #DBUS_ERROR_FAILED.
1306 * @param reply_to the message we're replying to
1307 * @param error_name the error name
1308 * @param error_message the error message string (or #NULL for none, but please give a message)
1309 * @returns a new error message object, free with dbus_message_unref()
1312 dbus_message_new_error (DBusMessage *reply_to,
1313 const char *error_name,
1314 const char *error_message)
1316 DBusMessage *message;
1318 DBusMessageIter iter;
1320 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1321 _dbus_return_val_if_fail (error_name != NULL, NULL);
1322 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1324 sender = dbus_message_get_sender (reply_to);
1326 /* sender may be NULL for non-message-bus case or
1327 * when the message bus is dealing with an unregistered
1330 message = dbus_message_new_empty_header ();
1331 if (message == NULL)
1334 if (!_dbus_header_create (&message->header,
1335 DBUS_MESSAGE_TYPE_ERROR,
1336 sender, NULL, NULL, NULL, error_name))
1338 dbus_message_unref (message);
1342 dbus_message_set_no_reply (message, TRUE);
1344 if (!dbus_message_set_reply_serial (message,
1345 dbus_message_get_serial (reply_to)))
1347 dbus_message_unref (message);
1351 if (error_message != NULL)
1353 dbus_message_iter_init_append (message, &iter);
1354 if (!dbus_message_iter_append_basic (&iter,
1358 dbus_message_unref (message);
1367 * Creates a new message that is an error reply to another message, allowing
1368 * you to use printf formatting.
1370 * See dbus_message_new_error() for details - this function is the same
1371 * aside from the printf formatting.
1373 * @todo add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to
1374 * public header, see DBUS_DEPRECATED for an example)
1376 * @param reply_to the original message
1377 * @param error_name the error name
1378 * @param error_format the error message format as with printf
1379 * @param ... format string arguments
1380 * @returns a new error message
1383 dbus_message_new_error_printf (DBusMessage *reply_to,
1384 const char *error_name,
1385 const char *error_format,
1390 DBusMessage *message;
1392 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1393 _dbus_return_val_if_fail (error_name != NULL, NULL);
1394 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1396 if (!_dbus_string_init (&str))
1399 va_start (args, error_format);
1401 if (_dbus_string_append_printf_valist (&str, error_format, args))
1402 message = dbus_message_new_error (reply_to, error_name,
1403 _dbus_string_get_const_data (&str));
1407 _dbus_string_free (&str);
1416 * Creates a new message that is an exact replica of the message
1417 * specified, except that its refcount is set to 1, its message serial
1418 * is reset to 0, and if the original message was "locked" (in the
1419 * outgoing message queue and thus not modifiable) the new message
1420 * will not be locked.
1422 * @todo This function can't be used in programs that try to recover from OOM errors.
1424 * @param message the message
1425 * @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.
1428 dbus_message_copy (const DBusMessage *message)
1430 DBusMessage *retval;
1432 _dbus_return_val_if_fail (message != NULL, NULL);
1434 retval = dbus_new0 (DBusMessage, 1);
1438 retval->refcount.value = 1;
1439 retval->byte_order = message->byte_order;
1440 retval->locked = FALSE;
1441 #ifndef DBUS_DISABLE_CHECKS
1442 retval->generation = message->generation;
1445 if (!_dbus_header_copy (&message->header, &retval->header))
1451 if (!_dbus_string_init_preallocated (&retval->body,
1452 _dbus_string_get_length (&message->body)))
1454 _dbus_header_free (&retval->header);
1459 if (!_dbus_string_copy (&message->body, 0,
1463 #ifdef HAVE_UNIX_FD_PASSING
1464 retval->unix_fds = dbus_new(int, message->n_unix_fds);
1465 if (retval->unix_fds == NULL && message->n_unix_fds > 0)
1468 retval->n_unix_fds_allocated = message->n_unix_fds;
1470 for (retval->n_unix_fds = 0;
1471 retval->n_unix_fds < message->n_unix_fds;
1472 retval->n_unix_fds++)
1474 retval->unix_fds[retval->n_unix_fds] = _dbus_dup(message->unix_fds[retval->n_unix_fds], NULL);
1476 if (retval->unix_fds[retval->n_unix_fds] < 0)
1485 _dbus_header_free (&retval->header);
1486 _dbus_string_free (&retval->body);
1488 #ifdef HAVE_UNIX_FD_PASSING
1489 close_unix_fds(retval->unix_fds, &retval->n_unix_fds);
1490 dbus_free(retval->unix_fds);
1500 * Increments the reference count of a DBusMessage.
1502 * @param message the message
1503 * @returns the message
1504 * @see dbus_message_unref
1507 dbus_message_ref (DBusMessage *message)
1509 dbus_int32_t old_refcount;
1511 _dbus_return_val_if_fail (message != NULL, NULL);
1512 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1513 _dbus_return_val_if_fail (!message->in_cache, NULL);
1515 old_refcount = _dbus_atomic_inc (&message->refcount);
1516 _dbus_assert (old_refcount >= 1);
1522 * Decrements the reference count of a DBusMessage, freeing the
1523 * message if the count reaches 0.
1525 * @param message the message
1526 * @see dbus_message_ref
1529 dbus_message_unref (DBusMessage *message)
1531 dbus_int32_t old_refcount;
1533 _dbus_return_if_fail (message != NULL);
1534 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1535 _dbus_return_if_fail (!message->in_cache);
1537 old_refcount = _dbus_atomic_dec (&message->refcount);
1539 _dbus_assert (old_refcount >= 0);
1541 if (old_refcount == 1)
1543 /* Calls application callbacks! */
1544 dbus_message_cache_or_finalize (message);
1549 * Gets the type of a message. Types include
1550 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1551 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1552 * types are allowed and all code must silently ignore messages of
1553 * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
1555 * @param message the message
1556 * @returns the type of the message
1559 dbus_message_get_type (DBusMessage *message)
1561 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1563 return _dbus_header_get_message_type (&message->header);
1567 * Appends fields to a message given a variable argument list. The
1568 * variable argument list should contain the type of each argument
1569 * followed by the value to append. Appendable types are basic types,
1570 * and arrays of fixed-length basic types. To append variable-length
1571 * basic types, or any more complex value, you have to use an iterator
1572 * rather than this function.
1574 * To append a basic type, specify its type code followed by the
1575 * address of the value. For example:
1579 * dbus_int32_t v_INT32 = 42;
1580 * const char *v_STRING = "Hello World";
1581 * dbus_message_append_args (message,
1582 * DBUS_TYPE_INT32, &v_INT32,
1583 * DBUS_TYPE_STRING, &v_STRING,
1584 * DBUS_TYPE_INVALID);
1587 * To append an array of fixed-length basic types, pass in the
1588 * DBUS_TYPE_ARRAY typecode, the element typecode, the address of
1589 * the array pointer, and a 32-bit integer giving the number of
1590 * elements in the array. So for example:
1592 * const dbus_int32_t array[] = { 1, 2, 3 };
1593 * const dbus_int32_t *v_ARRAY = array;
1594 * dbus_message_append_args (message,
1595 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3,
1596 * DBUS_TYPE_INVALID);
1599 * @warning in C, given "int array[]", "&array == array" (the
1600 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
1601 * So if you're using an array instead of a pointer you have to create
1602 * a pointer variable, assign the array to it, then take the address
1603 * of the pointer variable. For strings it works to write
1604 * const char *array = "Hello" and then use &array though.
1606 * The last argument to this function must be #DBUS_TYPE_INVALID,
1607 * marking the end of the argument list. If you don't do this
1608 * then libdbus won't know to stop and will read invalid memory.
1610 * String/signature/path arrays should be passed in as "const char***
1611 * address_of_array" and "int n_elements"
1613 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1615 * @todo If this fails due to lack of memory, the message is hosed and
1616 * you have to start over building the whole message.
1618 * @param message the message
1619 * @param first_arg_type type of the first argument
1620 * @param ... value of first argument, list of additional type-value pairs
1621 * @returns #TRUE on success
1624 dbus_message_append_args (DBusMessage *message,
1631 _dbus_return_val_if_fail (message != NULL, FALSE);
1633 va_start (var_args, first_arg_type);
1634 retval = dbus_message_append_args_valist (message,
1643 * Like dbus_message_append_args() but takes a va_list for use by language bindings.
1645 * @todo for now, if this function fails due to OOM it will leave
1646 * the message half-written and you have to discard the message
1649 * @see dbus_message_append_args.
1650 * @param message the message
1651 * @param first_arg_type type of first argument
1652 * @param var_args value of first argument, then list of type/value pairs
1653 * @returns #TRUE on success
1656 dbus_message_append_args_valist (DBusMessage *message,
1661 DBusMessageIter iter;
1663 _dbus_return_val_if_fail (message != NULL, FALSE);
1665 type = first_arg_type;
1667 dbus_message_iter_init_append (message, &iter);
1669 while (type != DBUS_TYPE_INVALID)
1671 if (dbus_type_is_basic (type))
1673 const DBusBasicValue *value;
1674 value = va_arg (var_args, const DBusBasicValue*);
1676 if (!dbus_message_iter_append_basic (&iter,
1681 else if (type == DBUS_TYPE_ARRAY)
1684 DBusMessageIter array;
1687 element_type = va_arg (var_args, int);
1689 buf[0] = element_type;
1691 if (!dbus_message_iter_open_container (&iter,
1697 if (dbus_type_is_fixed (element_type) &&
1698 element_type != DBUS_TYPE_UNIX_FD)
1700 const DBusBasicValue **value;
1703 value = va_arg (var_args, const DBusBasicValue**);
1704 n_elements = va_arg (var_args, int);
1706 if (!dbus_message_iter_append_fixed_array (&array,
1712 else if (element_type == DBUS_TYPE_STRING ||
1713 element_type == DBUS_TYPE_SIGNATURE ||
1714 element_type == DBUS_TYPE_OBJECT_PATH)
1716 const char ***value_p;
1721 value_p = va_arg (var_args, const char***);
1722 n_elements = va_arg (var_args, int);
1727 while (i < n_elements)
1729 if (!dbus_message_iter_append_basic (&array,
1738 _dbus_warn ("arrays of %s can't be appended with %s for now\n",
1739 _dbus_type_to_string (element_type),
1740 _DBUS_FUNCTION_NAME);
1744 if (!dbus_message_iter_close_container (&iter, &array))
1747 #ifndef DBUS_DISABLE_CHECKS
1750 _dbus_warn ("type %s isn't supported yet in %s\n",
1751 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
1756 type = va_arg (var_args, int);
1766 * Gets arguments from a message given a variable argument list. The
1767 * supported types include those supported by
1768 * dbus_message_append_args(); that is, basic types and arrays of
1769 * fixed-length basic types. The arguments are the same as they would
1770 * be for dbus_message_iter_get_basic() or
1771 * dbus_message_iter_get_fixed_array().
1773 * In addition to those types, arrays of string, object path, and
1774 * signature are supported; but these are returned as allocated memory
1775 * and must be freed with dbus_free_string_array(), while the other
1776 * types are returned as const references. To get a string array
1777 * pass in "char ***array_location" and "int *n_elements"
1779 * The variable argument list should contain the type of the argument
1780 * followed by a pointer to where the value should be stored. The list
1781 * is terminated with #DBUS_TYPE_INVALID.
1783 * Except for string arrays, the returned values are constant; do not
1784 * free them. They point into the #DBusMessage.
1786 * If the requested arguments are not present, or do not have the
1787 * requested types, then an error will be set.
1789 * If more arguments than requested are present, the requested
1790 * arguments are returned and the extra arguments are ignored.
1792 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1794 * @param message the message
1795 * @param error error to be filled in on failure
1796 * @param first_arg_type the first argument type
1797 * @param ... location for first argument value, then list of type-location pairs
1798 * @returns #FALSE if the error was set
1801 dbus_message_get_args (DBusMessage *message,
1809 _dbus_return_val_if_fail (message != NULL, FALSE);
1810 _dbus_return_val_if_error_is_set (error, FALSE);
1812 va_start (var_args, first_arg_type);
1813 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
1820 * Like dbus_message_get_args but takes a va_list for use by language bindings.
1822 * @see dbus_message_get_args
1823 * @param message the message
1824 * @param error error to be filled in
1825 * @param first_arg_type type of the first argument
1826 * @param var_args return location for first argument, followed by list of type/location pairs
1827 * @returns #FALSE if error was set
1830 dbus_message_get_args_valist (DBusMessage *message,
1835 DBusMessageIter iter;
1837 _dbus_return_val_if_fail (message != NULL, FALSE);
1838 _dbus_return_val_if_error_is_set (error, FALSE);
1840 dbus_message_iter_init (message, &iter);
1841 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
1845 _dbus_message_iter_init_common (DBusMessage *message,
1846 DBusMessageRealIter *real,
1849 _dbus_assert (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
1851 /* Since the iterator will read or write who-knows-what from the
1852 * message, we need to get in the right byte order
1854 ensure_byte_order (message);
1856 real->message = message;
1857 real->changed_stamp = message->changed_stamp;
1858 real->iter_type = iter_type;
1859 real->sig_refcount = 0;
1863 * Initializes a #DBusMessageIter for reading the arguments of the
1864 * message passed in.
1866 * When possible, dbus_message_get_args() is much more convenient.
1867 * Some types of argument can only be read with #DBusMessageIter
1870 * The easiest way to iterate is like this:
1872 * dbus_message_iter_init (message, &iter);
1873 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
1874 * dbus_message_iter_next (&iter);
1877 * #DBusMessageIter contains no allocated memory; it need not be
1878 * freed, and can be copied by assignment or memcpy().
1880 * @param message the message
1881 * @param iter pointer to an iterator to initialize
1882 * @returns #FALSE if the message has no arguments
1885 dbus_message_iter_init (DBusMessage *message,
1886 DBusMessageIter *iter)
1888 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1889 const DBusString *type_str;
1892 _dbus_return_val_if_fail (message != NULL, FALSE);
1893 _dbus_return_val_if_fail (iter != NULL, FALSE);
1895 get_const_signature (&message->header, &type_str, &type_pos);
1897 _dbus_message_iter_init_common (message, real,
1898 DBUS_MESSAGE_ITER_TYPE_READER);
1900 _dbus_type_reader_init (&real->u.reader,
1901 message->byte_order,
1906 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
1910 * Checks if an iterator has any more fields.
1912 * @param iter the message iter
1913 * @returns #TRUE if there are more fields following
1916 dbus_message_iter_has_next (DBusMessageIter *iter)
1918 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1920 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
1921 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
1923 return _dbus_type_reader_has_next (&real->u.reader);
1927 * Moves the iterator to the next field, if any. If there's no next
1928 * field, returns #FALSE. If the iterator moves forward, returns
1931 * @param iter the message iter
1932 * @returns #TRUE if the iterator was moved to the next field
1935 dbus_message_iter_next (DBusMessageIter *iter)
1937 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1939 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
1940 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
1942 return _dbus_type_reader_next (&real->u.reader);
1946 * Returns the argument type of the argument that the message iterator
1947 * points to. If the iterator is at the end of the message, returns
1948 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
1951 * dbus_message_iter_init (&iter);
1952 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
1953 * dbus_message_iter_next (&iter);
1956 * @param iter the message iter
1957 * @returns the argument type
1960 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
1962 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1964 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
1965 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
1967 return _dbus_type_reader_get_current_type (&real->u.reader);
1971 * Returns the element type of the array that the message iterator
1972 * points to. Note that you need to check that the iterator points to
1973 * an array prior to using this function.
1975 * @param iter the message iter
1976 * @returns the array element type
1979 dbus_message_iter_get_element_type (DBusMessageIter *iter)
1981 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1983 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
1984 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
1985 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
1987 return _dbus_type_reader_get_element_type (&real->u.reader);
1991 * Recurses into a container value when reading values from a message,
1992 * initializing a sub-iterator to use for traversing the child values
1995 * Note that this recurses into a value, not a type, so you can only
1996 * recurse if the value exists. The main implication of this is that
1997 * if you have for example an empty array of array of int32, you can
1998 * recurse into the outermost array, but it will have no values, so
1999 * you won't be able to recurse further. There's no array of int32 to
2002 * If a container is an array of fixed-length types, it is much more
2003 * efficient to use dbus_message_iter_get_fixed_array() to get the
2004 * whole array in one shot, rather than individually walking over the
2007 * Be sure you have somehow checked that
2008 * dbus_message_iter_get_arg_type() matches the type you are expecting
2009 * to recurse into. Results of this function are undefined if there is
2010 * no container to recurse into at the current iterator position.
2012 * @param iter the message iterator
2013 * @param sub the sub-iterator to initialize
2016 dbus_message_iter_recurse (DBusMessageIter *iter,
2017 DBusMessageIter *sub)
2019 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2020 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2022 _dbus_return_if_fail (_dbus_message_iter_check (real));
2023 _dbus_return_if_fail (sub != NULL);
2026 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
2030 * Returns the current signature of a message iterator. This
2031 * is useful primarily for dealing with variants; one can
2032 * recurse into a variant and determine the signature of
2033 * the variant's value.
2035 * The returned string must be freed with dbus_free().
2037 * @param iter the message iterator
2038 * @returns the contained signature, or NULL if out of memory
2041 dbus_message_iter_get_signature (DBusMessageIter *iter)
2043 const DBusString *sig;
2047 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2049 _dbus_return_val_if_fail (_dbus_message_iter_check (real), NULL);
2051 if (!_dbus_string_init (&retstr))
2054 _dbus_type_reader_get_signature (&real->u.reader, &sig,
2056 if (!_dbus_string_append_len (&retstr,
2057 _dbus_string_get_const_data (sig) + start,
2060 if (!_dbus_string_steal_data (&retstr, &ret))
2062 _dbus_string_free (&retstr);
2067 * Reads a basic-typed value from the message iterator.
2068 * Basic types are the non-containers such as integer and string.
2070 * The value argument should be the address of a location to store
2071 * the returned value. So for int32 it should be a "dbus_int32_t*"
2072 * and for string a "const char**". The returned value is
2073 * by reference and should not be freed.
2075 * Be sure you have somehow checked that
2076 * dbus_message_iter_get_arg_type() matches the type you are
2077 * expecting, or you'll crash when you try to use an integer as a
2078 * string or something.
2080 * To read any container type (array, struct, dict) you will need
2081 * to recurse into the container with dbus_message_iter_recurse().
2082 * If the container is an array of fixed-length values, you can
2083 * get all the array elements at once with
2084 * dbus_message_iter_get_fixed_array(). Otherwise, you have to
2085 * iterate over the container's contents one value at a time.
2087 * All basic-typed values are guaranteed to fit in 8 bytes. So you can
2088 * write code like this:
2091 * dbus_uint64_t value;
2093 * dbus_message_iter_get_basic (&read_iter, &value);
2094 * type = dbus_message_iter_get_arg_type (&read_iter);
2095 * dbus_message_iter_append_basic (&write_iter, type, &value);
2098 * On some really obscure platforms dbus_uint64_t might not exist, if
2099 * you need to worry about this you will know. dbus_uint64_t is just
2100 * one example of a type that's large enough to hold any possible
2101 * value, you could use a struct or char[8] instead if you like.
2103 * @param iter the iterator
2104 * @param value location to store the value
2107 dbus_message_iter_get_basic (DBusMessageIter *iter,
2110 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2112 _dbus_return_if_fail (_dbus_message_iter_check (real));
2113 _dbus_return_if_fail (value != NULL);
2115 if (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_UNIX_FD)
2117 #ifdef HAVE_UNIX_FD_PASSING
2120 _dbus_type_reader_read_basic(&real->u.reader, &idx);
2122 if (idx.u32 >= real->message->n_unix_fds) {
2123 /* Hmm, we cannot really signal an error here, so let's make
2124 sure to return an invalid fd. */
2125 *((int*) value) = -1;
2129 *((int*) value) = _dbus_dup(real->message->unix_fds[idx.u32], NULL);
2131 *((int*) value) = -1;
2136 _dbus_type_reader_read_basic (&real->u.reader,
2142 * Returns the number of bytes in the array as marshaled in the wire
2143 * protocol. The iterator must currently be inside an array-typed
2146 * This function is deprecated on the grounds that it is stupid. Why
2147 * would you want to know how many bytes are in the array as marshaled
2148 * in the wire protocol? For now, use the n_elements returned from
2149 * dbus_message_iter_get_fixed_array() instead, or iterate over the
2150 * array values and count them.
2152 * @todo introduce a variant of this get_n_elements that returns
2153 * the number of elements, though with a non-fixed array it will not
2154 * be very efficient, so maybe it's not good.
2156 * @param iter the iterator
2157 * @returns the number of bytes in the array
2160 dbus_message_iter_get_array_len (DBusMessageIter *iter)
2162 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2164 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2166 return _dbus_type_reader_get_array_length (&real->u.reader);
2170 * Reads a block of fixed-length values from the message iterator.
2171 * Fixed-length values are those basic types that are not string-like,
2172 * such as integers, bool, double. The returned block will be from the
2173 * current position in the array until the end of the array.
2175 * The message iter should be "in" the array (that is, you recurse into the
2176 * array, and then you call dbus_message_iter_get_fixed_array() on the
2177 * "sub-iterator" created by dbus_message_iter_recurse()).
2179 * The value argument should be the address of a location to store the
2180 * returned array. So for int32 it should be a "const dbus_int32_t**"
2181 * The returned value is by reference and should not be freed.
2183 * This function should only be used if dbus_type_is_fixed() returns
2184 * #TRUE for the element type.
2186 * If an array's elements are not fixed in size, you have to recurse
2187 * into the array with dbus_message_iter_recurse() and read the
2188 * elements one by one.
2190 * Because the array is not copied, this function runs in constant
2191 * time and is fast; it's much preferred over walking the entire array
2192 * with an iterator. (However, you can always use
2193 * dbus_message_iter_recurse(), even for fixed-length types;
2194 * dbus_message_iter_get_fixed_array() is just an optimization.)
2196 * @param iter the iterator
2197 * @param value location to store the block
2198 * @param n_elements number of elements in the block
2201 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
2205 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2206 int subtype = _dbus_type_reader_get_current_type(&real->u.reader);
2208 _dbus_return_if_fail (_dbus_message_iter_check (real));
2209 _dbus_return_if_fail (value != NULL);
2210 _dbus_return_if_fail ((subtype == DBUS_TYPE_INVALID) ||
2211 (dbus_type_is_fixed (subtype) && subtype != DBUS_TYPE_UNIX_FD));
2213 _dbus_type_reader_read_fixed_multi (&real->u.reader,
2218 * Initializes a #DBusMessageIter for appending arguments to the end
2221 * @todo If appending any of the arguments fails due to lack of
2222 * memory, the message is hosed and you have to start over building
2223 * the whole message.
2225 * @param message the message
2226 * @param iter pointer to an iterator to initialize
2229 dbus_message_iter_init_append (DBusMessage *message,
2230 DBusMessageIter *iter)
2232 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2234 _dbus_return_if_fail (message != NULL);
2235 _dbus_return_if_fail (iter != NULL);
2237 _dbus_message_iter_init_common (message, real,
2238 DBUS_MESSAGE_ITER_TYPE_WRITER);
2240 /* We create the signature string and point iterators at it "on demand"
2241 * when a value is actually appended. That means that init() never fails
2244 _dbus_type_writer_init_types_delayed (&real->u.writer,
2245 message->byte_order,
2247 _dbus_string_get_length (&message->body));
2251 * Creates a temporary signature string containing the current
2252 * signature, stores it in the iterator, and points the iterator to
2253 * the end of it. Used any time we write to the message.
2255 * @param real an iterator without a type_str
2256 * @returns #FALSE if no memory
2259 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
2262 const DBusString *current_sig;
2263 int current_sig_pos;
2265 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2267 if (real->u.writer.type_str != NULL)
2269 _dbus_assert (real->sig_refcount > 0);
2270 real->sig_refcount += 1;
2274 str = dbus_new (DBusString, 1);
2278 if (!_dbus_header_get_field_raw (&real->message->header,
2279 DBUS_HEADER_FIELD_SIGNATURE,
2280 ¤t_sig, ¤t_sig_pos))
2287 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
2288 current_sig_pos += 1; /* move on to sig data */
2290 if (!_dbus_string_init_preallocated (str, current_len + 4))
2296 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
2299 _dbus_string_free (str);
2306 if (!_dbus_string_init_preallocated (str, 4))
2313 real->sig_refcount = 1;
2315 _dbus_type_writer_add_types (&real->u.writer,
2316 str, _dbus_string_get_length (str));
2321 * Sets the new signature as the message signature, frees the
2322 * signature string, and marks the iterator as not having a type_str
2323 * anymore. Frees the signature even if it fails, so you can't
2324 * really recover from failure. Kinda busted.
2326 * @param real an iterator without a type_str
2327 * @returns #FALSE if no memory
2330 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2333 const char *v_STRING;
2336 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2337 _dbus_assert (real->u.writer.type_str != NULL);
2338 _dbus_assert (real->sig_refcount > 0);
2340 real->sig_refcount -= 1;
2342 if (real->sig_refcount > 0)
2344 _dbus_assert (real->sig_refcount == 0);
2348 str = real->u.writer.type_str;
2350 v_STRING = _dbus_string_get_const_data (str);
2351 if (!_dbus_header_set_field_basic (&real->message->header,
2352 DBUS_HEADER_FIELD_SIGNATURE,
2353 DBUS_TYPE_SIGNATURE,
2357 _dbus_type_writer_remove_types (&real->u.writer);
2358 _dbus_string_free (str);
2364 #ifndef DBUS_DISABLE_CHECKS
2366 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2368 if (!_dbus_message_iter_check (iter))
2371 if (iter->message->locked)
2373 _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)\n");
2379 #endif /* DBUS_DISABLE_CHECKS */
2381 #ifdef HAVE_UNIX_FD_PASSING
2383 expand_fd_array(DBusMessage *m,
2388 /* This makes space for adding n new fds to the array and returns a
2389 pointer to the place were the first fd should be put. */
2391 if (m->n_unix_fds + n > m->n_unix_fds_allocated)
2396 /* Make twice as much space as necessary */
2397 k = (m->n_unix_fds + n) * 2;
2399 /* Allocate at least four */
2403 p = dbus_realloc(m->unix_fds, k * sizeof(int));
2408 m->n_unix_fds_allocated = k;
2411 return m->unix_fds + m->n_unix_fds;
2416 * Appends a basic-typed value to the message. The basic types are the
2417 * non-container types such as integer and string.
2419 * The "value" argument should be the address of a basic-typed value.
2420 * So for string, const char**. For integer, dbus_int32_t*.
2422 * @todo If this fails due to lack of memory, the message is hosed and
2423 * you have to start over building the whole message.
2425 * @param iter the append iterator
2426 * @param type the type of the value
2427 * @param value the address of the value
2428 * @returns #FALSE if not enough memory
2431 dbus_message_iter_append_basic (DBusMessageIter *iter,
2435 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2438 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2439 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2440 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2441 _dbus_return_val_if_fail (value != NULL, FALSE);
2443 if (!_dbus_message_iter_open_signature (real))
2446 if (type == DBUS_TYPE_UNIX_FD)
2448 #ifdef HAVE_UNIX_FD_PASSING
2452 /* First step, include the fd in the fd list of this message */
2453 if (!(fds = expand_fd_array(real->message, 1)))
2456 *fds = _dbus_dup(*(int*) value, NULL);
2460 u = real->message->n_unix_fds;
2462 /* Second step, write the index to the fd */
2463 if (!(ret = _dbus_type_writer_write_basic (&real->u.writer, DBUS_TYPE_UNIX_FD, &u))) {
2464 _dbus_close(*fds, NULL);
2468 real->message->n_unix_fds += 1;
2471 /* Final step, update the header accordingly */
2472 ret = _dbus_header_set_field_basic (&real->message->header,
2473 DBUS_HEADER_FIELD_UNIX_FDS,
2477 /* If any of these operations fail the message is
2478 hosed. However, no memory or fds should be leaked since what
2479 has been added to message has been added to the message, and
2480 can hence be accounted for when the message is being
2488 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
2491 if (!_dbus_message_iter_close_signature (real))
2498 * Appends a block of fixed-length values to an array. The
2499 * fixed-length types are all basic types that are not string-like. So
2500 * int32, double, bool, etc. You must call
2501 * dbus_message_iter_open_container() to open an array of values
2502 * before calling this function. You may call this function multiple
2503 * times (and intermixed with calls to
2504 * dbus_message_iter_append_basic()) for the same array.
2506 * The "value" argument should be the address of the array. So for
2507 * integer, "dbus_int32_t**" is expected for example.
2509 * @warning in C, given "int array[]", "&array == array" (the
2510 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2511 * So if you're using an array instead of a pointer you have to create
2512 * a pointer variable, assign the array to it, then take the address
2513 * of the pointer variable.
2515 * const dbus_int32_t array[] = { 1, 2, 3 };
2516 * const dbus_int32_t *v_ARRAY = array;
2517 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
2518 * fprintf (stderr, "No memory!\n");
2520 * For strings it works to write const char *array = "Hello" and then
2521 * use &array though.
2523 * @todo If this fails due to lack of memory, the message is hosed and
2524 * you have to start over building the whole message.
2526 * @param iter the append iterator
2527 * @param element_type the type of the array elements
2528 * @param value the address of the array
2529 * @param n_elements the number of elements to append
2530 * @returns #FALSE if not enough memory
2533 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
2538 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2541 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2542 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2543 _dbus_return_val_if_fail (dbus_type_is_fixed (element_type) && element_type != DBUS_TYPE_UNIX_FD, FALSE);
2544 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
2545 _dbus_return_val_if_fail (value != NULL, FALSE);
2546 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
2547 _dbus_return_val_if_fail (n_elements <=
2548 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
2551 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
2557 * Appends a container-typed value to the message; you are required to
2558 * append the contents of the container using the returned
2559 * sub-iterator, and then call
2560 * dbus_message_iter_close_container(). Container types are for
2561 * example struct, variant, and array. For variants, the
2562 * contained_signature should be the type of the single value inside
2563 * the variant. For structs and dict entries, contained_signature
2564 * should be #NULL; it will be set to whatever types you write into
2565 * the struct. For arrays, contained_signature should be the type of
2566 * the array elements.
2568 * @todo If this fails due to lack of memory, the message is hosed and
2569 * you have to start over building the whole message.
2571 * @param iter the append iterator
2572 * @param type the type of the value
2573 * @param contained_signature the type of container contents
2574 * @param sub sub-iterator to initialize
2575 * @returns #FALSE if not enough memory
2578 dbus_message_iter_open_container (DBusMessageIter *iter,
2580 const char *contained_signature,
2581 DBusMessageIter *sub)
2583 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2584 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2585 DBusString contained_str;
2587 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2588 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2589 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
2590 _dbus_return_val_if_fail (sub != NULL, FALSE);
2591 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
2592 contained_signature == NULL) ||
2593 (type == DBUS_TYPE_DICT_ENTRY &&
2594 contained_signature == NULL) ||
2595 (type == DBUS_TYPE_VARIANT &&
2596 contained_signature != NULL) ||
2597 (type == DBUS_TYPE_ARRAY &&
2598 contained_signature != NULL), FALSE);
2600 /* this would fail if the contained_signature is a dict entry, since
2601 * dict entries are invalid signatures standalone (they must be in
2604 _dbus_return_val_if_fail ((type == DBUS_TYPE_ARRAY && contained_signature && *contained_signature == DBUS_DICT_ENTRY_BEGIN_CHAR) ||
2605 (contained_signature == NULL ||
2606 _dbus_check_is_valid_signature (contained_signature)),
2609 if (!_dbus_message_iter_open_signature (real))
2614 if (contained_signature != NULL)
2616 _dbus_string_init_const (&contained_str, contained_signature);
2618 return _dbus_type_writer_recurse (&real->u.writer,
2621 &real_sub->u.writer);
2625 return _dbus_type_writer_recurse (&real->u.writer,
2628 &real_sub->u.writer);
2634 * Closes a container-typed value appended to the message; may write
2635 * out more information to the message known only after the entire
2636 * container is written, and may free resources created by
2637 * dbus_message_iter_open_container().
2639 * @todo If this fails due to lack of memory, the message is hosed and
2640 * you have to start over building the whole message.
2642 * @param iter the append iterator
2643 * @param sub sub-iterator to close
2644 * @returns #FALSE if not enough memory
2647 dbus_message_iter_close_container (DBusMessageIter *iter,
2648 DBusMessageIter *sub)
2650 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2651 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2654 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2655 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2656 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
2657 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2659 ret = _dbus_type_writer_unrecurse (&real->u.writer,
2660 &real_sub->u.writer);
2662 if (!_dbus_message_iter_close_signature (real))
2669 * Sets a flag indicating that the message does not want a reply; if
2670 * this flag is set, the other end of the connection may (but is not
2671 * required to) optimize by not sending method return or error
2672 * replies. If this flag is set, there is no way to know whether the
2673 * message successfully arrived at the remote end. Normally you know a
2674 * message was received when you receive the reply to it.
2676 * The flag is #FALSE by default, that is by default the other end is
2677 * required to reply.
2679 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
2681 * @param message the message
2682 * @param no_reply #TRUE if no reply is desired
2685 dbus_message_set_no_reply (DBusMessage *message,
2686 dbus_bool_t no_reply)
2688 _dbus_return_if_fail (message != NULL);
2689 _dbus_return_if_fail (!message->locked);
2691 _dbus_header_toggle_flag (&message->header,
2692 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
2697 * Returns #TRUE if the message does not expect
2700 * @param message the message
2701 * @returns #TRUE if the message sender isn't waiting for a reply
2704 dbus_message_get_no_reply (DBusMessage *message)
2706 _dbus_return_val_if_fail (message != NULL, FALSE);
2708 return _dbus_header_get_flag (&message->header,
2709 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
2713 * Sets a flag indicating that an owner for the destination name will
2714 * be automatically started before the message is delivered. When this
2715 * flag is set, the message is held until a name owner finishes
2716 * starting up, or fails to start up. In case of failure, the reply
2719 * The flag is set to #TRUE by default, i.e. auto starting is the default.
2721 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
2723 * @param message the message
2724 * @param auto_start #TRUE if auto-starting is desired
2727 dbus_message_set_auto_start (DBusMessage *message,
2728 dbus_bool_t auto_start)
2730 _dbus_return_if_fail (message != NULL);
2731 _dbus_return_if_fail (!message->locked);
2733 _dbus_header_toggle_flag (&message->header,
2734 DBUS_HEADER_FLAG_NO_AUTO_START,
2739 * Returns #TRUE if the message will cause an owner for
2740 * destination name to be auto-started.
2742 * @param message the message
2743 * @returns #TRUE if the message will use auto-start
2746 dbus_message_get_auto_start (DBusMessage *message)
2748 _dbus_return_val_if_fail (message != NULL, FALSE);
2750 return !_dbus_header_get_flag (&message->header,
2751 DBUS_HEADER_FLAG_NO_AUTO_START);
2756 * Sets the object path this message is being sent to (for
2757 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
2758 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
2760 * The path must contain only valid characters as defined
2761 * in the D-Bus specification.
2763 * @param message the message
2764 * @param object_path the path or #NULL to unset
2765 * @returns #FALSE if not enough memory
2768 dbus_message_set_path (DBusMessage *message,
2769 const char *object_path)
2771 _dbus_return_val_if_fail (message != NULL, FALSE);
2772 _dbus_return_val_if_fail (!message->locked, FALSE);
2773 _dbus_return_val_if_fail (object_path == NULL ||
2774 _dbus_check_is_valid_path (object_path),
2777 return set_or_delete_string_field (message,
2778 DBUS_HEADER_FIELD_PATH,
2779 DBUS_TYPE_OBJECT_PATH,
2784 * Gets the object path this message is being sent to (for
2785 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
2786 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
2788 * See also dbus_message_get_path_decomposed().
2790 * The returned string becomes invalid if the message is
2791 * modified, since it points into the wire-marshaled message data.
2793 * @param message the message
2794 * @returns the path (should not be freed) or #NULL
2797 dbus_message_get_path (DBusMessage *message)
2801 _dbus_return_val_if_fail (message != NULL, NULL);
2803 v = NULL; /* in case field doesn't exist */
2804 _dbus_header_get_field_basic (&message->header,
2805 DBUS_HEADER_FIELD_PATH,
2806 DBUS_TYPE_OBJECT_PATH,
2812 * Checks if the message has a particular object path. The object
2813 * path is the destination object for a method call or the emitting
2814 * object for a signal.
2816 * @param message the message
2817 * @param path the path name
2818 * @returns #TRUE if there is a path field in the header
2821 dbus_message_has_path (DBusMessage *message,
2824 const char *msg_path;
2825 msg_path = dbus_message_get_path (message);
2827 if (msg_path == NULL)
2838 if (strcmp (msg_path, path) == 0)
2845 * Gets the object path this message is being sent to
2846 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
2847 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
2848 * format (one array element per path component).
2849 * Free the returned array with dbus_free_string_array().
2851 * An empty but non-NULL path array means the path "/".
2852 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
2853 * and the path "/" becomes { NULL }.
2855 * See also dbus_message_get_path().
2857 * @todo this could be optimized by using the len from the message
2858 * instead of calling strlen() again
2860 * @param message the message
2861 * @param path place to store allocated array of path components; #NULL set here if no path field exists
2862 * @returns #FALSE if no memory to allocate the array
2865 dbus_message_get_path_decomposed (DBusMessage *message,
2870 _dbus_return_val_if_fail (message != NULL, FALSE);
2871 _dbus_return_val_if_fail (path != NULL, FALSE);
2875 v = dbus_message_get_path (message);
2878 if (!_dbus_decompose_path (v, strlen (v),
2886 * Sets the interface this message is being sent to
2887 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
2888 * the interface a signal is being emitted from
2889 * (for DBUS_MESSAGE_TYPE_SIGNAL).
2891 * The interface name must contain only valid characters as defined
2892 * in the D-Bus specification.
2894 * @param message the message
2895 * @param interface the interface or #NULL to unset
2896 * @returns #FALSE if not enough memory
2899 dbus_message_set_interface (DBusMessage *message,
2900 const char *interface)
2902 _dbus_return_val_if_fail (message != NULL, FALSE);
2903 _dbus_return_val_if_fail (!message->locked, FALSE);
2904 _dbus_return_val_if_fail (interface == NULL ||
2905 _dbus_check_is_valid_interface (interface),
2908 return set_or_delete_string_field (message,
2909 DBUS_HEADER_FIELD_INTERFACE,
2915 * Gets the interface this message is being sent to
2916 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
2917 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
2918 * The interface name is fully-qualified (namespaced).
2919 * Returns #NULL if none.
2921 * The returned string becomes invalid if the message is
2922 * modified, since it points into the wire-marshaled message data.
2924 * @param message the message
2925 * @returns the message interface (should not be freed) or #NULL
2928 dbus_message_get_interface (DBusMessage *message)
2932 _dbus_return_val_if_fail (message != NULL, NULL);
2934 v = NULL; /* in case field doesn't exist */
2935 _dbus_header_get_field_basic (&message->header,
2936 DBUS_HEADER_FIELD_INTERFACE,
2943 * Checks if the message has an interface
2945 * @param message the message
2946 * @param interface the interface name
2947 * @returns #TRUE if the interface field in the header matches
2950 dbus_message_has_interface (DBusMessage *message,
2951 const char *interface)
2953 const char *msg_interface;
2954 msg_interface = dbus_message_get_interface (message);
2956 if (msg_interface == NULL)
2958 if (interface == NULL)
2964 if (interface == NULL)
2967 if (strcmp (msg_interface, interface) == 0)
2975 * Sets the interface member being invoked
2976 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
2977 * (DBUS_MESSAGE_TYPE_SIGNAL).
2979 * The member name must contain only valid characters as defined
2980 * in the D-Bus specification.
2982 * @param message the message
2983 * @param member the member or #NULL to unset
2984 * @returns #FALSE if not enough memory
2987 dbus_message_set_member (DBusMessage *message,
2990 _dbus_return_val_if_fail (message != NULL, FALSE);
2991 _dbus_return_val_if_fail (!message->locked, FALSE);
2992 _dbus_return_val_if_fail (member == NULL ||
2993 _dbus_check_is_valid_member (member),
2996 return set_or_delete_string_field (message,
2997 DBUS_HEADER_FIELD_MEMBER,
3003 * Gets the interface member being invoked
3004 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3005 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3007 * The returned string becomes invalid if the message is
3008 * modified, since it points into the wire-marshaled message data.
3010 * @param message the message
3011 * @returns the member name (should not be freed) or #NULL
3014 dbus_message_get_member (DBusMessage *message)
3018 _dbus_return_val_if_fail (message != NULL, NULL);
3020 v = NULL; /* in case field doesn't exist */
3021 _dbus_header_get_field_basic (&message->header,
3022 DBUS_HEADER_FIELD_MEMBER,
3029 * Checks if the message has an interface member
3031 * @param message the message
3032 * @param member the member name
3033 * @returns #TRUE if there is a member field in the header
3036 dbus_message_has_member (DBusMessage *message,
3039 const char *msg_member;
3040 msg_member = dbus_message_get_member (message);
3042 if (msg_member == NULL)
3053 if (strcmp (msg_member, member) == 0)
3061 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
3062 * The name is fully-qualified (namespaced).
3064 * The error name must contain only valid characters as defined
3065 * in the D-Bus specification.
3067 * @param message the message
3068 * @param error_name the name or #NULL to unset
3069 * @returns #FALSE if not enough memory
3072 dbus_message_set_error_name (DBusMessage *message,
3073 const char *error_name)
3075 _dbus_return_val_if_fail (message != NULL, FALSE);
3076 _dbus_return_val_if_fail (!message->locked, FALSE);
3077 _dbus_return_val_if_fail (error_name == NULL ||
3078 _dbus_check_is_valid_error_name (error_name),
3081 return set_or_delete_string_field (message,
3082 DBUS_HEADER_FIELD_ERROR_NAME,
3088 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
3091 * The returned string becomes invalid if the message is
3092 * modified, since it points into the wire-marshaled message data.
3094 * @param message the message
3095 * @returns the error name (should not be freed) or #NULL
3098 dbus_message_get_error_name (DBusMessage *message)
3102 _dbus_return_val_if_fail (message != NULL, NULL);
3104 v = NULL; /* in case field doesn't exist */
3105 _dbus_header_get_field_basic (&message->header,
3106 DBUS_HEADER_FIELD_ERROR_NAME,
3113 * Sets the message's destination. The destination is the name of
3114 * another connection on the bus and may be either the unique name
3115 * assigned by the bus to each connection, or a well-known name
3116 * specified in advance.
3118 * The destination name must contain only valid characters as defined
3119 * in the D-Bus specification.
3121 * @param message the message
3122 * @param destination the destination name or #NULL to unset
3123 * @returns #FALSE if not enough memory
3126 dbus_message_set_destination (DBusMessage *message,
3127 const char *destination)
3129 _dbus_return_val_if_fail (message != NULL, FALSE);
3130 _dbus_return_val_if_fail (!message->locked, FALSE);
3131 _dbus_return_val_if_fail (destination == NULL ||
3132 _dbus_check_is_valid_bus_name (destination),
3135 return set_or_delete_string_field (message,
3136 DBUS_HEADER_FIELD_DESTINATION,
3142 * Gets the destination of a message or #NULL if there is none set.
3144 * The returned string becomes invalid if the message is
3145 * modified, since it points into the wire-marshaled message data.
3147 * @param message the message
3148 * @returns the message destination (should not be freed) or #NULL
3151 dbus_message_get_destination (DBusMessage *message)
3155 _dbus_return_val_if_fail (message != NULL, NULL);
3157 v = NULL; /* in case field doesn't exist */
3158 _dbus_header_get_field_basic (&message->header,
3159 DBUS_HEADER_FIELD_DESTINATION,
3166 * Sets the message sender.
3168 * The sender must be a valid bus name as defined in the D-Bus
3171 * Usually you don't want to call this. The message bus daemon will
3172 * call it to set the origin of each message. If you aren't implementing
3173 * a message bus daemon you shouldn't need to set the sender.
3175 * @param message the message
3176 * @param sender the sender or #NULL to unset
3177 * @returns #FALSE if not enough memory
3180 dbus_message_set_sender (DBusMessage *message,
3183 _dbus_return_val_if_fail (message != NULL, FALSE);
3184 _dbus_return_val_if_fail (!message->locked, FALSE);
3185 _dbus_return_val_if_fail (sender == NULL ||
3186 _dbus_check_is_valid_bus_name (sender),
3189 return set_or_delete_string_field (message,
3190 DBUS_HEADER_FIELD_SENDER,
3196 * Gets the unique name of the connection which originated this
3197 * message, or #NULL if unknown or inapplicable. The sender is filled
3198 * in by the message bus.
3200 * Note, the returned sender is always the unique bus name.
3201 * Connections may own multiple other bus names, but those
3202 * are not found in the sender field.
3204 * The returned string becomes invalid if the message is
3205 * modified, since it points into the wire-marshaled message data.
3207 * @param message the message
3208 * @returns the unique name of the sender or #NULL
3211 dbus_message_get_sender (DBusMessage *message)
3215 _dbus_return_val_if_fail (message != NULL, NULL);
3217 v = NULL; /* in case field doesn't exist */
3218 _dbus_header_get_field_basic (&message->header,
3219 DBUS_HEADER_FIELD_SENDER,
3226 * Gets the type signature of the message, i.e. the arguments in the
3227 * message payload. The signature includes only "in" arguments for
3228 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
3229 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
3230 * what you might expect (that is, it does not include the signature of the
3231 * entire C++-style method).
3233 * The signature is a string made up of type codes such as
3234 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
3235 * the value of #DBUS_TYPE_INVALID).
3237 * The returned string becomes invalid if the message is
3238 * modified, since it points into the wire-marshaled message data.
3240 * @param message the message
3241 * @returns the type signature
3244 dbus_message_get_signature (DBusMessage *message)
3246 const DBusString *type_str;
3249 _dbus_return_val_if_fail (message != NULL, NULL);
3251 get_const_signature (&message->header, &type_str, &type_pos);
3253 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
3257 _dbus_message_has_type_interface_member (DBusMessage *message,
3259 const char *interface,
3264 _dbus_assert (message != NULL);
3265 _dbus_assert (interface != NULL);
3266 _dbus_assert (member != NULL);
3268 if (dbus_message_get_type (message) != type)
3271 /* Optimize by checking the short member name first
3272 * instead of the longer interface name
3275 n = dbus_message_get_member (message);
3277 if (n && strcmp (n, member) == 0)
3279 n = dbus_message_get_interface (message);
3281 if (n == NULL || strcmp (n, interface) == 0)
3289 * Checks whether the message is a method call with the given
3290 * interface and member fields. If the message is not
3291 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
3292 * member field, returns #FALSE. If the interface field is missing,
3293 * then it will be assumed equal to the provided interface. The D-Bus
3294 * protocol allows method callers to leave out the interface name.
3296 * @param message the message
3297 * @param interface the name to check (must not be #NULL)
3298 * @param method the name to check (must not be #NULL)
3300 * @returns #TRUE if the message is the specified method call
3303 dbus_message_is_method_call (DBusMessage *message,
3304 const char *interface,
3307 _dbus_return_val_if_fail (message != NULL, FALSE);
3308 _dbus_return_val_if_fail (interface != NULL, FALSE);
3309 _dbus_return_val_if_fail (method != NULL, FALSE);
3310 /* don't check that interface/method are valid since it would be
3311 * expensive, and not catch many common errors
3314 return _dbus_message_has_type_interface_member (message,
3315 DBUS_MESSAGE_TYPE_METHOD_CALL,
3320 * Checks whether the message is a signal with the given interface and
3321 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
3322 * has a different interface or member field, returns #FALSE.
3324 * @param message the message
3325 * @param interface the name to check (must not be #NULL)
3326 * @param signal_name the name to check (must not be #NULL)
3328 * @returns #TRUE if the message is the specified signal
3331 dbus_message_is_signal (DBusMessage *message,
3332 const char *interface,
3333 const char *signal_name)
3335 _dbus_return_val_if_fail (message != NULL, FALSE);
3336 _dbus_return_val_if_fail (interface != NULL, FALSE);
3337 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
3338 /* don't check that interface/name are valid since it would be
3339 * expensive, and not catch many common errors
3342 return _dbus_message_has_type_interface_member (message,
3343 DBUS_MESSAGE_TYPE_SIGNAL,
3344 interface, signal_name);
3348 * Checks whether the message is an error reply with the given error
3349 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
3350 * different name, returns #FALSE.
3352 * @param message the message
3353 * @param error_name the name to check (must not be #NULL)
3355 * @returns #TRUE if the message is the specified error
3358 dbus_message_is_error (DBusMessage *message,
3359 const char *error_name)
3363 _dbus_return_val_if_fail (message != NULL, FALSE);
3364 _dbus_return_val_if_fail (error_name != NULL, FALSE);
3365 /* don't check that error_name is valid since it would be expensive,
3366 * and not catch many common errors
3369 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3372 n = dbus_message_get_error_name (message);
3374 if (n && strcmp (n, error_name) == 0)
3381 * Checks whether the message was sent to the given name. If the
3382 * message has no destination specified or has a different
3383 * destination, returns #FALSE.
3385 * @param message the message
3386 * @param name the name to check (must not be #NULL)
3388 * @returns #TRUE if the message has the given destination name
3391 dbus_message_has_destination (DBusMessage *message,
3396 _dbus_return_val_if_fail (message != NULL, FALSE);
3397 _dbus_return_val_if_fail (name != NULL, FALSE);
3398 /* don't check that name is valid since it would be expensive, and
3399 * not catch many common errors
3402 s = dbus_message_get_destination (message);
3404 if (s && strcmp (s, name) == 0)
3411 * Checks whether the message has the given unique name as its sender.
3412 * If the message has no sender specified or has a different sender,
3413 * returns #FALSE. Note that a peer application will always have the
3414 * unique name of the connection as the sender. So you can't use this
3415 * function to see whether a sender owned a well-known name.
3417 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
3420 * @param message the message
3421 * @param name the name to check (must not be #NULL)
3423 * @returns #TRUE if the message has the given sender
3426 dbus_message_has_sender (DBusMessage *message,
3431 _dbus_return_val_if_fail (message != NULL, FALSE);
3432 _dbus_return_val_if_fail (name != NULL, FALSE);
3433 /* don't check that name is valid since it would be expensive, and
3434 * not catch many common errors
3437 s = dbus_message_get_sender (message);
3439 if (s && strcmp (s, name) == 0)
3446 * Checks whether the message has the given signature; see
3447 * dbus_message_get_signature() for more details on what the signature
3450 * @param message the message
3451 * @param signature typecode array
3452 * @returns #TRUE if message has the given signature
3455 dbus_message_has_signature (DBusMessage *message,
3456 const char *signature)
3460 _dbus_return_val_if_fail (message != NULL, FALSE);
3461 _dbus_return_val_if_fail (signature != NULL, FALSE);
3462 /* don't check that signature is valid since it would be expensive,
3463 * and not catch many common errors
3466 s = dbus_message_get_signature (message);
3468 if (s && strcmp (s, signature) == 0)
3475 * Sets a #DBusError based on the contents of the given
3476 * message. The error is only set if the message
3477 * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
3478 * The name of the error is set to the name of the message,
3479 * and the error message is set to the first argument
3480 * if the argument exists and is a string.
3482 * The return value indicates whether the error was set (the error is
3483 * set if and only if the message is an error message). So you can
3484 * check for an error reply and convert it to DBusError in one go:
3486 * if (dbus_set_error_from_message (error, reply))
3492 * @param error the error to set
3493 * @param message the message to set it from
3494 * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
3497 dbus_set_error_from_message (DBusError *error,
3498 DBusMessage *message)
3502 _dbus_return_val_if_fail (message != NULL, FALSE);
3503 _dbus_return_val_if_error_is_set (error, FALSE);
3505 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3509 dbus_message_get_args (message, NULL,
3510 DBUS_TYPE_STRING, &str,
3513 dbus_set_error (error, dbus_message_get_error_name (message),
3514 str ? "%s" : NULL, str);
3522 * @addtogroup DBusMessageInternals
3528 * The initial buffer size of the message loader.
3530 * @todo this should be based on min header size plus some average
3531 * body size, or something. Or rather, the min header size only, if we
3532 * want to try to read only the header, store that in a DBusMessage,
3533 * then read only the body and store that, etc., depends on
3534 * how we optimize _dbus_message_loader_get_buffer() and what
3535 * the exact message format is.
3537 #define INITIAL_LOADER_DATA_LEN 32
3540 * Creates a new message loader. Returns #NULL if memory can't
3543 * @returns new loader, or #NULL.
3546 _dbus_message_loader_new (void)
3548 DBusMessageLoader *loader;
3550 loader = dbus_new0 (DBusMessageLoader, 1);
3554 loader->refcount = 1;
3556 loader->corrupted = FALSE;
3557 loader->corruption_reason = DBUS_VALID;
3559 /* this can be configured by the app, but defaults to the protocol max */
3560 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
3562 /* We set a very relatively conservative default here since due to how
3563 SCM_RIGHTS works we need to preallocate an fd array of the maximum
3564 number of unix fds we want to receive in advance. A
3565 try-and-reallocate loop is not possible. */
3566 loader->max_message_unix_fds = 1024;
3568 if (!_dbus_string_init (&loader->data))
3574 /* preallocate the buffer for speed, ignore failure */
3575 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
3576 _dbus_string_set_length (&loader->data, 0);
3578 #ifdef HAVE_UNIX_FD_PASSING
3579 loader->unix_fds = NULL;
3580 loader->n_unix_fds = loader->n_unix_fds_allocated = 0;
3581 loader->unix_fds_outstanding = FALSE;
3588 * Increments the reference count of the loader.
3590 * @param loader the loader.
3591 * @returns the loader
3594 _dbus_message_loader_ref (DBusMessageLoader *loader)
3596 loader->refcount += 1;
3602 * Decrements the reference count of the loader and finalizes the
3603 * loader when the count reaches zero.
3605 * @param loader the loader.
3608 _dbus_message_loader_unref (DBusMessageLoader *loader)
3610 loader->refcount -= 1;
3611 if (loader->refcount == 0)
3613 #ifdef HAVE_UNIX_FD_PASSING
3614 close_unix_fds(loader->unix_fds, &loader->n_unix_fds);
3615 dbus_free(loader->unix_fds);
3617 _dbus_list_foreach (&loader->messages,
3618 (DBusForeachFunction) dbus_message_unref,
3620 _dbus_list_clear (&loader->messages);
3621 _dbus_string_free (&loader->data);
3627 * Gets the buffer to use for reading data from the network. Network
3628 * data is read directly into an allocated buffer, which is then used
3629 * in the DBusMessage, to avoid as many extra memcpy's as possible.
3630 * The buffer must always be returned immediately using
3631 * _dbus_message_loader_return_buffer(), even if no bytes are
3632 * successfully read.
3634 * @todo this function can be a lot more clever. For example
3635 * it can probably always return a buffer size to read exactly
3636 * the body of the next message, thus avoiding any memory wastage
3639 * @todo we need to enforce a max length on strings in header fields.
3641 * @param loader the message loader.
3642 * @param buffer the buffer
3645 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
3646 DBusString **buffer)
3648 _dbus_assert (!loader->buffer_outstanding);
3650 *buffer = &loader->data;
3652 loader->buffer_outstanding = TRUE;
3656 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
3657 * indicating to the loader how many bytes of the buffer were filled
3658 * in. This function must always be called, even if no bytes were
3659 * successfully read.
3661 * @param loader the loader.
3662 * @param buffer the buffer.
3663 * @param bytes_read number of bytes that were read into the buffer.
3666 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
3670 _dbus_assert (loader->buffer_outstanding);
3671 _dbus_assert (buffer == &loader->data);
3673 loader->buffer_outstanding = FALSE;
3677 * Gets the buffer to use for reading unix fds from the network.
3679 * This works similar to _dbus_message_loader_get_buffer()
3681 * @param loader the message loader.
3682 * @param fds the array to read fds into
3683 * @param max_n_fds how many fds to read at most
3684 * @return TRUE on success, FALSE on OOM
3687 _dbus_message_loader_get_unix_fds(DBusMessageLoader *loader,
3689 unsigned *max_n_fds)
3691 #ifdef HAVE_UNIX_FD_PASSING
3692 _dbus_assert (!loader->unix_fds_outstanding);
3694 /* Allocate space where we can put the fds we read. We allocate
3695 space for max_message_unix_fds since this is an
3696 upper limit how many fds can be received within a single
3697 message. Since SCM_RIGHTS doesn't allow a reallocate+retry logic
3698 we are allocating the maximum possible array size right from the
3699 beginning. This sucks a bit, however unless SCM_RIGHTS is fixed
3700 there is no better way. */
3702 if (loader->n_unix_fds_allocated < loader->max_message_unix_fds)
3704 int *a = dbus_realloc(loader->unix_fds,
3705 loader->max_message_unix_fds * sizeof(loader->unix_fds[0]));
3710 loader->unix_fds = a;
3711 loader->n_unix_fds_allocated = loader->max_message_unix_fds;
3714 *fds = loader->unix_fds + loader->n_unix_fds;
3715 *max_n_fds = loader->n_unix_fds_allocated - loader->n_unix_fds;
3717 loader->unix_fds_outstanding = TRUE;
3720 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
3725 * Returns a buffer obtained from _dbus_message_loader_get_unix_fds().
3727 * This works similar to _dbus_message_loader_return_buffer()
3729 * @param loader the message loader.
3730 * @param fds the array fds were read into
3731 * @param max_n_fds how many fds were read
3735 _dbus_message_loader_return_unix_fds(DBusMessageLoader *loader,
3739 #ifdef HAVE_UNIX_FD_PASSING
3740 _dbus_assert(loader->unix_fds_outstanding);
3741 _dbus_assert(loader->unix_fds + loader->n_unix_fds == fds);
3742 _dbus_assert(loader->n_unix_fds + n_fds <= loader->n_unix_fds_allocated);
3744 loader->n_unix_fds += n_fds;
3745 loader->unix_fds_outstanding = FALSE;
3747 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
3752 * FIXME when we move the header out of the buffer, that memmoves all
3753 * buffered messages. Kind of crappy.
3755 * Also we copy the header and body, which is kind of crappy. To
3756 * avoid this, we have to allow header and body to be in a single
3757 * memory block, which is good for messages we read and bad for
3758 * messages we are creating. But we could move_len() the buffer into
3759 * this single memory block, and move_len() will just swap the buffers
3760 * if you're moving the entire buffer replacing the dest string.
3762 * We could also have the message loader tell the transport how many
3763 * bytes to read; so it would first ask for some arbitrary number like
3764 * 256, then if the message was incomplete it would use the
3765 * header/body len to ask for exactly the size of the message (or
3766 * blocks the size of a typical kernel buffer for the socket). That
3767 * way we don't get trailing bytes in the buffer that have to be
3768 * memmoved. Though I suppose we also don't have a chance of reading a
3769 * bunch of small messages at once, so the optimization may be stupid.
3771 * Another approach would be to keep a "start" index into
3772 * loader->data and only delete it occasionally, instead of after
3773 * each message is loaded.
3775 * load_message() returns FALSE if not enough memory OR the loader was corrupted
3778 load_message (DBusMessageLoader *loader,
3779 DBusMessage *message,
3781 int fields_array_len,
3786 DBusValidity validity;
3787 const DBusString *type_str;
3789 DBusValidationMode mode;
3790 dbus_uint32_t n_unix_fds = 0;
3792 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
3797 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
3800 /* 1. VALIDATE AND COPY OVER HEADER */
3801 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
3802 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
3804 if (!_dbus_header_load (&message->header,
3812 _dbus_string_get_length (&loader->data)))
3814 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
3816 /* assert here so we can catch any code that still uses DBUS_VALID to indicate
3817 oom errors. They should use DBUS_VALIDITY_UNKNOWN_OOM_ERROR instead */
3818 _dbus_assert (validity != DBUS_VALID);
3820 if (validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
3824 loader->corrupted = TRUE;
3825 loader->corruption_reason = validity;
3830 _dbus_assert (validity == DBUS_VALID);
3832 message->byte_order = byte_order;
3834 /* 2. VALIDATE BODY */
3835 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
3837 get_const_signature (&message->header, &type_str, &type_pos);
3839 /* Because the bytes_remaining arg is NULL, this validates that the
3840 * body is the right length
3842 validity = _dbus_validate_body_with_reason (type_str,
3849 if (validity != DBUS_VALID)
3851 _dbus_verbose ("Failed to validate message body code %d\n", validity);
3853 loader->corrupted = TRUE;
3854 loader->corruption_reason = validity;
3860 /* 3. COPY OVER UNIX FDS */
3861 _dbus_header_get_field_basic(&message->header,
3862 DBUS_HEADER_FIELD_UNIX_FDS,
3866 #ifdef HAVE_UNIX_FD_PASSING
3868 if (n_unix_fds > loader->n_unix_fds)
3870 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
3871 n_unix_fds, loader->n_unix_fds);
3873 loader->corrupted = TRUE;
3874 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
3878 /* If this was a recycled message there might still be
3879 some memory allocated for the fds */
3880 dbus_free(message->unix_fds);
3884 message->unix_fds = _dbus_memdup(loader->unix_fds, n_unix_fds * sizeof(message->unix_fds[0]));
3885 if (message->unix_fds == NULL)
3887 _dbus_verbose ("Failed to allocate file descriptor array\n");
3892 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
3893 loader->n_unix_fds -= n_unix_fds;
3894 memmove(loader->unix_fds + n_unix_fds, loader->unix_fds, loader->n_unix_fds);
3897 message->unix_fds = NULL;
3903 _dbus_verbose ("Hmm, message claims to come with file descriptors "
3904 "but that's not supported on our platform, disconnecting.\n");
3906 loader->corrupted = TRUE;
3907 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
3913 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
3915 if (!_dbus_list_append (&loader->messages, message))
3917 _dbus_verbose ("Failed to append new message to loader queue\n");
3922 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
3923 _dbus_assert (_dbus_string_get_length (&loader->data) >=
3924 (header_len + body_len));
3926 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
3928 _dbus_verbose ("Failed to move body into new message\n");
3933 _dbus_string_delete (&loader->data, 0, header_len + body_len);
3935 /* don't waste more than 2k of memory */
3936 _dbus_string_compact (&loader->data, 2048);
3938 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
3939 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
3941 _dbus_verbose ("Loaded message %p\n", message);
3943 _dbus_assert (!oom);
3944 _dbus_assert (!loader->corrupted);
3945 _dbus_assert (loader->messages != NULL);
3946 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
3954 /* does nothing if the message isn't in the list */
3955 _dbus_list_remove_last (&loader->messages, message);
3958 _dbus_assert (!loader->corrupted);
3960 _dbus_assert (loader->corrupted);
3962 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
3968 * Converts buffered data into messages, if we have enough data. If
3969 * we don't have enough data, does nothing.
3971 * @todo we need to check that the proper named header fields exist
3972 * for each message type.
3974 * @todo If a message has unknown type, we should probably eat it
3975 * right here rather than passing it out to applications. However
3976 * it's not an error to see messages of unknown type.
3978 * @param loader the loader.
3979 * @returns #TRUE if we had enough memory to finish.
3982 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
3984 while (!loader->corrupted &&
3985 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
3987 DBusValidity validity;
3988 int byte_order, fields_array_len, header_len, body_len;
3990 if (_dbus_header_have_message_untrusted (loader->max_message_size,
3997 _dbus_string_get_length (&loader->data)))
3999 DBusMessage *message;
4001 _dbus_assert (validity == DBUS_VALID);
4003 message = dbus_message_new_empty_header ();
4004 if (message == NULL)
4007 if (!load_message (loader, message,
4008 byte_order, fields_array_len,
4009 header_len, body_len))
4011 dbus_message_unref (message);
4012 /* load_message() returns false if corrupted or OOM; if
4013 * corrupted then return TRUE for not OOM
4015 return loader->corrupted;
4018 _dbus_assert (loader->messages != NULL);
4019 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4023 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
4025 if (validity != DBUS_VALID)
4027 loader->corrupted = TRUE;
4028 loader->corruption_reason = validity;
4038 * Peeks at first loaded message, returns #NULL if no messages have
4041 * @param loader the loader.
4042 * @returns the next message, or #NULL if none.
4045 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
4047 if (loader->messages)
4048 return loader->messages->data;
4054 * Pops a loaded message (passing ownership of the message
4055 * to the caller). Returns #NULL if no messages have been
4058 * @param loader the loader.
4059 * @returns the next message, or #NULL if none.
4062 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
4064 return _dbus_list_pop_first (&loader->messages);
4068 * Pops a loaded message inside a list link (passing ownership of the
4069 * message and link to the caller). Returns #NULL if no messages have
4072 * @param loader the loader.
4073 * @returns the next message link, or #NULL if none.
4076 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
4078 return _dbus_list_pop_first_link (&loader->messages);
4082 * Returns a popped message link, used to undo a pop.
4084 * @param loader the loader
4085 * @param link the link with a message in it
4088 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
4091 _dbus_list_prepend_link (&loader->messages, link);
4095 * Checks whether the loader is confused due to bad data.
4096 * If messages are received that are invalid, the
4097 * loader gets confused and gives up permanently.
4098 * This state is called "corrupted."
4100 * @param loader the loader
4101 * @returns #TRUE if the loader is hosed.
4104 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
4106 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4107 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4108 return loader->corrupted;
4112 * Sets the maximum size message we allow.
4114 * @param loader the loader
4115 * @param size the max message size in bytes
4118 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
4121 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
4123 _dbus_verbose ("clamping requested max message size %ld to %d\n",
4124 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
4125 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4127 loader->max_message_size = size;
4131 * Gets the maximum allowed message size in bytes.
4133 * @param loader the loader
4134 * @returns max size in bytes
4137 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
4139 return loader->max_message_size;
4143 * Sets the maximum unix fds per message we allow.
4145 * @param loader the loader
4146 * @param size the max number of unix fds in a message
4149 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader,
4152 if (n > DBUS_MAXIMUM_MESSAGE_UNIX_FDS)
4154 _dbus_verbose ("clamping requested max message unix_fds %ld to %d\n",
4155 n, DBUS_MAXIMUM_MESSAGE_UNIX_FDS);
4156 n = DBUS_MAXIMUM_MESSAGE_UNIX_FDS;
4158 loader->max_message_unix_fds = n;
4162 * Gets the maximum allowed number of unix fds per message
4164 * @param loader the loader
4165 * @returns max unix fds
4168 _dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
4170 return loader->max_message_unix_fds;
4173 static DBusDataSlotAllocator slot_allocator;
4174 _DBUS_DEFINE_GLOBAL_LOCK (message_slots);
4177 * Allocates an integer ID to be used for storing application-specific
4178 * data on any DBusMessage. The allocated ID may then be used
4179 * with dbus_message_set_data() and dbus_message_get_data().
4180 * The passed-in slot must be initialized to -1, and is filled in
4181 * with the slot ID. If the passed-in slot is not -1, it's assumed
4182 * to be already allocated, and its refcount is incremented.
4184 * The allocated slot is global, i.e. all DBusMessage objects will
4185 * have a slot with the given integer ID reserved.
4187 * @param slot_p address of a global variable storing the slot
4188 * @returns #FALSE on failure (no memory)
4191 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
4193 return _dbus_data_slot_allocator_alloc (&slot_allocator,
4194 &_DBUS_LOCK_NAME (message_slots),
4199 * Deallocates a global ID for message data slots.
4200 * dbus_message_get_data() and dbus_message_set_data() may no
4201 * longer be used with this slot. Existing data stored on existing
4202 * DBusMessage objects will be freed when the message is
4203 * finalized, but may not be retrieved (and may only be replaced if
4204 * someone else reallocates the slot). When the refcount on the
4205 * passed-in slot reaches 0, it is set to -1.
4207 * @param slot_p address storing the slot to deallocate
4210 dbus_message_free_data_slot (dbus_int32_t *slot_p)
4212 _dbus_return_if_fail (*slot_p >= 0);
4214 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
4218 * Stores a pointer on a DBusMessage, along
4219 * with an optional function to be used for freeing
4220 * the data when the data is set again, or when
4221 * the message is finalized. The slot number
4222 * must have been allocated with dbus_message_allocate_data_slot().
4224 * @param message the message
4225 * @param slot the slot number
4226 * @param data the data to store
4227 * @param free_data_func finalizer function for the data
4228 * @returns #TRUE if there was enough memory to store the data
4231 dbus_message_set_data (DBusMessage *message,
4234 DBusFreeFunction free_data_func)
4236 DBusFreeFunction old_free_func;
4240 _dbus_return_val_if_fail (message != NULL, FALSE);
4241 _dbus_return_val_if_fail (slot >= 0, FALSE);
4243 retval = _dbus_data_slot_list_set (&slot_allocator,
4244 &message->slot_list,
4245 slot, data, free_data_func,
4246 &old_free_func, &old_data);
4250 /* Do the actual free outside the message lock */
4252 (* old_free_func) (old_data);
4259 * Retrieves data previously set with dbus_message_set_data().
4260 * The slot must still be allocated (must not have been freed).
4262 * @param message the message
4263 * @param slot the slot to get data from
4264 * @returns the data, or #NULL if not found
4267 dbus_message_get_data (DBusMessage *message,
4272 _dbus_return_val_if_fail (message != NULL, NULL);
4274 res = _dbus_data_slot_list_get (&slot_allocator,
4275 &message->slot_list,
4282 * Utility function to convert a machine-readable (not translated)
4283 * string into a D-Bus message type.
4286 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
4287 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
4288 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
4289 * "error" -> DBUS_MESSAGE_TYPE_ERROR
4290 * anything else -> DBUS_MESSAGE_TYPE_INVALID
4295 dbus_message_type_from_string (const char *type_str)
4297 if (strcmp (type_str, "method_call") == 0)
4298 return DBUS_MESSAGE_TYPE_METHOD_CALL;
4299 if (strcmp (type_str, "method_return") == 0)
4300 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
4301 else if (strcmp (type_str, "signal") == 0)
4302 return DBUS_MESSAGE_TYPE_SIGNAL;
4303 else if (strcmp (type_str, "error") == 0)
4304 return DBUS_MESSAGE_TYPE_ERROR;
4306 return DBUS_MESSAGE_TYPE_INVALID;
4310 * Utility function to convert a D-Bus message type into a
4311 * machine-readable string (not translated).
4314 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
4315 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
4316 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
4317 * DBUS_MESSAGE_TYPE_ERROR -> "error"
4318 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
4323 dbus_message_type_to_string (int type)
4327 case DBUS_MESSAGE_TYPE_METHOD_CALL:
4328 return "method_call";
4329 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
4330 return "method_return";
4331 case DBUS_MESSAGE_TYPE_SIGNAL:
4333 case DBUS_MESSAGE_TYPE_ERROR:
4341 * Turn a DBusMessage into the marshalled form as described in the D-Bus
4344 * Generally, this function is only useful for encapsulating D-Bus messages in
4345 * a different protocol.
4347 * @param msg the DBusMessage
4348 * @param marshalled_data_p the location to save the marshalled form to
4349 * @param len_p the location to save the length of the marshalled form to
4350 * @returns #FALSE if there was not enough memory
4353 dbus_message_marshal (DBusMessage *msg,
4354 char **marshalled_data_p,
4359 _dbus_return_val_if_fail (msg != NULL, FALSE);
4360 _dbus_return_val_if_fail (marshalled_data_p != NULL, FALSE);
4361 _dbus_return_val_if_fail (len_p != NULL, FALSE);
4363 if (!_dbus_string_init (&tmp))
4366 if (!_dbus_string_copy (&(msg->header.data), 0, &tmp, 0))
4369 *len_p = _dbus_string_get_length (&tmp);
4371 if (!_dbus_string_copy (&(msg->body), 0, &tmp, *len_p))
4374 *len_p = _dbus_string_get_length (&tmp);
4376 if (!_dbus_string_steal_data (&tmp, marshalled_data_p))
4379 _dbus_string_free (&tmp);
4383 _dbus_string_free (&tmp);
4388 * Demarshal a D-Bus message from the format described in the D-Bus
4391 * Generally, this function is only useful for encapsulating D-Bus messages in
4392 * a different protocol.
4394 * @param str the marshalled DBusMessage
4395 * @param len the length of str
4396 * @param error the location to save errors to
4397 * @returns #NULL if there was an error
4400 dbus_message_demarshal (const char *str,
4404 DBusMessageLoader *loader;
4408 _dbus_return_val_if_fail (str != NULL, NULL);
4410 loader = _dbus_message_loader_new ();
4415 _dbus_message_loader_get_buffer (loader, &buffer);
4416 _dbus_string_append_len (buffer, str, len);
4417 _dbus_message_loader_return_buffer (loader, buffer, len);
4419 if (!_dbus_message_loader_queue_messages (loader))
4422 if (_dbus_message_loader_get_is_corrupted (loader))
4425 msg = _dbus_message_loader_pop_message (loader);
4430 _dbus_message_loader_unref (loader);
4434 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS, "Message is corrupted");
4435 _dbus_message_loader_unref (loader);
4439 _DBUS_SET_OOM (error);
4440 _dbus_message_loader_unref (loader);
4445 * Returns the number of bytes required to be in the buffer to demarshal a
4448 * Generally, this function is only useful for encapsulating D-Bus messages in
4449 * a different protocol.
4451 * @param str data to be marshalled
4452 * @param len the length of str
4453 * @param error the location to save errors to
4454 * @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
4458 dbus_message_demarshal_bytes_needed(const char *buf,
4462 int byte_order, fields_array_len, header_len, body_len;
4463 DBusValidity validity = DBUS_VALID;
4466 if (!buf || len < DBUS_MINIMUM_HEADER_SIZE)
4469 if (len > DBUS_MAXIMUM_MESSAGE_LENGTH)
4470 len = DBUS_MAXIMUM_MESSAGE_LENGTH;
4471 _dbus_string_init_const_len (&str, buf, len);
4473 validity = DBUS_VALID;
4475 = _dbus_header_have_message_untrusted(DBUS_MAXIMUM_MESSAGE_LENGTH,
4476 &validity, &byte_order,
4482 _dbus_string_free (&str);
4484 if (validity == DBUS_VALID)
4486 _dbus_assert(have_message);
4487 return header_len + body_len;
4491 return -1; /* broken! */
4497 /* tests in dbus-message-util.c */