IAsyncOperationWithProgress Interface

Definition

public interface class IAsyncOperationWithProgress : IAsyncInfo

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.FoundationContract, 65536)]
/// [Windows.Foundation.Metadata.Guid(3050321623, 58007, 18831, 186, 96, 2, 137, 231, 110, 35, 221)]
template 
struct IAsyncOperationWithProgress : IAsyncInfo

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.FoundationContract), 65536)]
[Windows.Foundation.Metadata.Guid(3050321623, 58007, 18831, 186, 96, 2, 137, 231, 110, 35, 221)]
public interface IAsyncOperationWithProgress : IAsyncInfo

Public Interface IAsyncOperationWithProgress(Of TResult, TProgress)
Implements IAsyncInfo

Type Parameters

Derived

Windows.Devices.Sms.GetSmsMessagesOperation

Attributes

ContractVersionAttribute GuidAttribute

Implements

IAsyncInfo

Windows requirements

Remarks

IAsyncOperationWithProgress is the return type for many Windows Runtime asynchronous methods that have a result upon completion, and also support notifications that report progress (which callers can subscribe to by assigning a callback for Progress). This constitutes about 100 different Windows Runtime APIs. APIs that don't report progress (but do have a result) use another interface, IAsyncOperation.

When you use methods that return IAsyncOperationWithProgress (with a TResult specific constraint) in your app code, you usually don't access the IAsyncOperationWithProgress 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 Windows Runtime asynchronous programming (Call asynchronous APIs in C# or Visual Basic, C++, JavaScript).

It's not common to use IAsyncOperationWithProgress 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 Windows Runtime interface. JavaScript has WinJS.Promise, and the then/done syntax. .NET has the AsTask extension method, and once the IAsyncOperationWithProgress is converted to a Task, 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, IAsyncOperationWithProgress 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.

Specifically, if you want to handle progress in .NET code, use the AsTask signature that in an extension usage has a single IProgress reference parameter. (In this usage, the progress unit is already constrained and matches the IAsyncOperationWithProgress method you're using.) Provide an object that implements IProgress, and your Report method implementation is invoked each time the Windows Runtime method reports a progress notification.

To monitor the progress of the action (if not using the language-specific techniques described above), set the Progress property, providing it the name of a method that implements the AsyncOperationProgressHandler delegate.

C++/WinRT extension functions

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 IAsyncOperationWithProgress, 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

IAsyncOperationWithProgress inherits IAsyncInfo. Types that implement IAsyncOperationWithProgress also implement the interface members of IAsyncInfo:

• Cancel method
• Close method
• ErrorCode property
• Id property
• Status property

Notes to implementers

As with calling the existing methods, there are language-specific ways to define asynchronous methods that don't use IAsyncOperationWithProgress directly. If writing code using .NET, your method can return a Task. 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 Windows Runtime 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 Windows Runtime component.

See also

• IAsyncInfo
• IAsyncOperation
• Asynchronous programming