PendingReply QML Type

An object representing asynchronous results. More...

• List of all members, including inherited members

Properties

• resultAvailable : bool
• success : bool
• valid : bool
• value : var
• watcher : QIviPendingReplyWatcher*

Methods

• setFailed()
• setSuccess(var value)
• then(success, failed)

Detailed Description

A PendingReply is a way for providing asynchronous results. It can be used as a return value for asynchronous functions.

The QML API is very similar to JavaScript Promises.

This documentation shows how to use the PendingReply from within QML and how to execute code once the asynchronous result is ready.

Note: It is not supported to create a PendingReply from QML. The object is supposed to be created from C++ and returned to QML as a result. For more information on how to use it from C++ see the QIviPendingReply documentation.

When a PendingReply is created from C++ it doesn't have a result set yet and the resultAvailable property is false. A result for the pending reply can only be set once and it either indicates a failed(setFailed) or a successful(setSuccess) call. This can be checked using the success property. The actual result is available from the value property, which returns undefined if no result is available or the reply failed.

Using a PendingReply

As explained above, the PendingReply is supposed to be used as a return value for asynchronous operations done in C++. To inform about when a reply result is available there are two ways:

The then method

Similar to a JavaScript Promise the PendingReply is then-able, which means it provides a then method. This method can be used to add callbacks which are executed when the reply succeeds or fails.

import QtQuick 2.0
import QtIvi 1.0

Text {
    id: root
    text: "not ready"

    Component.onCompleted: {
        var asyncReply = TestObject.asyncFunction();
        asyncReply.then(function(value) {
                            root.text = "reply ready: " + value
                        },
                        function() {
                            root.text = "reply failed"
                        })
    }
}

This simple QML snippet calls the C++ function TestObject::asyncFunction() which returns a PendingReply. See the C++ part on how to write such a function and use the PendingReply from C++.

The then method is used to register two callbacks. The first callback is the result callback and takes the reply value as an argument. This will update the text element accordingly. The second argument is the failed callback, which doesn't take an argument as there is no valid reply value.

If the failed state is not of interest it is also possible to not add any callback for it e.g.

asyncReply.then(function(value) {
                    root.text = "reply ready: " + value
                })

In a similar way only the failed callback can be registered by passing undefined to the function as the first argument:

asyncReply.then(undefined,
                function() {
                    root.text = "reply failed"
                })

Synchronous results

When a PendingReply object is used in an API the corresponding function cannot provide the result immediately. But especially for input validation the function can return an error state right away. For this the PendingReply object offers the properties resultAvailable and success to check for this when the object is given for QML.

Checking this for every PendingReply use in QML can be tedious and produces a lot of boiler-plate code. Because of this the PendingReply works similar to a JavaScript Promise and will execute the callbacks although the result is already available.

Signals and Slots

Although the then method is the recommended way from QML, the PendingReply also provides signals. To make the PendingReply as lightweight as possible it is using Q_GADGET and cannot provide signals directly, but provides it through the QIviPendingReplyWatcher class. The QIviPendingReplyWatcher can be accessed using the watcher property.

Note: The QIviPendingReplyWatcher is owned by the PendingReply. Saving the watcher outside of of the PendingReply is not safe as it is destroyed once all copies of this PendingReply object are destroyed.

Property Documentation

Method Documentation