Função PdhEnumObjectsHA (pdh.h)

Artigo
11/20/2024

Retorna uma lista de objetos disponíveis no computador especificado ou no arquivo de log especificado.

Essa função é idêntica a PdhEnumObjects, exceto que dá suporte ao uso de identificadores para fontes de dados.

Sintaxe

PDH_FUNCTION PdhEnumObjectsHA(
  [in]      PDH_HLOG hDataSource,
  [in]      LPCSTR   szMachineName,
  [out]     PZZSTR   mszObjectList,
  [in, out] LPDWORD  pcchBufferSize,
  [in]      DWORD    dwDetailLevel,
  [in]      BOOL     bRefresh
);

Parâmetros

[in] hDataSource

Manipule para uma fonte de dados retornada pela função PdhBindInputDataSource .

[in] szMachineName

cadeia de caracteres terminada pornulo que especifica o nome do computador usado para enumerar os objetos de desempenho.

Inclua as barras principais no nome do computador, por exemplo, \computername.

Se szDataSource for NULL, você poderá definir szMachineName para NULL para especificar o computador local.

[out] mszObjectList

Buffer alocado pelo chamador que recebe a lista de nomes de objetos. Cada nome de objeto nesta lista é encerrado por um caractere de nulo. A lista é encerrada com dois caracteres nulos-terminator. Defina como NULL se pcchBufferLength for zero.

[in, out] pcchBufferSize

Tamanho do buffer mszObjectList , em TCHARs . Se zero na entrada, a função retornará PDH_MORE_DATA e definirá esse parâmetro como o tamanho do buffer necessário. Se o buffer for maior que o tamanho necessário, a função definirá esse parâmetro como o tamanho real do buffer usado. Se o tamanho especificado na entrada for maior que zero, mas menor que o tamanho necessário, você não deverá contar com o tamanho retornado para realocar o buffer.

Windows XP: Adicionar um ao tamanho do buffer necessário.

[in] dwDetailLevel

Nível de detalhes dos itens de desempenho a serem retornados. Todos os itens que são do nível de detalhes especificado ou menos serão retornados (os níveis são listados em ordem crescente). Esse parâmetro pode ser um dos valores a seguir.

Valor	Significado
PERF_DETAIL_NOVICE	Nível de detalhes do usuário novato.
PERF_DETAIL_ADVANCED	Nível de usuário avançado de detalhes.
PERF_DETAIL_EXPERT	Nível de usuário especialista em detalhes.
PERF_DETAIL_WIZARD	Nível de detalhes do designer do sistema.

[in] bRefresh

Indica se a lista de objetos armazenados em cache deve ser atualizada automaticamente. Especifique um dos valores a seguir.

Se você chamar essa função duas vezes, uma vez para obter o tamanho da lista e uma segunda vez para obter a lista real, defina esse parâmetro para TRUE na primeira chamada e FALSE na segunda chamada. Se ambas as chamadas forem VERDADEIRO, a segunda chamada também poderá retornar PDH_MORE_DATA porque os dados do objeto podem ter sido alterados entre chamadas.

Valor	Significado
verdadeiro	O cache de objetos é atualizado automaticamente antes que os objetos sejam retornados.
falso	Não atualize automaticamente o cache.

Valor de retorno

Se a função for bem-sucedida, ela retornará ERROR_SUCCESS.

Se a função falhar, o valor retornado será um código de erro do sistema ou um código de erro PDH . Veja a seguir os valores possíveis.

Código de retorno	Descrição
PDH_MORE_DATA	O buffer mszObjectList é muito pequeno para manter a lista de objetos. Esse valor retornado será esperado se pcchBufferLength for zero na entrada. Se o tamanho especificado na entrada for maior que zero, mas menor que o tamanho necessário, você não deverá contar com o tamanho retornado para realocar o buffer.
PDH_CSTATUS_NO_MACHINE	O computador especificado está offline ou indisponível.
PDH_CSTATUS_NO_OBJECT	Não foi possível encontrar o objeto especificado.
PDH_INVALID_ARGUMENT	Um parâmetro não é válido. Por exemplo, em algumas versões, você poderá receber esse erro se o tamanho especificado na entrada for maior que zero, mas menor que o tamanho necessário.

Observações

Você deve chamar essa função duas vezes, a primeira vez para obter o tamanho do buffer necessário (definir mszObjectList para NULL e pcchBufferLength para 0) e a segunda vez para obter os dados.

Nota

O cabeçalho pdh.h define PdhEnumObjectsH como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	pdh.h
biblioteca	Pdh.lib
de DLL	Pdh.dll

Consulte também

PdhBindInputDataSource

PdhEnumObjectItemsH

Compartilhar via