SetupDiCreateDevRegKeyA 関数 (setupapi.h)

[アーティクル]
08/26/2023

SetupDiCreateDevRegKey 関数は、デバイス固有の構成情報のレジストリキーを作成し、キーへのハンドルを返します。

構文

WINSETUPAPI HKEY SetupDiCreateDevRegKeyA(
  [in]           HDEVINFO         DeviceInfoSet,
  [in]           PSP_DEVINFO_DATA DeviceInfoData,
  [in]           DWORD            Scope,
  [in]           DWORD            HwProfile,
  [in]           DWORD            KeyType,
  [in, optional] HINF             InfHandle,
  [in, optional] PCSTR            InfSectionName
);

パラメーター

[in] DeviceInfoSet

レジストリキーを作成するデバイスを表すデバイス情報要素を含むデバイス情報セットへのハンドル。

[in] DeviceInfoData

DeviceInfoSet のデバイス情報要素を指定するSP_DEVINFO_DATA構造体へのポインター。

[in] Scope

作成するレジストリキーのスコープ。スコープによって、情報が格納される場所が決まります。作成されるキーは、グローバルまたはハードウェアプロファイル固有です。値は、次のいずれかです。

DICS_FLAG_GLOBAL

グローバル構成情報を格納するキーを作成します。この情報は、特定のハードウェアプロファイルに固有の情報ではありません。 NT ベースのオペレーティングシステムでは、 HKEY_LOCAL_MACHINEにルート化されたキーが作成されます。開かれる正確なキーは、 KeyType パラメーターの値によって異なります。

DICS_FLAG_CONFIGSPECIFIC

ハードウェアプロファイル固有の構成情報を格納するキーを作成します。このキーは、HKEY_LOCAL_MACHINEではなく、ハードウェアプロファイル 固有のブランチのいずれかにルート化されます。

[in] HwProfile

HwProfileFlags が SPDICS_FLAG_CONFIGSPECIFIC に設定されている場合にキーを作成するハードウェアプロファイル。 HwProfile が 0 の場合は、現在のハードウェアプロファイルのキーが作成されます。 HwProfileFlags がSPDICS_FLAG_GLOBAL場合、HwProfile は無視されます。

[in] KeyType

作成するレジストリストレージキーの種類。値は、次のいずれかです。

DIREG_DEV

デバイスのハードウェアキーを作成します。

DIREG_DRV

デバイスのソフトウェアキーを作成します。

[in, optional] InfHandle

新しく作成されたキーに対して実行される INF DDInstall セクションを含む、開いている INF ファイルへのハンドル。このパラメーターは省略可能であり、 NULL にすることができます。このパラメーターを指定する場合は、 InfSectionName も指定する必要があります。

[in, optional] InfSectionName

InfHandle で指定された INF ファイル内の INF DDInstall セクションの名前。このセクションは、新しく作成されたキーに対して実行されます。このパラメーターは省略可能であり、 NULL にすることができます。このパラメーターを指定する場合は、 InfHandle も指定する必要があります。

戻り値

SetupDiCreateDevRegKey が成功した場合、この関数は、デバイス固有の構成データを格納および取得できる、指定されたレジストリキーへのハンドルを返します。 SetupDiCreateDevRegKey が失敗した場合、関数はINVALID_HANDLE_VALUEを返します。拡張されたエラー情報を取得するには、GetLastError を呼び出します。

解説

SetupDiCreateDevRegKey の呼び出し元は、Administrators グループのメンバーである必要があります。

RegCloseKey を呼び出して、SetupDiCreateDevRegKey から返されたハンドルを閉じます。

指定したキーが既に存在する場合、 SetupDiCreateDevRegKey はそのキーへのハンドルを返します。それ以外の場合、 SetupDiCreateDevRegKey は 指定したキーを作成し、新しいキーへのハンドルを返します。 Windows Server 2003 以降のバージョンの Windows の場合、キーハンドルにはKEY_READとKEY_WRITEアクセスのみが含まれます。以前の Windows バージョンの場合、このハンドルにはKEY_ALL_ACCESSアクセス権があります。

SetupDiCreateDevRegKey が呼び出される前に、指定したデバイスインスタンスを登録する必要があります。ただし、オペレーティングシステムによって PnP デバイスインスタンスが自動的に登録されることに注意してください。 PnP 以外のデバイスインスタンスを登録する方法については、「 SetupDiRegisterDeviceInfo」を参照してください。

レイアウトファイル (INF バージョンセクションの LayoutFile エントリで指定) を使用するインストールでは、SetupDiCreateDevRegKey を呼び出す前に、SetupOpenAppendInfFile (Microsoft Windows SDK ドキュメントで説明) を呼び出してレイアウトファイルを開く必要があります。

指定されたデバイス情報セットにリモートシステムのデバイス情報要素が含まれており、 InfHandle と InfSectionName も指定されている場合、作成要求は失敗し、 GetLastError の後続の呼び出しはERROR_REMOTE_REQUEST_UNSUPPORTEDを返します。

注意

setupapi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SetupDiCreateDevRegKey を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイルエラーまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

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