CM_Get_Device_Interface_ListA函式 (cfgmgr32.h)

發行項
02/23/2024

CM_Get_Device_Interface_List函式會擷取屬於指定裝置介面類別的裝置介面實例清單。

語法

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

參數

[in] InterfaceClassGuid

提供識別裝置介面類別的 GUID。

[in, optional] pDeviceID

呼叫端提供的指標，代表裝置實例標識碼的NULL終止字元串。如果指定，函式會擷取裝置針對指定類別所支援的裝置介面。如果此值為 NULL，或指向零長度字串，則函式會擷取屬於指定類別的所有介面。

[out] Buffer

呼叫端提供的緩衝區指標會接收多個 NULL 終止的 Unicode 字串，每個字串都代表介面實例的符號連結名稱。

[in] BufferLen

呼叫端提供的值，指定 Buffer 所指向之緩衝區的長度，以字元為單位。呼叫 CM_Get_Device_Interface_List_Size 以判斷所需的緩衝區大小。

[in] ulFlags

包含下列其中一個呼叫端提供的旗標：

CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES

函式提供清單，其中包含與符合指定 GUID 和裝置實例識別碼的所有裝置相關聯的裝置介面，如果有的話。

CM_GET_DEVICE_INTERFACE_LIST_PRESENT

函式提供清單，其中包含與目前使用中之裝置相關聯的裝置介面，以及符合指定 GUID 和裝置實例標識碼的清單。如果有的話。

傳回值

如果作業成功，函式會傳回CR_SUCCESS。否則，它會傳回其中一個錯誤碼，其中CR_前置詞如 Cfgmgr32.h 中所定義。

下表包含此函式可能會傳回的一些較常見的錯誤碼。

傳回碼	Description
CR_BUFFER_SMALL	緩衝區緩衝區太小，無法保存所要求的裝置介面清單。

備註

在呼叫 CM_Get_Device_Interface_List_Size 以取得清單的大小，以及呼叫 CM_Get_Device_Interface_List 以取得清單，可以將新的裝置介面新增至系統，使傳回的大小不再有效。如果CM_Get_Device_Interface_List傳回CR_BUFFER_SMALL，則呼叫端應該對該條件保持強固，然後重試取得大小和清單。

範例

此代碼段說明如何重試取得大小和清單，如一節中所述。

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

注意

cfgmgr32.h 標頭會將CM_Get_Device_Interface_List定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。
目標平台	Universal
標頭	cfgmgr32.h (包含 Cfgmgr32.h)
程式庫	Cfgmgr32.lib
Dll	CfgMgr32.dll

另請參閱

CM_Get_Device_Interface_List_Size

共用方式為