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 呼叫指定這些屬性。

規格需求

另請參閱

SW_DEVICE_CREATE_CALLBACK