Skip to content

Latest commit

 

History

History
489 lines (319 loc) · 15.3 KB

asyncbase-class.md

File metadata and controls

489 lines (319 loc) · 15.3 KB
description title ms.date ms.topic f1_keywords helpviewer_keywords ms.assetid
Learn more about: AsyncBase Class
AsyncBase Class
10/08/2018
reference
async/Microsoft::WRL::AsyncBase
async/Microsoft::WRL::AsyncBase::AsyncBase
async/Microsoft::WRL::AsyncBase::Cancel
async/Microsoft::WRL::AsyncBase::CheckValidStateForDelegateCall
async/Microsoft::WRL::AsyncBase::CheckValidStateForResultsCall
async/Microsoft::WRL::AsyncBase::Close
async/Microsoft::WRL::AsyncBase::ContinueAsyncOperation
async/Microsoft::WRL::AsyncBase::CurrentStatus
async/Microsoft::WRL::AsyncBase::ErrorCode
async/Microsoft::WRL::AsyncBase::FireCompletion
async/Microsoft::WRL::AsyncBase::FireProgress
async/Microsoft::WRL::AsyncBase::get_ErrorCode
async/Microsoft::WRL::AsyncBase::get_Id
async/Microsoft::WRL::AsyncBase::get_Status
async/Microsoft::WRL::AsyncBase::GetOnComplete
async/Microsoft::WRL::AsyncBase::GetOnProgress
async/Microsoft::WRL::AsyncBase::OnCancel
async/Microsoft::WRL::AsyncBase::OnClose
async/Microsoft::WRL::AsyncBase::OnStart
async/Microsoft::WRL::AsyncBase::put_Id
async/Microsoft::WRL::AsyncBase::PutOnComplete
async/Microsoft::WRL::AsyncBase::PutOnProgress
async/Microsoft::WRL::AsyncBase::TryTransitionToCompleted
async/Microsoft::WRL::AsyncBase::TryTransitionToError
Microsoft::WRL::AsyncBase class
Microsoft::WRL::AsyncBase::AsyncBase, constructor
Microsoft::WRL::AsyncBase::Cancel method
Microsoft::WRL::AsyncBase::CheckValidStateForDelegateCall method
Microsoft::WRL::AsyncBase::CheckValidStateForResultsCall method
Microsoft::WRL::AsyncBase::Close method
Microsoft::WRL::AsyncBase::ContinueAsyncOperation method
Microsoft::WRL::AsyncBase::CurrentStatus method
Microsoft::WRL::AsyncBase::ErrorCode method
Microsoft::WRL::AsyncBase::FireCompletion method
Microsoft::WRL::AsyncBase::FireProgress method
Microsoft::WRL::AsyncBase::get_ErrorCode method
Microsoft::WRL::AsyncBase::get_Id method
Microsoft::WRL::AsyncBase::get_Status method
Microsoft::WRL::AsyncBase::GetOnComplete method
Microsoft::WRL::AsyncBase::GetOnProgress method
Microsoft::WRL::AsyncBase::OnCancel method
Microsoft::WRL::AsyncBase::OnClose method
Microsoft::WRL::AsyncBase::OnStart method
Microsoft::WRL::AsyncBase::put_Id method
Microsoft::WRL::AsyncBase::PutOnComplete method
Microsoft::WRL::AsyncBase::PutOnProgress method
Microsoft::WRL::AsyncBase::TryTransitionToCompleted method
Microsoft::WRL::AsyncBase::TryTransitionToError method
64259b9b-f427-4ffd-a611-e7a2f82362b2

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.