AsyncResult object

An object which encapsulates the result of an asynchronous request, including status and error information if the request failed.

Hosts: Access, Excel, Outlook, PowerPoint, Project, Word
Last changed in 1.1
AsyncResult

Members

Properties

Name Description
asyncContext Gets the user-defined item passed to the optional asyncContext parameter of the invoked method in the same state as it was passed in.
error Gets an Error object that provides a description of the error, if any error occurred.
status Gets the status of the asynchronous operation.
value Gets the payload or content of this asynchronous operation, if any.

Remarks

When the function you pass to the callback parameter of an "Async" method executes, it receives an AsyncResult object that you can access from the callback function's only parameter.

The following is an example applicable to content and task pane add-ins. The example shows a call to the getSelectedDataAsync method of the Document object.

Office.context.document.getSelectedDataAsync("text", {
        valueFormat: "unformatted",
        filterType: "all"
    },
    function (result) {
        if (result.status === "success") {
            var dataValue = result.value; // Get selected data.
            console.log('Selected data is ' + dataValue);
        } else {
            var err = result.error;
            console.log(err.name + ": " + err.message);
        }
    });

The anonymous function passed as the callback argument ( function (result){...}) has a single parameter named result that provides access to an AsyncResult object when the function executes. When the call to the getSelectedDataAsync method completes, the callback function executes, and the following line of code accesses the value property of the AsyncResult object to return the data selected in the document:

var dataValue = result.value;

Note that other lines of code in the function use the result parameter of the callback function to access the status and error properties of the AsyncResult object.

The AsyncResult object is available from the function passed as the argument to the callback parameter of the following methods:

Parent Object Method
Auth getAccessTokenAsync
Binding (Excel and Word only) getDataAsync
setDataAsync
removeHandlerAsync
Bindings (Excel and Word only) addFromPromptAsync
addFromSelectionAsync
addFromNamedItemAsync
getAllAsync
getByIdAsync
releaseByIdAsync
CustomProperties (Outlook only) saveAsync
CustomXmlNode (Word only) getNodesAsync
getNodeValueAsync
getXmlAsync
getTextAsync
setNodeValueAsync
setTextAsync
setXmlAsync
CustomXmlPart (Word only) deleteAsync
getNodesAsync
getXmlAsync
CustomXmlParts (Word only) addAsync
getByIdAsync
getByNamespaceAsync
CustomXmlPrefixMappings (Word only) addNamespaceAsync
getNamespaceAsync
getPrefixAsync
Document (Excel, PowerPoint, Project, and Word only) getSelectedDataAsync
setSelectedDataAsync
getFileAsync
getFilePropertiesAsync
getActiveViewAsync
File getSliceAsync
closeAsync
Mailbox (Outlook only) getUserIdentityTokenAsync
makeEwsRequestAsync
Item (Outlook only) loadCustomPropertiesAsync
TableBinding (Excel and Word only) addRowsAsync
deleteAllDataValuesAsync
RoamingSettings (Outlook only) saveAsync
Settings (Excel, PowerPoint, and Word only) refreshAsync
saveAsync
UI displayDialogAsync

Support history

Version Changes
1.1 Added support for Excel, PowerPoint, and Word in Office for iPad.
1.1 Added support for add-ins for Access.
1.0 Introduced
desktop Office Online (in browser) Office for iPad OWA for Devices Outlook for Mac Access Y Excel Y Y Y Outlook Y Y Y Y PowerPoint Y Y Y Project Y Word Y Y Y
Add-in types Content, task pane, Outlook
Library Office.js
Namespace Office

Support history


Version Changes
1.1 Added support for Excel, PowerPoint, and Word in Office for iPad.
1.1 Added support for add-ins for Access.
1.0 Introduced