Platform SDK: Performance Monitoring

PdhEnumObjectItems

The PdhEnumObjectItems function returns the available counters and instances provided by the specified object on the specified machine.

PDH_STATUS PdhEnumObjectItems(
  LPCTSTR szDataSource,  
  LPCTSTR szMachineName, 
  LPCTSTR szObjectName,  
  LPTSTR mszCounterList, 
  LPDWORD pcchCounterListLength,
  LPTSTR mszInstanceList,  
  LPDWORD pcchInstanceListLength,
  DWORD dwDetailLevel,  
  DWORD dwFlags       
);

Parameters

szDataSource

Windows 2000: [in] A pointer to a null-terminated string containing either the name of a log file or the null termination only. If you specify the name of a log file, performance data will be taken from that log file. If this parameter contains a null string, performance data will be collected from a real-time data source.

Windows NT 4.0: [in] Reserved. Must be NULL.

szMachineName

[in] A pointer to a null-terminated string containing the name of the machine on which to list the object items. If the machine specified is not in the list of currently connected machines, the PDH will try to connect to it.

szObjectName

[in] A pointer to a null-terminated string containing the name of the object on the specified machine from which the items are to be listed.

mszCounterList

[out] A pointer to a null-terminated string containing the name of the buffer allocated by the calling function that receives the MULTI_SZ list of performance counters provided by the specified object on the specified machine. This parameter can be NULL if the value of the variable referenced by pcchCounterListLength is zero.

pcchCounterListLength

[in/out] A pointer to a DWORD that on input contains the size, in characters, of the available buffer. On output, it receives the size of the buffer used. If the buffer size is zero on input, no data is returned in the mszCounterList buffer, and the size of the buffer required is returned in the variable referenced by pcchCounterListLength. The size returned includes both terminating NULL characters of the MULTI_SZ string.

mszInstanceList

[out] A pointer to a null-terminated string containing the name of the buffer allocated by the calling function that receives the MULTI_SZ list of the instances of the specified object on the specified machine. This argument can be NULL if the value of the variable pointed to by pcchCounterListLength is zero.

pcchInstanceListLength

[in/out] A pointer to a variable that on input contains the size, in characters, of the available buffer. On output, it receives the size of the buffer used. If the buffer size is zero on input, no data is returned in the mszInstanceList buffer, and the size of the buffer required is returned in the variable pointed to by pcchInstanceListLength. The size returned includes both terminating NULL characters of the MULTI_SZ string. If the specified object does not support variable instances, then the returned value will be 0. If the specified object does support variable instances, but does not currently have any instances, then the value returned is 2, which is the size, in characters, of an empty MULTI_SZ list string.

dwDetailLevel

[in] The detail level of the performance items to return. All items that are of the specified detail level or less will be returned. This parameter can be one of the following values.

Value	Meaning
PERF_LEVEL_NOVICE	Novice user level of detail.
PERF_LEVEL_ADVANCE	Advanced user level of detail. Includes the novice level of detail.
PERF_DETAIL_EXPERT	Expert user level of detail. Includes the novice and advanced levels of detail.
PERF_DETAIL_WIZARD	System designer level of detail. Includes all levels of detail.

dwFlags

This parameter must be zero.

Return Values

If the function succeeds, it returns ERROR_SUCCESS.

If the function fails, the return value is a PDH error status defined in PDHMsg.h. The following are possible error values.

Error value	Description
PDH_MORE_DATA	There are more entries available to return than there is room in the buffer. Some entries might be returned in the buffer, however.
PDH_INSUFFICIENT_BUFFER	The buffer provided is not large enough to contain any data.
PDH_INVALID_ARGUMENT	A required argument is invalid or a reserved argument is not NULL.
PDH_MEMORY_ALLOCATION_FAILURE	A required temporary buffer could not be allocated.
PDH_CSTATUS_NO_MACHINE	The specified machine is offline or unavailable.
PDH_CSTATUS_NO_OBJECT	The specified object could not be found on the specified machine.

Remarks

Consecutive calls to this function will return identical lists of counters and instances, because PdhEnumObjectItems will always query the list of performance objects defined by the last call to PdhEnumObjects. To refresh the list of performance objects, call PdhEnumObjects with a bRefresh flag value of TRUE before calling PdhEnumObjectItems again.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Header: Declared in Pdh.h.
  Library: Use Pdh.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

PdhEnumObjectItems

Parameters

Return Values

Remarks

Requirements

See Also