1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 /* dbus-message.c DBusMessage object
4 * Copyright (C) 2002, 2003, 2004, 2005 Red Hat Inc.
5 * Copyright (C) 2002, 2003 CodeFactory AB
7 * Licensed under the Academic Free License version 2.1
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
26 #include "dbus-internals.h"
27 #include "dbus-marshal-recursive.h"
28 #include "dbus-marshal-validate.h"
29 #include "dbus-marshal-byteswap.h"
30 #include "dbus-marshal-header.h"
31 #include "dbus-signature.h"
32 #include "dbus-message-private.h"
33 #include "dbus-object-tree.h"
34 #include "dbus-memory.h"
35 #include "dbus-list.h"
36 #include "dbus-threads-internal.h"
37 #ifdef HAVE_UNIX_FD_PASSING
38 #include "dbus-sysdeps-unix.h"
43 static void dbus_message_finalize (DBusMessage *message);
46 * @defgroup DBusMessageInternals DBusMessage implementation details
47 * @ingroup DBusInternals
48 * @brief DBusMessage private implementation details.
50 * The guts of DBusMessage and its methods.
55 /* Not thread locked, but strictly const/read-only so should be OK
57 /** An static string representing an empty signature */
58 _DBUS_STRING_DEFINE_STATIC(_dbus_empty_signature_str, "");
60 /* these have wacky values to help trap uninitialized iterators;
61 * but has to fit in 3 bits
64 DBUS_MESSAGE_ITER_TYPE_READER = 3,
65 DBUS_MESSAGE_ITER_TYPE_WRITER = 7
68 /** typedef for internals of message iterator */
69 typedef struct DBusMessageRealIter DBusMessageRealIter;
72 * @brief Internals of DBusMessageIter
74 * Object representing a position in a message. All fields are internal.
76 struct DBusMessageRealIter
78 DBusMessage *message; /**< Message used */
79 dbus_uint32_t changed_stamp : CHANGED_STAMP_BITS; /**< stamp to detect invalid iters */
80 dbus_uint32_t iter_type : 3; /**< whether this is a reader or writer iter */
81 dbus_uint32_t sig_refcount : 8; /**< depth of open_signature() */
84 DBusTypeWriter writer; /**< writer */
85 DBusTypeReader reader; /**< reader */
86 } u; /**< the type writer or reader that does all the work */
90 get_const_signature (DBusHeader *header,
91 const DBusString **type_str_p,
94 if (_dbus_header_get_field_raw (header,
95 DBUS_HEADER_FIELD_SIGNATURE,
99 *type_pos_p += 1; /* skip the signature length which is 1 byte */
103 *type_str_p = &_dbus_empty_signature_str;
109 * Swaps the message to compiler byte order if required
111 * @param message the message
114 _dbus_message_byteswap (DBusMessage *message)
116 const DBusString *type_str;
119 if (message->byte_order == DBUS_COMPILER_BYTE_ORDER)
122 _dbus_verbose ("Swapping message into compiler byte order\n");
124 get_const_signature (&message->header, &type_str, &type_pos);
126 _dbus_marshal_byteswap (type_str, type_pos,
128 DBUS_COMPILER_BYTE_ORDER,
131 message->byte_order = DBUS_COMPILER_BYTE_ORDER;
133 _dbus_header_byteswap (&message->header, DBUS_COMPILER_BYTE_ORDER);
136 /** byte-swap the message if it doesn't match our byte order.
137 * Called only when we need the message in our own byte order,
138 * normally when reading arrays of integers or doubles.
139 * Otherwise should not be called since it would do needless
142 #define ensure_byte_order(message) \
143 if (message->byte_order != DBUS_COMPILER_BYTE_ORDER) \
144 _dbus_message_byteswap (message)
147 * Gets the data to be sent over the network for this message.
148 * The header and then the body should be written out.
149 * This function is guaranteed to always return the same
150 * data once a message is locked (with dbus_message_lock()).
152 * @param message the message.
153 * @param header return location for message header data.
154 * @param body return location for message body data.
157 _dbus_message_get_network_data (DBusMessage *message,
158 const DBusString **header,
159 const DBusString **body)
161 _dbus_assert (message->locked);
163 *header = &message->header.data;
164 *body = &message->body;
168 * Gets the unix fds to be sent over the network for this message.
169 * This function is guaranteed to always return the same data once a
170 * message is locked (with dbus_message_lock()).
172 * @param message the message.
173 * @param fds return location of unix fd array
174 * @param n_fds return number of entries in array
176 void _dbus_message_get_unix_fds(DBusMessage *message,
180 _dbus_assert (message->locked);
182 #ifdef HAVE_UNIX_FD_PASSING
183 *fds = message->unix_fds;
184 *n_fds = message->n_unix_fds;
192 * Sets the serial number of a message.
193 * This can only be done once on a message.
195 * DBusConnection will automatically set the serial to an appropriate value
196 * when the message is sent; this function is only needed when encapsulating
197 * messages in another protocol, or otherwise bypassing DBusConnection.
199 * @param message the message
200 * @param serial the serial
203 dbus_message_set_serial (DBusMessage *message,
204 dbus_uint32_t serial)
206 _dbus_return_if_fail (message != NULL);
207 _dbus_return_if_fail (!message->locked);
209 _dbus_header_set_serial (&message->header, serial);
213 * Adds a counter to be incremented immediately with the size/unix fds
214 * of this message, and decremented by the size/unix fds of this
215 * message when this message if finalized. The link contains a
216 * counter with its refcount already incremented, but the counter
217 * itself not incremented. Ownership of link and counter refcount is
218 * passed to the message.
220 * @param message the message
221 * @param link link with counter as data
224 _dbus_message_add_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->counters == NULL)
235 message->size_counter_delta =
236 _dbus_string_get_length (&message->header.data) +
237 _dbus_string_get_length (&message->body);
239 #ifdef HAVE_UNIX_FD_PASSING
240 message->unix_fd_counter_delta = message->n_unix_fds;
244 _dbus_verbose ("message has size %ld\n",
245 message->size_counter_delta);
249 _dbus_list_append_link (&message->counters, link);
251 _dbus_counter_adjust_size (link->data, message->size_counter_delta);
253 #ifdef HAVE_UNIX_FD_PASSING
254 _dbus_counter_adjust_unix_fd (link->data, message->unix_fd_counter_delta);
259 * Adds a counter to be incremented immediately with the size/unix fds
260 * of this message, and decremented by the size/unix fds of this
261 * message when this message if finalized.
263 * @param message the message
264 * @param counter the counter
265 * @returns #FALSE if no memory
268 _dbus_message_add_counter (DBusMessage *message,
269 DBusCounter *counter)
273 link = _dbus_list_alloc_link (counter);
277 _dbus_counter_ref (counter);
278 _dbus_message_add_counter_link (message, link);
284 * Removes a counter tracking the size/unix fds of this message, and
285 * decrements the counter by the size/unix fds of this message.
287 * @param message the message
288 * @param link_return return the link used
289 * @param counter the counter
292 _dbus_message_remove_counter (DBusMessage *message,
293 DBusCounter *counter,
294 DBusList **link_return)
298 link = _dbus_list_find_last (&message->counters,
300 _dbus_assert (link != NULL);
302 _dbus_list_unlink (&message->counters,
307 _dbus_list_free_link (link);
309 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
311 #ifdef HAVE_UNIX_FD_PASSING
312 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
315 _dbus_counter_unref (counter);
319 * Locks a message. Allows checking that applications don't keep a
320 * reference to a message in the outgoing queue and change it
321 * underneath us. Messages are locked when they enter the outgoing
322 * queue (dbus_connection_send_message()), and the library complains
323 * if the message is modified while locked. This function may also
324 * called externally, for applications wrapping D-Bus in another protocol.
326 * @param message the message to lock.
329 dbus_message_lock (DBusMessage *message)
331 if (!message->locked)
333 _dbus_header_update_lengths (&message->header,
334 _dbus_string_get_length (&message->body));
336 /* must have a signature if you have a body */
337 _dbus_assert (_dbus_string_get_length (&message->body) == 0 ||
338 dbus_message_get_signature (message) != NULL);
340 message->locked = TRUE;
345 set_or_delete_string_field (DBusMessage *message,
351 return _dbus_header_delete_field (&message->header, field);
353 return _dbus_header_set_field_basic (&message->header,
360 /* Probably we don't need to use this */
362 * Sets the signature of the message, i.e. the arguments in the
363 * message payload. The signature includes only "in" arguments for
364 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
365 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
366 * what you might expect (it does not include the signature of the
367 * entire C++-style method).
369 * The signature is a string made up of type codes such as
370 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
371 * the value of #DBUS_TYPE_INVALID). The macros such as
372 * #DBUS_TYPE_INT32 evaluate to integers; to assemble a signature you
373 * may find it useful to use the string forms, such as
374 * #DBUS_TYPE_INT32_AS_STRING.
376 * An "unset" or #NULL signature is considered the same as an empty
377 * signature. In fact dbus_message_get_signature() will never return
380 * @param message the message
381 * @param signature the type signature or #NULL to unset
382 * @returns #FALSE if no memory
385 _dbus_message_set_signature (DBusMessage *message,
386 const char *signature)
388 _dbus_return_val_if_fail (message != NULL, FALSE);
389 _dbus_return_val_if_fail (!message->locked, FALSE);
390 _dbus_return_val_if_fail (signature == NULL ||
391 _dbus_check_is_valid_signature (signature));
392 /* can't delete the signature if you have a message body */
393 _dbus_return_val_if_fail (_dbus_string_get_length (&message->body) == 0 ||
396 return set_or_delete_string_field (message,
397 DBUS_HEADER_FIELD_SIGNATURE,
405 * We cache some DBusMessage to reduce the overhead of allocating
406 * them. In my profiling this consistently made about an 8%
407 * difference. It avoids the malloc for the message, the malloc for
408 * the slot list, the malloc for the header string and body string,
409 * and the associated free() calls. It does introduce another global
410 * lock which could be a performance issue in certain cases.
412 * For the echo client/server the round trip time goes from around
413 * .000077 to .000069 with the message cache on my laptop. The sysprof
414 * change is as follows (numbers are cumulative percentage):
416 * with message cache implemented as array as it is now (0.000069 per):
417 * new_empty_header 1.46
418 * mutex_lock 0.56 # i.e. _DBUS_LOCK(message_cache)
424 * mutex_lock 0.33 # i.e. _DBUS_LOCK(message_cache)
427 * with message cache implemented as list (0.000070 per roundtrip):
428 * new_empty_header 2.72
429 * list_pop_first 1.88
433 * without cache (0.000077 per roundtrip):
434 * new_empty_header 6.7
435 * string_init_preallocated 3.43
444 * If you implement the message_cache with a list, the primary reason
445 * it's slower is that you add another thread lock (on the DBusList
449 /** Avoid caching huge messages */
450 #define MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE
452 /** Avoid caching too many messages */
453 #define MAX_MESSAGE_CACHE_SIZE 5
455 _DBUS_DEFINE_GLOBAL_LOCK (message_cache);
456 static DBusMessage *message_cache[MAX_MESSAGE_CACHE_SIZE];
457 static int message_cache_count = 0;
458 static dbus_bool_t message_cache_shutdown_registered = FALSE;
461 dbus_message_cache_shutdown (void *data)
465 _DBUS_LOCK (message_cache);
468 while (i < MAX_MESSAGE_CACHE_SIZE)
470 if (message_cache[i])
471 dbus_message_finalize (message_cache[i]);
476 message_cache_count = 0;
477 message_cache_shutdown_registered = FALSE;
479 _DBUS_UNLOCK (message_cache);
483 * Tries to get a message from the message cache. The retrieved
484 * message will have junk in it, so it still needs to be cleared out
485 * in dbus_message_new_empty_header()
487 * @returns the message, or #NULL if none cached
490 dbus_message_get_cached (void)
492 DBusMessage *message;
497 _DBUS_LOCK (message_cache);
499 _dbus_assert (message_cache_count >= 0);
501 if (message_cache_count == 0)
503 _DBUS_UNLOCK (message_cache);
507 /* This is not necessarily true unless count > 0, and
508 * message_cache is uninitialized until the shutdown is
511 _dbus_assert (message_cache_shutdown_registered);
514 while (i < MAX_MESSAGE_CACHE_SIZE)
516 if (message_cache[i])
518 message = message_cache[i];
519 message_cache[i] = NULL;
520 message_cache_count -= 1;
525 _dbus_assert (message_cache_count >= 0);
526 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
527 _dbus_assert (message != NULL);
529 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
531 _dbus_assert (message->counters == NULL);
533 _DBUS_UNLOCK (message_cache);
538 #ifdef HAVE_UNIX_FD_PASSING
540 close_unix_fds(int *fds, unsigned *n_fds)
550 for (i = 0; i < *n_fds; i++)
552 if (!_dbus_close(fds[i], &e))
554 _dbus_warn("Failed to close file descriptor: %s\n", e.message);
561 /* We don't free the array here, in case we can recycle it later */
566 free_counter (void *element,
569 DBusCounter *counter = element;
570 DBusMessage *message = data;
572 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
573 #ifdef HAVE_UNIX_FD_PASSING
574 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
577 _dbus_counter_unref (counter);
581 * Tries to cache a message, otherwise finalize it.
583 * @param message the message
586 dbus_message_cache_or_finalize (DBusMessage *message)
588 dbus_bool_t was_cached;
591 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
593 /* This calls application code and has to be done first thing
594 * without holding the lock
596 _dbus_data_slot_list_clear (&message->slot_list);
598 _dbus_list_foreach (&message->counters,
599 free_counter, message);
600 _dbus_list_clear (&message->counters);
602 #ifdef HAVE_UNIX_FD_PASSING
603 close_unix_fds(message->unix_fds, &message->n_unix_fds);
608 _DBUS_LOCK (message_cache);
610 if (!message_cache_shutdown_registered)
612 _dbus_assert (message_cache_count == 0);
614 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
618 while (i < MAX_MESSAGE_CACHE_SIZE)
620 message_cache[i] = NULL;
624 message_cache_shutdown_registered = TRUE;
627 _dbus_assert (message_cache_count >= 0);
629 if ((_dbus_string_get_length (&message->header.data) +
630 _dbus_string_get_length (&message->body)) >
631 MAX_MESSAGE_SIZE_TO_CACHE)
634 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
637 /* Find empty slot */
639 while (message_cache[i] != NULL)
642 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
644 _dbus_assert (message_cache[i] == NULL);
645 message_cache[i] = message;
646 message_cache_count += 1;
648 #ifndef DBUS_DISABLE_CHECKS
649 message->in_cache = TRUE;
653 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
655 _DBUS_UNLOCK (message_cache);
658 dbus_message_finalize (message);
661 #ifndef DBUS_DISABLE_CHECKS
663 _dbus_message_iter_check (DBusMessageRealIter *iter)
667 _dbus_warn_check_failed ("dbus message iterator is NULL\n");
671 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
673 if (iter->u.reader.byte_order != iter->message->byte_order)
675 _dbus_warn_check_failed ("dbus message changed byte order since iterator was created\n");
678 /* because we swap the message into compiler order when you init an iter */
679 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
681 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
683 if (iter->u.writer.byte_order != iter->message->byte_order)
685 _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created\n");
688 /* because we swap the message into compiler order when you init an iter */
689 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
693 _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted\n");
697 if (iter->changed_stamp != iter->message->changed_stamp)
699 _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
705 #endif /* DBUS_DISABLE_CHECKS */
708 * Implementation of the varargs arg-getting functions.
709 * dbus_message_get_args() is the place to go for complete
712 * @todo This may leak memory and file descriptors if parsing fails. See #21259
714 * @see dbus_message_get_args
715 * @param iter the message iter
716 * @param error error to be filled in
717 * @param first_arg_type type of the first argument
718 * @param var_args return location for first argument, followed by list of type/location pairs
719 * @returns #FALSE if error was set
722 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
727 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
728 int spec_type, msg_type, i;
731 _dbus_assert (_dbus_message_iter_check (real));
735 spec_type = first_arg_type;
738 while (spec_type != DBUS_TYPE_INVALID)
740 msg_type = dbus_message_iter_get_arg_type (iter);
742 if (msg_type != spec_type)
744 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
745 "Argument %d is specified to be of type \"%s\", but "
746 "is actually of type \"%s\"\n", i,
747 _dbus_type_to_string (spec_type),
748 _dbus_type_to_string (msg_type));
753 if (spec_type == DBUS_TYPE_UNIX_FD)
755 #ifdef HAVE_UNIX_FD_PASSING
759 pfd = va_arg (var_args, int*);
762 _dbus_type_reader_read_basic(&real->u.reader, &idx);
764 if (idx.u32 >= real->message->n_unix_fds)
766 dbus_set_error (error, DBUS_ERROR_INCONSISTENT_MESSAGE,
767 "Message refers to file descriptor at index %i,"
768 "but has only %i descriptors attached.\n",
770 real->message->n_unix_fds);
774 if ((nfd = _dbus_dup(real->message->unix_fds[idx.u32], error)) < 0)
779 dbus_set_error (error, DBUS_ERROR_NOT_SUPPORTED,
780 "Platform does not support file desciptor passing.\n");
784 else if (dbus_type_is_basic (spec_type))
788 ptr = va_arg (var_args, DBusBasicValue*);
790 _dbus_assert (ptr != NULL);
792 _dbus_type_reader_read_basic (&real->u.reader,
795 else if (spec_type == DBUS_TYPE_ARRAY)
798 int spec_element_type;
799 const DBusBasicValue **ptr;
801 DBusTypeReader array;
803 spec_element_type = va_arg (var_args, int);
804 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
806 if (spec_element_type != element_type)
808 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
809 "Argument %d is specified to be an array of \"%s\", but "
810 "is actually an array of \"%s\"\n",
812 _dbus_type_to_string (spec_element_type),
813 _dbus_type_to_string (element_type));
818 if (dbus_type_is_fixed (spec_element_type) &&
819 element_type != DBUS_TYPE_UNIX_FD)
821 ptr = va_arg (var_args, const DBusBasicValue**);
822 n_elements_p = va_arg (var_args, int*);
824 _dbus_assert (ptr != NULL);
825 _dbus_assert (n_elements_p != NULL);
827 _dbus_type_reader_recurse (&real->u.reader, &array);
829 _dbus_type_reader_read_fixed_multi (&array,
830 (void *) ptr, n_elements_p);
832 else if (spec_element_type == DBUS_TYPE_STRING ||
833 spec_element_type == DBUS_TYPE_SIGNATURE ||
834 spec_element_type == DBUS_TYPE_OBJECT_PATH)
840 str_array_p = va_arg (var_args, char***);
841 n_elements_p = va_arg (var_args, int*);
843 _dbus_assert (str_array_p != NULL);
844 _dbus_assert (n_elements_p != NULL);
846 /* Count elements in the array */
847 _dbus_type_reader_recurse (&real->u.reader, &array);
850 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
853 _dbus_type_reader_next (&array);
856 str_array = dbus_new0 (char*, n_elements + 1);
857 if (str_array == NULL)
859 _DBUS_SET_OOM (error);
863 /* Now go through and dup each string */
864 _dbus_type_reader_recurse (&real->u.reader, &array);
867 while (i < n_elements)
870 _dbus_type_reader_read_basic (&array,
873 str_array[i] = _dbus_strdup (s);
874 if (str_array[i] == NULL)
876 dbus_free_string_array (str_array);
877 _DBUS_SET_OOM (error);
883 if (!_dbus_type_reader_next (&array))
884 _dbus_assert (i == n_elements);
887 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
888 _dbus_assert (i == n_elements);
889 _dbus_assert (str_array[i] == NULL);
891 *str_array_p = str_array;
892 *n_elements_p = n_elements;
894 #ifndef DBUS_DISABLE_CHECKS
897 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
898 _DBUS_FUNCTION_NAME);
903 #ifndef DBUS_DISABLE_CHECKS
906 _dbus_warn ("you can only read arrays and basic types with %s for now\n",
907 _DBUS_FUNCTION_NAME);
912 spec_type = va_arg (var_args, int);
913 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
915 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
916 "Message has only %d arguments, but more were expected", i);
933 * @defgroup DBusMessage DBusMessage
935 * @brief Message to be sent or received over a #DBusConnection.
937 * A DBusMessage is the most basic unit of communication over a
938 * DBusConnection. A DBusConnection represents a stream of messages
939 * received from a remote application, and a stream of messages
940 * sent to a remote application.
942 * A message has a message type, returned from
943 * dbus_message_get_type(). This indicates whether the message is a
944 * method call, a reply to a method call, a signal, or an error reply.
946 * A message has header fields such as the sender, destination, method
947 * or signal name, and so forth. DBusMessage has accessor functions for
948 * these, such as dbus_message_get_member().
950 * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
951 * and dbus_message_is_error() check several header fields at once and are
952 * slightly more efficient than checking the header fields with individual
953 * accessor functions.
955 * Finally, a message has arguments. The number and types of arguments
956 * are in the message's signature header field (accessed with
957 * dbus_message_get_signature()). Simple argument values are usually
958 * retrieved with dbus_message_get_args() but more complex values such
959 * as structs may require the use of #DBusMessageIter.
961 * The D-Bus specification goes into some more detail about header fields and
968 * @typedef DBusMessage
970 * Opaque data type representing a message received from or to be
971 * sent to another application.
975 * Returns the serial of a message or 0 if none has been specified.
976 * The message's serial number is provided by the application sending
977 * the message and is used to identify replies to this message.
979 * All messages received on a connection will have a serial provided
980 * by the remote application.
982 * For messages you're sending, dbus_connection_send() will assign a
983 * serial and return it to you.
985 * @param message the message
986 * @returns the serial
989 dbus_message_get_serial (DBusMessage *message)
991 _dbus_return_val_if_fail (message != NULL, 0);
993 return _dbus_header_get_serial (&message->header);
997 * Sets the reply serial of a message (the serial of the message this
1000 * @param message the message
1001 * @param reply_serial the serial we're replying to
1002 * @returns #FALSE if not enough memory
1005 dbus_message_set_reply_serial (DBusMessage *message,
1006 dbus_uint32_t reply_serial)
1008 _dbus_return_val_if_fail (message != NULL, FALSE);
1009 _dbus_return_val_if_fail (!message->locked, FALSE);
1010 _dbus_return_val_if_fail (reply_serial != 0, FALSE); /* 0 is invalid */
1012 return _dbus_header_set_field_basic (&message->header,
1013 DBUS_HEADER_FIELD_REPLY_SERIAL,
1019 * Returns the serial that the message is a reply to or 0 if none.
1021 * @param message the message
1022 * @returns the reply serial
1025 dbus_message_get_reply_serial (DBusMessage *message)
1027 dbus_uint32_t v_UINT32;
1029 _dbus_return_val_if_fail (message != NULL, 0);
1031 if (_dbus_header_get_field_basic (&message->header,
1032 DBUS_HEADER_FIELD_REPLY_SERIAL,
1041 dbus_message_finalize (DBusMessage *message)
1043 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1045 /* This calls application callbacks! */
1046 _dbus_data_slot_list_free (&message->slot_list);
1048 _dbus_list_foreach (&message->counters,
1049 free_counter, message);
1050 _dbus_list_clear (&message->counters);
1052 _dbus_header_free (&message->header);
1053 _dbus_string_free (&message->body);
1055 #ifdef HAVE_UNIX_FD_PASSING
1056 close_unix_fds(message->unix_fds, &message->n_unix_fds);
1057 dbus_free(message->unix_fds);
1060 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1062 dbus_free (message);
1066 dbus_message_new_empty_header (void)
1068 DBusMessage *message;
1069 dbus_bool_t from_cache;
1071 message = dbus_message_get_cached ();
1073 if (message != NULL)
1080 message = dbus_new0 (DBusMessage, 1);
1081 if (message == NULL)
1083 #ifndef DBUS_DISABLE_CHECKS
1084 message->generation = _dbus_current_generation;
1087 #ifdef HAVE_UNIX_FD_PASSING
1088 message->unix_fds = NULL;
1089 message->n_unix_fds_allocated = 0;
1093 _dbus_atomic_inc (&message->refcount);
1095 message->byte_order = DBUS_COMPILER_BYTE_ORDER;
1096 message->locked = FALSE;
1097 #ifndef DBUS_DISABLE_CHECKS
1098 message->in_cache = FALSE;
1100 message->counters = NULL;
1101 message->size_counter_delta = 0;
1102 message->changed_stamp = 0;
1104 #ifdef HAVE_UNIX_FD_PASSING
1105 message->n_unix_fds = 0;
1106 message->n_unix_fds_allocated = 0;
1107 message->unix_fd_counter_delta = 0;
1111 _dbus_data_slot_list_init (&message->slot_list);
1115 _dbus_header_reinit (&message->header, message->byte_order);
1116 _dbus_string_set_length (&message->body, 0);
1120 if (!_dbus_header_init (&message->header, message->byte_order))
1122 dbus_free (message);
1126 if (!_dbus_string_init_preallocated (&message->body, 32))
1128 _dbus_header_free (&message->header);
1129 dbus_free (message);
1138 * Constructs a new message of the given message type.
1139 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
1140 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
1142 * Usually you want to use dbus_message_new_method_call(),
1143 * dbus_message_new_method_return(), dbus_message_new_signal(),
1144 * or dbus_message_new_error() instead.
1146 * @param message_type type of message
1147 * @returns new message or #NULL if no memory
1150 dbus_message_new (int message_type)
1152 DBusMessage *message;
1154 _dbus_return_val_if_fail (message_type != DBUS_MESSAGE_TYPE_INVALID, NULL);
1156 message = dbus_message_new_empty_header ();
1157 if (message == NULL)
1160 if (!_dbus_header_create (&message->header,
1162 NULL, NULL, NULL, NULL, NULL))
1164 dbus_message_unref (message);
1172 * Constructs a new message to invoke a method on a remote
1173 * object. Returns #NULL if memory can't be allocated for the
1174 * message. The destination may be #NULL in which case no destination
1175 * is set; this is appropriate when using D-Bus in a peer-to-peer
1176 * context (no message bus). The interface may be #NULL, which means
1177 * that if multiple methods with the given name exist it is undefined
1178 * which one will be invoked.
1180 * The path and method names may not be #NULL.
1182 * Destination, path, interface, and method name can't contain
1183 * any invalid characters (see the D-Bus specification).
1185 * @param destination name that the message should be sent to or #NULL
1186 * @param path object path the message should be sent to
1187 * @param interface interface to invoke method on, or #NULL
1188 * @param method method to invoke
1190 * @returns a new DBusMessage, free with dbus_message_unref()
1193 dbus_message_new_method_call (const char *destination,
1195 const char *interface,
1198 DBusMessage *message;
1200 _dbus_return_val_if_fail (path != NULL, NULL);
1201 _dbus_return_val_if_fail (method != NULL, NULL);
1202 _dbus_return_val_if_fail (destination == NULL ||
1203 _dbus_check_is_valid_bus_name (destination), NULL);
1204 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1205 _dbus_return_val_if_fail (interface == NULL ||
1206 _dbus_check_is_valid_interface (interface), NULL);
1207 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
1209 message = dbus_message_new_empty_header ();
1210 if (message == NULL)
1213 if (!_dbus_header_create (&message->header,
1214 DBUS_MESSAGE_TYPE_METHOD_CALL,
1215 destination, path, interface, method, NULL))
1217 dbus_message_unref (message);
1225 * Constructs a message that is a reply to a method call. Returns
1226 * #NULL if memory can't be allocated for the message.
1228 * @param method_call the message being replied to
1229 * @returns a new DBusMessage, free with dbus_message_unref()
1232 dbus_message_new_method_return (DBusMessage *method_call)
1234 DBusMessage *message;
1237 _dbus_return_val_if_fail (method_call != NULL, NULL);
1239 sender = dbus_message_get_sender (method_call);
1241 /* sender is allowed to be null here in peer-to-peer case */
1243 message = dbus_message_new_empty_header ();
1244 if (message == NULL)
1247 if (!_dbus_header_create (&message->header,
1248 DBUS_MESSAGE_TYPE_METHOD_RETURN,
1249 sender, NULL, NULL, NULL, NULL))
1251 dbus_message_unref (message);
1255 dbus_message_set_no_reply (message, TRUE);
1257 if (!dbus_message_set_reply_serial (message,
1258 dbus_message_get_serial (method_call)))
1260 dbus_message_unref (message);
1268 * Constructs a new message representing a signal emission. Returns
1269 * #NULL if memory can't be allocated for the message. A signal is
1270 * identified by its originating object path, interface, and the name
1273 * Path, interface, and signal name must all be valid (the D-Bus
1274 * specification defines the syntax of these fields).
1276 * @param path the path to the object emitting the signal
1277 * @param interface the interface the signal is emitted from
1278 * @param name name of the signal
1279 * @returns a new DBusMessage, free with dbus_message_unref()
1282 dbus_message_new_signal (const char *path,
1283 const char *interface,
1286 DBusMessage *message;
1288 _dbus_return_val_if_fail (path != NULL, NULL);
1289 _dbus_return_val_if_fail (interface != NULL, NULL);
1290 _dbus_return_val_if_fail (name != NULL, NULL);
1291 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1292 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (interface), NULL);
1293 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
1295 message = dbus_message_new_empty_header ();
1296 if (message == NULL)
1299 if (!_dbus_header_create (&message->header,
1300 DBUS_MESSAGE_TYPE_SIGNAL,
1301 NULL, path, interface, name, NULL))
1303 dbus_message_unref (message);
1307 dbus_message_set_no_reply (message, TRUE);
1313 * Creates a new message that is an error reply to another message.
1314 * Error replies are most common in response to method calls, but
1315 * can be returned in reply to any message.
1317 * The error name must be a valid error name according to the syntax
1318 * given in the D-Bus specification. If you don't want to make
1319 * up an error name just use #DBUS_ERROR_FAILED.
1321 * @param reply_to the message we're replying to
1322 * @param error_name the error name
1323 * @param error_message the error message string (or #NULL for none, but please give a message)
1324 * @returns a new error message object, free with dbus_message_unref()
1327 dbus_message_new_error (DBusMessage *reply_to,
1328 const char *error_name,
1329 const char *error_message)
1331 DBusMessage *message;
1333 DBusMessageIter iter;
1335 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1336 _dbus_return_val_if_fail (error_name != NULL, NULL);
1337 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1339 sender = dbus_message_get_sender (reply_to);
1341 /* sender may be NULL for non-message-bus case or
1342 * when the message bus is dealing with an unregistered
1345 message = dbus_message_new_empty_header ();
1346 if (message == NULL)
1349 if (!_dbus_header_create (&message->header,
1350 DBUS_MESSAGE_TYPE_ERROR,
1351 sender, NULL, NULL, NULL, error_name))
1353 dbus_message_unref (message);
1357 dbus_message_set_no_reply (message, TRUE);
1359 if (!dbus_message_set_reply_serial (message,
1360 dbus_message_get_serial (reply_to)))
1362 dbus_message_unref (message);
1366 if (error_message != NULL)
1368 dbus_message_iter_init_append (message, &iter);
1369 if (!dbus_message_iter_append_basic (&iter,
1373 dbus_message_unref (message);
1382 * Creates a new message that is an error reply to another message, allowing
1383 * you to use printf formatting.
1385 * See dbus_message_new_error() for details - this function is the same
1386 * aside from the printf formatting.
1388 * @todo add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to
1389 * public header, see DBUS_DEPRECATED for an example)
1391 * @param reply_to the original message
1392 * @param error_name the error name
1393 * @param error_format the error message format as with printf
1394 * @param ... format string arguments
1395 * @returns a new error message
1398 dbus_message_new_error_printf (DBusMessage *reply_to,
1399 const char *error_name,
1400 const char *error_format,
1405 DBusMessage *message;
1407 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1408 _dbus_return_val_if_fail (error_name != NULL, NULL);
1409 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1411 if (!_dbus_string_init (&str))
1414 va_start (args, error_format);
1416 if (_dbus_string_append_printf_valist (&str, error_format, args))
1417 message = dbus_message_new_error (reply_to, error_name,
1418 _dbus_string_get_const_data (&str));
1422 _dbus_string_free (&str);
1431 * Creates a new message that is an exact replica of the message
1432 * specified, except that its refcount is set to 1, its message serial
1433 * is reset to 0, and if the original message was "locked" (in the
1434 * outgoing message queue and thus not modifiable) the new message
1435 * will not be locked.
1437 * @todo This function can't be used in programs that try to recover from OOM errors.
1439 * @param message the message
1440 * @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.
1443 dbus_message_copy (const DBusMessage *message)
1445 DBusMessage *retval;
1447 _dbus_return_val_if_fail (message != NULL, NULL);
1449 retval = dbus_new0 (DBusMessage, 1);
1453 _dbus_atomic_inc (&retval->refcount);
1454 retval->byte_order = message->byte_order;
1455 retval->locked = FALSE;
1456 #ifndef DBUS_DISABLE_CHECKS
1457 retval->generation = message->generation;
1460 if (!_dbus_header_copy (&message->header, &retval->header))
1466 if (!_dbus_string_init_preallocated (&retval->body,
1467 _dbus_string_get_length (&message->body)))
1469 _dbus_header_free (&retval->header);
1474 if (!_dbus_string_copy (&message->body, 0,
1478 #ifdef HAVE_UNIX_FD_PASSING
1479 retval->unix_fds = dbus_new(int, message->n_unix_fds);
1480 if (retval->unix_fds == NULL && message->n_unix_fds > 0)
1483 retval->n_unix_fds_allocated = message->n_unix_fds;
1485 for (retval->n_unix_fds = 0;
1486 retval->n_unix_fds < message->n_unix_fds;
1487 retval->n_unix_fds++)
1489 retval->unix_fds[retval->n_unix_fds] = _dbus_dup(message->unix_fds[retval->n_unix_fds], NULL);
1491 if (retval->unix_fds[retval->n_unix_fds] < 0)
1500 _dbus_header_free (&retval->header);
1501 _dbus_string_free (&retval->body);
1503 #ifdef HAVE_UNIX_FD_PASSING
1504 close_unix_fds(retval->unix_fds, &retval->n_unix_fds);
1505 dbus_free(retval->unix_fds);
1515 * Increments the reference count of a DBusMessage.
1517 * @param message the message
1518 * @returns the message
1519 * @see dbus_message_unref
1522 dbus_message_ref (DBusMessage *message)
1524 #ifndef DBUS_DISABLE_ASSERT
1525 dbus_int32_t old_refcount;
1528 _dbus_return_val_if_fail (message != NULL, NULL);
1529 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1530 _dbus_return_val_if_fail (!message->in_cache, NULL);
1532 #ifdef DBUS_DISABLE_ASSERT
1533 _dbus_atomic_inc (&message->refcount);
1535 old_refcount = _dbus_atomic_inc (&message->refcount);
1536 _dbus_assert (old_refcount >= 1);
1543 * Decrements the reference count of a DBusMessage, freeing the
1544 * message if the count reaches 0.
1546 * @param message the message
1547 * @see dbus_message_ref
1550 dbus_message_unref (DBusMessage *message)
1552 dbus_int32_t old_refcount;
1554 _dbus_return_if_fail (message != NULL);
1555 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1556 _dbus_return_if_fail (!message->in_cache);
1558 old_refcount = _dbus_atomic_dec (&message->refcount);
1560 _dbus_assert (old_refcount >= 1);
1562 if (old_refcount == 1)
1564 /* Calls application callbacks! */
1565 dbus_message_cache_or_finalize (message);
1570 * Gets the type of a message. Types include
1571 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1572 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1573 * types are allowed and all code must silently ignore messages of
1574 * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
1576 * @param message the message
1577 * @returns the type of the message
1580 dbus_message_get_type (DBusMessage *message)
1582 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1584 return _dbus_header_get_message_type (&message->header);
1588 * Appends fields to a message given a variable argument list. The
1589 * variable argument list should contain the type of each argument
1590 * followed by the value to append. Appendable types are basic types,
1591 * and arrays of fixed-length basic types (except arrays of Unix file
1592 * descriptors). To append variable-length basic types, or any more
1593 * complex value, you have to use an iterator rather than this
1596 * To append a basic type, specify its type code followed by the
1597 * address of the value. For example:
1601 * dbus_int32_t v_INT32 = 42;
1602 * const char *v_STRING = "Hello World";
1603 * dbus_message_append_args (message,
1604 * DBUS_TYPE_INT32, &v_INT32,
1605 * DBUS_TYPE_STRING, &v_STRING,
1606 * DBUS_TYPE_INVALID);
1609 * To append an array of fixed-length basic types (except Unix file
1610 * descriptors), pass in the DBUS_TYPE_ARRAY typecode, the element
1611 * typecode, the address of the array pointer, and a 32-bit integer
1612 * giving the number of elements in the array. So for example: @code
1613 * const dbus_int32_t array[] = { 1, 2, 3 }; const dbus_int32_t
1614 * *v_ARRAY = array; dbus_message_append_args (message,
1615 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3, DBUS_TYPE_INVALID);
1618 * This function does not support arrays of Unix file descriptors. If
1619 * you need those you need to manually recurse into the array.
1621 * For Unix file descriptors this function will internally duplicate
1622 * the descriptor you passed in. Hence you may close the descriptor
1623 * immediately after this call.
1625 * @warning in C, given "int array[]", "&array == array" (the
1626 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
1627 * So if you're using an array instead of a pointer you have to create
1628 * a pointer variable, assign the array to it, then take the address
1629 * of the pointer variable. For strings it works to write
1630 * const char *array = "Hello" and then use &array though.
1632 * The last argument to this function must be #DBUS_TYPE_INVALID,
1633 * marking the end of the argument list. If you don't do this
1634 * then libdbus won't know to stop and will read invalid memory.
1636 * String/signature/path arrays should be passed in as "const char***
1637 * address_of_array" and "int n_elements"
1639 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1641 * @todo If this fails due to lack of memory, the message is hosed and
1642 * you have to start over building the whole message.
1644 * @param message the message
1645 * @param first_arg_type type of the first argument
1646 * @param ... value of first argument, list of additional type-value pairs
1647 * @returns #TRUE on success
1650 dbus_message_append_args (DBusMessage *message,
1657 _dbus_return_val_if_fail (message != NULL, FALSE);
1659 va_start (var_args, first_arg_type);
1660 retval = dbus_message_append_args_valist (message,
1669 * Like dbus_message_append_args() but takes a va_list for use by language bindings.
1671 * @todo for now, if this function fails due to OOM it will leave
1672 * the message half-written and you have to discard the message
1675 * @see dbus_message_append_args.
1676 * @param message the message
1677 * @param first_arg_type type of first argument
1678 * @param var_args value of first argument, then list of type/value pairs
1679 * @returns #TRUE on success
1682 dbus_message_append_args_valist (DBusMessage *message,
1687 DBusMessageIter iter;
1689 _dbus_return_val_if_fail (message != NULL, FALSE);
1691 type = first_arg_type;
1693 dbus_message_iter_init_append (message, &iter);
1695 while (type != DBUS_TYPE_INVALID)
1697 if (dbus_type_is_basic (type))
1699 const DBusBasicValue *value;
1700 value = va_arg (var_args, const DBusBasicValue*);
1702 if (!dbus_message_iter_append_basic (&iter,
1707 else if (type == DBUS_TYPE_ARRAY)
1710 DBusMessageIter array;
1713 element_type = va_arg (var_args, int);
1715 buf[0] = element_type;
1717 if (!dbus_message_iter_open_container (&iter,
1723 if (dbus_type_is_fixed (element_type) &&
1724 element_type != DBUS_TYPE_UNIX_FD)
1726 const DBusBasicValue **value;
1729 value = va_arg (var_args, const DBusBasicValue**);
1730 n_elements = va_arg (var_args, int);
1732 if (!dbus_message_iter_append_fixed_array (&array,
1736 dbus_message_iter_abandon_container (&iter, &array);
1740 else if (element_type == DBUS_TYPE_STRING ||
1741 element_type == DBUS_TYPE_SIGNATURE ||
1742 element_type == DBUS_TYPE_OBJECT_PATH)
1744 const char ***value_p;
1749 value_p = va_arg (var_args, const char***);
1750 n_elements = va_arg (var_args, int);
1755 while (i < n_elements)
1757 if (!dbus_message_iter_append_basic (&array,
1760 dbus_message_iter_abandon_container (&iter, &array);
1768 _dbus_warn ("arrays of %s can't be appended with %s for now\n",
1769 _dbus_type_to_string (element_type),
1770 _DBUS_FUNCTION_NAME);
1774 if (!dbus_message_iter_close_container (&iter, &array))
1777 #ifndef DBUS_DISABLE_CHECKS
1780 _dbus_warn ("type %s isn't supported yet in %s\n",
1781 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
1786 type = va_arg (var_args, int);
1796 * Gets arguments from a message given a variable argument list. The
1797 * supported types include those supported by
1798 * dbus_message_append_args(); that is, basic types and arrays of
1799 * fixed-length basic types. The arguments are the same as they would
1800 * be for dbus_message_iter_get_basic() or
1801 * dbus_message_iter_get_fixed_array().
1803 * In addition to those types, arrays of string, object path, and
1804 * signature are supported; but these are returned as allocated memory
1805 * and must be freed with dbus_free_string_array(), while the other
1806 * types are returned as const references. To get a string array
1807 * pass in "char ***array_location" and "int *n_elements".
1809 * Similar to dbus_message_get_fixed_array() this function does not
1810 * support arrays of type DBUS_TYPE_UNIX_FD. If you need to parse
1811 * messages with arrays of Unix file descriptors you need to recurse
1812 * into the array manually.
1814 * Unix file descriptors that are read with this function will have
1815 * the FD_CLOEXEC flag set. If you need them without this flag set,
1816 * make sure to unset it with fcntl().
1818 * The variable argument list should contain the type of the argument
1819 * followed by a pointer to where the value should be stored. The list
1820 * is terminated with #DBUS_TYPE_INVALID.
1822 * Except for string arrays, the returned values are constant; do not
1823 * free them. They point into the #DBusMessage.
1825 * If the requested arguments are not present, or do not have the
1826 * requested types, then an error will be set.
1828 * If more arguments than requested are present, the requested
1829 * arguments are returned and the extra arguments are ignored.
1831 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1833 * @param message the message
1834 * @param error error to be filled in on failure
1835 * @param first_arg_type the first argument type
1836 * @param ... location for first argument value, then list of type-location pairs
1837 * @returns #FALSE if the error was set
1840 dbus_message_get_args (DBusMessage *message,
1848 _dbus_return_val_if_fail (message != NULL, FALSE);
1849 _dbus_return_val_if_error_is_set (error, FALSE);
1851 va_start (var_args, first_arg_type);
1852 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
1859 * Like dbus_message_get_args but takes a va_list for use by language bindings.
1861 * @see dbus_message_get_args
1862 * @param message the message
1863 * @param error error to be filled in
1864 * @param first_arg_type type of the first argument
1865 * @param var_args return location for first argument, followed by list of type/location pairs
1866 * @returns #FALSE if error was set
1869 dbus_message_get_args_valist (DBusMessage *message,
1874 DBusMessageIter iter;
1876 _dbus_return_val_if_fail (message != NULL, FALSE);
1877 _dbus_return_val_if_error_is_set (error, FALSE);
1879 dbus_message_iter_init (message, &iter);
1880 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
1884 _dbus_message_iter_init_common (DBusMessage *message,
1885 DBusMessageRealIter *real,
1888 _dbus_assert (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
1890 /* Since the iterator will read or write who-knows-what from the
1891 * message, we need to get in the right byte order
1893 ensure_byte_order (message);
1895 real->message = message;
1896 real->changed_stamp = message->changed_stamp;
1897 real->iter_type = iter_type;
1898 real->sig_refcount = 0;
1902 * Initializes a #DBusMessageIter for reading the arguments of the
1903 * message passed in.
1905 * When possible, dbus_message_get_args() is much more convenient.
1906 * Some types of argument can only be read with #DBusMessageIter
1909 * The easiest way to iterate is like this:
1911 * dbus_message_iter_init (message, &iter);
1912 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
1913 * dbus_message_iter_next (&iter);
1916 * #DBusMessageIter contains no allocated memory; it need not be
1917 * freed, and can be copied by assignment or memcpy().
1919 * @param message the message
1920 * @param iter pointer to an iterator to initialize
1921 * @returns #FALSE if the message has no arguments
1924 dbus_message_iter_init (DBusMessage *message,
1925 DBusMessageIter *iter)
1927 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1928 const DBusString *type_str;
1931 _dbus_return_val_if_fail (message != NULL, FALSE);
1932 _dbus_return_val_if_fail (iter != NULL, FALSE);
1934 get_const_signature (&message->header, &type_str, &type_pos);
1936 _dbus_message_iter_init_common (message, real,
1937 DBUS_MESSAGE_ITER_TYPE_READER);
1939 _dbus_type_reader_init (&real->u.reader,
1940 message->byte_order,
1945 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
1949 * Checks if an iterator has any more fields.
1951 * @param iter the message iter
1952 * @returns #TRUE if there are more fields following
1955 dbus_message_iter_has_next (DBusMessageIter *iter)
1957 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1959 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
1960 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
1962 return _dbus_type_reader_has_next (&real->u.reader);
1966 * Moves the iterator to the next field, if any. If there's no next
1967 * field, returns #FALSE. If the iterator moves forward, returns
1970 * @param iter the message iter
1971 * @returns #TRUE if the iterator was moved to the next field
1974 dbus_message_iter_next (DBusMessageIter *iter)
1976 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1978 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
1979 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
1981 return _dbus_type_reader_next (&real->u.reader);
1985 * Returns the argument type of the argument that the message iterator
1986 * points to. If the iterator is at the end of the message, returns
1987 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
1990 * dbus_message_iter_init (message, &iter);
1991 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
1992 * dbus_message_iter_next (&iter);
1995 * @param iter the message iter
1996 * @returns the argument type
1999 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
2001 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2003 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2004 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2006 return _dbus_type_reader_get_current_type (&real->u.reader);
2010 * Returns the element type of the array that the message iterator
2011 * points to. Note that you need to check that the iterator points to
2012 * an array prior to using this function.
2014 * @param iter the message iter
2015 * @returns the array element type
2018 dbus_message_iter_get_element_type (DBusMessageIter *iter)
2020 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2022 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2023 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
2024 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
2026 return _dbus_type_reader_get_element_type (&real->u.reader);
2030 * Recurses into a container value when reading values from a message,
2031 * initializing a sub-iterator to use for traversing the child values
2034 * Note that this recurses into a value, not a type, so you can only
2035 * recurse if the value exists. The main implication of this is that
2036 * if you have for example an empty array of array of int32, you can
2037 * recurse into the outermost array, but it will have no values, so
2038 * you won't be able to recurse further. There's no array of int32 to
2041 * If a container is an array of fixed-length types (except Unix file
2042 * descriptors), it is much more efficient to use
2043 * dbus_message_iter_get_fixed_array() to get the whole array in one
2044 * shot, rather than individually walking over the array elements.
2046 * Be sure you have somehow checked that
2047 * dbus_message_iter_get_arg_type() matches the type you are expecting
2048 * to recurse into. Results of this function are undefined if there is
2049 * no container to recurse into at the current iterator position.
2051 * @param iter the message iterator
2052 * @param sub the sub-iterator to initialize
2055 dbus_message_iter_recurse (DBusMessageIter *iter,
2056 DBusMessageIter *sub)
2058 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2059 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2061 _dbus_return_if_fail (_dbus_message_iter_check (real));
2062 _dbus_return_if_fail (sub != NULL);
2065 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
2069 * Returns the current signature of a message iterator. This
2070 * is useful primarily for dealing with variants; one can
2071 * recurse into a variant and determine the signature of
2072 * the variant's value.
2074 * The returned string must be freed with dbus_free().
2076 * @param iter the message iterator
2077 * @returns the contained signature, or NULL if out of memory
2080 dbus_message_iter_get_signature (DBusMessageIter *iter)
2082 const DBusString *sig;
2086 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2088 _dbus_return_val_if_fail (_dbus_message_iter_check (real), NULL);
2090 if (!_dbus_string_init (&retstr))
2093 _dbus_type_reader_get_signature (&real->u.reader, &sig,
2095 if (!_dbus_string_append_len (&retstr,
2096 _dbus_string_get_const_data (sig) + start,
2099 if (!_dbus_string_steal_data (&retstr, &ret))
2101 _dbus_string_free (&retstr);
2106 * Reads a basic-typed value from the message iterator.
2107 * Basic types are the non-containers such as integer and string.
2109 * The value argument should be the address of a location to store
2110 * the returned value. So for int32 it should be a "dbus_int32_t*"
2111 * and for string a "const char**". The returned value is
2112 * by reference and should not be freed.
2114 * This call duplicates Unix file descriptors when reading them. It is
2115 * your job to close them when you don't need them anymore.
2117 * Unix file descriptors that are read with this function will have
2118 * the FD_CLOEXEC flag set. If you need them without this flag set,
2119 * make sure to unset it with fcntl().
2121 * Be sure you have somehow checked that
2122 * dbus_message_iter_get_arg_type() matches the type you are
2123 * expecting, or you'll crash when you try to use an integer as a
2124 * string or something.
2126 * To read any container type (array, struct, dict) you will need to
2127 * recurse into the container with dbus_message_iter_recurse(). If
2128 * the container is an array of fixed-length values (except Unix file
2129 * descriptors), you can get all the array elements at once with
2130 * dbus_message_iter_get_fixed_array(). Otherwise, you have to iterate
2131 * over the container's contents one value at a time.
2133 * All basic-typed values are guaranteed to fit in 8 bytes. So you can
2134 * write code like this:
2137 * dbus_uint64_t value;
2139 * dbus_message_iter_get_basic (&read_iter, &value);
2140 * type = dbus_message_iter_get_arg_type (&read_iter);
2141 * dbus_message_iter_append_basic (&write_iter, type, &value);
2144 * On some really obscure platforms dbus_uint64_t might not exist, if
2145 * you need to worry about this you will know. dbus_uint64_t is just
2146 * one example of a type that's large enough to hold any possible
2147 * value, you could use a struct or char[8] instead if you like.
2149 * @param iter the iterator
2150 * @param value location to store the value
2153 dbus_message_iter_get_basic (DBusMessageIter *iter,
2156 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2158 _dbus_return_if_fail (_dbus_message_iter_check (real));
2159 _dbus_return_if_fail (value != NULL);
2161 if (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_UNIX_FD)
2163 #ifdef HAVE_UNIX_FD_PASSING
2166 _dbus_type_reader_read_basic(&real->u.reader, &idx);
2168 if (idx.u32 >= real->message->n_unix_fds) {
2169 /* Hmm, we cannot really signal an error here, so let's make
2170 sure to return an invalid fd. */
2171 *((int*) value) = -1;
2175 *((int*) value) = _dbus_dup(real->message->unix_fds[idx.u32], NULL);
2177 *((int*) value) = -1;
2182 _dbus_type_reader_read_basic (&real->u.reader,
2188 * Returns the number of bytes in the array as marshaled in the wire
2189 * protocol. The iterator must currently be inside an array-typed
2192 * This function is deprecated on the grounds that it is stupid. Why
2193 * would you want to know how many bytes are in the array as marshaled
2194 * in the wire protocol? For now, use the n_elements returned from
2195 * dbus_message_iter_get_fixed_array() instead, or iterate over the
2196 * array values and count them.
2198 * @todo introduce a variant of this get_n_elements that returns
2199 * the number of elements, though with a non-fixed array it will not
2200 * be very efficient, so maybe it's not good.
2202 * @param iter the iterator
2203 * @returns the number of bytes in the array
2206 dbus_message_iter_get_array_len (DBusMessageIter *iter)
2208 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2210 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2212 return _dbus_type_reader_get_array_length (&real->u.reader);
2216 * Reads a block of fixed-length values from the message iterator.
2217 * Fixed-length values are those basic types that are not string-like,
2218 * such as integers, bool, double. The returned block will be from the
2219 * current position in the array until the end of the array.
2221 * There is one exception here: although DBUS_TYPE_UNIX_FD is
2222 * considered a 'fixed' type arrays of this type may not be read with
2225 * The message iter should be "in" the array (that is, you recurse into the
2226 * array, and then you call dbus_message_iter_get_fixed_array() on the
2227 * "sub-iterator" created by dbus_message_iter_recurse()).
2229 * The value argument should be the address of a location to store the
2230 * returned array. So for int32 it should be a "const dbus_int32_t**"
2231 * The returned value is by reference and should not be freed.
2233 * This function should only be used if dbus_type_is_fixed() returns
2234 * #TRUE for the element type.
2236 * If an array's elements are not fixed in size, you have to recurse
2237 * into the array with dbus_message_iter_recurse() and read the
2238 * elements one by one.
2240 * Because the array is not copied, this function runs in constant
2241 * time and is fast; it's much preferred over walking the entire array
2242 * with an iterator. (However, you can always use
2243 * dbus_message_iter_recurse(), even for fixed-length types;
2244 * dbus_message_iter_get_fixed_array() is just an optimization.)
2246 * @param iter the iterator
2247 * @param value location to store the block
2248 * @param n_elements number of elements in the block
2251 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
2255 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2256 int subtype = _dbus_type_reader_get_current_type(&real->u.reader);
2258 _dbus_return_if_fail (_dbus_message_iter_check (real));
2259 _dbus_return_if_fail (value != NULL);
2260 _dbus_return_if_fail ((subtype == DBUS_TYPE_INVALID) ||
2261 (dbus_type_is_fixed (subtype) && subtype != DBUS_TYPE_UNIX_FD));
2263 _dbus_type_reader_read_fixed_multi (&real->u.reader,
2268 * Initializes a #DBusMessageIter for appending arguments to the end
2271 * @todo If appending any of the arguments fails due to lack of
2272 * memory, the message is hosed and you have to start over building
2273 * the whole message.
2275 * @param message the message
2276 * @param iter pointer to an iterator to initialize
2279 dbus_message_iter_init_append (DBusMessage *message,
2280 DBusMessageIter *iter)
2282 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2284 _dbus_return_if_fail (message != NULL);
2285 _dbus_return_if_fail (iter != NULL);
2287 _dbus_message_iter_init_common (message, real,
2288 DBUS_MESSAGE_ITER_TYPE_WRITER);
2290 /* We create the signature string and point iterators at it "on demand"
2291 * when a value is actually appended. That means that init() never fails
2294 _dbus_type_writer_init_types_delayed (&real->u.writer,
2295 message->byte_order,
2297 _dbus_string_get_length (&message->body));
2301 * Creates a temporary signature string containing the current
2302 * signature, stores it in the iterator, and points the iterator to
2303 * the end of it. Used any time we write to the message.
2305 * @param real an iterator without a type_str
2306 * @returns #FALSE if no memory
2309 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
2312 const DBusString *current_sig;
2313 int current_sig_pos;
2315 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2317 if (real->u.writer.type_str != NULL)
2319 _dbus_assert (real->sig_refcount > 0);
2320 real->sig_refcount += 1;
2324 str = dbus_new (DBusString, 1);
2328 if (!_dbus_header_get_field_raw (&real->message->header,
2329 DBUS_HEADER_FIELD_SIGNATURE,
2330 ¤t_sig, ¤t_sig_pos))
2337 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
2338 current_sig_pos += 1; /* move on to sig data */
2340 if (!_dbus_string_init_preallocated (str, current_len + 4))
2346 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
2349 _dbus_string_free (str);
2356 if (!_dbus_string_init_preallocated (str, 4))
2363 real->sig_refcount = 1;
2365 _dbus_type_writer_add_types (&real->u.writer,
2366 str, _dbus_string_get_length (str));
2371 * Sets the new signature as the message signature, frees the
2372 * signature string, and marks the iterator as not having a type_str
2373 * anymore. Frees the signature even if it fails, so you can't
2374 * really recover from failure. Kinda busted.
2376 * @param real an iterator without a type_str
2377 * @returns #FALSE if no memory
2380 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2383 const char *v_STRING;
2386 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2387 _dbus_assert (real->u.writer.type_str != NULL);
2388 _dbus_assert (real->sig_refcount > 0);
2390 real->sig_refcount -= 1;
2392 if (real->sig_refcount > 0)
2394 _dbus_assert (real->sig_refcount == 0);
2398 str = real->u.writer.type_str;
2400 v_STRING = _dbus_string_get_const_data (str);
2401 if (!_dbus_header_set_field_basic (&real->message->header,
2402 DBUS_HEADER_FIELD_SIGNATURE,
2403 DBUS_TYPE_SIGNATURE,
2407 _dbus_type_writer_remove_types (&real->u.writer);
2408 _dbus_string_free (str);
2415 * Frees the signature string and marks the iterator as not having a
2416 * type_str anymore. Since the new signature is not set, the message
2417 * will generally be hosed after this is called.
2419 * @param real an iterator without a type_str
2422 _dbus_message_iter_abandon_signature (DBusMessageRealIter *real)
2426 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2427 _dbus_assert (real->u.writer.type_str != NULL);
2428 _dbus_assert (real->sig_refcount > 0);
2430 real->sig_refcount -= 1;
2432 if (real->sig_refcount > 0)
2434 _dbus_assert (real->sig_refcount == 0);
2436 str = real->u.writer.type_str;
2438 _dbus_type_writer_remove_types (&real->u.writer);
2439 _dbus_string_free (str);
2443 #ifndef DBUS_DISABLE_CHECKS
2445 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2447 if (!_dbus_message_iter_check (iter))
2450 if (iter->message->locked)
2452 _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)\n");
2458 #endif /* DBUS_DISABLE_CHECKS */
2460 #ifdef HAVE_UNIX_FD_PASSING
2462 expand_fd_array(DBusMessage *m,
2467 /* This makes space for adding n new fds to the array and returns a
2468 pointer to the place were the first fd should be put. */
2470 if (m->n_unix_fds + n > m->n_unix_fds_allocated)
2475 /* Make twice as much space as necessary */
2476 k = (m->n_unix_fds + n) * 2;
2478 /* Allocate at least four */
2482 p = dbus_realloc(m->unix_fds, k * sizeof(int));
2487 m->n_unix_fds_allocated = k;
2490 return m->unix_fds + m->n_unix_fds;
2495 * Appends a basic-typed value to the message. The basic types are the
2496 * non-container types such as integer and string.
2498 * The "value" argument should be the address of a basic-typed value.
2499 * So for string, const char**. For integer, dbus_int32_t*.
2501 * For Unix file descriptors this function will internally duplicate
2502 * the descriptor you passed in. Hence you may close the descriptor
2503 * immediately after this call.
2505 * @todo If this fails due to lack of memory, the message is hosed and
2506 * you have to start over building the whole message.
2508 * @param iter the append iterator
2509 * @param type the type of the value
2510 * @param value the address of the value
2511 * @returns #FALSE if not enough memory
2514 dbus_message_iter_append_basic (DBusMessageIter *iter,
2518 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2521 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2522 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2523 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2524 _dbus_return_val_if_fail (value != NULL, FALSE);
2526 #ifndef DBUS_DISABLE_CHECKS
2529 const char * const *string_p;
2530 const dbus_bool_t *bool_p;
2532 case DBUS_TYPE_STRING:
2534 _dbus_return_val_if_fail (_dbus_check_is_valid_utf8 (*string_p), FALSE);
2537 case DBUS_TYPE_OBJECT_PATH:
2539 _dbus_return_val_if_fail (_dbus_check_is_valid_path (*string_p), FALSE);
2542 case DBUS_TYPE_SIGNATURE:
2544 _dbus_return_val_if_fail (_dbus_check_is_valid_signature (*string_p), FALSE);
2547 case DBUS_TYPE_BOOLEAN:
2549 _dbus_return_val_if_fail (*bool_p == 0 || *bool_p == 1, FALSE);
2554 /* nothing to check, all possible values are allowed */
2559 if (!_dbus_message_iter_open_signature (real))
2562 if (type == DBUS_TYPE_UNIX_FD)
2564 #ifdef HAVE_UNIX_FD_PASSING
2568 /* First step, include the fd in the fd list of this message */
2569 if (!(fds = expand_fd_array(real->message, 1)))
2572 *fds = _dbus_dup(*(int*) value, NULL);
2576 u = real->message->n_unix_fds;
2578 /* Second step, write the index to the fd */
2579 if (!(ret = _dbus_type_writer_write_basic (&real->u.writer, DBUS_TYPE_UNIX_FD, &u))) {
2580 _dbus_close(*fds, NULL);
2584 real->message->n_unix_fds += 1;
2587 /* Final step, update the header accordingly */
2588 ret = _dbus_header_set_field_basic (&real->message->header,
2589 DBUS_HEADER_FIELD_UNIX_FDS,
2593 /* If any of these operations fail the message is
2594 hosed. However, no memory or fds should be leaked since what
2595 has been added to message has been added to the message, and
2596 can hence be accounted for when the message is being
2604 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
2607 if (!_dbus_message_iter_close_signature (real))
2614 * Appends a block of fixed-length values to an array. The
2615 * fixed-length types are all basic types that are not string-like. So
2616 * int32, double, bool, etc. (Unix file descriptors however are not
2617 * supported.) You must call dbus_message_iter_open_container() to
2618 * open an array of values before calling this function. You may call
2619 * this function multiple times (and intermixed with calls to
2620 * dbus_message_iter_append_basic()) for the same array.
2622 * The "value" argument should be the address of the array. So for
2623 * integer, "dbus_int32_t**" is expected for example.
2625 * @warning in C, given "int array[]", "&array == array" (the
2626 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2627 * So if you're using an array instead of a pointer you have to create
2628 * a pointer variable, assign the array to it, then take the address
2629 * of the pointer variable.
2631 * const dbus_int32_t array[] = { 1, 2, 3 };
2632 * const dbus_int32_t *v_ARRAY = array;
2633 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
2634 * fprintf (stderr, "No memory!\n");
2636 * For strings it works to write const char *array = "Hello" and then
2637 * use &array though.
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 element_type the type of the array elements
2644 * @param value the address of the array
2645 * @param n_elements the number of elements to append
2646 * @returns #FALSE if not enough memory
2649 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
2654 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2657 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2658 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2659 _dbus_return_val_if_fail (dbus_type_is_fixed (element_type) && element_type != DBUS_TYPE_UNIX_FD, FALSE);
2660 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
2661 _dbus_return_val_if_fail (value != NULL, FALSE);
2662 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
2663 _dbus_return_val_if_fail (n_elements <=
2664 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
2667 #ifndef DBUS_DISABLE_CHECKS
2668 if (element_type == DBUS_TYPE_BOOLEAN)
2670 const dbus_bool_t * const *bools = value;
2673 for (i = 0; i < n_elements; i++)
2675 _dbus_return_val_if_fail ((*bools)[i] == 0 || (*bools)[i] == 1, FALSE);
2680 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
2686 * Appends a container-typed value to the message; you are required to
2687 * append the contents of the container using the returned
2688 * sub-iterator, and then call
2689 * dbus_message_iter_close_container(). Container types are for
2690 * example struct, variant, and array. For variants, the
2691 * contained_signature should be the type of the single value inside
2692 * the variant. For structs and dict entries, contained_signature
2693 * should be #NULL; it will be set to whatever types you write into
2694 * the struct. For arrays, contained_signature should be the type of
2695 * the array elements.
2697 * @todo If this fails due to lack of memory, the message is hosed and
2698 * you have to start over building the whole message.
2700 * @param iter the append iterator
2701 * @param type the type of the value
2702 * @param contained_signature the type of container contents
2703 * @param sub sub-iterator to initialize
2704 * @returns #FALSE if not enough memory
2707 dbus_message_iter_open_container (DBusMessageIter *iter,
2709 const char *contained_signature,
2710 DBusMessageIter *sub)
2712 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2713 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2714 DBusString contained_str;
2716 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2717 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2718 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
2719 _dbus_return_val_if_fail (sub != NULL, FALSE);
2720 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
2721 contained_signature == NULL) ||
2722 (type == DBUS_TYPE_DICT_ENTRY &&
2723 contained_signature == NULL) ||
2724 (type == DBUS_TYPE_VARIANT &&
2725 contained_signature != NULL) ||
2726 (type == DBUS_TYPE_ARRAY &&
2727 contained_signature != NULL), FALSE);
2729 /* this would fail if the contained_signature is a dict entry, since
2730 * dict entries are invalid signatures standalone (they must be in
2733 _dbus_return_val_if_fail ((type == DBUS_TYPE_ARRAY && contained_signature && *contained_signature == DBUS_DICT_ENTRY_BEGIN_CHAR) ||
2734 (contained_signature == NULL ||
2735 _dbus_check_is_valid_signature (contained_signature)),
2738 if (!_dbus_message_iter_open_signature (real))
2743 if (contained_signature != NULL)
2745 _dbus_string_init_const (&contained_str, contained_signature);
2747 return _dbus_type_writer_recurse (&real->u.writer,
2750 &real_sub->u.writer);
2754 return _dbus_type_writer_recurse (&real->u.writer,
2757 &real_sub->u.writer);
2763 * Closes a container-typed value appended to the message; may write
2764 * out more information to the message known only after the entire
2765 * container is written, and may free resources created by
2766 * dbus_message_iter_open_container().
2768 * @todo If this fails due to lack of memory, the message is hosed and
2769 * you have to start over building the whole message.
2771 * @param iter the append iterator
2772 * @param sub sub-iterator to close
2773 * @returns #FALSE if not enough memory
2776 dbus_message_iter_close_container (DBusMessageIter *iter,
2777 DBusMessageIter *sub)
2779 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2780 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2783 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2784 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2785 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
2786 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2788 ret = _dbus_type_writer_unrecurse (&real->u.writer,
2789 &real_sub->u.writer);
2791 if (!_dbus_message_iter_close_signature (real))
2798 * Abandons creation of a contained-typed value and frees resources created
2799 * by dbus_message_iter_open_container(). Once this returns, the message
2800 * is hosed and you have to start over building the whole message.
2802 * This should only be used to abandon creation of a message when you have
2805 * @param iter the append iterator
2806 * @param sub sub-iterator to close
2809 dbus_message_iter_abandon_container (DBusMessageIter *iter,
2810 DBusMessageIter *sub)
2812 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2813 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2815 _dbus_return_if_fail (_dbus_message_iter_append_check (real));
2816 _dbus_return_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2817 _dbus_return_if_fail (_dbus_message_iter_append_check (real_sub));
2818 _dbus_return_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2820 _dbus_message_iter_abandon_signature (real);
2824 * Sets a flag indicating that the message does not want a reply; if
2825 * this flag is set, the other end of the connection may (but is not
2826 * required to) optimize by not sending method return or error
2827 * replies. If this flag is set, there is no way to know whether the
2828 * message successfully arrived at the remote end. Normally you know a
2829 * message was received when you receive the reply to it.
2831 * The flag is #FALSE by default, that is by default the other end is
2832 * required to reply.
2834 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
2836 * @param message the message
2837 * @param no_reply #TRUE if no reply is desired
2840 dbus_message_set_no_reply (DBusMessage *message,
2841 dbus_bool_t no_reply)
2843 _dbus_return_if_fail (message != NULL);
2844 _dbus_return_if_fail (!message->locked);
2846 _dbus_header_toggle_flag (&message->header,
2847 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
2852 * Returns #TRUE if the message does not expect
2855 * @param message the message
2856 * @returns #TRUE if the message sender isn't waiting for a reply
2859 dbus_message_get_no_reply (DBusMessage *message)
2861 _dbus_return_val_if_fail (message != NULL, FALSE);
2863 return _dbus_header_get_flag (&message->header,
2864 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
2868 * Sets a flag indicating that an owner for the destination name will
2869 * be automatically started before the message is delivered. When this
2870 * flag is set, the message is held until a name owner finishes
2871 * starting up, or fails to start up. In case of failure, the reply
2874 * The flag is set to #TRUE by default, i.e. auto starting is the default.
2876 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
2878 * @param message the message
2879 * @param auto_start #TRUE if auto-starting is desired
2882 dbus_message_set_auto_start (DBusMessage *message,
2883 dbus_bool_t auto_start)
2885 _dbus_return_if_fail (message != NULL);
2886 _dbus_return_if_fail (!message->locked);
2888 _dbus_header_toggle_flag (&message->header,
2889 DBUS_HEADER_FLAG_NO_AUTO_START,
2894 * Returns #TRUE if the message will cause an owner for
2895 * destination name to be auto-started.
2897 * @param message the message
2898 * @returns #TRUE if the message will use auto-start
2901 dbus_message_get_auto_start (DBusMessage *message)
2903 _dbus_return_val_if_fail (message != NULL, FALSE);
2905 return !_dbus_header_get_flag (&message->header,
2906 DBUS_HEADER_FLAG_NO_AUTO_START);
2911 * Sets the object path this message is being sent to (for
2912 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
2913 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
2915 * The path must contain only valid characters as defined
2916 * in the D-Bus specification.
2918 * @param message the message
2919 * @param object_path the path or #NULL to unset
2920 * @returns #FALSE if not enough memory
2923 dbus_message_set_path (DBusMessage *message,
2924 const char *object_path)
2926 _dbus_return_val_if_fail (message != NULL, FALSE);
2927 _dbus_return_val_if_fail (!message->locked, FALSE);
2928 _dbus_return_val_if_fail (object_path == NULL ||
2929 _dbus_check_is_valid_path (object_path),
2932 return set_or_delete_string_field (message,
2933 DBUS_HEADER_FIELD_PATH,
2934 DBUS_TYPE_OBJECT_PATH,
2939 * Gets the object path this message is being sent to (for
2940 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
2941 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
2943 * See also dbus_message_get_path_decomposed().
2945 * The returned string becomes invalid if the message is
2946 * modified, since it points into the wire-marshaled message data.
2948 * @param message the message
2949 * @returns the path (should not be freed) or #NULL
2952 dbus_message_get_path (DBusMessage *message)
2956 _dbus_return_val_if_fail (message != NULL, NULL);
2958 v = NULL; /* in case field doesn't exist */
2959 _dbus_header_get_field_basic (&message->header,
2960 DBUS_HEADER_FIELD_PATH,
2961 DBUS_TYPE_OBJECT_PATH,
2967 * Checks if the message has a particular object path. The object
2968 * path is the destination object for a method call or the emitting
2969 * object for a signal.
2971 * @param message the message
2972 * @param path the path name
2973 * @returns #TRUE if there is a path field in the header
2976 dbus_message_has_path (DBusMessage *message,
2979 const char *msg_path;
2980 msg_path = dbus_message_get_path (message);
2982 if (msg_path == NULL)
2993 if (strcmp (msg_path, path) == 0)
3000 * Gets the object path this message is being sent to
3001 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3002 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
3003 * format (one array element per path component).
3004 * Free the returned array with dbus_free_string_array().
3006 * An empty but non-NULL path array means the path "/".
3007 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
3008 * and the path "/" becomes { NULL }.
3010 * See also dbus_message_get_path().
3012 * @todo this could be optimized by using the len from the message
3013 * instead of calling strlen() again
3015 * @param message the message
3016 * @param path place to store allocated array of path components; #NULL set here if no path field exists
3017 * @returns #FALSE if no memory to allocate the array
3020 dbus_message_get_path_decomposed (DBusMessage *message,
3025 _dbus_return_val_if_fail (message != NULL, FALSE);
3026 _dbus_return_val_if_fail (path != NULL, FALSE);
3030 v = dbus_message_get_path (message);
3033 if (!_dbus_decompose_path (v, strlen (v),
3041 * Sets the interface this message is being sent to
3042 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
3043 * the interface a signal is being emitted from
3044 * (for DBUS_MESSAGE_TYPE_SIGNAL).
3046 * The interface name must contain only valid characters as defined
3047 * in the D-Bus specification.
3049 * @param message the message
3050 * @param interface the interface or #NULL to unset
3051 * @returns #FALSE if not enough memory
3054 dbus_message_set_interface (DBusMessage *message,
3055 const char *interface)
3057 _dbus_return_val_if_fail (message != NULL, FALSE);
3058 _dbus_return_val_if_fail (!message->locked, FALSE);
3059 _dbus_return_val_if_fail (interface == NULL ||
3060 _dbus_check_is_valid_interface (interface),
3063 return set_or_delete_string_field (message,
3064 DBUS_HEADER_FIELD_INTERFACE,
3070 * Gets the interface this message is being sent to
3071 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3072 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
3073 * The interface name is fully-qualified (namespaced).
3074 * Returns #NULL if none.
3076 * The returned string becomes invalid if the message is
3077 * modified, since it points into the wire-marshaled message data.
3079 * @param message the message
3080 * @returns the message interface (should not be freed) or #NULL
3083 dbus_message_get_interface (DBusMessage *message)
3087 _dbus_return_val_if_fail (message != NULL, NULL);
3089 v = NULL; /* in case field doesn't exist */
3090 _dbus_header_get_field_basic (&message->header,
3091 DBUS_HEADER_FIELD_INTERFACE,
3098 * Checks if the message has an interface
3100 * @param message the message
3101 * @param interface the interface name
3102 * @returns #TRUE if the interface field in the header matches
3105 dbus_message_has_interface (DBusMessage *message,
3106 const char *interface)
3108 const char *msg_interface;
3109 msg_interface = dbus_message_get_interface (message);
3111 if (msg_interface == NULL)
3113 if (interface == NULL)
3119 if (interface == NULL)
3122 if (strcmp (msg_interface, interface) == 0)
3130 * Sets the interface member being invoked
3131 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3132 * (DBUS_MESSAGE_TYPE_SIGNAL).
3134 * The member name must contain only valid characters as defined
3135 * in the D-Bus specification.
3137 * @param message the message
3138 * @param member the member or #NULL to unset
3139 * @returns #FALSE if not enough memory
3142 dbus_message_set_member (DBusMessage *message,
3145 _dbus_return_val_if_fail (message != NULL, FALSE);
3146 _dbus_return_val_if_fail (!message->locked, FALSE);
3147 _dbus_return_val_if_fail (member == NULL ||
3148 _dbus_check_is_valid_member (member),
3151 return set_or_delete_string_field (message,
3152 DBUS_HEADER_FIELD_MEMBER,
3158 * Gets the interface member being invoked
3159 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3160 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3162 * The returned string becomes invalid if the message is
3163 * modified, since it points into the wire-marshaled message data.
3165 * @param message the message
3166 * @returns the member name (should not be freed) or #NULL
3169 dbus_message_get_member (DBusMessage *message)
3173 _dbus_return_val_if_fail (message != NULL, NULL);
3175 v = NULL; /* in case field doesn't exist */
3176 _dbus_header_get_field_basic (&message->header,
3177 DBUS_HEADER_FIELD_MEMBER,
3184 * Checks if the message has an interface member
3186 * @param message the message
3187 * @param member the member name
3188 * @returns #TRUE if there is a member field in the header
3191 dbus_message_has_member (DBusMessage *message,
3194 const char *msg_member;
3195 msg_member = dbus_message_get_member (message);
3197 if (msg_member == NULL)
3208 if (strcmp (msg_member, member) == 0)
3216 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
3217 * The name is fully-qualified (namespaced).
3219 * The error name must contain only valid characters as defined
3220 * in the D-Bus specification.
3222 * @param message the message
3223 * @param error_name the name or #NULL to unset
3224 * @returns #FALSE if not enough memory
3227 dbus_message_set_error_name (DBusMessage *message,
3228 const char *error_name)
3230 _dbus_return_val_if_fail (message != NULL, FALSE);
3231 _dbus_return_val_if_fail (!message->locked, FALSE);
3232 _dbus_return_val_if_fail (error_name == NULL ||
3233 _dbus_check_is_valid_error_name (error_name),
3236 return set_or_delete_string_field (message,
3237 DBUS_HEADER_FIELD_ERROR_NAME,
3243 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
3246 * The returned string becomes invalid if the message is
3247 * modified, since it points into the wire-marshaled message data.
3249 * @param message the message
3250 * @returns the error name (should not be freed) or #NULL
3253 dbus_message_get_error_name (DBusMessage *message)
3257 _dbus_return_val_if_fail (message != NULL, NULL);
3259 v = NULL; /* in case field doesn't exist */
3260 _dbus_header_get_field_basic (&message->header,
3261 DBUS_HEADER_FIELD_ERROR_NAME,
3268 * Sets the message's destination. The destination is the name of
3269 * another connection on the bus and may be either the unique name
3270 * assigned by the bus to each connection, or a well-known name
3271 * specified in advance.
3273 * The destination name must contain only valid characters as defined
3274 * in the D-Bus specification.
3276 * @param message the message
3277 * @param destination the destination name or #NULL to unset
3278 * @returns #FALSE if not enough memory
3281 dbus_message_set_destination (DBusMessage *message,
3282 const char *destination)
3284 _dbus_return_val_if_fail (message != NULL, FALSE);
3285 _dbus_return_val_if_fail (!message->locked, FALSE);
3286 _dbus_return_val_if_fail (destination == NULL ||
3287 _dbus_check_is_valid_bus_name (destination),
3290 return set_or_delete_string_field (message,
3291 DBUS_HEADER_FIELD_DESTINATION,
3297 * Gets the destination of a message or #NULL if there is none set.
3299 * The returned string becomes invalid if the message is
3300 * modified, since it points into the wire-marshaled message data.
3302 * @param message the message
3303 * @returns the message destination (should not be freed) or #NULL
3306 dbus_message_get_destination (DBusMessage *message)
3310 _dbus_return_val_if_fail (message != NULL, NULL);
3312 v = NULL; /* in case field doesn't exist */
3313 _dbus_header_get_field_basic (&message->header,
3314 DBUS_HEADER_FIELD_DESTINATION,
3321 * Sets the message sender.
3323 * The sender must be a valid bus name as defined in the D-Bus
3326 * Usually you don't want to call this. The message bus daemon will
3327 * call it to set the origin of each message. If you aren't implementing
3328 * a message bus daemon you shouldn't need to set the sender.
3330 * @param message the message
3331 * @param sender the sender or #NULL to unset
3332 * @returns #FALSE if not enough memory
3335 dbus_message_set_sender (DBusMessage *message,
3338 _dbus_return_val_if_fail (message != NULL, FALSE);
3339 _dbus_return_val_if_fail (!message->locked, FALSE);
3340 _dbus_return_val_if_fail (sender == NULL ||
3341 _dbus_check_is_valid_bus_name (sender),
3344 return set_or_delete_string_field (message,
3345 DBUS_HEADER_FIELD_SENDER,
3351 * Gets the unique name of the connection which originated this
3352 * message, or #NULL if unknown or inapplicable. The sender is filled
3353 * in by the message bus.
3355 * Note, the returned sender is always the unique bus name.
3356 * Connections may own multiple other bus names, but those
3357 * are not found in the sender field.
3359 * The returned string becomes invalid if the message is
3360 * modified, since it points into the wire-marshaled message data.
3362 * @param message the message
3363 * @returns the unique name of the sender or #NULL
3366 dbus_message_get_sender (DBusMessage *message)
3370 _dbus_return_val_if_fail (message != NULL, NULL);
3372 v = NULL; /* in case field doesn't exist */
3373 _dbus_header_get_field_basic (&message->header,
3374 DBUS_HEADER_FIELD_SENDER,
3381 * Gets the type signature of the message, i.e. the arguments in the
3382 * message payload. The signature includes only "in" arguments for
3383 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
3384 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
3385 * what you might expect (that is, it does not include the signature of the
3386 * entire C++-style method).
3388 * The signature is a string made up of type codes such as
3389 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
3390 * the value of #DBUS_TYPE_INVALID).
3392 * The returned string becomes invalid if the message is
3393 * modified, since it points into the wire-marshaled message data.
3395 * @param message the message
3396 * @returns the type signature
3399 dbus_message_get_signature (DBusMessage *message)
3401 const DBusString *type_str;
3404 _dbus_return_val_if_fail (message != NULL, NULL);
3406 get_const_signature (&message->header, &type_str, &type_pos);
3408 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
3412 _dbus_message_has_type_interface_member (DBusMessage *message,
3414 const char *interface,
3419 _dbus_assert (message != NULL);
3420 _dbus_assert (interface != NULL);
3421 _dbus_assert (member != NULL);
3423 if (dbus_message_get_type (message) != type)
3426 /* Optimize by checking the short member name first
3427 * instead of the longer interface name
3430 n = dbus_message_get_member (message);
3432 if (n && strcmp (n, member) == 0)
3434 n = dbus_message_get_interface (message);
3436 if (n == NULL || strcmp (n, interface) == 0)
3444 * Checks whether the message is a method call with the given
3445 * interface and member fields. If the message is not
3446 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
3447 * member field, returns #FALSE. If the interface field is missing,
3448 * then it will be assumed equal to the provided interface. The D-Bus
3449 * protocol allows method callers to leave out the interface name.
3451 * @param message the message
3452 * @param interface the name to check (must not be #NULL)
3453 * @param method the name to check (must not be #NULL)
3455 * @returns #TRUE if the message is the specified method call
3458 dbus_message_is_method_call (DBusMessage *message,
3459 const char *interface,
3462 _dbus_return_val_if_fail (message != NULL, FALSE);
3463 _dbus_return_val_if_fail (interface != NULL, FALSE);
3464 _dbus_return_val_if_fail (method != NULL, FALSE);
3465 /* don't check that interface/method are valid since it would be
3466 * expensive, and not catch many common errors
3469 return _dbus_message_has_type_interface_member (message,
3470 DBUS_MESSAGE_TYPE_METHOD_CALL,
3475 * Checks whether the message is a signal with the given interface and
3476 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
3477 * has a different interface or member field, returns #FALSE.
3479 * @param message the message
3480 * @param interface the name to check (must not be #NULL)
3481 * @param signal_name the name to check (must not be #NULL)
3483 * @returns #TRUE if the message is the specified signal
3486 dbus_message_is_signal (DBusMessage *message,
3487 const char *interface,
3488 const char *signal_name)
3490 _dbus_return_val_if_fail (message != NULL, FALSE);
3491 _dbus_return_val_if_fail (interface != NULL, FALSE);
3492 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
3493 /* don't check that interface/name are valid since it would be
3494 * expensive, and not catch many common errors
3497 return _dbus_message_has_type_interface_member (message,
3498 DBUS_MESSAGE_TYPE_SIGNAL,
3499 interface, signal_name);
3503 * Checks whether the message is an error reply with the given error
3504 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
3505 * different name, returns #FALSE.
3507 * @param message the message
3508 * @param error_name the name to check (must not be #NULL)
3510 * @returns #TRUE if the message is the specified error
3513 dbus_message_is_error (DBusMessage *message,
3514 const char *error_name)
3518 _dbus_return_val_if_fail (message != NULL, FALSE);
3519 _dbus_return_val_if_fail (error_name != NULL, FALSE);
3520 /* don't check that error_name is valid since it would be expensive,
3521 * and not catch many common errors
3524 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3527 n = dbus_message_get_error_name (message);
3529 if (n && strcmp (n, error_name) == 0)
3536 * Checks whether the message was sent to the given name. If the
3537 * message has no destination specified or has a different
3538 * destination, returns #FALSE.
3540 * @param message the message
3541 * @param name the name to check (must not be #NULL)
3543 * @returns #TRUE if the message has the given destination name
3546 dbus_message_has_destination (DBusMessage *message,
3551 _dbus_return_val_if_fail (message != NULL, FALSE);
3552 _dbus_return_val_if_fail (name != NULL, FALSE);
3553 /* don't check that name is valid since it would be expensive, and
3554 * not catch many common errors
3557 s = dbus_message_get_destination (message);
3559 if (s && strcmp (s, name) == 0)
3566 * Checks whether the message has the given unique name as its sender.
3567 * If the message has no sender specified or has a different sender,
3568 * returns #FALSE. Note that a peer application will always have the
3569 * unique name of the connection as the sender. So you can't use this
3570 * function to see whether a sender owned a well-known name.
3572 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
3575 * @param message the message
3576 * @param name the name to check (must not be #NULL)
3578 * @returns #TRUE if the message has the given sender
3581 dbus_message_has_sender (DBusMessage *message,
3586 _dbus_return_val_if_fail (message != NULL, FALSE);
3587 _dbus_return_val_if_fail (name != NULL, FALSE);
3588 /* don't check that name is valid since it would be expensive, and
3589 * not catch many common errors
3592 s = dbus_message_get_sender (message);
3594 if (s && strcmp (s, name) == 0)
3601 * Checks whether the message has the given signature; see
3602 * dbus_message_get_signature() for more details on what the signature
3605 * @param message the message
3606 * @param signature typecode array
3607 * @returns #TRUE if message has the given signature
3610 dbus_message_has_signature (DBusMessage *message,
3611 const char *signature)
3615 _dbus_return_val_if_fail (message != NULL, FALSE);
3616 _dbus_return_val_if_fail (signature != NULL, FALSE);
3617 /* don't check that signature is valid since it would be expensive,
3618 * and not catch many common errors
3621 s = dbus_message_get_signature (message);
3623 if (s && strcmp (s, signature) == 0)
3630 * Sets a #DBusError based on the contents of the given
3631 * message. The error is only set if the message
3632 * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
3633 * The name of the error is set to the name of the message,
3634 * and the error message is set to the first argument
3635 * if the argument exists and is a string.
3637 * The return value indicates whether the error was set (the error is
3638 * set if and only if the message is an error message). So you can
3639 * check for an error reply and convert it to DBusError in one go:
3641 * if (dbus_set_error_from_message (error, reply))
3647 * @param error the error to set
3648 * @param message the message to set it from
3649 * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
3652 dbus_set_error_from_message (DBusError *error,
3653 DBusMessage *message)
3657 _dbus_return_val_if_fail (message != NULL, FALSE);
3658 _dbus_return_val_if_error_is_set (error, FALSE);
3660 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3664 dbus_message_get_args (message, NULL,
3665 DBUS_TYPE_STRING, &str,
3668 dbus_set_error (error, dbus_message_get_error_name (message),
3669 str ? "%s" : NULL, str);
3675 * Checks whether a message contains unix fds
3677 * @param message the message
3678 * @returns #TRUE if the message contains unix fds
3681 dbus_message_contains_unix_fds(DBusMessage *message)
3683 #ifdef HAVE_UNIX_FD_PASSING
3684 _dbus_assert(message);
3686 return message->n_unix_fds > 0;
3695 * @addtogroup DBusMessageInternals
3701 * The initial buffer size of the message loader.
3703 * @todo this should be based on min header size plus some average
3704 * body size, or something. Or rather, the min header size only, if we
3705 * want to try to read only the header, store that in a DBusMessage,
3706 * then read only the body and store that, etc., depends on
3707 * how we optimize _dbus_message_loader_get_buffer() and what
3708 * the exact message format is.
3710 #define INITIAL_LOADER_DATA_LEN 32
3713 * Creates a new message loader. Returns #NULL if memory can't
3716 * @returns new loader, or #NULL.
3719 _dbus_message_loader_new (void)
3721 DBusMessageLoader *loader;
3723 loader = dbus_new0 (DBusMessageLoader, 1);
3727 loader->refcount = 1;
3729 loader->corrupted = FALSE;
3730 loader->corruption_reason = DBUS_VALID;
3732 /* this can be configured by the app, but defaults to the protocol max */
3733 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
3735 /* We set a very relatively conservative default here since due to how
3736 SCM_RIGHTS works we need to preallocate an fd array of the maximum
3737 number of unix fds we want to receive in advance. A
3738 try-and-reallocate loop is not possible. */
3739 loader->max_message_unix_fds = 1024;
3741 if (!_dbus_string_init (&loader->data))
3747 /* preallocate the buffer for speed, ignore failure */
3748 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
3749 _dbus_string_set_length (&loader->data, 0);
3751 #ifdef HAVE_UNIX_FD_PASSING
3752 loader->unix_fds = NULL;
3753 loader->n_unix_fds = loader->n_unix_fds_allocated = 0;
3754 loader->unix_fds_outstanding = FALSE;
3761 * Increments the reference count of the loader.
3763 * @param loader the loader.
3764 * @returns the loader
3767 _dbus_message_loader_ref (DBusMessageLoader *loader)
3769 loader->refcount += 1;
3775 * Decrements the reference count of the loader and finalizes the
3776 * loader when the count reaches zero.
3778 * @param loader the loader.
3781 _dbus_message_loader_unref (DBusMessageLoader *loader)
3783 loader->refcount -= 1;
3784 if (loader->refcount == 0)
3786 #ifdef HAVE_UNIX_FD_PASSING
3787 close_unix_fds(loader->unix_fds, &loader->n_unix_fds);
3788 dbus_free(loader->unix_fds);
3790 _dbus_list_foreach (&loader->messages,
3791 (DBusForeachFunction) dbus_message_unref,
3793 _dbus_list_clear (&loader->messages);
3794 _dbus_string_free (&loader->data);
3800 * Gets the buffer to use for reading data from the network. Network
3801 * data is read directly into an allocated buffer, which is then used
3802 * in the DBusMessage, to avoid as many extra memcpy's as possible.
3803 * The buffer must always be returned immediately using
3804 * _dbus_message_loader_return_buffer(), even if no bytes are
3805 * successfully read.
3807 * @todo this function can be a lot more clever. For example
3808 * it can probably always return a buffer size to read exactly
3809 * the body of the next message, thus avoiding any memory wastage
3812 * @todo we need to enforce a max length on strings in header fields.
3814 * @param loader the message loader.
3815 * @param buffer the buffer
3818 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
3819 DBusString **buffer)
3821 _dbus_assert (!loader->buffer_outstanding);
3823 *buffer = &loader->data;
3825 loader->buffer_outstanding = TRUE;
3829 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
3830 * indicating to the loader how many bytes of the buffer were filled
3831 * in. This function must always be called, even if no bytes were
3832 * successfully read.
3834 * @param loader the loader.
3835 * @param buffer the buffer.
3836 * @param bytes_read number of bytes that were read into the buffer.
3839 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
3843 _dbus_assert (loader->buffer_outstanding);
3844 _dbus_assert (buffer == &loader->data);
3846 loader->buffer_outstanding = FALSE;
3850 * Gets the buffer to use for reading unix fds from the network.
3852 * This works similar to _dbus_message_loader_get_buffer()
3854 * @param loader the message loader.
3855 * @param fds the array to read fds into
3856 * @param max_n_fds how many fds to read at most
3857 * @return TRUE on success, FALSE on OOM
3860 _dbus_message_loader_get_unix_fds(DBusMessageLoader *loader,
3862 unsigned *max_n_fds)
3864 #ifdef HAVE_UNIX_FD_PASSING
3865 _dbus_assert (!loader->unix_fds_outstanding);
3867 /* Allocate space where we can put the fds we read. We allocate
3868 space for max_message_unix_fds since this is an
3869 upper limit how many fds can be received within a single
3870 message. Since SCM_RIGHTS doesn't allow a reallocate+retry logic
3871 we are allocating the maximum possible array size right from the
3872 beginning. This sucks a bit, however unless SCM_RIGHTS is fixed
3873 there is no better way. */
3875 if (loader->n_unix_fds_allocated < loader->max_message_unix_fds)
3877 int *a = dbus_realloc(loader->unix_fds,
3878 loader->max_message_unix_fds * sizeof(loader->unix_fds[0]));
3883 loader->unix_fds = a;
3884 loader->n_unix_fds_allocated = loader->max_message_unix_fds;
3887 *fds = loader->unix_fds + loader->n_unix_fds;
3888 *max_n_fds = loader->n_unix_fds_allocated - loader->n_unix_fds;
3890 loader->unix_fds_outstanding = TRUE;
3893 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
3899 * Returns a buffer obtained from _dbus_message_loader_get_unix_fds().
3901 * This works similar to _dbus_message_loader_return_buffer()
3903 * @param loader the message loader.
3904 * @param fds the array fds were read into
3905 * @param max_n_fds how many fds were read
3909 _dbus_message_loader_return_unix_fds(DBusMessageLoader *loader,
3913 #ifdef HAVE_UNIX_FD_PASSING
3914 _dbus_assert(loader->unix_fds_outstanding);
3915 _dbus_assert(loader->unix_fds + loader->n_unix_fds == fds);
3916 _dbus_assert(loader->n_unix_fds + n_fds <= loader->n_unix_fds_allocated);
3918 loader->n_unix_fds += n_fds;
3919 loader->unix_fds_outstanding = FALSE;
3921 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
3926 * FIXME when we move the header out of the buffer, that memmoves all
3927 * buffered messages. Kind of crappy.
3929 * Also we copy the header and body, which is kind of crappy. To
3930 * avoid this, we have to allow header and body to be in a single
3931 * memory block, which is good for messages we read and bad for
3932 * messages we are creating. But we could move_len() the buffer into
3933 * this single memory block, and move_len() will just swap the buffers
3934 * if you're moving the entire buffer replacing the dest string.
3936 * We could also have the message loader tell the transport how many
3937 * bytes to read; so it would first ask for some arbitrary number like
3938 * 256, then if the message was incomplete it would use the
3939 * header/body len to ask for exactly the size of the message (or
3940 * blocks the size of a typical kernel buffer for the socket). That
3941 * way we don't get trailing bytes in the buffer that have to be
3942 * memmoved. Though I suppose we also don't have a chance of reading a
3943 * bunch of small messages at once, so the optimization may be stupid.
3945 * Another approach would be to keep a "start" index into
3946 * loader->data and only delete it occasionally, instead of after
3947 * each message is loaded.
3949 * load_message() returns FALSE if not enough memory OR the loader was corrupted
3952 load_message (DBusMessageLoader *loader,
3953 DBusMessage *message,
3955 int fields_array_len,
3960 DBusValidity validity;
3961 const DBusString *type_str;
3963 DBusValidationMode mode;
3964 dbus_uint32_t n_unix_fds = 0;
3966 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
3971 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
3974 /* 1. VALIDATE AND COPY OVER HEADER */
3975 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
3976 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
3978 if (!_dbus_header_load (&message->header,
3986 _dbus_string_get_length (&loader->data)))
3988 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
3990 /* assert here so we can catch any code that still uses DBUS_VALID to indicate
3991 oom errors. They should use DBUS_VALIDITY_UNKNOWN_OOM_ERROR instead */
3992 _dbus_assert (validity != DBUS_VALID);
3994 if (validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
3998 loader->corrupted = TRUE;
3999 loader->corruption_reason = validity;
4004 _dbus_assert (validity == DBUS_VALID);
4006 message->byte_order = byte_order;
4008 /* 2. VALIDATE BODY */
4009 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
4011 get_const_signature (&message->header, &type_str, &type_pos);
4013 /* Because the bytes_remaining arg is NULL, this validates that the
4014 * body is the right length
4016 validity = _dbus_validate_body_with_reason (type_str,
4023 if (validity != DBUS_VALID)
4025 _dbus_verbose ("Failed to validate message body code %d\n", validity);
4027 loader->corrupted = TRUE;
4028 loader->corruption_reason = validity;
4034 /* 3. COPY OVER UNIX FDS */
4035 _dbus_header_get_field_basic(&message->header,
4036 DBUS_HEADER_FIELD_UNIX_FDS,
4040 #ifdef HAVE_UNIX_FD_PASSING
4042 if (n_unix_fds > loader->n_unix_fds)
4044 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
4045 n_unix_fds, loader->n_unix_fds);
4047 loader->corrupted = TRUE;
4048 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4052 /* If this was a recycled message there might still be
4053 some memory allocated for the fds */
4054 dbus_free(message->unix_fds);
4058 message->unix_fds = _dbus_memdup(loader->unix_fds, n_unix_fds * sizeof(message->unix_fds[0]));
4059 if (message->unix_fds == NULL)
4061 _dbus_verbose ("Failed to allocate file descriptor array\n");
4066 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
4067 loader->n_unix_fds -= n_unix_fds;
4068 memmove(loader->unix_fds + n_unix_fds, loader->unix_fds, loader->n_unix_fds);
4071 message->unix_fds = NULL;
4077 _dbus_verbose ("Hmm, message claims to come with file descriptors "
4078 "but that's not supported on our platform, disconnecting.\n");
4080 loader->corrupted = TRUE;
4081 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4087 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
4089 if (!_dbus_list_append (&loader->messages, message))
4091 _dbus_verbose ("Failed to append new message to loader queue\n");
4096 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
4097 _dbus_assert (_dbus_string_get_length (&loader->data) >=
4098 (header_len + body_len));
4100 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
4102 _dbus_verbose ("Failed to move body into new message\n");
4107 _dbus_string_delete (&loader->data, 0, header_len + body_len);
4109 /* don't waste more than 2k of memory */
4110 _dbus_string_compact (&loader->data, 2048);
4112 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
4113 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
4115 _dbus_verbose ("Loaded message %p\n", message);
4117 _dbus_assert (!oom);
4118 _dbus_assert (!loader->corrupted);
4119 _dbus_assert (loader->messages != NULL);
4120 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4128 /* does nothing if the message isn't in the list */
4129 _dbus_list_remove_last (&loader->messages, message);
4132 _dbus_assert (!loader->corrupted);
4134 _dbus_assert (loader->corrupted);
4136 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
4142 * Converts buffered data into messages, if we have enough data. If
4143 * we don't have enough data, does nothing.
4145 * @todo we need to check that the proper named header fields exist
4146 * for each message type.
4148 * @todo If a message has unknown type, we should probably eat it
4149 * right here rather than passing it out to applications. However
4150 * it's not an error to see messages of unknown type.
4152 * @param loader the loader.
4153 * @returns #TRUE if we had enough memory to finish.
4156 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
4158 while (!loader->corrupted &&
4159 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
4161 DBusValidity validity;
4162 int byte_order, fields_array_len, header_len, body_len;
4164 if (_dbus_header_have_message_untrusted (loader->max_message_size,
4171 _dbus_string_get_length (&loader->data)))
4173 DBusMessage *message;
4175 _dbus_assert (validity == DBUS_VALID);
4177 message = dbus_message_new_empty_header ();
4178 if (message == NULL)
4181 if (!load_message (loader, message,
4182 byte_order, fields_array_len,
4183 header_len, body_len))
4185 dbus_message_unref (message);
4186 /* load_message() returns false if corrupted or OOM; if
4187 * corrupted then return TRUE for not OOM
4189 return loader->corrupted;
4192 _dbus_assert (loader->messages != NULL);
4193 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4197 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
4199 if (validity != DBUS_VALID)
4201 loader->corrupted = TRUE;
4202 loader->corruption_reason = validity;
4212 * Peeks at first loaded message, returns #NULL if no messages have
4215 * @param loader the loader.
4216 * @returns the next message, or #NULL if none.
4219 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
4221 if (loader->messages)
4222 return loader->messages->data;
4228 * Pops a loaded message (passing ownership of the message
4229 * to the caller). Returns #NULL if no messages have been
4232 * @param loader the loader.
4233 * @returns the next message, or #NULL if none.
4236 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
4238 return _dbus_list_pop_first (&loader->messages);
4242 * Pops a loaded message inside a list link (passing ownership of the
4243 * message and link to the caller). Returns #NULL if no messages have
4246 * @param loader the loader.
4247 * @returns the next message link, or #NULL if none.
4250 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
4252 return _dbus_list_pop_first_link (&loader->messages);
4256 * Returns a popped message link, used to undo a pop.
4258 * @param loader the loader
4259 * @param link the link with a message in it
4262 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
4265 _dbus_list_prepend_link (&loader->messages, link);
4269 * Checks whether the loader is confused due to bad data.
4270 * If messages are received that are invalid, the
4271 * loader gets confused and gives up permanently.
4272 * This state is called "corrupted."
4274 * @param loader the loader
4275 * @returns #TRUE if the loader is hosed.
4278 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
4280 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4281 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4282 return loader->corrupted;
4286 * Checks what kind of bad data confused the loader.
4288 * @param loader the loader
4289 * @returns why the loader is hosed, or DBUS_VALID if it isn't.
4292 _dbus_message_loader_get_corruption_reason (DBusMessageLoader *loader)
4294 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4295 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4297 return loader->corruption_reason;
4301 * Sets the maximum size message we allow.
4303 * @param loader the loader
4304 * @param size the max message size in bytes
4307 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
4310 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
4312 _dbus_verbose ("clamping requested max message size %ld to %d\n",
4313 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
4314 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4316 loader->max_message_size = size;
4320 * Gets the maximum allowed message size in bytes.
4322 * @param loader the loader
4323 * @returns max size in bytes
4326 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
4328 return loader->max_message_size;
4332 * Sets the maximum unix fds per message we allow.
4334 * @param loader the loader
4335 * @param size the max number of unix fds in a message
4338 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader,
4341 if (n > DBUS_MAXIMUM_MESSAGE_UNIX_FDS)
4343 _dbus_verbose ("clamping requested max message unix_fds %ld to %d\n",
4344 n, DBUS_MAXIMUM_MESSAGE_UNIX_FDS);
4345 n = DBUS_MAXIMUM_MESSAGE_UNIX_FDS;
4347 loader->max_message_unix_fds = n;
4351 * Gets the maximum allowed number of unix fds per message
4353 * @param loader the loader
4354 * @returns max unix fds
4357 _dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
4359 return loader->max_message_unix_fds;
4362 static DBusDataSlotAllocator slot_allocator;
4363 _DBUS_DEFINE_GLOBAL_LOCK (message_slots);
4366 * Allocates an integer ID to be used for storing application-specific
4367 * data on any DBusMessage. The allocated ID may then be used
4368 * with dbus_message_set_data() and dbus_message_get_data().
4369 * The passed-in slot must be initialized to -1, and is filled in
4370 * with the slot ID. If the passed-in slot is not -1, it's assumed
4371 * to be already allocated, and its refcount is incremented.
4373 * The allocated slot is global, i.e. all DBusMessage objects will
4374 * have a slot with the given integer ID reserved.
4376 * @param slot_p address of a global variable storing the slot
4377 * @returns #FALSE on failure (no memory)
4380 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
4382 return _dbus_data_slot_allocator_alloc (&slot_allocator,
4383 &_DBUS_LOCK_NAME (message_slots),
4388 * Deallocates a global ID for message data slots.
4389 * dbus_message_get_data() and dbus_message_set_data() may no
4390 * longer be used with this slot. Existing data stored on existing
4391 * DBusMessage objects will be freed when the message is
4392 * finalized, but may not be retrieved (and may only be replaced if
4393 * someone else reallocates the slot). When the refcount on the
4394 * passed-in slot reaches 0, it is set to -1.
4396 * @param slot_p address storing the slot to deallocate
4399 dbus_message_free_data_slot (dbus_int32_t *slot_p)
4401 _dbus_return_if_fail (*slot_p >= 0);
4403 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
4407 * Stores a pointer on a DBusMessage, along
4408 * with an optional function to be used for freeing
4409 * the data when the data is set again, or when
4410 * the message is finalized. The slot number
4411 * must have been allocated with dbus_message_allocate_data_slot().
4413 * @param message the message
4414 * @param slot the slot number
4415 * @param data the data to store
4416 * @param free_data_func finalizer function for the data
4417 * @returns #TRUE if there was enough memory to store the data
4420 dbus_message_set_data (DBusMessage *message,
4423 DBusFreeFunction free_data_func)
4425 DBusFreeFunction old_free_func;
4429 _dbus_return_val_if_fail (message != NULL, FALSE);
4430 _dbus_return_val_if_fail (slot >= 0, FALSE);
4432 retval = _dbus_data_slot_list_set (&slot_allocator,
4433 &message->slot_list,
4434 slot, data, free_data_func,
4435 &old_free_func, &old_data);
4439 /* Do the actual free outside the message lock */
4441 (* old_free_func) (old_data);
4448 * Retrieves data previously set with dbus_message_set_data().
4449 * The slot must still be allocated (must not have been freed).
4451 * @param message the message
4452 * @param slot the slot to get data from
4453 * @returns the data, or #NULL if not found
4456 dbus_message_get_data (DBusMessage *message,
4461 _dbus_return_val_if_fail (message != NULL, NULL);
4463 res = _dbus_data_slot_list_get (&slot_allocator,
4464 &message->slot_list,
4471 * Utility function to convert a machine-readable (not translated)
4472 * string into a D-Bus message type.
4475 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
4476 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
4477 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
4478 * "error" -> DBUS_MESSAGE_TYPE_ERROR
4479 * anything else -> DBUS_MESSAGE_TYPE_INVALID
4484 dbus_message_type_from_string (const char *type_str)
4486 if (strcmp (type_str, "method_call") == 0)
4487 return DBUS_MESSAGE_TYPE_METHOD_CALL;
4488 if (strcmp (type_str, "method_return") == 0)
4489 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
4490 else if (strcmp (type_str, "signal") == 0)
4491 return DBUS_MESSAGE_TYPE_SIGNAL;
4492 else if (strcmp (type_str, "error") == 0)
4493 return DBUS_MESSAGE_TYPE_ERROR;
4495 return DBUS_MESSAGE_TYPE_INVALID;
4499 * Utility function to convert a D-Bus message type into a
4500 * machine-readable string (not translated).
4503 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
4504 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
4505 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
4506 * DBUS_MESSAGE_TYPE_ERROR -> "error"
4507 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
4512 dbus_message_type_to_string (int type)
4516 case DBUS_MESSAGE_TYPE_METHOD_CALL:
4517 return "method_call";
4518 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
4519 return "method_return";
4520 case DBUS_MESSAGE_TYPE_SIGNAL:
4522 case DBUS_MESSAGE_TYPE_ERROR:
4530 * Turn a DBusMessage into the marshalled form as described in the D-Bus
4533 * Generally, this function is only useful for encapsulating D-Bus messages in
4534 * a different protocol.
4536 * @param msg the DBusMessage
4537 * @param marshalled_data_p the location to save the marshalled form to
4538 * @param len_p the location to save the length of the marshalled form to
4539 * @returns #FALSE if there was not enough memory
4542 dbus_message_marshal (DBusMessage *msg,
4543 char **marshalled_data_p,
4547 dbus_bool_t was_locked;
4549 _dbus_return_val_if_fail (msg != NULL, FALSE);
4550 _dbus_return_val_if_fail (marshalled_data_p != NULL, FALSE);
4551 _dbus_return_val_if_fail (len_p != NULL, FALSE);
4553 if (!_dbus_string_init (&tmp))
4556 /* Ensure the message is locked, to ensure the length header is filled in. */
4557 was_locked = msg->locked;
4560 dbus_message_lock (msg);
4562 if (!_dbus_string_copy (&(msg->header.data), 0, &tmp, 0))
4565 *len_p = _dbus_string_get_length (&tmp);
4567 if (!_dbus_string_copy (&(msg->body), 0, &tmp, *len_p))
4570 *len_p = _dbus_string_get_length (&tmp);
4572 if (!_dbus_string_steal_data (&tmp, marshalled_data_p))
4575 _dbus_string_free (&tmp);
4578 msg->locked = FALSE;
4583 _dbus_string_free (&tmp);
4586 msg->locked = FALSE;
4592 * Demarshal a D-Bus message from the format described in the D-Bus
4595 * Generally, this function is only useful for encapsulating D-Bus messages in
4596 * a different protocol.
4598 * @param str the marshalled DBusMessage
4599 * @param len the length of str
4600 * @param error the location to save errors to
4601 * @returns #NULL if there was an error
4604 dbus_message_demarshal (const char *str,
4608 DBusMessageLoader *loader;
4612 _dbus_return_val_if_fail (str != NULL, NULL);
4614 loader = _dbus_message_loader_new ();
4619 _dbus_message_loader_get_buffer (loader, &buffer);
4620 _dbus_string_append_len (buffer, str, len);
4621 _dbus_message_loader_return_buffer (loader, buffer, len);
4623 if (!_dbus_message_loader_queue_messages (loader))
4626 if (_dbus_message_loader_get_is_corrupted (loader))
4629 msg = _dbus_message_loader_pop_message (loader);
4634 _dbus_message_loader_unref (loader);
4638 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS, "Message is corrupted (%s)",
4639 _dbus_validity_to_error_message (loader->corruption_reason));
4640 _dbus_message_loader_unref (loader);
4644 _DBUS_SET_OOM (error);
4645 _dbus_message_loader_unref (loader);
4650 * Returns the number of bytes required to be in the buffer to demarshal a
4653 * Generally, this function is only useful for encapsulating D-Bus messages in
4654 * a different protocol.
4656 * @param str data to be marshalled
4657 * @param len the length of str
4658 * @param error the location to save errors to
4659 * @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
4663 dbus_message_demarshal_bytes_needed(const char *buf,
4667 int byte_order, fields_array_len, header_len, body_len;
4668 DBusValidity validity = DBUS_VALID;
4671 if (!buf || len < DBUS_MINIMUM_HEADER_SIZE)
4674 if (len > DBUS_MAXIMUM_MESSAGE_LENGTH)
4675 len = DBUS_MAXIMUM_MESSAGE_LENGTH;
4676 _dbus_string_init_const_len (&str, buf, len);
4678 validity = DBUS_VALID;
4680 = _dbus_header_have_message_untrusted(DBUS_MAXIMUM_MESSAGE_LENGTH,
4681 &validity, &byte_order,
4687 _dbus_string_free (&str);
4689 if (validity == DBUS_VALID)
4691 _dbus_assert (have_message || (header_len + body_len) > len);
4692 return header_len + body_len;
4696 return -1; /* broken! */
4702 /* tests in dbus-message-util.c */