From: John (J5) Palmieri <johnp@redhat.com>
Date: Thu, 3 Apr 2008 17:15:45 +0000 (-0400)
Subject: modify dbus_connection_send documentation
X-Git-Tag: dbus-1.2.1~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b5818e619f6258cc6d530ee62e99bd019b6d069b;p=thirdparty%2Fdbus.git

modify dbus_connection_send documentation

* dbus/dbus-connection.c (dbus_connection_send): add documentation
  to describe when to call dbus_connection_flush and
  dbus_connection_unref after a call to dbus_connection_send is made
  Initial wording by Stanislav Brabec <sbrabec at suse.cz>
  (fd.o bug#13558)
---

diff --git a/ChangeLog b/ChangeLog
index ae1f7be00..edca81108 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2008-04-03  John (J5) Palmieri <johnp@redhat.com>
+
+	* dbus/dbus-connection.c (dbus_connection_send): add documentation
+	  to describe when to call dbus_connection_flush and
+	  dbus_connection_unref after a call to dbus_connection_send is made
+	  Initial wording by Stanislav Brabec <sbrabec at suse.cz> 
+	  (fd.o bug#13558)
+
 2008-04-03  John (J5) Palmieri <johnp@redhat.com>
 
 	Patch from Jérémie Dimino <jeremie at dimino.org>
diff --git a/dbus/dbus-connection.c b/dbus/dbus-connection.c
index 9439f63f7..3a1670ca1 100644
--- a/dbus/dbus-connection.c
+++ b/dbus/dbus-connection.c
@@ -3055,18 +3055,24 @@ _dbus_connection_send_unlocked_no_update (DBusConnection *connection,
 /**
  * Adds a message to the outgoing message queue. Does not block to
  * write the message to the network; that happens asynchronously. To
- * force the message to be written, call dbus_connection_flush().
+ * force the message to be written, call dbus_connection_flush() however
+ * it is not necessary to call dbus_connection_flush() by hand; the 
+ * message will be sent the next time the main loop is run. 
+ * dbus_connection_flush() should only be used, for example, if
+ * the application was expected to exit before running the main loop.
+ *
  * Because this only queues the message, the only reason it can
  * fail is lack of memory. Even if the connection is disconnected,
- * no error will be returned.
- *
- * If the function fails due to lack of memory, it returns #FALSE.
- * The function will never fail for other reasons; even if the
- * connection is disconnected, you can queue an outgoing message,
+ * no error will be returned. If the function fails due to lack of memory, 
+ * it returns #FALSE. 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.
+ *
+ * dbus_message_unref() can be called as soon as this method returns
+ * as the message queue will hold its own ref until the message is sent.
  * 
  * @param connection the connection.
  * @param message the message to write.