IAsyncOperation<TResult> Interface
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Represents an asynchronous operation, which returns a result upon completion. This is the return type for many Windows Runtime (WinRT) asynchronous methods that have results but don't report progress.
public interface class IAsyncOperation : IAsyncInfo/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.FoundationContract, 65536)]
/// [Windows.Foundation.Metadata.Guid(2680336571, 58438, 17634, 170, 97, 156, 171, 143, 99, 106, 242)]
template <typename TResult>
struct IAsyncOperation : IAsyncInfo[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.FoundationContract), 65536)]
[Windows.Foundation.Metadata.Guid(2680336571, 58438, 17634, 170, 97, 156, 171, 143, 99, 106, 242)]
public interface IAsyncOperation<TResult> : IAsyncInfoPublic Interface IAsyncOperation(Of TResult)
Implements IAsyncInfoType Parameters
- TResult
- Derived
- Attributes
- Implements
Windows requirements
| Device family |
Windows 10 (introduced in 10.0.10240.0)
|
| API contract |
Windows.Foundation.FoundationContract (introduced in v1.0)
|
Remarks
IAsyncOperation<TResult> is the return type for many WinRT asynchronous methods that have a result upon completion, but don't report progress. This constitutes over 650 different WinRT APIs. APIs that report progress and have a result use another interface, IAsyncOperationWithProgress<TResult,TProgress>.
When you use methods that return IAsyncOperation<TResult> (with a TResult specific constraint) in your app code, you usually don't access the IAsyncOperation return value directly. That's because you almost always use the language-specific awaitable syntax. In this case, the apparent return value of the method is the type provided as the TResult parameter. For more info, see Asynchronous programming, or one of the language-specific guides to WinRT asynchronous programming (Call asynchronous APIs in C# or Visual Basic, C++, JavaScript).
It's not common to use IAsyncOperation<TResult> directly even if you don't use a language-specific awaitable syntax. Each of the languages has extension points that are generally easier to use than the WinRT interface. JavaScript has WinJS.Promise, and the then/done syntax. .NET has the AsTask extension method, and once the IAsyncOperation<TResult> is converted to a Task<TResult>, it's easier to get the result, cancel, get notification on completion, and so on. For C++/CX, you can wrap the calls using the Concurrency runtime (and use create_task). In other words, IAsyncOperation<TResult> can be considered runtime-level infrastructure, which each of the languages use as a framework to support awaitable syntax or asynchronous programming models in their own way.
Instead of using IAsyncOperation<TResult>, some WinRT asynchronous methods use custom operation types. For example, DataReaderLoadOperation is a WinRT type that implements IAsyncOperation using uint as the result type. The DataReaderLoadOperation type is then used as the custom operation/result type for the DataReader.LoadAsync method.
If you have a method that returns a .NET Task<T> and need an IAsyncOperation<TResult> to pass to a WinRT API, you can use the AsAsyncOperation extension method.
C++/WinRT extension functions
Note
Extension functions exist on the C++/WinRT projection types for certain WinRT APIs. For example, winrt::Windows::Foundation::IAsyncAction is the C++/WinRT projection type for IAsyncAction. The extension functions aren't part of the application binary interface (ABI) surface of the actual WinRT types, so they're not listed as members of the WinRT APIs. But you can call them from within any C++/WinRT project. See C++/WinRT functions that extend Windows Runtime APIs.
TResult get() const;
Waits synchronously for the operation to complete, and returns the completed value. Throws a corresponding exception if the operation is canceled, or enters an error state. You mustn't call it from a single-threaded apartment. For more info, and code examples showing how to call get, see Write a coroutine.
AsyncStatus wait_for(TimeSpan const& timeout) const;
Waits synchronously for the operation to complete, or for the specified timeout. Returns the state of the IAsyncOperation, or AsyncStatus::Started if the timeout elapsed. If the action didn't time out, then call GetResults to obtain the results of the operation. For more info, and code examples showing how to call wait_for, see Asynchronous timeouts made easy.
Interface inheritance
IAsyncOperation<TResult> inherits IAsyncInfo. Types that implement IAsyncOperation<TResult> also implement the interface members of IAsyncInfo:
Notes to implementers
As with calling the existing methods, there are language-specific ways to define asynchronous methods that don't use IAsyncOperation<TResult> directly. If writing code using .NET, your method can return a Task<TResult>. For C++/CX, you can use the Concurrency runtime. However, if you're defining a component, you can use Task/task internally but you must return one of the WinRT interfaces for your public methods. The language-specific asynchronous support types (and many other language-specific types you might conventionally use in code) can't be used for the public surface area of a WinRT component.
Properties
| Completed |
Gets or sets the delegate that is called when the operation completes. |
| ErrorCode |
Gets a string that describes an error condition of the asynchronous operation. (Inherited from IAsyncInfo) |
| Id |
Gets the handle of the asynchronous operation. (Inherited from IAsyncInfo) |
| Status |
Gets a value that indicates the status of the asynchronous operation. (Inherited from IAsyncInfo) |
Methods
| Cancel() |
Cancels the asynchronous operation. (Inherited from IAsyncInfo) |
| Close() |
Closes the asynchronous operation. (Inherited from IAsyncInfo) |
| GetResults() |
Returns the results of the operation. |