CM_Get_Device_Interface_ListW函式 (cfgmgr32.h)
CM_Get_Device_Interface_List函式會擷取屬於指定裝置介面類別的裝置介面實例清單。
語法
CMAPI CONFIGRET CM_Get_Device_Interface_ListW(
[in] LPGUID InterfaceClassGuid,
[in, optional] DEVINSTID_W pDeviceID,
[out] PZZWSTR 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 |
---|---|
|
緩衝區緩衝區太小,無法保存所要求的裝置介面清單。 |
備註
在呼叫 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 |