documentation for PendingCall

This commit is contained in:
Andreas Volz 2008-07-30 14:22:20 +02:00
parent 7826341ba3
commit 4f4cec402c

View file

@ -49,18 +49,74 @@ public:
PendingCall& operator = ( const PendingCall& ); PendingCall& operator = ( const PendingCall& );
/*!
* \brief Checks whether the pending call has received a reply yet, or not.
*
* \return true If a reply has been received.
*/
bool completed(); bool completed();
/*!
* \brief Cancels the pending call, such that any reply or error received will
* just be ignored.
*
* Drops the dbus library's internal reference to the DBusPendingCall so will
* free the call if nobody else is holding a reference. However you usually
* get a reference from Connection::send_async() so probably your app
* owns a ref also.
*
* Note that canceling a pending call will not simulate a timed-out call; if a
* call times out, then a timeout error reply is received. If you cancel the
* call, no reply is received unless the the reply was already received before
* you canceled.
*/
void cancel(); void cancel();
/*!
* \brief Block until the pending call is completed.
*
* The blocking is as with Connection::send_blocking(); it
* does not enter the main loop or process other messages, it simply waits for
* the reply in question.
*
* If the pending call is already completed, this function returns immediately.
*/
void block(); void block();
/*!
* \brief Stores a pointer on a PendingCall, along with an optional function to
* be used for freeing the data when the data is set again, or when the
* pending call is finalized.
*
* The slot is allocated automatic.
*
* \param data The data to store.
*/
void data( void* ); void data( void* );
/*!
* \brief Retrieves data previously set with dbus_pending_call_set_data().
*
* The slot must still be allocated (must not have been freed).
*
* \return The data, or NULL if not found.
*/
void* data(); void* data();
/*!
* \return The data slot.
*/
Slot<void, PendingCall&>& slot(); Slot<void, PendingCall&>& slot();
/*!
* \brief Gets the reply
*
* Ownership of the reply message passes to the caller. This function can only
* be called once per pending call, since the reply message is tranferred to
* the caller.
*
* \return The reply Message.
*/
Message steal_reply(); Message steal_reply();
private: private: