IRegistryKey：：NewSubKey 方法（portcls.h）

2025-04-09

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

要指派給子機碼之名稱的指標。這個參數必須是有效的非NULL 型別的指標 UNICODE_STRING。

[in] CreateOptions

指出建立選項的旗標。如果不需要的話，可以是零。如果 RegistryKeyType 的值 GeneralRegistryKey，則需要此參數;否則，方法不會使用此參數。如需詳細資訊，請參閱下列一節。

[out, optional] Disposition

處置值的輸出指標。此參數指向呼叫端配置的 ULONG 變數，方法會寫入狀態值，指出是否已建立新的索引鍵或開啟現有的索引鍵。這個參數是選擇性的，如果呼叫端不需要 NULL，則可以指定為 NULL。如需詳細資訊，請參閱下列一節。

傳回值

如果呼叫成功透過 NewSubKey 參數輸出有效的 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 物件的參考計數慣例。