Methods supporting the ability of DMA methods to report progress to their callers. This interface may be implemented by a client-provided COM object; support is not required by any of the DMA objects.
This method must be supported in every implementation of this interface.
Syntax
DmaRC IdmaProgressCallback::ReportProgress (
DmaRC rcProgressStatus,
DmaUInteger32 ulProgressNumerator,
DmaUInteger32 ulProgressDenominator,
DmaBoolean bAbortAllowed)
Parameters
Name | Mode | Description |
rcProgressStatus | input | A DMA return code that indicates the status of the underlying operation’s progress at this point. DMARC_OK always indicates that the operation is proceeding normally. Any other value is for a defined exception that the requester has the option of ignoring. |
ulProgressNumerator | input | The numerator of a fraction that represents fraction of completion of the underlying operation. |
ulProgressDenominator | input | The denominator of a fraction that represents fraction of completion. If the ulProgressDenominator is nonzero, then ulProgressNumerator / ulProgressDenominator * 100 % is the percentage of completion of the operation. If ulProgressDenominator is zero, the caller is unable to supply any information about the degree of completeness of the operation. |
bAbortAllowed | input | If DMA_TRUE, the underlying operation in progress can be aborted at this point; if DMA_FALSE it cannot (and the return code from ReportProgress will be ignored). Successive calls can pass in different values for bAbortAllowed. |
This method provides a way for potentially long-running DMA methods to report back on their progress. When a client supplies an IdmaProgressCallback interface pointer to a method which accepts such an argument, that method may provide a 'percentage done' indication via ReportProgress(). ReportProgress() also allows the caller to request that the method may be aborted.
Implementations of ReportProgress() must always return to their caller, and (because their execution delays the underlying method) should execute quickly. They should normally return DMARC_OK. Any other error code will be considered as a request to abort the underlying method.
There are no guarantees that ReportProgress() will ever be called, that a requested abort will take place, or that a non-zero value will ever be supplied for nProgressDenominator. If nProgressDenominator is nonzero, the callback procedure cannot rely on the percentage done being non-decreasing.
There are certain guarantees. (1) Once the denominator is nonzero,it stays nonzero. (2) If the denominator is ever nonzero, the percentage done will never be more than 100%, and the percent done can increase, decrease, or stay the same. (3) The client must be written so that the ReportProgress method might never be called, and, if it is, it may be called repeatedly, even after it instructs the underlying method to abort.
Return Values
Name | Description |
DMARC_ABORT | The progress callback indicated that the method should be aborted. |
DMARC_OK | (S_OK) Success. |