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.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for