ZwCreateKey 関数 (wdm.h)

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

ZwCreateKey ルーチンは、新しいレジストリキーを作成するか、既存のレジストリキーを開きます。

構文

NTSYSAPI NTSTATUS ZwCreateKey(
  [out]           PHANDLE            KeyHandle,
  [in]            ACCESS_MASK        DesiredAccess,
  [in]            POBJECT_ATTRIBUTES ObjectAttributes,
                  ULONG              TitleIndex,
  [in, optional]  PUNICODE_STRING    Class,
  [in]            ULONG              CreateOptions,
  [out, optional] PULONG             Disposition
);

パラメーター

[out] KeyHandle

キーへのハンドルを受け取る HANDLE 変数へのポインター。

[in] DesiredAccess

オブジェクトへの要求されたアクセスを決定する ACCESS_MASK 値を指定します。呼び出し元は、すべての種類のオブジェクトに対して定義されているアクセス権 ( ACCESS_MASKを参照) に加えて、オブジェクトディレクトリに固有の次のアクセス権を 1 つ以上指定できます。

DesiredAccess フラグ	呼び出し元がこれを行うことを許可します
KEY_QUERY_VALUE	キー値を読み取ります。
KEY_SET_VALUE	キー値を書き込みます。
KEY_CREATE_SUB_KEY	キーのサブキーを作成します。
KEY_ENUMERATE_SUB_KEYS	キーのサブキーを読み取ります。
KEY_CREATE_LINK	キーへのシンボリックリンクを作成します。このフラグは、デバイスドライバーと中間ドライバーでは使用されません。
KEY_NOTIFY	キーの名前、値、または属性が変更されたときに通知を受け取るように求めます。詳細については、「 ZwNotifyChangeKey」を参照してください。

呼び出し元は、いくつかのACCESS_MASKフラグを組み合わせた次の定数のいずれかを指定することもできます。

常時	これらのACCESS_MASKフラグで構成されます
KEY_READ	STANDARD_RIGHTS_READ、KEY_QUERY_VALUE、KEY_ENUMERATE_SUB_KEYS、KEY_NOTIFY
KEY_WRITE	STANDARD_RIGHTS_WRITE、KEY_SET_VALUE、KEY_CREATE_SUB_KEY
KEY_EXECUTE	KEY_READと同じです。
KEY_ALL_ACCESS	STANDARD_RIGHTS_ALL、KEY_QUERY_VALUE、KEY_SET_VALUE、KEY_CREATE_SUB_KEY、KEY_ENUMERATE_SUB_KEYS、KEY_NOTIFY、KEY_CREATE_LINK

[in] ObjectAttributes

オブジェクト名とその他の属性を指定する OBJECT_ATTRIBUTES 構造体へのポインター。 InitializeObjectAttributes を使用して、この構造体を初期化します。呼び出し元がシステムスレッドコンテキストで実行されていない場合は、 InitializeObjectAttributes を呼び出すときにOBJ_KERNEL_HANDLE属性を設定する必要があります。

TitleIndex

デバイスドライバーと中間ドライバーでは、このパラメーターを 0 に設定します。

[in, optional] Class

キーのオブジェクトクラスを含む Unicode 文字列へのポインター。この情報は、構成マネージャーによって使用されます。

[in] CreateOptions

キーを作成または開くときに適用するオプションを指定します。次のフラグの互換性のある組み合わせとして指定します。

CreateOptions フラグ	説明
REG_OPTION_VOLATILE	システムの再起動時にキーは保持されません。
REG_OPTION_NON_VOLATILE	キーは、システムの再起動時に保持されます。
REG_OPTION_CREATE_LINK	新しく作成されたキーはシンボリックリンクです。このフラグは、デバイスドライバーと中間ドライバーでは使用されません。
REG_OPTION_BACKUP_RESTORE	キーは、バックアップ操作と復元操作を許可する特別な特権で作成または開く必要があります。このフラグは、デバイスドライバーと中間ドライバーでは使用されません。

[out, optional] Disposition

新しいキーが作成されたか、既存のキーが開かれたかを示す値を受け取る変数へのポインター。

廃棄値	説明
REG_CREATED_NEW_KEY	新しいキーが作成されました。
REG_OPENED_EXISTING_KEY	既存のキーが開かれました。

戻り値

ZwCreateKey は 、成功した場合はSTATUS_SUCCESS、失敗した場合は適切な NTSTATUS エラーコードを返します。

注釈

ZwCreateKey は、呼び出し元がレジストリキーを操作するために使用できるハンドルを提供します。詳細については、「ドライバーでのレジストリの使用」を参照してください。

KeyHandle が指すハンドルが使用されなくなったら、ドライバーは ZwClose を呼び出して閉じる必要があります。

ZwCreateKey を使用して作成または開くファイルの名前を指定するには、次の 2 つの方法があります。

完全修飾パス名として、入力 ObjectAttributes の ObjectName メンバーで指定されます。レジストリキーのパス名は 、\Registry で始まります。
入力 ObjectAttributes の RootDirectory メンバーのハンドルによって表される、別のレジストリキーに対する相対パス名。

ObjectAttributes で指定されたキーが存在しない場合、ルーチンはキーの作成を試みます。この試行を成功させるには、新しいキーが RootDirectory によって参照されるキーの直接サブキーである必要があり、 RootDirectory が参照するキーは、KEY_CREATE_SUB_KEYアクセスのために開かれている必要があります。

指定したキーが既に存在する場合は、そのキーが開き、その値は何も影響を受けません。

キーの作成時に ObjectAttributes によって指定されたセキュリティ属性によって、ZwCreateKey と ZwOpenKey の後続の呼び出しで、指定した DesiredAccess が許可されるかどうかが決まります。

呼び出し元がシステムスレッドコンテキストで実行されていない場合は、作成するハンドルがプライベートハンドルであることを確認する必要があります。それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってハンドルにアクセスできます。詳細については、「オブジェクトハンドル」を参照してください。

レジストリキーの操作の詳細については、「ドライバーでのレジストリの使用」を参照してください。

この関数の呼び出しがユーザーモードで行われる場合は、"ZwCreateKey" ではなく "NtCreateKey" という名前を使用する必要があります。

Windows カーネルの NtCreateKey ルーチンは、カーネルモードドライバーから直接アクセスできません。

カーネルモードドライバーからの呼び出しの場合、Windows ネイティブシステムサービスルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。 ルーチンの NtXxx バージョンと ZwXxx バージョンの間の関係の詳細については、「ネイティブシステムサービスルーチンの Nt バージョンと Zw バージョンの使用」を参照してください。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport)、 IrqlZwPassive(wdm)、 PowerIrpDDis(wdm)、 ZwRegistryCreate(storport)、ZwRegistryCreate(storport)、 ZwRegistryCreate(wdm)、 ZwRegistryOpen(wdm)