SwDeviceCreate 函式 (swdevice.h)
起始軟體裝置的列舉。
語法
HRESULT SwDeviceCreate(
[in] PCWSTR pszEnumeratorName,
[in] PCWSTR pszParentDeviceInstance,
[in] const SW_DEVICE_CREATE_INFO *pCreateInfo,
[in] ULONG cPropertyCount,
[in, optional] const DEVPROPERTY *pProperties,
[in] SW_DEVICE_CREATE_CALLBACK pCallback,
[in, optional] PVOID pContext,
[out] PHSWDEVICE phSwDevice
);
參數
[in] pszEnumeratorName
為軟體裝置命名列舉值的字串。 選擇代表列舉裝置之元件的名稱。
[in] pszParentDeviceInstance
字串，指定軟體裝置父系之裝置的裝置實例標識符。
這可以是 HTREE\ROOT\0，但建議將根裝置的子系保持在最低。 我們也建議軟體裝置的慣用父系是軟體裝置擴充功能的實際裝置。 在軟體裝置沒有這類自然父系的情況下，請建立裝置作為根目錄的子系，以收集元件將列舉的所有軟體裝置;然後，將實際的軟體裝置列舉為此裝置群組節點的子系。 這會將根裝置的子系保留為可管理的數位。
[in] pCreateInfo
SW_DEVICE_CREATE_INFO 結構的指標，描述 PnP 用來建立裝置的資訊。
[in] cPropertyCount
pProperties 陣列中的 DEVPROPERTY 結構數目。
[in, optional] pProperties
DEVPROPERTY 結構的選擇性數位。 這些屬性會在裝置建立之後設定，但在傳送裝置已建立的通知之前。 如需詳細資訊，請參閱。 此指標可以是 NULL。
[in] pCallback
操作系統在 PnP 列舉裝置之後呼叫 的SW_DEVICE_CREATE_CALLBACK 回呼函式。
[in, optional] pContext
操作系統傳遞給回呼函式的選擇性客戶端內容。 此指標可以是 NULL。
[out] phSwDevice
接收代表裝置 之 HSWDEVICE 句柄之變數的指標。 呼叫 SwDeviceClose 以在用戶端應用程式想要 PnP 移除裝置之後關閉此句柄。
DECLARE_HANDLE(HSWDEVICE);
typedef HSWDEVICE *PHSWDEVICE;
傳回值
如果已成功起始裝置列舉，則會傳回S_OK。 這並不表示已成功列舉裝置。 檢查SW_DEVICE_CREATE_CALLBACK回呼函式的 CreateResult 參數，以判斷裝置是否已成功列舉。
備註
SwDeviceCreate 會 傳回代表裝置的句柄。 關閉此句柄之後，PnP 會移除裝置。
呼叫程式必須具有系統管理員存取權，才能起始軟體裝置的列舉。
PnP 會將軟體裝置的裝置實例標識元形成為 「SWD<pszEnumeratorName><pszInstanceId>“，但此字串可能會變更，或 PnP 可能會裝飾名稱。 請一律從回呼函式取得裝置實例標識碼。
在 SwDeviceCreate 呼叫中設定的屬性與稍後藉由呼叫 SwDevicePropertySet 所設定的屬性之間有些微差異。 設定為 SwDeviceCreate 一部分的屬性會儲存在記憶體中;如果卸載裝置或 Null 驅動程式抹除屬性存放區，當 PnP 重新列舉裝置時，軟體裝置 API 功能會再次寫出這些屬性。 這對用戶端而言都是透明的。 列舉之後使用 SwDevicePropertySet 設定的屬性不會保存在記憶體中。 但是，如果您使用 SwDeviceCreate 來設定屬性，您可以使用 SwDevicePropertySet 來更新值，而且此更新會套用至記憶體內部值以及保存的存放區。
建議您盡可能將所有屬性指定為 SwDeviceCreate 呼叫的一部分，並針對每個 SwDeviceCreate 呼叫指定這些屬性。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows 8 |
| 最低支援的伺服器 | Windows Server 2012 |
| 目標平台 | Universal |
| 標頭 | swdevice.h |
| 程式庫 | Swdevice.lib;Windows 10 上的 OneCoreUAP.lib |
| Dll | Cfgmgr32.dll |