SetupDiRegisterDeviceInfo 関数 (setupapi.h)

  • [アーティクル]

SetupDiRegisterDeviceInfo 関数は、DIF_REGISTERDEVICE要求の既定のハンドラーです。

構文

WINSETUPAPI BOOL SetupDiRegisterDeviceInfo(
  [in]            HDEVINFO           DeviceInfoSet,
  [in, out]       PSP_DEVINFO_DATA   DeviceInfoData,
  [in]            DWORD              Flags,
  [in, optional]  PSP_DETSIG_CMPPROC CompareProc,
  [in, optional]  PVOID              CompareContext,
  [out, optional] PSP_DEVINFO_DATA   DupDeviceInfoData
);

パラメーター

[in] DeviceInfoSet

登録するデバイスを表す デバイス情報 要素を含むデバイス情報セットへのハンドル。 デバイス情報セットには、リモート要素を含めてはなりません。

[in, out] DeviceInfoData

DeviceInfoSet のデバイス情報要素を指定するSP_DEVINFO_DATA構造体へのポインター。 DeviceInfoData のため、これは IN-OUT パラメーターです。DevInst は、戻り時に新しいハンドル値で更新される場合があります。

[in] Flags

デバイスの登録方法を制御するフラグ値。0 または次の値を指定できます。

SPRDI_FIND_DUPS

DeviceInfoData で表されるデバイスに対応する既存のデバイス インスタンスを検索します。 このフラグが指定されていない場合、デバイス インスタンスが既に存在するかどうかに関係なく、デバイス インスタンスが登録されます。

呼び出し元が CompareProc を提供する場合は、呼び出し元もこのフラグを設定する必要があります。

[in, optional] CompareProc

重複検出で使用する比較コールバック関数へのポインター。 このパラメーターは省略可能であり、 NULL にすることができます。 このパラメーターを指定すると、登録されているデバイス インスタンスと同じクラスの各デバイス インスタンスに対してコールバック関数が呼び出されます。 コールバック関数のプロトタイプは次のとおりです。

typedef  DWORD (CALLBACK* PSP_DETSIG_CMPPROC) (
    IN HDEVINFO  DeviceInfoSet,
    IN PSP_DEVINFO_DATA  NewDeviceData,
    IN PSP_DEVINFO_DATA  ExistingDeviceData,
    IN PVOID  CompareContextOPTIONAL
    );

compare 関数は、2 つのデバイスが重複している場合は、ERROR_DUPLICATE_FOUNDを返す必要があります。 それ以外の場合は、NO_ERRORを返す必要があります。 他のエラーが発生した場合、コールバック関数は、エラーを示す適切なERROR_* コードを返す必要があります。

CompareProc が指定されておらず、重複検出が要求された場合は、既定の比較動作が使用されます。 既定では、新しいデバイスの検出署名と、 クラス内の他のすべてのデバイスの署名の検出を比較します。 検出署名は、デバイスのブート ログ構成のクラス固有のリソース記述子に含まれています。

[in, optional] CompareContext

コールバック関数に渡される呼び出し元が指定したコンテキスト バッファーへのポインター。 CompareProc が指定されていない場合、このパラメーターは無視されます。

[out, optional] DupDeviceInfoData

重複するデバイス インスタンス (存在する場合) に関する情報を受け取る SP_DEVINFO_DATA 構造体へのポインター。このデバイスを登録しようとした結果として検出されます。 このパラメーターは省略可能であり、 NULL にすることができます。 このパラメーターを指定した場合、呼び出し元は DupDeviceInfoData を設定する必要があります。cbSize から sizeof(SP_DEVINFO_DATA)。 これは、関数が FALSE を返し、 GetLastError が ERROR_DUPLICATE_FOUNDを返す場合に入力されます。 このデバイス情報要素は、指定した DeviceInfoSet のメンバーとして追加されます (まだメンバーでない場合)。 DupDeviceInfoData が指定されていない場合、重複はデバイス情報セットに追加されません。

DIF_REGISTERDEVICE要求を処理するときにこの関数を呼び出す場合、DupDeviceInfoData パラメーターは NULL である必要があります。

戻り値

成功した場合、この関数は TRUE を 返します。 それ以外の場合は FALSE を 返し、ログに記録されたエラーは GetLastError の呼び出しで取得できます。

注釈

SetupDiRegisterDeviceInfo は、主に PnP 以外のデバイスをローカル コンピューターのプラグ アンド プレイ (PnP) マネージャーに登録するように設計されています。 デバイス情報セットがリモート コンピューター用の場合、 SetupDiRegisterDeviceInfo は失敗しませんが、デバイス情報セットは、その後、リモート コンピューターでの操作をサポートしていない DIF_Xxx インストール要求または SetupDiXxx 関数で使用できないため、使用が制限されます。 たとえば、 SetupDiCreateDevRegKey を呼び出して、リモート コンピューターで新しく登録されたデバイスの INF セクションを実行すると失敗します。

メモSetupDiRegisterDeviceInfo が既定のデバイス登録操作を完了した後、クラス インストーラーがデバイス登録操作を実行する必要がある状況でのみ、クラス インストーラーのみが SetupDiRegisterDeviceInfo を呼び出す必要があります。 このような状況では、インストーラーがDIF_REGISTERDEVICE要求を処理するときに、クラス インストーラーが SetupDiRegisterDeviceInfo を直接呼び出す必要があります。 既定のハンドラーの呼び出しの詳細については、「 既定の DIF コード ハンドラーの呼び出し」を参照してください。
 
デバイス情報要素を登録した後、呼び出し元は、このデバイスに関連付けられている DevInst ハンドルの格納されているコピーを更新する必要があります。 登録中にハンドル値が変更された可能性があるため、これは必要です。 構造体の DevInst フィールドがハンドルの現在の値を反映するように更新されるため、呼び出し元はSP_DEVINFO_DATA構造体を再度取得する必要はありません。

PnP デバイス インスタンスに対してこの関数を直接呼び出さないでください。 PnP デバイス インスタンスは、オペレーティング システムによって自動的に登録されます。 ただし、PnP 以外のデバイス インスタンスは、次のいずれかの方法で登録する必要があります。

  1. インストール アプリケーションが DIF_DETECT 要求を使用してデバイスを正常に検出する場合は、DIF_REGISTERDEVICE要求を使用してデバイス インスタンスを登録する必要もあります。 要求は既定の方法で処理する必要があります。 (既定では、 SetupDiCallClassInstaller は 最初にクラス インストーラーとクラス共同インストーラーを呼び出して重複検出を行い、デバイス インスタンスを登録します。これらのインストーラーがデバイス インスタンスを登録しない場合、 SetupDiCallClassInstaller はSetupDiRegisterDeviceInfo を 呼び出して重複検出を行い、デバイス インスタンスを登録します)。
  2. インストール アプリケーションでデバイス インスタンス ( SetupDiCreateDeviceInfo を呼び出すなど) を作成し、重複検出を行わない場合は、インストール アプリケーションでDIF_REGISTERDEVICE要求を使用してデバイス インスタンスを登録する必要があります。 要求は、前に説明したように既定の方法で処理する必要があります。
  3. インストール アプリケーションが新しいデバイスを作成し、重複検出を行う場合、インストール アプリケーションはDIF_REGISTERDEVICE要求を使用する必要がありますが、 SetupDiCallClassInstaller が SetupDiRegisterDeviceInfo を呼び出さないようにする必要があります。 SetupDiCallClassInstaller がSetupDiRegisterDeviceInfo を呼び出さないようにするには、デバイス インスタンスのSP_DEVINSTALL_PARAMS構造体の Flags メンバーにDI_NODI_DEFAULTACTION フラグを設定します。

    SetupDiCallClassInstaller がDIF_REGISTERDEVICE要求に対して TRUE を返した場合、クラス インストーラーまたはクラス共同インストーラーによってデバイス インスタンスが登録されます。 この場合、インストール アプリケーションは引き続きデバイスをインストールできます。

    SetupDiCallClassInstaller がDIF_REGISTERDEVICE要求に対して FALSE を返した場合、クラス インストーラーまたはクラス共同インストーラーはデバイス インスタンスを登録しませんでした。 この場合、 GetLastError が 要求に対して返す最後のエラーに応じて、インストール アプリケーションで次のいずれかを実行する必要があります。

    • 最後のエラーがERROR_DI_DO_DEFAULT場合、インストール アプリケーションは SetupDiRegisterDeviceInfo を直接呼び出し、 CompareProc を 指定して重複検出を実行できます。 この呼び出しが成功し、重複が見つからない場合は、デバイスのインストールを続行できます。 重複が見つかった場合、 SetupDiRegisterDeviceInfo は FALSE を返し、インストール アプリケーションはデバイスのインストールを終了する必要があります。
    • 最後のエラーがERROR_DI_DO_DEFAULTされていない場合、インストール アプリケーションはデバイスのインストールを終了する必要があります。
    SetupDiRegisterDeviceInfo の呼び出し元は、Administrators グループのメンバーである必要があります。

要件

要件 値
サポートされている最小のクライアント Microsoft Windows 2000 以降のバージョンの Windows で使用できます。
対象プラットフォーム デスクトップ
Header setupapi.h (Setupapi.h を含む)
Library Setupapi.lib
[DLL] Setupapi.dll

こちらもご覧ください

DIF_REGISTERDEVICE

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS