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
ソフトウェア デバイスの親であるデバイスのデバイス インスタンス ID を指定する文字列。
これは HTREE\ROOT\0 にすることができますが、ルート デバイスの子は最小限に抑えておくことをお勧めします。 また、ソフトウェア デバイスの優先親は、ソフトウェア デバイスが機能を拡張している実際のデバイスにすることもお勧めします。 ソフトウェア デバイスにこのような自然な親がない場合は、コンポーネントが列挙するすべてのソフトウェア デバイスを収集できるルートの子としてデバイスを作成します。次に、実際のソフトウェア デバイスをこのデバイス グループ 化ノードの子として列挙します。 これにより、ルート デバイスの子が管理可能な番号に保持されます。
[in] pCreateInfo
PnP がデバイスの作成に使用する情報を記述する SW_DEVICE_CREATE_INFO 構造体へのポインター。
[in] cPropertyCount
pProperties 配列内の DEVPROPERTY 構造体の数。
[in, optional] pProperties
DEVPROPERTY 構造体の省略可能な配列。 これらのプロパティは、デバイスが作成された後、デバイスが作成されたことを示す通知が送信される前に、デバイスで設定されます。 詳細については、「解説」を参照してください。 このポインターには NULL を指定できます。
[in] pCallback
PnP がデバイス を 列挙した後にオペレーティング システムが呼び出すSW_DEVICE_CREATE_CALLBACKコールバック関数。
[in, optional] pContext
オペレーティング システムがコールバック関数に渡すオプションのクライアント コンテキスト。 このポインターには NULL を指定できます。
[out] phSwDevice
デバイスを表す HSWDEVICE ハンドルを受け取る変数へのポインター。 クライアント アプリが PnP でデバイスを削除する必要が出た後、 SwDeviceClose を呼び出してこのハンドルを閉じます。
DECLARE_HANDLE(HSWDEVICE);
typedef HSWDEVICE *PHSWDEVICE;
戻り値
デバイス列挙が正常に開始された場合、S_OKが返されます。 これは、デバイスが正常に列挙されたことを意味するものではありません。 デバイスが正常に列挙されたかどうかを判断するには、SW_DEVICE_CREATE_CALLBACK コールバック関数の CreateResult パラメーターを確認します。
注釈
SwDeviceCreate は、デバイスを表すハンドルを返します。 このハンドルを閉じると、PnP によってデバイスが削除されます。
ソフトウェア デバイスの列挙を開始するには、呼び出し元プロセスに管理者アクセス権が必要です。
PnP は、ソフトウェア デバイスのデバイス インスタンス ID を "SWD<pszEnumeratorName><pszInstanceId>"。ただし、この文字列が変更されたり、PnP によって名前が装飾されたりする可能性があります。 常に、コールバック関数からデバイス インスタンス ID を取得します。
SwDeviceCreate 呼び出しの一部として設定されるプロパティと、後で SwDevicePropertySet を呼び出して設定されるプロパティには微妙な違いがあります。 SwDeviceCreate の一部として設定されたプロパティはメモリに格納されます。デバイスがアンインストールされた場合、または null ドライバーによってプロパティ ストアが消去された場合、PnP がデバイスを再列挙すると、これらのプロパティはソフトウェア デバイス API 機能によって再び書き出されます。 これはすべてクライアントに対して透過的です。 列挙後 に SwDevicePropertySet を使用して設定されたプロパティは、メモリに保持されません。 ただし、 SwDeviceCreate を使用してプロパティを設定した場合は、 SwDevicePropertySet を使用して値を更新できます。この更新プログラムは、メモリ内の値と永続化されたストアに適用されます。
可能であれば 、SwDeviceCreate の呼び出しの一部としてすべてのプロパティを指定し、 SwDeviceCreate を呼び出すたびにこれらのプロパティを指定することをお勧めします。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8 |
| サポートされている最小のサーバー | Windows Server 2012 |
| 対象プラットフォーム | ユニバーサル |
| Header | swdevice.h |
| Library | Swdevice.lib;Windows 10の OneCoreUAP.lib |
| [DLL] | Cfgmgr32.dll |