fungsi CM_Get_Device_Interface_ListA (cfgmgr32.h)

Artikel
08/22/2023

Fungsi CM_Get_Device_Interface_List mengambil daftar instans antarmuka perangkat milik kelas antarmuka perangkat tertentu.

Sintaks

CMAPI CONFIGRET CM_Get_Device_Interface_ListA(
  [in]           LPGUID      InterfaceClassGuid,
  [in, optional] DEVINSTID_A pDeviceID,
  [out]          PZZSTR      Buffer,
  [in]           ULONG       BufferLen,
  [in]           ULONG       ulFlags
);

Parameter

[in] InterfaceClassGuid

Menyediakan GUID yang mengidentifikasi kelas antarmuka perangkat.

[in, optional] pDeviceID

Penunjuk yang disediakan penelepon ke string yang dihentikan NULL yang mewakili ID instans perangkat. Jika ditentukan, fungsi mengambil antarmuka perangkat yang didukung oleh perangkat untuk kelas yang ditentukan. Jika nilai ini NULL, atau jika menunjuk ke string panjang nol, fungsi mengambil semua antarmuka yang termasuk dalam kelas yang ditentukan.

[out] Buffer

Penunjuk yang disediakan penelepon ke buffer yang menerima beberapa string Unicode yang dihentikan NULL, masing-masing mewakili nama tautan simbolis instans antarmuka.

[in] BufferLen

Nilai yang disediakan penelepon yang menentukan panjang, dalam karakter, dari buffer yang ditujukkan oleh Buffer. Panggil CM_Get_Device_Interface_List_Size untuk menentukan ukuran buffer yang diperlukan.

[in] ulFlags

Berisi salah satu bendera yang disediakan penelepon berikut:

CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES

Fungsi ini menyediakan daftar yang berisi antarmuka perangkat yang terkait dengan semua perangkat yang cocok dengan GUID dan ID instans perangkat yang ditentukan, jika ada.

CM_GET_DEVICE_INTERFACE_LIST_PRESENT

Fungsi ini menyediakan daftar yang berisi antarmuka perangkat yang terkait dengan perangkat yang saat ini aktif, dan yang cocok dengan GUID dan ID instans perangkat yang ditentukan, jika ada.

Nilai kembali

Jika operasi berhasil, fungsi akan mengembalikan CR_SUCCESS. Jika tidak, ia mengembalikan salah satu kode kesalahan dengan awalan CR_ seperti yang didefinisikan dalam Cfgmgr32.h.

Tabel berikut ini menyertakan beberapa kode kesalahan yang lebih umum yang mungkin dikembalikan fungsi ini.

Menampilkan kode	Deskripsi
CR_BUFFER_SMALL	Buffer Buffer terlalu kecil untuk menyimpan daftar antarmuka perangkat yang diminta.

Keterangan

Antara memanggil CM_Get_Device_Interface_List_Size untuk mendapatkan ukuran daftar dan memanggil CM_Get_Device_Interface_List untuk mendapatkan daftar, antarmuka perangkat baru dapat ditambahkan ke sistem yang menyebabkan ukuran yang dikembalikan tidak lagi valid. Penelepon harus kuat dengan kondisi tersebut dan mencoba kembali mendapatkan ukuran dan daftar jika CM_Get_Device_Interface_List mengembalikan CR_BUFFER_SMALL.

Contoh

Cuplikan ini menggambarkan mencoba kembali mendapatkan ukuran dan daftar seperti yang dijelaskan di bagian Keterangan.

    CONFIGRET cr = CR_SUCCESS;
    PWSTR DeviceInterfaceList = NULL;
    ULONG DeviceInterfaceListLength = 0;

    do {
        cr = CM_Get_Device_Interface_List_Size(&DeviceInterfaceListLength,
                                               (LPGUID)&GUID_DEVINTERFACE_VOLUME,
                                               NULL,
                                               CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES);

        if (cr != CR_SUCCESS)
        {
            break;
        }

        if (DeviceInterfaceList != NULL) {
            HeapFree(GetProcessHeap(),
                     0,
                     DeviceInterfaceList);
        }

        DeviceInterfaceList = (PWSTR)HeapAlloc(GetProcessHeap(),
                                               HEAP_ZERO_MEMORY,
                                               DeviceInterfaceListLength * sizeof(WCHAR));

        if (DeviceInterfaceList == NULL)
        {
            cr = CR_OUT_OF_MEMORY;
            break;
        }

        cr = CM_Get_Device_Interface_List((LPGUID)&GUID_DEVINTERFACE_VOLUME,
                                          NULL,
                                          DeviceInterfaceList,
                                          DeviceInterfaceListLength,
                                          CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES);
    } while (cr == CR_BUFFER_SMALL);

    if (cr != CR_SUCCESS)
    {
        goto Exit;
    }

Catatan

Header cfgmgr32.h mendefinisikan CM_Get_Device_Interface_List sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Microsoft Windows 2000 dan versi Windows yang lebih baru.
Target Platform	Universal
Header	cfgmgr32.h (termasuk Cfgmgr32.h)
Pustaka	Cfgmgr32.lib
DLL	CfgMgr32.dll

Lihat juga

CM_Get_Device_Interface_List_Size

Bagikan melalui