Função PdhExpandCounterPathA (pdh.h)

  • Artigo

Examina o computador especificado (ou computador local, se nenhum for especificado) para contadores e instâncias de contadores que correspondem às cadeias de caracteres curinga no caminho do contador.

Nota Essa função é substituída pela função PdhExpandWildCardPath .
 

Sintaxe

PDH_FUNCTION PdhExpandCounterPathA(
  [in]      LPCSTR  szWildCardPath,
  [out]     PZZSTR  mszExpandedPathList,
  [in, out] LPDWORD pcchPathListLength
);

Parâmetros

[in] szWildCardPath

Cadeia de caracteres terminada em nulo que contém o caminho do contador a ser expandido. A função pesquisa o computador especificado no caminho para correspondências. Se o caminho não especificar um computador, a função pesquisa o computador local. O comprimento máximo de um caminho de contador é PDH_MAX_COUNTER_PATH.

[out] mszExpandedPathList

Buffer alocado pelo chamador que recebe a lista de caminhos de contador expandidos que correspondem à especificação curinga em szWildCardPath. Cada caminho de contador nessa lista é encerrado por um caractere nulo . A lista é encerrada com dois caracteres NULL . Defina como NULL se pcchPathListLength for zero.

[in, out] pcchPathListLength

Tamanho do buffer mszExpandedPathList , 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 que foi usado. Se o tamanho especificado na entrada for maior que zero, mas menor que o tamanho necessário, você não deverá depender do tamanho retornado para realocar o buffer.

Nota Você deve adicionar um ao tamanho necessário no Windows XP.
 

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.

Código de retorno Descrição
PDH_MORE_DATA
 O buffer mszExpandedPathList é muito pequeno para conter a lista de caminhos. Esse valor retornado será esperado se pcchPathListLength 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á depender do tamanho retornado para realocar o buffer.
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_MEMORY_ALLOCATION_FAILURE
 Não é possível alocar memória para dar suporte a essa função.

Comentários

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

O formato geral do caminho do contador é o seguinte:

\computer\object(parent/instance#index)\counter

Os componentes pai, instância, índice e contador do caminho do contador podem conter um nome válido ou um caractere curinga. Os componentes de computador, pai, instância e índice não são necessários para todos os contadores.

Os caminhos de contador que você deve usar são determinados pelo próprio contador. Por exemplo, o objeto LogicalDisk tem um índice de instância, portanto, você deve fornecer o #index ou um curinga. Portanto, você pode usar o seguinte formato:

\LogicalDisk(/#*)*

Em comparação, o objeto Process não requer um índice de instância. Portanto, você pode usar o seguinte formato:

\Process(*)\ID Process

Veja a seguir uma lista dos formatos possíveis:

  • \\computer\object(parent/instance#index)\counter
  • \\computer\object(parent/instance)\counter
  • \\computer\object(instance#index)\counter
  • \\computer\object(instance)\counter
  • \\computer\object\counter
  • \object(parent/instance#index)\counter
  • \object(parent/instance)\counter
  • \object(instance#index)\counter
  • \object(instance)\counter
  • \object\counter
Se um caractere curinga for especificado no nome pai, todas as instâncias do objeto especificado que correspondem aos campos de instância e contador especificados serão retornadas.

Se um caractere curinga for especificado no nome da instância, todas as instâncias do objeto e do objeto pai especificados serão retornadas se todos os nomes de instância correspondentes ao índice especificado corresponderem ao caractere curinga.

Se um caractere curinga for especificado no nome do contador, todos os contadores do objeto especificado serão retornados.

Não há suporte para correspondências parciais de cadeia de caracteres de caminho do contador (por exemplo, "pro*").

Exemplos

O exemplo a seguir demonstra como essa função.


#include <windows.h>
#include <stdio.h>
#include <stdlib.h>
#include <pdh.h>
#include <pdhmsg.h>

#pragma comment(lib, "pdh.lib")

CONST PWSTR WILDCARD_PATH = L"\\Processor(*)\\*";

void wmain(void)
{
    PDH_STATUS Status;
    PWSTR EndOfPaths;
    PWSTR Paths = NULL;
    DWORD BufferSize = 0;

    Status = PdhExpandCounterPath(WILDCARD_PATH, Paths, &BufferSize);

    while (Status == PDH_MORE_DATA) 
    {
        Paths = (PWSTR)malloc(BufferSize * sizeof(WCHAR));
        Status = PdhExpandCounterPath(WILDCARD_PATH, Paths, &BufferSize);
    }

    if (Status != ERROR_SUCCESS) 
    {
        wprintf(L"\nPdhExpandCounterPath failed with status 0x%x", Status);
        goto Cleanup;
    }

    if (Paths == NULL) 
    {
        wprintf(L"\nThe counter path %s cannot be expanded.", WILDCARD_PATH);
        goto Cleanup;
    }

    EndOfPaths = Paths + BufferSize;

    // On Vista and later operating systems, the buffer is terminated with two 
    // null-terminator characters; however, on earlier systems, the buffer is
    // not terminated with two null-terminator characters. This covers both cases.
    for (PWSTR p = Paths; ((p != EndOfPaths) && (*p != L'\0')); p += wcslen(p) + 1) 
    {
        wprintf(L"\n%s", p);
    }

Cleanup:
    if (Paths) 
    {
        free(Paths);
    }
}

Observação

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

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

PdhExpandWildCardPath

PdhMakeCounterPath