dbus/dbus dbus-bus.c, 1.62, 1.63 dbus-connection.c, 1.144,
1.145 dbus-errors.c, 1.31, 1.32 dbus-marshal-recursive.c, 1.54,
1.55 dbus-memory.c, 1.27, 1.28 dbus-message.c, 1.179,
1.180 dbus-message.h, 1.61, 1.62 dbus-timeout.c, 1.16,
1.17 dbus-watch.c, 1.20, 1.21
Havoc Pennington
hp at kemper.freedesktop.org
Sat Oct 21 10:08:10 PDT 2006
Update of /cvs/dbus/dbus/dbus
In directory kemper:/tmp/cvs-serv14918/dbus
Modified Files:
dbus-bus.c dbus-connection.c dbus-errors.c
dbus-marshal-recursive.c dbus-memory.c dbus-message.c
dbus-message.h dbus-timeout.c dbus-watch.c
Log Message:
2006-10-21 Havoc Pennington <hp at redhat.com>
* dbus/dbus-message.h: put #ifndef DBUS_DISABLE_DEPRECATED around
dbus_message_iter_get_array_len().
* throughout: documentation improvements.
Index: dbus-bus.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-bus.c,v
retrieving revision 1.62
retrieving revision 1.63
diff -u -d -r1.62 -r1.63
--- dbus-bus.c 17 Oct 2006 20:52:13 -0000 1.62
+++ dbus-bus.c 21 Oct 2006 17:08:08 -0000 1.63
@@ -36,6 +36,21 @@
* @ingroup DBus
* @brief Functions for communicating with the message bus
*
+ * dbus_bus_get() allows all modules and libraries in a given
+ * process to share the same connection to the bus daemon by storing
+ * the connection globally.
+ *
+ * All other functions in this module are just convenience functions;
+ * most of them invoke methods on the bus daemon, by sending method
+ * call messages to #DBUS_SERVICE_DBUS. These convenience functions
+ * often make blocking method calls. If you don't want to block,
+ * you can send the method call messages manually in the same way
+ * you would any other method call message.
+ *
+ * This module is the only one in libdbus that's specific to
+ * communicating with the message bus daemon. The rest of the API can
+ * also be used for connecting to another application directly.
+ *
* @todo right now the default address of the system bus is hardcoded,
* so if you change it in the global config file suddenly you have to
* set DBUS_SYSTEM_BUS_ADDRESS env variable. Might be nice if the
@@ -472,6 +487,11 @@
* will exit if the connection closes. You can undo this
* by calling dbus_connection_set_exit_on_disconnect() yourself
* after you get the connection.
+ *
+ * dbus_bus_get() calls dbus_bus_register() for you.
+ *
+ * If returning a newly-created connection, this function will block
+ * until authentication and bus registration are complete.
*
* @param type bus type
* @param error address where an error can be returned.
@@ -485,11 +505,11 @@
}
/**
- * Connects to a bus daemon and registers the client with it as with dbus_bus_register().
- * Unlike dbus_bus_get(), always creates a new connection. This connection
- * will not be saved or recycled by libdbus. Caller owns a reference
- * to the bus and must either close it or know it to be closed
- * prior to releasing this reference.
+ * Connects to a bus daemon and registers the client with it as with
+ * dbus_bus_register(). Unlike dbus_bus_get(), always creates a new
+ * connection. This connection will not be saved or recycled by
+ * libdbus. Caller owns a reference to the bus and must either close
+ * it or know it to be closed prior to releasing this reference.
*
* See dbus_connection_open_private() for more details on when to
* close and unref this connection.
@@ -500,6 +520,11 @@
* by calling dbus_connection_set_exit_on_disconnect() yourself
* after you get the connection.
*
+ * dbus_bus_get_private() calls dbus_bus_register() for you.
+ *
+ * This function will block until authentication and bus registration
+ * are complete.
+ *
* @param type bus type
* @param error address where an error can be returned.
* @returns a DBusConnection with new ref
@@ -519,6 +544,13 @@
*
* If you use dbus_bus_get() or dbus_bus_get_private() this
* function will be called for you.
+ *
+ * If you open a bus connection with dbus_connection_open() or
+ * dbus_connection_open_private() you will have to dbus_bus_register()
+ * yourself, or make the appropriate registration method calls
+ * yourself.
+ *
+ * This function will block until registration is complete.
*
* @param connection the connection
* @param error place to store errors
@@ -598,9 +630,11 @@
/**
- * Sets the unique name of the connection. Can only be used if you
- * registered with the bus manually (i.e. if you did not call
- * dbus_bus_register()). Can only be called once per connection.
+ * Sets the unique name of the connection, as assigned by the message
+ * bus. Can only be used if you registered with the bus manually
+ * (i.e. if you did not call dbus_bus_register()). Can only be called
+ * once per connection. After the unique name is set, you can get it
+ * with dbus_bus_get_unique_name().
*
* @param connection the connection
* @param unique_name the unique name
@@ -626,11 +660,17 @@
}
/**
- * Gets the unique name of the connection. Only possible after the
- * connection has been registered with the message bus.
+ * Gets the unique name of the connection as assigned by the message
+ * bus. Only possible after the connection has been registered with
+ * the message bus.
*
- * The name remains valid for the duration of the connection and
+ * The name remains valid until the connection is freed, and
* should not be freed by the caller.
+ *
+ * There are two ways to set the unique name; one is
+ * dbus_bus_register(), the other is dbus_bus_set_unique_name().
+ * You are responsible for calling dbus_bus_set_unique_name()
+ * if you register by hand instead of using dbus_bus_register().
*
* @param connection the connection
* @returns the unique name or NULL on error
@@ -650,16 +690,22 @@
}
/**
- * Asks the bus to return the uid of the named
- * connection.
+ * Asks the bus to return the uid of the named connection.
+ * Only works on UNIX; only works for connections on the same
+ * machine as the bus. If you are not on the same machine
+ * as the bus, then calling this is probably a bad idea,
+ * since the uid will mean little to your application.
*
- * Not going to work on Windows, the bus should return
- * an error then.
+ * For the system message bus you're guaranteed to be on the same
+ * machine since it only listens on a UNIX domain socket (at least,
+ * as shipped by default).
+ *
+ * This function will just return an error on Windows.
*
* @param connection the connection
* @param name a name owned by the connection
* @param error location to store the error
- * @returns a result code, -1 if error is set
+ * @returns the unix user id, or ((unsigned)-1) if error is set
*/
unsigned long
dbus_bus_get_unix_user (DBusConnection *connection,
@@ -734,17 +780,46 @@
* result codes are discussed here, but the specification is the
* canonical version of this information.
*
- * The #DBUS_NAME_FLAG_ALLOW_REPLACEMENT flag indicates that the caller
- * will allow other services to take over the name from the current owner.
+ * First you should know that for each bus name, the bus stores
+ * a queue of connections that would like to own it. Only
+ * one owns it at a time - called the primary owner. If the primary
+ * owner releases the name or disconnects, then the next owner in the
+ * queue atomically takes over.
*
- * The #DBUS_NAME_FLAG_REPLACE_EXISTING flag indicates that the caller
- * would like to take over the name from the current owner.
- * If the current name owner did not use #DBUS_NAME_FLAG_ALLOW_REPLACEMENT
- * then this flag indicates that the caller would like to be placed
- * in the queue to own the name when the current owner lets go.
+ * So for example if you have an application org.freedesktop.TextEditor
+ * and multiple instances of it can be run, you can have all of them
+ * sitting in the queue. The first one to start up will receive messages
+ * sent to org.freedesktop.TextEditor, but if that one exits another
+ * will become the primary owner and receive messages.
+ *
+ * The queue means you don't need to manually watch for the current owner to
+ * disappear and then request the name again.
+ *
+ * When requesting a name, you can specify several flags.
+ *
+ * #DBUS_NAME_FLAG_ALLOW_REPLACEMENT and #DBUS_NAME_FLAG_DO_NOT_QUEUE
+ * are properties stored by the bus for this connection with respect to
+ * each requested bus name. These properties are stored even if the
+ * connection is queued and does not become the primary owner.
+ * You can update these flags by calling RequestName again (even if
+ * you already own the name).
+ *
+ * #DBUS_NAME_FLAG_ALLOW_REPLACEMENT means that another requestor of the
+ * name can take it away from you by specifying #DBUS_NAME_FLAG_REPLACE_EXISTING.
+ *
+ * #DBUS_NAME_FLAG_DO_NOT_QUEUE means that if you aren't the primary owner,
+ * you don't want to be queued up - you only care about being the
+ * primary owner.
+ *
+ * Unlike the other two flags, #DBUS_NAME_FLAG_REPLACE_EXISTING is a property
+ * of the individual RequestName call, i.e. the bus does not persistently
+ * associate it with the connection-name pair. If a RequestName call includes
+ * the #DBUS_NAME_FLAG_REPLACE_EXISTING flag, and the current primary
+ * owner has #DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, then the current primary
+ * owner will be kicked off.
*
* If no flags are given, an application will receive the requested
- * name only if the name is currently unowned; it will NOT give
+ * name only if the name is currently unowned; and it will NOT give
* up the name if another application asks to take it over using
* #DBUS_NAME_FLAG_REPLACE_EXISTING.
*
@@ -770,7 +845,9 @@
* #DBUS_NAME_FLAG_REPLACE_EXISTING.
*
* #DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER happens if an application
- * requests a name it already owns.
+ * requests a name it already owns. (Re-requesting a name is useful if
+ * you want to change the #DBUS_NAME_FLAG_ALLOW_REPLACEMENT or
+ * #DBUS_NAME_FLAG_DO_NOT_QUEUE settings.)
*
* When a service represents an application, say "text editor," then
* it should specify #DBUS_NAME_FLAG_ALLOW_REPLACEMENT if it wants
@@ -779,7 +856,19 @@
* specify #DBUS_NAME_FLAG_REPLACE_EXISTING to either take over
* (last-started-wins) or be queued up (first-started-wins) according
* to whether #DBUS_NAME_FLAG_ALLOW_REPLACEMENT was given.
- *
+ *
+ * Conventionally, single-instance applications often offer a command
+ * line option called --replace which means to replace the current
+ * instance. To implement this, always set
+ * #DBUS_NAME_FLAG_ALLOW_REPLACEMENT when you request your
+ * application's bus name. When you lose ownership of your bus name,
+ * you need to exit. Look for the signal "NameLost" from
+ * #DBUS_SERVICE_DBUS and #DBUS_INTERFACE_DBUS (the signal's first
+ * argument is the bus name that was lost). If starting up without
+ * --replace, do not specify #DBUS_NAME_FLAG_REPLACE_EXISTING, and
+ * exit if you fail to become the bus name owner. If --replace is
+ * given, ask to replace the old owner.
+ *
* @param connection the connection
* @param name the name to request
* @param flags flags
@@ -855,10 +944,18 @@
/**
- * Asks the bus to unassign the given name to this connection by invoking
- * the ReleaseName method on the bus. This method is fully documented
- * in the D-Bus specification.
+ * Asks the bus to unassign the given name from this connection by
+ * invoking the ReleaseName method on the bus. The "ReleaseName"
+ * method is canonically documented in the D-Bus specification.
*
+ * Possible results are: #DBUS_RELEASE_NAME_REPLY_RELEASED
+ * which means you owned the name or were in the queue to own it,
+ * and and now you don't own it and aren't in the queue.
+ * #DBUS_RELEASE_NAME_REPLY_NOT_OWNER which means someone else
+ * owns the name so you can't release it.
+ * #DBUS_RELEASE_NAME_REPLY_NON_EXISTENT
+ * which means nobody owned the name.
+ *
* @param connection the connection
* @param name the name to remove
* @param error location to store the error
@@ -930,8 +1027,17 @@
}
/**
- * Checks whether a certain name has an owner.
+ * Asks the bus whether a certain name has an owner.
*
+ * Using this can easily result in a race condition,
+ * since an owner can appear or disappear after you
+ * call this.
+ *
+ * If you want to request a name, just request it;
+ * if you want to avoid replacing a current owner,
+ * don't specify #DBUS_NAME_FLAG_REPLACE_EXISTING and
+ * you will get an error if there's already an owner.
+ *
* @param connection the connection
* @param name the name
* @param error location to store any errors
@@ -1000,6 +1106,12 @@
* The flags parameter is for future expansion, currently you should
* specify 0.
*
+ * It's often easier to avoid explicitly starting services, and
+ * just send a method call to the service's bus name instead.
+ * Method calls start a service to handle them by default
+ * unless you call dbus_message_set_auto_start() to disable this
+ * behavior.
+ *
* @param connection the connection
* @param name the name we want the new service to request
* @param flags the flags (should always be 0 for now)
@@ -1119,11 +1231,13 @@
* path='/bar/foo',destination=':452345.34'"
*
* Possible keys you can match on are type, sender,
- * interface, member, path, destination and the special
- * arg keys. Excluding a key from the rule indicates
- * a wildcard match. For instance excluding the
+ * interface, member, path, destination and numbered
+ * keys to match message args (keys are 'arg0', 'arg1', etc.).
+ * Omitting a key from the rule indicates
+ * a wildcard match. For instance omitting
* the member from a match rule but adding a sender would
- * let all messages from that sender through.
+ * let all messages from that sender through regardless of
+ * the member.
*
* Matches are inclusive not exclusive so as long as one
* rule matches the message will get through. It is important
@@ -1132,12 +1246,31 @@
* can cause performance problems such as draining batteries
* on embedded platforms.
*
- * The special arg keys are used for further restricting the
- * match based on the parameters sent by the signal or method.
- * For instance arg1='foo' will check the first argument,
- * arg2='bar' the second and so on. For performance reasons
- * there is a set limit on the highest number parameter that
- * can be checked which is set in dbus-protocol.h
+ * If you match message args ('arg0', 'arg1', and so forth)
+ * only string arguments will match. That is, arg0='5' means
+ * match the string "5" not the integer 5.
+ *
+ * Currently there is no way to match against non-string arguments.
+ *
+ * Matching on interface is tricky because method call
+ * messages only optionally specify the interface.
+ * If a message omits the interface, then it will NOT match
+ * if the rule specifies an interface name. This means match
+ * rules on method calls should not usually give an interface.
+ *
+ * However, signal messages are required to include the interface
+ * so when matching signals usually you should specify the interface
+ * in the match rule.
+ *
+ * For security reasons, you can match arguments only up to
+ * #DBUS_MAXIMUM_MATCH_RULE_ARG_NUMBER.
+ *
+ * Match rules have a maximum length of #DBUS_MAXIMUM_MATCH_RULE_LENGTH
+ * bytes.
+ *
+ * Both of these maximums are much higher than you're likely to need,
+ * they only exist because the D-Bus bus daemon has fixed limits on
+ * all resource usage.
*
* @param connection connection to the message bus
* @param rule textual form of match rule
@@ -1181,6 +1314,10 @@
* recently-added identical rule gets removed). The "rule" argument
* is the string form of a match rule.
*
+ * The bus compares match rules semantically, not textually, so
+ * whitespace and ordering don't have to be identical to
+ * the rule you passed to dbus_bus_add_match().
+ *
* If you pass #NULL for the error, this function will not
* block; otherwise it will. See detailed explanation in
* docs for dbus_bus_add_match().
Index: dbus-connection.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-connection.c,v
retrieving revision 1.144
retrieving revision 1.145
diff -u -d -r1.144 -r1.145
--- dbus-connection.c 21 Oct 2006 03:14:50 -0000 1.144
+++ dbus-connection.c 21 Oct 2006 17:08:08 -0000 1.145
@@ -2940,16 +2940,19 @@
* The function will never fail for other reasons; even if the
* connection is disconnected, you can queue an outgoing message,
* though obviously it won't be sent.
+ *
+ * The message serial is used by the remote application to send a
+ * reply; see dbus_message_get_serial() or the D-Bus specification.
*
* @param connection the connection.
* @param message the message to write.
- * @param client_serial return location for client serial.
+ * @param serial return location for message serial, or #NULL if you don't care
* @returns #TRUE on success.
*/
dbus_bool_t
dbus_connection_send (DBusConnection *connection,
DBusMessage *message,
- dbus_uint32_t *client_serial)
+ dbus_uint32_t *serial)
{
_dbus_return_val_if_fail (connection != NULL, FALSE);
_dbus_return_val_if_fail (message != NULL, FALSE);
@@ -2958,7 +2961,7 @@
return _dbus_connection_send_and_unlock (connection,
message,
- client_serial);
+ serial);
}
static dbus_bool_t
Index: dbus-errors.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-errors.c,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -d -r1.31 -r1.32
--- dbus-errors.c 4 Aug 2006 16:15:16 -0000 1.31
+++ dbus-errors.c 21 Oct 2006 17:08:08 -0000 1.32
@@ -124,6 +124,9 @@
* }
* @endcode
*
+ * By convention, all functions allow #NULL instead of a DBusError*,
+ * so callers who don't care about the error can ignore it.
+ *
* There are some rules. An error passed to a D-Bus function must
* always be unset; you can't pass in an error that's already set. If
* a function has a return code indicating whether an error occurred,
@@ -137,13 +140,19 @@
* You can check the specific error that occurred using
* dbus_error_has_name().
*
+ * Errors will not be set for programming errors, such as passing
+ * invalid arguments to the libdbus API. Instead, libdbus will print
+ * warnings, exit on a failed assertion, or even crash in those cases
+ * (in other words, incorrect use of the API results in undefined
+ * behavior, possibly accompanied by helpful debugging output if
+ * you're lucky).
+ *
* @{
*/
/**
- * Initializes a DBusError structure. Does not allocate
- * any memory; the error only needs to be freed
- * if it is set at some point.
+ * Initializes a DBusError structure. Does not allocate any memory;
+ * the error only needs to be freed if it is set at some point.
*
* @param error the DBusError.
*/
@@ -190,11 +199,15 @@
/**
* Assigns an error name and message to a DBusError. Does nothing if
- * error is #NULL. The message may be NULL, which means a default
- * message will be deduced from the name. If the error name is unknown
- * to D-Bus the default message will be totally useless, though.
+ * error is #NULL. The message may be #NULL, which means a default
+ * message will be deduced from the name. The default message will be
+ * totally useless, though, so using a #NULL message is not recommended.
*
- * @param error the error.
+ * Because this function does not copy the error name or message, you
+ * must ensure the name and message are global data that won't be
+ * freed. You probably want dbus_set_error() instead, in most cases.
+ *
+ * @param error the error.or #NULL
* @param name the error name (not copied!!!)
* @param message the error message (not copied!!!)
*/
@@ -297,14 +310,15 @@
* Assigns an error name and message to a DBusError.
* Does nothing if error is #NULL.
*
- * The format may be NULL, which means a default message will be
- * deduced from the name. If the error name is unknown to D-Bus the
- * default message will be totally useless, though.
+ * The format may be #NULL, which means a (pretty much useless)
+ * default message will be deduced from the name. This is not a good
+ * idea, just go ahead and provide a useful error message. It won't
+ * hurt you.
*
* If no memory can be allocated for the error message,
* an out-of-memory error message will be set instead.
*
- * @param error the error.
+ * @param error the error.or #NULL
* @param name the error name
* @param format printf-style format string.
*/
Index: dbus-marshal-recursive.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-marshal-recursive.c,v
retrieving revision 1.54
retrieving revision 1.55
diff -u -d -r1.54 -r1.55
--- dbus-marshal-recursive.c 20 Oct 2006 03:04:59 -0000 1.54
+++ dbus-marshal-recursive.c 21 Oct 2006 17:08:08 -0000 1.55
@@ -560,7 +560,7 @@
_dbus_assert (reader->value_pos >= reader->u.array.start_pos);
switch (_dbus_first_type_in_signature (reader->type_str,
- reader->type_pos))
+ reader->type_pos))
{
case DBUS_TYPE_DICT_ENTRY:
case DBUS_TYPE_STRUCT:
@@ -875,10 +875,10 @@
}
/**
- * Returns the number of values remaining in the current array reader.
+ * Returns the number of bytes in the array.
*
* @param reader the reader to read from
- * @returns the number of elements remaining in the array
+ * @returns the number of bytes in the array
*/
int
_dbus_type_reader_get_array_length (const DBusTypeReader *reader)
Index: dbus-memory.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-memory.c,v
retrieving revision 1.27
retrieving revision 1.28
diff -u -d -r1.27 -r1.28
--- dbus-memory.c 3 Aug 2006 20:34:36 -0000 1.27
+++ dbus-memory.c 21 Oct 2006 17:08:08 -0000 1.28
@@ -430,6 +430,9 @@
* on all platforms. Returns #NULL if the allocation fails.
* The memory must be released with dbus_free().
*
+ * dbus_malloc() memory is NOT safe to free with regular free() from
+ * the C library. Free it with dbus_free() only.
+ *
* @param bytes number of bytes to allocate
* @return allocated memory, or #NULL if the allocation fails.
*/
@@ -481,6 +484,9 @@
* return #NULL if bytes is zero on all platforms. Returns #NULL if the
* allocation fails. The memory must be released with dbus_free().
*
+ * dbus_malloc0() memory is NOT safe to free with regular free() from
+ * the C library. Free it with dbus_free() only.
+ *
* @param bytes number of bytes to allocate
* @return allocated memory, or #NULL if the allocation fails.
*/
@@ -741,16 +747,41 @@
*/
/**
- * The D-Bus library keeps some internal global variables, for example
- * to cache the username of the current process. This function is
- * used to free these global variables. It is really useful only for
- * leak-checking cleanliness and the like. WARNING: this function is
- * NOT thread safe, it must be called while NO other threads are using
- * D-Bus. You cannot continue using D-Bus after calling this function,
- * as it does things like free global mutexes created by
- * dbus_threads_init(). To use a D-Bus function after calling
- * dbus_shutdown(), you have to start over from scratch, e.g. calling
- * dbus_threads_init() again.
+ * Frees all memory allocated internally by libdbus and
+ * reverses the effects of dbus_threads_init(). libdbus keeps internal
+ * global variables, for example caches and thread locks, and it
+ * can be useful to free these internal data structures.
+ *
+ * dbus_shutdown() does NOT free memory that was returned
+ * to the application. It only returns libdbus-internal
+ * data structures.
+ *
+ * You MUST free all memory and release all reference counts
+ * returned to you by libdbus prior to calling dbus_shutdown().
+ *
+ * You can't continue to use any D-Bus objects, such as connections,
+ * that were allocated prior to dbus_shutdown(). You can, however,
+ * start over; call dbus_threads_init() again, create new connections,
+ * and so forth.
+ *
+ * WARNING: dbus_shutdown() is NOT thread safe, it must be called
+ * while NO other threads are using D-Bus. (Remember, you have to free
+ * all D-Bus objects and memory before you call dbus_shutdown(), so no
+ * thread can be using libdbus.)
+ *
+ * The purpose of dbus_shutdown() is to allow applications to get
+ * clean output from memory leak checkers. dbus_shutdown() may also be
+ * useful if you want to dlopen() libdbus instead of linking to it,
+ * and want to be able to unload the library again.
+ *
+ * There is absolutely no requirement to call dbus_shutdown() - in fact,
+ * most applications won't bother and should not feel guilty.
+ *
+ * You have to know that nobody is using libdbus in your application's
+ * process before you can call dbus_shutdown(). One implication of this
+ * is that calling dbus_shutdown() from a library is almost certainly
+ * wrong, since you don't know what the rest of the app is up to.
+ *
*/
void
dbus_shutdown (void)
Index: dbus-message.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-message.c,v
retrieving revision 1.179
retrieving revision 1.180
diff -u -d -r1.179 -r1.180
--- dbus-message.c 20 Oct 2006 05:16:58 -0000 1.179
+++ dbus-message.c 21 Oct 2006 17:08:08 -0000 1.180
@@ -579,18 +579,229 @@
dbus_message_finalize (message);
}
+/**
+ * Implementation of the varargs arg-getting functions.
+ * dbus_message_get_args() is the place to go for complete
+ * documentation.
+ *
+ * @see dbus_message_get_args
+ * @param iter the message iter
+ * @param error error to be filled in
+ * @param first_arg_type type of the first argument
+ * @param var_args return location for first argument, followed by list of type/location pairs
+ * @returns #FALSE if error was set
+ */
+dbus_bool_t
+_dbus_message_iter_get_args_valist (DBusMessageIter *iter,
+ DBusError *error,
+ int first_arg_type,
+ va_list var_args)
+{
+ DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
+ int spec_type, msg_type, i;
+ dbus_bool_t retval;
+
+ _dbus_assert (_dbus_message_iter_check (real));
+
+ retval = FALSE;
+
+ spec_type = first_arg_type;
+ i = 0;
+
+ while (spec_type != DBUS_TYPE_INVALID)
+ {
+ msg_type = dbus_message_iter_get_arg_type (iter);
+
+ if (msg_type != spec_type)
+ {
+ dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
+ "Argument %d is specified to be of type \"%s\", but "
+ "is actually of type \"%s\"\n", i,
+ _dbus_type_to_string (spec_type),
+ _dbus_type_to_string (msg_type));
+
+ goto out;
+ }
+
+ if (dbus_type_is_basic (spec_type))
+ {
+ DBusBasicValue *ptr;
+
+ ptr = va_arg (var_args, DBusBasicValue*);
+
+ _dbus_assert (ptr != NULL);
+
+ _dbus_type_reader_read_basic (&real->u.reader,
+ ptr);
+ }
+ else if (spec_type == DBUS_TYPE_ARRAY)
+ {
+ int element_type;
+ int spec_element_type;
+ const DBusBasicValue **ptr;
+ int *n_elements_p;
+ DBusTypeReader array;
+
+ spec_element_type = va_arg (var_args, int);
+ element_type = _dbus_type_reader_get_element_type (&real->u.reader);
+
+ if (spec_element_type != element_type)
+ {
+ dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
+ "Argument %d is specified to be an array of \"%s\", but "
+ "is actually an array of \"%s\"\n",
+ i,
+ _dbus_type_to_string (spec_element_type),
+ _dbus_type_to_string (element_type));
+
+ goto out;
+ }
+
+ if (dbus_type_is_fixed (spec_element_type))
+ {
+ ptr = va_arg (var_args, const DBusBasicValue**);
+ n_elements_p = va_arg (var_args, int*);
+
+ _dbus_assert (ptr != NULL);
+ _dbus_assert (n_elements_p != NULL);
+
+ _dbus_type_reader_recurse (&real->u.reader, &array);
+
+ _dbus_type_reader_read_fixed_multi (&array,
+ ptr, n_elements_p);
+ }
+ else if (spec_element_type == DBUS_TYPE_STRING ||
+ spec_element_type == DBUS_TYPE_SIGNATURE ||
+ spec_element_type == DBUS_TYPE_OBJECT_PATH)
+ {
+ char ***str_array_p;
+ int n_elements;
+ char **str_array;
+
+ str_array_p = va_arg (var_args, char***);
+ n_elements_p = va_arg (var_args, int*);
+
+ _dbus_assert (str_array_p != NULL);
+ _dbus_assert (n_elements_p != NULL);
+
+ /* Count elements in the array */
+ _dbus_type_reader_recurse (&real->u.reader, &array);
+
+ n_elements = 0;
+ while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
+ {
+ ++n_elements;
+ _dbus_type_reader_next (&array);
+ }
+
+ str_array = dbus_new0 (char*, n_elements + 1);
+ if (str_array == NULL)
+ {
+ _DBUS_SET_OOM (error);
+ goto out;
+ }
+
+ /* Now go through and dup each string */
+ _dbus_type_reader_recurse (&real->u.reader, &array);
+
+ i = 0;
+ while (i < n_elements)
+ {
+ const char *s;
+ _dbus_type_reader_read_basic (&array,
+ &s);
+
+ str_array[i] = _dbus_strdup (s);
+ if (str_array[i] == NULL)
+ {
+ dbus_free_string_array (str_array);
+ _DBUS_SET_OOM (error);
+ goto out;
+ }
+
+ ++i;
+
+ if (!_dbus_type_reader_next (&array))
+ _dbus_assert (i == n_elements);
+ }
+
+ _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
+ _dbus_assert (i == n_elements);
+ _dbus_assert (str_array[i] == NULL);
+
+ *str_array_p = str_array;
+ *n_elements_p = n_elements;
+ }
+#ifndef DBUS_DISABLE_CHECKS
+ else
+ {
+ _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
+ _DBUS_FUNCTION_NAME);
+ goto out;
+ }
+#endif
+ }
+#ifndef DBUS_DISABLE_CHECKS
+ else
+ {
+ _dbus_warn ("you can only read arrays and basic types with %s for now\n",
+ _DBUS_FUNCTION_NAME);
+ goto out;
+ }
+#endif
+
+ spec_type = va_arg (var_args, int);
+ if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
+ {
+ dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
+ "Message has only %d arguments, but more were expected", i);
+ goto out;
+ }
+
+ i++;
+ }
+
+ retval = TRUE;
+
+ out:
+
+ return retval;
+}
+
/** @} */
/**
* @defgroup DBusMessage DBusMessage
* @ingroup DBus
- * @brief Message to be sent or received over a DBusConnection.
+ * @brief Message to be sent or received over a #DBusConnection.
*
* A DBusMessage is the most basic unit of communication over a
* DBusConnection. A DBusConnection represents a stream of messages
* received from a remote application, and a stream of messages
* sent to a remote application.
*
+ * A message has a message type, returned from
+ * dbus_message_get_type(). This indicates whether the message is a
+ * method call, a reply to a method call, a signal, or an error reply.
+ *
+ * A message has header fields such as the sender, destination, method
+ * or signal name, and so forth. DBusMessage has accessor functions for
+ * these, such as dbus_message_get_member().
+ *
+ * Convenience functions dbus_message_is_method_call(), dbus_message_is_signal(),
+ * and dbus_message_is_error() check several header fields at once and are
+ * slightly more efficient than checking the header fields with individual
+ * accessor functions.
+ *
+ * Finally, a message has arguments. The number and types of arguments
+ * are in the message's signature header field (accessed with
+ * dbus_message_get_signature()). Simple argument values are usually
+ * retrieved with dbus_message_get_args() but more complex values such
+ * as structs may require the use of #DBusMessageIter.
+ *
+ * The D-Bus specification goes into some more detail about header fields and
+ * message types.
+ *
* @{
*/
@@ -604,12 +815,16 @@
/**
* Returns the serial of a message or 0 if none has been specified.
* The message's serial number is provided by the application sending
- * the message and is used to identify replies to this message. All
- * messages received on a connection will have a serial, but messages
- * you haven't sent yet may return 0.
+ * the message and is used to identify replies to this message.
+ *
+ * All messages received on a connection will have a serial provided
+ * by the remote application.
+ *
+ * For messages you're sending, dbus_connection_send() will assign a
+ * serial and return it to you.
*
* @param message the message
- * @returns the client serial
+ * @returns the serial
*/
dbus_uint32_t
dbus_message_get_serial (DBusMessage *message)
@@ -620,11 +835,11 @@
}
/**
- * Sets the reply serial of a message (the client serial
- * of the message this is a reply to).
+ * Sets the reply serial of a message (the serial of the message this
+ * is a reply to).
*
* @param message the message
- * @param reply_serial the client serial
+ * @param reply_serial the serial we're replying to
* @returns #FALSE if not enough memory
*/
dbus_bool_t
@@ -748,8 +963,12 @@
* Types include #DBUS_MESSAGE_TYPE_METHOD_CALL,
* #DBUS_MESSAGE_TYPE_SIGNAL, and so forth.
*
+ * Usually you want to use dbus_message_new_method_call(),
+ * dbus_message_new_method_return(), dbus_message_new_signal(),
+ * or dbus_message_new_error() instead.
+ *
* @param message_type type of message
- * @returns new message or #NULL If no memory
+ * @returns new message or #NULL if no memory
*/
DBusMessage*
dbus_message_new (int message_type)
@@ -781,14 +1000,18 @@
* context (no message bus). The interface may be #NULL, which means
* that if multiple methods with the given name exist it is undefined
* which one will be invoked.
- *
+ *
+ * The path and method names may not be #NULL.
+ *
+ * Destination, path, interface, and method name can't contain
+ * any invalid characters (see the D-Bus specification).
+ *
* @param destination name that the message should be sent to or #NULL
* @param path object path the message should be sent to
- * @param interface interface to invoke method on
+ * @param interface interface to invoke method on, or #NULL
* @param method method to invoke
*
* @returns a new DBusMessage, free with dbus_message_unref()
- * @see dbus_message_unref()
*/
DBusMessage*
dbus_message_new_method_call (const char *destination,
@@ -826,10 +1049,8 @@
* Constructs a message that is a reply to a method call. Returns
* #NULL if memory can't be allocated for the message.
*
- * @param method_call the message which the created
- * message is a reply to.
+ * @param method_call the message being replied to
* @returns a new DBusMessage, free with dbus_message_unref()
- * @see dbus_message_new_method_call(), dbus_message_unref()
*/
DBusMessage*
dbus_message_new_method_return (DBusMessage *method_call)
@@ -870,14 +1091,16 @@
/**
* Constructs a new message representing a signal emission. Returns
* #NULL if memory can't be allocated for the message. A signal is
- * identified by its originating interface, and the name of the
- * signal.
+ * identified by its originating object path, interface, and the name
+ * of the signal.
*
+ * Path, interface, and signal name must all be valid (the D-Bus
+ * specification defines the syntax of these fields).
+ *
* @param path the path to the object emitting the signal
* @param interface the interface the signal is emitted from
* @param name name of the signal
* @returns a new DBusMessage, free with dbus_message_unref()
- * @see dbus_message_unref()
*/
DBusMessage*
dbus_message_new_signal (const char *path,
@@ -911,13 +1134,18 @@
}
/**
- * Creates a new message that is an error reply to a certain message.
- * Error replies are possible in response to method calls primarily.
+ * Creates a new message that is an error reply to another message.
+ * Error replies are most common in response to method calls, but
+ * can be returned in reply to any message.
*
- * @param reply_to the original message
+ * The error name must be a valid error name according to the syntax
+ * given in the D-Bus specification. If you don't want to make
+ * up an error name just use #DBUS_ERROR_FAILED.
+ *
+ * @param reply_to the message we're replying to
* @param error_name the error name
- * @param error_message the error message string or #NULL for none
- * @returns a new error message
+ * @param error_message the error message string (or #NULL for none, but please give a message)
+ * @returns a new error message object, free with dbus_message_unref()
*/
DBusMessage*
dbus_message_new_error (DBusMessage *reply_to,
@@ -975,8 +1203,11 @@
}
/**
- * Creates a new message that is an error reply to a certain message.
- * Error replies are possible in response to method calls primarily.
+ * Creates a new message that is an error reply to another message, allowing
+ * you to use printf formatting.
+ *
+ * See dbus_message_new_error() for details - this function is the same
+ * aside from the printf formatting.
*
* @param reply_to the original message
* @param error_name the error name
@@ -1024,8 +1255,8 @@
* outgoing message queue and thus not modifiable) the new message
* will not be locked.
*
- * @param message the message.
- * @returns the new message.
+ * @param message the message
+ * @returns the new message.or #NULL if not enough memory
*/
DBusMessage *
dbus_message_copy (const DBusMessage *message)
@@ -1077,7 +1308,7 @@
/**
* Increments the reference count of a DBusMessage.
*
- * @param message The message
+ * @param message the message
* @returns the message
* @see dbus_message_unref
*/
@@ -1097,9 +1328,10 @@
}
/**
- * Decrements the reference count of a DBusMessage.
+ * Decrements the reference count of a DBusMessage, freeing the
+ * message if the count reaches 0.
*
- * @param message The message
+ * @param message the message
* @see dbus_message_ref
*/
void
@@ -1127,8 +1359,7 @@
* #DBUS_MESSAGE_TYPE_METHOD_CALL, #DBUS_MESSAGE_TYPE_METHOD_RETURN,
* #DBUS_MESSAGE_TYPE_ERROR, #DBUS_MESSAGE_TYPE_SIGNAL, but other
* types are allowed and all code must silently ignore messages of
- * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned,
- * however.
+ * unknown type. #DBUS_MESSAGE_TYPE_INVALID will never be returned.
*
* @param message the message
* @returns the type of the message
@@ -1156,8 +1387,10 @@
*
* dbus_int32_t v_INT32 = 42;
* const char *v_STRING = "Hello World";
- * DBUS_TYPE_INT32, &v_INT32,
- * DBUS_TYPE_STRING, &v_STRING,
+ * dbus_message_append_args (message,
+ * DBUS_TYPE_INT32, &v_INT32,
+ * DBUS_TYPE_STRING, &v_STRING,
+ * DBUS_TYPE_INVALID);
* @endcode
*
* To append an array of fixed-length basic types, pass in the
@@ -1167,7 +1400,9 @@
* @code
* const dbus_int32_t array[] = { 1, 2, 3 };
* const dbus_int32_t *v_ARRAY = array;
- * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3
+ * dbus_message_append_args (message,
+ * DBUS_TYPE_ARRAY, DBUS_TYPE_INT32, &v_ARRAY, 3,
+ * DBUS_TYPE_INVALID);
* @endcode
*
* @warning in C, given "int array[]", "&array == array" (the
@@ -1178,7 +1413,8 @@
* const char *array = "Hello" and then use &array though.
*
* The last argument to this function must be #DBUS_TYPE_INVALID,
- * marking the end of the argument list.
+ * marking the end of the argument list. If you don't do this
+ * then libdbus won't know to stop and will read invalid memory.
*
* String/signature/path arrays should be passed in as "const char***
* address_of_array" and "int n_elements"
@@ -1213,8 +1449,7 @@
}
/**
- * This function takes a va_list for use by language bindings.
- * It's otherwise the same as dbus_message_append_args().
+ * Like dbus_message_append_args() but takes a va_list for use by language bindings.
*
* @todo for now, if this function fails due to OOM it will leave
* the message half-written and you have to discard the message
@@ -1353,12 +1588,15 @@
* followed by a pointer to where the value should be stored. The list
* is terminated with #DBUS_TYPE_INVALID.
*
- * The returned values are constant; do not free them. They point
- * into the #DBusMessage.
+ * Except for string arrays, the returned values are constant; do not
+ * free them. They point into the #DBusMessage.
*
* If the requested arguments are not present, or do not have the
* requested types, then an error will be set.
*
+ * If more arguments than requested are present, the requested
+ * arguments are returned and the extra arguments are ignored.
+ *
* @todo support DBUS_TYPE_STRUCT and DBUS_TYPE_VARIANT and complex arrays
*
* @param message the message
@@ -1387,8 +1625,7 @@
}
/**
- * This function takes a va_list for use by language bindings. It is
- * otherwise the same as dbus_message_get_args().
+ * Like dbus_message_get_args but takes a va_list for use by language bindings.
*
* @see dbus_message_get_args
* @param message the message
@@ -1434,6 +1671,20 @@
* Initializes a #DBusMessageIter for reading the arguments of the
* message passed in.
*
+ * When possible, dbus_message_get_args() is much more convenient.
+ * Some types of argument can only be read with #DBusMessageIter
+ * however.
+ *
+ * The easiest way to iterate is like this:
+ * @code
+ * dbus_message_iter_init (&iter);
+ * while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
+ * dbus_message_iter_next (&iter);
+ * @endcode
+ *
+ * #DBusMessageIter contains no allocated memory; it need not be
+ * freed, and can be copied by assignment or memcpy().
+ *
* @param message the message
* @param iter pointer to an iterator to initialize
* @returns #FALSE if the message has no arguments
@@ -1469,7 +1720,7 @@
{
if (iter == NULL)
{
- _dbus_warn ("dbus message iterator is NULL\n");
+ _dbus_warn_check_failed ("dbus message iterator is NULL\n");
return FALSE;
}
@@ -1477,7 +1728,7 @@
{
if (iter->u.reader.byte_order != iter->message->byte_order)
{
- _dbus_warn ("dbus message changed byte order since iterator was created\n");
+ _dbus_warn_check_failed ("dbus message changed byte order since iterator was created\n");
return FALSE;
}
/* because we swap the message into compiler order when you init an iter */
@@ -1487,7 +1738,7 @@
{
if (iter->u.writer.byte_order != iter->message->byte_order)
{
- _dbus_warn ("dbus message changed byte order since append iterator was created\n");
+ _dbus_warn_check_failed ("dbus message changed byte order since append iterator was created\n");
return FALSE;
}
/* because we swap the message into compiler order when you init an iter */
@@ -1495,13 +1746,13 @@
}
else
{
- _dbus_warn ("dbus message iterator looks uninitialized or corrupted\n");
+ _dbus_warn_check_failed ("dbus message iterator looks uninitialized or corrupted\n");
return FALSE;
}
if (iter->changed_stamp != iter->message->changed_stamp)
{
- _dbus_warn ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
+ _dbus_warn_check_failed ("dbus message iterator invalid because the message has been modified (or perhaps the iterator is just uninitialized)\n");
return FALSE;
}
@@ -1513,8 +1764,7 @@
* Checks if an iterator has any more fields.
*
* @param iter the message iter
- * @returns #TRUE if there are more fields
- * following
+ * @returns #TRUE if there are more fields following
*/
dbus_bool_t
dbus_message_iter_has_next (DBusMessageIter *iter)
@@ -1626,6 +1876,8 @@
* recurse into a variant and determine the signature of
* the variant's value.
*
+ * The returned string must be freed with dbus_free().
+ *
* @param iter the message iterator
* @returns the contained signature, or NULL if out of memory
*/
@@ -1677,10 +1929,12 @@
* #endif
* @endcode
*
- * To avoid the #DBUS_HAVE_INT64 conditional, create a struct or
- * something that occupies at least 8 bytes, e.g. you could use a
- * struct with two int32 values in it. dbus_uint64_t is just one
- * example of a type that's large enough to hold any possible value.
+ * You can skip the #DBUS_HAVE_INT64 conditional unless you care about
+ * some sort of really obscure platform. If you do know about such a
+ * platform and want your code to work on it, create a struct
+ * that occupies at least 8 bytes. dbus_uint64_t is just
+ * one example of a type that's large enough to hold any possible
+ * value.
*
* Be sure you have somehow checked that
* dbus_message_iter_get_arg_type() matches the type you are
@@ -1704,10 +1958,22 @@
}
/**
- * Returns the number of elements in the array;
+ * Returns the number of bytes in the array as marshaled in the wire
+ * protocol. The iterator must currently be inside an array-typed
+ * value.
+ *
+ * This function is deprecated on the grounds that it is stupid. Why
+ * would you want to know how many bytes are in the array as marshaled
+ * in the wire protocol? For now, use the n_elements returned from
+ * dbus_message_iter_get_fixed_array() instead, or iterate over the
+ * array values and count them.
*
+ * @todo introduce a variant of this get_n_elements that returns
+ * the number of elements, though with a non-fixed array it will not
+ * be very efficient, so maybe it's not good.
+ *
* @param iter the iterator
- * @returns the number of elements in the array
+ * @returns the number of bytes in the array
*/
int
dbus_message_iter_get_array_len (DBusMessageIter *iter)
@@ -1725,13 +1991,17 @@
* such as integers, bool, double. The block read will be from the
* current position in the array until the end of the array.
*
- * This function should only be used if #dbus_type_is_fixed returns
+ * This function should only be used if dbus_type_is_fixed() returns
* #TRUE for the element type.
*
* The value argument should be the address of a location to store the
* returned array. So for int32 it should be a "const dbus_int32_t**"
* The returned value is by reference and should not be freed.
*
+ * Because the array is not copied, this function runs in
+ * constant time and is fast; it's much preferred over walking the
+ * entire array with an iterator.
+ *
* @param iter the iterator
* @param value location to store the block
* @param n_elements number of elements in the block
@@ -1754,202 +2024,12 @@
}
/**
- * This function takes a va_list for use by language bindings and is
- * otherwise the same as dbus_message_iter_get_args().
- * dbus_message_get_args() is the place to go for complete
- * documentation.
- *
- * @see dbus_message_get_args
- * @param iter the message iter
- * @param error error to be filled in
- * @param first_arg_type type of the first argument
- * @param var_args return location for first argument, followed by list of type/location pairs
- * @returns #FALSE if error was set
- */
-dbus_bool_t
-_dbus_message_iter_get_args_valist (DBusMessageIter *iter,
- DBusError *error,
- int first_arg_type,
- va_list var_args)
-{
- DBusMessageRealIter *real = (DBusMessageRealIter *)iter;
- int spec_type, msg_type, i;
- dbus_bool_t retval;
-
- _dbus_assert (_dbus_message_iter_check (real));
-
- retval = FALSE;
-
- spec_type = first_arg_type;
- i = 0;
-
- while (spec_type != DBUS_TYPE_INVALID)
- {
- msg_type = dbus_message_iter_get_arg_type (iter);
-
- if (msg_type != spec_type)
- {
- dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
- "Argument %d is specified to be of type \"%s\", but "
- "is actually of type \"%s\"\n", i,
- _dbus_type_to_string (spec_type),
- _dbus_type_to_string (msg_type));
-
- goto out;
- }
-
- if (dbus_type_is_basic (spec_type))
- {
- DBusBasicValue *ptr;
-
- ptr = va_arg (var_args, DBusBasicValue*);
-
- _dbus_assert (ptr != NULL);
-
- _dbus_type_reader_read_basic (&real->u.reader,
- ptr);
- }
- else if (spec_type == DBUS_TYPE_ARRAY)
- {
- int element_type;
- int spec_element_type;
- const DBusBasicValue **ptr;
- int *n_elements_p;
- DBusTypeReader array;
-
- spec_element_type = va_arg (var_args, int);
- element_type = _dbus_type_reader_get_element_type (&real->u.reader);
-
- if (spec_element_type != element_type)
- {
- dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
- "Argument %d is specified to be an array of \"%s\", but "
- "is actually an array of \"%s\"\n",
- i,
- _dbus_type_to_string (spec_element_type),
- _dbus_type_to_string (element_type));
-
- goto out;
- }
-
- if (dbus_type_is_fixed (spec_element_type))
- {
- ptr = va_arg (var_args, const DBusBasicValue**);
- n_elements_p = va_arg (var_args, int*);
-
- _dbus_assert (ptr != NULL);
- _dbus_assert (n_elements_p != NULL);
-
- _dbus_type_reader_recurse (&real->u.reader, &array);
-
- _dbus_type_reader_read_fixed_multi (&array,
- ptr, n_elements_p);
- }
- else if (spec_element_type == DBUS_TYPE_STRING ||
- spec_element_type == DBUS_TYPE_SIGNATURE ||
- spec_element_type == DBUS_TYPE_OBJECT_PATH)
- {
- char ***str_array_p;
- int n_elements;
- char **str_array;
-
- str_array_p = va_arg (var_args, char***);
- n_elements_p = va_arg (var_args, int*);
-
- _dbus_assert (str_array_p != NULL);
- _dbus_assert (n_elements_p != NULL);
-
- /* Count elements in the array */
- _dbus_type_reader_recurse (&real->u.reader, &array);
-
- n_elements = 0;
- while (_dbus_type_reader_get_current_type (&array) != DBUS_TYPE_INVALID)
- {
- ++n_elements;
- _dbus_type_reader_next (&array);
- }
-
- str_array = dbus_new0 (char*, n_elements + 1);
- if (str_array == NULL)
- {
- _DBUS_SET_OOM (error);
- goto out;
- }
-
- /* Now go through and dup each string */
- _dbus_type_reader_recurse (&real->u.reader, &array);
-
- i = 0;
- while (i < n_elements)
- {
- const char *s;
- _dbus_type_reader_read_basic (&array,
- &s);
-
- str_array[i] = _dbus_strdup (s);
- if (str_array[i] == NULL)
- {
- dbus_free_string_array (str_array);
- _DBUS_SET_OOM (error);
- goto out;
- }
-
- ++i;
-
- if (!_dbus_type_reader_next (&array))
- _dbus_assert (i == n_elements);
- }
-
- _dbus_assert (_dbus_type_reader_get_current_type (&array) == DBUS_TYPE_INVALID);
- _dbus_assert (i == n_elements);
- _dbus_assert (str_array[i] == NULL);
-
- *str_array_p = str_array;
- *n_elements_p = n_elements;
- }
-#ifndef DBUS_DISABLE_CHECKS
- else
- {
- _dbus_warn ("you can't read arrays of container types (struct, variant, array) with %s for now\n",
- _DBUS_FUNCTION_NAME);
- goto out;
- }
-#endif
- }
-#ifndef DBUS_DISABLE_CHECKS
- else
- {
- _dbus_warn ("you can only read arrays and basic types with %s for now\n",
- _DBUS_FUNCTION_NAME);
- goto out;
- }
-#endif
-
- spec_type = va_arg (var_args, int);
- if (!_dbus_type_reader_next (&real->u.reader) && spec_type != DBUS_TYPE_INVALID)
- {
- dbus_set_error (error, DBUS_ERROR_INVALID_ARGS,
- "Message has only %d arguments, but more were expected", i);
- goto out;
- }
-
- i++;
- }
-
- retval = TRUE;
-
- out:
-
- return retval;
-}
-
-/**
* Initializes a #DBusMessageIter for appending arguments to the end
* of a message.
*
* @todo If appending any of the arguments fails due to lack of
- * memory, generally the message is hosed and you have to start over
- * building the whole message.
+ * memory, the message is hosed and you have to start over building
+ * the whole message.
*
* @param message the message
* @param iter pointer to an iterator to initialize
@@ -2099,7 +2179,7 @@
if (iter->message->locked)
{
- _dbus_warn ("dbus append iterator can't be used: message is locked (has already been sent)\n");
+ _dbus_warn_check_failed ("dbus append iterator can't be used: message is locked (has already been sent)\n");
return FALSE;
}
@@ -2322,6 +2402,11 @@
* message successfully arrived at the remote end. Normally you know a
* message was received when you receive the reply to it.
*
+ * The flag is #FALSE by default, that is by default the other end is
+ * required to reply.
+ *
+ * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_REPLY_EXPECTED
+ *
* @param message the message
* @param no_reply #TRUE if no reply is desired
*/
@@ -2360,6 +2445,10 @@
* starting up, or fails to start up. In case of failure, the reply
* will be an error.
*
+ * The flag is set to #TRUE by default, i.e. auto starting is the default.
+ *
+ * On the protocol level this toggles #DBUS_HEADER_FLAG_NO_AUTO_START
+ *
* @param message the message
* @param auto_start #TRUE if auto-starting is desired
*/
@@ -2397,6 +2486,9 @@
* DBUS_MESSAGE_TYPE_METHOD_CALL) or the one a signal is being
* emitted from (for DBUS_MESSAGE_TYPE_SIGNAL).
*
+ * The path must contain only valid characters as defined
+ * in the D-Bus specification.
+ *
* @param message the message
* @param object_path the path or #NULL to unset
* @returns #FALSE if not enough memory
@@ -2422,6 +2514,11 @@
* DBUS_MESSAGE_TYPE_METHOD_CALL) or being emitted from (for
* DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
*
+ * See also dbus_message_get_path_decomposed().
+ *
+ * The returned string becomes invalid if the message is
+ * modified, since it points into the wire-marshaled message data.
+ *
* @param message the message
* @returns the path (should not be freed) or #NULL
*/
@@ -2441,7 +2538,9 @@
}
/**
- * Checks if the message has a path
+ * Checks if the message has a particular object path. The object
+ * path is the destination object for a method call or the emitting
+ * object for a signal.
*
* @param message the message
* @param path the path name
@@ -2482,6 +2581,8 @@
* So the path "/foo/bar" becomes { "foo", "bar", NULL }
* and the path "/" becomes { NULL }.
*
+ * See also dbus_message_get_path().
+ *
* @todo this could be optimized by using the len from the message
* instead of calling strlen() again
*
@@ -2516,6 +2617,9 @@
* the interface a signal is being emitted from
* (for DBUS_MESSAGE_TYPE_SIGNAL).
*
+ * The interface name must contain only valid characters as defined
+ * in the D-Bus specification.
+ *
* @param message the message
* @param interface the interface or #NULL to unset
* @returns #FALSE if not enough memory
@@ -2543,6 +2647,9 @@
* The interface name is fully-qualified (namespaced).
* Returns #NULL if none.
*
+ * The returned string becomes invalid if the message is
+ * modified, since it points into the wire-marshaled message data.
+ *
* @param message the message
* @returns the message interface (should not be freed) or #NULL
*/
@@ -2566,7 +2673,7 @@
*
* @param message the message
* @param interface the interface name
- * @returns #TRUE if there is a interface field in the header
+ * @returns #TRUE if the interface field in the header matches
*/
dbus_bool_t
dbus_message_has_interface (DBusMessage *message,
@@ -2597,7 +2704,9 @@
* Sets the interface member being invoked
* (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
* (DBUS_MESSAGE_TYPE_SIGNAL).
- * The interface name is fully-qualified (namespaced).
+ *
+ * The member name must contain only valid characters as defined
+ * in the D-Bus specification.
*
* @param message the message
* @param member the member or #NULL to unset
@@ -2624,6 +2733,9 @@
* (DBUS_MESSAGE_TYPE_METHOD_CALL) or emitted
* (DBUS_MESSAGE_TYPE_SIGNAL). Returns #NULL if none.
*
+ * The returned string becomes invalid if the message is
+ * modified, since it points into the wire-marshaled message data.
+ *
* @param message the message
* @returns the member name (should not be freed) or #NULL
*/
@@ -2678,6 +2790,9 @@
* Sets the name of the error (DBUS_MESSAGE_TYPE_ERROR).
* The name is fully-qualified (namespaced).
*
+ * The error name must contain only valid characters as defined
+ * in the D-Bus specification.
+ *
* @param message the message
* @param error_name the name or #NULL to unset
* @returns #FALSE if not enough memory
@@ -2702,6 +2817,9 @@
* Gets the error name (DBUS_MESSAGE_TYPE_ERROR only)
* or #NULL if none.
*
+ * The returned string becomes invalid if the message is
+ * modified, since it points into the wire-marshaled message data.
+ *
* @param message the message
* @returns the error name (should not be freed) or #NULL
*/
@@ -2726,6 +2844,9 @@
* assigned by the bus to each connection, or a well-known name
* specified in advance.
*
+ * The destination name must contain only valid characters as defined
+ * in the D-Bus specification.
+ *
* @param message the message
* @param destination the destination name or #NULL to unset
* @returns #FALSE if not enough memory
@@ -2749,6 +2870,9 @@
/**
* Gets the destination of a message or #NULL if there is none set.
*
+ * The returned string becomes invalid if the message is
+ * modified, since it points into the wire-marshaled message data.
+ *
* @param message the message
* @returns the message destination (should not be freed) or #NULL
*/
@@ -2770,6 +2894,13 @@
/**
* Sets the message sender.
*
+ * The sender must be a valid bus name as defined in the D-Bus
+ * specification.
+ *
+ * Usually you don't want to call this. The message bus daemon will
+ * call it to set the origin of each message. If you aren't implementing
+ * a message bus daemon you shouldn't need to set the sender.
+ *
* @param message the message
* @param sender the sender or #NULL to unset
* @returns #FALSE if not enough memory
@@ -2795,6 +2926,13 @@
* message, or #NULL if unknown or inapplicable. The sender is filled
* in by the message bus.
*
+ * Note, the returned sender is always the unique bus name.
+ * Connections may own multiple other bus names, but those
+ * are not found in the sender field.
+ *
+ * The returned string becomes invalid if the message is
+ * modified, since it points into the wire-marshaled message data.
+ *
* @param message the message
* @returns the unique name of the sender or #NULL
*/
@@ -2818,13 +2956,16 @@
* message payload. The signature includes only "in" arguments for
* #DBUS_MESSAGE_TYPE_METHOD_CALL and only "out" arguments for
* #DBUS_MESSAGE_TYPE_METHOD_RETURN, so is slightly different from
- * what you might expect (it does not include the signature of the
+ * what you might expect (that is, it does not include the signature of the
* entire C++-style method).
*
* The signature is a string made up of type codes such as
* #DBUS_TYPE_INT32. The string is terminated with nul (nul is also
* the value of #DBUS_TYPE_INVALID).
*
+ * The returned string becomes invalid if the message is
+ * modified, since it points into the wire-marshaled message data.
+ *
* @param message the message
* @returns the type signature
*/
@@ -2907,9 +3048,7 @@
/**
* Checks whether the message is a signal with the given interface and
* member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or
- * has a different interface or member field, returns #FALSE. If the
- * interface field in the message is missing, it is assumed to match
- * any interface you pass in to this function.
+ * has a different interface or member field, returns #FALSE.
*
* @param message the message
* @param interface the name to check (must not be #NULL)
@@ -3064,7 +3203,7 @@
/**
* Sets a #DBusError based on the contents of the given
* message. The error is only set if the message
- * is an error message, as in DBUS_MESSAGE_TYPE_ERROR.
+ * is an error message, as in #DBUS_MESSAGE_TYPE_ERROR.
* The name of the error is set to the name of the message,
* and the error message is set to the first argument
* if the argument exists and is a string.
@@ -3081,7 +3220,7 @@
*
* @param error the error to set
* @param message the message to set it from
- * @returns #TRUE if dbus_message_get_is_error() returns #TRUE for the message
+ * @returns #TRUE if the message had type #DBUS_MESSAGE_TYPE_ERROR
*/
dbus_bool_t
dbus_set_error_from_message (DBusError *error,
Index: dbus-message.h
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-message.h,v
retrieving revision 1.61
retrieving revision 1.62
diff -u -d -r1.61 -r1.62
--- dbus-message.h 15 Jun 2005 15:59:57 -0000 1.61
+++ dbus-message.h 21 Oct 2006 17:08:08 -0000 1.62
@@ -163,7 +163,12 @@
DBusMessageIter *sub);
void dbus_message_iter_get_basic (DBusMessageIter *iter,
void *value);
+#ifndef DBUS_DISABLE_DEPRECATED
+/* This function returns the wire protocol size of the array in bytes,
+ * you do not want to know that probably
+ */
int dbus_message_iter_get_array_len (DBusMessageIter *iter);
+#endif
void dbus_message_iter_get_fixed_array (DBusMessageIter *iter,
void *value,
int *n_elements);
Index: dbus-timeout.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-timeout.c,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17
--- dbus-timeout.c 3 Aug 2006 20:34:36 -0000 1.16
+++ dbus-timeout.c 21 Oct 2006 17:08:08 -0000 1.17
@@ -384,6 +384,9 @@
* Types and functions related to DBusTimeout. A timeout
* represents a timeout that the main loop needs to monitor,
* as in Qt's QTimer or GLib's g_timeout_add().
+ *
+ * Use dbus_connection_set_timeout_functions() or dbus_server_set_timeout_functions()
+ * to be notified when libdbus needs to add or remove timeouts.
*
* @{
*/
Index: dbus-watch.c
===================================================================
RCS file: /cvs/dbus/dbus/dbus/dbus-watch.c,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -d -r1.20 -r1.21
--- dbus-watch.c 17 Oct 2006 20:52:13 -0000 1.20
+++ dbus-watch.c 21 Oct 2006 17:08:08 -0000 1.21
@@ -465,6 +465,9 @@
* Types and functions related to DBusWatch. A watch represents
* a file descriptor that the main loop needs to monitor,
* as in Qt's QSocketNotifier or GLib's g_io_add_watch().
+ *
+ * Use dbus_connection_set_watch_functions() or dbus_server_set_watch_functions()
+ * to be notified when libdbus needs to add or remove watches.
*
* @{
*/
More information about the dbus-commit
mailing list