WdfRegistryCreateKey 関数 (wdfregistry.h)

[アーティクル]
02/29/2024

[KMDF と UMDF に適用]

WdfRegistryCreateKey メソッドは、指定されたレジストリキーを作成して開くか、キーが既に存在する場合はキーを開き、レジストリキーを表すフレームワークレジストリキーオブジェクトを作成します。

構文

NTSTATUS WdfRegistryCreateKey(
  [in, optional]  WDFKEY                 ParentKey,
  [in]            PCUNICODE_STRING       KeyName,
  [in]            ACCESS_MASK            DesiredAccess,
  [in]            ULONG                  CreateOptions,
  [out, optional] PULONG                 CreateDisposition,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES KeyAttributes,
  [out]           WDFKEY                 *Key
);

パラメーター

[in, optional] ParentKey

フレームワークレジストリキーオブジェクトへのハンドル。このオブジェクトは、ドライバーが開いた親レジストリキーを表します。このパラメーターは省略可能であり、 NULL にすることができます。パラメーターが NULL でない場合、 KeyName が指定するキーは、レジストリ内のこの親キーの下に存在する必要があります。この親キーの詳細については、「解説」セクションを参照してください。

[in] KeyName

開くキーの名前を含む UNICODE_STRING 構造体へのポインター。キー名にはパス情報を含めることができます。 ParentKey が NULL の場合、KeyName はレジストリキーへの完全なパスを指定する必要があります。

[in] DesiredAccess

ドライバーが指定したレジストリキーに対して要求するアクセス権を指定する、 ACCESS_MASK型指定された値。ドライバーがレジストリキーに通常使用するアクセス権の一覧については、「 Registry-Key オブジェクトへのハンドルを開く」を参照してください。ドライバーは、必要なアクセスの種類のみを要求する必要があります。たとえば、ドライバーは、レジストリキーのみを読み取るかどうかをKEY_ALL_ACCESSを要求しないでください。

[in] CreateOptions

1 つ以上のフラグ。これらのフラグの詳細については、「 CreateOptions パラメーター」または「ZwCreateKey」を参照してください。

[out, optional] CreateDisposition

新しいキーが作成された場合にREG_CREATED_NEW_KEYを受け取る場所へのポインター。既存のキーが開かれた場合はREG_OPENED_EXISTING_KEY。これらの値は Wdm.h で定義されています。このポインターは省略可能であり、 NULL にすることができます。

[in, optional] KeyAttributes

新しいレジストリキーオブジェクトのドライバー指定の属性を含む WDF_OBJECT_ATTRIBUTES 構造体へのポインター。このパラメーターは省略可能であり、WDF_NO_OBJECT_ATTRIBUTESできます。

[out] Key

新しいレジストリキーオブジェクトへのハンドルを受け取る場所へのポインター。

戻り値

操作が成功した場合、WdfRegistryCreateKey はSTATUS_SUCCESSを返します。それ以外の場合、メソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_DEVICE_REQUEST	IRQL = PASSIVE_LEVELで WdfRegistryCreateKey が呼び出されませんでした。
STATUS_INVALID_PARAMETER	無効なパラメーターが指定されました。
STATUS_INSUFFICIENT_RESOURCES	レジストリキーオブジェクトを割り当てませんでした。
STATUS_ACCESS_DENIED	システムは、指定されたアクセス権を拒否しました。
STATUS_OBJECT_NAME_NOT_FOUND	指定されたレジストリキーが存在しません。

WdfRegistryCreateKey メソッドが返す可能性があるその他の戻り値の一覧については、「Framework オブジェクト作成エラー」を参照してください。

このメソッドは、他の NTSTATUS 値を返す場合もあります。

注釈

親キーを表すレジストリキーオブジェクトへのハンドルを取得するために、ドライバーは WdfDriverOpenParametersRegistryKey、 WdfDeviceOpenRegistryKey、または WdfFdoInitOpenRegistryKey を呼び出すことができます。

既定では、新しいレジストリキーオブジェクトの親は、WdfDriverCreate メソッドによって作成されるフレームワークドライバーオブジェクトです。 WDF_OBJECT_ATTRIBUTES構造体の ParentObject メンバーを使用して、別の親を指定できます。フレームワークは、親オブジェクトを削除するときにレジストリキーオブジェクトを削除します。ドライバーが既定の親を変更しない場合、ドライバーは、オブジェクトの使用が完了したときにレジストリキーオブジェクトを削除する必要があります。それ以外の場合、レジストリキーオブジェクトは、I/O マネージャーがドライバーをアンロードするまで保持されます。

ドライバーが既定の親を変更しない場合、ドライバーはオブジェクトの使用が完了したときに WdfRegistryClose を呼び出す必要があります。それ以外の場合、レジストリキーオブジェクトは、I/O マネージャーがドライバーをアンロードするまで保持されます。または、ドライバーは WdfObjectDelete を呼び出してレジストリキーオブジェクトを削除することもできます。

レジストリキーオブジェクトの詳細については、「 Framework-Based ドライバーでのレジストリの使用」を参照してください。

例

次のコード例では、ドライバーのソフトウェアキーを開き、ドライバーのソフトウェアキーの下にある myKeyStr レジストリキーを作成して開きます。

WDFKEY  hKey, subkey;
NTSTATUS  status;
UNICODE_STRING  myKeyStr;

status = WdfDeviceOpenRegistryKey(
                                  device,
                                  PLUGPLAY_REGKEY_DRIVER,
                                  KEY_READ,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &hKey
                                  );
if (NT_SUCCESS(status)){
    RtlInitUnicodeString(
                         &myKeyStr,
                         L"myKeyStr"
                         );
    status = WdfRegistryCreateKey(
                                  hKey,
                                  &myKeyStr,
                                  KEY_READ,
                                  REG_OPTION_NON_VOLATILE,
                                  NULL,
                                  WDF_NO_OBJECT_ATTRIBUTES,
                                  &subkey
                                  );
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
最小 UMDF バージョン	2.0
Header	wdfregistry.h (Wdf.h を含む)
Library	Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)