IRegistryKey::NewSubKey メソッド (portcls.h)
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 オブジェクト の参照カウント規則に従います。
必要条件
| 要件 | 価値 |
|---|---|
| ターゲット プラットフォーム の | 万国 |
| ヘッダー | portcls.h (Portcls.h を含む) |
| IRQL | PASSIVE_LEVEL |