PdhEnumObjectItems

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

PDH_STATUS PdhEnumObjectItems(
  IN LPCTSTR szReserved,  // reserved
  IN LPCTSTR szMachineName,  // machine name
  IN LPCTSTR szObjectName,  // object name
  IN LPTSTR mszCounterList,  // buffer for object's counters
  IN LPDWORD pcchCounterListLength,
                          // size of counter list buffer
  IN LPTSTR mszInstanceList,  // buffer for object's instances
  IN LPDWORD pcchInstanceListLength,
                          // size of instance list buffer
  IN DWORD dwDetailLevel,  // detail level
  IN DWORD dwFlags        // formatting flag
);
 

Parameters

szReserved

Reserved. Must be NULL.

szMachineName

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

The name of the object on the specified machine from which the items are to be listed.

mszCounterList

The buffer allocated by the calling function that is to receive 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 DWORD referenced by pcchCounterListLength is 0.

pcchCounterListLength

A pointer to a DWORD containing the size, in characters, of the available buffer, and which returns the size of the buffer used. If the buffer size on entry is zero, then no data is returned in the mszCounterList buffer, and the size of the buffer required is returned in the DWORD pointed to by pdwCounterListLength. The size returned includes both terminating NULL characters of the MULTI_SZ string.

mszInstanceList

The buffer allocated by the calling function that is to receive 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 DWORD pointed to by pcchCounterListLength is 0.

pcchInstanceListLength

A pointer to the DWORD containing the size, in characters, of the available buffer, and which returns the size of the buffer used. If the buffer size on entry is zero, then no data is returned in the mszInstanceList buffer, and the size of the buffer required is returned in the DWORD 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 in this DWORD will be 2, which is the size, in characters, of an empty MULTI_SZ list string.

dwDetailLevel

The detail level of the performance items to return. All items that are of the specified detail level or less will be returned.

dwFlags

Must be 0.

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:

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.

See Also

Performance Data Helper Overview, Performance Data Functions, , PdhConnectMachine, PdhEnumObjects