PcNewRegistryKey 函式 （portcls.h）
PcNewRegistryKey 函式會開啟或建立新的登錄機碼，並建立 IRegistryKey 物件來表示機碼。 呼叫端會透過這個物件存取金鑰。
語法
PORTCLASSAPI NTSTATUS PcNewRegistryKey(
[out] PREGISTRYKEY *OutRegistryKey,
[in, optional] PUNKNOWN OuterUnknown,
[in] ULONG RegistryKeyType,
[in] ACCESS_MASK DesiredAccess,
[in, optional] PVOID DeviceObject,
[in, optional] PVOID SubDevice,
[in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
[in, optional] ULONG CreateOptions,
[out, optional] PULONG Disposition
);
參數
[out] OutRegistryKey
此函式所建立之登錄機碼對象的輸出指標。 此參數指向呼叫端配置的指標變數，函式會將指標輸出至 IRegistryKey 物件。 物件代表要開啟或建立的登錄機碼。 為此參數指定有效的非NULL 指標值。
[in, optional] OuterUnknown
需要匯總 outRegistryKey 物件之物件之 IUnknown 介面的指標。 除非需要匯總，否則請將此參數設定為 NULL。
[in] RegistryKeyType
指定呼叫端想要建立或開啟的登錄機碼類型。 如需詳細資訊，請參閱下列一節。
[in] DesiredAccess
指定訪問控制遮罩。 此參數是 類型為 ACCESS_MASK的結構。 指出呼叫端要求要開啟或建立之登錄機碼的存取類型。 如需詳細資訊，請參閱下列一節。
[in, optional] DeviceObject
配接器驅動程式裝置物件的指標。 此指標會轉換成 PVOID 類型。 如果 RegistryKeyType 是 GeneralRegistryKey以外的任何值，則此參數必須指向類型為 DEVICE_OBJECT的有效初始化系統結構。 如果 RegistryKeyType 的值是 GeneralRegistryKey，PcNewRegistryKey 函式就不會使用此參數。 如需詳細資訊，請參閱下列一節。
[in, optional] SubDevice
指定要提供給用戶端之裝置的層面。 配接器驅動程式必須將 NULL 值指派給此參數 NULL。
[in, optional] ObjectAttributes
要建立或開啟之索引鍵之物件屬性的指標。 如果 RegistryKeyType 具有 generalRegistryKey 值，此參數必須指向具有索引鍵有效 ObjectName 字串之類型 OBJECT_ATTRIBUTES 的有效初始化系統結構：否則，函式不會使用此參數。 如需詳細資訊，請參閱下列一節。
[in, optional] CreateOptions
指定建立選項。 如果不需要的話，可以是零。 如果 RegistryKeyType 未 GeneralRegistryKey，PcNewRegistryKey 函式會忽略此參數。 如需詳細資訊，請參閱下列一節。
[out, optional] Disposition
接收值的變數指標，指出是否已建立索引鍵或開啟現有的索引鍵。 這個參數是選擇性的，而且可以指定為 NULL 。 如果 RegistryKeyType 不是 GeneralRegistryKey以外的任何值，則 PcNewRegistryKey 函式會忽略此參數。 如需詳細資訊，請參閱下列一節。
傳回值
PcNewRegistryKey 如果呼叫成功，就會傳回STATUS_SUCCESS。 否則，它會傳回適當的錯誤碼。
言論
如果 RegistryKeyType 參數的值是 GeneralRegistryKey，則 PcNewRegistryKey 函式會開啟現有的機碼，或在登錄中建立新的機碼，如函式透過 Disposition 參數輸出的值所指示。 如果索引鍵不是 GeneralRegistryKey以外的任何類型，則函式會開啟先前在隨插即用裝置列舉期間建立的現有密鑰。
DesiredAccess、ObjectAttributes、CreateOptions，以及 Disposition 參數會採用針對在 ZwCreateKey 呼叫中具有相同 名稱的參數所定義的值。
RegistryKeyType 參數應該設定為下表所示的其中一個列舉值。
| RegistryKeyType 值 | 意義 |
|---|---|
| GeneralRegistryKey | 提供任何索引鍵類型的泛型存取。 如果指定的索引鍵已經存在，請開啟指定的索引鍵，如果索引鍵不存在，請建立索引鍵。 |
| DeviceRegistryKey | 開啟包含裝置特定資訊的現有金鑰。 金鑰位於 DeviceObject 所指定裝置實例的金鑰底下，。 |
| DriverRegistryKey | 開啟包含驅動程式特定資訊的現有金鑰。 |
| HwProfileRegistryKey | 開啟與目前硬體配置檔相關的現有密鑰，其中包含裝置或驅動程序資訊。 這可讓驅動程式存取硬體配置檔特定的組態資訊。 |
| DeviceInterfaceRegistryKey | 未搭配 PcNewRegistryKey使用。 如需詳細資訊，請參閱 IPort：：NewRegistryKey。 |
針對 GeneralRegistryKey的 RegistryKeyType 值，呼叫端必須提供 有效的 objectAttributes 參數值，而 CreateOptions 和 Disposition 參數都是選擇性的。 對於任何其他 RegistryKeyType 值，呼叫端必須提供有效的 deviceObject 參數值 DeviceObject，而且不會使用 CreateOptions 和 Disposition 參數。
ObjectAttributes 參數指向類型不透明OBJECT_ATTRIBUTES結構，其中包含索引鍵名稱和安全性描述元等對象屬性。 使用 InitializeObjectAttributes 巨集來初始化 結構。 在這個巨集的 Attributes 參數中，除非您想要允許非安全的使用者模式應用程式具有登錄機碼的讀取/寫入許可權，否則請設定OBJ_KERNEL_HANDLE旗標。
DesiredAccess 參數是訪問控制遮罩。 它會指定呼叫者透過 outRegistryKey 物件存取它時，必須具有新登錄機碼的訪問控制類型。 此遮罩不應與訪問控制清單 （ACL） 混淆，該清單會控制使用者對登錄機碼的存取。 呼叫 PcNewRegistryKey 以建立類型為 GeneralRegistryKey的登錄機碼時，ObjectAttributes 參數會指定密鑰的屬性，包括包含 ACL 的安全性描述項。 不過，如果新索引鍵的類型 GeneralRegistryKey，而且 ObjectAttributes 結構中的安全性描述元指標 NULL，或安全性描述元中的 ACL 指標 NULL，則新的密鑰默認會繼承父密鑰的 ACL。
如果密鑰不是 GeneralRegistryKey以外的任何類型，則密鑰會保留在裝置列舉期間建立密鑰時，隨插即用指派給密鑰的 ACL。
PcNewRegistryKey 函式與 IPort：：NewRegistryKey 方法類似，不同之處在於必須在 PcNewRegistryKey 呼叫中明確指定裝置物件和埠物件，但只會在 NewRegistryKey 呼叫中隱含。 PcNewRegistryKey 主要是由適配卡驅動程式使用。 迷你埠驅動程式通常會改為呼叫 NewRegistryKey。
OutRegistryKey 和 OuterUnknown 參數遵循 COM 物件的 參考計數慣例。
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | PortCls 系統驅動程式會在 Microsoft Windows 98/Me 和 Windows 2000 和更新版本的作系統中實作 PcNewRegistryKey 函式。 |
| 目標平臺 | 普遍 |
| 標頭 | portcls.h （包括 Portcls.h） |
| 連結庫 | Portcls.lib |
| IRQL | PASSIVE_LEVEL |