ZwCreateKeyTransacted 関数 (wdm.h)
ZwCreateKeyTransacted ルーチンは、新しいレジストリ キーを作成するか、既存のレジストリ キーを開き、キーをトランザクションに関連付けます。
構文
NTSYSAPI NTSTATUS ZwCreateKeyTransacted(
[out] PHANDLE KeyHandle,
[in] ACCESS_MASK DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
ULONG TitleIndex,
[in, optional] PUNICODE_STRING Class,
[in] ULONG CreateOptions,
[in] HANDLE TransactionHandle,
[out, optional] PULONG Disposition
);
パラメーター
[out] KeyHandle
ルーチンがキーにハンドルを書き込む HANDLE 変数へのポインター。
[in] DesiredAccess
呼び出し元が要求するキーへのアクセスの種類を指定します。 このパラメーターは 、ACCESS_MASK 値です。 詳細については、ZwCreateKey ルーチンの DesiredAccess パラメーターの説明を参照してください。
[in] ObjectAttributes
開いているキーのオブジェクト属性へのポインター。 このパラメーターは、InitializeObjectAttributes ルーチンによって以前に初期化されている必要があるOBJECT_ATTRIBUTES構造体を指します。 呼び出し元は、InitializeObjectAttributes の呼び出しで、レジストリ キーの名前を ObjectName パラメーターとして指定する必要があります。 呼び出し元がシステム スレッド コンテキストで実行されていない場合は、 InitializeObjectAttributes を呼び出すときにOBJ_KERNEL_HANDLE属性を設定する必要があります。
TitleIndex
デバイス ドライバーと中間ドライバーでは、このパラメーターを 0 に設定します。
[in, optional] Class
デバイス ドライバーと中間ドライバーでは、このパラメーターを NULL に設定 します。
[in] CreateOptions
ルーチンがキーを作成または開くときに適用するオプションを指定します。 このパラメーターを 0 に設定するか、次の 1 つ以上の REG_OPTION_XXX フラグ ビットのビットごとの OR に 設定します。
| CreateOptions フラグ | 説明 |
|---|---|
| REG_OPTION_VOLATILE | キーは、コンピューターの再起動後も保持 されません 。 |
| REG_OPTION_NON_VOLATILE | キーは、コンピューターの再起動後も保持されます。 |
| REG_OPTION_CREATE_LINK | キーはシンボリック リンクです。 このフラグは、デバイス ドライバーと中間ドライバーでは使用されません。 |
| REG_OPTION_BACKUP_RESTORE | バックアップ操作と復元操作を有効にする特別な特権でキーを開きます。 このフラグは、デバイス ドライバーと中間ドライバーでは使用されません。 |
[in] TransactionHandle
トランザクション オブジェクトへのハンドル。 このハンドルを取得するには、 ZwCreateTransaction ルーチンを呼び出します。 または、トランザクション オブジェクトへのポインターがある場合は、 ObOpenObjectByPointer ルーチンへのポインターを指定して、対応するトランザクション ハンドルを取得できます。
[out, optional] Disposition
呼び出しが新しいキーを作成したか、既存のキーを開いたかを示すために、ルーチンが次のいずれかの値を書き込む場所へのポインター。
| 廃棄 値 | 説明 |
|---|---|
| REG_CREATED_NEW_KEY | 新しいキーが作成されました。 |
| REG_OPENED_EXISTING_KEY | 既存のキーが開かれました。 |
この情報が不要な場合は、 Disposition = NULL を 設定できます。
戻り値
ZwCreateKeyTransacted は 、呼び出しが正常にキーを作成または開いた場合にSTATUS_SUCCESSを返します。 エラーの戻り値として考えられるのは、次のとおりです。
| リターン コード | 説明 |
|---|---|
|
ObjectAttributes パラメーターが NULL であるか、無効な情報を指しているか、CreateOptions パラメーターの値で無効なオプションが指定されています。 |
|
オブジェクト属性のレジストリ パスが無効です。 |
|
オブジェクト属性のレジストリ パスが見つかりませんでした。 |
|
呼び出し元には、名前付きレジストリ キーのハンドルを開くために必要なアクセス権がありませんでした。 |
|
メモリ割り当て操作に失敗しました。 |
注釈
このルーチンは、呼び出し元がレジストリ キーにアクセスできるハンドルを提供します。 さらに、このルーチンは、キーをアクティブなトランザクションに関連付けます。
KeyHandle が指すハンドルが使用されなくなったら、ドライバーは ZwClose ルーチンを呼び出して閉じる必要があります。
ZwCreateKeyTransacted と同様に、ZwOpenKeyTransacted ルーチンはキーをトランザクションに関連付けます。 新しいキーを作成したり、既存のキーを開いたりできる ZwCreateKeyTransacted とは異なり、 ZwOpenKeyTransacted は既に存在するレジストリ キーのみを開くことができます。
カーネル モード ドライバーがトランザクションへのハンドルを取得した後 (たとえば、 ZwCreateTransaction を呼び出すことによって)、ドライバーは、このトランザクションの一部である一連のレジストリ操作を実行できます。 ドライバーは、トランザクションで行われた変更にコミットするか、トランザクションをロールバックすることによって、トランザクションを閉じます。
ドライバーは、トランザクションの一部であるすべてのレジストリ操作を正常に完了した後、 ZwCommitTransaction ルーチンを呼び出して変更をコミットできます。 ドライバーは、トランザクションをロールバックする ZwRollbackTransaction ルーチンを呼び出すことができます。
トランザクション中に、操作を実行するシステム呼び出しが次のいずれかの条件を満たしている場合、レジストリ操作はトランザクションの一部になります。
- 呼び出しは、入力パラメーターとしてトランザクション ハンドルを指定します。 たとえば、 ZwCreateKeyTransacted と ZwOpenKeyTransacted の呼び出しでは、1 つ以上のハンドルをレジストリ キーにトランザクションに関連付けることができます。
- 呼び出しは、入力パラメーターとして、トランザクション ハンドルが指定 された ZwCreateKeyTransacted または ZwOpenKeyTransacted の呼び出しによって取得されたレジストリ キー ハンドルを指定します。 たとえば、 ZwSetValueKey ルーチンの呼び出しでは、この方法で取得したキー ハンドルを使用して、トランザクションの一部としてレジストリ キーの値を設定できます。
オブジェクト属性のセキュリティ記述子は、 DesiredAccess パラメーターで指定されたアクセス権が、キーにアクセスするルーチン (キーにアクセスする ZwOpenKeyTransacted など) またはキーのサブキーを作成する ルーチン (ZwCreateKeyTransacted など) への後の呼び出しで付与されるかどうかを決定します。
カーネル モードの呼び出し元がシステム スレッド コンテキストで実行されていない場合は、作成するハンドルがカーネル ハンドルであることを確認する必要があります。 それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってハンドルにアクセスできます。 詳細については、「 オブジェクト ハンドル」を参照してください。
カーネル モードでレジストリ キーを操作する方法の詳細については、「 ドライバーでのレジストリの使用」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista 以降のバージョンの Windows で使用できます。 |
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |