Implementing a Progress Indicator

Many of the operations initiated by clients take a significant amount of time. One of the input parameters to these potentially lengthy operations is a pointer to a progress object — an object that implements the IMAPIProgress interface. Progress objects control the appearance and display of progress indicators and are implemented by clients and by MAPI. You can choose whether or not to implement a progress object; the MAPI implementation is available for service providers to use if you elect not to supply an implementation.

Progress objects work with the following pieces of data:

• A global minimum value which, when your IMAPIProgress::Progress method is called, should be less than or equal to the value of the ulValue parameter. At the beginning of the operation, ulValue will be equal to this minimum value.
• A global maximum value which, when your IMAPIProgress::Progress method is called, should be greater than or equal to the ulValue parameter. At the end of the operation, ulValue will be equal to this maximum value.
• A flags value which indicates whether the progress corresponds to a top or lower level item.
• A value that indicates the current level of progress for the operation.
• The number of the currently processed item relative to the total.
• The total number of items to be processed during the operation.

The minimum and maximum values represent the beginning and end of the operation in numeric form. Use 0 for the initial minimum value and 1000 for the initial maximum value, passing these values to service providers in the IMAPIProgress::GetMin and IMAPIProgress::GetMax methods. Service providers reset these values when they call IMAPIProgress::SetLimits.

The flags value is used by service providers to determine how they should set the other values. Initialize the flags value to MAPI_TOP_LEVEL and return this value in your implementation of GetFlags until the service provider resets it by calling SetLimits.

In your implementation of the SetLimits method, save local copies of each of the parameters: lpulMin, lpulMax, and lpulFlags. These values should be readily available when a service provider calls your GetMin, GetMax, or GetFlags methods.

To update the display of the progress indicator, service providers call your IMAPIProgress::Progress method. There are three parameters to this method: a value, a count, and a total. Use the first parameter, ulValue, to display the progress indicator. The ulValue parameter is the progress indicator and will be equal to global ulMin only at the very beginning of the operation and equal to global ulMax 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 0, you can 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.