IWMDMProgress3::Begin3
The Begin3 method indicates that progress tracking for an operation is about to begin. An estimate of the duration of the operation is provided when possible. This method extends IWMDMProgress::Begin by providing additional input parameters for the identification (ID) of the event and for a pointer to the optional context of the commands. The operation is identified by an event ID. The method allows the caller to pass an opaque data structure to the application.
Syntax
HRESULT Begin3(
GUID EventId,
DWORD dwEstimatedTicks,
OPAQUECOMMAND* pContext
);
Parameters
EventId
[in] GUID containing the event ID for which progress notifications are being sent.
dwEstimatedTicks
[in] DWORD containing the estimated number of ticks that are needed for the operation to complete.
pContext
[in, out] Pointer to the context of commands that contain any data associated with the event. This parameter is optional and can be NULL.
Return Values
The method returns an HRESULT. All the interface methods in Windows Media Device Manager and service provider can return any of the following classes of error codes:
- Standard COM error codes
- Windows error codes converted to HRESULT values
- Windows Media Device Manager error codes
For a complete list of possible error codes, see Error Codes.
Possible values include, but are not limited to, those in the following table.
Return code | Description |
S_OK | The method succeeded. |
WMDM_E_USER_CANCELLED | The application instructs Windows Media Device Manager to cancel the current operation without waiting for it to finish. |
E_FAIL | An unspecified error occurred. |
Remarks
The interface owning the method that is implementing an operation calls Begin3 when the operation defined by the method is starting.
The number of ticks passed in dwEstimatedTicks is an estimate of how many ticks are needed for the operation to complete. During the course of the operation, the Progress3 method is called to indicate how many ticks have transpired. Applications can use the estimate to configure display mechanisms that show progress.
The application returns S_OK to indicate that an operation should be continued and WMDM_E_USER_CANCELLED to indicate that the operation should be cancelled. If the application is using block mode and returns WMDM_E_USER_CANCELLED, then Windows Media Device Manager will return this same error to the application.
Requirements
Header: Defined in wmdm.idl.
Library: mssachlp.lib
See Also