WdfRegistryOpenKey 関数 (wdfregistry.h)

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

[KMDF と UMDF に適用]

WdfRegistryOpenKey メソッドは、指定したレジストリキーを開き、レジストリキーを表すフレームワークレジストリキーオブジェクトを作成します。

構文

NTSTATUS WdfRegistryOpenKey(
  [in, optional] WDFKEY                 ParentKey,
  [in]           PCUNICODE_STRING       KeyName,
  [in]           ACCESS_MASK            DesiredAccess,
  [in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]          WDFKEY                 *Key
);

パラメーター

[in, optional] ParentKey

フレームワークレジストリキーオブジェクトへのハンドル。このオブジェクトは、ドライバーが開いた親レジストリキーを表します。このパラメーターは省略可能であり、 NULL にすることができます。パラメーターが NULL でない場合、 KeyName が指定するキーは、レジストリ内のこの親キーの下に存在する必要があります。この親キーの詳細については、「解説」セクションを参照してください。

[in] KeyName

開くキーの名前を含む UNICODE_STRING 構造体へのポインター。キー名にはパス情報を含めることができます。 ParentKey が NULL の場合、KeyName はレジストリキーへの完全なパスを指定する必要があります。例については、「解説」セクションを参照してください。

[in] DesiredAccess

ドライバーが指定したレジストリキーに対して要求するアクセス権を指定する、 ACCESS_MASK型指定された値。ドライバーがレジストリキーに通常使用するアクセス権の一覧については、「 Registry-Key オブジェクトへのハンドルを開く」を参照してください。ドライバーは、必要なアクセスの種類のみを要求する必要があります。たとえば、ドライバーは、レジストリキーのみを読み取るかどうかをKEY_ALL_ACCESSを要求しないでください。

[in, optional] KeyAttributes

新しいレジストリキーオブジェクトのドライバー指定の属性を含む WDF_OBJECT_ATTRIBUTES 構造体へのポインター。このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。

[out] Key

新しいレジストリキーオブジェクトへのハンドルを受け取る場所へのポインター。

戻り値

操作が成功した場合、WdfRegistryOpenKey はSTATUS_SUCCESSを返します。それ以外の場合、メソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_DEVICE_REQUEST	IRQL = PASSIVE_LEVELで WdfRegistryOpenKey が呼び出されませんでした。
STATUS_INVALID_PARAMETER	無効なパラメーターが指定されました。
STATUS_INSUFFICIENT_RESOURCES	レジストリキーオブジェクトを割り当てませんでした。
STATUS_ACCESS_DENIED	システムは、指定されたアクセス権を拒否しました。
STATUS_OBJECT_NAME_NOT_FOUND	指定されたレジストリキーが存在しません。

WdfRegistryOpenKey メソッドが返す可能性があるその他の戻り値の一覧については、「Framework オブジェクト作成エラー」を参照してください。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

注釈

親キーを表すレジストリキーオブジェクトへのハンドルを取得するために、ドライバーは WdfDriverOpenParametersRegistryKey、 WdfDeviceOpenRegistryKey、または WdfFdoInitOpenRegistryKey を呼び出すことができます。

KeyName パラメーターで指定される文字列形式は、呼び出し元が KMDF ドライバーか UMDF ドライバーかによって異なります。たとえば、次のパスを開くには、

HKLM\System\CurrentControlSet\Control

ドライバーでは、次の条件付きロジックを使用できます。

#ifdef _KERNEL_MODE
#define CONTROL_KEY_FULL_PATH L"\\Registry\\Machine\\System\\CurrentControlSet\\Control "
#else
#define CONTROL_KEY_FULL_PATH L"System\\CurrentControlSet\\Control\\" 
#endif

ドライバーが WdfRegistryOpenKey で開くレジストリキーの使用が完了したら、ドライバーは WdfRegistryClose を呼び出す必要があります。

レジストリキーオブジェクトの詳細については、「 Framework-Based ドライバーでのレジストリの使用」を参照してください。

例

次のコード例では、ドライバーのソフトウェアキーを開き、ドライバーのソフトウェアキーの下にある MySubKey レジストリキーを開きます。

WDFKEY  hKey, subkey;
NTSTATUS  status;
UNICODE_STRING myKeyStr;

status = WdfDeviceOpenRegistryKey(
                                  device,
                                  PLUGPLAY_REGKEY_DRIVER,
                                  KEY_READ,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &hKey
                                  );
if (NT_SUCCESS(status)){
    RtlInitUnicodeString(
                         &myKeyStr,
                         L"MySubKey"
                         );
    status = WdfRegistryOpenKey(
                                hKey,
                                &myKeyStr,
                                KEY_READ,
                                WDF_NO_OBJECT_ATTRIBUTES,
                                &subkey
                                );
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfregistry.h (Wdf.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)