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

指出建立選項的旗標。 如果不需要的話，可以為零。 如果 RegistryKeyType 具有 GeneralRegistryKey 值，則需要此參數;否則，方法不會使用此參數。 如需詳細資訊，請參閱接下來的＜備註＞一節。

Disposition

呼叫端配置的 ULONG 變數指標，此方法會寫入狀態值，指出是否已建立新的索引鍵或開啟現有的索引鍵。 此參數是選擇性的，如果呼叫端不需要狀態值，則可以指定為 NULL。 只有在 RegistryKeyType 具有 GeneralRegistryKey 值時，此方法才會使用此參數。 方法不會針對任何其他索引鍵類型使用 參數。 如需詳細資訊，請參閱接下來的＜備註＞一節。

傳回值

這個方法會傳回NTSTATUS，如果呼叫成功，則包含STATUS_SUCCESS。 否則，方法會傳回適當的錯誤碼。

備註

DesiredAccess、ObjectAttributes 和 Disposition 參數會採用針對 ZwCreateKey 呼叫中具有相同名稱的參數所定義的值。

如果 RegistryKeyType 參數具有 GeneralRegistryKey 值，則 NewRegistryKey 方法會開啟現有的登錄機碼或在登錄中建立新的機碼，如方法透過 Disposition 參數輸出的值所指出。 如果索引鍵類型是 GeneralRegistryKey 以外的任何值，則方法會開啟先前在 隨插即用 裝置列舉期間建立的現有索引鍵。

呼叫端應該將 RegistryKeyType 參數設定為下表所示的其中一個列舉值。

RegistryKeyType 值	意義
GeneralRegistryKey	提供任何索引鍵類型的泛型存取。 如果金鑰存在，則開啟金鑰，如果不存在，則會建立金鑰。
DeviceRegistryKey	開啟包含裝置特定資訊的現有金鑰。
DriverRegistryKey	開啟包含驅動程式特定資訊的現有金鑰。
HwProfileRegistryKey	針對裝置或驅動程式資訊，開啟相對於目前硬體配置檔的現有密鑰。 這可讓驅動程式存取硬體配置檔專屬的組態資訊。
DeviceInterfaceRegistryKey	開啟包含特定裝置介面實例相關信息的現有登錄機碼。

對於 GeneralRegistryKey 的 RegistryKeyType 值，呼叫端必須提供有效的 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 對象的參考計數慣例。

規格需求

需求	值
標頭	portcls.h
IRQL	PASSIVE_LEVEL

另請參閱

IPort