IMAPIProgress::Progress

  • Article

Applies to: Office 2010 | Outlook 2010 | Visual Studio

In this article
Notes to Implementers
Notes to Callers
MFCMAPI Reference

Updates the progress indicator with a display of the progress as it is made toward completion of the operation.

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

Parameters

  • ulValue
    [in] A number that indicates 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] A number that indicates the currently processed item relative to the total.

  • ulTotal
    [in] The total number of items to be processed during the operation.

Return Value

  • 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 start of the operation and to the global maximum value only at the completion of the operation.

Use the ulCount and ulTotal parameters, if available, to display an optional message such as "5 items completed out of 10." If ulCount and ulTotal are set to 0, decide whether to visually change the progress indicator. Some service providers set these parameters to 0 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 0 for these parameters every time.

For more information about how to implement 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 ulValue, a number that indicates the 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 in 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 in 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 How to: Display a Progress Indicator.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

File

Function

Comment

MAPIProgress.cpp

CMAPIProgress::Progress

MFCMAPI uses the IMAPIProgress::Progress method to update the MFCMAPI status bar with the current percentage of progress, calculated from uValue and the current maximum and minimum values.

See Also

Reference

IMAPIProgress::SetLimits

IMAPIProgress : IUnknown

Concepts

MFCMAPI as a Code Sample

How to: Display a Progress Indicator

Implementing a Progress Indicator