Funzione PdhAddCounterA (pdh.h)

Articolo
11/20/2024

Aggiunge il contatore specificato alla query.

Sintassi

PDH_FUNCTION PdhAddCounterA(
  [in]  PDH_HQUERY   hQuery,
  [in]  LPCSTR       szFullCounterPath,
  [in]  DWORD_PTR    dwUserData,
  [out] PDH_HCOUNTER *phCounter
);

Parametri

[in] hQuery

Handle per la query a cui si desidera aggiungere il contatore. Questo handle viene restituito dalla funzione PdhOpenQuery .

[in] szFullCounterPath

Stringa con terminazione Null contenente il percorso del contatore. Per informazioni dettagliate sul formato di un percorso del contatore, vedere Specifica di un percorso contatore. La lunghezza massima di un percorso del contatore è PDH_MAX_COUNTER_PATH.

[in] dwUserData

Valore definito dall'utente. Questo valore diventa parte delle informazioni sul contatore. Per recuperare questo valore in un secondo momento, chiamare la funzione PdhGetCounterInfo e accedere al membro dwUserData della struttura PDH_COUNTER_INFO.

[out] phCounter

Handle per il contatore aggiunto alla query. Potrebbe essere necessario fare riferimento a questo handle nelle chiamate successive.

Valore restituito

Restituisce ERROR_SUCCESS se la funzione ha esito positivo.

Se la funzione ha esito negativo, il valore restituito è un codice di errore di sistema o un codice di errore PDH . Di seguito sono riportati i valori possibili.

Codice restituito	Descrizione
PDH_CSTATUS_BAD_COUNTERNAME	Impossibile analizzare o interpretare il percorso del contatore.
PDH_CSTATUS_NO_COUNTER	Impossibile trovare il contatore specificato nel computer o nel file di log.
PDH_CSTATUS_NO_COUNTERNAME	Il percorso del contatore è vuoto.
PDH_CSTATUS_NO_MACHINE	Il percorso non contiene un nome computer e la funzione non è riuscita a recuperare il nome del computer locale.
PDH_CSTATUS_NO_OBJECT	Impossibile trovare l'oggetto specificato nel computer o nel file di log.
PDH_FUNCTION_NOT_FOUND	Impossibile determinare la funzione di calcolo da utilizzare per questo contatore.
PDH_INVALID_ARGUMENT	Uno o più argomenti non sono validi.
PDH_INVALID_HANDLE	L'handle di query non è valido.
PDH_MEMORY_ALLOCATION_FAILURE	Impossibile allocare memoria necessaria per completare la funzione.

Osservazioni

Se il percorso del contatore contiene un carattere jolly, alla query vengono aggiunti tutti i nomi dei contatori corrispondenti al carattere jolly.

Se viene specificata un'istanza del contatore che non esiste ancora, PdhAddCounter non segnala una condizione di errore. Restituisce invece ERROR_SUCCESS. Il motivo di questo comportamento è che non è noto se è stata specificata un'istanza di contatore inesistente o se ne esisterà una ma non è ancora stata creata.

Per rimuovere il contatore dalla query, usare la funzione PdhRemoveCounter.

Esempi

Per un esempio, vedere i contatori delle prestazioni di esplorazione o lettura dei dati sulle prestazioni da un file di log.

Nota

L'intestazione pdh.h definisce PdhAddCounter 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