IMAPIProgress::GetFlags

The IMAPIProgress::GetFlags method returns flag settings from the progress object for the level of operation on which progress information is calculated.

Quick Info

See IMAPIProgress : IUnknown.

HRESULT GetFlags(
  ULONG FAR * lpulFlags  
);

Parameters

lpulFlags

[out] Bitmask of flags that controls the level of operation on which progress information is calculated. The following flag can be returned:

MAPI_TOP_LEVEL: Progress is being calculated for the top-level object — the object that is called by the client to begin the operation. For example, the top-level object in a folder copy operation is the folder being copied.
When MAPI_TOP_LEVEL is not set, progress is being calculated for a lower level object, or subobject. In the folder copy operation, a lower level object would be one of the subfolders in the folder being copied.

Return Values

S_OK: The flags value was returned successfully.

Remarks

MAPI allows service providers to differentiate between top-level objects and subobjects with the MAPI_TOP_LEVEL flag so that all objects involved in an operation can use the same IMAPIProgress implementation to show progress, thereby causing the indicator display to proceed smoothly in a single positive direction. Whether or not the MAPI_TOP_LEVEL flag is set determines how service providers set the other parameters in subsequent calls to the progress object.

The value returned by GetFlags is set initially by the implementer and subsequently by the service provider through a call to IMAPIProgress:SetLimits.

Notes to Implementers

Always initialize the flag to MAPI_TOP_LEVEL and then rely on service providers to clear it when appropriate. Service providers can clear and reset the flag by calling IMAPIProgress::SetLimits. For more information about implementing GetFlags and the other IMAPIProgress methods, see Implementing a Progress Indicator.

Notes to Callers

When displaying a progress indicator, make your first call a call to IMAPIProgress::GetFlags. The value returned should be MAPI_TOP_LEVEL because all implementations initialize the contents of lpulFlags to this value. For more information about the sequence of calls to a progress object, see Displaying Progress Step by Step.