PdhEnumObjects

The PdhEnumObjects function returns a list of objects available on the specified machine.

PDH_STATUS PdhEnumObjects(
  LPCTSTR szDataSource,    
  LPCTSTR szMachineName,   
  LPTSTR mszObjectList,    
  LPDWORD pcchBufferLength, 
  DWORD dwDetailLevel,     
  BOOL bRefresh            
);

Parameters

szDataSource

Windows 2000: [in] A pointer to a null-terminated string containing either the name of a log file or a null string. 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 objects. If the machine specified is not in the list of currently connected machines, the PDH will try to connect to the machine and add it to the list.

mszObjectList

[out] A pointer to a null-terminated string containing the name of a buffer, allocated by the calling function, that receives the MULTI_SZ list of objects available on the specified machine. Each object name in this list is terminated by a NULL character. This parameter may be NULL if the value of the variable pointed to by pcchBufferLength is zero.

pcchBufferLength

[in/out] A pointer to a variable containing the size, in characters, of the available buffer on input and the size of the returned buffer on output. If the buffer size is zero on input, no data is returned in the mszObjectList buffer, and the parameter can be NULL. However, the size of the buffer required, in characters, is returned in the variable pointed to by pcchBufferLength. The size returned includes both terminating NULL characters of the MULTI_SZ 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_DETAIL_NOVICE	Novice user level of detail.
PERF_DETAIL_ADVANCED	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.

bRefresh

[in] Indicates whether a new list of objects will be obtained from the specified machine. If the machine is not currently connected by the PDH, then this flag is ignored and the list is refreshed automatically. This parameter can be one of the following values.

Value	Meaning
TRUE	A new performance data buffer for this machine will be cached before the objects are returned.
FALSE	A new performance data buffer for this machine will not be cached; the object list will be returned from currently cached performance data buffer.

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.

Remarks

When you request a required buffer size, the bRefresh flag should be FALSE for all subsequent calls to this function. Otherwise, the size might not be valid.

The term real-time as used in the description of this function does not imply the standard meaning of the term real-time. Instead, it describes the collection of performance data from a source providing current information (for example, the registry or a WMI provider) rather than from a log file.

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.

See Also

PdhConnectMachine, PdhEnumMachines