Displaying Progress Step by Step

To display a progress indicator, call IMAPIProgress::GetFlags to retrieve the current flags setting.

     If the MAPI_TOP_LEVEL flag is set
  1. Set a variable equal to the total number of items to process in the operation. For example, if you are copying the contents of a folder, this value will be equal to the number of the subfolders in the folder plus the number of messages.
  2. Set a variable equal to 1000 divided by the number of items.
  3. If you are showing progress for subobjects, call the progress object's IMAPIProgress::SetLimits method and pass the following values for the three parameters:
  4. For each object to be processed:
    1. Call IMAPIProgress::SetLimits and pass the following values for the three parameters:
·    Set the lpulMin parameter to the variable set in step 2 multiplied by the current item minus 1.
·    Set the lpulMax parameter to the variable set in step 2 multiplied by the current object.
·    Set the lpulFlags parameter to 0.

  1. Perform whatever processing should be done on this object. If this is a subobject and you want to display progress on subobjects, pass a pointer to the progress object in the lpProgress parameter to the method.
  2. Call IMAPIProgress::Progress and pass the following values for the three parameters:
·    Set the ulValue parameter to the variable set in step 2 multiplied by the current object.
·    Set the ulCount parameter to the current object.
·    Set the ulTotal parameter to the variable set in step 1, the total number of objects.

    If the MAPI_TOP_LEVEL flag is not set
  1. Call the progress object's IMAPIProgress::GetMin method to retrieve the minimum value for the display.
  2. Call IMAPIProgress::GetMax to retrieve the maximum value for the display.
  3. Set a variable equal to the total number of objects to be processed.
  4. Set a variable equal to the result of subtracting the minimum value from the maximum value and then dividing by the total number of objects.
  5. For each object to be processed:
    1. If your provider is showing progress for subobjects, call IMAPIProgress::SetLimits and pass the following values for the three parameters:
·    Set the lpulMin parameter to the minimum value plus the current item minus 1 multiplied by the variable set in step 4.
·    Set the lpulMax parameter to the minimum value plus the current unit multiplied by the variable set in step 4.
·    Set the lpulFlags parameter to 0.

  1. Perform whatever processing should be done on this object. If the object is a subobject, and your provider displays progress for subobjects, pass a pointer to the progress object in the lpProgress parameter to the method.
  2. Call IMAPIProgress::Progress and pass the following values for the three parameters:
·    Set the ulValue parameter to variable set in step 2 multiplied by the current object.
·    Set the ulCount parameter to 0.
·    Set the ulTotal parameter to 0.

The following code sample illustrates the logic required to show progress at all levels of an operation that copies the contents of a folder containing five subfolders.

lpProgress->GetFlags (lpulFlags);
ulFlags = *lpulFlags;

/* Folder in charge of the display. It contains 5 subfolders. */
if (ulFlags & MAPI_TOP_LEVEL)    
{
    ulItems = 5                         // 5 subfolders in this folder
    ulScale = (ulMax / ulItems)         // 200 because ulMax = 1000
    lpProgress->SetLimits(0, ulMax, MAPI_TOP_LEVEL)

    for (i = 1; i <= ulItems; i++)      // for each subfolder to copy
    {
        lpProgress->SetLimits( (i - 1) * ulScale, i * ulScale, 0) 
        CopyOneFolder(lpFolder(i), lpProgress)
        lpProgress->Progress( i * ulScale, i, ulItems)
    }
}
else  
/* One of the subfolders to be copied. It contains 3 messages */
{
    lpProgress->GetMin(&ulMin);
    lpProgress->GetMax(&ulMax);
    ulItems = 3;
    ulDelta = (ulMax - ulMin) / ulItems;
    for (i = 1; i <= ulItems; i++)
    {
        lpProgress->SetLimits(ulMin + (i - 1) * ulDelta, 
                              ulMin + i * ulDelta, 0)
        CopyOneFolder(lpFolder(i), lpProgress)

        /* Pass 0 for ulCount and ulTotal because this is not the */
        /* top level display and that information is unavailable  */
        lpProgress->Progress( i * ulDelta, 0, 0)
    }
}