Função PdhParseInstanceNameA (pdh.h)

Artigo
11/20/2024

Analisa os elementos de uma cadeia de caracteres de instância.

Sintaxe

PDH_FUNCTION PdhParseInstanceNameA(
  [in]      LPCSTR  szInstanceString,
  [out]     LPSTR   szInstanceName,
  [in, out] LPDWORD pcchInstanceNameLength,
  [out]     LPSTR   szParentName,
  [in, out] LPDWORD pcchParentNameLength,
  [out]     LPDWORD lpIndex
);

Parâmetros

[in] szInstanceString

cadeia de caracteres terminada pornulo que especifica a cadeia de caracteres da instância a ser analisada em componentes individuais. Essa cadeia de caracteres pode conter os seguintes formatos e tem menos de MAX_PATH caracteres de comprimento:

exemplo
instance#index
pai/instância
parent/instance#index

[out] szInstanceName

Buffer alocado pelo chamador que recebe o nome de instância nuloencerrado. Defina como NULL se pcchInstanceNameLength for zero.

[in, out] pcchInstanceNameLength

Tamanho do buffer szInstanceName , 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.

[out] szParentName

O buffer alocado pelo chamador que recebe o nome nuloterminado da instância pai, se for especificado. Defina como NULL se pcchParentNameLength for zero.

[in, out] pcchParentNameLength

Tamanho do buffer de szParentName , 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.

[out] lpIndex

Valor de índice da instância. Se uma entrada de índice não estiver presente na cadeia de caracteres, esse valor será zero. Esse parâmetro pode ser NULL.

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_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.
PDH_MORE_DATA	Um ou ambos os buffers de cadeia de caracteres são muito pequenos para conter os dados. Esse valor retornado será esperado se o buffer de tamanho correspondente 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_INVALID_INSTANCE	A cadeia de caracteres da instância está formatada incorretamente, excede MAX_PATH caracteres de comprimento ou não pode ser analisada.

Observações

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

Nota

O cabeçalho pdh.h define PdhParseInstanceName 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

PdhMakeCounterPath

Compartilhar via