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

指出建立選項的旗標。如果不需要的話，可以為零。如果 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 對象的參考計數慣例。