ITerraExplorerAsync80

This interface, returned by most of TerraExplorer's asynchronous methods such as ConnectAsync, CreateFeatureLayerAsync and ExecuteQueryAsync, provides a callback-based mechanism similar to the JavaScript promise and the C# Task. It allows for handling the various stages of an asynchronous operation, from tracking progress to managing rejection/error, and finally resolving the operation.

ITerraExplorerAsync80 allows for efficient management of asynchronous operations through its support for method chaining. Methods that return an instance of ITerraExplorerAsync80 support subsequent calls to methods on the returned object directly, ensuring a cleaner and more streamlined code structure, and making asynchronous operations more intuitive to handle.

E.g.,

g_asyncObj = layer.ExecuteQueryAsync(attributeFilter, -1, "", geometryFilter)

    .OnResolve(function (features) {

        // Handle features

    });

After calling the ExecuteQueryAsync method on the layer object, the returned ITerraExplorerAsync80 instance is immediately chained with the OnResolve method. If a corresponding synchronous method has a return value, it's passed as a parameter to the OnResolve method's callback function. For example, calling ExecuteQueryAsync would pass an IFeatures80, containing all the features returned by the attribute and spatial query, to the OnResolve callback.

See "Asynchronous Requests" in the "Overview" chapter for C# and JavaScript examples.

 

	Properties
	State	Returns the current state of the asynchronous operation (pending, fulfilled, rejected), allowing you to check its status.
	Methods
	Abort	Aborts or cancels the ongoing asynchronous operation.
	OnProgress	Reports on the progress of the asynchronous operation, providing updates on the ongoing task. This function is currently only implemented for the ExecuteQueryAsync and QueryElevationBufferAsync methods.
	OnReject	This function is called when the asynchronous operation encounters an error or is rejected, allowing you to handle any failures or exceptions. It also returns an error message.
	OnResolve	This function is called when the asynchronous operation is successfully resolved, and it returns the output generated by the parent asynchronous function.

State

This function returns the current state of the asynchronous operation. It can be any of the following values:

§   ASYNC_STATE_FULFILLED = 0
The asynchronous operation successfully completed its task.

§   ASYNC_STATE_REJECTED = 1
The asynchronous operation failed to complete successfully due to an error.

§   ASYNC_STATE_PENDING = 2
The asynchronous operation is still in progress and has neither succeeded nor failed yet.

§   ASYNC_STATE_SETTLED = 3
The asynchronous operation is finished, whether it ended in success or failure.

 

JavaScript
State

 

C#
AsyncState State { get; }

 

C++
HRESULT State ([out, retval] AsyncState* pVal)

Abort

This method is used to abort or cancel the ongoing asynchronous function.

 

JavaScript
Abort

 

C#
void Abort ()

 

C++
HRESULT Abort ()

 

OnProgress

This function is called to report on the progress of the asynchronous operation, providing updates on the ongoing task. This function is currently only implemented for the ExecuteQueryAsync and QueryElevationBufferAsync methods.

 

JavaScript
OnProgress (dispFunc)

 

C#
ITerraExplorerAsync80 OnProgress {object dispFunc}

 

C++
HRESULT OnProgress (VARIANT_dispFunc,                      ITerraExplorerAsync80** pThis)

Parameters

dispFunc

The callback function to be executed when the event occurs. This function receives progress data, in double format. This function is currently only implemented for the ExecuteQueryAsync and QueryElevationBufferAsync methods.

Return Value

pThis

An ITerraExplorerAsync80 that enables further method chaining or accessing other properties and methods.

Exceptions

HRESULT can return any of the values listed in the HRESULT Return Values list, as well as the following values:

TE_E_INFOTREE_PARENTNOTGROUP	The group ID entered does not represent a valid group in the Project Tree.
TE_E_INFOTREE_ITEMNOTGROUP	The item entered is not a group and therefore cannot be used as a group.
TE_E_INFOTREE_CANTUSEROOT	Cannot use Tree root for this operation
TE_E_INFOTREE_ITEMISGROUP	Item ID is a group so an object cannot be retrieved.

 

OnReject

This method includes a callback function that is called when the asynchronous operation encounters an error or is rejected, allowing you to handle any failures or exceptions.

 

JavaScript
OnReject (dispFunc)

 

C#
ITerraExplorerAsync80 OnReject {object dispFunc}

 

C++
HRESULT OnReject (VARIANT_dispFunc,                      ITerraExplorerAsync80** pThis)

 

Parameters

dispFunc

The callback function to be executed when the event occurs. This function receives an error message in string format.

Return Value

pThis

An ITerraExplorerAsync80 that enables further method chaining or accessing other properties and methods.

Exceptions

HRESULT can return any of the values listed in the HRESULT Return Values list, as well as the following values:

TE_E_INFOTREE_PARENTNOTGROUP	The group ID entered does not represent a valid group in the Project Tree.
TE_E_INFOTREE_ITEMNOTGROUP	The item entered is not a group and therefore cannot be used as a group.
TE_E_INFOTREE_CANTUSEROOT	Cannot use Tree root for this operation
TE_E_INFOTREE_ITEMISGROUP	Item ID is a group so an object cannot be retrieved.

 

OnResolve

This method includes a callback function that is called when the asynchronous operation is successfully resolved. The callback function provided allows handling and processing of the results of the asynchronous operation.

 

JavaScript
OnResolve (dispFunc)

 

C#
ITerraExplorerAsync80 OnResolve {object dispFunc}

 

C++
HRESULT OnResolve (VARIANT_dispFunc,                      ITerraExplorerAsync80** pThis)

Parameters

dispFunc

The callback function to be executed when the event occurs. If a corresponding synchronous method has a return value, it's passed as a parameter to the OnResolve method's callback function. For example, calling ExecuteQueryAsync will pass an IFeatures80, containing all the features returned by the attribute and spatial query, to the OnResolve callback.

Return Value

pThis

An ITerraExplorerAsync80 that enables further method chaining or accessing other properties and methods.

Exceptions

HRESULT can return any of the values listed in the HRESULT Return Values list, as well as the following values:

TE_E_INFOTREE_PARENTNOTGROUP	The group ID entered does not represent a valid group in the Project Tree.
TE_E_INFOTREE_ITEMNOTGROUP	The item entered is not a group and therefore cannot be used as a group.
TE_E_INFOTREE_CANTUSEROOT	Cannot use Tree root for this operation
TE_E_INFOTREE_ITEMISGROUP	Item ID is a group so an object cannot be retrieved.