2003-04-18 Havoc Pennington <hp@pobox.com>

	* 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

9 files changed, 147 insertions, 31 deletions

diff --git a/ChangeLog b/ChangeLog
index 0e914047..a52d9d71 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,24 @@
 2003-04-18  Havoc Pennington  <hp@pobox.com>
 
+	* 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
+
+2003-04-18  Havoc Pennington  <hp@pobox.com>
+
 	* glib/dbus-gmain.c: adapt to watch changes
 
 	* bus/bus.c, bus/activation.c, etc.: adjust to watch changes
diff --git a/bus/Makefile.am b/bus/Makefile.am
index 85f47ddc..823d9cc4 100644
--- a/bus/Makefile.am
+++ b/bus/Makefile.am
@@ -63,7 +63,7 @@ dbus_daemon_1_LDADD=					\
 ## so if adding tests not to be run in make check, don't add them to 
 ## TESTS
 if DBUS_BUILD_TESTS
-TESTS_ENVIRONMENT=DBUS_TEST_DATA=$(top_builddir)/test/data
+TESTS_ENVIRONMENT=DBUS_TEST_DATA=$(top_builddir)/test/data DBUS_TEST_HOMEDIR=$(top_builddir)/dbus
 TESTS=bus-test 
 else
 TESTS=
diff --git a/bus/dispatch.c b/bus/dispatch.c
index 11fe515c..711ce041 100644
--- a/bus/dispatch.c
+++ b/bus/dispatch.c
@@ -1958,7 +1958,7 @@ bus_dispatch_sha1_test (const DBusString *test_data_dir)
   _dbus_verbose ("Testing SHA1 context\n");
   
   context = bus_context_new_test (test_data_dir,
-                                  "valid-config-files/debug-allow-all.conf");
+                                  "valid-config-files/debug-allow-all-sha1.conf");
   if (context == NULL)
     return FALSE;
 
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
             {
diff --git a/doc/TODO b/doc/TODO
index 2f1e7876..e6fe6bce 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -86,3 +86,6 @@
    not on how many can be buffered for a given connection.
 
  - make client serial and reply serial unsigned and add dbus_message_get_is_reply()
+
+ - other apps can send you a fake DBUS_MESSAGE_LOCAL_DISCONNECT; need to 
+   check for that and disallow it.