Condividi tramite

Funzione PdhExpandWildCardPathHA (pdh.h)

  • Articolo

Esamina il computer o il file di log specificato e restituisce i percorsi dei contatori corrispondenti al percorso del contatore specificato che contiene caratteri jolly.

Questa funzione è identica alla funzione PdhExpandWildCardPath , ad eccezione del fatto che supporta l'uso di handle per le origini dati.

Sintassi

PDH_FUNCTION PdhExpandWildCardPathHA(
  [in]      PDH_HLOG hDataSource,
  [in]      LPCSTR   szWildCardPath,
  [out]     PZZSTR   mszExpandedPathList,
  [in, out] LPDWORD  pcchPathListLength,
  [in]      DWORD    dwFlags
);

Parametri

[in] hDataSource

Handle in un'origine dati restituita dalla funzione PdhBindInputDataSource.

[in] szWildCardPath

Nullstringa con terminazione che specifica il percorso del contatore da espandere. La lunghezza massima di un percorso del contatore è PDH_MAX_COUNTER_PATH.

Se hDataSource è un'origine dati in tempo reale, la funzione cerca nel computer specificato nel percorso le corrispondenze. Se il percorso non specifica un computer, la funzione cerca nel computer locale.

[out] mszExpandedPathList

Buffer allocato dal chiamante che riceve un elenco di percorsi del contatore nullterminati che corrispondono alla specifica del carattere jolly nella szWildCardPath. L'elenco viene terminato da due caratteri NULL. Impostare su NULL se pcchPathListLength è zero.

[in, out] pcchPathListLength

Dimensioni del buffer di mszExpandedPathList , in TCHARs. Se zero per l'input e l'oggetto esiste, la funzione restituisce PDH_MORE_DATA e imposta questo parametro sulla dimensione del buffer richiesta. Se il buffer è maggiore delle dimensioni necessarie, la funzione imposta questo parametro sulle dimensioni effettive del buffer utilizzato. Se la dimensione specificata per l'input è maggiore di zero ma minore della dimensione richiesta, non è consigliabile basarsi sulle dimensioni restituite per riallocare il buffer.

Nota È necessario aggiungerne una alle dimensioni necessarie in Windows XP.
 

[in] dwFlags

Flag che indicano quali caratteri jolly non espandere. È possibile specificare uno o più flag.

Valore Significato
PDH_NOEXPANDCOUNTERS
 Non espandere il nome del contatore se il percorso contiene un carattere jolly per il nome del contatore.
PDH_NOEXPANDINSTANCES
 Non espandere il nome dell'istanza se il percorso contiene un carattere jolly per l'istanza padre, il nome dell'istanza o l'indice dell'istanza.
PDH_REFRESHCOUNTERS
 Aggiornare l'elenco dei contatori.

Valore restituito

Se la funzione ha esito positivo, restituisce ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito è un codice di errore di sistema o un codice di errore PDH .

Codice restituito Descrizione
PDH_MORE_DATA
 Il buffer mszExpandedPathList non è sufficientemente grande da contenere l'elenco di percorsi. Questo valore restituito è previsto se pcchPathListLength è zero in input. Se la dimensione specificata per l'input è maggiore di zero ma minore della dimensione richiesta, non è consigliabile basarsi sulle dimensioni restituite per riallocare il buffer.
PDH_INVALID_ARGUMENT
 Parametro non valido. Ad esempio, in alcune versioni è possibile ricevere questo errore se la dimensione specificata per l'input è maggiore di zero, ma minore della dimensione richiesta.
PDH_MEMORY_ALLOCATION_FAILURE
 Impossibile allocare memoria per supportare questa funzione.
PDH_CSTATUS_NO_OBJECT
 Impossibile trovare l'oggetto specificato nel computer o nel file di log.

Osservazioni

È necessario chiamare questa funzione due volte, la prima volta per ottenere le dimensioni del buffer necessarie (impostare mszExpandedPathList su null e pcchPathListLength su 0) e la seconda volta per ottenere i dati.

PdhExpandWildCardPathH differisce da PdhExpandCounterPath nei modi seguenti:

  1. Consente di controllare quali caratteri jolly sono espansi.
  2. Il contenuto di un file di log può essere usato come origine dei nomi dei contatori.
Il formato generale del percorso del contatore è il seguente:

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

I componenti padre, istanza, indice e contatore del percorso del contatore possono contenere un nome valido o un carattere jolly. I componenti computer, padre, istanza e indice non sono necessari per tutti i contatori.

Di seguito è riportato un elenco dei formati possibili:

  • \\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
Usare un asterisco (*) come carattere jolly, ad esempio \object(*)\counter.

Se viene specificato un carattere jolly nel nome padre, verranno restituite tutte le istanze dell'oggetto specificato che corrispondono all'istanza e ai campi del contatore specificati. Ad esempio, \object(*/instance)\counter.

Se nel nome dell'istanza viene specificato un carattere jolly, verranno restituite tutte le istanze dell'oggetto specificato e dell'oggetto padre se tutti i nomi di istanza corrispondenti all'indice specificato corrispondono al carattere jolly. Ad esempio, \object(parent/*)\counter.

Se viene specificato un carattere jolly nel nome del contatore, vengono restituiti tutti i contatori dell'oggetto specificato.

Le corrispondenze parziali della stringa di percorso del contatore (ad esempio, "pro*") sono supportate.

Precedente a Windows Vista: corrispondenze con caratteri jolly parziali non sono supportate.

Nota

L'intestazione pdh.h definisce PdhExpandWildCardPathH come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito Valore
client minimo supportato Windows XP [solo app desktop]
server minimo supportato Windows Server 2003 [solo app desktop]
piattaforma di destinazione Finestre
intestazione pdh.h
libreria Pdh.lib
dll Pdh.dll

Vedere anche

funzione PdhBindInputDataSourceAfunzione PdhEnumObjectItemsHAfunzione PdhEnumObjectsHAfunzione PdhExpandCounterPathA