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を返します。 エラーの戻り値として考えられるのは、次のとおりです。

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

注釈

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

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)

こちらもご覧ください

ACCESS_MASK

InitializeObjectAttributes

OBJECT_ATTRIBUTES

ObOpenObjectByPointer

ZwClose

ZwCommitTransaction

ZwCreateKey

ZwCreateTransaction

ZwOpenKeyTransacted

ZwRollbackTransaction

ZwSetValueKey