[glibmm] Gio::DBus::Address: Wrap the gio dbus address API in this namespace.

[José Alburquerque <jaalburqu src gnome org>]

commit 2294de4884210fa4749587030645ac42b2b4fe88
Author: José Alburquerque <jaalburqu svn gnome org>
Date:   Fri Nov 19 01:30:02 2010 -0500

    	Gio::DBus::Address: Wrap the gio dbus address API in this namespace.
    
    	* gio/giomm.h:
    	* gio/src/dbusaddress.{ccg,hg}:
    	* gio/src/filelist.am: Add new sources and make sure they are built.
    
    	* gio/src/dbusconnection.hg:
    	* gio/src/dbuserror.hg: Typos.

 ChangeLog                 |   11 +++
 gio/giomm.h               |    1 +
 gio/src/dbusaddress.ccg   |  187 +++++++++++++++++++++++++++++++++++++++++++++
 gio/src/dbusaddress.hg    |  161 ++++++++++++++++++++++++++++++++++++++
 gio/src/dbusconnection.hg |   35 +++++----
 gio/src/dbuserror.hg      |    4 +-
 gio/src/filelist.am       |    1 +
 7 files changed, 381 insertions(+), 19 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 1c1d219..cd9f36d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2010-11-19  José Alburquerque  <jaalburqu svn gnome org>
+
+	Gio::DBus::Address: Wrap the gio dbus address API in this namespace.
+
+	* gio/giomm.h:
+	* gio/src/dbusaddress.{ccg,hg}:
+	* gio/src/filelist.am: Add new sources and make sure they are built.
+
+	* gio/src/dbusconnection.hg:
+	* gio/src/dbuserror.hg: Typos.
+
 2010-11-16  José Alburquerque  <jaalburqu svn gnome org>
 
 	DBusConnection: Add call(), call_finish() and call_sync() methods.
diff --git a/gio/giomm.h b/gio/giomm.h
index f79d870..a8d3c47 100644
--- a/gio/giomm.h
+++ b/gio/giomm.h
@@ -31,6 +31,7 @@
 #include <giomm/contenttype.h>
 #include <giomm/datainputstream.h>
 #include <giomm/dataoutputstream.h>
+#include <giomm/dbusaddress.h>
 #include <giomm/dbusauthobserver.h>
 #include <giomm/dbusconnection.h>
 #include <giomm/dbusmessage.h>
diff --git a/gio/src/dbusaddress.ccg b/gio/src/dbusaddress.ccg
new file mode 100644
index 0000000..529f766
--- /dev/null
+++ b/gio/src/dbusaddress.ccg
@@ -0,0 +1,187 @@
+// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+
+/* Copyright (C) 2010 The giomm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free
+ * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+#include <gio/gio.h>
+#include "slot_async.h"
+
+namespace Gio
+{
+
+namespace DBus
+{
+
+namespace Address
+{
+
+bool is_address(const Glib::ustring& string)
+{
+  return static_cast<bool>(g_dbus_is_address(string.c_str()));
+}
+
+bool is_supported(const Glib::ustring& address)
+{
+  GError* gerror = 0;
+  bool const result = g_dbus_is_supported_address(address.c_str(), &gerror);
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+  return result;
+}
+
+void get_stream(const Glib::ustring& address, const SlotAsyncReady slot,
+  const Glib::RefPtr<Cancellable>& cancellable)
+{
+  SlotAsyncReady* slot_copy = new SlotAsyncReady(slot);
+  g_dbus_address_get_stream(address.c_str(), Glib::unwrap(cancellable),
+    &SignalProxy_async_callback, slot_copy);
+}
+
+void get_stream(const Glib::ustring& address, const SlotAsyncReady slot)
+{
+  SlotAsyncReady* slot_copy = new SlotAsyncReady(slot);
+  g_dbus_address_get_stream(address.c_str(), 0, &SignalProxy_async_callback,
+    slot_copy);
+}
+
+Glib::RefPtr<IOStream> get_stream_finish(const Glib::RefPtr<AsyncResult>& res,
+  Glib::ustring& out_guid)
+{
+  GError* gerror = 0;
+  gchar* g_out_guid = 0;
+
+  Glib::RefPtr<IOStream> result =
+    Glib::wrap(g_dbus_address_get_stream_finish(Glib::unwrap(res),
+    &g_out_guid, &gerror));
+
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+
+  out_guid = g_out_guid;
+  return result;
+}
+
+Glib::RefPtr<IOStream> get_stream_finish(const Glib::RefPtr<AsyncResult>& res)
+{
+  GError* gerror = 0;
+
+  Glib::RefPtr<IOStream> result =
+    Glib::wrap(g_dbus_address_get_stream_finish(Glib::unwrap(res), 0,
+    &gerror));
+
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+
+  return result;
+}
+
+Glib::RefPtr<IOStream> get_stream_sync(const Glib::ustring& address,
+  const Glib::RefPtr<Cancellable>& cancellable, Glib::ustring& out_guid)
+{
+  GError* gerror = 0;
+  gchar* g_out_guid = 0;
+
+  Glib::RefPtr<IOStream> result =
+    Glib::wrap(g_dbus_address_get_stream_sync(address.c_str(),
+    &g_out_guid, Glib::unwrap(cancellable), &gerror));
+
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+
+  out_guid = g_out_guid;
+  return result;
+}
+
+Glib::RefPtr<IOStream> get_stream_sync(const Glib::ustring& address,
+  Glib::ustring& out_guid)
+{
+  GError* gerror = 0;
+  gchar* g_out_guid = 0;
+
+  Glib::RefPtr<IOStream> result =
+    Glib::wrap(g_dbus_address_get_stream_sync(address.c_str(),
+    &g_out_guid, 0, &gerror));
+
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+
+  out_guid = g_out_guid;
+  return result;
+}
+
+Glib::RefPtr<IOStream> get_stream_sync(const Glib::ustring& address,
+  const Glib::RefPtr<Cancellable>& cancellable)
+{
+  GError* gerror = 0;
+
+  Glib::RefPtr<IOStream> result =
+    Glib::wrap(g_dbus_address_get_stream_sync(address.c_str(), 0,
+    Glib::unwrap(cancellable), &gerror));
+
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+
+  return result;
+}
+
+Glib::RefPtr<IOStream> get_stream_sync(const Glib::ustring& address)
+{
+  GError* gerror = 0;
+
+  Glib::RefPtr<IOStream> result =
+    Glib::wrap(g_dbus_address_get_stream_sync(address.c_str(), 0, 0, &gerror));
+
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+
+  return result;
+}
+
+Glib::ustring get_for_bus_sync(BusType bus_type,
+  const Glib::RefPtr<Cancellable>& cancellable)
+{
+  GError* gerror = 0;
+
+  Glib::ustring result =
+    Glib::ustring(g_dbus_address_get_for_bus_sync(
+    static_cast<GBusType>(bus_type), Glib::unwrap(cancellable), &gerror));
+
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+
+  return result;
+}
+
+Glib::ustring get_for_bus_sync(BusType bus_type)
+{
+  GError* gerror = 0;
+
+  Glib::ustring result =
+    Glib::ustring(g_dbus_address_get_for_bus_sync(
+    static_cast<GBusType>(bus_type), 0, &gerror));
+
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+
+  return result;
+}
+
+}
+
+} // namespace DBus
+
+} // namespace Gio
diff --git a/gio/src/dbusaddress.hg b/gio/src/dbusaddress.hg
new file mode 100644
index 0000000..42a2e24
--- /dev/null
+++ b/gio/src/dbusaddress.hg
@@ -0,0 +1,161 @@
+// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+
+/* Copyright (C) 2010 The giomm Development Team
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free
+ * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+ */
+
+#include <giomm/dbusconnection.h>
+
+_DEFS(giomm,gio)
+
+namespace Gio
+{
+
+namespace DBus
+{
+
+namespace Address
+{
+
+/** Checks if @a string is a D-Bus address.
+ *
+ * This doesn't check if @a string is actually supported by BusServer or
+ * BusConnection - use is_supported_address() to do more checks.
+ *
+ * @param string A string.
+ * @return <tt>true</tt> if @a string is a valid D-Bus address, <tt>false</tt>
+ * otherwise.
+ * @newin{2,28}
+ */
+bool is_address(const Glib::ustring& string);
+
+/** Like is_address() but also checks if the library supports the transports
+ * in @a address and that key/value pairs for each transport are valid.
+ *
+ * @param address A supposed address.
+ * @return <tt>true</t> if @a address is a valid D-Bus address that is
+ * supported by this library, <tt>false</tt> otherwise.
+ * @throw Glib::Error.
+ * @newin{2,28}
+ */
+bool is_supported(const Glib::ustring& address);
+
+/** Asynchronously connects to an endpoint specified by @a address and sets up
+ * the connection so it is in a state to run the client-side of the D-Bus
+ * authentication conversation.
+ *
+ * When the operation is finished, @a slot will be invoked. You can then call
+ * get_stream_finish() to get the result of the operation.
+ *
+ * This is an asynchronous failable function. See get_stream_sync() for the
+ * synchronous version.
+ *
+ * @param address A valid D-Bus address.
+ * @param cancellable A Cancellable.
+ * @param slot A SlotAsyncReady to call when the request is satisfied.
+ * @newin{2,28}
+ */
+void get_stream(const Glib::ustring& address, const SlotAsyncReady slot,
+  const Glib::RefPtr<Cancellable>& cancellable);
+
+/// A non-cancellable version of get_stream().
+void get_stream(const Glib::ustring& address, const SlotAsyncReady slot);
+
+/** Finishes an operation started with get_stream().
+ *
+ * @param res A AsyncResult obtained from the SlotAsyncReady passed to
+ * get_stream().
+ * @param out_guid Return location to store the GUID extracted from address,
+ * if any.
+ * @return A IOStream.
+ * @throw Glib::Error.
+ * @newin{2,28}
+ */
+Glib::RefPtr<IOStream> get_stream_finish(const Glib::RefPtr<AsyncResult>& res,
+  Glib::ustring& out_guid);
+
+/** Finishes an operation started with get_stream().
+ *
+ * @param res A AsyncResult obtained from the SlotAsyncReady passed to
+ * get_stream().
+ * @return A IOStream.
+ * @throw Glib::Error.
+ * @newin{2,28}
+ */
+Glib::RefPtr<IOStream> get_stream_finish(const Glib::RefPtr<AsyncResult>& res);
+
+/** Synchronously connects to an endpoint specified by @a address and sets up
+ * the connection so it is in a state to run the client-side of the D-Bus
+ * authentication conversation.
+ *
+ * This is a synchronous failable function. See get_stream() for the
+ * asynchronous version.
+ *
+ * @param address A valid D-Bus address.
+ * @param out_guid A return location to store the GUID extracted from address,
+ * if any.
+ * @param cancellable A Cancellable.
+ * @param Returns A IOStream.
+ * @throw Glib::Error.
+ * @newin{2,28}
+ */
+Glib::RefPtr<IOStream> get_stream_sync(const Glib::ustring& address,
+  const Glib::RefPtr<Cancellable>& cancellable, Glib::ustring& out_guid);
+
+/// A non-cancellable version of get_stream_sync().
+Glib::RefPtr<IOStream> get_stream_sync(const Glib::ustring& address,
+  Glib::ustring& out_guid);
+
+/** Synchronously connects to an endpoint specified by @a address and sets up
+ * the connection so it is in a state to run the client-side of the D-Bus
+ * authentication conversation.
+ *
+ * This is a synchronous failable function. See get_stream() for the
+ * asynchronous version.
+ *
+ * @param address A valid D-Bus address.
+ * @param cancellable A Cancellable.
+ * @param Returns A IOStream.
+ * @throw Glib::Error.
+ * @newin{2,28}
+ */
+Glib::RefPtr<IOStream> get_stream_sync(const Glib::ustring& address,
+  const Glib::RefPtr<Cancellable>& cancellable);
+
+/// A non-cancellable version of get_stream_sync().
+Glib::RefPtr<IOStream> get_stream_sync(const Glib::ustring& address);
+
+/** Synchronously looks up the D-Bus address for the well-known message bus
+ * instance specified by @a bus_type. This may involve using various platform
+ * specific mechanisms.
+ *
+ * @param bus_type A BusType.
+ * @param cancellable A Cancellable.
+ * @return A valid D-Bus address string for @a bus_type.
+ * @throw Glib::Error.
+ * @newin{2,28}
+ */
+Glib::ustring get_for_bus_sync(BusType bus_type,
+  const Glib::RefPtr<Cancellable>& cancellable);
+
+/// A non-cancellable get_for_bus_sync().
+Glib::ustring get_for_bus_sync(BusType bus_type);
+
+} // namespace Address
+
+} // namespace DBus
+
+} // namespace Gio
diff --git a/gio/src/dbusconnection.hg b/gio/src/dbusconnection.hg
index 7efeb06..6199a15 100644
--- a/gio/src/dbusconnection.hg
+++ b/gio/src/dbusconnection.hg
@@ -424,8 +424,9 @@ public:
   _WRAP_METHOD(Glib::RefPtr<Credentials> get_peer_credentials(), g_dbus_connection_get_peer_credentials, refreturn)
   _WRAP_METHOD(Glib::RefPtr<const Credentials> get_peer_credentials() const, g_dbus_connection_get_peer_credentials, refreturn, constversion)
 
-  /** Asynchronously invokes the method_name method on the @a interface_name
-   * D-Bus interface on the remote object at @a object_path owned by bus_name.
+  /** Asynchronously invokes the @a method_name method on the @a
+   * interface_name D-Bus interface on the remote object at @a object_path
+   * owned by @a bus_name.
    *
    * If the connection is closed then the operation will fail with
    * Gio::IO_ERROR_CLOSED. If @a cancellable is cancelled, the operation will
@@ -447,17 +448,16 @@ public:
    * @param object_path Path of remote object.
    * @param interface_name D-Bus interface to invoke method on.
    * @param method_name The name of the method to invoke.
-   * @param slot A SlotAsyncReady to call when the request is satisfied or
-   * NULL if you don't care about the result of the method invocation.
-   * @param cancellable A Cancellable or NULL.
-   * @param bus_name A unique or well-known bus name or NULL if connection is
-   * not a message bus connection.
+   * @param slot A SlotAsyncReady to call when the request is satisfied.
+   * @param cancellable A Cancellable.
+   * @param bus_name A unique or well-known bus name or <tt>0</tt> if the
+   * connection is not a message bus connection.
    * @param timeout_msec The timeout in milliseconds, -1 to use the default
    * timeout or G_MAXINT for no timeout.
    * @param flags Flags from the Gio::DBusCallFlags enumeration.
    * @param parameters A Glib::VariantBase tuple with parameters for the
-   * method or NULL if not passing parameters.
-   * @param reply_type The expected type of the reply, or NULL.
+   * method or <tt>0</tt> if not passing parameters.
+   * @param reply_type The expected type of the reply, or <tt>0</tt>.
    * @newin{2,28}
    */
   void call(
@@ -487,7 +487,7 @@ public:
     const Glib::VariantType&            reply_type = Glib::VariantType()
   );
 
-  /** Finishes an operation started with g_dbus_connection_call().
+  /** Finishes an operation started with call().
    * @param output A location in which to return a tuple with return values.
    * @param res A AsyncResult obtained from the SlotAsyncReady passed to
    * call().
@@ -500,8 +500,9 @@ public:
   );
   _IGNORE(g_dbus_connection_call_finish)
 
-  /** Synchronously invokes the method_name method on the @a interface_name
-   * D-Bus interface on the remote object at @a object_path owned by bus_name.
+  /** Synchronously invokes the @a method_name method on the @a interface_name
+   * D-Bus interface on the remote object at @a object_path owned by @a
+   * bus_name.
    *
    * If the connection is closed then the operation will fail with
    * Gio::IO_ERROR_CLOSED. If @a cancellable is cancelled, the operation will
@@ -521,15 +522,15 @@ public:
    * @param object_path Path of remote object.
    * @param interface_name D-Bus interface to invoke method on.
    * @param method_name The name of the method to invoke.
-   * @param cancellable A Cancellable or NULL.
-   * @param bus_name A unique or well-known bus name or NULL if connection is
-   * not a message bus connection.
+   * @param cancellable A Cancellable.
+   * @param bus_name A unique or well-known bus name or <tt>0</tt> if the
+   * connection is not a message bus connection.
    * @param timeout_msec The timeout in milliseconds, -1 to use the default
    * timeout or G_MAXINT for no timeout.
    * @param flags Flags from the Gio::DBusCallFlags enumeration.
    * @param parameters A Glib::VariantBase tuple with parameters for the
-   * method or NULL if not passing parameters.
-   * @param reply_type The expected type of the reply, or NULL.
+   * method or <tt>0</tt> if not passing parameters.
+   * @param reply_type The expected type of the reply, or <tt>0</tt>.
    * @throw Glib::Error.
    * @newin{2,28}
    */
diff --git a/gio/src/dbuserror.hg b/gio/src/dbuserror.hg
index 8cac255..3b26f3d 100644
--- a/gio/src/dbuserror.hg
+++ b/gio/src/dbuserror.hg
@@ -48,8 +48,8 @@ bool is_remote_error(const Glib::Error& error);
  * been used on @a error.
  *
  * @param error A Glib::Error.
- * @return An allocated string or 0 if the D-Bus error name could not be
- * found.
+ * @return An allocated string or <tt>0</tt> if the D-Bus error name could not
+ * be found.
  * @newin{2,28}
  */
 Glib::ustring get_remote_error(const Glib::Error& error);
diff --git a/gio/src/filelist.am b/gio/src/filelist.am
index b0a840c..6f5a281 100644
--- a/gio/src/filelist.am
+++ b/gio/src/filelist.am
@@ -25,6 +25,7 @@ giomm_files_any_hg =			\
 	credentials.hg			\
 	datainputstream.hg		\
 	dataoutputstream.hg		\
+        dbusaddress.hg \
 	dbusauthobserver.hg \
 	dbusconnection.hg \
 	dbuserror.hg \