Office.AsyncResult interface

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

Remarks

HostsAccess, Excel, Outlook, PowerPoint, Project, Word

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.

Examples

// 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.

Properties

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. This returns the user-defined item (which can be of any JavaScript type: String, Number, Boolean, Object, Array, Null, or Undefined) passed to the optional asyncContext parameter of the invoked method. Returns Undefined, if you didn't pass anything to the asyncContext parameter.

error

Gets an Office.Error object that provides a description of the error, if any error occurred.

status

Gets the Office.AsyncResultStatus of the asynchronous operation.

value

Gets the payload or content of this asynchronous operation, if any.

Property Details

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. This returns the user-defined item (which can be of any JavaScript type: String, Number, Boolean, Object, Array, Null, or Undefined) passed to the optional asyncContext parameter of the invoked method. Returns Undefined, if you didn't pass anything to the asyncContext parameter.

asyncContext: any;

Property Value

any

Remarks

Support details

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

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

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad OWA for Devices Office for Mac
Access Y
Excel Y Y Y
Outlook Y Y Y Y
PowerPoint Y Y Y
Project
Word Y Y Y

Examples

function getDataWithContext() {
    var format = "Your data: ";
    Office.context.document.getSelectedDataAsync(
        Office.CoercionType.Text, 
        { asyncContext: format }, 
        showDataWithContext);
}

function showDataWithContext(asyncResult) {
    write(asyncResult.asyncContext + asyncResult.value);
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

error

Gets an Office.Error object that provides a description of the error, if any error occurred.

error: Office.Error;

Property Value

Remarks

Support details

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

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

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad OWA for Devices Office for Mac
Access Y
Excel Y Y Y
Outlook Y Y Y Y
PowerPoint Y Y Y
Project Y
Word Y Y Y

Examples

function getData() {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.Table, function(asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
        }
        else {
            write(asyncResult.value);
        }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

status

Gets the Office.AsyncResultStatus of the asynchronous operation.

status: AsyncResultStatus;

Property Value

Remarks

Support details

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

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

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad OWA for Devices Office for Mac
Access Y
Excel Y Y Y
Outlook Y Y Y Y
PowerPoint Y Y Y
Project Y
Word Y Y Y

Examples

function getData() {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.Table, function(asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
        }
        else {
            write(asyncResult.value);
        }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

value

Gets the payload or content of this asynchronous operation, if any.

value: T;

Property Value

T

Remarks

You access the AsyncResult object in the function passed as the argument to the callback parameter of an "Async" method, such as the getSelectedDataAsync and setSelectedDataAsync methods of the Document object.

Note: What the value property returns for a particular "Async" method varies depending on the purpose and context of that method. To determine what is returned by the value property for an "Async" method, refer to the "Callback value" section of the method's topic.

Support details

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

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

Supported hosts, by platform

Office for Windows desktop Office Online (in browser) Office for iPad OWA for Devices Office for Mac
Access Y
Excel Y Y Y
Outlook Y Y Y Y
PowerPoint Y Y Y
Project Y
Word Y Y Y

Examples

function getData() {
    Office.context.document.getSelectedDataAsync(Office.CoercionType.Table, function(asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write(asyncResult.error.message);
        }
        else {
            write(asyncResult.value);
        }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}