次の方法で共有


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 を呼び出すたびにこれらのプロパティを指定することをお勧めします。

メモSwDeviceCreate の呼び出しが戻る前に、オペレーティング システムが SW_DEVICE_CREATE_CALLBACK を呼び出す可能性があります。 このため、デバイスのソフトウェア デバイス ハンドルは、コールバック関数のパラメーターとして指定されます。
 
ソフトウェア デバイスは、その時点に存在しない親の子として作成できます。 PnP は、親が存在した後にソフトウェア デバイスを列挙します。

要件

要件
サポートされている最小のクライアント Windows 8
サポートされている最小のサーバー Windows Server 2012
対象プラットフォーム ユニバーサル
Header swdevice.h
Library Swdevice.lib;Windows 10の OneCoreUAP.lib
[DLL] Cfgmgr32.dll

こちらもご覧ください

SW_DEVICE_CREATE_CALLBACK