Compartilhar via

Função PdhExpandWildCardPathA (pdh.h)

  • Artigo

Examina o computador ou o arquivo de log especificado e retorna os caminhos de contador que correspondem ao caminho de contador fornecido que contém caracteres curinga.

Para usar identificadores em fontes de dados, use a função PdhExpandWildCardPathH .

Sintaxe

PDH_FUNCTION PdhExpandWildCardPathA(
  [in]      LPCSTR  szDataSource,
  [in]      LPCSTR  szWildCardPath,
  [out]     PZZSTR  mszExpandedPathList,
  [in, out] LPDWORD pcchPathListLength,
  [in]      DWORD   dwFlags
);

Parâmetros

[in] szDataSource

cadeia de caracteres terminada pornulo que contém o nome de um arquivo de log. A função usa os objetos de desempenho e os contadores definidos no arquivo de log para expandir o caminho especificado no parâmetro szWildCardPath .

Se NULL, a função pesquisa o computador especificado em szWildCardPath.

[in] szWildCardPath

cadeia de caracteres terminada pornulo que especifica o caminho do contador a ser expandido. O comprimento máximo de um caminho de contador é PDH_MAX_COUNTER_PATH.

Se o parâmetro szDataSource for NULL, 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.

[out] mszExpandedPathList

Buffer alocado pelo chamador que recebe uma lista de caminhos de contador nulosencerrados que correspondem à especificação curinga noszWildCardPath . A lista é encerrada por dois caracteres NULL . Defina como NULL se pcchPathListLength for zero.

[in, out] pcchPathListLength

Tamanho do buffer de mszExpandedPathList , em TCHARs. Se houver zero na entrada e no objeto, 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.

Observação Você deve adicionar um ao tamanho necessário no Windows XP.
 

[in] dwFlags

Sinalizadores que indicam quais caracteres curinga não expandir. Você pode especificar um ou mais sinalizadores.

Valor Significado
PDH_NOEXPANDCOUNTERS
 Não expanda o nome do contador se o caminho contiver um caractere curinga para o nome do contador.
PDH_NOEXPANDINSTANCES
 Não expanda o nome da instância se o caminho contiver um caractere curinga para instância pai, nome da instância ou índice de instância.
PDH_REFRESHCOUNTERS
 Atualize a lista de contadores.

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 .

Código de retorno Descrição
PDH_MORE_DATA
 O buffer mszExpandedPathList não é grande o suficiente 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á contar com o 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_INVALID_PATH
 O objeto especificado não contém uma instância.
PDH_MEMORY_ALLOCATION_FAILURE
 Não é possível alocar memória para dar suporte a essa função.
PDH_CSTATUS_NO_OBJECT
 Não é possível localizar o objeto especificado no computador ou no arquivo de log.

Observações

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

PdhExpandWildCardPath difere PdhExpandCounterPath das seguintes maneiras:

  1. Permite controlar quais caracteres curinga são expandidos.
  2. O conteúdo de um arquivo de log pode ser usado como a origem dos nomes de contador.
O formato de caminho do contador geral é 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.

Veja a seguir uma lista dos possíveis formatos:

  • \\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
Use um asterisco (*) como caractere curinga, por exemplo, \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. Por exemplo, \object(*/instance)\counter.

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. Por exemplo, \object(parent/*)\counter. Se o objeto não contiver uma instância, ocorrerá um erro.

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

Há suporte para correspondências parciais de cadeia de caracteres de caminho de contador (por exemplo, "pro*").

Antes do Windows Vista: não há suporte para correspondências curinga parciais .

Nota

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

PdhEnumObjectItems

PdhEnumObjects

PdhExpandCounterPath

PdhExpandWildCardPathH