[telepathy-qt4/master] PendingOperation: Moved docs to source file.
Andre Moreira Magalhaes (andrunko)
andre.magalhaes at collabora.co.uk
Thu Jun 18 08:49:53 PDT 2009
---
TelepathyQt4/pending-operation.cpp | 145 +++++++++++++++++++++++++++++-
TelepathyQt4/pending-operation.h | 103 ---------------------
TelepathyQt4/simple-pending-operations.h | 24 -----
3 files changed, 144 insertions(+), 128 deletions(-)
diff --git a/TelepathyQt4/pending-operation.cpp b/TelepathyQt4/pending-operation.cpp
index 3f13aa9..5de3187 100644
--- a/TelepathyQt4/pending-operation.cpp
+++ b/TelepathyQt4/pending-operation.cpp
@@ -48,12 +48,47 @@ struct PendingOperation::Private
bool finished;
};
+/**
+ * \class PendingOperation
+ * \headerfile <TelepathyQt4/pending-operation.h> <TelepathyQt4/PendingOperation>
+ *
+ * Abstract base class for pending asynchronous operations.
+ *
+ * This class represents an incomplete asynchronous operation, such as a
+ * D-Bus method call. When the operation has finished, it emits
+ * #finished. The slot or slots connected to the #finished() signal may obtain
+ * additional information from the %PendingOperation.
+ *
+ * In simple cases, like a D-Bus method with no 'out' arguments or for which
+ * all 'out' arguments are to be ignored (so the possible results are
+ * success with no extra information, or failure with an error code), the
+ * trivial subclass %PendingVoidMethodCall can be used.
+ *
+ * For pending operations that produce a result, another subclass of
+ * %PendingOperation can be used, with additional methods that provide that
+ * result to the library user.
+ *
+ * After #finished() is emitted, the %PendingOperation is automatically
+ * deleted using deleteLater(), so library users must not explicitly
+ * delete this object.
+ *
+ * The design is loosely based on KDE's KJob.
+ */
+
+/**
+ * Protected constructor. Only subclasses of this class may be constructed
+ *
+ * \param parent The object on which this pending operation takes place
+ */
PendingOperation::PendingOperation(QObject *parent)
: QObject(parent),
mPriv(new Private())
{
}
+/**
+ * Class destructor.
+ */
PendingOperation::~PendingOperation()
{
if (!mPriv->finished) {
@@ -72,6 +107,10 @@ void PendingOperation::emitFinished()
deleteLater();
}
+/**
+ * Record that this pending operation has finished successfully, and
+ * emit the #finished() signal next time the event loop runs.
+ */
void PendingOperation::setFinished()
{
if (mPriv->finished) {
@@ -90,6 +129,13 @@ void PendingOperation::setFinished()
QTimer::singleShot(0, this, SLOT(emitFinished()));
}
+/**
+ * Record that this pending operation has finished with an error, and
+ * emit the #finished() signal next time the event loop runs.
+ *
+ * \param name A D-Bus error name, which must be non-empty
+ * \param message A debugging message
+ */
void PendingOperation::setFinishedWithError(const QString &name,
const QString &message)
{
@@ -118,40 +164,137 @@ void PendingOperation::setFinishedWithError(const QString &name,
QTimer::singleShot(0, this, SLOT(emitFinished()));
}
+/**
+ * Record that this pending operation has finished with an error, and
+ * emit the #finished() signal next time the event loop runs.
+ *
+ * \param error A QtDBus error
+ */
void PendingOperation::setFinishedWithError(const QDBusError &error)
{
setFinishedWithError(error.name(), error.message());
}
+/**
+ * Returns whether or not the request completed successfully. If the
+ * request has not yet finished processing (isFinished() returns
+ * <code>false</code>), this cannot yet be known, and <code>false</code>
+ * will be returned.
+ *
+ * Equivalent to <code>(isFinished() && !isError())</code>.
+ *
+ * \return <code>true</code> iff the request has finished processing AND
+ * has completed successfully.
+ */
bool PendingOperation::isValid() const
{
return (mPriv->finished && mPriv->errorName.isEmpty());
}
+/**
+ * Returns whether or not the request has finished processing. #finished()
+ * is emitted when this changes from <code>false</code> to
+ * <code>true</code>.
+ *
+ * Equivalent to <code>(isValid() || isError())</code>.
+ *
+ * \sa finished()
+ *
+ * \return <code>true</code> if the request has finished
+ */
bool PendingOperation::isFinished() const
{
return mPriv->finished;
}
+/**
+ * Returns whether or not the request resulted in an error. If the
+ * request has not yet finished processing (isFinished() returns
+ * <code>false</code>), this cannot yet be known, and <code>false</code>
+ * will be returned.
+ *
+ * Equivalent to <code>(isFinished() && !isValid())</code>.
+ *
+ * \return <code>true</code> iff the request has finished processing AND
+ * has resulted in an error.
+ */
bool PendingOperation::isError() const
{
return (mPriv->finished && !mPriv->errorName.isEmpty());
}
+/**
+ * If isError() would return true, returns the D-Bus error with which
+ * the operation failed. If the operation succeeded or has not yet
+ * finished, returns an empty string.
+ *
+ * \return a D-Bus error name or an empty string
+ */
QString PendingOperation::errorName() const
{
return mPriv->errorName;
}
+/**
+ * If isError() would return true, returns a debugging message associated
+ * with the error, which may be an empty string. Otherwise, return an
+ * empty string.
+ *
+ * \return a debugging message or an empty string
+ */
QString PendingOperation::errorMessage() const
{
return mPriv->errorMessage;
}
+/**
+ * \fn void PendingOperation::finished(Tp::PendingOperation* operation)
+ *
+ * Emitted when the pending operation finishes, i.e. when #isFinished()
+ * changes from <code>false</code> to <code>true</code>.
+ *
+ * \param operation This operation object, from which further information
+ * may be obtained
+ */
+
+/**
+ * \class PendingSuccess
+ * \headerfile <TelepathyQt4/simple-pending-operations.h> <TelepathyQt4/PendingSuccess>
+ *
+ * A PendingOperation that is always successful.
+ */
+
+/**
+ * \class PendingFailure
+ * \headerfile <TelepathyQt4/simple-pending-operations.h> <TelepathyQt4/PendingFailure>
+ *
+ * A PendingOperation that always fails with the error passed to the
+ * constructor.
+ */
+/**
+ * \class PendingVoidMethodCall
+ * \headerfile <TelepathyQt4/simple-pending-operations.h> <TelepathyQt4/PendingVoidMethodCall>
+ *
+ * Generic subclass of PendingOperation representing a pending D-Bus method
+ * call that does not return anything (or returns a result that is not
+ * interesting).
+ *
+ * Objects of this class indicate the success or failure of the method call,
+ * but if the method call succeeds, no additional information is available.
+ */
+
+/**
+ * Constructor.
+ *
+ * \param parent The object on which this pending operation takes place
+ * \param call A pending call as returned by the auto-generated low level
+ * Telepathy API; if the method returns anything, the return
+ * value(s) will be ignored
+ */
PendingVoidMethodCall::PendingVoidMethodCall(QObject *proxy,
QDBusPendingCall call)
- : PendingOperation(proxy)
+ : PendingOperation(proxy)
{
connect(new QDBusPendingCallWatcher(call),
SIGNAL(finished(QDBusPendingCallWatcher*)),
diff --git a/TelepathyQt4/pending-operation.h b/TelepathyQt4/pending-operation.h
index fbb876d..7656721 100644
--- a/TelepathyQt4/pending-operation.h
+++ b/TelepathyQt4/pending-operation.h
@@ -35,29 +35,6 @@ class QDBusPendingCallWatcher;
namespace Tp
{
-/**
- * Abstract base class for pending asynchronous operations.
- *
- * This class represents an incomplete asynchronous operation, such as a
- * D-Bus method call. When the operation has finished, it emits
- * #finished. The slot or slots connected to the #finished() signal may obtain
- * additional information from the %PendingOperation.
- *
- * In simple cases, like a D-Bus method with no 'out' arguments or for which
- * all 'out' arguments are to be ignored (so the possible results are
- * success with no extra information, or failure with an error code), the
- * trivial subclass %PendingVoidMethodCall can be used.
- *
- * For pending operations that produce a result, another subclass of
- * %PendingOperation can be used, with additional methods that provide that
- * result to the library user.
- *
- * After #finished() is emitted, the %PendingOperation is automatically
- * deleted using deleteLater(), so library users must not explicitly
- * delete this object.
- *
- * The design is loosely based on KDE's KJob.
- */
class PendingOperation : public QObject
{
Q_OBJECT
@@ -66,103 +43,23 @@ class PendingOperation : public QObject
public:
virtual ~PendingOperation();
- /**
- * Returns whether or not the request has finished processing. #finished()
- * is emitted when this changes from <code>false</code> to
- * <code>true</code>.
- *
- * Equivalent to <code>(isValid() || isError())</code>.
- *
- * \sa finished()
- *
- * \return <code>true</code> if the request has finished
- */
bool isFinished() const;
- /**
- * Returns whether or not the request completed successfully. If the
- * request has not yet finished processing (isFinished() returns
- * <code>false</code>), this cannot yet be known, and <code>false</code>
- * will be returned.
- *
- * Equivalent to <code>(isFinished() && !isError())</code>.
- *
- * \return <code>true</code> iff the request has finished processing AND
- * has completed successfully.
- */
bool isValid() const;
- /**
- * Returns whether or not the request resulted in an error. If the
- * request has not yet finished processing (isFinished() returns
- * <code>false</code>), this cannot yet be known, and <code>false</code>
- * will be returned.
- *
- * Equivalent to <code>(isFinished() && !isValid())</code>.
- *
- * \return <code>true</code> iff the request has finished processing AND
- * has resulted in an error.
- */
bool isError() const;
-
- /**
- * If #isError() would return true, returns the D-Bus error with which
- * the operation failed. If the operation succeeded or has not yet
- * finished, returns an empty string.
- *
- * \return a D-Bus error name or an empty string
- */
QString errorName() const;
-
- /**
- * If isError() would return true, returns a debugging message associated
- * with the error, which may be an empty string. Otherwise, return an
- * empty string.
- *
- * \return a debugging message or an empty string
- */
QString errorMessage() const;
Q_SIGNALS:
- /**
- * Emitted when the pending operation finishes, i.e. when #isFinished()
- * changes from <code>false</code> to <code>true</code>.
- *
- * \param operation This operation object, from which further information
- * may be obtained
- */
void finished(Tp::PendingOperation *operation);
protected:
- /**
- * Protected constructor. Only subclasses of this class may be constructed
- *
- * \param parent The object on which this pending operation takes place
- */
PendingOperation(QObject *parent);
protected Q_SLOTS:
- /**
- * Record that this pending operation has finished successfully, and
- * emit the #finished() signal next time the event loop runs.
- */
void setFinished();
-
- /**
- * Record that this pending operation has finished with an error, and
- * emit the #finished() signal next time the event loop runs.
- *
- * \param name A D-Bus error name, which must be non-empty
- * \param message A debugging message
- */
void setFinishedWithError(const QString &name, const QString &message);
-
- /**
- * Record that this pending operation has finished with an error, and
- * emit the #finished() signal next time the event loop runs.
- *
- * \param error A QtDBus error
- */
void setFinishedWithError(const QDBusError &error);
private Q_SLOTS:
diff --git a/TelepathyQt4/simple-pending-operations.h b/TelepathyQt4/simple-pending-operations.h
index 06f1aa9..f17d300 100644
--- a/TelepathyQt4/simple-pending-operations.h
+++ b/TelepathyQt4/simple-pending-operations.h
@@ -33,9 +33,6 @@
namespace Tp
{
-/**
- * A %PendingOperation that is always successful.
- */
class PendingSuccess : public PendingOperation
{
Q_OBJECT
@@ -49,10 +46,6 @@ public:
}
};
-/**
- * A %PendingOperation that always fails with the error passed to the
- * constructor.
- */
class PendingFailure : public PendingOperation
{
Q_OBJECT
@@ -73,35 +66,18 @@ public:
}
};
-/**
- * Generic subclass of %PendingOperation representing a pending D-Bus method
- * call that does not return anything (or returns a result that is not
- * interesting).
- *
- * Objects of this class indicate the success or failure of the method call,
- * but if the method call succeeds, no additional information is available.
- */
class PendingVoidMethodCall : public PendingOperation
{
Q_OBJECT
Q_DISABLE_COPY(PendingVoidMethodCall)
public:
- /**
- * Constructor.
- *
- * \param parent The object on which this pending operation takes place
- * \param call A pending call as returned by the auto-generated low level
- * Telepathy API; if the method returns anything, the return
- * value(s) will be ignored
- */
PendingVoidMethodCall(QObject *parent, QDBusPendingCall call);
private Q_SLOTS:
void watcherFinished(QDBusPendingCallWatcher*);
private:
- // just ABI padding at the moment
struct Private;
Private *mPriv;
};
--
1.5.6.5
More information about the telepathy-commits
mailing list