HrGetFolderMetrics

The HrGetFolderMetrics function retrieves folder statistics.

Quick Info

HRESULT HrGetFolderMetrics(
  HFLDMTRC hFolderMetric,  
  FILETIME * pftNow,       
  DWORD fMetric,           
  DWORD * pcMessages,      
  FILETIME * pftLongestWait,  
  FILETIME * pftTotalWait  
);
 

Parameters

hFolderMetric

Input parameter. Specifies the handle to the calculations for this folder.

pftNow

Input parameter. Points to the current time.

fMetric

Input parameter. Specifies the calculations to make:

FM_CMESSAGES

Returns a value in pcMessages.

FM_LONGEST_WAIT

Returns a value in pftLongestWait.

FM_TOTAL_WAIT

Returns a value in pftTotalWait.

pcMessages

Output parameter. Points to the number of messages in the folder (calculated if FM_CMESSAGES is specified in fMetric).

pftLongestWait

Output parameter. Points to the duration of the longest wait in the current message list (calculated if FM_LONGEST_WAIT is specified in fMetric).

pftTotalWait

Output parameter. Points to the total of the wait durations of all messages in the folder (calculated if FM_TOTAL_WAIT is specified in fMetric).

Return Values

See Return Values.

Remarks

Three statistics are available:

• Number of messages in the folder.
• Duration of wait for the message that has been in the folder for the longest period of time.
• Total wait duration for all messages in the folder.

One, two, or all three calculations can be requested in the same call.

The statistics require different amounts of overhead to calculate. Calculating the number of messages in a folder is the least expensive statistic. Calculating the total of the wait durations is the most expensive. To optimize performance, request only the statistics you need.

All parameters in the call are mandatory, even if fewer than three calculations are requested. For example, if you do not request the number of messages calculation, you must still provide a value for pcMessages.

For more information on this function, see Folder Snapshot Functions in the Gateway Programmer's Reference.

See Also

CloseFolderMetrics, HrOpenFolderMetrics