Fungsi PdhExpandCounterPathA (pdh.h)

Memeriksa komputer yang ditentukan (atau komputer lokal jika tidak ada yang ditentukan) untuk penghitung dan instans penghitung yang cocok dengan string wildcard di jalur penghitung.

Sintaksis

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

Parameter

[in] szWildCardPath

String null-dihentikan yang berisi jalur penghitung untuk diperluas. Fungsi mencari komputer yang ditentukan dalam jalur untuk kecocokan. Jika jalur tidak menentukan komputer, fungsi akan mencari komputer lokal. Panjang maksimum jalur penghitung adalah PDH_MAX_COUNTER_PATH.

[out] mszExpandedPathList

Buffer yang dialokasikan pemanggil yang menerima daftar jalur penghitung yang diperluas yang cocok dengan spesifikasi wildcard di szWildCardPath. Setiap jalur penghitung dalam daftar ini dihentikan oleh karakter null . Daftar dihentikan dengan dua karakter NULL. Atur ke NULL jika pcchPathListLength adalah nol.

[in, out] pcchPathListLength

Ukuran buffer mszExpandedPathList, dalam TCHAR. Jika nol pada input, fungsi mengembalikan PDH_MORE_DATA dan mengatur parameter ini ke ukuran buffer yang diperlukan. Jika buffer lebih besar dari ukuran yang diperlukan, fungsi mengatur parameter ini ke ukuran buffer aktual yang digunakan. Jika ukuran yang ditentukan pada input lebih besar dari nol tetapi kurang dari ukuran yang diperlukan, Anda tidak boleh mengandalkan ukuran yang dikembalikan untuk merealokasi buffer.

Mengembalikan nilai

Jika fungsi berhasil, fungsi akan mengembalikan ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah kode kesalahan sistem atau kode kesalahan PDH .

Mengembalikan kode	Deskripsi
PDH_MORE_DATA	Buffer mszExpandedPathList terlalu kecil untuk berisi daftar jalur. Nilai pengembalian ini diharapkan jika pcchPathListLength adalah nol pada input. Jika ukuran yang ditentukan pada input lebih besar dari nol tetapi kurang dari ukuran yang diperlukan, Anda tidak boleh mengandalkan ukuran yang dikembalikan untuk merealokasi buffer.
PDH_INVALID_ARGUMENT	Parameter tidak valid. Misalnya, pada beberapa rilis, Anda dapat menerima kesalahan ini jika ukuran yang ditentukan pada input lebih besar dari nol tetapi kurang dari ukuran yang diperlukan.
PDH_MEMORY_ALLOCATION_FAILURE	Tidak dapat mengalokasikan memori untuk mendukung fungsi ini.

Komentar

Anda harus memanggil fungsi ini dua kali, pertama kali untuk mendapatkan ukuran buffer yang diperlukan (atur mszExpandedPathList ke null dan pcchPathListLength ke 0), dan kedua kalinya untuk mendapatkan data.

Format jalur penghitung umum adalah sebagai berikut:

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

Komponen induk, instans, indeks, dan penghitung dari jalur penghitung mungkin berisi nama yang valid atau karakter kartubebas. Komponen komputer, induk, instans, dan indeks tidak diperlukan untuk semua penghitung.

Jalur penghitung yang harus Anda gunakan ditentukan oleh penghitung itu sendiri. Misalnya, objek LogicalDisk memiliki indeks instans, jadi Anda harus menyediakan #index, atau kartubebas. Oleh karena itu, Anda dapat menggunakan format berikut:

\LogicalDisk(/#*)*

Sebagai perbandingan, objek Proses tidak memerlukan indeks instans. Oleh karena itu, Anda dapat menggunakan format berikut:

\Process(*)\ID Process

Berikut ini adalah daftar format yang mungkin:

• \\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

Jika karakter kartubebas ditentukan dalam nama induk, semua instans objek yang ditentukan yang cocok dengan instans dan bidang penghitung yang ditentukan akan dikembalikan.

Jika karakter kartubebas ditentukan dalam nama instans, semua instans objek dan objek induk yang ditentukan akan dikembalikan jika semua nama instans yang sesuai dengan indeks yang ditentukan cocok dengan karakter kartubebas.

Jika karakter kartubebas ditentukan dalam nama penghitung, semua penghitung objek yang ditentukan dikembalikan.

String jalur penghitung parsial cocok (misalnya, "pro*") tidak didukung.

Contoh

Contoh berikut menunjukkan cara fungsi ini.

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

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Platform Target	Windows
Header	pdh.h
Pustaka	Pdh.lib
DLL	Pdh.dll

Lihat juga

PdhExpandWildCardPath

PdhMakeCounterPath