ZwOpenKeyTransactedEx 関数 (wdm.h)
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を返します。 考えられるエラーの戻り値は次のとおりです。
| リターン コード | 説明 |
|---|---|
|
ObjectAttributes パラメーターが NULL であるか、無効な情報を指しています。 |
|
OpenOptions パラメーターの値は、無効なオプションを指定します。 |
|
オブジェクト属性のレジストリ パスが無効です。 |
|
オブジェクト属性のレジストリ パスが見つかりませんでした。 |
|
呼び出し元には、名前付きレジストリ キーのハンドルを開くために必要なアクセス権がありませんでした。 |
|
メモリ割り当て操作が失敗しました。 |
注釈
このルーチンは、呼び出し元がレジストリ キーにアクセスできるハンドルを提供します。 さらに、このルーチンは、キーをアクティブなトランザクションに関連付けます。
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) |