WdfRegistryCreateKey 関数 (wdfregistry.h)
[KMDF と UMDF に適用]
WdfRegistryCreateKey メソッドは、指定されたレジストリ キーを作成して開くか、キーが既に存在する場合はキーを開き、レジストリ キーを表すフレームワーク レジストリ キー オブジェクトを作成します。
構文
NTSTATUS WdfRegistryCreateKey(
[in, optional] WDFKEY ParentKey,
[in] PCUNICODE_STRING KeyName,
[in] ACCESS_MASK DesiredAccess,
[in] ULONG CreateOptions,
[out, optional] PULONG CreateDisposition,
[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] CreateOptions
1 つ以上のフラグ。 これらのフラグの詳細については、「 CreateOptions パラメーター」または 「ZwCreateKey」を参照してください。
[out, optional] CreateDisposition
新しいキーが作成された場合にREG_CREATED_NEW_KEYを受け取る場所へのポインター。既存のキーが開かれた場合はREG_OPENED_EXISTING_KEY。 これらの値は Wdm.h で定義されています。 このポインターは省略可能であり、 NULL にすることができます。
[in, optional] KeyAttributes
新しいレジストリ キー オブジェクトのドライバー指定の属性を含む WDF_OBJECT_ATTRIBUTES 構造体へのポインター。 このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。
[out] Key
新しいレジストリ キー オブジェクトへのハンドルを受け取る場所へのポインター。
戻り値
操作が成功した場合、WdfRegistryCreateKey はSTATUS_SUCCESSを返します。 それ以外の場合、メソッドは次のいずれかの値を返す可能性があります。
| リターン コード | 説明 |
|---|---|
|
IRQL = PASSIVE_LEVELで WdfRegistryCreateKey が呼び出されませんでした。 |
|
無効なパラメーターが指定されました。 |
|
レジストリ キー オブジェクトを割り当てませんでした。 |
|
システムは、指定されたアクセス権を拒否しました。 |
|
指定されたレジストリ キーが存在しません。 |
WdfRegistryCreateKey メソッドが返す可能性があるその他の戻り値の一覧については、「Framework オブジェクト作成エラー」を参照してください。
このメソッドは、他の NTSTATUS 値を返す場合もあります。
注釈
親キーを表すレジストリ キー オブジェクトへのハンドルを取得するために、ドライバーは WdfDriverOpenParametersRegistryKey、 WdfDeviceOpenRegistryKey、または WdfFdoInitOpenRegistryKey を呼び出すことができます。
既定では、新しいレジストリ キー オブジェクトの親は 、WdfDriverCreate メソッドによって作成されるフレームワーク ドライバー オブジェクトです。 WDF_OBJECT_ATTRIBUTES構造体の ParentObject メンバーを使用して、別の親を指定できます。 フレームワークは、親オブジェクトを削除するときにレジストリ キー オブジェクトを削除します。 ドライバーが既定の親を変更しない場合、ドライバーは、オブジェクトの使用が完了したときにレジストリ キー オブジェクトを削除する必要があります。それ以外の場合、レジストリ キー オブジェクトは、I/O マネージャーがドライバーをアンロードするまで保持されます。
ドライバーが既定の親を変更しない場合、ドライバーは オブジェクトの使用が完了したときに WdfRegistryClose を呼び出す必要があります。それ以外の場合、レジストリ キー オブジェクトは、I/O マネージャーがドライバーをアンロードするまで保持されます。 または、ドライバーは WdfObjectDelete を呼び出してレジストリ キー オブジェクトを削除することもできます。
レジストリ キー オブジェクトの詳細については、「 Framework-Based ドライバーでのレジストリの使用」を参照してください。
例
次のコード例では、ドライバーのソフトウェア キーを開き、ドライバーのソフトウェア キーの下にある myKeyStr レジストリ キーを作成して開きます。
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"myKeyStr"
);
status = WdfRegistryCreateKey(
hKey,
&myKeyStr,
KEY_READ,
REG_OPTION_NON_VOLATILE,
NULL,
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) |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示