ZwOpenKeyTransactedEx 関数 (wdm.h)

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

ZwOpenKeyTransactedEx ルーチンは、既存のレジストリキーを開き、キーをトランザクションに関連付けます。

構文

NTSYSAPI NTSTATUS ZwOpenKeyTransactedEx(
  [out] PHANDLE            KeyHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in]  ULONG              OpenOptions,
  [in]  HANDLE             TransactionHandle
);

パラメーター

[out] KeyHandle

ルーチンがキーにハンドルを書き込む HANDLE 変数へのポインター。

[in] DesiredAccess

呼び出し元が要求するキーへのアクセスの種類を指定します。このパラメーターは、ACCESS_MASK 値です。詳細については、ZwCreateKey ルーチンの DesiredAccess パラメーターの説明を参照してください。

[in] ObjectAttributes

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

[in] OpenOptions

キーを開くときに適用するオプションを指定します。このパラメーターを 0 に設定するか、次の 1 つ以上の REG_OPTION_XXX フラグビットのビットごとの OR に設定します。

OpenOptions フラグ	説明
REG_OPTION_OPEN_LINK	キーはシンボリックリンクです。このフラグは、デバイスドライバーと中間ドライバーでは使用されません。
REG_OPTION_BACKUP_RESTORE	キーは、バックアップ操作と復元操作を許可する特別な特権で開く必要があります。このフラグは、デバイスドライバーと中間ドライバーでは使用されません。

[in] TransactionHandle

トランザクションオブジェクトへのハンドル。このハンドルを取得するには、 ZwCreateTransaction ルーチンを呼び出します。または、トランザクションオブジェクトへのポインターがある場合は、 ObOpenObjectByPointer ルーチンへのポインターを指定して、対応するトランザクションハンドルを取得できます。

戻り値

呼び出しが正常にキーを開いた場合、ZwOpenKeyTransactedEx はSTATUS_SUCCESSを返します。考えられるエラーの戻り値は次のとおりです。

リターンコード	説明
STATUS_INVALID_PARAMETER	ObjectAttributes パラメーターが NULL であるか、無効な情報を指しています。
STATUS_INVALID_PARAMETER_4	OpenOptions パラメーターの値は、無効なオプションを指定します。
STATUS_OBJECT_PATH_SYNTAX_BAD	オブジェクト属性のレジストリパスが無効です。
STATUS_OBJECT_NAME_NOT_FOUND	オブジェクト属性のレジストリパスが見つかりませんでした。
STATUS_ACCESS_DENIED	呼び出し元には、名前付きレジストリキーのハンドルを開くために必要なアクセス権がありませんでした。
STATUS_INSUFFICIENT_RESOURCES	メモリ割り当て操作が失敗しました。

注釈

このルーチンは、呼び出し元がレジストリキーにアクセスできるハンドルを提供します。さらに、このルーチンは、キーをアクティブなトランザクションに関連付けます。

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

指定したキーがレジストリに存在しない場合、 ZwOpenKeyTransactedEx はエラー状態値を返し、キーハンドルを指定しません。 ZwCreateKeyTransacted ルーチンとは異なり、ZwOpenKeyTransactedEx ルーチンは、キーが存在しない場合、指定したキーを作成しません。 ZwCreateKeyTransacted と ZwOpenKeyTransactedEx の両方が、レジストリキーをトランザクションに関連付けます。

ZwOpenKeyEx ルーチンは ZwOpenKeyTransactedEx に似ていますが、キーをトランザクションに関連付けません。

ZwOpenKeyTransacted ルーチンは ZwOpenKeyTransactedEx に似ていますが、OpenOptions パラメーターは受け入れられません。 ZwOpenKeyTransactedEx の OpenOptions パラメーターを使用すると、呼び出し元はシンボリックリンクであるキーを開いたり、バックアップおよび復元操作用のキーを開いたりできます。 OpenOptions パラメーターを 0 に設定した ZwOpenKeyTransactedEx の呼び出しは、ZwOpenKeyTransacted の呼び出しと同じです。

カーネルモードドライバーがトランザクションへのハンドルを取得した後 (たとえば、 ZwCreateTransaction を呼び出すことによって)、ドライバーは、このトランザクションの一部である一連のレジストリ操作を実行できます。ドライバーは、トランザクションで行われた変更にコミットするか、トランザクションをロールバックすることによって、トランザクションを閉じることができます。

ドライバーは、トランザクションの一部であるすべてのレジストリ操作を正常に完了した後、 ZwCommitTransaction ルーチンを呼び出して変更にコミットできます。ドライバーは、トランザクションをロールバックする ZwRollbackTransaction ルーチンを呼び出すことができます。

トランザクション中に、操作を実行するシステム呼び出しが次のいずれかの条件を満たしている場合、レジストリ操作はトランザクションの一部になります。

呼び出しは、入力パラメーターとしてトランザクションハンドルを指定します。たとえば、 ZwCreateKeyTransacted と ZwOpenKeyTransactedEx の呼び出しでは、1 つ以上のキーをトランザクションに関連付けることができます。
呼び出しは、入力パラメーターとして、トランザクションハンドルが指定された ZwCreateKeyTransacted または ZwOpenKeyTransactedEx の呼び出しによって取得されたレジストリキーハンドルを指定します。たとえば、 ZwSetValueKey ルーチンの呼び出しでは、この方法で取得したキーハンドルを使用して、トランザクションの一部としてレジストリキーの値を設定できます。

カーネルモードトランザクションの詳細については、カーネルトランザクションマネージャーの使用に関するページを参照してください。

ZwOpenKeyTransactedEx は、 ObjectAttributes パラメーターが指す構造体のセキュリティ情報を無視します。

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

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

要件

要件	値
サポートされている最小のクライアント	Windows 7 以降のバージョンの Windows オペレーティングシステムで使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)