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
6 * Copyright (C) 2015 Samsung Electronics
8 * Licensed under the Academic Free License version 2.1
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License
21 * along with this program; if not, write to the Free Software
22 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
27 #include "dbus-internals.h"
28 #include "dbus-marshal-recursive.h"
29 #include "dbus-marshal-validate.h"
30 #include "dbus-marshal-byteswap.h"
31 #include "dbus-marshal-header.h"
32 #include "dbus-signature.h"
33 #include "dbus-message-private.h"
34 #include "dbus-object-tree.h"
35 #include "dbus-memory.h"
36 #include "dbus-list.h"
37 #include "dbus-threads-internal.h"
38 #ifdef HAVE_UNIX_FD_PASSING
39 #include "dbus-sysdeps.h"
40 #include "dbus-sysdeps-unix.h"
42 #include "dbus-marshal-gvariant.h"
43 #include "dbus-protocol-gvariant.h"
47 #define _DBUS_TYPE_IS_STRINGLIKE(type) \
48 (type == DBUS_TYPE_STRING || type == DBUS_TYPE_SIGNATURE || \
49 type == DBUS_TYPE_OBJECT_PATH)
51 static unsigned char _dbus_default_protocol_version = DBUS_MAJOR_PROTOCOL_VERSION; /* DBUS_PROTOCOL_VERSION_GVARIANT; */
52 static dbus_bool_t _dbus_first_bus_open = FALSE;
54 static void protocol_strategy_last_type (int type);
55 static void protocol_strategy_static (int type);
57 typedef void (*DBusProtocolStrategyFunction)(int type);
58 static DBusProtocolStrategyFunction _dbus_protocol_strategy_bus_function = protocol_strategy_last_type;
59 static DBusProtocolStrategyFunction _dbus_protocol_strategy_message_function = protocol_strategy_static;
61 static void dbus_message_finalize (DBusMessage *message);
64 * @defgroup DBusMessageInternals DBusMessage implementation details
65 * @ingroup DBusInternals
66 * @brief DBusMessage private implementation details.
68 * The guts of DBusMessage and its methods.
73 #ifdef DBUS_ENABLE_EMBEDDED_TESTS
75 _dbus_enable_message_cache (void)
77 static int enabled = -1;
81 const char *s = _dbus_getenv ("DBUS_MESSAGE_CACHE");
92 _dbus_warn ("DBUS_MESSAGE_CACHE should be 0 or 1 if set, not '%s'",
100 /* constant expression, should be optimized away */
101 # define _dbus_enable_message_cache() (TRUE)
104 #ifndef _dbus_message_trace_ref
106 _dbus_message_trace_ref (DBusMessage *message,
111 static int enabled = -1;
113 _dbus_trace_ref ("DBusMessage", message, old_refcount, new_refcount, why,
114 "DBUS_MESSAGE_TRACE", &enabled);
118 /* Not thread locked, but strictly const/read-only so should be OK
120 /** An static string representing an empty signature */
121 _DBUS_STRING_DEFINE_STATIC(_dbus_empty_signature_str, "");
123 /* these have wacky values to help trap uninitialized iterators;
124 * but has to fit in 3 bits
127 DBUS_MESSAGE_ITER_TYPE_READER = 3,
128 DBUS_MESSAGE_ITER_TYPE_WRITER = 7
131 /** typedef for internals of message iterator */
132 typedef struct DBusMessageRealIter DBusMessageRealIter;
134 #define BUILD_BUG_ON(condition) ((void)sizeof(char[1 - 2*!!(condition)]))
137 * @brief Internals of DBusMessageIter
139 * Object representing a position in a message. All fields are internal.
141 struct DBusMessageRealIter
143 DBusMessage *message; /**< Message used */
144 dbus_uint32_t changed_stamp : CHANGED_STAMP_BITS; /**< stamp to detect invalid iters */
145 dbus_uint32_t iter_type : 3; /**< whether this is a reader or writer iter */
146 dbus_uint32_t sig_refcount : 8; /**< depth of open_signature() */
149 DBusTypeWriter writer; /**< writer */
150 DBusTypeReader reader; /**< reader */
151 } u; /**< the type writer or reader that does all the work */
155 _dbus_header_is_gvariant (const DBusHeader *header)
157 return (header->protocol_version == DBUS_PROTOCOL_VERSION_GVARIANT);
161 _dbus_message_is_gvariant (const DBusMessage *message)
163 return _dbus_header_is_gvariant (&message->header);
167 _dbus_message_toggle_gvariant (DBusMessage *message, dbus_bool_t gvariant)
169 message->header.protocol_version = gvariant ? DBUS_PROTOCOL_VERSION_GVARIANT : DBUS_MAJOR_PROTOCOL_VERSION;
173 get_const_signature (DBusMessage *message,
174 const DBusString **type_str_p,
177 dbus_bool_t got_signature = FALSE;
178 if (_dbus_message_is_gvariant (message) && message->locked)
180 /* only locked GVariant messages have signatures in the body */
182 * in case of received GVariant message, there may be no signature field in a header,
183 * but in the body. However, it is not nul-terminated.
184 * So, we need to allocate space and put it into message.
185 * It could also happen before, so check message->signature for already existing.
186 * FIXME: That may kinda break oom-safety.
187 * For now - if oom, then return empty signature.
189 if (message->signature == NULL)
192 got_signature = _dbus_message_gvariant_get_signature (message,
196 if (got_signature && type_str_len > 1)
198 message->signature = dbus_new (DBusString, 1);
199 got_signature = got_signature &&
200 _dbus_string_init_preallocated (message->signature, type_str_len - 1);
202 /* we need to copy the signature, but to ensure backward compatibility
203 * it must be stripped off outer parentheses - they are always there */
204 got_signature = got_signature &&
205 _dbus_string_copy_len (*type_str_p, *type_pos_p + 1, type_str_len - 2,
206 message->signature, 0);
207 got_signature = got_signature &&
208 _dbus_string_append_byte (message->signature, 0);
212 got_signature = TRUE;
216 *type_str_p = message->signature;
220 else if (_dbus_header_get_field_raw (&message->header,
221 DBUS_HEADER_FIELD_SIGNATURE,
225 if (!_dbus_message_is_gvariant (message))
226 *type_pos_p += 1; /* skip the signature length which is 1 byte */
227 got_signature = TRUE;
231 *type_str_p = &_dbus_empty_signature_str;
237 * Swaps the message to compiler byte order if required
239 * @param message the message
242 _dbus_message_byteswap (DBusMessage *message)
244 const DBusString *type_str;
248 byte_order = _dbus_header_get_byte_order (&message->header);
250 if (byte_order == DBUS_COMPILER_BYTE_ORDER)
253 _dbus_verbose ("Swapping message into compiler byte order\n");
255 get_const_signature (message, &type_str, &type_pos);
257 _dbus_marshal_byteswap (type_str, type_pos,
259 DBUS_COMPILER_BYTE_ORDER,
262 _dbus_header_byteswap (&message->header, DBUS_COMPILER_BYTE_ORDER);
263 _dbus_assert (_dbus_header_get_byte_order (&message->header) ==
264 DBUS_COMPILER_BYTE_ORDER);
267 /** byte-swap the message if it doesn't match our byte order.
268 * Called only when we need the message in our own byte order,
269 * normally when reading arrays of integers or doubles.
270 * Otherwise should not be called since it would do needless
273 #define ensure_byte_order(message) _dbus_message_byteswap (message)
276 * Gets the data to be sent over the network for this message.
277 * The header and then the body should be written out.
278 * This function is guaranteed to always return the same
279 * data once a message is locked (with dbus_message_lock()).
281 * @param message the message.
282 * @param header return location for message header data.
283 * @param body return location for message body data.
286 _dbus_message_get_network_data (DBusMessage *message,
287 const DBusString **header,
288 const DBusString **body)
290 _dbus_assert (message->locked);
292 *header = &message->header.data;
293 *body = &message->body;
296 void _dbus_message_set_timeout_ms(DBusMessage *message, int timeout_ms) {
297 message->timeout_ms = timeout_ms;
299 int _dbus_message_get_timeout_ms(DBusMessage const *message) {
300 return message->timeout_ms;
304 * Gets the unix fds to be sent over the network for this message.
305 * This function is guaranteed to always return the same data once a
306 * message is locked (with dbus_message_lock()).
308 * @param message the message.
309 * @param fds return location of unix fd array
310 * @param n_fds return number of entries in array
312 void _dbus_message_get_unix_fds(DBusMessage *message,
316 _dbus_assert (message->locked);
318 #ifdef HAVE_UNIX_FD_PASSING
319 *fds = message->unix_fds;
320 *n_fds = message->n_unix_fds;
328 * Sets the serial number of a message.
329 * This can only be done once on a message.
331 * DBusConnection will automatically set the serial to an appropriate value
332 * when the message is sent; this function is only needed when encapsulating
333 * messages in another protocol, or otherwise bypassing DBusConnection.
335 * @param message the message
336 * @param serial the serial
339 dbus_message_set_serial (DBusMessage *message,
340 dbus_uint32_t serial)
342 _dbus_return_if_fail (message != NULL);
343 _dbus_return_if_fail (!message->locked);
345 _dbus_header_set_serial (&message->header, serial);
349 * Adds a counter to be incremented immediately with the size/unix fds
350 * of this message, and decremented by the size/unix fds of this
351 * message when this message if finalized. The link contains a
352 * counter with its refcount already incremented, but the counter
353 * itself not incremented. Ownership of link and counter refcount is
354 * passed to the message.
356 * This function may be called with locks held. As a result, the counter's
357 * notify function is not called; the caller is expected to either call
358 * _dbus_counter_notify() on the counter when they are no longer holding
359 * locks, or take the same action that would be taken by the notify function.
361 * @param message the message
362 * @param link link with counter as data
365 _dbus_message_add_counter_link (DBusMessage *message,
368 /* right now we don't recompute the delta when message
369 * size changes, and that's OK for current purposes
370 * I think, but could be important to change later.
371 * Do recompute it whenever there are no outstanding counters,
372 * since it's basically free.
374 if (message->counters == NULL)
376 message->size_counter_delta =
377 _dbus_string_get_length (&message->header.data) +
378 _dbus_string_get_length (&message->body);
380 #ifdef HAVE_UNIX_FD_PASSING
381 message->unix_fd_counter_delta = message->n_unix_fds;
385 _dbus_verbose ("message has size %ld\n",
386 message->size_counter_delta);
390 _dbus_list_append_link (&message->counters, link);
392 _dbus_counter_adjust_size (link->data, message->size_counter_delta);
394 #ifdef HAVE_UNIX_FD_PASSING
395 _dbus_counter_adjust_unix_fd (link->data, message->unix_fd_counter_delta);
400 * Adds a counter to be incremented immediately with the size/unix fds
401 * of this message, and decremented by the size/unix fds of this
402 * message when this message if finalized.
404 * This function may be called with locks held. As a result, the counter's
405 * notify function is not called; the caller is expected to either call
406 * _dbus_counter_notify() on the counter when they are no longer holding
407 * locks, or take the same action that would be taken by the notify function.
409 * @param message the message
410 * @param counter the counter
411 * @returns #FALSE if no memory
414 _dbus_message_add_counter (DBusMessage *message,
415 DBusCounter *counter)
419 link = _dbus_list_alloc_link (counter);
423 _dbus_counter_ref (counter);
424 _dbus_message_add_counter_link (message, link);
430 * Removes a counter tracking the size/unix fds of this message, and
431 * decrements the counter by the size/unix fds of this message.
433 * @param message the message
434 * @param counter the counter
437 _dbus_message_remove_counter (DBusMessage *message,
438 DBusCounter *counter)
442 link = _dbus_list_find_last (&message->counters,
444 _dbus_assert (link != NULL);
446 _dbus_list_remove_link (&message->counters, link);
448 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
450 #ifdef HAVE_UNIX_FD_PASSING
451 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
454 _dbus_counter_notify (counter);
455 _dbus_counter_unref (counter);
459 * Locks a message. Allows checking that applications don't keep a
460 * reference to a message in the outgoing queue and change it
461 * underneath us. Messages are locked when they enter the outgoing
462 * queue (dbus_connection_send_message()), and the library complains
463 * if the message is modified while locked. This function may also
464 * called externally, for applications wrapping D-Bus in another protocol.
466 * @param message the message to lock.
469 dbus_message_lock (DBusMessage *message)
471 if (!message->locked)
473 if (!_dbus_message_is_gvariant (message))
474 _dbus_header_update_lengths (&message->header,
475 _dbus_string_get_length (&message->body));
477 _dbus_message_finalize_gvariant (message, TRUE);
479 /* must have a signature if you have a body */
480 _dbus_assert (_dbus_string_get_length (&message->body) == 0 ||
481 dbus_message_get_signature (message) != NULL);
483 message->locked = TRUE;
488 set_or_delete_string_field (DBusMessage *message,
494 return _dbus_header_delete_field (&message->header, field);
496 return _dbus_header_set_field_basic (&message->header,
503 /* Probably we don't need to use this */
505 * Sets the signature of the message, i.e. the arguments in the
506 * message payload. The signature includes only "in" arguments for
507 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
508 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
509 * what you might expect (it does not include the signature of the
510 * entire C++-style method).
512 * The signature is a string made up of type codes such as
513 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
514 * the value of #DBUS_TYPE_INVALID). The macros such as
515 * #DBUS_TYPE_INT32 evaluate to integers; to assemble a signature you
516 * may find it useful to use the string forms, such as
517 * #DBUS_TYPE_INT32_AS_STRING.
519 * An "unset" or #NULL signature is considered the same as an empty
520 * signature. In fact dbus_message_get_signature() will never return
523 * @param message the message
524 * @param signature the type signature or #NULL to unset
525 * @returns #FALSE if no memory
528 _dbus_message_set_signature (DBusMessage *message,
529 const char *signature)
531 _dbus_return_val_if_fail (message != NULL, FALSE);
532 _dbus_return_val_if_fail (!message->locked, FALSE);
533 _dbus_return_val_if_fail (signature == NULL ||
534 _dbus_check_is_valid_signature (signature));
535 /* can't delete the signature if you have a message body */
536 _dbus_return_val_if_fail (_dbus_string_get_length (&message->body) == 0 ||
539 return set_or_delete_string_field (message,
540 DBUS_HEADER_FIELD_SIGNATURE,
548 * We cache some DBusMessage to reduce the overhead of allocating
549 * them. In my profiling this consistently made about an 8%
550 * difference. It avoids the malloc for the message, the malloc for
551 * the slot list, the malloc for the header string and body string,
552 * and the associated free() calls. It does introduce another global
553 * lock which could be a performance issue in certain cases.
555 * For the echo client/server the round trip time goes from around
556 * .000077 to .000069 with the message cache on my laptop. The sysprof
557 * change is as follows (numbers are cumulative percentage):
559 * with message cache implemented as array as it is now (0.000069 per):
560 * new_empty_header 1.46
561 * mutex_lock 0.56 # i.e. _DBUS_LOCK(message_cache)
567 * mutex_lock 0.33 # i.e. _DBUS_LOCK(message_cache)
570 * with message cache implemented as list (0.000070 per roundtrip):
571 * new_empty_header 2.72
572 * list_pop_first 1.88
576 * without cache (0.000077 per roundtrip):
577 * new_empty_header 6.7
578 * string_init_preallocated 3.43
587 * If you implement the message_cache with a list, the primary reason
588 * it's slower is that you add another thread lock (on the DBusList
592 /** Avoid caching huge messages */
593 #define MAX_MESSAGE_SIZE_TO_CACHE 10 * _DBUS_ONE_KILOBYTE
595 /** Avoid caching too many messages */
596 #define MAX_MESSAGE_CACHE_SIZE 5
598 /* Protected by _DBUS_LOCK (message_cache) */
599 static DBusMessage *message_cache[MAX_MESSAGE_CACHE_SIZE];
600 static int message_cache_count = 0;
601 static dbus_bool_t message_cache_shutdown_registered = FALSE;
604 dbus_message_cache_shutdown (void *data)
608 if (!_DBUS_LOCK (message_cache))
609 _dbus_assert_not_reached ("we would have initialized global locks "
610 "before registering a shutdown function");
613 while (i < MAX_MESSAGE_CACHE_SIZE)
615 if (message_cache[i])
616 dbus_message_finalize (message_cache[i]);
621 message_cache_count = 0;
622 message_cache_shutdown_registered = FALSE;
624 _DBUS_UNLOCK (message_cache);
628 * Tries to get a message from the message cache. The retrieved
629 * message will have junk in it, so it still needs to be cleared out
630 * in dbus_message_new_empty_header()
632 * @returns the message, or #NULL if none cached
635 dbus_message_get_cached (void)
637 DBusMessage *message;
642 if (!_DBUS_LOCK (message_cache))
644 /* we'd have initialized global locks before caching anything,
645 * so there can't be anything in the cache */
649 _dbus_assert (message_cache_count >= 0);
651 if (message_cache_count == 0)
653 _DBUS_UNLOCK (message_cache);
657 /* This is not necessarily true unless count > 0, and
658 * message_cache is uninitialized until the shutdown is
661 _dbus_assert (message_cache_shutdown_registered);
664 while (i < MAX_MESSAGE_CACHE_SIZE)
666 if (message_cache[i])
668 message = message_cache[i];
669 message_cache[i] = NULL;
670 message_cache_count -= 1;
675 _dbus_assert (message_cache_count >= 0);
676 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
677 _dbus_assert (message != NULL);
679 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
681 _dbus_assert (message->counters == NULL);
683 _DBUS_UNLOCK (message_cache);
688 #ifdef HAVE_UNIX_FD_PASSING
690 close_unix_fds(int *fds, unsigned *n_fds)
700 for (i = 0; i < *n_fds; i++)
702 if (!_dbus_close(fds[i], &e))
704 _dbus_warn("Failed to close file descriptor: %s\n", e.message);
711 /* We don't free the array here, in case we can recycle it later */
716 free_counter (void *element,
719 DBusCounter *counter = element;
720 DBusMessage *message = data;
722 _dbus_counter_adjust_size (counter, - message->size_counter_delta);
723 #ifdef HAVE_UNIX_FD_PASSING
724 _dbus_counter_adjust_unix_fd (counter, - message->unix_fd_counter_delta);
727 _dbus_counter_notify (counter);
728 _dbus_counter_unref (counter);
732 * Tries to cache a message, otherwise finalize it.
734 * @param message the message
737 dbus_message_cache_or_finalize (DBusMessage *message)
739 dbus_bool_t was_cached;
742 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
744 /* This calls application code and has to be done first thing
745 * without holding the lock
747 _dbus_data_slot_list_clear (&message->slot_list);
749 _dbus_list_foreach (&message->counters,
750 free_counter, message);
751 _dbus_list_clear (&message->counters);
753 #ifdef HAVE_UNIX_FD_PASSING
754 close_unix_fds(message->unix_fds, &message->n_unix_fds);
757 if (NULL != message->signature)
759 _dbus_string_free (message->signature);
760 dbus_free (message->signature);
761 message->signature = NULL;
764 if (NULL != message->unique_sender)
766 _dbus_string_free (message->unique_sender);
767 dbus_free (message->unique_sender);
768 message->unique_sender = NULL;
773 if (!_DBUS_LOCK (message_cache))
775 /* The only way to get a non-null message goes through
776 * dbus_message_get_cached() which takes the lock. */
777 _dbus_assert_not_reached ("we would have initialized global locks "
778 "the first time we constructed a message");
781 if (!message_cache_shutdown_registered)
783 _dbus_assert (message_cache_count == 0);
785 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
789 while (i < MAX_MESSAGE_CACHE_SIZE)
791 message_cache[i] = NULL;
795 message_cache_shutdown_registered = TRUE;
798 _dbus_assert (message_cache_count >= 0);
800 if (!_dbus_enable_message_cache ())
803 if ((_dbus_string_get_length (&message->header.data) +
804 _dbus_string_get_length (&message->body)) >
805 MAX_MESSAGE_SIZE_TO_CACHE)
808 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
811 /* Find empty slot */
813 while (message_cache[i] != NULL)
816 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
818 _dbus_assert (message_cache[i] == NULL);
819 message_cache[i] = message;
820 message_cache_count += 1;
822 #ifndef DBUS_DISABLE_CHECKS
823 message->in_cache = TRUE;
827 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
829 _DBUS_UNLOCK (message_cache);
832 dbus_message_finalize (message);
835 #if defined(DBUS_ENABLE_CHECKS) || defined(DBUS_ENABLE_ASSERT)
837 _dbus_message_iter_check (DBusMessageRealIter *iter)
843 _dbus_warn_check_failed ("dbus message iterator is NULL\n");
847 byte_order = _dbus_header_get_byte_order (&iter->message->header);
849 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
851 if (iter->u.reader.byte_order != byte_order)
853 _dbus_warn_check_failed ("dbus message changed byte order since iterator was created\n");
856 /* because we swap the message into compiler order when you init an iter */
857 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
859 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
861 if (iter->u.writer.byte_order != byte_order)
863 _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created\n");
866 /* because we swap the message into compiler order when you init an iter */
867 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
871 _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted\n");
875 if (iter->changed_stamp != iter->message->changed_stamp)
877 _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
883 #endif /* DBUS_ENABLE_CHECKS || DBUS_ENABLE_ASSERT */
886 * Implementation of the varargs arg-getting functions.
887 * dbus_message_get_args() is the place to go for complete
890 * @see dbus_message_get_args
891 * @param iter the message iter
892 * @param error error to be filled in
893 * @param first_arg_type type of the first argument
894 * @param var_args return location for first argument, followed by list of type/location pairs
895 * @returns #FALSE if error was set
898 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
903 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
904 int spec_type, msg_type, i, j;
908 _dbus_assert (_dbus_message_iter_check (real));
912 spec_type = first_arg_type;
915 /* copy var_args first, then we can do another iteration over it to
916 * free memory and close unix fds if parse failed at some point.
918 DBUS_VA_COPY (copy_args, var_args);
920 while (spec_type != DBUS_TYPE_INVALID)
922 msg_type = dbus_message_iter_get_arg_type (iter);
924 if (msg_type != spec_type)
926 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
927 "Argument %d is specified to be of type \"%s\", but "
928 "is actually of type \"%s\"\n", i,
929 _dbus_type_to_string (spec_type),
930 _dbus_type_to_string (msg_type));
935 if (spec_type == DBUS_TYPE_UNIX_FD)
937 #ifdef HAVE_UNIX_FD_PASSING
941 pfd = va_arg (var_args, int*);
944 _dbus_type_reader_read_basic(&real->u.reader, &idx);
946 if (idx.u32 >= real->message->n_unix_fds)
948 dbus_set_error (error, DBUS_ERROR_INCONSISTENT_MESSAGE,
949 "Message refers to file descriptor at index %i,"
950 "but has only %i descriptors attached.\n",
952 real->message->n_unix_fds);
956 if ((nfd = _dbus_dup(real->message->unix_fds[idx.u32], error)) < 0)
961 dbus_set_error (error, DBUS_ERROR_NOT_SUPPORTED,
962 "Platform does not support file desciptor passing.\n");
966 else if (dbus_type_is_basic (spec_type))
970 ptr = va_arg (var_args, DBusBasicValue*);
972 _dbus_assert (ptr != NULL);
974 _dbus_type_reader_read_basic (&real->u.reader,
977 else if (spec_type == DBUS_TYPE_ARRAY)
980 int spec_element_type;
981 const DBusBasicValue **ptr;
983 DBusTypeReader array;
985 spec_element_type = va_arg (var_args, int);
986 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
988 if (spec_element_type != element_type)
990 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
991 "Argument %d is specified to be an array of \"%s\", but "
992 "is actually an array of \"%s\"\n",
994 _dbus_type_to_string (spec_element_type),
995 _dbus_type_to_string (element_type));
1000 if (dbus_type_is_fixed (spec_element_type) &&
1001 element_type != DBUS_TYPE_UNIX_FD)
1003 ptr = va_arg (var_args, const DBusBasicValue**);
1004 n_elements_p = va_arg (var_args, int*);
1006 _dbus_assert (ptr != NULL);
1007 _dbus_assert (n_elements_p != NULL);
1009 _dbus_type_reader_recurse (&real->u.reader, &array);
1011 _dbus_type_reader_read_fixed_multi (&array,
1012 (void *) ptr, n_elements_p);
1014 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
1016 char ***str_array_p;
1020 str_array_p = va_arg (var_args, char***);
1021 n_elements_p = va_arg (var_args, int*);
1023 _dbus_assert (str_array_p != NULL);
1024 _dbus_assert (n_elements_p != NULL);
1026 /* Count elements in the array */
1027 _dbus_type_reader_recurse (&real->u.reader, &array);
1030 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
1033 _dbus_type_reader_next (&array);
1036 str_array = dbus_new0 (char*, n_elements + 1);
1037 if (str_array == NULL)
1039 _DBUS_SET_OOM (error);
1043 /* Now go through and dup each string */
1044 _dbus_type_reader_recurse (&real->u.reader, &array);
1047 while (j < n_elements)
1050 _dbus_type_reader_read_basic (&array,
1053 str_array[j] = _dbus_strdup (s);
1054 if (str_array[j] == NULL)
1056 dbus_free_string_array (str_array);
1057 _DBUS_SET_OOM (error);
1063 if (!_dbus_type_reader_next (&array))
1064 _dbus_assert (j == n_elements);
1067 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
1068 _dbus_assert (j == n_elements);
1069 _dbus_assert (str_array[j] == NULL);
1071 *str_array_p = str_array;
1072 *n_elements_p = n_elements;
1074 #ifndef DBUS_DISABLE_CHECKS
1077 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
1078 _DBUS_FUNCTION_NAME);
1083 #ifndef DBUS_DISABLE_CHECKS
1086 _dbus_warn ("you can only read arrays and basic types with %s for now\n",
1087 _DBUS_FUNCTION_NAME);
1092 /* how many arguments already handled */
1095 spec_type = va_arg (var_args, int);
1096 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
1098 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
1099 "Message has only %d arguments, but more were expected", i);
1107 /* there may memory or unix fd leak in the above iteration if parse failed.
1108 * so we have another iteration over copy_args to free memory and close
1113 spec_type = first_arg_type;
1118 if (spec_type == DBUS_TYPE_UNIX_FD)
1120 #ifdef HAVE_UNIX_FD_PASSING
1123 pfd = va_arg (copy_args, int *);
1127 _dbus_close (*pfd, NULL);
1132 else if (dbus_type_is_basic (spec_type))
1134 /* move the index forward */
1135 va_arg (copy_args, DBusBasicValue *);
1137 else if (spec_type == DBUS_TYPE_ARRAY)
1139 int spec_element_type;
1141 spec_element_type = va_arg (copy_args, int);
1142 if (dbus_type_is_fixed (spec_element_type))
1144 /* move the index forward */
1145 va_arg (copy_args, const DBusBasicValue **);
1146 va_arg (copy_args, int *);
1148 else if (_DBUS_TYPE_IS_STRINGLIKE (spec_element_type))
1150 char ***str_array_p;
1152 str_array_p = va_arg (copy_args, char ***);
1153 /* move the index forward */
1154 va_arg (copy_args, int *);
1155 _dbus_assert (str_array_p != NULL);
1156 dbus_free_string_array (*str_array_p);
1157 *str_array_p = NULL;
1161 spec_type = va_arg (copy_args, int);
1173 * @defgroup DBusMessage DBusMessage
1175 * @brief Message to be sent or received over a #DBusConnection.
1177 * A DBusMessage is the most basic unit of communication over a
1178 * DBusConnection. A DBusConnection represents a stream of messages
1179 * received from a remote application, and a stream of messages
1180 * sent to a remote application.
1182 * A message has a message type, returned from
1183 * dbus_message_get_type(). This indicates whether the message is a
1184 * method call, a reply to a method call, a signal, or an error reply.
1186 * A message has header fields such as the sender, destination, method
1187 * or signal name, and so forth. DBusMessage has accessor functions for
1188 * these, such as dbus_message_get_member().
1190 * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
1191 * and dbus_message_is_error() check several header fields at once and are
1192 * slightly more efficient than checking the header fields with individual
1193 * accessor functions.
1195 * Finally, a message has arguments. The number and types of arguments
1196 * are in the message's signature header field (accessed with
1197 * dbus_message_get_signature()). Simple argument values are usually
1198 * retrieved with dbus_message_get_args() but more complex values such
1199 * as structs may require the use of #DBusMessageIter.
1201 * The D-Bus specification goes into some more detail about header fields and
1208 * @typedef DBusMessage
1210 * Opaque data type representing a message received from or to be
1211 * sent to another application.
1215 * Returns the serial of a message or 0 if none has been specified.
1216 * The message's serial number is provided by the application sending
1217 * the message and is used to identify replies to this message.
1219 * All messages received on a connection will have a serial provided
1220 * by the remote application.
1222 * For messages you're sending, dbus_connection_send() will assign a
1223 * serial and return it to you.
1225 * @param message the message
1226 * @returns the serial
1229 dbus_message_get_serial (DBusMessage *message)
1231 _dbus_return_val_if_fail (message != NULL, 0);
1233 return _dbus_header_get_serial (&message->header);
1237 * Sets the reply serial of a message (the serial of the message this
1240 * @param message the message
1241 * @param reply_serial the serial we're replying to
1242 * @returns #FALSE if not enough memory
1245 dbus_message_set_reply_serial (DBusMessage *message,
1246 dbus_uint32_t reply_serial)
1248 DBusBasicValue value;
1251 _dbus_return_val_if_fail (message != NULL, FALSE);
1252 _dbus_return_val_if_fail (!message->locked, FALSE);
1253 _dbus_return_val_if_fail (reply_serial != 0, FALSE); /* 0 is invalid */
1255 if (_dbus_message_is_gvariant (message))
1257 type = DBUS_TYPE_UINT64;
1258 value.u64 = reply_serial;
1262 type = DBUS_TYPE_UINT64;
1263 value.u32 = reply_serial;
1266 return _dbus_header_set_field_basic (&message->header,
1267 DBUS_HEADER_FIELD_REPLY_SERIAL,
1273 * Returns the serial that the message is a reply to or 0 if none.
1275 * @param message the message
1276 * @returns the reply serial
1279 dbus_message_get_reply_serial (DBusMessage *message)
1281 dbus_uint32_t v_UINT32;
1282 dbus_uint64_t v_UINT64;
1283 int type = DBUS_TYPE_UINT32;
1284 void *value = &v_UINT32;
1286 _dbus_return_val_if_fail (message != NULL, 0);
1288 if (_dbus_message_is_gvariant (message))
1290 type = DBUS_TYPE_UINT64;
1294 if (_dbus_header_get_field_basic (&message->header,
1295 DBUS_HEADER_FIELD_REPLY_SERIAL,
1299 if (_dbus_message_is_gvariant (message))
1309 dbus_message_finalize (DBusMessage *message)
1311 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1313 /* This calls application callbacks! */
1314 _dbus_data_slot_list_free (&message->slot_list);
1316 _dbus_list_foreach (&message->counters,
1317 free_counter, message);
1318 _dbus_list_clear (&message->counters);
1320 _dbus_header_free (&message->header);
1321 _dbus_string_free (&message->body);
1323 #ifdef HAVE_UNIX_FD_PASSING
1324 close_unix_fds(message->unix_fds, &message->n_unix_fds);
1325 dbus_free(message->unix_fds);
1328 _dbus_assert (_dbus_atomic_get (&message->refcount) == 0);
1330 dbus_free (message);
1334 dbus_message_new_empty_header (dbus_bool_t gvariant)
1336 DBusMessage *message;
1337 dbus_bool_t from_cache;
1339 message = dbus_message_get_cached ();
1341 if (message != NULL)
1348 message = dbus_new0 (DBusMessage, 1);
1349 if (message == NULL)
1351 #ifndef DBUS_DISABLE_CHECKS
1352 message->generation = _dbus_current_generation;
1355 #ifdef HAVE_UNIX_FD_PASSING
1356 message->unix_fds = NULL;
1357 message->n_unix_fds_allocated = 0;
1361 _dbus_atomic_inc (&message->refcount);
1363 _dbus_message_trace_ref (message, 0, 1, "new_empty_header");
1365 message->locked = FALSE;
1366 #ifndef DBUS_DISABLE_CHECKS
1367 message->in_cache = FALSE;
1369 message->counters = NULL;
1370 message->size_counter_delta = 0;
1371 message->timeout_ms = -1;
1372 message->changed_stamp = 0;
1374 #ifdef HAVE_UNIX_FD_PASSING
1375 message->n_unix_fds = 0;
1376 message->n_unix_fds_allocated = 0;
1377 message->unix_fd_counter_delta = 0;
1380 _dbus_message_toggle_gvariant (message, gvariant); /* this works only if kdbus is enabled */
1383 _dbus_data_slot_list_init (&message->slot_list);
1387 _dbus_header_reinit (&message->header);
1388 _dbus_string_set_length (&message->body, 0);
1392 if (!_dbus_header_init (&message->header))
1394 dbus_free (message);
1398 if (!_dbus_string_init_preallocated (&message->body, 32))
1400 _dbus_header_free (&message->header);
1401 dbus_free (message);
1406 message->signature = NULL;
1407 message->unique_sender = NULL;
1408 message->gvariant_body_last_offset = GVARIANT_LAST_OFFSET_NOT_SET;
1409 message->gvariant_body_last_pos = 0;
1415 _dbus_message_create_protocol_version (int message_type,
1416 const char *destination,
1418 const char *interface,
1420 const char *error_name,
1421 dbus_bool_t gvariant)
1423 DBusMessage *message;
1425 _dbus_assert (message_type != DBUS_MESSAGE_TYPE_INVALID);
1427 message = dbus_message_new_empty_header (gvariant);
1428 if (message == NULL)
1431 if (!(_dbus_message_is_gvariant(message) ? _dbus_header_gvariant_create : _dbus_header_create) (&message->header,
1432 DBUS_COMPILER_BYTE_ORDER,
1434 destination, path, interface, member, error_name))
1436 dbus_message_unref (message);
1444 _dbus_message_create (int message_type,
1445 const char *destination,
1447 const char *interface,
1449 const char *error_name)
1451 return _dbus_message_create_protocol_version(message_type,
1457 _dbus_default_protocol_version == DBUS_PROTOCOL_VERSION_GVARIANT);
1461 * Constructs a new message of the given message type.
1462 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
1463 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
1465 * Usually you want to use dbus_message_new_method_call(),
1466 * dbus_message_new_method_return(), dbus_message_new_signal(),
1467 * or dbus_message_new_error() instead.
1469 * @param message_type type of message
1470 * @returns new message or #NULL if no memory
1473 dbus_message_new (int message_type)
1475 return _dbus_message_create(message_type,
1476 NULL, NULL, NULL, NULL, NULL);
1480 * Constructs a new message to invoke a method on a remote
1481 * object. Returns #NULL if memory can't be allocated for the
1482 * message. The destination may be #NULL in which case no destination
1483 * is set; this is appropriate when using D-Bus in a peer-to-peer
1484 * context (no message bus). The interface may be #NULL, which means
1485 * that if multiple methods with the given name exist it is undefined
1486 * which one will be invoked.
1488 * The path and method names may not be #NULL.
1490 * Destination, path, interface, and method name can't contain
1491 * any invalid characters (see the D-Bus specification).
1493 * @param destination name that the message should be sent to or #NULL
1494 * @param path object path the message should be sent to
1495 * @param iface interface to invoke method on, or #NULL
1496 * @param method method to invoke
1498 * @returns a new DBusMessage, free with dbus_message_unref()
1501 dbus_message_new_method_call (const char *destination,
1506 _dbus_return_val_if_fail (path != NULL, NULL);
1507 _dbus_return_val_if_fail (method != NULL, NULL);
1508 _dbus_return_val_if_fail (destination == NULL ||
1509 _dbus_check_is_valid_bus_name (destination), NULL);
1510 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1511 _dbus_return_val_if_fail (iface == NULL ||
1512 _dbus_check_is_valid_interface (iface), NULL);
1513 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
1515 return _dbus_message_create(DBUS_MESSAGE_TYPE_METHOD_CALL,
1516 destination, path, iface, method, NULL);
1520 * Constructs a message that is a reply to a method call. Returns
1521 * #NULL if memory can't be allocated for the message.
1523 * @param method_call the message being replied to
1524 * @returns a new DBusMessage, free with dbus_message_unref()
1527 dbus_message_new_method_return (DBusMessage *method_call)
1529 DBusMessage *message;
1532 _dbus_return_val_if_fail (method_call != NULL, NULL);
1534 sender = dbus_message_get_sender (method_call);
1536 /* sender is allowed to be null here in peer-to-peer case */
1538 message = _dbus_message_create (DBUS_MESSAGE_TYPE_METHOD_RETURN,
1539 sender, NULL, NULL, NULL, NULL);
1540 if (message == NULL)
1543 dbus_message_set_no_reply (message, TRUE);
1545 if (!dbus_message_set_reply_serial (message,
1546 dbus_message_get_serial (method_call)))
1548 dbus_message_unref (message);
1556 * Constructs a new message representing a signal emission. Returns
1557 * #NULL if memory can't be allocated for the message. A signal is
1558 * identified by its originating object path, interface, and the name
1561 * Path, interface, and signal name must all be valid (the D-Bus
1562 * specification defines the syntax of these fields).
1564 * @param path the path to the object emitting the signal
1565 * @param iface the interface the signal is emitted from
1566 * @param name name of the signal
1567 * @returns a new DBusMessage, free with dbus_message_unref()
1570 dbus_message_new_signal (const char *path,
1574 DBusMessage *message;
1576 _dbus_return_val_if_fail (path != NULL, NULL);
1577 _dbus_return_val_if_fail (iface != NULL, NULL);
1578 _dbus_return_val_if_fail (name != NULL, NULL);
1579 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
1580 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (iface), NULL);
1581 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
1583 message = _dbus_message_create (DBUS_MESSAGE_TYPE_SIGNAL,
1584 NULL, path, iface, name, NULL);
1585 if (message == NULL)
1588 dbus_message_set_no_reply (message, TRUE);
1594 * Creates a new message that is an error reply to another message.
1595 * Error replies are most common in response to method calls, but
1596 * can be returned in reply to any message.
1598 * The error name must be a valid error name according to the syntax
1599 * given in the D-Bus specification. If you don't want to make
1600 * up an error name just use #DBUS_ERROR_FAILED.
1602 * @param reply_to the message we're replying to
1603 * @param error_name the error name
1604 * @param error_message the error message string (or #NULL for none, but please give a message)
1605 * @returns a new error message object, free with dbus_message_unref()
1608 dbus_message_new_error (DBusMessage *reply_to,
1609 const char *error_name,
1610 const char *error_message)
1612 DBusMessage *message;
1614 DBusMessageIter iter;
1616 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1617 _dbus_return_val_if_fail (error_name != NULL, NULL);
1618 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1620 sender = dbus_message_get_sender (reply_to);
1622 /* sender may be NULL for non-message-bus case or
1623 * when the message bus is dealing with an unregistered
1626 message = _dbus_message_create (DBUS_MESSAGE_TYPE_ERROR,
1627 sender, NULL, NULL, NULL, error_name);
1628 if (message == NULL)
1631 dbus_message_set_no_reply (message, TRUE);
1633 if (!dbus_message_set_reply_serial (message,
1634 dbus_message_get_serial (reply_to)))
1636 dbus_message_unref (message);
1640 if (error_message != NULL)
1642 dbus_message_iter_init_append (message, &iter);
1643 if (!dbus_message_iter_append_basic (&iter,
1647 dbus_message_unref (message);
1656 * Creates a new message that is an error reply to another message, allowing
1657 * you to use printf formatting.
1659 * See dbus_message_new_error() for details - this function is the same
1660 * aside from the printf formatting.
1662 * @todo add _DBUS_GNUC_PRINTF to this (requires moving _DBUS_GNUC_PRINTF to
1663 * public header, see DBUS_DEPRECATED for an example)
1665 * @param reply_to the original message
1666 * @param error_name the error name
1667 * @param error_format the error message format as with printf
1668 * @param ... format string arguments
1669 * @returns a new error message
1672 dbus_message_new_error_printf (DBusMessage *reply_to,
1673 const char *error_name,
1674 const char *error_format,
1679 DBusMessage *message;
1681 _dbus_return_val_if_fail (reply_to != NULL, NULL);
1682 _dbus_return_val_if_fail (error_name != NULL, NULL);
1683 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
1685 if (!_dbus_string_init (&str))
1688 va_start (args, error_format);
1690 if (_dbus_string_append_printf_valist (&str, error_format, args))
1691 message = dbus_message_new_error (reply_to, error_name,
1692 _dbus_string_get_const_data (&str));
1696 _dbus_string_free (&str);
1705 * Creates a new message that is an exact replica of the message
1706 * specified, except that its refcount is set to 1, its message serial
1707 * is reset to 0, and if the original message was "locked" (in the
1708 * outgoing message queue and thus not modifiable) the new message
1709 * will not be locked.
1711 * @todo This function can't be used in programs that try to recover from OOM errors.
1713 * @param message the message
1714 * @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.
1717 dbus_message_copy (const DBusMessage *message)
1719 DBusMessage *retval;
1721 _dbus_return_val_if_fail (message != NULL, NULL);
1723 retval = dbus_new0 (DBusMessage, 1);
1727 _dbus_atomic_inc (&retval->refcount);
1729 retval->locked = FALSE;
1730 #ifndef DBUS_DISABLE_CHECKS
1731 retval->generation = message->generation;
1733 _dbus_message_toggle_gvariant (retval, _dbus_message_is_gvariant (message));
1735 if (!_dbus_header_copy (&message->header, &retval->header))
1741 if (!_dbus_string_init_preallocated (&retval->body,
1742 _dbus_string_get_length (&message->body)))
1744 _dbus_header_free (&retval->header);
1749 if (!_dbus_string_copy (&message->body, 0,
1753 #ifdef HAVE_UNIX_FD_PASSING
1754 retval->unix_fds = dbus_new(int, message->n_unix_fds);
1755 if (retval->unix_fds == NULL && message->n_unix_fds > 0)
1758 retval->n_unix_fds_allocated = message->n_unix_fds;
1760 for (retval->n_unix_fds = 0;
1761 retval->n_unix_fds < message->n_unix_fds;
1762 retval->n_unix_fds++)
1764 retval->unix_fds[retval->n_unix_fds] = _dbus_dup(message->unix_fds[retval->n_unix_fds], NULL);
1766 if (retval->unix_fds[retval->n_unix_fds] < 0)
1772 _dbus_message_trace_ref (retval, 0, 1, "copy");
1776 _dbus_header_free (&retval->header);
1777 _dbus_string_free (&retval->body);
1779 #ifdef HAVE_UNIX_FD_PASSING
1780 close_unix_fds(retval->unix_fds, &retval->n_unix_fds);
1781 dbus_free(retval->unix_fds);
1791 * Increments the reference count of a DBusMessage.
1793 * @param message the message
1794 * @returns the message
1795 * @see dbus_message_unref
1798 dbus_message_ref (DBusMessage *message)
1800 dbus_int32_t old_refcount;
1802 _dbus_return_val_if_fail (message != NULL, NULL);
1803 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1804 _dbus_return_val_if_fail (!message->in_cache, NULL);
1806 old_refcount = _dbus_atomic_inc (&message->refcount);
1807 _dbus_assert (old_refcount >= 1);
1808 _dbus_message_trace_ref (message, old_refcount, old_refcount + 1, "ref");
1814 * Decrements the reference count of a DBusMessage, freeing the
1815 * message if the count reaches 0.
1817 * @param message the message
1818 * @see dbus_message_ref
1821 dbus_message_unref (DBusMessage *message)
1823 dbus_int32_t old_refcount;
1825 _dbus_return_if_fail (message != NULL);
1826 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1827 _dbus_return_if_fail (!message->in_cache);
1829 old_refcount = _dbus_atomic_dec (&message->refcount);
1831 _dbus_assert (old_refcount >= 1);
1833 _dbus_message_trace_ref (message, old_refcount, old_refcount - 1, "unref");
1835 if (old_refcount == 1)
1837 /* Calls application callbacks! */
1838 dbus_message_cache_or_finalize (message);
1843 * Gets the type of a message. Types include
1844 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1845 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1846 * types are allowed and all code must silently ignore messages of
1847 * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
1849 * @param message the message
1850 * @returns the type of the message
1853 dbus_message_get_type (DBusMessage *message)
1855 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1857 return _dbus_header_get_message_type (&message->header);
1861 * Appends fields to a message given a variable argument list. The
1862 * variable argument list should contain the type of each argument
1863 * followed by the value to append. Appendable types are basic types,
1864 * and arrays of fixed-length basic types (except arrays of Unix file
1865 * descriptors). To append variable-length basic types, or any more
1866 * complex value, you have to use an iterator rather than this
1869 * To append a basic type, specify its type code followed by the
1870 * address of the value. For example:
1874 * dbus_int32_t v_INT32 = 42;
1875 * const char *v_STRING = "Hello World";
1876 * dbus_message_append_args (message,
1877 * DBUS_TYPE_INT32, &v_INT32,
1878 * DBUS_TYPE_STRING, &v_STRING,
1879 * DBUS_TYPE_INVALID);
1882 * To append an array of fixed-length basic types (except Unix file
1883 * descriptors), pass in the DBUS_TYPE_ARRAY typecode, the element
1884 * typecode, the address of the array pointer, and a 32-bit integer
1885 * giving the number of elements in the array. So for example: @code
1886 * const dbus_int32_t array[] = { 1, 2, 3 }; const dbus_int32_t
1887 * *v_ARRAY = array; dbus_message_append_args (message,
1888 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3, DBUS_TYPE_INVALID);
1891 * This function does not support arrays of Unix file descriptors. If
1892 * you need those you need to manually recurse into the array.
1894 * For Unix file descriptors this function will internally duplicate
1895 * the descriptor you passed in. Hence you may close the descriptor
1896 * immediately after this call.
1898 * @warning in C, given "int array[]", "&array == array" (the
1899 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
1900 * So if you're using an array instead of a pointer you have to create
1901 * a pointer variable, assign the array to it, then take the address
1902 * of the pointer variable. For strings it works to write
1903 * const char *array = "Hello" and then use &array though.
1905 * The last argument to this function must be #DBUS_TYPE_INVALID,
1906 * marking the end of the argument list. If you don't do this
1907 * then libdbus won't know to stop and will read invalid memory.
1909 * String/signature/path arrays should be passed in as "const char***
1910 * address_of_array" and "int n_elements"
1912 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1914 * @todo If this fails due to lack of memory, the message is hosed and
1915 * you have to start over building the whole message.
1917 * @param message the message
1918 * @param first_arg_type type of the first argument
1919 * @param ... value of first argument, list of additional type-value pairs
1920 * @returns #TRUE on success
1923 dbus_message_append_args (DBusMessage *message,
1930 _dbus_return_val_if_fail (message != NULL, FALSE);
1932 va_start (var_args, first_arg_type);
1933 retval = dbus_message_append_args_valist (message,
1942 * Like dbus_message_append_args() but takes a va_list for use by language bindings.
1944 * @todo for now, if this function fails due to OOM it will leave
1945 * the message half-written and you have to discard the message
1948 * @see dbus_message_append_args.
1949 * @param message the message
1950 * @param first_arg_type type of first argument
1951 * @param var_args value of first argument, then list of type/value pairs
1952 * @returns #TRUE on success
1955 dbus_message_append_args_valist (DBusMessage *message,
1960 DBusMessageIter iter;
1962 _dbus_return_val_if_fail (message != NULL, FALSE);
1964 type = first_arg_type;
1966 dbus_message_iter_init_append (message, &iter);
1968 while (type != DBUS_TYPE_INVALID)
1970 if (dbus_type_is_basic (type))
1972 const DBusBasicValue *value;
1973 value = va_arg (var_args, const DBusBasicValue*);
1975 if (!dbus_message_iter_append_basic (&iter,
1980 else if (type == DBUS_TYPE_ARRAY)
1983 DBusMessageIter array;
1986 element_type = va_arg (var_args, int);
1988 buf[0] = element_type;
1990 if (!dbus_message_iter_open_container (&iter,
1996 if (dbus_type_is_fixed (element_type) &&
1997 element_type != DBUS_TYPE_UNIX_FD)
1999 const DBusBasicValue **value;
2002 value = va_arg (var_args, const DBusBasicValue**);
2003 n_elements = va_arg (var_args, int);
2005 if (!dbus_message_iter_append_fixed_array (&array,
2009 dbus_message_iter_abandon_container (&iter, &array);
2013 else if (_DBUS_TYPE_IS_STRINGLIKE (element_type))
2015 const char ***value_p;
2020 value_p = va_arg (var_args, const char***);
2021 n_elements = va_arg (var_args, int);
2026 while (i < n_elements)
2028 if (!dbus_message_iter_append_basic (&array,
2031 dbus_message_iter_abandon_container (&iter, &array);
2039 _dbus_warn ("arrays of %s can't be appended with %s for now\n",
2040 _dbus_type_to_string (element_type),
2041 _DBUS_FUNCTION_NAME);
2042 dbus_message_iter_abandon_container (&iter, &array);
2046 if (!dbus_message_iter_close_container (&iter, &array))
2049 #ifndef DBUS_DISABLE_CHECKS
2052 _dbus_warn ("type %s isn't supported yet in %s\n",
2053 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
2058 type = va_arg (var_args, int);
2068 * Gets arguments from a message given a variable argument list. The
2069 * supported types include those supported by
2070 * dbus_message_append_args(); that is, basic types and arrays of
2071 * fixed-length basic types. The arguments are the same as they would
2072 * be for dbus_message_iter_get_basic() or
2073 * dbus_message_iter_get_fixed_array().
2075 * In addition to those types, arrays of string, object path, and
2076 * signature are supported; but these are returned as allocated memory
2077 * and must be freed with dbus_free_string_array(), while the other
2078 * types are returned as const references. To get a string array
2079 * pass in "char ***array_location" and "int *n_elements".
2081 * Similar to dbus_message_get_fixed_array() this function does not
2082 * support arrays of type DBUS_TYPE_UNIX_FD. If you need to parse
2083 * messages with arrays of Unix file descriptors you need to recurse
2084 * into the array manually.
2086 * Unix file descriptors that are read with this function will have
2087 * the FD_CLOEXEC flag set. If you need them without this flag set,
2088 * make sure to unset it with fcntl().
2090 * The variable argument list should contain the type of the argument
2091 * followed by a pointer to where the value should be stored. The list
2092 * is terminated with #DBUS_TYPE_INVALID.
2094 * Except for string arrays, the returned values are constant; do not
2095 * free them. They point into the #DBusMessage.
2097 * If the requested arguments are not present, or do not have the
2098 * requested types, then an error will be set.
2100 * If more arguments than requested are present, the requested
2101 * arguments are returned and the extra arguments are ignored.
2103 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
2105 * @param message the message
2106 * @param error error to be filled in on failure
2107 * @param first_arg_type the first argument type
2108 * @param ... location for first argument value, then list of type-location pairs
2109 * @returns #FALSE if the error was set
2112 dbus_message_get_args (DBusMessage *message,
2120 _dbus_return_val_if_fail (message != NULL, FALSE);
2121 _dbus_return_val_if_error_is_set (error, FALSE);
2123 va_start (var_args, first_arg_type);
2124 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
2131 * Like dbus_message_get_args but takes a va_list for use by language bindings.
2133 * @see dbus_message_get_args
2134 * @param message the message
2135 * @param error error to be filled in
2136 * @param first_arg_type type of the first argument
2137 * @param var_args return location for first argument, followed by list of type/location pairs
2138 * @returns #FALSE if error was set
2141 dbus_message_get_args_valist (DBusMessage *message,
2146 DBusMessageIter iter;
2148 _dbus_return_val_if_fail (message != NULL, FALSE);
2149 _dbus_return_val_if_error_is_set (error, FALSE);
2151 dbus_message_iter_init (message, &iter);
2152 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
2156 _dbus_message_iter_init_common (DBusMessage *message,
2157 DBusMessageRealIter *real,
2160 _DBUS_STATIC_ASSERT (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
2162 /* Since the iterator will read or write who-knows-what from the
2163 * message, we need to get in the right byte order
2165 ensure_byte_order (message);
2167 real->message = message;
2168 real->changed_stamp = message->changed_stamp;
2169 real->iter_type = iter_type;
2170 real->sig_refcount = 0;
2174 * Initializes a #DBusMessageIter for reading the arguments of the
2175 * message passed in.
2177 * When possible, dbus_message_get_args() is much more convenient.
2178 * Some types of argument can only be read with #DBusMessageIter
2181 * The easiest way to iterate is like this:
2183 * dbus_message_iter_init (message, &iter);
2184 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2185 * dbus_message_iter_next (&iter);
2188 * #DBusMessageIter contains no allocated memory; it need not be
2189 * freed, and can be copied by assignment or memcpy().
2191 * @param message the message
2192 * @param iter pointer to an iterator to initialize
2193 * @returns #FALSE if the message has no arguments
2196 dbus_message_iter_init (DBusMessage *message,
2197 DBusMessageIter *iter)
2199 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2200 const DBusString *type_str;
2203 BUILD_BUG_ON (sizeof(DBusMessageIter) != sizeof(DBusMessageRealIter));
2205 _dbus_return_val_if_fail (message != NULL, FALSE);
2206 _dbus_return_val_if_fail (iter != NULL, FALSE);
2208 get_const_signature (message, &type_str, &type_pos);
2210 _dbus_message_iter_init_common (message, real,
2211 DBUS_MESSAGE_ITER_TYPE_READER);
2213 _dbus_type_reader_init (&real->u.reader,
2214 _dbus_header_get_byte_order (&message->header),
2219 if (_dbus_message_is_gvariant (message))
2220 _dbus_type_reader_gvariant_init (&real->u.reader, message);
2222 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
2226 * Checks if an iterator has any more fields.
2228 * @param iter the message iter
2229 * @returns #TRUE if there are more fields following
2232 dbus_message_iter_has_next (DBusMessageIter *iter)
2234 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2236 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2237 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2239 return _dbus_type_reader_has_next (&real->u.reader);
2243 * Moves the iterator to the next field, if any. If there's no next
2244 * field, returns #FALSE. If the iterator moves forward, returns
2247 * @param iter the message iter
2248 * @returns #TRUE if the iterator was moved to the next field
2251 dbus_message_iter_next (DBusMessageIter *iter)
2253 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2255 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
2256 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2258 return _dbus_type_reader_next (&real->u.reader);
2262 * Returns the argument type of the argument that the message iterator
2263 * points to. If the iterator is at the end of the message, returns
2264 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
2267 * dbus_message_iter_init (message, &iter);
2268 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
2269 * dbus_message_iter_next (&iter);
2272 * @param iter the message iter
2273 * @returns the argument type
2276 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
2278 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2280 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2281 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
2283 return _dbus_type_reader_get_current_type (&real->u.reader);
2287 * Returns the element type of the array that the message iterator
2288 * points to. Note that you need to check that the iterator points to
2289 * an array prior to using this function.
2291 * @param iter the message iter
2292 * @returns the array element type
2295 dbus_message_iter_get_element_type (DBusMessageIter *iter)
2297 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2299 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
2300 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
2301 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
2303 return _dbus_type_reader_get_element_type (&real->u.reader);
2307 * Recurses into a container value when reading values from a message,
2308 * initializing a sub-iterator to use for traversing the child values
2311 * Note that this recurses into a value, not a type, so you can only
2312 * recurse if the value exists. The main implication of this is that
2313 * if you have for example an empty array of array of int32, you can
2314 * recurse into the outermost array, but it will have no values, so
2315 * you won't be able to recurse further. There's no array of int32 to
2318 * If a container is an array of fixed-length types (except Unix file
2319 * descriptors), it is much more efficient to use
2320 * dbus_message_iter_get_fixed_array() to get the whole array in one
2321 * shot, rather than individually walking over the array elements.
2323 * Be sure you have somehow checked that
2324 * dbus_message_iter_get_arg_type() matches the type you are expecting
2325 * to recurse into. Results of this function are undefined if there is
2326 * no container to recurse into at the current iterator position.
2328 * @param iter the message iterator
2329 * @param sub the sub-iterator to initialize
2332 dbus_message_iter_recurse (DBusMessageIter *iter,
2333 DBusMessageIter *sub)
2335 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2336 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2338 _dbus_return_if_fail (_dbus_message_iter_check (real));
2339 _dbus_return_if_fail (sub != NULL);
2342 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
2346 * Returns the current signature of a message iterator. This
2347 * is useful primarily for dealing with variants; one can
2348 * recurse into a variant and determine the signature of
2349 * the variant's value.
2351 * The returned string must be freed with dbus_free().
2353 * @param iter the message iterator
2354 * @returns the contained signature, or NULL if out of memory
2357 dbus_message_iter_get_signature (DBusMessageIter *iter)
2359 const DBusString *sig;
2363 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2365 _dbus_return_val_if_fail (_dbus_message_iter_check (real), NULL);
2367 if (!_dbus_string_init (&retstr))
2370 _dbus_type_reader_get_signature (&real->u.reader, &sig,
2372 if (!_dbus_string_append_len (&retstr,
2373 _dbus_string_get_const_data (sig) + start,
2376 if (!_dbus_string_steal_data (&retstr, &ret))
2378 _dbus_string_free (&retstr);
2383 * Reads a basic-typed value from the message iterator.
2384 * Basic types are the non-containers such as integer and string.
2386 * The value argument should be the address of a location to store
2387 * the returned value. So for int32 it should be a "dbus_int32_t*"
2388 * and for string a "const char**". The returned value is
2389 * by reference and should not be freed.
2391 * This call duplicates Unix file descriptors when reading them. It is
2392 * your job to close them when you don't need them anymore.
2394 * Unix file descriptors that are read with this function will have
2395 * the FD_CLOEXEC flag set. If you need them without this flag set,
2396 * make sure to unset it with fcntl().
2398 * Be sure you have somehow checked that
2399 * dbus_message_iter_get_arg_type() matches the type you are
2400 * expecting, or you'll crash when you try to use an integer as a
2401 * string or something.
2403 * To read any container type (array, struct, dict) you will need to
2404 * recurse into the container with dbus_message_iter_recurse(). If
2405 * the container is an array of fixed-length values (except Unix file
2406 * descriptors), you can get all the array elements at once with
2407 * dbus_message_iter_get_fixed_array(). Otherwise, you have to iterate
2408 * over the container's contents one value at a time.
2410 * All basic-typed values are guaranteed to fit in a #DBusBasicValue,
2411 * so in versions of libdbus that have that type, you can write code like this:
2414 * DBusBasicValue value;
2416 * dbus_message_iter_get_basic (&read_iter, &value);
2417 * type = dbus_message_iter_get_arg_type (&read_iter);
2418 * dbus_message_iter_append_basic (&write_iter, type, &value);
2421 * (All D-Bus basic types are either numeric and 8 bytes or smaller, or
2422 * behave like a string; so in older versions of libdbus, DBusBasicValue
2423 * can be replaced with union { char *string; unsigned char bytes[8]; },
2426 * @param iter the iterator
2427 * @param value location to store the value
2430 dbus_message_iter_get_basic (DBusMessageIter *iter,
2433 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2435 _dbus_return_if_fail (_dbus_message_iter_check (real));
2436 _dbus_return_if_fail (value != NULL);
2438 if (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_UNIX_FD)
2440 #ifdef HAVE_UNIX_FD_PASSING
2443 _dbus_type_reader_read_basic(&real->u.reader, &idx);
2445 if (idx.u32 >= real->message->n_unix_fds) {
2446 /* Hmm, we cannot really signal an error here, so let's make
2447 sure to return an invalid fd. */
2448 *((int*) value) = -1;
2452 *((int*) value) = _dbus_dup(real->message->unix_fds[idx.u32], NULL);
2454 *((int*) value) = -1;
2459 _dbus_type_reader_read_basic (&real->u.reader,
2465 * Returns the number of elements in the array-typed value pointed
2466 * to by the iterator.
2467 * Note that this function is O(1) for arrays of fixed-size types
2468 * but O(n) for arrays of variable-length types such as strings,
2469 * so it may be a bad idea to use it.
2471 * @param iter the iterator
2472 * @returns the number of elements in the array
2475 dbus_message_iter_get_element_count (DBusMessageIter *iter)
2477 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2478 DBusTypeReader array;
2482 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2483 _dbus_return_val_if_fail (_dbus_type_reader_get_current_type (&real->u.reader)
2484 == DBUS_TYPE_ARRAY, 0);
2486 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
2487 _dbus_type_reader_recurse (&real->u.reader, &array);
2488 if (dbus_type_is_fixed (element_type))
2490 int alignment = _dbus_type_get_alignment (element_type);
2491 int total_len = _dbus_type_reader_get_array_length (&array);
2492 n_elements = total_len / alignment;
2496 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
2499 _dbus_type_reader_next (&array);
2507 * Returns the number of bytes in the array as marshaled in the wire
2508 * protocol. The iterator must currently be inside an array-typed
2511 * This function is deprecated on the grounds that it is stupid. Why
2512 * would you want to know how many bytes are in the array as marshaled
2513 * in the wire protocol? Use dbus_message_iter_get_element_count() instead.
2515 * @param iter the iterator
2516 * @returns the number of bytes in the array
2519 dbus_message_iter_get_array_len (DBusMessageIter *iter)
2521 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2523 _dbus_return_val_if_fail (_dbus_message_iter_check (real), 0);
2525 return _dbus_type_reader_get_array_length (&real->u.reader);
2529 * Reads a block of fixed-length values from the message iterator.
2530 * Fixed-length values are those basic types that are not string-like,
2531 * such as integers, bool, double. The returned block will be from the
2532 * current position in the array until the end of the array.
2534 * There is one exception here: although DBUS_TYPE_UNIX_FD is
2535 * considered a 'fixed' type arrays of this type may not be read with
2538 * The message iter should be "in" the array (that is, you recurse into the
2539 * array, and then you call dbus_message_iter_get_fixed_array() on the
2540 * "sub-iterator" created by dbus_message_iter_recurse()).
2542 * The value argument should be the address of a location to store the
2543 * returned array. So for int32 it should be a "const dbus_int32_t**"
2544 * The returned value is by reference and should not be freed.
2546 * This function should only be used if dbus_type_is_fixed() returns
2547 * #TRUE for the element type.
2549 * If an array's elements are not fixed in size, you have to recurse
2550 * into the array with dbus_message_iter_recurse() and read the
2551 * elements one by one.
2553 * Because the array is not copied, this function runs in constant
2554 * time and is fast; it's much preferred over walking the entire array
2555 * with an iterator. (However, you can always use
2556 * dbus_message_iter_recurse(), even for fixed-length types;
2557 * dbus_message_iter_get_fixed_array() is just an optimization.)
2559 * @param iter the iterator
2560 * @param value location to store the block
2561 * @param n_elements number of elements in the block
2564 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
2568 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2569 #ifndef DBUS_DISABLE_CHECKS
2570 int subtype = _dbus_type_reader_get_current_type(&real->u.reader);
2572 _dbus_return_if_fail (_dbus_message_iter_check (real));
2573 _dbus_return_if_fail (value != NULL);
2574 _dbus_return_if_fail ((subtype == DBUS_TYPE_INVALID) ||
2575 (dbus_type_is_fixed (subtype) && subtype != DBUS_TYPE_UNIX_FD));
2578 _dbus_type_reader_read_fixed_multi (&real->u.reader,
2583 * Initializes a #DBusMessageIter for appending arguments to the end
2586 * @todo If appending any of the arguments fails due to lack of
2587 * memory, the message is hosed and you have to start over building
2588 * the whole message.
2590 * @param message the message
2591 * @param iter pointer to an iterator to initialize
2594 dbus_message_iter_init_append (DBusMessage *message,
2595 DBusMessageIter *iter)
2597 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2599 _dbus_return_if_fail (message != NULL);
2600 _dbus_return_if_fail (iter != NULL);
2602 _dbus_message_iter_init_common (message, real,
2603 DBUS_MESSAGE_ITER_TYPE_WRITER);
2605 /* We create the signature string and point iterators at it "on demand"
2606 * when a value is actually appended. That means that init() never fails
2609 _dbus_type_writer_gvariant_init_types_delayed (
2611 _dbus_header_get_byte_order (&message->header),
2613 _dbus_string_get_length (&message->body),
2614 _dbus_message_is_gvariant (message),
2615 &message->gvariant_body_last_offset,
2616 &message->gvariant_body_last_pos);
2620 * Creates a temporary signature string containing the current
2621 * signature, stores it in the iterator, and points the iterator to
2622 * the end of it. Used any time we write to the message.
2624 * @param real an iterator without a type_str
2625 * @returns #FALSE if no memory
2628 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
2631 const DBusString *current_sig;
2632 int current_sig_pos;
2634 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2636 if (real->u.writer.type_str != NULL)
2638 _dbus_assert (real->sig_refcount > 0);
2639 real->sig_refcount += 1;
2643 str = dbus_new (DBusString, 1);
2647 if (!_dbus_header_get_field_raw (&real->message->header,
2648 DBUS_HEADER_FIELD_SIGNATURE,
2649 ¤t_sig, ¤t_sig_pos))
2655 int additional_size_for_len = 0;
2657 if (!real->u.writer.gvariant)
2659 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
2660 current_sig_pos += 1; /* move on to sig data */
2661 additional_size_for_len = 4;
2665 /* GVariant has no length field, simply string */
2666 current_len = strlen (_dbus_string_get_const_data (current_sig) + current_sig_pos);
2669 if (!_dbus_string_init_preallocated (str, current_len + additional_size_for_len))
2675 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
2678 _dbus_string_free (str);
2685 if (!_dbus_string_init_preallocated (str, 4))
2692 real->sig_refcount = 1;
2694 _dbus_type_writer_add_types (&real->u.writer,
2695 str, _dbus_string_get_length (str));
2700 * Sets the new signature as the message signature, frees the
2701 * signature string, and marks the iterator as not having a type_str
2702 * anymore. Frees the signature even if it fails, so you can't
2703 * really recover from failure. Kinda busted.
2705 * @param real an iterator without a type_str
2706 * @returns #FALSE if no memory
2709 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2712 const char *v_STRING;
2715 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2716 _dbus_assert (real->u.writer.type_str != NULL);
2717 _dbus_assert (real->sig_refcount > 0);
2719 real->sig_refcount -= 1;
2721 if (real->sig_refcount > 0)
2723 _dbus_assert (real->sig_refcount == 0);
2727 str = real->u.writer.type_str;
2729 v_STRING = _dbus_string_get_const_data (str);
2730 if (!_dbus_header_set_field_basic (&real->message->header,
2731 DBUS_HEADER_FIELD_SIGNATURE,
2732 DBUS_TYPE_SIGNATURE,
2736 _dbus_type_writer_remove_types (&real->u.writer);
2737 _dbus_string_free (str);
2744 * Frees the signature string and marks the iterator as not having a
2745 * type_str anymore. Since the new signature is not set, the message
2746 * will generally be hosed after this is called.
2748 * @param real an iterator without a type_str
2751 _dbus_message_iter_abandon_signature (DBusMessageRealIter *real)
2755 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2756 _dbus_assert (real->u.writer.type_str != NULL);
2757 _dbus_assert (real->sig_refcount > 0);
2759 real->sig_refcount -= 1;
2761 if (real->sig_refcount > 0)
2763 _dbus_assert (real->sig_refcount == 0);
2765 str = real->u.writer.type_str;
2767 _dbus_type_writer_remove_types (&real->u.writer);
2768 _dbus_string_free (str);
2772 #ifndef DBUS_DISABLE_CHECKS
2774 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2776 if (!_dbus_message_iter_check (iter))
2779 if (iter->message->locked)
2781 _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)\n");
2787 #endif /* DBUS_DISABLE_CHECKS */
2789 #ifdef HAVE_UNIX_FD_PASSING
2791 expand_fd_array(DBusMessage *m,
2796 /* This makes space for adding n new fds to the array and returns a
2797 pointer to the place were the first fd should be put. */
2799 if (m->n_unix_fds + n > m->n_unix_fds_allocated)
2804 /* Make twice as much space as necessary */
2805 k = (m->n_unix_fds + n) * 2;
2807 /* Allocate at least four */
2811 p = dbus_realloc(m->unix_fds, k * sizeof(int));
2816 m->n_unix_fds_allocated = k;
2819 return m->unix_fds + m->n_unix_fds;
2824 * Appends a basic-typed value to the message. The basic types are the
2825 * non-container types such as integer and string.
2827 * The "value" argument should be the address of a basic-typed value.
2828 * So for string, const char**. For integer, dbus_int32_t*.
2830 * For Unix file descriptors this function will internally duplicate
2831 * the descriptor you passed in. Hence you may close the descriptor
2832 * immediately after this call.
2834 * @todo If this fails due to lack of memory, the message is hosed and
2835 * you have to start over building the whole message.
2837 * @param iter the append iterator
2838 * @param type the type of the value
2839 * @param value the address of the value
2840 * @returns #FALSE if not enough memory
2843 dbus_message_iter_append_basic (DBusMessageIter *iter,
2847 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2850 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2851 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2852 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2853 _dbus_return_val_if_fail (value != NULL, FALSE);
2855 #ifndef DBUS_DISABLE_CHECKS
2858 const char * const *string_p;
2859 const dbus_bool_t *bool_p;
2861 case DBUS_TYPE_STRING:
2863 _dbus_return_val_if_fail (_dbus_check_is_valid_utf8 (*string_p), FALSE);
2866 case DBUS_TYPE_OBJECT_PATH:
2868 _dbus_return_val_if_fail (_dbus_check_is_valid_path (*string_p), FALSE);
2871 case DBUS_TYPE_SIGNATURE:
2873 _dbus_return_val_if_fail (_dbus_check_is_valid_signature (*string_p), FALSE);
2876 case DBUS_TYPE_BOOLEAN:
2878 _dbus_return_val_if_fail (*bool_p == 0 || *bool_p == 1, FALSE);
2883 /* nothing to check, all possible values are allowed */
2888 if (!_dbus_message_iter_open_signature (real))
2891 if (type == DBUS_TYPE_UNIX_FD)
2893 #ifdef HAVE_UNIX_FD_PASSING
2899 /* First step, include the fd in the fd list of this message */
2900 if (!(fds = expand_fd_array(real->message, 1)))
2903 *fds = _dbus_dup(*(int*) value, NULL);
2907 u = real->message->n_unix_fds;
2909 /* Second step, write the index to the fd */
2910 if (!(ret = _dbus_type_writer_write_basic (&real->u.writer, DBUS_TYPE_UNIX_FD, &u))) {
2911 _dbus_close(*fds, NULL);
2915 real->message->n_unix_fds += 1;
2918 /* Final step, update the header accordingly */
2919 ret = _dbus_header_set_field_basic (&real->message->header,
2920 DBUS_HEADER_FIELD_UNIX_FDS,
2924 /* If any of these operations fail the message is
2925 hosed. However, no memory or fds should be leaked since what
2926 has been added to message has been added to the message, and
2927 can hence be accounted for when the message is being
2931 /* This is redundant (we could just fall through), but it avoids
2932 * -Wunused-label in builds that don't HAVE_UNIX_FD_PASSING */
2938 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
2942 if (!_dbus_message_iter_close_signature (real))
2949 * Appends a block of fixed-length values to an array. The
2950 * fixed-length types are all basic types that are not string-like. So
2951 * int32, double, bool, etc. (Unix file descriptors however are not
2952 * supported.) You must call dbus_message_iter_open_container() to
2953 * open an array of values before calling this function. You may call
2954 * this function multiple times (and intermixed with calls to
2955 * dbus_message_iter_append_basic()) for the same array.
2957 * The "value" argument should be the address of the array. So for
2958 * integer, "dbus_int32_t**" is expected for example.
2960 * @warning in C, given "int array[]", "&array == array" (the
2961 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2962 * So if you're using an array instead of a pointer you have to create
2963 * a pointer variable, assign the array to it, then take the address
2964 * of the pointer variable.
2966 * const dbus_int32_t array[] = { 1, 2, 3 };
2967 * const dbus_int32_t *v_ARRAY = array;
2968 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
2969 * fprintf (stderr, "No memory!\n");
2971 * For strings it works to write const char *array = "Hello" and then
2972 * use &array though.
2974 * @todo If this fails due to lack of memory, the message is hosed and
2975 * you have to start over building the whole message.
2977 * @param iter the append iterator
2978 * @param element_type the type of the array elements
2979 * @param value the address of the array
2980 * @param n_elements the number of elements to append
2981 * @returns #FALSE if not enough memory
2984 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
2989 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2992 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2993 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2994 _dbus_return_val_if_fail (dbus_type_is_fixed (element_type) && element_type != DBUS_TYPE_UNIX_FD, FALSE);
2995 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
2996 _dbus_return_val_if_fail (value != NULL, FALSE);
2997 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
2998 _dbus_return_val_if_fail (n_elements <=
2999 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
3002 #ifndef DBUS_DISABLE_CHECKS
3003 if (element_type == DBUS_TYPE_BOOLEAN)
3005 const dbus_bool_t * const *bools = value;
3008 for (i = 0; i < n_elements; i++)
3010 _dbus_return_val_if_fail ((*bools)[i] == 0 || (*bools)[i] == 1, FALSE);
3015 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
3021 * Appends a container-typed value to the message; you are required to
3022 * append the contents of the container using the returned
3023 * sub-iterator, and then call
3024 * dbus_message_iter_close_container(). Container types are for
3025 * example struct, variant, and array. For variants, the
3026 * contained_signature should be the type of the single value inside
3027 * the variant. For structs and dict entries, contained_signature
3028 * should be #NULL; it will be set to whatever types you write into
3029 * the struct. For arrays, contained_signature should be the type of
3030 * the array elements.
3032 * @todo If this fails due to lack of memory, the message is hosed and
3033 * you have to start over building the whole message.
3035 * @param iter the append iterator
3036 * @param type the type of the value
3037 * @param contained_signature the type of container contents
3038 * @param sub sub-iterator to initialize
3039 * @returns #FALSE if not enough memory
3042 dbus_message_iter_open_container (DBusMessageIter *iter,
3044 const char *contained_signature,
3045 DBusMessageIter *sub)
3047 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
3048 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
3049 DBusString contained_str;
3051 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
3052 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
3053 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
3054 _dbus_return_val_if_fail (sub != NULL, FALSE);
3055 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
3056 contained_signature == NULL) ||
3057 (type == DBUS_TYPE_DICT_ENTRY &&
3058 contained_signature == NULL) ||
3059 (type == DBUS_TYPE_VARIANT &&
3060 contained_signature != NULL) ||
3061 (type == DBUS_TYPE_ARRAY &&
3062 contained_signature != NULL), FALSE);
3064 /* this would fail if the contained_signature is a dict entry, since
3065 * dict entries are invalid signatures standalone (they must be in
3068 _dbus_return_val_if_fail ((type == DBUS_TYPE_ARRAY && contained_signature && *contained_signature == DBUS_DICT_ENTRY_BEGIN_CHAR) ||
3069 (contained_signature == NULL ||
3070 _dbus_check_is_valid_signature (contained_signature)),
3073 if (!_dbus_message_iter_open_signature (real))
3078 if (contained_signature != NULL)
3080 _dbus_string_init_const (&contained_str, contained_signature);
3082 return _dbus_type_writer_recurse (&real->u.writer,
3085 &real_sub->u.writer);
3089 return _dbus_type_writer_recurse (&real->u.writer,
3092 &real_sub->u.writer);
3098 * Closes a container-typed value appended to the message; may write
3099 * out more information to the message known only after the entire
3100 * container is written, and may free resources created by
3101 * dbus_message_iter_open_container().
3103 * @todo If this fails due to lack of memory, the message is hosed and
3104 * you have to start over building the whole message.
3106 * @param iter the append iterator
3107 * @param sub sub-iterator to close
3108 * @returns #FALSE if not enough memory
3111 dbus_message_iter_close_container (DBusMessageIter *iter,
3112 DBusMessageIter *sub)
3114 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
3115 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
3118 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
3119 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
3120 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
3121 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
3123 ret = _dbus_type_writer_unrecurse (&real->u.writer,
3124 &real_sub->u.writer);
3126 if (!_dbus_message_iter_close_signature (real))
3133 * Abandons creation of a contained-typed value and frees resources created
3134 * by dbus_message_iter_open_container(). Once this returns, the message
3135 * is hosed and you have to start over building the whole message.
3137 * This should only be used to abandon creation of a message when you have
3140 * @param iter the append iterator
3141 * @param sub sub-iterator to close
3144 dbus_message_iter_abandon_container (DBusMessageIter *iter,
3145 DBusMessageIter *sub)
3147 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
3148 #ifndef DBUS_DISABLE_CHECKS
3149 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
3151 _dbus_return_if_fail (_dbus_message_iter_append_check (real));
3152 _dbus_return_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
3153 _dbus_return_if_fail (_dbus_message_iter_append_check (real_sub));
3154 _dbus_return_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
3157 _dbus_message_iter_abandon_signature (real);
3161 * Sets a flag indicating that the message does not want a reply; if
3162 * this flag is set, the other end of the connection may (but is not
3163 * required to) optimize by not sending method return or error
3164 * replies. If this flag is set, there is no way to know whether the
3165 * message successfully arrived at the remote end. Normally you know a
3166 * message was received when you receive the reply to it.
3168 * The flag is #FALSE by default, that is by default the other end is
3169 * required to reply.
3171 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
3173 * @param message the message
3174 * @param no_reply #TRUE if no reply is desired
3177 dbus_message_set_no_reply (DBusMessage *message,
3178 dbus_bool_t no_reply)
3180 _dbus_return_if_fail (message != NULL);
3181 _dbus_return_if_fail (!message->locked);
3183 _dbus_header_toggle_flag (&message->header,
3184 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
3189 * Returns #TRUE if the message does not expect
3192 * @param message the message
3193 * @returns #TRUE if the message sender isn't waiting for a reply
3196 dbus_message_get_no_reply (DBusMessage *message)
3198 _dbus_return_val_if_fail (message != NULL, FALSE);
3200 return _dbus_header_get_flag (&message->header,
3201 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
3205 * Sets a flag indicating that an owner for the destination name will
3206 * be automatically started before the message is delivered. When this
3207 * flag is set, the message is held until a name owner finishes
3208 * starting up, or fails to start up. In case of failure, the reply
3211 * The flag is set to #TRUE by default, i.e. auto starting is the default.
3213 * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
3215 * @param message the message
3216 * @param auto_start #TRUE if auto-starting is desired
3219 dbus_message_set_auto_start (DBusMessage *message,
3220 dbus_bool_t auto_start)
3222 _dbus_return_if_fail (message != NULL);
3223 _dbus_return_if_fail (!message->locked);
3225 _dbus_header_toggle_flag (&message->header,
3226 DBUS_HEADER_FLAG_NO_AUTO_START,
3231 * Returns #TRUE if the message will cause an owner for
3232 * destination name to be auto-started.
3234 * @param message the message
3235 * @returns #TRUE if the message will use auto-start
3238 dbus_message_get_auto_start (DBusMessage *message)
3240 _dbus_return_val_if_fail (message != NULL, FALSE);
3242 return !_dbus_header_get_flag (&message->header,
3243 DBUS_HEADER_FLAG_NO_AUTO_START);
3248 * Sets the object path this message is being sent to (for
3249 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
3250 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
3252 * The path must contain only valid characters as defined
3253 * in the D-Bus specification.
3255 * @param message the message
3256 * @param object_path the path or #NULL to unset
3257 * @returns #FALSE if not enough memory
3260 dbus_message_set_path (DBusMessage *message,
3261 const char *object_path)
3263 _dbus_return_val_if_fail (message != NULL, FALSE);
3264 _dbus_return_val_if_fail (!message->locked, FALSE);
3265 _dbus_return_val_if_fail (object_path == NULL ||
3266 _dbus_check_is_valid_path (object_path),
3269 return set_or_delete_string_field (message,
3270 DBUS_HEADER_FIELD_PATH,
3271 DBUS_TYPE_OBJECT_PATH,
3276 * Gets the object path this message is being sent to (for
3277 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
3278 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3280 * See also dbus_message_get_path_decomposed().
3282 * The returned string becomes invalid if the message is
3283 * modified, since it points into the wire-marshaled message data.
3285 * @param message the message
3286 * @returns the path (should not be freed) or #NULL
3289 dbus_message_get_path (DBusMessage *message)
3293 _dbus_return_val_if_fail (message != NULL, NULL);
3295 v = NULL; /* in case field doesn't exist */
3296 _dbus_header_get_field_basic (&message->header,
3297 DBUS_HEADER_FIELD_PATH,
3298 DBUS_TYPE_OBJECT_PATH,
3304 * Checks if the message has a particular object path. The object
3305 * path is the destination object for a method call or the emitting
3306 * object for a signal.
3308 * @param message the message
3309 * @param path the path name
3310 * @returns #TRUE if there is a path field in the header
3313 dbus_message_has_path (DBusMessage *message,
3316 const char *msg_path;
3317 msg_path = dbus_message_get_path (message);
3319 if (msg_path == NULL)
3330 if (strcmp (msg_path, path) == 0)
3337 * Gets the object path this message is being sent to
3338 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3339 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
3340 * format (one array element per path component).
3341 * Free the returned array with dbus_free_string_array().
3343 * An empty but non-NULL path array means the path "/".
3344 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
3345 * and the path "/" becomes { NULL }.
3347 * See also dbus_message_get_path().
3349 * @todo this could be optimized by using the len from the message
3350 * instead of calling strlen() again
3352 * @param message the message
3353 * @param path place to store allocated array of path components; #NULL set here if no path field exists
3354 * @returns #FALSE if no memory to allocate the array
3357 dbus_message_get_path_decomposed (DBusMessage *message,
3362 _dbus_return_val_if_fail (message != NULL, FALSE);
3363 _dbus_return_val_if_fail (path != NULL, FALSE);
3367 v = dbus_message_get_path (message);
3370 if (!_dbus_decompose_path (v, strlen (v),
3378 * Sets the interface this message is being sent to
3379 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
3380 * the interface a signal is being emitted from
3381 * (for DBUS_MESSAGE_TYPE_SIGNAL).
3383 * The interface name must contain only valid characters as defined
3384 * in the D-Bus specification.
3386 * @param message the message
3387 * @param iface the interface or #NULL to unset
3388 * @returns #FALSE if not enough memory
3391 dbus_message_set_interface (DBusMessage *message,
3394 _dbus_return_val_if_fail (message != NULL, FALSE);
3395 _dbus_return_val_if_fail (!message->locked, FALSE);
3396 _dbus_return_val_if_fail (iface == NULL ||
3397 _dbus_check_is_valid_interface (iface),
3400 return set_or_delete_string_field (message,
3401 DBUS_HEADER_FIELD_INTERFACE,
3407 * Gets the interface this message is being sent to
3408 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
3409 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
3410 * The interface name is fully-qualified (namespaced).
3411 * Returns #NULL if none.
3413 * The returned string becomes invalid if the message is
3414 * modified, since it points into the wire-marshaled message data.
3416 * @param message the message
3417 * @returns the message interface (should not be freed) or #NULL
3420 dbus_message_get_interface (DBusMessage *message)
3424 _dbus_return_val_if_fail (message != NULL, NULL);
3426 v = NULL; /* in case field doesn't exist */
3427 _dbus_header_get_field_basic (&message->header,
3428 DBUS_HEADER_FIELD_INTERFACE,
3435 * Checks if the message has an interface
3437 * @param message the message
3438 * @param iface the interface name
3439 * @returns #TRUE if the interface field in the header matches
3442 dbus_message_has_interface (DBusMessage *message,
3445 const char *msg_interface;
3446 msg_interface = dbus_message_get_interface (message);
3448 if (msg_interface == NULL)
3459 if (strcmp (msg_interface, iface) == 0)
3467 * Sets the interface member being invoked
3468 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3469 * (DBUS_MESSAGE_TYPE_SIGNAL).
3471 * The member name must contain only valid characters as defined
3472 * in the D-Bus specification.
3474 * @param message the message
3475 * @param member the member or #NULL to unset
3476 * @returns #FALSE if not enough memory
3479 dbus_message_set_member (DBusMessage *message,
3482 _dbus_return_val_if_fail (message != NULL, FALSE);
3483 _dbus_return_val_if_fail (!message->locked, FALSE);
3484 _dbus_return_val_if_fail (member == NULL ||
3485 _dbus_check_is_valid_member (member),
3488 return set_or_delete_string_field (message,
3489 DBUS_HEADER_FIELD_MEMBER,
3495 * Gets the interface member being invoked
3496 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
3497 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
3499 * The returned string becomes invalid if the message is
3500 * modified, since it points into the wire-marshaled message data.
3502 * @param message the message
3503 * @returns the member name (should not be freed) or #NULL
3506 dbus_message_get_member (DBusMessage *message)
3510 _dbus_return_val_if_fail (message != NULL, NULL);
3512 v = NULL; /* in case field doesn't exist */
3513 _dbus_header_get_field_basic (&message->header,
3514 DBUS_HEADER_FIELD_MEMBER,
3521 * Checks if the message has an interface member
3523 * @param message the message
3524 * @param member the member name
3525 * @returns #TRUE if there is a member field in the header
3528 dbus_message_has_member (DBusMessage *message,
3531 const char *msg_member;
3532 msg_member = dbus_message_get_member (message);
3534 if (msg_member == NULL)
3545 if (strcmp (msg_member, member) == 0)
3553 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
3554 * The name is fully-qualified (namespaced).
3556 * The error name must contain only valid characters as defined
3557 * in the D-Bus specification.
3559 * @param message the message
3560 * @param error_name the name or #NULL to unset
3561 * @returns #FALSE if not enough memory
3564 dbus_message_set_error_name (DBusMessage *message,
3565 const char *error_name)
3567 _dbus_return_val_if_fail (message != NULL, FALSE);
3568 _dbus_return_val_if_fail (!message->locked, FALSE);
3569 _dbus_return_val_if_fail (error_name == NULL ||
3570 _dbus_check_is_valid_error_name (error_name),
3573 return set_or_delete_string_field (message,
3574 DBUS_HEADER_FIELD_ERROR_NAME,
3580 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
3583 * The returned string becomes invalid if the message is
3584 * modified, since it points into the wire-marshaled message data.
3586 * @param message the message
3587 * @returns the error name (should not be freed) or #NULL
3590 dbus_message_get_error_name (DBusMessage *message)
3594 _dbus_return_val_if_fail (message != NULL, NULL);
3596 v = NULL; /* in case field doesn't exist */
3597 _dbus_header_get_field_basic (&message->header,
3598 DBUS_HEADER_FIELD_ERROR_NAME,
3605 * Sets the message's destination. The destination is the name of
3606 * another connection on the bus and may be either the unique name
3607 * assigned by the bus to each connection, or a well-known name
3608 * specified in advance.
3610 * The destination name must contain only valid characters as defined
3611 * in the D-Bus specification.
3613 * @param message the message
3614 * @param destination the destination name or #NULL to unset
3615 * @returns #FALSE if not enough memory
3618 dbus_message_set_destination (DBusMessage *message,
3619 const char *destination)
3621 _dbus_return_val_if_fail (message != NULL, FALSE);
3622 _dbus_return_val_if_fail (!message->locked, FALSE);
3623 _dbus_return_val_if_fail (destination == NULL ||
3624 _dbus_check_is_valid_bus_name (destination),
3627 return set_or_delete_string_field (message,
3628 DBUS_HEADER_FIELD_DESTINATION,
3634 * Gets the destination of a message or #NULL if there is none set.
3636 * The returned string becomes invalid if the message is
3637 * modified, since it points into the wire-marshaled message data.
3639 * @param message the message
3640 * @returns the message destination (should not be freed) or #NULL
3643 dbus_message_get_destination (DBusMessage *message)
3647 _dbus_return_val_if_fail (message != NULL, NULL);
3649 v = NULL; /* in case field doesn't exist */
3650 _dbus_header_get_field_basic (&message->header,
3651 DBUS_HEADER_FIELD_DESTINATION,
3658 * Sets the message sender.
3660 * The sender must be a valid bus name as defined in the D-Bus
3663 * Usually you don't want to call this. The message bus daemon will
3664 * call it to set the origin of each message. If you aren't implementing
3665 * a message bus daemon you shouldn't need to set the sender.
3667 * @param message the message
3668 * @param sender the sender or #NULL to unset
3669 * @returns #FALSE if not enough memory
3672 dbus_message_set_sender (DBusMessage *message,
3675 _dbus_return_val_if_fail (message != NULL, FALSE);
3676 _dbus_return_val_if_fail (!message->locked, FALSE);
3677 _dbus_return_val_if_fail (sender == NULL ||
3678 _dbus_check_is_valid_bus_name (sender),
3681 return set_or_delete_string_field (message,
3682 DBUS_HEADER_FIELD_SENDER,
3688 * Gets the unique name of the connection which originated this
3689 * message, or #NULL if unknown or inapplicable. The sender is filled
3690 * in by the message bus.
3692 * Note, the returned sender is always the unique bus name.
3693 * Connections may own multiple other bus names, but those
3694 * are not found in the sender field.
3696 * The returned string becomes invalid if the message is
3697 * modified, since it points into the wire-marshaled message data.
3699 * @param message the message
3700 * @returns the unique name of the sender or #NULL
3703 dbus_message_get_sender (DBusMessage *message)
3707 _dbus_return_val_if_fail (message != NULL, NULL);
3709 if (NULL != message->unique_sender)
3710 return _dbus_string_get_const_data (message->unique_sender);
3712 v = NULL; /* in case field doesn't exist */
3713 _dbus_header_get_field_basic (&message->header,
3714 DBUS_HEADER_FIELD_SENDER,
3721 * Gets the type signature of the message, i.e. the arguments in the
3722 * message payload. The signature includes only "in" arguments for
3723 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
3724 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
3725 * what you might expect (that is, it does not include the signature of the
3726 * entire C++-style method).
3728 * The signature is a string made up of type codes such as
3729 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
3730 * the value of #DBUS_TYPE_INVALID).
3732 * The returned string becomes invalid if the message is
3733 * modified, since it points into the wire-marshaled message data.
3735 * @param message the message
3736 * @returns the type signature
3739 dbus_message_get_signature (DBusMessage *message)
3741 const DBusString *type_str;
3744 _dbus_return_val_if_fail (message != NULL, NULL);
3746 get_const_signature (message, &type_str, &type_pos);
3748 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
3752 _dbus_message_has_type_interface_member (DBusMessage *message,
3759 _dbus_assert (message != NULL);
3760 _dbus_assert (iface != NULL);
3761 _dbus_assert (member != NULL);
3763 if (dbus_message_get_type (message) != type)
3766 /* Optimize by checking the short member name first
3767 * instead of the longer interface name
3770 n = dbus_message_get_member (message);
3772 if (n && strcmp (n, member) == 0)
3774 n = dbus_message_get_interface (message);
3776 if (n == NULL || strcmp (n, iface) == 0)
3784 * Checks whether the message is a method call with the given
3785 * interface and member fields. If the message is not
3786 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
3787 * member field, returns #FALSE. If the interface field is missing,
3788 * then it will be assumed equal to the provided interface. The D-Bus
3789 * protocol allows method callers to leave out the interface name.
3791 * @param message the message
3792 * @param iface the name to check (must not be #NULL)
3793 * @param method the name to check (must not be #NULL)
3795 * @returns #TRUE if the message is the specified method call
3798 dbus_message_is_method_call (DBusMessage *message,
3802 _dbus_return_val_if_fail (message != NULL, FALSE);
3803 _dbus_return_val_if_fail (iface != NULL, FALSE);
3804 _dbus_return_val_if_fail (method != NULL, FALSE);
3805 /* don't check that interface/method are valid since it would be
3806 * expensive, and not catch many common errors
3809 return _dbus_message_has_type_interface_member (message,
3810 DBUS_MESSAGE_TYPE_METHOD_CALL,
3815 * Checks whether the message is a signal with the given interface and
3816 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
3817 * has a different interface or member field, returns #FALSE.
3819 * @param message the message
3820 * @param iface the name to check (must not be #NULL)
3821 * @param signal_name the name to check (must not be #NULL)
3823 * @returns #TRUE if the message is the specified signal
3826 dbus_message_is_signal (DBusMessage *message,
3828 const char *signal_name)
3830 _dbus_return_val_if_fail (message != NULL, FALSE);
3831 _dbus_return_val_if_fail (iface != NULL, FALSE);
3832 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
3833 /* don't check that interface/name are valid since it would be
3834 * expensive, and not catch many common errors
3837 return _dbus_message_has_type_interface_member (message,
3838 DBUS_MESSAGE_TYPE_SIGNAL,
3839 iface, signal_name);
3843 * Checks whether the message is an error reply with the given error
3844 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
3845 * different name, returns #FALSE.
3847 * @param message the message
3848 * @param error_name the name to check (must not be #NULL)
3850 * @returns #TRUE if the message is the specified error
3853 dbus_message_is_error (DBusMessage *message,
3854 const char *error_name)
3858 _dbus_return_val_if_fail (message != NULL, FALSE);
3859 _dbus_return_val_if_fail (error_name != NULL, FALSE);
3860 /* don't check that error_name is valid since it would be expensive,
3861 * and not catch many common errors
3864 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
3867 n = dbus_message_get_error_name (message);
3869 if (n && strcmp (n, error_name) == 0)
3876 * Checks whether the message was sent to the given name. If the
3877 * message has no destination specified or has a different
3878 * destination, returns #FALSE.
3880 * @param message the message
3881 * @param name the name to check (must not be #NULL)
3883 * @returns #TRUE if the message has the given destination name
3886 dbus_message_has_destination (DBusMessage *message,
3891 _dbus_return_val_if_fail (message != NULL, FALSE);
3892 _dbus_return_val_if_fail (name != NULL, FALSE);
3893 /* don't check that name is valid since it would be expensive, and
3894 * not catch many common errors
3897 s = dbus_message_get_destination (message);
3899 if (s && strcmp (s, name) == 0)
3906 * Checks whether the message has the given unique name as its sender.
3907 * If the message has no sender specified or has a different sender,
3908 * returns #FALSE. Note that a peer application will always have the
3909 * unique name of the connection as the sender. So you can't use this
3910 * function to see whether a sender owned a well-known name.
3912 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
3915 * @param message the message
3916 * @param name the name to check (must not be #NULL)
3918 * @returns #TRUE if the message has the given sender
3921 dbus_message_has_sender (DBusMessage *message,
3926 _dbus_return_val_if_fail (message != NULL, FALSE);
3927 _dbus_return_val_if_fail (name != NULL, FALSE);
3928 /* don't check that name is valid since it would be expensive, and
3929 * not catch many common errors
3932 s = dbus_message_get_sender (message);
3934 if (s && strcmp (s, name) == 0)
3941 * Checks whether the message has the given signature; see
3942 * dbus_message_get_signature() for more details on what the signature
3945 * @param message the message
3946 * @param signature typecode array
3947 * @returns #TRUE if message has the given signature
3950 dbus_message_has_signature (DBusMessage *message,
3951 const char *signature)
3955 _dbus_return_val_if_fail (message != NULL, FALSE);
3956 _dbus_return_val_if_fail (signature != NULL, FALSE);
3957 /* don't check that signature is valid since it would be expensive,
3958 * and not catch many common errors
3961 s = dbus_message_get_signature (message);
3963 if (s && strcmp (s, signature) == 0)
3970 * Sets a #DBusError based on the contents of the given
3971 * message. The error is only set if the message
3972 * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
3973 * The name of the error is set to the name of the message,
3974 * and the error message is set to the first argument
3975 * if the argument exists and is a string.
3977 * The return value indicates whether the error was set (the error is
3978 * set if and only if the message is an error message). So you can
3979 * check for an error reply and convert it to DBusError in one go:
3981 * if (dbus_set_error_from_message (error, reply))
3987 * @param error the error to set
3988 * @param message the message to set it from
3989 * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
3992 dbus_set_error_from_message (DBusError *error,
3993 DBusMessage *message)
3997 _dbus_return_val_if_fail (message != NULL, FALSE);
3998 _dbus_return_val_if_error_is_set (error, FALSE);
4000 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
4004 dbus_message_get_args (message, NULL,
4005 DBUS_TYPE_STRING, &str,
4008 dbus_set_error (error, dbus_message_get_error_name (message),
4009 str ? "%s" : NULL, str);
4015 * Checks whether a message contains unix fds
4017 * @param message the message
4018 * @returns #TRUE if the message contains unix fds
4021 dbus_message_contains_unix_fds(DBusMessage *message)
4023 #ifdef HAVE_UNIX_FD_PASSING
4024 _dbus_assert(message);
4026 return message->n_unix_fds > 0;
4035 * @addtogroup DBusMessageInternals
4041 * The initial buffer size of the message loader.
4043 * @todo this should be based on min header size plus some average
4044 * body size, or something. Or rather, the min header size only, if we
4045 * want to try to read only the header, store that in a DBusMessage,
4046 * then read only the body and store that, etc., depends on
4047 * how we optimize _dbus_message_loader_get_buffer() and what
4048 * the exact message format is.
4050 #define INITIAL_LOADER_DATA_LEN 32
4053 * Creates a new message loader. Returns #NULL if memory can't
4056 * @returns new loader, or #NULL.
4059 _dbus_message_loader_new (void)
4061 DBusMessageLoader *loader;
4063 loader = dbus_new0 (DBusMessageLoader, 1);
4067 loader->refcount = 1;
4069 loader->corrupted = FALSE;
4070 loader->corruption_reason = DBUS_VALID;
4072 /* this can be configured by the app, but defaults to the protocol max */
4073 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4075 /* We set a very relatively conservative default here since due to how
4076 SCM_RIGHTS works we need to preallocate an fd array of the maximum
4077 number of unix fds we want to receive in advance. A
4078 try-and-reallocate loop is not possible. */
4079 loader->max_message_unix_fds = DBUS_DEFAULT_MESSAGE_UNIX_FDS;
4081 if (!_dbus_string_init (&loader->data))
4087 /* preallocate the buffer for speed, ignore failure */
4088 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
4089 _dbus_string_set_length (&loader->data, 0);
4091 #ifdef HAVE_UNIX_FD_PASSING
4092 loader->unix_fds = NULL;
4093 loader->n_unix_fds = loader->n_unix_fds_allocated = 0;
4094 loader->unix_fds_outstanding = FALSE;
4101 * Increments the reference count of the loader.
4103 * @param loader the loader.
4104 * @returns the loader
4107 _dbus_message_loader_ref (DBusMessageLoader *loader)
4109 loader->refcount += 1;
4115 * Decrements the reference count of the loader and finalizes the
4116 * loader when the count reaches zero.
4118 * @param loader the loader.
4121 _dbus_message_loader_unref (DBusMessageLoader *loader)
4123 loader->refcount -= 1;
4124 if (loader->refcount == 0)
4126 #ifdef HAVE_UNIX_FD_PASSING
4127 close_unix_fds(loader->unix_fds, &loader->n_unix_fds);
4128 dbus_free(loader->unix_fds);
4130 _dbus_list_foreach (&loader->messages,
4131 (DBusForeachFunction) dbus_message_unref,
4133 _dbus_list_clear (&loader->messages);
4134 _dbus_string_free (&loader->data);
4140 * Gets the buffer to use for reading data from the network. Network
4141 * data is read directly into an allocated buffer, which is then used
4142 * in the DBusMessage, to avoid as many extra memcpy's as possible.
4143 * The buffer must always be returned immediately using
4144 * _dbus_message_loader_return_buffer(), even if no bytes are
4145 * successfully read.
4147 * @todo this function can be a lot more clever. For example
4148 * it can probably always return a buffer size to read exactly
4149 * the body of the next message, thus avoiding any memory wastage
4152 * @todo we need to enforce a max length on strings in header fields.
4154 * @param loader the message loader.
4155 * @param buffer the buffer
4158 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
4159 DBusString **buffer)
4161 _dbus_assert (!loader->buffer_outstanding);
4163 *buffer = &loader->data;
4165 loader->buffer_outstanding = TRUE;
4169 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
4170 * indicating to the loader how many bytes of the buffer were filled
4171 * in. This function must always be called, even if no bytes were
4172 * successfully read.
4174 * @param loader the loader.
4175 * @param buffer the buffer.
4178 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
4181 _dbus_assert (loader->buffer_outstanding);
4182 _dbus_assert (buffer == &loader->data);
4184 loader->buffer_outstanding = FALSE;
4188 * Gets the buffer to use for reading unix fds from the network.
4190 * This works similar to _dbus_message_loader_get_buffer()
4192 * @param loader the message loader.
4193 * @param fds the array to read fds into
4194 * @param max_n_fds how many fds to read at most
4195 * @return TRUE on success, FALSE on OOM
4198 _dbus_message_loader_get_unix_fds(DBusMessageLoader *loader,
4200 unsigned *max_n_fds)
4202 #ifdef HAVE_UNIX_FD_PASSING
4203 _dbus_assert (!loader->unix_fds_outstanding);
4205 /* Allocate space where we can put the fds we read. We allocate
4206 space for max_message_unix_fds since this is an
4207 upper limit how many fds can be received within a single
4208 message. Since SCM_RIGHTS doesn't allow a reallocate+retry logic
4209 we are allocating the maximum possible array size right from the
4210 beginning. This sucks a bit, however unless SCM_RIGHTS is fixed
4211 there is no better way. */
4213 if (loader->n_unix_fds_allocated < loader->max_message_unix_fds)
4215 int *a = dbus_realloc(loader->unix_fds,
4216 loader->max_message_unix_fds * sizeof(loader->unix_fds[0]));
4221 loader->unix_fds = a;
4222 loader->n_unix_fds_allocated = loader->max_message_unix_fds;
4225 *fds = loader->unix_fds + loader->n_unix_fds;
4226 *max_n_fds = loader->n_unix_fds_allocated - loader->n_unix_fds;
4228 loader->unix_fds_outstanding = TRUE;
4231 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
4237 * Returns a buffer obtained from _dbus_message_loader_get_unix_fds().
4239 * This works similar to _dbus_message_loader_return_buffer()
4241 * @param loader the message loader.
4242 * @param fds the array fds were read into
4243 * @param n_fds how many fds were read
4247 _dbus_message_loader_return_unix_fds(DBusMessageLoader *loader,
4251 #ifdef HAVE_UNIX_FD_PASSING
4252 _dbus_assert(loader->unix_fds_outstanding);
4253 _dbus_assert(loader->unix_fds + loader->n_unix_fds == fds);
4254 _dbus_assert(loader->n_unix_fds + n_fds <= loader->n_unix_fds_allocated);
4256 loader->n_unix_fds += n_fds;
4257 loader->unix_fds_outstanding = FALSE;
4259 if (n_fds && loader->unix_fds_change)
4260 loader->unix_fds_change (loader->unix_fds_change_data);
4262 _dbus_assert_not_reached("Platform doesn't support unix fd passing");
4267 * FIXME when we move the header out of the buffer, that memmoves all
4268 * buffered messages. Kind of crappy.
4270 * Also we copy the header and body, which is kind of crappy. To
4271 * avoid this, we have to allow header and body to be in a single
4272 * memory block, which is good for messages we read and bad for
4273 * messages we are creating. But we could move_len() the buffer into
4274 * this single memory block, and move_len() will just swap the buffers
4275 * if you're moving the entire buffer replacing the dest string.
4277 * We could also have the message loader tell the transport how many
4278 * bytes to read; so it would first ask for some arbitrary number like
4279 * 256, then if the message was incomplete it would use the
4280 * header/body len to ask for exactly the size of the message (or
4281 * blocks the size of a typical kernel buffer for the socket). That
4282 * way we don't get trailing bytes in the buffer that have to be
4283 * memmoved. Though I suppose we also don't have a chance of reading a
4284 * bunch of small messages at once, so the optimization may be stupid.
4286 * Another approach would be to keep a "start" index into
4287 * loader->data and only delete it occasionally, instead of after
4288 * each message is loaded.
4290 * load_message() returns FALSE if not enough memory OR the loader was corrupted
4293 load_message (DBusMessageLoader *loader,
4294 DBusMessage *message,
4296 int fields_array_len,
4301 DBusValidity validity;
4302 const DBusString *type_str;
4304 DBusValidationMode mode;
4305 dbus_uint32_t n_unix_fds = 0;
4307 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
4312 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
4315 /* 1. VALIDATE AND COPY OVER HEADER */
4316 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
4317 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
4319 if (!_dbus_header_load (&message->header,
4327 _dbus_string_get_length (&loader->data)))
4329 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
4331 /* assert here so we can catch any code that still uses DBUS_VALID to indicate
4332 oom errors. They should use DBUS_VALIDITY_UNKNOWN_OOM_ERROR instead */
4333 _dbus_assert (validity != DBUS_VALID);
4335 if (validity == DBUS_VALIDITY_UNKNOWN_OOM_ERROR)
4339 loader->corrupted = TRUE;
4340 loader->corruption_reason = validity;
4345 _dbus_assert (validity == DBUS_VALID);
4347 /* 2. VALIDATE BODY */
4348 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
4350 if (_dbus_message_is_gvariant (message))
4354 validity = _dbus_validate_gvariant_body_with_reason (type_str,
4365 get_const_signature (message, &type_str, &type_pos);
4367 /* Because the bytes_remaining arg is NULL, this validates that the
4368 * body is the right length
4371 validity = _dbus_validate_body_with_reason (type_str,
4379 if (validity != DBUS_VALID)
4381 _dbus_verbose ("Failed to validate message body code %d\n", validity);
4383 loader->corrupted = TRUE;
4384 loader->corruption_reason = validity;
4390 /* 3. COPY OVER UNIX FDS */
4391 _dbus_header_get_field_basic(&message->header,
4392 DBUS_HEADER_FIELD_UNIX_FDS,
4396 #ifdef HAVE_UNIX_FD_PASSING
4398 if (n_unix_fds > loader->n_unix_fds)
4400 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
4401 n_unix_fds, loader->n_unix_fds);
4403 loader->corrupted = TRUE;
4404 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4408 /* If this was a recycled message there might still be
4409 some memory allocated for the fds */
4410 dbus_free(message->unix_fds);
4414 message->unix_fds = _dbus_memdup(loader->unix_fds, n_unix_fds * sizeof(message->unix_fds[0]));
4415 if (message->unix_fds == NULL)
4417 _dbus_verbose ("Failed to allocate file descriptor array\n");
4422 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
4423 loader->n_unix_fds -= n_unix_fds;
4424 memmove (loader->unix_fds, loader->unix_fds + n_unix_fds, loader->n_unix_fds * sizeof (loader->unix_fds[0]));
4426 if (loader->unix_fds_change)
4427 loader->unix_fds_change (loader->unix_fds_change_data);
4430 message->unix_fds = NULL;
4436 _dbus_verbose ("Hmm, message claims to come with file descriptors "
4437 "but that's not supported on our platform, disconnecting.\n");
4439 loader->corrupted = TRUE;
4440 loader->corruption_reason = DBUS_INVALID_MISSING_UNIX_FDS;
4446 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
4448 if (!_dbus_list_append (&loader->messages, message))
4450 _dbus_verbose ("Failed to append new message to loader queue\n");
4455 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
4456 _dbus_assert (_dbus_string_get_length (&loader->data) >=
4457 (header_len + body_len));
4459 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
4461 _dbus_verbose ("Failed to move body into new message\n");
4466 _dbus_string_delete (&loader->data, 0, header_len + body_len);
4468 /* don't waste more than 2k of memory */
4469 _dbus_string_compact (&loader->data, 2048);
4471 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
4472 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
4474 _dbus_verbose ("Loaded message %p\n", message);
4476 _dbus_assert (!oom);
4477 _dbus_assert (!loader->corrupted);
4478 _dbus_assert (loader->messages != NULL);
4479 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4487 /* does nothing if the message isn't in the list */
4488 _dbus_list_remove_last (&loader->messages, message);
4491 _dbus_assert (!loader->corrupted);
4493 _dbus_assert (loader->corrupted);
4495 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
4501 set_unique_sender (DBusMessage *message, uint64_t unique_sender_id)
4503 if (NULL == message->unique_sender)
4505 message->unique_sender = dbus_new (DBusString, 1);
4506 if (NULL == message->unique_sender)
4509 if (!_dbus_string_init (message->unique_sender))
4513 _dbus_string_set_length (message->unique_sender, 0);
4515 if (!_dbus_string_append_printf (message->unique_sender, ":1.%llu", (unsigned long long)unique_sender_id))
4517 _dbus_string_free (message->unique_sender);
4518 dbus_free (message->unique_sender);
4519 message->unique_sender = NULL;
4527 * Converts buffered data into messages, if we have enough data. If
4528 * we don't have enough data, does nothing.
4530 * @todo we need to check that the proper named header fields exist
4531 * for each message type.
4533 * @todo If a message has unknown type, we should probably eat it
4534 * right here rather than passing it out to applications. However
4535 * it's not an error to see messages of unknown type.
4537 * @param loader the loader.
4538 * @returns #TRUE if we had enough memory to finish.
4541 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
4543 while (!loader->corrupted &&
4544 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
4546 DBusValidity validity;
4547 int byte_order, fields_array_len, header_len, body_len;
4548 dbus_bool_t is_gvariant;
4550 if (_dbus_header_have_message_untrusted (loader->max_message_size,
4557 _dbus_string_get_length (&loader->data),
4560 DBusMessage *message;
4562 _dbus_assert (validity == DBUS_VALID);
4564 message = dbus_message_new_empty_header (is_gvariant);
4565 if (message == NULL)
4568 if (!load_message (loader, message,
4569 byte_order, fields_array_len,
4570 header_len, body_len))
4572 dbus_message_unref (message);
4573 /* load_message() returns false if corrupted or OOM; if
4574 * corrupted then return TRUE for not OOM
4576 return loader->corrupted;
4579 if (_dbus_message_is_gvariant (message))
4581 set_unique_sender (message, _dbus_message_loader_get_unique_sender_id (loader));
4582 message->locked = TRUE;
4585 _dbus_assert (loader->messages != NULL);
4586 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
4590 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
4592 if (validity != DBUS_VALID)
4594 loader->corrupted = TRUE;
4595 loader->corruption_reason = validity;
4605 _dbus_decode_kmsg (DBusString *data,
4610 if (_dbus_string_get_length (data) >= DBUS_MINIMUM_HEADER_SIZE)
4613 DBusValidity validity;
4614 int byte_order, fields_array_len, header_len, body_len;
4615 dbus_bool_t is_gvariant;
4617 if (_dbus_header_have_message_untrusted (DBUS_MAXIMUM_MESSAGE_LENGTH,
4624 _dbus_string_get_length (data),
4627 DBusMessage *message;
4628 dbus_uint32_t n_unix_fds = 0;
4629 const DBusString *type_str = NULL;
4632 _dbus_assert (validity == DBUS_VALID);
4634 message = dbus_message_new_empty_header (is_gvariant);
4635 if (message == NULL)
4639 * Validate and copy over header
4641 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
4642 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (data));
4644 if (!_dbus_header_load (&message->header,
4645 DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED,
4652 _dbus_string_get_length (data)))
4654 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
4655 dbus_message_unref (message);
4659 _dbus_assert (validity == DBUS_VALID);
4664 if (_dbus_message_is_gvariant (message))
4666 validity = _dbus_validate_gvariant_body_with_reason (type_str,
4676 _dbus_verbose ("Not valid GVariant dbus message\n");
4677 dbus_message_unref (message);
4681 if (validity != DBUS_VALID)
4683 _dbus_verbose ("Failed to validate message body code %d\n", validity);
4684 dbus_message_unref (message);
4689 * Copy over Unix FDS
4691 _dbus_header_get_field_basic(&message->header,
4692 DBUS_HEADER_FIELD_UNIX_FDS,
4696 #ifdef HAVE_UNIX_FD_PASSING
4698 if (n_unix_fds > n_fds)
4700 _dbus_verbose("Message contains references to more unix fds than were sent %u != %u\n",
4701 n_unix_fds, message->n_unix_fds);
4702 dbus_message_unref (message);
4706 /* If this was a recycled message there might still be
4707 some memory allocated for the fds */
4708 dbus_free(message->unix_fds);
4712 message->unix_fds = _dbus_memdup(fds, n_unix_fds * sizeof(message->unix_fds[0]));
4713 if (message->unix_fds == NULL)
4715 _dbus_verbose ("Failed to allocate file descriptor array\n");
4716 dbus_message_unref (message);
4720 message->n_unix_fds_allocated = message->n_unix_fds = n_unix_fds;
4723 message->unix_fds = NULL;
4727 _dbus_verbose ("Hmm, message claims to come with file descriptors "
4728 "but that's not supported on our platform, disconnecting.\n");
4729 dbus_message_unref (message);
4735 * Copy over message body
4737 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
4738 _dbus_assert (_dbus_string_get_length (data) >= (header_len + body_len));
4740 if (!_dbus_string_copy_len (data, header_len, body_len, &message->body, 0))
4742 _dbus_verbose ("Failed to move body into new message\n");
4743 dbus_message_unref (message);
4747 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
4748 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
4750 set_unique_sender (message, sender_id);
4751 message->locked = TRUE;
4753 /* Yupi, we have DBusMessage* */
4758 _dbus_verbose ("Data broken with invalid code %d\n", validity);
4760 } /* if _dbus_header_have_message_untrusted() */
4765 _dbus_verbose ("message size < DBUS_MINIMUM_HEADER_SIZE\n");
4767 } /* if DBUS_MINIMUM_HEADER_SIZE */
4771 * Peeks at first loaded message, returns #NULL if no messages have
4774 * @param loader the loader.
4775 * @returns the next message, or #NULL if none.
4778 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
4780 if (loader->messages)
4781 return loader->messages->data;
4787 * Pops a loaded message (passing ownership of the message
4788 * to the caller). Returns #NULL if no messages have been
4791 * @param loader the loader.
4792 * @returns the next message, or #NULL if none.
4795 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
4797 return _dbus_list_pop_first (&loader->messages);
4801 * Pops a loaded message inside a list link (passing ownership of the
4802 * message and link to the caller). Returns #NULL if no messages have
4805 * @param loader the loader.
4806 * @returns the next message link, or #NULL if none.
4809 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
4811 return _dbus_list_pop_first_link (&loader->messages);
4815 * Returns a popped message link, used to undo a pop.
4817 * @param loader the loader
4818 * @param link the link with a message in it
4821 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
4824 _dbus_list_prepend_link (&loader->messages, link);
4828 * Checks whether the loader is confused due to bad data.
4829 * If messages are received that are invalid, the
4830 * loader gets confused and gives up permanently.
4831 * This state is called "corrupted."
4833 * @param loader the loader
4834 * @returns #TRUE if the loader is hosed.
4837 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
4839 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4840 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4841 return loader->corrupted;
4845 * Checks what kind of bad data confused the loader.
4847 * @param loader the loader
4848 * @returns why the loader is hosed, or DBUS_VALID if it isn't.
4851 _dbus_message_loader_get_corruption_reason (DBusMessageLoader *loader)
4853 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
4854 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
4856 return loader->corruption_reason;
4860 * Sets the maximum size message we allow.
4862 * @param loader the loader
4863 * @param size the max message size in bytes
4866 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
4869 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
4871 _dbus_verbose ("clamping requested max message size %ld to %d\n",
4872 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
4873 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
4875 loader->max_message_size = size;
4879 * Gets the maximum allowed message size in bytes.
4881 * @param loader the loader
4882 * @returns max size in bytes
4885 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
4887 return loader->max_message_size;
4891 * Sets the maximum unix fds per message we allow.
4893 * @param loader the loader
4894 * @param n the max number of unix fds in a message
4897 _dbus_message_loader_set_max_message_unix_fds (DBusMessageLoader *loader,
4900 if (n > DBUS_MAXIMUM_MESSAGE_UNIX_FDS)
4902 _dbus_verbose ("clamping requested max message unix_fds %ld to %d\n",
4903 n, DBUS_MAXIMUM_MESSAGE_UNIX_FDS);
4904 n = DBUS_MAXIMUM_MESSAGE_UNIX_FDS;
4906 loader->max_message_unix_fds = n;
4910 * Gets the maximum allowed number of unix fds per message
4912 * @param loader the loader
4913 * @returns max unix fds
4916 _dbus_message_loader_get_max_message_unix_fds (DBusMessageLoader *loader)
4918 return loader->max_message_unix_fds;
4922 * Return how many file descriptors are pending in the loader
4924 * @param loader the loader
4927 _dbus_message_loader_get_pending_fds_count (DBusMessageLoader *loader)
4929 #ifdef HAVE_UNIX_FD_PASSING
4930 return loader->n_unix_fds;
4937 * Register a function to be called whenever the number of pending file
4938 * descriptors in the loader change.
4940 * @param loader the loader
4941 * @param callback the callback
4942 * @param data the data for the callback
4945 _dbus_message_loader_set_pending_fds_function (DBusMessageLoader *loader,
4946 void (* callback) (void *),
4949 #ifdef HAVE_UNIX_FD_PASSING
4950 loader->unix_fds_change = callback;
4951 loader->unix_fds_change_data = data;
4956 _dbus_message_loader_set_unique_sender_id (DBusMessageLoader *loader,
4959 loader->unique_sender_id = id;
4963 _dbus_message_loader_get_unique_sender_id (DBusMessageLoader *loader)
4965 return loader->unique_sender_id;
4968 static DBusDataSlotAllocator slot_allocator =
4969 _DBUS_DATA_SLOT_ALLOCATOR_INIT (_DBUS_LOCK_NAME (message_slots));
4972 * Allocates an integer ID to be used for storing application-specific
4973 * data on any DBusMessage. The allocated ID may then be used
4974 * with dbus_message_set_data() and dbus_message_get_data().
4975 * The passed-in slot must be initialized to -1, and is filled in
4976 * with the slot ID. If the passed-in slot is not -1, it's assumed
4977 * to be already allocated, and its refcount is incremented.
4979 * The allocated slot is global, i.e. all DBusMessage objects will
4980 * have a slot with the given integer ID reserved.
4982 * @param slot_p address of a global variable storing the slot
4983 * @returns #FALSE on failure (no memory)
4986 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
4988 return _dbus_data_slot_allocator_alloc (&slot_allocator,
4993 * Deallocates a global ID for message data slots.
4994 * dbus_message_get_data() and dbus_message_set_data() may no
4995 * longer be used with this slot. Existing data stored on existing
4996 * DBusMessage objects will be freed when the message is
4997 * finalized, but may not be retrieved (and may only be replaced if
4998 * someone else reallocates the slot). When the refcount on the
4999 * passed-in slot reaches 0, it is set to -1.
5001 * @param slot_p address storing the slot to deallocate
5004 dbus_message_free_data_slot (dbus_int32_t *slot_p)
5006 _dbus_return_if_fail (*slot_p >= 0);
5008 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
5012 * Stores a pointer on a DBusMessage, along
5013 * with an optional function to be used for freeing
5014 * the data when the data is set again, or when
5015 * the message is finalized. The slot number
5016 * must have been allocated with dbus_message_allocate_data_slot().
5018 * @param message the message
5019 * @param slot the slot number
5020 * @param data the data to store
5021 * @param free_data_func finalizer function for the data
5022 * @returns #TRUE if there was enough memory to store the data
5025 dbus_message_set_data (DBusMessage *message,
5028 DBusFreeFunction free_data_func)
5030 DBusFreeFunction old_free_func;
5034 _dbus_return_val_if_fail (message != NULL, FALSE);
5035 _dbus_return_val_if_fail (slot >= 0, FALSE);
5037 retval = _dbus_data_slot_list_set (&slot_allocator,
5038 &message->slot_list,
5039 slot, data, free_data_func,
5040 &old_free_func, &old_data);
5044 /* Do the actual free outside the message lock */
5046 (* old_free_func) (old_data);
5053 * Retrieves data previously set with dbus_message_set_data().
5054 * The slot must still be allocated (must not have been freed).
5056 * @param message the message
5057 * @param slot the slot to get data from
5058 * @returns the data, or #NULL if not found
5061 dbus_message_get_data (DBusMessage *message,
5066 _dbus_return_val_if_fail (message != NULL, NULL);
5068 res = _dbus_data_slot_list_get (&slot_allocator,
5069 &message->slot_list,
5076 * Utility function to convert a machine-readable (not translated)
5077 * string into a D-Bus message type.
5080 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
5081 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
5082 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
5083 * "error" -> DBUS_MESSAGE_TYPE_ERROR
5084 * anything else -> DBUS_MESSAGE_TYPE_INVALID
5089 dbus_message_type_from_string (const char *type_str)
5091 if (strcmp (type_str, "method_call") == 0)
5092 return DBUS_MESSAGE_TYPE_METHOD_CALL;
5093 if (strcmp (type_str, "method_return") == 0)
5094 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
5095 else if (strcmp (type_str, "signal") == 0)
5096 return DBUS_MESSAGE_TYPE_SIGNAL;
5097 else if (strcmp (type_str, "error") == 0)
5098 return DBUS_MESSAGE_TYPE_ERROR;
5100 return DBUS_MESSAGE_TYPE_INVALID;
5104 * Utility function to convert a D-Bus message type into a
5105 * machine-readable string (not translated).
5108 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
5109 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
5110 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
5111 * DBUS_MESSAGE_TYPE_ERROR -> "error"
5112 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
5117 dbus_message_type_to_string (int type)
5121 case DBUS_MESSAGE_TYPE_METHOD_CALL:
5122 return "method_call";
5123 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
5124 return "method_return";
5125 case DBUS_MESSAGE_TYPE_SIGNAL:
5127 case DBUS_MESSAGE_TYPE_ERROR:
5135 * Turn a DBusMessage into the marshalled form as described in the D-Bus
5138 * Generally, this function is only useful for encapsulating D-Bus messages in
5139 * a different protocol.
5141 * @param msg the DBusMessage
5142 * @param marshalled_data_p the location to save the marshalled form to
5143 * @param len_p the location to save the length of the marshalled form to
5144 * @returns #FALSE if there was not enough memory
5147 dbus_message_marshal (DBusMessage *msg,
5148 char **marshalled_data_p,
5152 dbus_bool_t was_locked;
5154 _dbus_return_val_if_fail (msg != NULL, FALSE);
5155 _dbus_return_val_if_fail (marshalled_data_p != NULL, FALSE);
5156 _dbus_return_val_if_fail (len_p != NULL, FALSE);
5158 if (!_dbus_string_init (&tmp))
5161 /* Ensure the message is locked, to ensure the length header is filled in. */
5162 was_locked = msg->locked;
5165 dbus_message_lock (msg);
5167 if (!_dbus_string_copy (&(msg->header.data), 0, &tmp, 0))
5170 *len_p = _dbus_string_get_length (&tmp);
5172 if (!_dbus_string_copy (&(msg->body), 0, &tmp, *len_p))
5175 *len_p = _dbus_string_get_length (&tmp);
5177 if (!_dbus_string_steal_data (&tmp, marshalled_data_p))
5180 _dbus_string_free (&tmp);
5183 msg->locked = FALSE;
5188 _dbus_string_free (&tmp);
5191 msg->locked = FALSE;
5197 * Demarshal a D-Bus message from the format described in the D-Bus
5200 * Generally, this function is only useful for encapsulating D-Bus messages in
5201 * a different protocol.
5203 * @param str the marshalled DBusMessage
5204 * @param len the length of str
5205 * @param error the location to save errors to
5206 * @returns #NULL if there was an error
5209 dbus_message_demarshal (const char *str,
5213 DBusMessageLoader *loader;
5217 _dbus_return_val_if_fail (str != NULL, NULL);
5219 loader = _dbus_message_loader_new ();
5224 _dbus_message_loader_get_buffer (loader, &buffer);
5226 if (!_dbus_string_append_len (buffer, str, len))
5229 _dbus_message_loader_return_buffer (loader, buffer);
5231 if (!_dbus_message_loader_queue_messages (loader))
5234 if (_dbus_message_loader_get_is_corrupted (loader))
5237 msg = _dbus_message_loader_pop_message (loader);
5242 _dbus_message_loader_unref (loader);
5246 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS, "Message is corrupted (%s)",
5247 _dbus_validity_to_error_message (loader->corruption_reason));
5248 _dbus_message_loader_unref (loader);
5252 _DBUS_SET_OOM (error);
5253 _dbus_message_loader_unref (loader);
5258 * Returns the number of bytes required to be in the buffer to demarshal a
5261 * Generally, this function is only useful for encapsulating D-Bus messages in
5262 * a different protocol.
5264 * @param buf data to be marshalled
5265 * @param len the length of @p buf
5266 * @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
5270 dbus_message_demarshal_bytes_needed(const char *buf,
5274 int byte_order, fields_array_len, header_len, body_len;
5275 DBusValidity validity = DBUS_VALID;
5277 dbus_bool_t is_gvariant;
5279 if (!buf || len < DBUS_MINIMUM_HEADER_SIZE)
5282 if (len > DBUS_MAXIMUM_MESSAGE_LENGTH)
5283 len = DBUS_MAXIMUM_MESSAGE_LENGTH;
5284 _dbus_string_init_const_len (&str, buf, len);
5286 validity = DBUS_VALID;
5288 = _dbus_header_have_message_untrusted(DBUS_MAXIMUM_MESSAGE_LENGTH,
5289 &validity, &byte_order,
5296 _dbus_string_free (&str);
5298 if (validity == DBUS_VALID)
5300 _dbus_assert (have_message || (header_len + body_len) > len);
5301 (void) have_message; /* unused unless asserting */
5302 return header_len + body_len;
5306 return -1; /* broken! */
5311 _dbus_message_copy_recursive(DBusMessageIter *iter, DBusMessageIter *dest)
5313 dbus_bool_t res = TRUE;
5316 while ((current_type = dbus_message_iter_get_arg_type (iter)) != DBUS_TYPE_INVALID) {
5317 if (dbus_type_is_basic(current_type)) {
5318 DBusBasicValue value;
5319 dbus_message_iter_get_basic (iter, &value);
5320 dbus_message_iter_append_basic (dest, current_type, &value);
5323 DBusMessageIter sub;
5324 DBusMessageIter dest_sub;
5327 dbus_message_iter_recurse (iter, &sub);
5328 if (DBUS_TYPE_VARIANT == current_type)
5329 sig = dbus_message_iter_get_signature (&sub);
5330 else if (DBUS_TYPE_ARRAY == current_type)
5331 sig = dbus_message_iter_get_signature (&sub);
5333 res = res && dbus_message_iter_open_container (dest, current_type, sig, &dest_sub);
5335 res = res && _dbus_message_copy_recursive (&sub, &dest_sub);
5336 res = res && dbus_message_iter_close_container (dest, &dest_sub);
5343 dbus_message_iter_next (iter);
5350 _dbus_on_new_bus (int type)
5352 _dbus_assert (type == DBUS_MAJOR_PROTOCOL_VERSION || type == DBUS_PROTOCOL_VERSION_GVARIANT);
5353 _dbus_protocol_strategy_bus_function (type);
5357 _dbus_on_send_message (int type)
5359 _dbus_assert (type == DBUS_MAJOR_PROTOCOL_VERSION || type == DBUS_PROTOCOL_VERSION_GVARIANT);
5360 _dbus_protocol_strategy_message_function (type);
5364 _dbus_message_remarshal (DBusMessage *message, dbus_bool_t gvariant)
5367 DBusMessageIter iter, ret_iter;
5369 dbus_uint32_t serial;
5372 _dbus_assert (message->locked);
5374 _dbus_on_send_message (gvariant ? DBUS_PROTOCOL_VERSION_GVARIANT : DBUS_MAJOR_PROTOCOL_VERSION);
5376 ret = _dbus_message_create_protocol_version (dbus_message_get_type(message),
5377 dbus_message_get_destination(message),
5378 dbus_message_get_path(message),
5379 dbus_message_get_interface(message),
5380 dbus_message_get_member(message),
5381 dbus_message_get_error_name(message),
5384 dbus_message_iter_init (message, &iter);
5385 dbus_message_iter_init_append (ret, &ret_iter);
5386 if (!_dbus_message_copy_recursive(&iter, &ret_iter))
5389 #ifdef HAVE_UNIX_FD_PASSING
5390 ret->unix_fds = dbus_new(int, message->n_unix_fds);
5391 if (ret->unix_fds == NULL && message->n_unix_fds > 0)
5394 ret->n_unix_fds_allocated = message->n_unix_fds;
5396 for (i = 0; i < message->n_unix_fds; ++i) {
5397 ret->unix_fds[i] = _dbus_dup(message->unix_fds[i], NULL);
5399 if (ret->unix_fds[i] < 0)
5403 ret->n_unix_fds = message->n_unix_fds;
5406 /* Remarshal data in header:
5407 byte order (already set)
5409 flags - only those we understand
5410 version (already set)
5413 fields array (length)
5416 interface (already set)
5417 member (already set)
5418 error name (already set)
5420 destination (already set)
5422 signature (set during copy, but an action needed for conversion to GVariant)
5427 _dbus_header_toggle_flag (&ret->header, DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
5428 _dbus_header_get_flag (&message->header, DBUS_HEADER_FLAG_NO_REPLY_EXPECTED));
5430 _dbus_header_toggle_flag (&ret->header, DBUS_HEADER_FLAG_NO_AUTO_START,
5431 _dbus_header_get_flag (&message->header, DBUS_HEADER_FLAG_NO_AUTO_START));
5433 /* SERIAL / COOKIE */
5434 serial = dbus_message_get_serial (message);
5437 dbus_message_set_serial (ret, serial);
5439 /* Field: REPLY_SERIAL */
5440 serial = dbus_message_get_reply_serial (message);
5442 if (0 != serial && !dbus_message_set_reply_serial (ret, serial))
5446 sender = dbus_message_get_sender (message);
5448 if (NULL != sender && !dbus_message_set_sender (ret, sender))
5453 _dbus_header_update_lengths (&ret->header,
5454 _dbus_string_get_length (&ret->body));
5456 /* Field: SIGNATURE to body; add body offset - this is done with dbus_message_lock() */
5458 dbus_message_lock (ret);
5463 _dbus_header_free (&ret->header);
5464 _dbus_string_free (&ret->body);
5466 #ifdef HAVE_UNIX_FD_PASSING
5467 close_unix_fds(ret->unix_fds, &ret->n_unix_fds);
5468 dbus_free(ret->unix_fds);
5475 dbus_set_protocol_version (unsigned char version)
5477 _dbus_default_protocol_version = version;
5481 protocol_strategy_first_type (int type)
5483 /* change protocol once */
5484 if (!_dbus_first_bus_open)
5486 _dbus_first_bus_open = TRUE;
5487 _dbus_default_protocol_version = type;
5492 protocol_strategy_last_type (int type)
5494 /* change protocol every time it is needed */
5495 if (_dbus_default_protocol_version != type)
5496 _dbus_default_protocol_version = type;
5500 protocol_strategy_static (int type)
5506 dbus_set_default_protocol_strategy (const char *strategy_name)
5508 if (strcmp (strategy_name, "first-bus") == 0)
5510 _dbus_protocol_strategy_bus_function = protocol_strategy_first_type;
5511 _dbus_protocol_strategy_message_function = protocol_strategy_static;
5513 else if (strcmp (strategy_name, "dbus1") == 0)
5515 _dbus_default_protocol_version = DBUS_MAJOR_PROTOCOL_VERSION;
5516 _dbus_protocol_strategy_bus_function = protocol_strategy_static;
5517 _dbus_protocol_strategy_message_function = protocol_strategy_static;
5519 else if (strcmp (strategy_name, "gvariant") == 0)
5521 _dbus_default_protocol_version = DBUS_PROTOCOL_VERSION_GVARIANT;
5522 _dbus_protocol_strategy_bus_function = protocol_strategy_static;
5523 _dbus_protocol_strategy_message_function = protocol_strategy_static;
5525 else if (strcmp (strategy_name, "last-message") == 0)
5527 _dbus_protocol_strategy_bus_function = protocol_strategy_static;
5528 _dbus_protocol_strategy_message_function = protocol_strategy_last_type;
5530 else /* "last-bus" is default strategy */
5532 _dbus_protocol_strategy_bus_function = protocol_strategy_last_type;
5533 _dbus_protocol_strategy_message_function = protocol_strategy_static;
5538 _dbus_generate_local_error_message (dbus_uint32_t serial,
5542 DBusMessage *message;
5543 message = dbus_message_new (DBUS_MESSAGE_TYPE_ERROR);
5547 if (!dbus_message_set_error_name (message, error_name))
5549 dbus_message_unref (message);
5554 dbus_message_set_no_reply (message, TRUE);
5556 if (!dbus_message_set_reply_serial (message,
5559 dbus_message_unref (message);
5564 if (error_msg != NULL)
5566 DBusMessageIter iter;
5568 dbus_message_iter_init_append (message, &iter);
5569 if (!dbus_message_iter_append_basic (&iter,
5573 dbus_message_unref (message);
5584 _dbus_message_assure_dbus1 (DBusMessage **message)
5586 if ((*message)->header.protocol_version != DBUS_MAJOR_PROTOCOL_VERSION)
5588 *message = _dbus_message_remarshal (*message, FALSE);
5595 _dbus_message_assure_gvariant (DBusMessage **message)
5597 if ((*message)->header.protocol_version != DBUS_PROTOCOL_VERSION_GVARIANT)
5599 *message = _dbus_message_remarshal (*message, TRUE);
5607 /* tests in dbus-message-util.c */