2006-03-06 Thiago Macieira <thiago.macieira@trolltech.com>

	* qt/*:
	* dbus/qdbus.h: Sync with KDE Subversion revision 516237. This
	represents the first feature-complete version of the Qt4
	bindings since I took ove maintainership.

1 files changed, 86 insertions, 11 deletions

diff --git a/qt/qdbusobject.cpp b/qt/qdbusobject.cpp
index 139154e8..3fd9a5b2 100644
--- a/qt/qdbusobject.cpp
+++ b/qt/qdbusobject.cpp
@@ -33,32 +33,50 @@
 #include "qdbusobject_p.h"
 #include "qdbusutil.h"
 
+/*!
+    \class QDBusObject
+    \brief Base object for referencing remote D-Bus Objects
+
+    This class provides the basic functionality for referencing remote objects. It does not,
+    however, allow you to place calls to the remote object: you have to use the QDBusInterface class
+    for that.
+*/
+
+/*!
+    \internal
+*/
 QDBusObject::QDBusObject(QDBusObjectPrivate* p, const QDBusConnection& conn)
     :d(p), m_conn(conn)
 {
 }
     
-QDBusObject::QDBusObject(const QDBusConnection& conn, const QString& service, const QString& path)
-    : m_conn(conn)
-{
-    *this = m_conn.findObject(service, path);
-}
-
+/*!
+    Creates a QDBusObject that references the same object that the QDBusInterface class does.
+*/
 QDBusObject::QDBusObject(const QDBusInterface& iface)
     : m_conn(iface.connection())
 {
     *this = m_conn.findObject(iface.service(), iface.path());
 }
 
+/*!
+    Copy constructor: creates a copy of the \p other object.
+*/
 QDBusObject::QDBusObject(const QDBusObject& other)
     : d(other.d), m_conn(other.m_conn)
 {
 }
 
+/*!
+    Destroys this object and frees any resource it held.
+*/
 QDBusObject::~QDBusObject()
 {
 }
 
+/*!
+    Assignment operator: copy the contents of the \p other QDBusObject.
+*/
 QDBusObject& QDBusObject::operator=(const QDBusObject& other)
 {
 #if 0    
@@ -74,21 +92,38 @@ QDBusObject& QDBusObject::operator=(const QDBusObject& other)
     return *this;
 }
 
+/*!
+    Returns the connection this object is bound to.
+*/
 QDBusConnection QDBusObject::connection() const
 {
     return m_conn;
 }
 
+/*!
+    Returns the service this object is associated to.
+    \sa connection
+*/
 QString QDBusObject::service() const
 {
     return d ? d->data->service : QString();
 }
 
+/*!
+    Returns the path on the remote service this object is on.
+    \sa connection, service
+*/
 QString QDBusObject::path() const
 {
     return d ? d->data->path : QString();
 }
 
+/*!
+    Places an Introspect call to the remote object and return the XML data that describes its
+    contents. This is the raw XML data of the structures introspectionData() returns.
+
+    \bug We should not cache here. The remote object can change.
+*/
 QString QDBusObject::introspect() const
 {
     if (!d)
@@ -97,17 +132,22 @@ QString QDBusObject::introspect() const
 
     if (d->data->introspection.isNull()) {
         // Try to introspect
-        QDBusIntrospectableInterface iface = *this;
-        QString xml = iface.introspect();
+        QDBusIntrospectableInterface iface(*this);
+        QDBusReply<QString> reply = iface.introspect();
 
-        if (!m_conn.lastError().isValid()) {
+        if (reply.isSuccess()) {
             // this will change the contents of d->data
-            QDBusXmlParser::parse(d, xml);
+            QDBusXmlParser::parse(d, reply);
         }
     }
     return d->data->introspection;
 }
 
+/*!
+    Places an Introspect call to the remote object and return the parsed structures representing the
+    object's interfaces and child objects. The raw XML data corresponding to this function's
+    structures can be obtained using introspect().
+*/
 QSharedDataPointer<QDBusIntrospection::Object> QDBusObject::introspectionData() const
 {
     QSharedDataPointer<QDBusIntrospection::Object> retval;
@@ -116,12 +156,23 @@ QSharedDataPointer<QDBusIntrospection::Object> QDBusObject::introspectionData()
     return retval;
 }
 
+/*!
+    Returns a list of all the interfaces in this object. This is the same value as the found in the
+    \ref QDBusIntrospection::Object::interfaces "interfaces" member of the value returned by
+    introspectionData().
+*/
 QStringList QDBusObject::interfaces() const
 {
     introspect();
     return d ? d->data->interfaces : QStringList();
 }
 
+/*!
+    Returns a map of all the children object in this object along with pre-created QDBusObjects for
+    referencing them.
+
+    \todo Write this function!
+*/
 QMap<QString, QDBusObject> QDBusObject::children() const
 {
     QMap<QString, QDBusObject> retval;
@@ -141,6 +192,10 @@ QMap<QString, QDBusObject> QDBusObject::children() const
     return retval;
 }
 
+/*!
+    Returns true if we're referencing a valid object service and path. This does not mean the object
+    actually exists in the remote application or that the remote application exists.
+*/
 bool QDBusObject::isValid() const
 {
     return d && m_conn.isConnected() && QDBusUtil::isValidBusName(d->data->service) &&
@@ -148,6 +203,9 @@ bool QDBusObject::isValid() const
 }
 
 #if 0                           // we don't have a way of determining if an object exists or not
+/*!
+    Returns true if the object being referenced exists.
+*/
 bool QDBusObject::exists() const
 {
     if (!isValid())
@@ -167,7 +225,24 @@ bool QDBusObject::exists() const
     }
 
     if (err.name == DBUS_ERROR_SERVICE_UNKNOWN ||
-        err.name == DBUS_ERROR_BAD_ADDRESS
+        err.name == DBUS_ERROR_BAD_ADDRESS)
     return !m_conn.lastError().isValid();
 }
 #endif
+
+/*!
+    \fn QDBusObject::operator Interface()
+    Cast this object to an interface, if possible.
+*/
+
+/*!
+    \fn QDBusObject::operator const Interface()
+    Cast this object to an interface, if possible.
+*/
+
+/*!
+    \fn qdbus_cast
+    \relates QDBusObject
+
+    Casts a QDBusObject to the QDBusInterface-derived class of type Interface.
+*/