IPort::NewRegistryKey メソッド (portcls.h)

NewRegistryKey メソッドは、既存のレジストリ キーを開くか、レジストリに新しいキーを作成します。 メソッドは、キーを表すレジストリ キー オブジェクトを作成し、このオブジェクトへの参照を呼び出し元に出力します。 呼び出し元は、オブジェクトの IRegistryKey インターフェイスを介してキーにアクセスします。

構文

NTSTATUS NewRegistryKey(
  PREGISTRYKEY       *OutRegistryKey,
  PUNKNOWN           OuterUnknown,
  ULONG              RegistryKeyType,
  ACCESS_MASK        DesiredAccess,
  POBJECT_ATTRIBUTES ObjectAttributes,
  ULONG              CreateOptions,
  PULONG             Disposition
);

パラメーター

OutRegistryKey

メソッドが IRegistryKey オブジェクトへの参照を書き込む呼び出し元によって割り当てられたポインター変数へのポインター。 このオブジェクトは、開かれるか作成されるレジストリ キーを表します。 呼び出し元は、このパラメーターに有効な NULL 以外のポインター値を指定する必要があります。

OuterUnknown

レジストリ キー オブジェクトを集計する必要があるオブジェクトの IUnknown インターフェイスへのポインター。 このパラメーターは省略可能です。 集計が必要ない場合は、このパラメーターを NULL として指定します。

RegistryKeyType

呼び出し元がアクセスを要求しているレジストリ キーの種類を指定します。 詳細については、「解説」を参照してください。

DesiredAccess

呼び出し元がキーに対して必要とするアクセスの種類を指定するアクセス制御マスク。 このパラメーターの型は ACCESS_MASK です。 詳細については、「解説」を参照してください。

ObjectAttributes

作成または開いているキーのオブジェクト属性へのポインター。 RegistryKeyType の値が GeneralRegistryKey の場合、このパラメーターは、キーの有効な ObjectName 文字列を使用してOBJECT_ATTRIBUTES型の有効な初期化されたシステム構造を指す必要があります。それ以外の場合、メソッドはこのパラメーターを使用しません。 詳細については、「解説」を参照してください。

CreateOptions

作成オプションを示すフラグ。 何も必要ない場合は、0 を指定できます。 このパラメーターは、RegistryKeyType の値が GeneralRegistryKey の場合に必要です。それ以外の場合、メソッドはこのパラメーターを使用しません。 詳細については、「解説」を参照してください。

Disposition

新しいキーが作成されたか、既存のキーが開かれたかを示す状態値をメソッドが書き込む呼び出し元によって割り当てられた ULONG 変数へのポインター。 このパラメーターは省略可能であり、呼び出し元が状態値を必要としない場合は NULL として指定できます。 このパラメーターは、RegistryKeyType の値が GeneralRegistryKey の場合にのみ使用されます。 メソッドでは、他のどのキー型にも パラメーターを使用しません。 詳細については、「解説」を参照してください。

戻り値

このメソッドは、呼び出しが成功した場合にSTATUS_SUCCESSを含む NTSTATUS を返します。 それ以外の場合、メソッドは適切なエラー コードを返します。

注釈

DesiredAccess、ObjectAttributes、および Disposition パラメーターは、ZwCreateKey 呼び出しで同じ名前のパラメーターに定義されている値を受け取ります。

RegistryKeyType パラメーターの値が GeneralRegistryKey の場合、NewRegistryKey メソッドは既存のレジストリ キーを開くか、または Disposition パラメーターを通じて出力される値によって示されるように、レジストリに新しいキーを作成します。 キーの種類が GeneralRegistryKey 以外の値である場合、メソッドは、デバイス列挙中に以前に作成された既存のキープラグ アンド プレイ開きます。

呼び出し元は、RegistryKeyType パラメーターを次の表に示す列挙値のいずれかに設定する必要があります。

RegistryKeyType 値が GeneralRegistryKey の場合、呼び出し元は有効な ObjectAttributes パラメーター値を指定する必要があり、CreateOptions パラメーターと Disposition パラメーターは省略可能です。 他の RegistryKeyType 値の場合、呼び出し元は有効な DeviceObject パラメーター値を指定する必要があり、CreateOptions パラメーターと Disposition パラメーターは使用されません。

ObjectAttributes パラメーターは、キー名やセキュリティ記述子などのオブジェクト属性を含む型OBJECT_ATTRIBUTESの不透明な構造を指します。 InitializeObjectAttributes マクロを使用して構造体を初期化します。 このマクロの Attributes パラメーターで、セキュリティで保護されていないユーザー モードのアプリケーションにレジストリ キーへの読み取り/書き込みアクセスを許可する場合を除き、OBJ_KERNEL_HANDLE フラグを設定します。

DesiredAccess パラメーターは、アクセス制御マスクです。 OutRegistryKey オブジェクトを介してアクセスするときに、呼び出し元が新しいレジストリ キーに対して必要とするアクセス制御の種類を指定します。 このマスクは、レジストリ キーへのユーザーによるアクセスを制御する ACL (アクセス制御リスト) と混同しないでください。 NewRegistryKey を呼び出して GeneralRegistryKey 型のレジストリ キーを作成する場合、ObjectAttributes パラメーターは、ACL を含むセキュリティ記述子を含むキーの属性を指定します。 ただし、キーの種類が GeneralRegistryKey で、ObjectAttributes 構造体のセキュリティ記述子ポインターが NULL であるか、セキュリティ記述子の ACL ポインターが NULL の場合、呼び出しによって作成された新しいキーは、既定で親キーの ACL を継承します。

キーが GeneralRegistryKey 型でない場合、キーは、デバイスの列挙中に作成されたときにキーに割り当てられたプラグ アンド プレイ ACL を保持します。

NewRegistryKey メソッドは、PcNewRegistryKey 関数に似ていますが、デバイス オブジェクトとポート オブジェクトは、PcNewRegistryKey 呼び出しで明示的に指定する必要がありますが、単に NewRegistryKey 呼び出しでは暗黙的に指定される必要があります。 PcNewRegistryKey は通常、アダプター ドライバーによって呼び出されます。 ミニポート ドライバーは通常、代わりに NewRegistryKey を呼び出します。

NewRegistryKey または PcNewRegistryKey の呼び出しによってレジストリ キーが作成または開かれると、そのキーの下にサブキーを作成するために IRegistryKey::NewSubKey メソッドを使用できます。

OutRegistryKey パラメーターと OuterUnknown パラメーターは、COM オブジェクトの参照カウント規則に従います。

要件

こちらもご覧ください

IPort