1 /* -*- mode: C; c-file-style: "gnu" -*- */
2 /* dbus-message.c DBusMessage object
4 * Copyright (C) 2002, 2003, 2004, 2005 Red Hat Inc.
5 * Copyright (C) 2002, 2003 CodeFactory AB
7 * Licensed under the Academic Free License version 2.1
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License
20 * along with this program; if not, write to the Free Software
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
25 #include "dbus-internals.h"
26 #include "dbus-marshal-recursive.h"
27 #include "dbus-marshal-validate.h"
28 #include "dbus-marshal-byteswap.h"
29 #include "dbus-marshal-header.h"
30 #include "dbus-signature.h"
31 #include "dbus-message-private.h"
32 #include "dbus-object-tree.h"
33 #include "dbus-memory.h"
34 #include "dbus-list.h"
38 * @defgroup DBusMessageInternals DBusMessage implementation details
39 * @ingroup DBusInternals
40 * @brief DBusMessage private implementation details.
42 * The guts of DBusMessage and its methods.
47 /* Not thread locked, but strictly const/read-only so should be OK
49 /** An static string representing an empty signature */
50 _DBUS_STRING_DEFINE_STATIC(_dbus_empty_signature_str, "");
52 /* these have wacky values to help trap uninitialized iterators;
53 * but has to fit in 3 bits
56 DBUS_MESSAGE_ITER_TYPE_READER = 3,
57 DBUS_MESSAGE_ITER_TYPE_WRITER = 7
60 /** typedef for internals of message iterator */
61 typedef struct DBusMessageRealIter DBusMessageRealIter;
64 * @brief Internals of DBusMessageIter
66 * Object representing a position in a message. All fields are internal.
68 struct DBusMessageRealIter
70 DBusMessage *message; /**< Message used */
71 dbus_uint32_t changed_stamp : CHANGED_STAMP_BITS; /**< stamp to detect invalid iters */
72 dbus_uint32_t iter_type : 3; /**< whether this is a reader or writer iter */
73 dbus_uint32_t sig_refcount : 8; /**< depth of open_signature() */
76 DBusTypeWriter writer; /**< writer */
77 DBusTypeReader reader; /**< reader */
78 } u; /**< the type writer or reader that does all the work */
82 get_const_signature (DBusHeader *header,
83 const DBusString **type_str_p,
86 if (_dbus_header_get_field_raw (header,
87 DBUS_HEADER_FIELD_SIGNATURE,
91 *type_pos_p += 1; /* skip the signature length which is 1 byte */
95 *type_str_p = &_dbus_empty_signature_str;
101 * Swaps the message to compiler byte order if required
103 * @param message the message
106 _dbus_message_byteswap (DBusMessage *message)
108 const DBusString *type_str;
111 if (message->byte_order == DBUS_COMPILER_BYTE_ORDER)
114 _dbus_verbose ("Swapping message into compiler byte order\n");
116 get_const_signature (&message->header, &type_str, &type_pos);
118 _dbus_marshal_byteswap (type_str, type_pos,
120 DBUS_COMPILER_BYTE_ORDER,
123 message->byte_order = DBUS_COMPILER_BYTE_ORDER;
125 _dbus_header_byteswap (&message->header, DBUS_COMPILER_BYTE_ORDER);
128 #define ensure_byte_order(message) \
129 if (message->byte_order != DBUS_COMPILER_BYTE_ORDER) \
130 _dbus_message_byteswap (message)
133 * Gets the data to be sent over the network for this message.
134 * The header and then the body should be written out.
135 * This function is guaranteed to always return the same
136 * data once a message is locked (with _dbus_message_lock()).
138 * @param message the message.
139 * @param header return location for message header data.
140 * @param body return location for message body data.
143 _dbus_message_get_network_data (DBusMessage *message,
144 const DBusString **header,
145 const DBusString **body)
147 _dbus_assert (message->locked);
149 *header = &message->header.data;
150 *body = &message->body;
154 * Sets the serial number of a message.
155 * This can only be done once on a message.
157 * @param message the message
158 * @param serial the serial
161 _dbus_message_set_serial (DBusMessage *message,
162 dbus_uint32_t serial)
164 _dbus_assert (message != NULL);
165 _dbus_assert (!message->locked);
166 _dbus_assert (dbus_message_get_serial (message) == 0);
168 _dbus_header_set_serial (&message->header, serial);
172 * Adds a counter to be incremented immediately with the
173 * size of this message, and decremented by the size
174 * of this message when this message if finalized.
175 * The link contains a counter with its refcount already
176 * incremented, but the counter itself not incremented.
177 * Ownership of link and counter refcount is passed to
180 * @param message the message
181 * @param link link with counter as data
184 _dbus_message_add_size_counter_link (DBusMessage *message,
187 /* right now we don't recompute the delta when message
188 * size changes, and that's OK for current purposes
189 * I think, but could be important to change later.
190 * Do recompute it whenever there are no outstanding counters,
191 * since it's basically free.
193 if (message->size_counters == NULL)
195 message->size_counter_delta =
196 _dbus_string_get_length (&message->header.data) +
197 _dbus_string_get_length (&message->body);
200 _dbus_verbose ("message has size %ld\n",
201 message->size_counter_delta);
205 _dbus_list_append_link (&message->size_counters, link);
207 _dbus_counter_adjust (link->data, message->size_counter_delta);
211 * Adds a counter to be incremented immediately with the
212 * size of this message, and decremented by the size
213 * of this message when this message if finalized.
215 * @param message the message
216 * @param counter the counter
217 * @returns #FALSE if no memory
220 _dbus_message_add_size_counter (DBusMessage *message,
221 DBusCounter *counter)
225 link = _dbus_list_alloc_link (counter);
229 _dbus_counter_ref (counter);
230 _dbus_message_add_size_counter_link (message, link);
236 * Removes a counter tracking the size of this message, and decrements
237 * the counter by the size of this message.
239 * @param message the message
240 * @param link_return return the link used
241 * @param counter the counter
244 _dbus_message_remove_size_counter (DBusMessage *message,
245 DBusCounter *counter,
246 DBusList **link_return)
250 link = _dbus_list_find_last (&message->size_counters,
252 _dbus_assert (link != NULL);
254 _dbus_list_unlink (&message->size_counters,
259 _dbus_list_free_link (link);
261 _dbus_counter_adjust (counter, - message->size_counter_delta);
263 _dbus_counter_unref (counter);
267 * Locks a message. Allows checking that applications don't keep a
268 * reference to a message in the outgoing queue and change it
269 * underneath us. Messages are locked when they enter the outgoing
270 * queue (dbus_connection_send_message()), and the library complains
271 * if the message is modified while locked.
273 * @param message the message to lock.
276 _dbus_message_lock (DBusMessage *message)
278 if (!message->locked)
280 _dbus_header_update_lengths (&message->header,
281 _dbus_string_get_length (&message->body));
283 /* must have a signature if you have a body */
284 _dbus_assert (_dbus_string_get_length (&message->body) == 0 ||
285 dbus_message_get_signature (message) != NULL);
287 message->locked = TRUE;
292 set_or_delete_string_field (DBusMessage *message,
298 return _dbus_header_delete_field (&message->header, field);
300 return _dbus_header_set_field_basic (&message->header,
307 /* Probably we don't need to use this */
309 * Sets the signature of the message, i.e. the arguments in the
310 * message payload. The signature includes only "in" arguments for
311 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
312 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
313 * what you might expect (it does not include the signature of the
314 * entire C++-style method).
316 * The signature is a string made up of type codes such as
317 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
318 * the value of #DBUS_TYPE_INVALID). The macros such as
319 * #DBUS_TYPE_INT32 evaluate to integers; to assemble a signature you
320 * may find it useful to use the string forms, such as
321 * #DBUS_TYPE_INT32_AS_STRING.
323 * An "unset" or #NULL signature is considered the same as an empty
324 * signature. In fact dbus_message_get_signature() will never return
327 * @param message the message
328 * @param signature the type signature or #NULL to unset
329 * @returns #FALSE if no memory
332 _dbus_message_set_signature (DBusMessage *message,
333 const char *signature)
335 _dbus_return_val_if_fail (message != NULL, FALSE);
336 _dbus_return_val_if_fail (!message->locked, FALSE);
337 _dbus_return_val_if_fail (signature == NULL ||
338 _dbus_check_is_valid_signature (signature));
339 /* can't delete the signature if you have a message body */
340 _dbus_return_val_if_fail (_dbus_string_get_length (&message->body) == 0 ||
343 return set_or_delete_string_field (message,
344 DBUS_HEADER_FIELD_SIGNATURE,
353 * @defgroup DBusMessage DBusMessage
355 * @brief Message to be sent or received over a DBusConnection.
357 * A DBusMessage is the most basic unit of communication over a
358 * DBusConnection. A DBusConnection represents a stream of messages
359 * received from a remote application, and a stream of messages
360 * sent to a remote application.
366 * @typedef DBusMessage
368 * Opaque data type representing a message received from or to be
369 * sent to another application.
373 * Returns the serial of a message or 0 if none has been specified.
374 * The message's serial number is provided by the application sending
375 * the message and is used to identify replies to this message. All
376 * messages received on a connection will have a serial, but messages
377 * you haven't sent yet may return 0.
379 * @param message the message
380 * @returns the client serial
383 dbus_message_get_serial (DBusMessage *message)
385 _dbus_return_val_if_fail (message != NULL, 0);
387 return _dbus_header_get_serial (&message->header);
391 * Sets the reply serial of a message (the client serial
392 * of the message this is a reply to).
394 * @param message the message
395 * @param reply_serial the client serial
396 * @returns #FALSE if not enough memory
399 dbus_message_set_reply_serial (DBusMessage *message,
400 dbus_uint32_t reply_serial)
402 _dbus_return_val_if_fail (message != NULL, FALSE);
403 _dbus_return_val_if_fail (!message->locked, FALSE);
405 return _dbus_header_set_field_basic (&message->header,
406 DBUS_HEADER_FIELD_REPLY_SERIAL,
412 * Returns the serial that the message is a reply to or 0 if none.
414 * @param message the message
415 * @returns the reply serial
418 dbus_message_get_reply_serial (DBusMessage *message)
420 dbus_uint32_t v_UINT32;
422 _dbus_return_val_if_fail (message != NULL, 0);
424 if (_dbus_header_get_field_basic (&message->header,
425 DBUS_HEADER_FIELD_REPLY_SERIAL,
434 free_size_counter (void *element,
437 DBusCounter *counter = element;
438 DBusMessage *message = data;
440 _dbus_counter_adjust (counter, - message->size_counter_delta);
442 _dbus_counter_unref (counter);
446 dbus_message_finalize (DBusMessage *message)
448 _dbus_assert (message->refcount.value == 0);
450 /* This calls application callbacks! */
451 _dbus_data_slot_list_free (&message->slot_list);
453 _dbus_list_foreach (&message->size_counters,
454 free_size_counter, message);
455 _dbus_list_clear (&message->size_counters);
457 _dbus_header_free (&message->header);
458 _dbus_string_free (&message->body);
460 _dbus_assert (message->refcount.value == 0);
467 * We cache some DBusMessage to reduce the overhead of allocating
468 * them. In my profiling this consistently made about an 8%
469 * difference. It avoids the malloc for the message, the malloc for
470 * the slot list, the malloc for the header string and body string,
471 * and the associated free() calls. It does introduce another global
472 * lock which could be a performance issue in certain cases.
474 * For the echo client/server the round trip time goes from around
475 * .000077 to .000069 with the message cache on my laptop. The sysprof
476 * change is as follows (numbers are cumulative percentage):
478 * with message cache implemented as array as it is now (0.000069 per):
479 * new_empty_header 1.46
480 * mutex_lock 0.56 # i.e. _DBUS_LOCK(message_cache)
486 * mutex_lock 0.33 # i.e. _DBUS_LOCK(message_cache)
489 * with message cache implemented as list (0.000070 per roundtrip):
490 * new_empty_header 2.72
491 * list_pop_first 1.88
495 * without cache (0.000077 per roundtrip):
496 * new_empty_header 6.7
497 * string_init_preallocated 3.43
506 * If you implement the message_cache with a list, the primary reason
507 * it's slower is that you add another thread lock (on the DBusList
511 /** Avoid caching huge messages */
512 #define MAX_MESSAGE_SIZE_TO_CACHE _DBUS_ONE_MEGABYTE
514 /** Avoid caching too many messages */
515 #define MAX_MESSAGE_CACHE_SIZE 5
517 _DBUS_DEFINE_GLOBAL_LOCK (message_cache);
518 static DBusMessage *message_cache[MAX_MESSAGE_CACHE_SIZE];
519 static int message_cache_count = 0;
520 static dbus_bool_t message_cache_shutdown_registered = FALSE;
523 dbus_message_cache_shutdown (void *data)
527 _DBUS_LOCK (message_cache);
530 while (i < MAX_MESSAGE_CACHE_SIZE)
532 if (message_cache[i])
533 dbus_message_finalize (message_cache[i]);
538 message_cache_count = 0;
539 message_cache_shutdown_registered = FALSE;
541 _DBUS_UNLOCK (message_cache);
545 * Tries to get a message from the message cache. The retrieved
546 * message will have junk in it, so it still needs to be cleared out
547 * in dbus_message_new_empty_header()
549 * @returns the message, or #NULL if none cached
552 dbus_message_get_cached (void)
554 DBusMessage *message;
559 _DBUS_LOCK (message_cache);
561 _dbus_assert (message_cache_count >= 0);
563 if (message_cache_count == 0)
565 _DBUS_UNLOCK (message_cache);
569 /* This is not necessarily true unless count > 0, and
570 * message_cache is uninitialized until the shutdown is
573 _dbus_assert (message_cache_shutdown_registered);
576 while (i < MAX_MESSAGE_CACHE_SIZE)
578 if (message_cache[i])
580 message = message_cache[i];
581 message_cache[i] = NULL;
582 message_cache_count -= 1;
587 _dbus_assert (message_cache_count >= 0);
588 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
589 _dbus_assert (message != NULL);
591 _DBUS_UNLOCK (message_cache);
593 _dbus_assert (message->refcount.value == 0);
594 _dbus_assert (message->size_counters == NULL);
600 * Tries to cache a message, otherwise finalize it.
602 * @param message the message
605 dbus_message_cache_or_finalize (DBusMessage *message)
607 dbus_bool_t was_cached;
610 _dbus_assert (message->refcount.value == 0);
612 /* This calls application code and has to be done first thing
613 * without holding the lock
615 _dbus_data_slot_list_clear (&message->slot_list);
617 _dbus_list_foreach (&message->size_counters,
618 free_size_counter, message);
619 _dbus_list_clear (&message->size_counters);
623 _DBUS_LOCK (message_cache);
625 if (!message_cache_shutdown_registered)
627 _dbus_assert (message_cache_count == 0);
629 if (!_dbus_register_shutdown_func (dbus_message_cache_shutdown, NULL))
633 while (i < MAX_MESSAGE_CACHE_SIZE)
635 message_cache[i] = NULL;
639 message_cache_shutdown_registered = TRUE;
642 _dbus_assert (message_cache_count >= 0);
644 if ((_dbus_string_get_length (&message->header.data) +
645 _dbus_string_get_length (&message->body)) >
646 MAX_MESSAGE_SIZE_TO_CACHE)
649 if (message_cache_count >= MAX_MESSAGE_CACHE_SIZE)
652 /* Find empty slot */
654 while (message_cache[i] != NULL)
657 _dbus_assert (i < MAX_MESSAGE_CACHE_SIZE);
659 _dbus_assert (message_cache[i] == NULL);
660 message_cache[i] = message;
661 message_cache_count += 1;
663 #ifndef DBUS_DISABLE_CHECKS
664 message->in_cache = TRUE;
668 _DBUS_UNLOCK (message_cache);
670 _dbus_assert (message->refcount.value == 0);
673 dbus_message_finalize (message);
677 dbus_message_new_empty_header (void)
679 DBusMessage *message;
680 dbus_bool_t from_cache;
682 message = dbus_message_get_cached ();
691 message = dbus_new (DBusMessage, 1);
694 #ifndef DBUS_DISABLE_CHECKS
695 message->generation = _dbus_current_generation;
699 message->refcount.value = 1;
700 message->byte_order = DBUS_COMPILER_BYTE_ORDER;
701 message->locked = FALSE;
702 #ifndef DBUS_DISABLE_CHECKS
703 message->in_cache = FALSE;
705 message->size_counters = NULL;
706 message->size_counter_delta = 0;
707 message->changed_stamp = 0;
710 _dbus_data_slot_list_init (&message->slot_list);
714 _dbus_header_reinit (&message->header, message->byte_order);
715 _dbus_string_set_length (&message->body, 0);
719 if (!_dbus_header_init (&message->header, message->byte_order))
725 if (!_dbus_string_init_preallocated (&message->body, 32))
727 _dbus_header_free (&message->header);
737 * Constructs a new message of the given message type.
738 * Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
739 * #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
741 * @param message_type type of message
742 * @returns new message or #NULL If no memory
745 dbus_message_new (int message_type)
747 DBusMessage *message;
749 _dbus_return_val_if_fail (message_type != DBUS_MESSAGE_TYPE_INVALID, NULL);
751 message = dbus_message_new_empty_header ();
755 if (!_dbus_header_create (&message->header,
757 NULL, NULL, NULL, NULL, NULL))
759 dbus_message_unref (message);
767 * Constructs a new message to invoke a method on a remote
768 * object. Returns #NULL if memory can't be allocated for the
769 * message. The destination may be #NULL in which case no destination
770 * is set; this is appropriate when using D-BUS in a peer-to-peer
771 * context (no message bus). The interface may be #NULL, which means
772 * that if multiple methods with the given name exist it is undefined
773 * which one will be invoked.
775 * @param destination name that the message should be sent to or #NULL
776 * @param path object path the message should be sent to
777 * @param interface interface to invoke method on
778 * @param method method to invoke
780 * @returns a new DBusMessage, free with dbus_message_unref()
781 * @see dbus_message_unref()
784 dbus_message_new_method_call (const char *destination,
786 const char *interface,
789 DBusMessage *message;
791 _dbus_return_val_if_fail (path != NULL, NULL);
792 _dbus_return_val_if_fail (method != NULL, NULL);
793 _dbus_return_val_if_fail (destination == NULL ||
794 _dbus_check_is_valid_bus_name (destination), NULL);
795 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
796 _dbus_return_val_if_fail (interface == NULL ||
797 _dbus_check_is_valid_interface (interface), NULL);
798 _dbus_return_val_if_fail (_dbus_check_is_valid_member (method), NULL);
800 message = dbus_message_new_empty_header ();
804 if (!_dbus_header_create (&message->header,
805 DBUS_MESSAGE_TYPE_METHOD_CALL,
806 destination, path, interface, method, NULL))
808 dbus_message_unref (message);
816 * Constructs a message that is a reply to a method call. Returns
817 * #NULL if memory can't be allocated for the message.
819 * @param method_call the message which the created
820 * message is a reply to.
821 * @returns a new DBusMessage, free with dbus_message_unref()
822 * @see dbus_message_new_method_call(), dbus_message_unref()
825 dbus_message_new_method_return (DBusMessage *method_call)
827 DBusMessage *message;
830 _dbus_return_val_if_fail (method_call != NULL, NULL);
832 sender = dbus_message_get_sender (method_call);
834 /* sender is allowed to be null here in peer-to-peer case */
836 message = dbus_message_new_empty_header ();
840 if (!_dbus_header_create (&message->header,
841 DBUS_MESSAGE_TYPE_METHOD_RETURN,
842 sender, NULL, NULL, NULL, NULL))
844 dbus_message_unref (message);
848 dbus_message_set_no_reply (message, TRUE);
850 if (!dbus_message_set_reply_serial (message,
851 dbus_message_get_serial (method_call)))
853 dbus_message_unref (message);
861 * Constructs a new message representing a signal emission. Returns
862 * #NULL if memory can't be allocated for the message. A signal is
863 * identified by its originating interface, and the name of the
866 * @param path the path to the object emitting the signal
867 * @param interface the interface the signal is emitted from
868 * @param name name of the signal
869 * @returns a new DBusMessage, free with dbus_message_unref()
870 * @see dbus_message_unref()
873 dbus_message_new_signal (const char *path,
874 const char *interface,
877 DBusMessage *message;
879 _dbus_return_val_if_fail (path != NULL, NULL);
880 _dbus_return_val_if_fail (interface != NULL, NULL);
881 _dbus_return_val_if_fail (name != NULL, NULL);
882 _dbus_return_val_if_fail (_dbus_check_is_valid_path (path), NULL);
883 _dbus_return_val_if_fail (_dbus_check_is_valid_interface (interface), NULL);
884 _dbus_return_val_if_fail (_dbus_check_is_valid_member (name), NULL);
886 message = dbus_message_new_empty_header ();
890 if (!_dbus_header_create (&message->header,
891 DBUS_MESSAGE_TYPE_SIGNAL,
892 NULL, path, interface, name, NULL))
894 dbus_message_unref (message);
898 dbus_message_set_no_reply (message, TRUE);
904 * Creates a new message that is an error reply to a certain message.
905 * Error replies are possible in response to method calls primarily.
907 * @param reply_to the original message
908 * @param error_name the error name
909 * @param error_message the error message string or #NULL for none
910 * @returns a new error message
913 dbus_message_new_error (DBusMessage *reply_to,
914 const char *error_name,
915 const char *error_message)
917 DBusMessage *message;
919 DBusMessageIter iter;
921 _dbus_return_val_if_fail (reply_to != NULL, NULL);
922 _dbus_return_val_if_fail (error_name != NULL, NULL);
923 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
925 sender = dbus_message_get_sender (reply_to);
927 /* sender may be NULL for non-message-bus case or
928 * when the message bus is dealing with an unregistered
931 message = dbus_message_new_empty_header ();
935 if (!_dbus_header_create (&message->header,
936 DBUS_MESSAGE_TYPE_ERROR,
937 sender, NULL, NULL, NULL, error_name))
939 dbus_message_unref (message);
943 dbus_message_set_no_reply (message, TRUE);
945 if (!dbus_message_set_reply_serial (message,
946 dbus_message_get_serial (reply_to)))
948 dbus_message_unref (message);
952 if (error_message != NULL)
954 dbus_message_iter_init_append (message, &iter);
955 if (!dbus_message_iter_append_basic (&iter,
959 dbus_message_unref (message);
968 * Creates a new message that is an error reply to a certain message.
969 * Error replies are possible in response to method calls primarily.
971 * @param reply_to the original message
972 * @param error_name the error name
973 * @param error_format the error message format as with printf
974 * @param ... format string arguments
975 * @returns a new error message
978 dbus_message_new_error_printf (DBusMessage *reply_to,
979 const char *error_name,
980 const char *error_format,
985 DBusMessage *message;
987 _dbus_return_val_if_fail (reply_to != NULL, NULL);
988 _dbus_return_val_if_fail (error_name != NULL, NULL);
989 _dbus_return_val_if_fail (_dbus_check_is_valid_error_name (error_name), NULL);
991 if (!_dbus_string_init (&str))
994 va_start (args, error_format);
996 if (_dbus_string_append_printf_valist (&str, error_format, args))
997 message = dbus_message_new_error (reply_to, error_name,
998 _dbus_string_get_const_data (&str));
1002 _dbus_string_free (&str);
1011 * Creates a new message that is an exact replica of the message
1012 * specified, except that its refcount is set to 1, its message serial
1013 * is reset to 0, and if the original message was "locked" (in the
1014 * outgoing message queue and thus not modifiable) the new message
1015 * will not be locked.
1017 * @param message the message.
1018 * @returns the new message.
1021 dbus_message_copy (const DBusMessage *message)
1023 DBusMessage *retval;
1025 _dbus_return_val_if_fail (message != NULL, NULL);
1027 retval = dbus_new0 (DBusMessage, 1);
1031 retval->refcount.value = 1;
1032 retval->byte_order = message->byte_order;
1033 retval->locked = FALSE;
1034 #ifndef DBUS_DISABLE_CHECKS
1035 retval->generation = message->generation;
1038 if (!_dbus_header_copy (&message->header, &retval->header))
1044 if (!_dbus_string_init_preallocated (&retval->body,
1045 _dbus_string_get_length (&message->body)))
1047 _dbus_header_free (&retval->header);
1052 if (!_dbus_string_copy (&message->body, 0,
1059 _dbus_header_free (&retval->header);
1060 _dbus_string_free (&retval->body);
1068 * Increments the reference count of a DBusMessage.
1070 * @param message The message
1071 * @returns the message
1072 * @see dbus_message_unref
1075 dbus_message_ref (DBusMessage *message)
1077 dbus_int32_t old_refcount;
1079 _dbus_return_val_if_fail (message != NULL, NULL);
1080 _dbus_return_val_if_fail (message->generation == _dbus_current_generation, NULL);
1081 _dbus_return_val_if_fail (!message->in_cache, NULL);
1083 old_refcount = _dbus_atomic_inc (&message->refcount);
1084 _dbus_assert (old_refcount >= 1);
1090 * Decrements the reference count of a DBusMessage.
1092 * @param message The message
1093 * @see dbus_message_ref
1096 dbus_message_unref (DBusMessage *message)
1098 dbus_int32_t old_refcount;
1100 _dbus_return_if_fail (message != NULL);
1101 _dbus_return_if_fail (message->generation == _dbus_current_generation);
1102 _dbus_return_if_fail (!message->in_cache);
1104 old_refcount = _dbus_atomic_dec (&message->refcount);
1106 _dbus_assert (old_refcount >= 0);
1108 if (old_refcount == 1)
1110 /* Calls application callbacks! */
1111 dbus_message_cache_or_finalize (message);
1116 * Gets the type of a message. Types include
1117 * #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
1118 * #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
1119 * types are allowed and all code must silently ignore messages of
1120 * unknown type. DBUS_MESSAGE_TYPE_INVALID will never be returned,
1124 * @param message the message
1125 * @returns the type of the message
1128 dbus_message_get_type (DBusMessage *message)
1130 _dbus_return_val_if_fail (message != NULL, DBUS_MESSAGE_TYPE_INVALID);
1132 return _dbus_header_get_message_type (&message->header);
1136 * Appends fields to a message given a variable argument list. The
1137 * variable argument list should contain the type of each argument
1138 * followed by the value to append. Appendable types are basic types,
1139 * and arrays of fixed-length basic types. To append variable-length
1140 * basic types, or any more complex value, you have to use an iterator
1141 * rather than this function.
1143 * To append a basic type, specify its type code followed by the
1144 * value. For example:
1147 * DBUS_TYPE_INT32, 42,
1148 * DBUS_TYPE_STRING, "Hello World"
1152 * dbus_int32_t val = 42;
1153 * DBUS_TYPE_INT32, val
1156 * Be sure that your provided value is the right size. For example, this
1159 * DBUS_TYPE_INT64, 42
1161 * Because the "42" will be a 32-bit integer. You need to cast to
1164 * To append an array of fixed-length basic types, pass in the
1165 * DBUS_TYPE_ARRAY typecode, the element typecode, the address of
1166 * the array pointer, and a 32-bit integer giving the number of
1167 * elements in the array. So for example:
1169 * const dbus_int32_t array[] = { 1, 2, 3 };
1170 * const dbus_int32_t *v_ARRAY = array;
1171 * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3
1174 * @warning in C, given "int array[]", "&array == array" (the
1175 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
1176 * So if you're using an array instead of a pointer you have to create
1177 * a pointer variable, assign the array to it, then take the address
1178 * of the pointer variable. For strings it works to write
1179 * const char *array = "Hello" and then use &array though.
1181 * The last argument to this function must be #DBUS_TYPE_INVALID,
1182 * marking the end of the argument list.
1184 * String/signature/path arrays should be passed in as "const char***
1185 * address_of_array" and "int n_elements"
1187 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1189 * @todo If this fails due to lack of memory, the message is hosed and
1190 * you have to start over building the whole message.
1192 * @param message the message
1193 * @param first_arg_type type of the first argument
1194 * @param ... value of first argument, list of additional type-value pairs
1195 * @returns #TRUE on success
1198 dbus_message_append_args (DBusMessage *message,
1205 _dbus_return_val_if_fail (message != NULL, FALSE);
1207 va_start (var_args, first_arg_type);
1208 retval = dbus_message_append_args_valist (message,
1217 * This function takes a va_list for use by language bindings.
1218 * It's otherwise the same as dbus_message_append_args().
1220 * @todo for now, if this function fails due to OOM it will leave
1221 * the message half-written and you have to discard the message
1224 * @see dbus_message_append_args.
1225 * @param message the message
1226 * @param first_arg_type type of first argument
1227 * @param var_args value of first argument, then list of type/value pairs
1228 * @returns #TRUE on success
1231 dbus_message_append_args_valist (DBusMessage *message,
1236 DBusMessageIter iter;
1238 _dbus_return_val_if_fail (message != NULL, FALSE);
1240 type = first_arg_type;
1242 dbus_message_iter_init_append (message, &iter);
1244 while (type != DBUS_TYPE_INVALID)
1246 if (dbus_type_is_basic (type))
1248 const DBusBasicValue *value;
1249 value = va_arg (var_args, const DBusBasicValue*);
1251 if (!dbus_message_iter_append_basic (&iter,
1256 else if (type == DBUS_TYPE_ARRAY)
1259 DBusMessageIter array;
1262 element_type = va_arg (var_args, int);
1264 buf[0] = element_type;
1266 if (!dbus_message_iter_open_container (&iter,
1272 if (_dbus_type_is_fixed (element_type))
1274 const DBusBasicValue **value;
1277 value = va_arg (var_args, const DBusBasicValue**);
1278 n_elements = va_arg (var_args, int);
1280 if (!dbus_message_iter_append_fixed_array (&array,
1286 else if (element_type == DBUS_TYPE_STRING ||
1287 element_type == DBUS_TYPE_SIGNATURE ||
1288 element_type == DBUS_TYPE_OBJECT_PATH)
1290 const char ***value_p;
1295 value_p = va_arg (var_args, const char***);
1296 n_elements = va_arg (var_args, int);
1301 while (i < n_elements)
1303 if (!dbus_message_iter_append_basic (&array,
1312 _dbus_warn ("arrays of %s can't be appended with %s for now\n",
1313 _dbus_type_to_string (element_type),
1314 _DBUS_FUNCTION_NAME);
1318 if (!dbus_message_iter_close_container (&iter, &array))
1321 #ifndef DBUS_DISABLE_CHECKS
1324 _dbus_warn ("type %s isn't supported yet in %s\n",
1325 _dbus_type_to_string (type), _DBUS_FUNCTION_NAME);
1330 type = va_arg (var_args, int);
1340 * Gets arguments from a message given a variable argument list. The
1341 * supported types include those supported by
1342 * dbus_message_append_args(); that is, basic types and arrays of
1343 * fixed-length basic types. The arguments are the same as they would
1344 * be for dbus_message_iter_get_basic() or
1345 * dbus_message_iter_get_fixed_array().
1347 * In addition to those types, arrays of string, object path, and
1348 * signature are supported; but these are returned as allocated memory
1349 * and must be freed with dbus_free_string_array(), while the other
1350 * types are returned as const references. To get a string array
1351 * pass in "char ***array_location" and "int *n_elements"
1353 * The variable argument list should contain the type of the argument
1354 * followed by a pointer to where the value should be stored. The list
1355 * is terminated with #DBUS_TYPE_INVALID.
1357 * The returned values are constant; do not free them. They point
1358 * into the #DBusMessage.
1360 * If the requested arguments are not present, or do not have the
1361 * requested types, then an error will be set.
1363 * @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
1365 * @param message the message
1366 * @param error error to be filled in on failure
1367 * @param first_arg_type the first argument type
1368 * @param ... location for first argument value, then list of type-location pairs
1369 * @returns #FALSE if the error was set
1372 dbus_message_get_args (DBusMessage *message,
1380 _dbus_return_val_if_fail (message != NULL, FALSE);
1381 _dbus_return_val_if_error_is_set (error, FALSE);
1383 va_start (var_args, first_arg_type);
1384 retval = dbus_message_get_args_valist (message, error, first_arg_type, var_args);
1391 * This function takes a va_list for use by language bindings. It is
1392 * otherwise the same as dbus_message_get_args().
1394 * @see dbus_message_get_args
1395 * @param message the message
1396 * @param error error to be filled in
1397 * @param first_arg_type type of the first argument
1398 * @param var_args return location for first argument, followed by list of type/location pairs
1399 * @returns #FALSE if error was set
1402 dbus_message_get_args_valist (DBusMessage *message,
1407 DBusMessageIter iter;
1409 _dbus_return_val_if_fail (message != NULL, FALSE);
1410 _dbus_return_val_if_error_is_set (error, FALSE);
1412 dbus_message_iter_init (message, &iter);
1413 return _dbus_message_iter_get_args_valist (&iter, error, first_arg_type, var_args);
1417 _dbus_message_iter_init_common (DBusMessage *message,
1418 DBusMessageRealIter *real,
1421 _dbus_assert (sizeof (DBusMessageRealIter) <= sizeof (DBusMessageIter));
1423 /* Since the iterator will read or write who-knows-what from the
1424 * message, we need to get in the right byte order
1426 ensure_byte_order (message);
1428 real->message = message;
1429 real->changed_stamp = message->changed_stamp;
1430 real->iter_type = iter_type;
1431 real->sig_refcount = 0;
1435 * Initializes a #DBusMessageIter for reading the arguments of the
1436 * message passed in.
1438 * @param message the message
1439 * @param iter pointer to an iterator to initialize
1440 * @returns #FALSE if the message has no arguments
1443 dbus_message_iter_init (DBusMessage *message,
1444 DBusMessageIter *iter)
1446 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1447 const DBusString *type_str;
1450 _dbus_return_val_if_fail (message != NULL, FALSE);
1451 _dbus_return_val_if_fail (iter != NULL, FALSE);
1453 get_const_signature (&message->header, &type_str, &type_pos);
1455 _dbus_message_iter_init_common (message, real,
1456 DBUS_MESSAGE_ITER_TYPE_READER);
1458 _dbus_type_reader_init (&real->u.reader,
1459 message->byte_order,
1464 return _dbus_type_reader_get_current_type (&real->u.reader) != DBUS_TYPE_INVALID;
1467 #ifndef DBUS_DISABLE_CHECKS
1469 _dbus_message_iter_check (DBusMessageRealIter *iter)
1473 _dbus_warn ("dbus message iterator is NULL\n");
1477 if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_READER)
1479 if (iter->u.reader.byte_order != iter->message->byte_order)
1481 _dbus_warn ("dbus message changed byte order since iterator was created\n");
1484 /* because we swap the message into compiler order when you init an iter */
1485 _dbus_assert (iter->u.reader.byte_order == DBUS_COMPILER_BYTE_ORDER);
1487 else if (iter->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER)
1489 if (iter->u.writer.byte_order != iter->message->byte_order)
1491 _dbus_warn ("dbus message changed byte order since append iterator was created\n");
1494 /* because we swap the message into compiler order when you init an iter */
1495 _dbus_assert (iter->u.writer.byte_order == DBUS_COMPILER_BYTE_ORDER);
1499 _dbus_warn ("dbus message iterator looks uninitialized or corrupted\n");
1503 if (iter->changed_stamp != iter->message->changed_stamp)
1505 _dbus_warn ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
1511 #endif /* DBUS_DISABLE_CHECKS */
1514 * Checks if an iterator has any more fields.
1516 * @param iter the message iter
1517 * @returns #TRUE if there are more fields
1521 dbus_message_iter_has_next (DBusMessageIter *iter)
1523 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1525 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
1526 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
1528 return _dbus_type_reader_has_next (&real->u.reader);
1532 * Moves the iterator to the next field, if any. If there's no next
1533 * field, returns #FALSE. If the iterator moves forward, returns
1536 * @param iter the message iter
1537 * @returns #TRUE if the iterator was moved to the next field
1540 dbus_message_iter_next (DBusMessageIter *iter)
1542 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1544 _dbus_return_val_if_fail (_dbus_message_iter_check (real), FALSE);
1545 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
1547 return _dbus_type_reader_next (&real->u.reader);
1551 * Returns the argument type of the argument that the message iterator
1552 * points to. If the iterator is at the end of the message, returns
1553 * #DBUS_TYPE_INVALID. You can thus write a loop as follows:
1556 * dbus_message_iter_init (&iter);
1557 * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
1558 * dbus_message_iter_next (&iter);
1561 * @param iter the message iter
1562 * @returns the argument type
1565 dbus_message_iter_get_arg_type (DBusMessageIter *iter)
1567 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1569 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
1570 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, FALSE);
1572 return _dbus_type_reader_get_current_type (&real->u.reader);
1576 * Returns the element type of the array that the message iterator
1577 * points to. Note that you need to check that the iterator points to
1578 * an array prior to using this function.
1580 * @param iter the message iter
1581 * @returns the array element type
1584 dbus_message_iter_get_element_type (DBusMessageIter *iter)
1586 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1588 _dbus_return_val_if_fail (_dbus_message_iter_check (real), DBUS_TYPE_INVALID);
1589 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_READER, DBUS_TYPE_INVALID);
1590 _dbus_return_val_if_fail (dbus_message_iter_get_arg_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
1592 return _dbus_type_reader_get_element_type (&real->u.reader);
1596 * Recurses into a container value when reading values from a message,
1597 * initializing a sub-iterator to use for traversing the child values
1600 * Note that this recurses into a value, not a type, so you can only
1601 * recurse if the value exists. The main implication of this is that
1602 * if you have for example an empty array of array of int32, you can
1603 * recurse into the outermost array, but it will have no values, so
1604 * you won't be able to recurse further. There's no array of int32 to
1607 * @param iter the message iterator
1608 * @param sub the sub-iterator to initialize
1611 dbus_message_iter_recurse (DBusMessageIter *iter,
1612 DBusMessageIter *sub)
1614 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1615 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
1617 _dbus_return_if_fail (_dbus_message_iter_check (real));
1618 _dbus_return_if_fail (sub != NULL);
1621 _dbus_type_reader_recurse (&real->u.reader, &real_sub->u.reader);
1625 * Reads a basic-typed value from the message iterator.
1626 * Basic types are the non-containers such as integer and string.
1628 * The value argument should be the address of a location to store
1629 * the returned value. So for int32 it should be a "dbus_int32_t*"
1630 * and for string a "const char**". The returned value is
1631 * by reference and should not be freed.
1633 * All returned values are guaranteed to fit in 8 bytes. So you can
1634 * write code like this:
1637 * #ifdef DBUS_HAVE_INT64
1638 * dbus_uint64_t value;
1640 * dbus_message_iter_get_basic (&read_iter, &value);
1641 * type = dbus_message_iter_get_arg_type (&read_iter);
1642 * dbus_message_iter_append_basic (&write_iter, type, &value);
1646 * To avoid the #DBUS_HAVE_INT64 conditional, create a struct or
1647 * something that occupies at least 8 bytes, e.g. you could use a
1648 * struct with two int32 values in it. dbus_uint64_t is just one
1649 * example of a type that's large enough to hold any possible value.
1651 * Be sure you have somehow checked that
1652 * dbus_message_iter_get_arg_type() matches the type you are
1653 * expecting, or you'll crash when you try to use an integer as a
1654 * string or something.
1656 * @param iter the iterator
1657 * @param value location to store the value
1660 dbus_message_iter_get_basic (DBusMessageIter *iter,
1663 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1665 _dbus_return_if_fail (_dbus_message_iter_check (real));
1666 _dbus_return_if_fail (value != NULL);
1668 _dbus_type_reader_read_basic (&real->u.reader,
1673 * Reads a block of fixed-length values from the message iterator.
1674 * Fixed-length values are those basic types that are not string-like,
1675 * such as integers, bool, double. The block read will be from the
1676 * current position in the array until the end of the array.
1678 * The value argument should be the address of a location to store the
1679 * returned array. So for int32 it should be a "const dbus_int32_t**"
1680 * The returned value is by reference and should not be freed.
1682 * @param iter the iterator
1683 * @param value location to store the block
1684 * @param n_elements number of elements in the block
1687 dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
1691 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1693 _dbus_return_if_fail (_dbus_message_iter_check (real));
1694 _dbus_return_if_fail (value != NULL);
1695 _dbus_return_if_fail (_dbus_type_is_fixed (_dbus_type_reader_get_element_type (&real->u.reader)));
1697 _dbus_type_reader_read_fixed_multi (&real->u.reader,
1702 * This function takes a va_list for use by language bindings and is
1703 * otherwise the same as dbus_message_iter_get_args().
1704 * dbus_message_get_args() is the place to go for complete
1707 * @see dbus_message_get_args
1708 * @param iter the message iter
1709 * @param error error to be filled in
1710 * @param first_arg_type type of the first argument
1711 * @param var_args return location for first argument, followed by list of type/location pairs
1712 * @returns #FALSE if error was set
1715 _dbus_message_iter_get_args_valist (DBusMessageIter *iter,
1720 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1721 int spec_type, msg_type, i;
1724 _dbus_assert (_dbus_message_iter_check (real));
1728 spec_type = first_arg_type;
1731 while (spec_type != DBUS_TYPE_INVALID)
1733 msg_type = dbus_message_iter_get_arg_type (iter);
1735 if (msg_type != spec_type)
1737 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
1738 "Argument %d is specified to be of type \"%s\", but "
1739 "is actually of type \"%s\"\n", i,
1740 _dbus_type_to_string (spec_type),
1741 _dbus_type_to_string (msg_type));
1746 if (dbus_type_is_basic (spec_type))
1748 DBusBasicValue *ptr;
1750 ptr = va_arg (var_args, DBusBasicValue*);
1752 _dbus_assert (ptr != NULL);
1754 _dbus_type_reader_read_basic (&real->u.reader,
1757 else if (spec_type == DBUS_TYPE_ARRAY)
1760 int spec_element_type;
1761 const DBusBasicValue **ptr;
1763 DBusTypeReader array;
1765 spec_element_type = va_arg (var_args, int);
1766 element_type = _dbus_type_reader_get_element_type (&real->u.reader);
1768 if (spec_element_type != element_type)
1770 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
1771 "Argument %d is specified to be an array of \"%s\", but "
1772 "is actually an array of \"%s\"\n",
1774 _dbus_type_to_string (spec_element_type),
1775 _dbus_type_to_string (element_type));
1780 if (_dbus_type_is_fixed (spec_element_type))
1782 ptr = va_arg (var_args, const DBusBasicValue**);
1783 n_elements_p = va_arg (var_args, int*);
1785 _dbus_assert (ptr != NULL);
1786 _dbus_assert (n_elements_p != NULL);
1788 _dbus_type_reader_recurse (&real->u.reader, &array);
1790 _dbus_type_reader_read_fixed_multi (&array,
1793 else if (spec_element_type == DBUS_TYPE_STRING ||
1794 spec_element_type == DBUS_TYPE_SIGNATURE ||
1795 spec_element_type == DBUS_TYPE_OBJECT_PATH)
1797 char ***str_array_p;
1801 str_array_p = va_arg (var_args, char***);
1802 n_elements_p = va_arg (var_args, int*);
1804 _dbus_assert (str_array_p != NULL);
1805 _dbus_assert (n_elements_p != NULL);
1807 /* Count elements in the array */
1808 _dbus_type_reader_recurse (&real->u.reader, &array);
1811 while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
1814 _dbus_type_reader_next (&array);
1817 str_array = dbus_new0 (char*, n_elements + 1);
1818 if (str_array == NULL)
1820 _DBUS_SET_OOM (error);
1824 /* Now go through and dup each string */
1825 _dbus_type_reader_recurse (&real->u.reader, &array);
1828 while (i < n_elements)
1831 _dbus_type_reader_read_basic (&array,
1834 str_array[i] = _dbus_strdup (s);
1835 if (str_array[i] == NULL)
1837 dbus_free_string_array (str_array);
1838 _DBUS_SET_OOM (error);
1844 if (!_dbus_type_reader_next (&array))
1845 _dbus_assert (i == n_elements);
1848 _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
1849 _dbus_assert (i == n_elements);
1850 _dbus_assert (str_array[i] == NULL);
1852 *str_array_p = str_array;
1853 *n_elements_p = n_elements;
1855 #ifndef DBUS_DISABLE_CHECKS
1858 _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
1859 _DBUS_FUNCTION_NAME);
1864 #ifndef DBUS_DISABLE_CHECKS
1867 _dbus_warn ("you can only read arrays and basic types with %s for now\n",
1868 _DBUS_FUNCTION_NAME);
1873 spec_type = va_arg (var_args, int);
1874 if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
1876 dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
1877 "Message has only %d arguments, but more were expected", i);
1892 * Initializes a #DBusMessageIter for appending arguments to the end
1895 * @todo If appending any of the arguments fails due to lack of
1896 * memory, generally the message is hosed and you have to start over
1897 * building the whole message.
1899 * @param message the message
1900 * @param iter pointer to an iterator to initialize
1903 dbus_message_iter_init_append (DBusMessage *message,
1904 DBusMessageIter *iter)
1906 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
1908 _dbus_return_if_fail (message != NULL);
1909 _dbus_return_if_fail (iter != NULL);
1911 _dbus_message_iter_init_common (message, real,
1912 DBUS_MESSAGE_ITER_TYPE_WRITER);
1914 /* We create the signature string and point iterators at it "on demand"
1915 * when a value is actually appended. That means that init() never fails
1918 _dbus_type_writer_init_types_delayed (&real->u.writer,
1919 message->byte_order,
1921 _dbus_string_get_length (&message->body));
1925 * Creates a temporary signature string containing the current
1926 * signature, stores it in the iterator, and points the iterator to
1927 * the end of it. Used any time we write to the message.
1929 * @param real an iterator without a type_str
1930 * @returns #FALSE if no memory
1933 _dbus_message_iter_open_signature (DBusMessageRealIter *real)
1936 const DBusString *current_sig;
1937 int current_sig_pos;
1939 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
1941 if (real->u.writer.type_str != NULL)
1943 _dbus_assert (real->sig_refcount > 0);
1944 real->sig_refcount += 1;
1948 str = dbus_new (DBusString, 1);
1952 if (!_dbus_header_get_field_raw (&real->message->header,
1953 DBUS_HEADER_FIELD_SIGNATURE,
1954 ¤t_sig, ¤t_sig_pos))
1961 current_len = _dbus_string_get_byte (current_sig, current_sig_pos);
1962 current_sig_pos += 1; /* move on to sig data */
1964 if (!_dbus_string_init_preallocated (str, current_len + 4))
1970 if (!_dbus_string_copy_len (current_sig, current_sig_pos, current_len,
1973 _dbus_string_free (str);
1980 if (!_dbus_string_init_preallocated (str, 4))
1987 real->sig_refcount = 1;
1989 _dbus_type_writer_add_types (&real->u.writer,
1990 str, _dbus_string_get_length (str));
1995 * Sets the new signature as the message signature, frees the
1996 * signature string, and marks the iterator as not having a type_str
1997 * anymore. Frees the signature even if it fails, so you can't
1998 * really recover from failure. Kinda busted.
2000 * @param real an iterator without a type_str
2001 * @returns #FALSE if no memory
2004 _dbus_message_iter_close_signature (DBusMessageRealIter *real)
2007 const char *v_STRING;
2010 _dbus_assert (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER);
2011 _dbus_assert (real->u.writer.type_str != NULL);
2012 _dbus_assert (real->sig_refcount > 0);
2014 real->sig_refcount -= 1;
2016 if (real->sig_refcount > 0)
2018 _dbus_assert (real->sig_refcount == 0);
2022 str = real->u.writer.type_str;
2024 v_STRING = _dbus_string_get_const_data (str);
2025 if (!_dbus_header_set_field_basic (&real->message->header,
2026 DBUS_HEADER_FIELD_SIGNATURE,
2027 DBUS_TYPE_SIGNATURE,
2031 _dbus_type_writer_remove_types (&real->u.writer);
2032 _dbus_string_free (str);
2038 #ifndef DBUS_DISABLE_CHECKS
2040 _dbus_message_iter_append_check (DBusMessageRealIter *iter)
2042 if (!_dbus_message_iter_check (iter))
2045 if (iter->message->locked)
2047 _dbus_warn ("dbus append iterator can't be used: message is locked (has already been sent)\n");
2053 #endif /* DBUS_DISABLE_CHECKS */
2056 * Appends a basic-typed value to the message. The basic types are the
2057 * non-container types such as integer and string.
2059 * The "value" argument should be the address of a basic-typed value.
2060 * So for string, const char**. For integer, dbus_int32_t*.
2062 * @todo If this fails due to lack of memory, the message is hosed and
2063 * you have to start over building the whole message.
2065 * @param iter the append iterator
2066 * @param type the type of the value
2067 * @param value the address of the value
2068 * @returns #FALSE if not enough memory
2071 dbus_message_iter_append_basic (DBusMessageIter *iter,
2075 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2078 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2079 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2080 _dbus_return_val_if_fail (dbus_type_is_basic (type), FALSE);
2081 _dbus_return_val_if_fail (value != NULL, FALSE);
2083 if (!_dbus_message_iter_open_signature (real))
2086 ret = _dbus_type_writer_write_basic (&real->u.writer, type, value);
2088 if (!_dbus_message_iter_close_signature (real))
2095 * Appends a block of fixed-length values to an array. The
2096 * fixed-length types are all basic types that are not string-like. So
2097 * int32, double, bool, etc. You must call
2098 * dbus_message_iter_open_container() to open an array of values
2099 * before calling this function. You may call this function multiple
2100 * times (and intermixed with calls to
2101 * dbus_message_iter_append_basic()) for the same array.
2103 * The "value" argument should be the address of the array. So for
2104 * integer, "dbus_int32_t**" is expected for example.
2106 * @warning in C, given "int array[]", "&array == array" (the
2107 * comp.lang.c FAQ says otherwise, but gcc and the FAQ don't agree).
2108 * So if you're using an array instead of a pointer you have to create
2109 * a pointer variable, assign the array to it, then take the address
2110 * of the pointer variable.
2112 * const dbus_int32_t array[] = { 1, 2, 3 };
2113 * const dbus_int32_t *v_ARRAY = array;
2114 * if (!dbus_message_iter_append_fixed_array (&iter, DBUS_TYPE_INT32, &v_ARRAY, 3))
2115 * fprintf (stderr, "No memory!\n");
2117 * For strings it works to write const char *array = "Hello" and then
2118 * use &array though.
2120 * @todo If this fails due to lack of memory, the message is hosed and
2121 * you have to start over building the whole message.
2123 * @param iter the append iterator
2124 * @param element_type the type of the array elements
2125 * @param value the address of the array
2126 * @param n_elements the number of elements to append
2127 * @returns #FALSE if not enough memory
2130 dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
2135 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2138 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2139 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2140 _dbus_return_val_if_fail (_dbus_type_is_fixed (element_type), FALSE);
2141 _dbus_return_val_if_fail (real->u.writer.container_type == DBUS_TYPE_ARRAY, FALSE);
2142 _dbus_return_val_if_fail (value != NULL, FALSE);
2143 _dbus_return_val_if_fail (n_elements >= 0, FALSE);
2144 _dbus_return_val_if_fail (n_elements <=
2145 DBUS_MAXIMUM_ARRAY_LENGTH / _dbus_type_get_alignment (element_type),
2148 ret = _dbus_type_writer_write_fixed_multi (&real->u.writer, element_type, value, n_elements);
2154 * Appends a container-typed value to the message; you are required to
2155 * append the contents of the container using the returned
2156 * sub-iterator, and then call
2157 * dbus_message_iter_close_container(). Container types are for
2158 * example struct, variant, and array. For variants, the
2159 * contained_signature should be the type of the single value inside
2160 * the variant. For structs and dict entries, contained_signature
2161 * should be #NULL; it will be set to whatever types you write into
2162 * the struct. For arrays, contained_signature should be the type of
2163 * the array elements.
2165 * @todo If this fails due to lack of memory, the message is hosed and
2166 * you have to start over building the whole message.
2168 * @param iter the append iterator
2169 * @param type the type of the value
2170 * @param contained_signature the type of container contents
2171 * @param sub sub-iterator to initialize
2172 * @returns #FALSE if not enough memory
2175 dbus_message_iter_open_container (DBusMessageIter *iter,
2177 const char *contained_signature,
2178 DBusMessageIter *sub)
2180 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2181 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2182 DBusString contained_str;
2184 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2185 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2186 _dbus_return_val_if_fail (dbus_type_is_container (type), FALSE);
2187 _dbus_return_val_if_fail (sub != NULL, FALSE);
2188 _dbus_return_val_if_fail ((type == DBUS_TYPE_STRUCT &&
2189 contained_signature == NULL) ||
2190 (type == DBUS_TYPE_DICT_ENTRY &&
2191 contained_signature == NULL) ||
2192 contained_signature != NULL, FALSE);
2195 /* FIXME this would fail if the contained_signature is a dict entry,
2196 * since dict entries are invalid signatures standalone (they must be in
2199 _dbus_return_val_if_fail (contained_signature == NULL ||
2200 _dbus_check_is_valid_signature (contained_signature));
2203 if (!_dbus_message_iter_open_signature (real))
2208 if (contained_signature != NULL)
2210 _dbus_string_init_const (&contained_str, contained_signature);
2212 return _dbus_type_writer_recurse (&real->u.writer,
2215 &real_sub->u.writer);
2219 return _dbus_type_writer_recurse (&real->u.writer,
2222 &real_sub->u.writer);
2228 * Closes a container-typed value appended to the message; may write
2229 * out more information to the message known only after the entire
2230 * container is written, and may free resources created by
2231 * dbus_message_iter_open_container().
2233 * @todo If this fails due to lack of memory, the message is hosed and
2234 * you have to start over building the whole message.
2236 * @param iter the append iterator
2237 * @param sub sub-iterator to close
2238 * @returns #FALSE if not enough memory
2241 dbus_message_iter_close_container (DBusMessageIter *iter,
2242 DBusMessageIter *sub)
2244 DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
2245 DBusMessageRealIter *real_sub = (DBusMessageRealIter *)sub;
2248 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real), FALSE);
2249 _dbus_return_val_if_fail (real->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2250 _dbus_return_val_if_fail (_dbus_message_iter_append_check (real_sub), FALSE);
2251 _dbus_return_val_if_fail (real_sub->iter_type == DBUS_MESSAGE_ITER_TYPE_WRITER, FALSE);
2253 ret = _dbus_type_writer_unrecurse (&real->u.writer,
2254 &real_sub->u.writer);
2256 if (!_dbus_message_iter_close_signature (real))
2263 * Sets a flag indicating that the message does not want a reply; if
2264 * this flag is set, the other end of the connection may (but is not
2265 * required to) optimize by not sending method return or error
2266 * replies. If this flag is set, there is no way to know whether the
2267 * message successfully arrived at the remote end. Normally you know a
2268 * message was received when you receive the reply to it.
2270 * @param message the message
2271 * @param no_reply #TRUE if no reply is desired
2274 dbus_message_set_no_reply (DBusMessage *message,
2275 dbus_bool_t no_reply)
2277 _dbus_return_if_fail (message != NULL);
2278 _dbus_return_if_fail (!message->locked);
2280 _dbus_header_toggle_flag (&message->header,
2281 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED,
2286 * Returns #TRUE if the message does not expect
2289 * @param message the message
2290 * @returns #TRUE if the message sender isn't waiting for a reply
2293 dbus_message_get_no_reply (DBusMessage *message)
2295 _dbus_return_val_if_fail (message != NULL, FALSE);
2297 return _dbus_header_get_flag (&message->header,
2298 DBUS_HEADER_FLAG_NO_REPLY_EXPECTED);
2302 * Sets a flag indicating that an owner for the destination name will
2303 * be automatically started before the message is delivered. When this
2304 * flag is set, the message is held until a name owner finishes
2305 * starting up, or fails to start up. In case of failure, the reply
2308 * @param message the message
2309 * @param auto_start #TRUE if auto-starting is desired
2312 dbus_message_set_auto_start (DBusMessage *message,
2313 dbus_bool_t auto_start)
2315 _dbus_return_if_fail (message != NULL);
2316 _dbus_return_if_fail (!message->locked);
2318 _dbus_header_toggle_flag (&message->header,
2319 DBUS_HEADER_FLAG_NO_AUTO_START,
2324 * Returns #TRUE if the message will cause an owner for
2325 * destination name to be auto-started.
2327 * @param message the message
2328 * @returns #TRUE if the message will use auto-start
2331 dbus_message_get_auto_start (DBusMessage *message)
2333 _dbus_return_val_if_fail (message != NULL, FALSE);
2335 return !_dbus_header_get_flag (&message->header,
2336 DBUS_HEADER_FLAG_NO_AUTO_START);
2341 * Sets the object path this message is being sent to (for
2342 * DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
2343 * emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
2345 * @param message the message
2346 * @param object_path the path or #NULL to unset
2347 * @returns #FALSE if not enough memory
2350 dbus_message_set_path (DBusMessage *message,
2351 const char *object_path)
2353 _dbus_return_val_if_fail (message != NULL, FALSE);
2354 _dbus_return_val_if_fail (!message->locked, FALSE);
2355 _dbus_return_val_if_fail (object_path == NULL ||
2356 _dbus_check_is_valid_path (object_path),
2359 return set_or_delete_string_field (message,
2360 DBUS_HEADER_FIELD_PATH,
2361 DBUS_TYPE_OBJECT_PATH,
2366 * Gets the object path this message is being sent to (for
2367 * DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
2368 * DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
2370 * @param message the message
2371 * @returns the path (should not be freed) or #NULL
2374 dbus_message_get_path (DBusMessage *message)
2378 _dbus_return_val_if_fail (message != NULL, NULL);
2380 v = NULL; /* in case field doesn't exist */
2381 _dbus_header_get_field_basic (&message->header,
2382 DBUS_HEADER_FIELD_PATH,
2383 DBUS_TYPE_OBJECT_PATH,
2389 * Gets the object path this message is being sent to
2390 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
2391 * from (for DBUS_MESSAGE_TYPE_SIGNAL) in a decomposed
2392 * format (one array element per path component).
2393 * Free the returned array with dbus_free_string_array().
2395 * An empty but non-NULL path array means the path "/".
2396 * So the path "/foo/bar" becomes { "foo", "bar", NULL }
2397 * and the path "/" becomes { NULL }.
2399 * @todo this could be optimized by using the len from the message
2400 * instead of calling strlen() again
2402 * @param message the message
2403 * @param path place to store allocated array of path components; #NULL set here if no path field exists
2404 * @returns #FALSE if no memory to allocate the array
2407 dbus_message_get_path_decomposed (DBusMessage *message,
2412 _dbus_return_val_if_fail (message != NULL, FALSE);
2413 _dbus_return_val_if_fail (path != NULL, FALSE);
2417 v = dbus_message_get_path (message);
2420 if (!_dbus_decompose_path (v, strlen (v),
2428 * Sets the interface this message is being sent to
2429 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or
2430 * the interface a signal is being emitted from
2431 * (for DBUS_MESSAGE_TYPE_SIGNAL).
2433 * @param message the message
2434 * @param interface the interface or #NULL to unset
2435 * @returns #FALSE if not enough memory
2438 dbus_message_set_interface (DBusMessage *message,
2439 const char *interface)
2441 _dbus_return_val_if_fail (message != NULL, FALSE);
2442 _dbus_return_val_if_fail (!message->locked, FALSE);
2443 _dbus_return_val_if_fail (interface == NULL ||
2444 _dbus_check_is_valid_interface (interface),
2447 return set_or_delete_string_field (message,
2448 DBUS_HEADER_FIELD_INTERFACE,
2454 * Gets the interface this message is being sent to
2455 * (for DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted
2456 * from (for DBUS_MESSAGE_TYPE_SIGNAL).
2457 * The interface name is fully-qualified (namespaced).
2458 * Returns #NULL if none.
2460 * @param message the message
2461 * @returns the message interface (should not be freed) or #NULL
2464 dbus_message_get_interface (DBusMessage *message)
2468 _dbus_return_val_if_fail (message != NULL, NULL);
2470 v = NULL; /* in case field doesn't exist */
2471 _dbus_header_get_field_basic (&message->header,
2472 DBUS_HEADER_FIELD_INTERFACE,
2479 * Sets the interface member being invoked
2480 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
2481 * (DBUS_MESSAGE_TYPE_SIGNAL).
2482 * The interface name is fully-qualified (namespaced).
2484 * @param message the message
2485 * @param member the member or #NULL to unset
2486 * @returns #FALSE if not enough memory
2489 dbus_message_set_member (DBusMessage *message,
2492 _dbus_return_val_if_fail (message != NULL, FALSE);
2493 _dbus_return_val_if_fail (!message->locked, FALSE);
2494 _dbus_return_val_if_fail (member == NULL ||
2495 _dbus_check_is_valid_member (member),
2498 return set_or_delete_string_field (message,
2499 DBUS_HEADER_FIELD_MEMBER,
2505 * Gets the interface member being invoked
2506 * (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
2507 * (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
2509 * @param message the message
2510 * @returns the member name (should not be freed) or #NULL
2513 dbus_message_get_member (DBusMessage *message)
2517 _dbus_return_val_if_fail (message != NULL, NULL);
2519 v = NULL; /* in case field doesn't exist */
2520 _dbus_header_get_field_basic (&message->header,
2521 DBUS_HEADER_FIELD_MEMBER,
2528 * Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
2529 * The name is fully-qualified (namespaced).
2531 * @param message the message
2532 * @param error_name the name or #NULL to unset
2533 * @returns #FALSE if not enough memory
2536 dbus_message_set_error_name (DBusMessage *message,
2537 const char *error_name)
2539 _dbus_return_val_if_fail (message != NULL, FALSE);
2540 _dbus_return_val_if_fail (!message->locked, FALSE);
2541 _dbus_return_val_if_fail (error_name == NULL ||
2542 _dbus_check_is_valid_error_name (error_name),
2545 return set_or_delete_string_field (message,
2546 DBUS_HEADER_FIELD_ERROR_NAME,
2552 * Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
2555 * @param message the message
2556 * @returns the error name (should not be freed) or #NULL
2559 dbus_message_get_error_name (DBusMessage *message)
2563 _dbus_return_val_if_fail (message != NULL, NULL);
2565 v = NULL; /* in case field doesn't exist */
2566 _dbus_header_get_field_basic (&message->header,
2567 DBUS_HEADER_FIELD_ERROR_NAME,
2574 * Sets the message's destination. The destination is the name of
2575 * another connection on the bus and may be either the unique name
2576 * assigned by the bus to each connection, or a well-known name
2577 * specified in advance.
2579 * @param message the message
2580 * @param destination the destination name or #NULL to unset
2581 * @returns #FALSE if not enough memory
2584 dbus_message_set_destination (DBusMessage *message,
2585 const char *destination)
2587 _dbus_return_val_if_fail (message != NULL, FALSE);
2588 _dbus_return_val_if_fail (!message->locked, FALSE);
2589 _dbus_return_val_if_fail (destination == NULL ||
2590 _dbus_check_is_valid_bus_name (destination),
2593 return set_or_delete_string_field (message,
2594 DBUS_HEADER_FIELD_DESTINATION,
2600 * Gets the destination of a message or #NULL if there is none set.
2602 * @param message the message
2603 * @returns the message destination (should not be freed) or #NULL
2606 dbus_message_get_destination (DBusMessage *message)
2610 _dbus_return_val_if_fail (message != NULL, NULL);
2612 v = NULL; /* in case field doesn't exist */
2613 _dbus_header_get_field_basic (&message->header,
2614 DBUS_HEADER_FIELD_DESTINATION,
2621 * Sets the message sender.
2623 * @param message the message
2624 * @param sender the sender or #NULL to unset
2625 * @returns #FALSE if not enough memory
2628 dbus_message_set_sender (DBusMessage *message,
2631 _dbus_return_val_if_fail (message != NULL, FALSE);
2632 _dbus_return_val_if_fail (!message->locked, FALSE);
2633 _dbus_return_val_if_fail (sender == NULL ||
2634 _dbus_check_is_valid_bus_name (sender),
2637 return set_or_delete_string_field (message,
2638 DBUS_HEADER_FIELD_SENDER,
2644 * Gets the unique name of the connection which originated this
2645 * message, or #NULL if unknown or inapplicable. The sender is filled
2646 * in by the message bus.
2648 * @param message the message
2649 * @returns the unique name of the sender or #NULL
2652 dbus_message_get_sender (DBusMessage *message)
2656 _dbus_return_val_if_fail (message != NULL, NULL);
2658 v = NULL; /* in case field doesn't exist */
2659 _dbus_header_get_field_basic (&message->header,
2660 DBUS_HEADER_FIELD_SENDER,
2667 * Gets the type signature of the message, i.e. the arguments in the
2668 * message payload. The signature includes only "in" arguments for
2669 * #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
2670 * #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
2671 * what you might expect (it does not include the signature of the
2672 * entire C++-style method).
2674 * The signature is a string made up of type codes such as
2675 * #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
2676 * the value of #DBUS_TYPE_INVALID).
2678 * @param message the message
2679 * @returns the type signature
2682 dbus_message_get_signature (DBusMessage *message)
2684 const DBusString *type_str;
2687 _dbus_return_val_if_fail (message != NULL, NULL);
2689 get_const_signature (&message->header, &type_str, &type_pos);
2691 return _dbus_string_get_const_data_len (type_str, type_pos, 0);
2695 _dbus_message_has_type_interface_member (DBusMessage *message,
2697 const char *interface,
2702 _dbus_assert (message != NULL);
2703 _dbus_assert (interface != NULL);
2704 _dbus_assert (member != NULL);
2706 if (dbus_message_get_type (message) != type)
2709 /* Optimize by checking the short member name first
2710 * instead of the longer interface name
2713 n = dbus_message_get_member (message);
2715 if (n && strcmp (n, member) == 0)
2717 n = dbus_message_get_interface (message);
2719 if (n == NULL || strcmp (n, interface) == 0)
2727 * Checks whether the message is a method call with the given
2728 * interface and member fields. If the message is not
2729 * #DBUS_MESSAGE_TYPE_METHOD_CALL, or has a different interface or
2730 * member field, returns #FALSE. If the interface field is missing,
2731 * then it will be assumed equal to the provided interface. The D-BUS
2732 * protocol allows method callers to leave out the interface name.
2734 * @param message the message
2735 * @param interface the name to check (must not be #NULL)
2736 * @param method the name to check (must not be #NULL)
2738 * @returns #TRUE if the message is the specified method call
2741 dbus_message_is_method_call (DBusMessage *message,
2742 const char *interface,
2745 _dbus_return_val_if_fail (message != NULL, FALSE);
2746 _dbus_return_val_if_fail (interface != NULL, FALSE);
2747 _dbus_return_val_if_fail (method != NULL, FALSE);
2748 /* don't check that interface/method are valid since it would be
2749 * expensive, and not catch many common errors
2752 return _dbus_message_has_type_interface_member (message,
2753 DBUS_MESSAGE_TYPE_METHOD_CALL,
2758 * Checks whether the message is a signal with the given interface and
2759 * member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
2760 * has a different interface or member field, returns #FALSE. If the
2761 * interface field in the message is missing, it is assumed to match
2762 * any interface you pass in to this function.
2764 * @param message the message
2765 * @param interface the name to check (must not be #NULL)
2766 * @param signal_name the name to check (must not be #NULL)
2768 * @returns #TRUE if the message is the specified signal
2771 dbus_message_is_signal (DBusMessage *message,
2772 const char *interface,
2773 const char *signal_name)
2775 _dbus_return_val_if_fail (message != NULL, FALSE);
2776 _dbus_return_val_if_fail (interface != NULL, FALSE);
2777 _dbus_return_val_if_fail (signal_name != NULL, FALSE);
2778 /* don't check that interface/name are valid since it would be
2779 * expensive, and not catch many common errors
2782 return _dbus_message_has_type_interface_member (message,
2783 DBUS_MESSAGE_TYPE_SIGNAL,
2784 interface, signal_name);
2788 * Checks whether the message is an error reply with the given error
2789 * name. If the message is not #DBUS_MESSAGE_TYPE_ERROR, or has a
2790 * different name, returns #FALSE.
2792 * @param message the message
2793 * @param error_name the name to check (must not be #NULL)
2795 * @returns #TRUE if the message is the specified error
2798 dbus_message_is_error (DBusMessage *message,
2799 const char *error_name)
2803 _dbus_return_val_if_fail (message != NULL, FALSE);
2804 _dbus_return_val_if_fail (error_name != NULL, FALSE);
2805 /* don't check that error_name is valid since it would be expensive,
2806 * and not catch many common errors
2809 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
2812 n = dbus_message_get_error_name (message);
2814 if (n && strcmp (n, error_name) == 0)
2821 * Checks whether the message was sent to the given name. If the
2822 * message has no destination specified or has a different
2823 * destination, returns #FALSE.
2825 * @param message the message
2826 * @param name the name to check (must not be #NULL)
2828 * @returns #TRUE if the message has the given destination name
2831 dbus_message_has_destination (DBusMessage *message,
2836 _dbus_return_val_if_fail (message != NULL, FALSE);
2837 _dbus_return_val_if_fail (name != NULL, FALSE);
2838 /* don't check that name is valid since it would be expensive, and
2839 * not catch many common errors
2842 s = dbus_message_get_destination (message);
2844 if (s && strcmp (s, name) == 0)
2851 * Checks whether the message has the given unique name as its sender.
2852 * If the message has no sender specified or has a different sender,
2853 * returns #FALSE. Note that a peer application will always have the
2854 * unique name of the connection as the sender. So you can't use this
2855 * function to see whether a sender owned a well-known name.
2857 * Messages from the bus itself will have #DBUS_SERVICE_DBUS
2860 * @param message the message
2861 * @param name the name to check (must not be #NULL)
2863 * @returns #TRUE if the message has the given sender
2866 dbus_message_has_sender (DBusMessage *message,
2871 _dbus_return_val_if_fail (message != NULL, FALSE);
2872 _dbus_return_val_if_fail (name != NULL, FALSE);
2873 /* don't check that name is valid since it would be expensive, and
2874 * not catch many common errors
2877 s = dbus_message_get_sender (message);
2879 if (s && strcmp (s, name) == 0)
2886 * Checks whether the message has the given signature; see
2887 * dbus_message_get_signature() for more details on what the signature
2890 * @param message the message
2891 * @param signature typecode array
2892 * @returns #TRUE if message has the given signature
2895 dbus_message_has_signature (DBusMessage *message,
2896 const char *signature)
2900 _dbus_return_val_if_fail (message != NULL, FALSE);
2901 _dbus_return_val_if_fail (signature != NULL, FALSE);
2902 /* don't check that signature is valid since it would be expensive,
2903 * and not catch many common errors
2906 s = dbus_message_get_signature (message);
2908 if (s && strcmp (s, signature) == 0)
2915 * Sets a #DBusError based on the contents of the given
2916 * message. The error is only set if the message
2917 * is an error message, as in DBUS_MESSAGE_TYPE_ERROR.
2918 * The name of the error is set to the name of the message,
2919 * and the error message is set to the first argument
2920 * if the argument exists and is a string.
2922 * The return value indicates whether the error was set (the error is
2923 * set if and only if the message is an error message). So you can
2924 * check for an error reply and convert it to DBusError in one go:
2926 * if (dbus_set_error_from_message (error, reply))
2932 * @param error the error to set
2933 * @param message the message to set it from
2934 * @returns #TRUE if dbus_message_get_is_error() returns #TRUE for the message
2937 dbus_set_error_from_message (DBusError *error,
2938 DBusMessage *message)
2942 _dbus_return_val_if_fail (message != NULL, FALSE);
2943 _dbus_return_val_if_error_is_set (error, FALSE);
2945 if (dbus_message_get_type (message) != DBUS_MESSAGE_TYPE_ERROR)
2949 dbus_message_get_args (message, NULL,
2950 DBUS_TYPE_STRING, &str,
2953 dbus_set_error (error, dbus_message_get_error_name (message),
2954 str ? "%s" : NULL, str);
2962 * @addtogroup DBusMessageInternals
2968 * The initial buffer size of the message loader.
2970 * @todo this should be based on min header size plus some average
2971 * body size, or something. Or rather, the min header size only, if we
2972 * want to try to read only the header, store that in a DBusMessage,
2973 * then read only the body and store that, etc., depends on
2974 * how we optimize _dbus_message_loader_get_buffer() and what
2975 * the exact message format is.
2977 #define INITIAL_LOADER_DATA_LEN 32
2980 * Creates a new message loader. Returns #NULL if memory can't
2983 * @returns new loader, or #NULL.
2986 _dbus_message_loader_new (void)
2988 DBusMessageLoader *loader;
2990 loader = dbus_new0 (DBusMessageLoader, 1);
2994 loader->refcount = 1;
2996 loader->corrupted = FALSE;
2997 loader->corruption_reason = DBUS_VALID;
2999 /* this can be configured by the app, but defaults to the protocol max */
3000 loader->max_message_size = DBUS_MAXIMUM_MESSAGE_LENGTH;
3002 if (!_dbus_string_init (&loader->data))
3008 /* preallocate the buffer for speed, ignore failure */
3009 _dbus_string_set_length (&loader->data, INITIAL_LOADER_DATA_LEN);
3010 _dbus_string_set_length (&loader->data, 0);
3016 * Increments the reference count of the loader.
3018 * @param loader the loader.
3019 * @returns the loader
3022 _dbus_message_loader_ref (DBusMessageLoader *loader)
3024 loader->refcount += 1;
3030 * Decrements the reference count of the loader and finalizes the
3031 * loader when the count reaches zero.
3033 * @param loader the loader.
3036 _dbus_message_loader_unref (DBusMessageLoader *loader)
3038 loader->refcount -= 1;
3039 if (loader->refcount == 0)
3041 _dbus_list_foreach (&loader->messages,
3042 (DBusForeachFunction) dbus_message_unref,
3044 _dbus_list_clear (&loader->messages);
3045 _dbus_string_free (&loader->data);
3051 * Gets the buffer to use for reading data from the network. Network
3052 * data is read directly into an allocated buffer, which is then used
3053 * in the DBusMessage, to avoid as many extra memcpy's as possible.
3054 * The buffer must always be returned immediately using
3055 * _dbus_message_loader_return_buffer(), even if no bytes are
3056 * successfully read.
3058 * @todo this function can be a lot more clever. For example
3059 * it can probably always return a buffer size to read exactly
3060 * the body of the next message, thus avoiding any memory wastage
3063 * @todo we need to enforce a max length on strings in header fields.
3065 * @param loader the message loader.
3066 * @param buffer the buffer
3069 _dbus_message_loader_get_buffer (DBusMessageLoader *loader,
3070 DBusString **buffer)
3072 _dbus_assert (!loader->buffer_outstanding);
3074 *buffer = &loader->data;
3076 loader->buffer_outstanding = TRUE;
3080 * Returns a buffer obtained from _dbus_message_loader_get_buffer(),
3081 * indicating to the loader how many bytes of the buffer were filled
3082 * in. This function must always be called, even if no bytes were
3083 * successfully read.
3085 * @param loader the loader.
3086 * @param buffer the buffer.
3087 * @param bytes_read number of bytes that were read into the buffer.
3090 _dbus_message_loader_return_buffer (DBusMessageLoader *loader,
3094 _dbus_assert (loader->buffer_outstanding);
3095 _dbus_assert (buffer == &loader->data);
3097 loader->buffer_outstanding = FALSE;
3101 * FIXME when we move the header out of the buffer, that memmoves all
3102 * buffered messages. Kind of crappy.
3104 * Also we copy the header and body, which is kind of crappy. To
3105 * avoid this, we have to allow header and body to be in a single
3106 * memory block, which is good for messages we read and bad for
3107 * messages we are creating. But we could move_len() the buffer into
3108 * this single memory block, and move_len() will just swap the buffers
3109 * if you're moving the entire buffer replacing the dest string.
3111 * We could also have the message loader tell the transport how many
3112 * bytes to read; so it would first ask for some arbitrary number like
3113 * 256, then if the message was incomplete it would use the
3114 * header/body len to ask for exactly the size of the message (or
3115 * blocks the size of a typical kernel buffer for the socket). That
3116 * way we don't get trailing bytes in the buffer that have to be
3117 * memmoved. Though I suppose we also don't have a chance of reading a
3118 * bunch of small messages at once, so the optimization may be stupid.
3120 * Another approach would be to keep a "start" index into
3121 * loader->data and only delete it occasionally, instead of after
3122 * each message is loaded.
3124 * load_message() returns FALSE if not enough memory OR the loader was corrupted
3127 load_message (DBusMessageLoader *loader,
3128 DBusMessage *message,
3130 int fields_array_len,
3135 DBusValidity validity;
3136 const DBusString *type_str;
3138 DBusValidationMode mode;
3140 mode = DBUS_VALIDATION_MODE_DATA_IS_UNTRUSTED;
3145 _dbus_verbose_bytes_of_string (&loader->data, 0, header_len /* + body_len */);
3148 /* 1. VALIDATE AND COPY OVER HEADER */
3149 _dbus_assert (_dbus_string_get_length (&message->header.data) == 0);
3150 _dbus_assert ((header_len + body_len) <= _dbus_string_get_length (&loader->data));
3152 if (!_dbus_header_load (&message->header,
3160 _dbus_string_get_length (&loader->data)))
3162 _dbus_verbose ("Failed to load header for new message code %d\n", validity);
3163 if (validity == DBUS_VALID)
3167 loader->corrupted = TRUE;
3168 loader->corruption_reason = validity;
3173 _dbus_assert (validity == DBUS_VALID);
3175 message->byte_order = byte_order;
3177 /* 2. VALIDATE BODY */
3178 if (mode != DBUS_VALIDATION_MODE_WE_TRUST_THIS_DATA_ABSOLUTELY)
3180 get_const_signature (&message->header, &type_str, &type_pos);
3182 /* Because the bytes_remaining arg is NULL, this validates that the
3183 * body is the right length
3185 validity = _dbus_validate_body_with_reason (type_str,
3192 if (validity != DBUS_VALID)
3194 _dbus_verbose ("Failed to validate message body code %d\n", validity);
3196 loader->corrupted = TRUE;
3197 loader->corruption_reason = validity;
3203 /* 3. COPY OVER BODY AND QUEUE MESSAGE */
3205 if (!_dbus_list_append (&loader->messages, message))
3207 _dbus_verbose ("Failed to append new message to loader queue\n");
3212 _dbus_assert (_dbus_string_get_length (&message->body) == 0);
3213 _dbus_assert (_dbus_string_get_length (&loader->data) >=
3214 (header_len + body_len));
3216 if (!_dbus_string_copy_len (&loader->data, header_len, body_len, &message->body, 0))
3218 _dbus_verbose ("Failed to move body into new message\n");
3223 _dbus_string_delete (&loader->data, 0, header_len + body_len);
3225 _dbus_assert (_dbus_string_get_length (&message->header.data) == header_len);
3226 _dbus_assert (_dbus_string_get_length (&message->body) == body_len);
3228 _dbus_verbose ("Loaded message %p\n", message);
3230 _dbus_assert (!oom);
3231 _dbus_assert (!loader->corrupted);
3232 _dbus_assert (loader->messages != NULL);
3233 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
3241 /* does nothing if the message isn't in the list */
3242 _dbus_list_remove_last (&loader->messages, message);
3245 _dbus_assert (!loader->corrupted);
3247 _dbus_assert (loader->corrupted);
3249 _dbus_verbose_bytes_of_string (&loader->data, 0, _dbus_string_get_length (&loader->data));
3255 * Converts buffered data into messages, if we have enough data. If
3256 * we don't have enough data, does nothing.
3258 * @todo we need to check that the proper named header fields exist
3259 * for each message type.
3261 * @todo If a message has unknown type, we should probably eat it
3262 * right here rather than passing it out to applications. However
3263 * it's not an error to see messages of unknown type.
3265 * @param loader the loader.
3266 * @returns #TRUE if we had enough memory to finish.
3269 _dbus_message_loader_queue_messages (DBusMessageLoader *loader)
3271 while (!loader->corrupted &&
3272 _dbus_string_get_length (&loader->data) >= DBUS_MINIMUM_HEADER_SIZE)
3274 DBusValidity validity;
3275 int byte_order, fields_array_len, header_len, body_len;
3277 if (_dbus_header_have_message_untrusted (loader->max_message_size,
3284 _dbus_string_get_length (&loader->data)))
3286 DBusMessage *message;
3288 _dbus_assert (validity == DBUS_VALID);
3290 message = dbus_message_new_empty_header ();
3291 if (message == NULL)
3294 if (!load_message (loader, message,
3295 byte_order, fields_array_len,
3296 header_len, body_len))
3298 dbus_message_unref (message);
3299 /* load_message() returns false if corrupted or OOM; if
3300 * corrupted then return TRUE for not OOM
3302 return loader->corrupted;
3305 _dbus_assert (loader->messages != NULL);
3306 _dbus_assert (_dbus_list_find_last (&loader->messages, message) != NULL);
3310 _dbus_verbose ("Initial peek at header says we don't have a whole message yet, or data broken with invalid code %d\n",
3312 if (validity != DBUS_VALID)
3314 loader->corrupted = TRUE;
3315 loader->corruption_reason = validity;
3325 * Peeks at first loaded message, returns #NULL if no messages have
3328 * @param loader the loader.
3329 * @returns the next message, or #NULL if none.
3332 _dbus_message_loader_peek_message (DBusMessageLoader *loader)
3334 if (loader->messages)
3335 return loader->messages->data;
3341 * Pops a loaded message (passing ownership of the message
3342 * to the caller). Returns #NULL if no messages have been
3345 * @param loader the loader.
3346 * @returns the next message, or #NULL if none.
3349 _dbus_message_loader_pop_message (DBusMessageLoader *loader)
3351 return _dbus_list_pop_first (&loader->messages);
3355 * Pops a loaded message inside a list link (passing ownership of the
3356 * message and link to the caller). Returns #NULL if no messages have
3359 * @param loader the loader.
3360 * @returns the next message link, or #NULL if none.
3363 _dbus_message_loader_pop_message_link (DBusMessageLoader *loader)
3365 return _dbus_list_pop_first_link (&loader->messages);
3369 * Returns a popped message link, used to undo a pop.
3371 * @param loader the loader
3372 * @param link the link with a message in it
3375 _dbus_message_loader_putback_message_link (DBusMessageLoader *loader,
3378 _dbus_list_prepend_link (&loader->messages, link);
3382 * Checks whether the loader is confused due to bad data.
3383 * If messages are received that are invalid, the
3384 * loader gets confused and gives up permanently.
3385 * This state is called "corrupted."
3387 * @param loader the loader
3388 * @returns #TRUE if the loader is hosed.
3391 _dbus_message_loader_get_is_corrupted (DBusMessageLoader *loader)
3393 _dbus_assert ((loader->corrupted && loader->corruption_reason != DBUS_VALID) ||
3394 (!loader->corrupted && loader->corruption_reason == DBUS_VALID));
3395 return loader->corrupted;
3399 * Sets the maximum size message we allow.
3401 * @param loader the loader
3402 * @param size the max message size in bytes
3405 _dbus_message_loader_set_max_message_size (DBusMessageLoader *loader,
3408 if (size > DBUS_MAXIMUM_MESSAGE_LENGTH)
3410 _dbus_verbose ("clamping requested max message size %ld to %d\n",
3411 size, DBUS_MAXIMUM_MESSAGE_LENGTH);
3412 size = DBUS_MAXIMUM_MESSAGE_LENGTH;
3414 loader->max_message_size = size;
3418 * Gets the maximum allowed message size in bytes.
3420 * @param loader the loader
3421 * @returns max size in bytes
3424 _dbus_message_loader_get_max_message_size (DBusMessageLoader *loader)
3426 return loader->max_message_size;
3429 static DBusDataSlotAllocator slot_allocator;
3430 _DBUS_DEFINE_GLOBAL_LOCK (message_slots);
3433 * Allocates an integer ID to be used for storing application-specific
3434 * data on any DBusMessage. The allocated ID may then be used
3435 * with dbus_message_set_data() and dbus_message_get_data().
3436 * The passed-in slot must be initialized to -1, and is filled in
3437 * with the slot ID. If the passed-in slot is not -1, it's assumed
3438 * to be already allocated, and its refcount is incremented.
3440 * The allocated slot is global, i.e. all DBusMessage objects will
3441 * have a slot with the given integer ID reserved.
3443 * @param slot_p address of a global variable storing the slot
3444 * @returns #FALSE on failure (no memory)
3447 dbus_message_allocate_data_slot (dbus_int32_t *slot_p)
3449 return _dbus_data_slot_allocator_alloc (&slot_allocator,
3450 _DBUS_LOCK_NAME (message_slots),
3455 * Deallocates a global ID for message data slots.
3456 * dbus_message_get_data() and dbus_message_set_data() may no
3457 * longer be used with this slot. Existing data stored on existing
3458 * DBusMessage objects will be freed when the message is
3459 * finalized, but may not be retrieved (and may only be replaced if
3460 * someone else reallocates the slot). When the refcount on the
3461 * passed-in slot reaches 0, it is set to -1.
3463 * @param slot_p address storing the slot to deallocate
3466 dbus_message_free_data_slot (dbus_int32_t *slot_p)
3468 _dbus_return_if_fail (*slot_p >= 0);
3470 _dbus_data_slot_allocator_free (&slot_allocator, slot_p);
3474 * Stores a pointer on a DBusMessage, along
3475 * with an optional function to be used for freeing
3476 * the data when the data is set again, or when
3477 * the message is finalized. The slot number
3478 * must have been allocated with dbus_message_allocate_data_slot().
3480 * @param message the message
3481 * @param slot the slot number
3482 * @param data the data to store
3483 * @param free_data_func finalizer function for the data
3484 * @returns #TRUE if there was enough memory to store the data
3487 dbus_message_set_data (DBusMessage *message,
3490 DBusFreeFunction free_data_func)
3492 DBusFreeFunction old_free_func;
3496 _dbus_return_val_if_fail (message != NULL, FALSE);
3497 _dbus_return_val_if_fail (slot >= 0, FALSE);
3499 retval = _dbus_data_slot_list_set (&slot_allocator,
3500 &message->slot_list,
3501 slot, data, free_data_func,
3502 &old_free_func, &old_data);
3506 /* Do the actual free outside the message lock */
3508 (* old_free_func) (old_data);
3515 * Retrieves data previously set with dbus_message_set_data().
3516 * The slot must still be allocated (must not have been freed).
3518 * @param message the message
3519 * @param slot the slot to get data from
3520 * @returns the data, or #NULL if not found
3523 dbus_message_get_data (DBusMessage *message,
3528 _dbus_return_val_if_fail (message != NULL, NULL);
3530 res = _dbus_data_slot_list_get (&slot_allocator,
3531 &message->slot_list,
3538 * Utility function to convert a machine-readable (not translated)
3539 * string into a D-BUS message type.
3542 * "method_call" -> DBUS_MESSAGE_TYPE_METHOD_CALL
3543 * "method_return" -> DBUS_MESSAGE_TYPE_METHOD_RETURN
3544 * "signal" -> DBUS_MESSAGE_TYPE_SIGNAL
3545 * "error" -> DBUS_MESSAGE_TYPE_ERROR
3546 * anything else -> DBUS_MESSAGE_TYPE_INVALID
3551 dbus_message_type_from_string (const char *type_str)
3553 if (strcmp (type_str, "method_call") == 0)
3554 return DBUS_MESSAGE_TYPE_METHOD_CALL;
3555 if (strcmp (type_str, "method_return") == 0)
3556 return DBUS_MESSAGE_TYPE_METHOD_RETURN;
3557 else if (strcmp (type_str, "signal") == 0)
3558 return DBUS_MESSAGE_TYPE_SIGNAL;
3559 else if (strcmp (type_str, "error") == 0)
3560 return DBUS_MESSAGE_TYPE_ERROR;
3562 return DBUS_MESSAGE_TYPE_INVALID;
3566 * Utility function to convert a D-BUS message type into a
3567 * machine-readable string (not translated).
3570 * DBUS_MESSAGE_TYPE_METHOD_CALL -> "method_call"
3571 * DBUS_MESSAGE_TYPE_METHOD_RETURN -> "method_return"
3572 * DBUS_MESSAGE_TYPE_SIGNAL -> "signal"
3573 * DBUS_MESSAGE_TYPE_ERROR -> "error"
3574 * DBUS_MESSAGE_TYPE_INVALID -> "invalid"
3579 dbus_message_type_to_string (int type)
3583 case DBUS_MESSAGE_TYPE_METHOD_CALL:
3584 return "method_call";
3585 case DBUS_MESSAGE_TYPE_METHOD_RETURN:
3586 return "method_return";
3587 case DBUS_MESSAGE_TYPE_SIGNAL:
3589 case DBUS_MESSAGE_TYPE_ERROR:
3598 /* tests in dbus-message-util.c */