Funzione PdhExpandCounterPathA (pdh.h)

Articolo
11/20/2024

Esamina il computer specificato (o il computer locale se non è specificato nessuno) per i contatori e le istanze di contatori che corrispondono alle stringhe con caratteri jolly nel percorso del contatore.

Nota Questa funzione viene sostituita dalla funzione PdhExpandWildCardPath .

Sintassi

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

Parametri

[in] szWildCardPath

nullstringa con terminazione contenente il percorso del contatore da espandere. La funzione cerca le corrispondenze nel computer specificato nel percorso. Se il percorso non specifica un computer, la funzione cerca nel computer locale. La lunghezza massima di un percorso del contatore è PDH_MAX_COUNTER_PATH.

[out] mszExpandedPathList

Buffer allocato dal chiamante che riceve l'elenco dei percorsi dei contatori espansi che corrispondono alla specifica con caratteri jolly in szWildCardPath. Ogni percorso del contatore in questo elenco viene terminato da un carattere null. L'elenco viene terminato con due caratteri NULL. Impostare su NULL se pcchPathListLength è zero.

[in, out] pcchPathListLength

Dimensioni del buffer di mszExpandedPathList , in TCHARs. Se zero in ingresso, 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.

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 è troppo piccolo per 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.

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.

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.

I percorsi dei contatori che è necessario utilizzare sono determinati dal contatore stesso. Ad esempio, l'oggetto LogicalDisk ha un indice di istanza, pertanto è necessario specificare il #index o un carattere jolly. Pertanto, è possibile usare il formato seguente:

\LogicalDisk(/#*)*

In confronto, l'oggetto Process non richiede un indice di istanza. Pertanto, è possibile usare il formato seguente:

\Process(*)\ID Process

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

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.

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.

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*") non sono supportate.

Esempi

Nell'esempio seguente viene illustrato come eseguire questa funzione.


#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);
    }
}

Nota

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

PdhExpandWildCardPath

PdhMakeCounterPath

Condividi tramite