IRegistryKey::NewSubKey メソッド (portcls.h)

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

メソッドは NewSubKey 、新しいレジストリサブキーを作成するか、 IRegistryKey オブジェクトによって表されるキーの下に既存のサブキーを開きます。

構文

NTSTATUS NewSubKey(
  [out]           IRegistryKey    **RegistrySubKey,
  [in]            PUNKNOWN        OuterUnknown,
  [in]            ACCESS_MASK     DesiredAccess,
  [in]            PUNICODE_STRING SubKeyName,
  [in]            ULONG           CreateOptions,
  [out, optional] PULONG          Disposition
);

パラメーター

[out] RegistrySubKey

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

[in] OuterUnknown

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

[in] DesiredAccess

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

[in] SubKeyName

サブキーに割り当てる名前へのポインター。このパラメーターは、UNICODE_STRING型の初期化された構造体への有効な NULL 以外のポインターである必要があります。

[in] CreateOptions

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

[out, optional] Disposition

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

戻り値

NewSubKeyは、RegistrySubKey パラメーターを介した有効な IRegistryKey ポインターの出力で呼び出しが成功した場合に、STATUS_SUCCESSを返します。それ以外の場合、メソッドは適切なエラーコードを返します。

注釈

メソッドは NewSubKey 、指定されたレジストリキーが既に存在する場合は開くか、存在しない場合はレジストリに新しいキーを作成します。メソッドは、RegistrySubKey パラメーターを使用して、新しいキーの IRegistryKey インターフェイスへのポインターを出力します。メソッドは、キーが開かれたか作成されたかを示すために、省略可能な Disposition パラメーターを使用して状態値も出力します。

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

DesiredAccess パラメーターは、RegistrySubKey オブジェクトを介してアクセスするときに呼び出し元がサブキーに対して必要とするアクセス制御の種類を指定するアクセス制御マスクです。このマスクは、ユーザーによるレジストリサブキーへのアクセスを制御する ACL (アクセス制御リスト) と混同しないでください。 PcNewRegistryKey 関数または IPort::NewRegistryKey メソッドが GeneralRegistryKey 型のレジストリキーを作成すると、ObjectAttributes パラメーターは、ACL を含むセキュリティ記述子を含むキーの属性を指定します。ただし、メソッドが NewSubKey 新しいレジストリサブキーを作成すると、そのサブキーは親キーから ACL を継承するだけです。メソッドは NewSubKey 、親キーとは異なる ACL を指定する手段を提供しません。

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