WdfRegistryCreateKey 関数 (wdfregistry.h)

[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を返します。 それ以外の場合、メソッドは次のいずれかの値を返す可能性があります。

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
                                  );
}

要件

こちらもご覧ください

ACCESS_MASK

RtlInitUnicodeString

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfDeviceOpenRegistryKey

WdfDriverCreate

WdfDriverOpenParametersRegistryKey

WdfFdoInitOpenRegistryKey

WdfRegistryOpenKey

ZwCreateKey