IMAPIProgress::Progress

The IMAPIProgress::Progress method updates the progress indicator with a display of the progress as it is made toward completion of the operation.

Quick Info

See IMAPIProgress : IUnknown.

HRESULT Progress(
  ULONG ulValue,   
  ULONG ulCount,   
  ULONG ulTotal    
);
 

Parameters

ulValue

[in] Number indicating the current level of progress, calculated from the ulCount and ulTotal parameters or from the lpulMin and lpulMax parameters of the IMAPIProgress::SetLimits method between the global lower limit and the global upper limit.

ulCount

[in] Number indicating the currently processed item relative to the total.

ulTotal

[in] Total number of items to be processed during the operation.

Return Values

S_OK

The progress indicator was successfully updated.

Notes to Implementers

The ulValue parameter will be equal to the global minimum value only at the beginning of the operation and to the global maximum value only at the completion of the operation.

Use the second and third parameters, ulCount and ulTotal, if available, to display an optional message such as "5 items completed out of 10." If the second and third parameters are set to zero, choose whether or not to visually change the progress indicator. Some service providers set these parameters to zeroes to indicate that they are processing a subobject whose progress is monitored relative to a parent object. In this situation, it makes sense to change the display only when the parent object reports progress. Some service providers pass zeroes for these parameters every time.

For more information about implementing Progress and the other IMAPIProgress methods, see Implementing a Progress Indicator.

Notes to Callers

Not all three of the parameters to IMAPIProgress::Progress are required. The only parameter that is required is the first value, a number that indicates percentage of progress. If the MAPI_TOP_LEVEL flag is set, you can also pass an object count and an object total. Some implementations use these values to display a phrase such as "5 items completed out of 10" with the progress indicator.

If you are copying all messages within a single folder, set ulTotal to the total number of messages being copied. If you are copying a folder, set ulTotal to the number of subfolders within the folder. If the folder to be copied contains no subfolders and only messages, set ulTotal to 1.

For more information about how and when to make calls to a progress object, see Displaying Progress Step by Step.

See Also

IMAPIProgress::SetLimits