From e0b284c7e38f0c002b2173d85ab89dc18700867c Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Fri, 18 Apr 2003 05:52:11 +0000 Subject: 2003-04-18 Havoc Pennington * dbus/dbus-mainloop.c (_dbus_loop_iterate): fix UMR in verbose debug spew * dbus/dbus-auth.c (handle_client_data_cookie_sha1_mech): fix OOM handling problem * dbus/dbus-keyring.c (_dbus_keyring_new_homedir): only whine about DBUS_TEST_HOMEDIR once * bus/Makefile.am (TESTS_ENVIRONMENT): put DBUS_TEST_HOMEDIR in the environment * bus/dispatch.c (bus_dispatch_sha1_test): actually load sha1 config file so we test the right thing Throughout: assorted docs improvements --- dbus/dbus-auth.c | 2 +- dbus/dbus-connection.c | 103 +++++++++++++++++++++++++++++++++++++++++-------- dbus/dbus-errors.c | 36 ++++++++++++----- dbus/dbus-keyring.c | 7 +++- dbus/dbus-mainloop.c | 4 +- 5 files changed, 123 insertions(+), 29 deletions(-) (limited to 'dbus') diff --git a/dbus/dbus-auth.c b/dbus/dbus-auth.c index c585bd08..e9db1eaf 100644 --- a/dbus/dbus-auth.c +++ b/dbus/dbus-auth.c @@ -871,7 +871,7 @@ handle_client_data_cookie_sha1_mech (DBusAuth *auth, goto out_5; if (!_dbus_string_init (&correct_hash)) - goto out_6; + goto out_5; if (!sha1_compute_hash (auth, val, &server_challenge, diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c index 14be0895..7a89da3e 100644 --- a/dbus/dbus-connection.c +++ b/dbus/dbus-connection.c @@ -42,16 +42,61 @@ * * A DBusConnection represents a connection to another * application. Messages can be sent and received via this connection. - * - * The connection maintains a queue of incoming messages and a queue - * of outgoing messages. dbus_connection_pop_message() and friends - * can be used to read incoming messages from the queue. - * Outgoing messages are automatically discarded as they are - * written to the network. - * + * The other application may be a message bus; for convenience, the + * function dbus_bus_get() is provided to automatically open a + * connection to the well-known message buses. + * * In brief a DBusConnection is a message queue associated with some - * message transport mechanism such as a socket. + * message transport mechanism such as a socket. The connection + * maintains a queue of incoming messages and a queue of outgoing + * messages. + * + * Incoming messages are normally processed by calling + * dbus_connection_dispatch(). dbus_connection_dispatch() runs any + * handlers registered for the topmost message in the message queue, + * then discards the message, then returns. * + * dbus_connection_get_dispatch_status() indicates whether + * messages are currently in the queue that need dispatching. + * dbus_connection_set_dispatch_status_function() allows + * you to set a function to be used to monitor the dispatch status. + * + * If you're using GLib or Qt add-on libraries for D-BUS, there are + * special convenience functions in those libraries that hide + * all the details of dispatch and watch/timeout monitoring. + * For example, dbus_connection_setup_with_g_main(). + * + * If you aren't using these add-on libraries, you have to manually + * call dbus_connection_set_dispatch_status_function(), + * dbus_connection_set_watch_functions(), + * dbus_connection_set_timeout_functions() providing appropriate + * functions to integrate the connection with your application's main + * loop. + * + * When you use dbus_connection_send() or one of its variants to send + * a message, the message is added to the outgoing queue. It's + * actually written to the network later; either in + * dbus_watch_handle() invoked by your main loop, or in + * dbus_connection_flush() which blocks until it can write out the + * entire outgoing queue. The GLib/Qt add-on libraries again + * handle the details here for you by setting up watch functions. + * + * When a connection is disconnected, you are guaranteed to get a + * message with the name #DBUS_MESSAGE_LOCAL_DISCONNECT. + * + * You may not drop the last reference to a #DBusConnection + * until that connection has been disconnected. + * + * You may dispatch the unprocessed incoming message queue even if the + * connection is disconnected. However, #DBUS_MESSAGE_LOCAL_DISCONNECT + * will always be the last message in the queue (obviously no messages + * are received after disconnection). + * + * #DBusConnection has thread locks and drops them when invoking user + * callbacks, so in general is transparently threadsafe. However, + * #DBusMessage does NOT have thread locks; you must not send the same + * message to multiple #DBusConnection that will be used from + * different threads. */ /** @@ -1668,12 +1713,12 @@ _dbus_connection_wait_for_borrowed (DBusConnection *connection) * Returns the first-received message from the incoming message queue, * leaving it in the queue. If the queue is empty, returns #NULL. * - * The caller does not own a reference to the returned message, and must - * either return it using dbus_connection_return_message or keep it after - * calling dbus_connection_steal_borrowed_message. No one can get at the - * message while its borrowed, so return it as quickly as possible and - * don't keep a reference to it after returning it. If you need to keep - * the message, make a copy of it. + * The caller does not own a reference to the returned message, and + * must either return it using dbus_connection_return_message() or + * keep it after calling dbus_connection_steal_borrowed_message(). No + * one can get at the message while its borrowed, so return it as + * quickly as possible and don't keep a reference to it after + * returning it. If you need to keep the message, make a copy of it. * * @param connection the connection. * @returns next message in the incoming queue. @@ -1706,7 +1751,11 @@ dbus_connection_borrow_message (DBusConnection *connection) } /** - * @todo docs + * Used to return a message after peeking at it using + * dbus_connection_borrow_message(). + * + * @param connection the connection + * @param message the message from dbus_connection_borrow_message() */ void dbus_connection_return_message (DBusConnection *connection, @@ -1723,7 +1772,13 @@ dbus_connection_return_message (DBusConnection *connection, } /** - * @todo docs + * Used to keep a message after peeking at it using + * dbus_connection_borrow_message(). Before using this function, see + * the caveats/warnings in the documentation for + * dbus_connection_pop_message(). + * + * @param connection the connection + * @param message the message from dbus_connection_borrow_message() */ void dbus_connection_steal_borrowed_message (DBusConnection *connection, @@ -1805,6 +1860,12 @@ _dbus_connection_pop_message_unlocked (DBusConnection *connection) * removing it from the queue. The caller owns a reference to the * returned message. If the queue is empty, returns #NULL. * + * This function bypasses any message handlers that are registered, + * and so using it is usually wrong. Instead, let the main loop invoke + * dbus_connection_dispatch(). Popping messages manually is only + * useful in very simple programs that don't share a #DBusConnection + * with any libraries or other modules. + * * @param connection the connection. * @returns next message in the incoming queue. */ @@ -2478,6 +2539,11 @@ dbus_connection_set_unix_user_function (DBusConnection *connection, * Filters added during a filter callback won't be run on the * message being processed. * + * The connection does NOT add a reference to the message handler; + * instead, if the message handler is finalized, the connection simply + * forgets about it. Thus the caller of this function must keep a + * reference to the message handler. + * * @param connection the connection * @param handler the handler * @returns #TRUE on success, #FALSE if not enough memory. @@ -2541,6 +2607,11 @@ dbus_connection_remove_filter (DBusConnection *connection, * handler. If the function returns #FALSE, the handlers were not * registered due to lack of memory. * + * The connection does NOT add a reference to the message handler; + * instead, if the message handler is finalized, the connection simply + * forgets about it. Thus the caller of this function must keep a + * reference to the message handler. + * * @todo the messages_to_handle arg may be more convenient if it's a * single string instead of an array. Though right now MessageHandler * is sort of designed to say be associated with an entire object with diff --git a/dbus/dbus-errors.c b/dbus/dbus-errors.c index 0f70bcb1..30b2e0a6 100644 --- a/dbus/dbus-errors.c +++ b/dbus/dbus-errors.c @@ -38,13 +38,28 @@ * In essence D-BUS error reporting works as follows: * * @code - * DBusResultCode result = DBUS_RESULT_SUCCESS; - * dbus_some_function (arg1, arg2, &result); - * if (result != DBUS_RESULT_SUCCESS) - * printf ("an error occurred\n"); + * DBusError error; + * _dbus_error_init (&error); + * dbus_some_function (arg1, arg2, &error); + * if (dbus_error_is_set (&error)) + * { + * fprintf (stderr, "an error occurred: %s\n", error.message); + * dbus_error_free (&error); + * } * @endcode * - * @todo add docs with DBusError + * 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, + * and also a #DBusError parameter, then the error will always be set + * if and only if the return code indicates an error occurred. i.e. + * the return code and the error are never going to disagree. + * + * An error only needs to be freed if it's been set, not if + * it's merely been initialized. + * + * You can check the specific error that occurred using + * dbus_error_has_name(). * * @{ */ @@ -156,9 +171,10 @@ dbus_error_free (DBusError *error) } /** - * Assigns an error name and message to a DBusError. - * Does nothing if error is #NULL. The message may - * be NULL only if the error is DBUS_ERROR_NO_MEMORY. + * 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. * * @param error the error. * @param name the error name (not copied!!!) @@ -261,7 +277,9 @@ dbus_error_is_set (const DBusError *error) * Assigns an error name and message to a DBusError. * Does nothing if error is #NULL. * - * The format may be NULL only if the error is DBUS_ERROR_NO_MEMORY. + * 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. * * If no memory can be allocated for the error message, * an out-of-memory error message will be set instead. diff --git a/dbus/dbus-keyring.c b/dbus/dbus-keyring.c index 85f0a015..67ae056d 100644 --- a/dbus/dbus-keyring.c +++ b/dbus/dbus-keyring.c @@ -731,7 +731,12 @@ _dbus_keyring_new_homedir (const DBusString *username, } else { - _dbus_warn ("Using your real home directory for testing, set DBUS_TEST_HOMEDIR to avoid\n"); + static dbus_bool_t already_warned = FALSE; + if (!already_warned) + { + _dbus_warn ("Using your real home directory for testing, set DBUS_TEST_HOMEDIR to avoid\n"); + already_warned = TRUE; + } } } #endif diff --git a/dbus/dbus-mainloop.c b/dbus/dbus-mainloop.c index 95669ff4..1d1af78c 100644 --- a/dbus/dbus-mainloop.c +++ b/dbus/dbus-mainloop.c @@ -588,11 +588,11 @@ _dbus_loop_iterate (DBusLoop *loop, if (flags & DBUS_WATCH_WRITABLE) fds[n_fds].events |= _DBUS_POLLOUT; - n_fds += 1; - #if MAINLOOP_SPEW _dbus_verbose (" polling watch on fd %d\n", fds[n_fds].fd); #endif + + n_fds += 1; } else { -- cgit