AsyncBase Class

Implements the Windows Runtime asynchronous state machine.

Syntax

template <
    typename TComplete,
    typename TProgress = Details::Nil,
    AsyncResultType resultType = SingleResult
>
class AsyncBase : public AsyncBase<TComplete, Details::Nil, resultType>;

template <typename TComplete, AsyncResultType resultType>
class AsyncBase<TComplete, Details::Nil, resultType> :
    public Microsoft::WRL::Implements<IAsyncInfo>;

Parameters

TComplete
An event handler that is called when an asynchronous operation completes.

TProgress
An event handler that is called when a running asynchronous operation reports the current progress of the operation.

resultType
One of the AsyncResultType enumeration values. By default, SingleResult.

Members

Public Constructors

Public Methods

Protected Methods

Inheritance Hierarchy

AsyncBase

AsyncBase

Requirements

Header: async.h

Namespace: Microsoft::WRL

AsyncBase::AsyncBase

Initializes an instance of the AsyncBase class.

AsyncBase();

AsyncBase::Cancel

Cancels an asynchronous operation.

STDMETHOD(
   Cancel
)(void);

Return Value

By default, always returns S_OK.

Remarks

Cancel() is a default implementation of IAsyncInfo::Cancel, and does no actual work. To actually cancel an asynchronous operation, override the OnCancel() pure virtual method.

AsyncBase::CheckValidStateForDelegateCall

Tests whether delegate properties can be modified in the current asynchronous state.

inline HRESULT CheckValidStateForDelegateCall();

Return Value

S_OK if delegate properties can be modified; otherwise, E_ILLEGAL_METHOD_CALL.

AsyncBase::CheckValidStateForResultsCall

Tests whether the results of an asynchronous operation can be collected in the current asynchronous state.

inline HRESULT CheckValidStateForResultsCall();

Return Value

S_OK if results can be collected; otherwise, E_ILLEGAL_METHOD_CALLE_ILLEGAL_METHOD_CALL.

AsyncBase::Close

Closes the asynchronous operation.

STDMETHOD(
   Close
)(void) override;

Return Value

S_OK if the operation closes or is already closed; otherwise, E_ILLEGAL_STATE_CHANGE.

Remarks

Close() is a default implementation of IAsyncInfo::Close, and does no actual work. To actually close an asynchronous operation, override the OnClose() pure virtual method.

AsyncBase::ContinueAsyncOperation

Determines whether the asynchronous operation should continue processing or should halt.

inline bool ContinueAsyncOperation();

Return Value

true if the current state of the asynchronous operation is started, which means the operation should continue. Otherwise, false, which means the operation should halt.

AsyncBase::CurrentStatus

Retrieves the status of the current asynchronous operation.

inline void CurrentStatus(
   Details::AsyncStatusInternal *status
);

Parameters

status
The location where this operation stores the current status.

Remarks

This operation is thread-safe.

AsyncBase::ErrorCode

Retrieves the error code for the current asynchronous operation.

inline void ErrorCode(
   HRESULT *error
);

Parameters

error
The location where this operation stores the current error code.

Remarks

This operation is thread-safe.

AsyncBase::FireCompletion

Invokes the completion event handler, or resets the internal progress delegate.

void FireCompletion(
   void
) override;

virtual void FireCompletion();

Remarks

The first version of FireCompletion() resets the internal progress delegate variable. The second version invokes the completion event handler if the asynchronous operation is complete.

AsyncBase::FireProgress

Invokes the current progress event handler.

void FireProgress(
   const typename ProgressTraits::Arg2Type arg
);

Parameters

arg
The event handler method to invoke.

Remarks

ProgressTraits is derived from ArgTraitsHelper Structure.

AsyncBase::get_ErrorCode

Retrieves the error code for the current asynchronous operation.

STDMETHOD(
   get_ErrorCode
)(HRESULT* errorCode) override;

Parameters

errorCode
The location where the current error code is stored.

Return Value

S_OK if successful; otherwise, E_ILLEGAL_METHOD_CALL if the current asynchronous operation is closed.

AsyncBase::get_Id

Retrieves the handle of the asynchronous operation.

STDMETHOD(
   get_Id
)(unsigned int *id) override;

Parameters

id
The location where the handle is to be stored.

Return Value

S_OK if successful; otherwise, E_ILLEGAL_METHOD_CALL.

Remarks

This method implements IAsyncInfo::get_Id.

AsyncBase::get_Status

Retrieves a value that indicates the status of the asynchronous operation.

STDMETHOD(
   get_Status
)(AsyncStatus *status) override;

Parameters

status
The location where the status is to be stored. For more information, see Windows::Foundation::AsyncStatus enumeration.

Return Value

S_OK if successful; otherwise, E_ILLEGAL_METHOD_CALL.

Remarks

This method implements IAsyncInfo::get_Status.

AsyncBase::GetOnComplete

Copies the address of the current completion event handler to the specified variable.

STDMETHOD(
   GetOnComplete
)(TComplete** completeHandler);

Parameters

completeHandler
The location where the address of the current completion event handler is stored.

Return Value

S_OK if successful; otherwise, E_ILLEGAL_METHOD_CALL.

AsyncBase::GetOnProgress

Copies the address of the current progress event handler to the specified variable.

STDMETHOD(
   GetOnProgress
)(TProgress** progressHandler);

Parameters

progressHandler
The location where the address of the current progress event handler is stored.

Return Value

S_OK if successful; otherwise, E_ILLEGAL_METHOD_CALL.

AsyncBase::OnCancel

When overridden in a derived class, cancels an asynchronous operation.

virtual void OnCancel(
   void
) = 0;

AsyncBase::OnClose

When overridden in a derived class, closes an asynchronous operation.

virtual void OnClose(
   void
) = 0;

AsyncBase::OnStart

When overridden in a derived class, starts an asynchronous operation.

virtual HRESULT OnStart(
   void
) = 0;

AsyncBase::put_Id

Sets the handle of the asynchronous operation.

STDMETHOD(
   put_Id
)(const unsigned int id);

Parameters

id
A nonzero handle.

Return Value

S_OK if successful; otherwise, E_INVALIDARG or E_ILLEGAL_METHOD_CALL.

AsyncBase::PutOnComplete

Sets the address of the completion event handler to the specified value.

STDMETHOD(
   PutOnComplete
)(TComplete* completeHandler);

Parameters

completeHandler
The address to which the completion event handler is set.

Return Value

S_OK if successful; otherwise, E_ILLEGAL_METHOD_CALL.

AsyncBase::PutOnProgress

Sets the address of the progress event handler to the specified value.

STDMETHOD(
   PutOnProgress
)(TProgress* progressHandler);

Parameters

progressHandler
The address to which the progress event handler is set.

Return Value

S_OK if successful; otherwise, E_ILLEGAL_METHOD_CALL.

AsyncBase::Start

Starts the asynchronous operation.

STDMETHOD(
   Start
)(void);

Return Value

S_OK if the operation starts or is already started; otherwise, E_ILLEGAL_STATE_CHANGE.

Remarks

Start() is a protected method that is not externally visible because async operations "hot start" before returning to the caller.

AsyncBase::TryTransitionToCompleted

Indicates whether the current asynchronous operation has completed.

bool TryTransitionToCompleted(
   void
);

Return Value

true if the asynchronous operation has completed; otherwise, false.

AsyncBase::TryTransitionToError

Indicates whether the specified error code can modify the internal error state.

bool TryTransitionToError(
   const HRESULT error
);

Parameters

error
An error HRESULT.

Return Value

true if the internal error state was changed; otherwise, false.

Remarks

This operation modifies the error state only if the error state is already set to S_OK. This operation has no effect if the error state is already error, cancelled, completed, or closed.