Docs API Reference

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.
         write('Selected data is ' + dataValue);
      else {            
         var err = result.error; 
         write(err.name + ": " + err.message);
      }
   });
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += 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
Document(Excel, PowerPoint, Project, and Word only) getSelectedDataAsync
setSelectedDataAsync
Bindings (Excel and Word only) addFromPromptAsync
addFromSelectionAsync
getAllAsync
getByIdAsync
releaseByIdAsync
Binding (Excel and Word only) getDataAsync
setDataAsync
removeHandlerAsync
TableBinding (Excel and Word only)
addRowsAsync
deleteAllDataValuesAsync
Settings (Excel, PowerPoint, and Word only) refreshAsync
saveAsync
CustomXmlNode (Word only) getNodesAsync
getNodeValueAsync
getXmlAsync
setNodeValueAsync
setXmlAsync
CustomXmlPart (Word only) deleteAsync
getNodesAsync
getXmlAsync
CustomXmlParts (Word only) addAsync
getByIdAsync
getByNamespaceAsync
CustomXmlPrefixMappings (Word only) addNamespaceAsync
getNamespaceAsync
getPrefixAsync
Mailbox (Outlook only) getUserIdentityTokenAsync
makeEwsRequestAsync
CustomProperties (Outlook only) saveAsync
Item (Outlook only) loadCustomPropertiesAsync
RoamingSettings (Outlook only) saveAsync

Support details

A capital Y in the following matrix indicates that this method is supported in the corresponding Office host application. An empty cell indicates that the Office host application doesn't support this method.

For more information about Office host application and server requirements, see Requirements for running Office Add-ins.

Office for Windows 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