[glibmm] DBusServer: Add docs to the signal_new_connection() signal.

[José Alburquerque <jaalburqu src gnome org>]

commit 1c02c600f93e2c8b651e74c95f66c96ea3d93b90
Author: José Alburquerque <jaalburqu svn gnome org>
Date:   Thu Jan 13 12:54:50 2011 -0500

    DBusServer: Add docs to the signal_new_connection() signal.
    
    	* gio/src/dbusserver.hg: Add the docs from the C API to make sure it
    	clear to users that when handling the "new-connection" signal that a
    	reference to the new connection must be kept or the connection will
    	not be accepted.
    
    	* examples/dbus/peer.cc: Make an exception message more general to
    	cover both a possible exception from the call_sync() call and the
    	close_sync() call.

 ChangeLog             |   13 +++++++++++++
 examples/dbus/peer.cc |    4 ++--
 gio/src/dbusserver.hg |   21 +++++++++++++++++++++
 3 files changed, 36 insertions(+), 2 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index abc45c9..e2e2943 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,18 @@
 2011-01-13  José Alburquerque  <jaalburqu svn gnome org>
 
+	DBusServer: Add docs to the signal_new_connection() signal.
+
+	* gio/src/dbusserver.hg: Add the docs from the C API to make sure it
+	clear to users that when handling the "new-connection" signal that a
+	reference to the new connection must be kept or the connection will
+	not be accepted.
+
+	* examples/dbus/peer.cc: Make an exception message more general to
+	cover both a possible exception from the call_sync() call and the
+	close_sync() call.
+
+2011-01-13  José Alburquerque  <jaalburqu svn gnome org>
+
 	DBusConnection, DBusMessage: Wrap properties and signals.
 
 	* tools/extra_defs_gen/generate_defs_gio.cc:
diff --git a/examples/dbus/peer.cc b/examples/dbus/peer.cc
index be25ebf..6d383c3 100644
--- a/examples/dbus/peer.cc
+++ b/examples/dbus/peer.cc
@@ -208,8 +208,8 @@ void run_as_client(Glib::ustring address)
   }
   catch(const Glib::Error& ex)
   {
-    std::cerr << "Error calling the server's method: " << ex.what() << "." <<
-      std::endl;
+    std::cerr << "Error communicating with the server: " << ex.what() <<
+      "." << std::endl;
     return;
   }
 }
diff --git a/gio/src/dbusserver.hg b/gio/src/dbusserver.hg
index 655ee71..e693fca 100644
--- a/gio/src/dbusserver.hg
+++ b/gio/src/dbusserver.hg
@@ -110,6 +110,27 @@ public:
   _WRAP_PROPERTY("guid", std::string)
 
 #m4 _CONVERSION(`GDBusConnection*', `const Glib::RefPtr<DBusConnection>&', `Glib::wrap($3, true)')
+  /** Emitted when a new authenticated connection has been made. Use
+   * Gio::DBusConnection::get_peer_credentials() to figure out what identity
+   * (if any), was authenticated.
+   *
+   * If you want to accept the connection, keep a global reference to the
+   * connection (by keeping it in a global RefPtr<>) and return <tt>true</tt>.
+   * When you are done with the connection call Gio::DBusConnection::close().
+   * Note that the other peer may disconnect at any time - a typical thing to
+   * do when accepting a connection is to listen to the
+   * Gio::DBusConnection::signal_closed() signal.
+   *
+   * If property_flags() contains Gio::DBUS_SERVER_FLAGS_RUN_IN_THREAD then
+   * the signal is emitted in a new thread dedicated to the connection.
+   * Otherwise the signal is emitted in the thread-default main loop of the
+   * thread that server was constructed in.
+   *
+   * You are guaranteed that signal handlers for this signal runs before
+   * incoming messages on the connection are processed. This means that it's
+   * suitable to call Gio::DBusConnection::register_object() or similar from
+   * the signal handler.
+   */
   _WRAP_SIGNAL(bool new_connection(const Glib::RefPtr<DBusConnection>& connection), "new-connection", no_default_handler)
 };