Criando uma consulta

Para criar uma nova consulta que coleta dados de desempenho de uma fonte ou arquivo de log em tempo real, chame a função PdhOpenQuery . A função retorna um identificador para a consulta que você usa em chamadas de função PDH subsequentes.

Depois de criar a consulta, chame a função PdhAddCounter para cada contador que você deseja adicionar à consulta. Você pode usar um dos métodos a seguir para fornecer o caminho do contador totalmente qualificado.

• Defina o caminho do contador como uma cadeia de caracteres estática. Use esse método se você sempre monitorar o mesmo contador e se estiver familiarizado com a sintaxe correta de um caminho de contador. Para obter informações sobre a sintaxe correta usada para especificar um contador, consulte Especificando um caminho de contador.
• Inicialize uma estrutura PDH_COUNTER_PATH_ELEMENTS com os nomes do computador, objeto, contador e instância. Passe essa estrutura para PdhMakeCounterPath , que retornará um caminho de contador para os elementos especificados.
• Especifique um caminho de contador que contenha caracteres curinga e chame PdhExpandWildCardPath para obter uma lista de nomes de contador que correspondam aos caracteres curinga no caminho. Examine a lista de nomes de contadores e adicione à consulta os contadores desejados nesta lista.
• Chame a função PdhBrowseCounters para exibir uma caixa de diálogo que permite que o usuário navegue e selecione contadores de desempenho. Para obter mais informações, consulte Contadores de navegação.

Observe que, se uma instância de contador for especificada que não existe, PdhAddCounter não relatará uma condição de erro. Em vez disso, retorna ERROR_SUCCESS. O motivo para esse comportamento é que não se sabe se uma instância de contador inexistente foi especificada ou uma que existirá, mas ainda não foi criada.

A instância de contador ausente será relatada por PdhCollectQueryData, PdhGetRawCounterValue ou PdhGetFormattedCounterValue. Ao chamar PdhCollectQueryData apenas para uma instância de contador e a instância do contador ainda não existir, supõe-se que a instância do contador não existirá e a função retornará PDH_NO_DATA. No entanto, se mais de um contador for consultado, PdhCollectQueryData ainda poderá retornar ERROR_SUCCESS mesmo que uma das instâncias de contador ainda não exista. Nesse caso, chame PdhGetRawCounterValue ou PdhGetFormattedCounterValue para cada uma das instâncias de contador de interesse. Se a instância não existir ao chamar PdhGetRawCounterValue, a função retornará ERROR_SUCCESS e definirá o membro CStatus de PDH_RAW_COUNTER como PDH_STATUS_NO_INSTANCE. Se a instância não existir ao chamar PdhGetFormattedCounterValue, a função retornará PDH_INVALID_DATA e definirá o membro CStatus do PDH_FMT_COUNTERVALUE como PDH_CSTATUS_NO_INSTANCE.

Observe que o caminho do contador especificado na função PdhAddCounter deve ser localizado. A função PdhAddEnglishCounter fornece uma maneira neutra de localidade para adicionar contadores de desempenho à consulta. Essa função é a maneira recomendada de adicionar contadores neutros de localidade a uma consulta.

Para remover um contador de uma consulta, chame a função PdhRemoveCounter .

Depois de concluir a coleta de dados para uma consulta, chame a função PdhCloseQuery para fechar a consulta e liberar todos os recursos do sistema alocados. PdhCloseQuery fecha todos os identificadores de contador associados à consulta.