Função PdhGetFormattedCounterValue (pdh.h)

  • Artigo

Calcula um valor exibivel para o contador especificado.

Sintaxe

PDH_FUNCTION PdhGetFormattedCounterValue(
  [in]  PDH_HCOUNTER          hCounter,
  [in]  DWORD                 dwFormat,
  [out] LPDWORD               lpdwType,
  [out] PPDH_FMT_COUNTERVALUE pValue
);

Parâmetros

[in] hCounter

Identificador do contador para o qual você deseja calcular um valor exibivel. A função PdhAddCounter retorna esse identificador.

[in] dwFormat

Determina o tipo de dados do valor formatado. Especifique um dos valores a seguir.

Valor Significado
PDH_FMT_DOUBLE
 Retornar dados como um ponto flutuante de precisão dupla real.
PDH_FMT_LARGE
 Retornar dados como um inteiro de 64 bits.
PDH_FMT_LONG
 Retornar dados como um inteiro longo.
 

Você pode usar o operador OR inclusivo bit a bit (|) para combinar o tipo de dados com um dos seguintes fatores de dimensionamento.

Valor Significado
PDH_FMT_NOSCALE
 Não aplique o fator de dimensionamento padrão do contador.
PDH_FMT_NOCAP100
 Valores de contador superiores a 100 (por exemplo, valores de contador que medem a carga do processador em computadores multiprocessadores) não serão redefinidos para 100. O comportamento padrão é que os valores do contador são limitados a um valor de 100.
PDH_FMT_1000
 Multiplique o valor real por 1.000.

[out] lpdwType

Recebe o tipo de contador. Para obter uma lista de tipos de contador, consulte a seção Tipos de contador do Kit de Implantação do Windows Server 2003. Esse parâmetro é opcional.

[out] pValue

Uma estrutura PDH_FMT_COUNTERVALUE que recebe o valor do contador.

Retornar valor

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 ou está formatado incorretamente.
PDH_INVALID_DATA
 O contador especificado não contém dados válidos ou um código de status bem-sucedido.
PDH_INVALID_HANDLE
 O identificador do contador não é válido.

Comentários

Os dados do contador são bloqueados (protegidos) durante a chamada para PdhGetFormattedCounterValue para evitar alterações durante o processamento da chamada. A leitura dos dados (chamando essa função com êxito) limpa o sinalizador alterado por dados para o contador.

Alguns contadores, como contadores de taxa, exigem dois valores de contador para calcular um valor exibivel. Nesse caso, você deve chamar PdhCollectQueryData duas vezes antes de chamar PdhGetFormattedCounterValue. Para obter mais informações, consulte Coletando dados de desempenho.

Se a instância do contador especificada não existir, o método retornará PDH_INVALID_DATA e definirá o membro CStatus da estrutura PDH_FMT_COUNTERVALUE como PDH_CSTATUS_NO_INSTANCE.

Antes do Windows Server 2003: A chamada de formato pode falhar para contadores que exigem apenas um único valor quando a instância não é encontrada. Tente chamar a consulta e formatar chamadas novamente. Se a chamada de formato falhar na segunda vez, a instância não será encontrada. Como alternativa, você pode chamar a função PdhEnumObjects com a opção de atualização definida como TRUE para atualizar as instâncias de contador antes de consultar e formatar os dados do contador.

Exemplos

Para obter um exemplo, consulte Navegando contadores de desempenho ou lendo dados de desempenho de um arquivo de log.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho pdh.h
Biblioteca Pdh.lib
DLL Pdh.dll

Confira também

PdhCollectQueryData

PdhGetRawCounterValue

PdhSetCounterScaleFactor