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值 指派給此參數。

[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 參數應該設定為下表所示的其中一個列舉值。

對於 GeneralRegistryKey 的 RegistryKeyType 值，呼叫端必須提供有效的 ObjectAttributes 參數值，而 CreateOptions 和 Disposition 參數是選擇性的。 對於任何其他 RegistryKeyType 值，呼叫端必須提供有效的 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，該 ACL 會在裝置列舉期間建立密鑰時 隨插即用 指派給密鑰。

PcNewRegistryKey 函式類似於 IPort：：NewRegistryKey 方法，但裝置物件和埠對象必須在 PcNewRegistryKey 呼叫中明確指定，但只是在 NewRegistryKey 呼叫中隱含。 PcNewRegistryKey 主要是由適配卡驅動程式使用。 迷你埠驅動程式通常會改為呼叫 NewRegistryKey 。

OutRegistryKey 和 OuterUnknown 參數遵循 COM 對象的參考計數慣例。

規格需求

另請參閱

ACCESS_MASK

DEVICE_OBJECT

IPort：：NewRegistryKey

IRegistryKey

InitializeObjectAttributes

OBJECT_ATTRIBUTES

ZwCreateKey