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

Name	Description
AsyncBase::AsyncBase	Initializes an instance of the AsyncBase class.

Public Methods

Name	Description
AsyncBase::Cancel	Cancels an asynchronous operation.
AsyncBase::Close	Closes the asynchronous operation.
AsyncBase::FireCompletion	Invokes the completion event handler, or resets the internal progress delegate.
AsyncBase::FireProgress	Invokes the current progress event handler.
AsyncBase::get_ErrorCode	Retrieves the error code for the current asynchronous operation.
AsyncBase::get_Id	Retrieves the handle of the asynchronous operation.
AsyncBase::get_Status	Retrieves a value that indicates the status of the asynchronous operation.
AsyncBase::GetOnComplete	Copies the address of the current completion event handler to the specified variable.
AsyncBase::GetOnProgress	Copies the address of the current progress event handler to the specified variable.
AsyncBase::put_Id	Sets the handle of the asynchronous operation.
AsyncBase::PutOnComplete	Sets the address of the completion event handler to the specified value.
AsyncBase::PutOnProgress	Sets the address of the progress event handler to the specified value.

Protected Methods

Name	Description
AsyncBase::CheckValidStateForDelegateCall	Tests whether delegate properties can be modified in the current asynchronous state.
AsyncBase::CheckValidStateForResultsCall	Tests whether the results of an asynchronous operation can be collected in the current asynchronous state.
AsyncBase::ContinueAsyncOperation	Determines whether the asynchronous operation should continue processing or should halt.
AsyncBase::CurrentStatus	Retrieves the status of the current asynchronous operation.
AsyncBase::ErrorCode	Retrieves the error code for the current asynchronous operation.
AsyncBase::OnCancel	When overridden in a derived class, cancels an asynchronous operation.
AsyncBase::OnClose	When overridden in a derived class, closes an asynchronous operation.
AsyncBase::OnStart	When overridden in a derived class, starts an asynchronous operation.
AsyncBase::Start	Starts the asynchronous operation.
AsyncBase::TryTransitionToCompleted	Indicates whether the current asynchronous operation has completed.
AsyncBase::TryTransitionToError	Indicates whether the specified error code can modify the internal error state.

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.