Funzione PcNewRegistryKey (portcls.h)

Articolo
08/07/2023

La funzione PcNewRegistryKey apre o crea una nuova chiave del Registro di sistema e crea un oggetto IRegistryKey per rappresentare la chiave. Il chiamante accede alla chiave tramite questo oggetto.

Sintassi

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
);

Parametri

[out] OutRegistryKey

Puntatore di output all'oggetto chiave del Registro di sistema creato da questa funzione. Questo parametro punta a una variabile puntatore allocata dal chiamante in cui la funzione restituisce il puntatore all'oggetto IRegistryKey . L'oggetto rappresenta la chiave del Registro di sistema da aprire o creare. Specificare un valore di puntatore non NULL valido per questo parametro.

[in, optional] OuterUnknown

Puntatore all'interfaccia IUnknown di un oggetto che deve aggregare l'oggetto OutRegistryKey . A meno che non sia necessaria l'aggregazione, impostare questo parametro su NULL.

[in] RegistryKeyType

Specifica il tipo di chiave del Registro di sistema che il chiamante desidera creare o aprire. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in] DesiredAccess

Specifica una maschera di controllo di accesso. Questo parametro è una struttura di tipo ACCESS_MASK. Indica il tipo di accesso richiesto dal chiamante alla chiave del Registro di sistema che deve essere aperta o creata. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, optional] DeviceObject

Puntatore all'oggetto dispositivo del driver dell'adattatore. Questo puntatore viene eseguito il cast al tipo PVOID. Se RegistryKeyType è un valore diverso da GeneralRegistryKey, questo parametro deve puntare a una struttura di sistema inizializzata valida di tipo DEVICE_OBJECT. Se il valore di RegistryKeyType è GeneralRegistryKey, la funzione PcNewRegistryKey non usa questo parametro. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, optional] SubDevice

Specifica l'aspetto del dispositivo che deve essere offerto ai client. I driver dell'adattatore devono assegnare il valore NULL a questo parametro.

[in, optional] ObjectAttributes

Puntatore agli attributi oggetto della chiave da creare o aprire. Se RegistryKeyType ha il valore GeneralRegistryKey, questo parametro deve puntare a una struttura di sistema valida e inizializzata di tipo OBJECT_ATTRIBUTES con una stringa ObjectName valida per la chiave; in caso contrario, la funzione non usa questo parametro. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, optional] CreateOptions

Specifica le opzioni di creazione. Può essere zero se non si desidera. Se RegistryKeyType non è GeneralRegistryKey, la funzione PcNewRegistryKey ignora questo parametro. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[out, optional] Disposition

Puntatore a una variabile che riceve un valore che indica se è stata creata una chiave o se è stata aperta una chiave esistente. Questo parametro è facoltativo e può essere specificato come NULL. Se RegistryKeyType è un valore diverso da GeneralRegistryKey, la funzione PcNewRegistryKey ignora questo parametro. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Valore restituito

PcNewRegistryKey restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo. In caso contrario, restituisce un codice di errore appropriato.

Commenti

Se il valore del parametro RegistryKeyType è GeneralRegistryKey, la funzione PcNewRegistryKey apre una chiave esistente o crea una nuova chiave nel Registro di sistema, come indicato dal valore restituito dalla funzione tramite il parametro Disposition . Se la chiave è di qualsiasi tipo diverso da GeneralRegistryKey, la funzione apre una chiave già esistente creata in precedenza durante Plug and Play'enumerazione del dispositivo.

I parametri DesiredAccess, ObjectAttributes, CreateOptions e Disposition accettano i valori definiti per i parametri con gli stessi nomi nella chiamata ZwCreateKey .

Il parametro RegistryKeyType deve essere impostato su uno dei valori di enumerazione illustrati nella tabella seguente.

Valore RegistryKeyType	Significato
GeneralRegistryKey	Fornire l'accesso generico a qualsiasi tipo di chiave. Aprire la chiave specificata se esiste già o creare la chiave in caso contrario.
DeviceRegistryKey	Aprire una chiave esistente contenente informazioni specifiche del dispositivo. La chiave si trova sotto la chiave per l'istanza del dispositivo specificata da DeviceObject.
DriverRegistryKey	Aprire una chiave esistente contenente informazioni specifiche del driver.
HwProfileRegistryKey	Aprire una chiave esistente relativa al profilo hardware corrente contenente informazioni sul dispositivo o sul driver. In questo modo il driver può accedere alle informazioni di configurazione specifiche del profilo hardware.
DeviceInterfaceRegistryKey	Non usato con PcNewRegistryKey. Per informazioni dettagliate, vedere IPort::NewRegistryKey .

Per un valore RegistryKeyType di GeneralRegistryKey, il chiamante deve fornire un valore di parametro ObjectAttributes valido e i parametri CreateOptions e Disposition sono facoltativi. Per qualsiasi altro valore RegistryKeyType , il chiamante deve fornire un valore di parametro DeviceObject valido e i parametri CreateOptions e Disposition non vengono usati.

Il parametro ObjectAttributes punta a una struttura opaca di tipo OBJECT_ATTRIBUTES che contiene attributi di oggetto, ad esempio il nome della chiave e il descrittore di sicurezza. Utilizzare la macro InitializeObjectAttributes per inizializzare la struttura. Nel parametro Attributes per questa macro impostare il flag OBJ_KERNEL_HANDLE a meno che non si intenda consentire alle applicazioni in modalità utente non sicure di avere accesso in lettura/scrittura alla chiave del Registro di sistema.

Il parametro DesiredAccess è una maschera di controllo di accesso. Specifica il tipo di controllo di accesso che il chiamante deve disporre della nuova chiave del Registro di sistema durante l'accesso tramite l'oggetto OutRegistryKey . Questa maschera non deve essere confusa con l'elenco di controllo di accesso (ACL) che controlla l'accesso da parte degli utenti alla chiave del Registro di sistema. Quando si chiama PcNewRegistryKey per creare una chiave del Registro di sistema di tipo GeneralRegistryKey, il parametro ObjectAttributes specifica gli attributi della chiave, incluso un descrittore di sicurezza che contiene l'ACL. Tuttavia, se la nuova chiave è di tipo GeneralRegistryKey e il puntatore del descrittore di sicurezza nella struttura ObjectAttributes è NULL o il puntatore ACL nel descrittore di sicurezza è NULL, la nuova chiave erediterà l'ACL della chiave padre per impostazione predefinita.

Se la chiave è di qualsiasi tipo diverso da GeneralRegistryKey, la chiave mantiene l'ACL che Plug and Play assegnato alla chiave al momento della creazione durante l'enumerazione del dispositivo.

La funzione PcNewRegistryKey è simile al metodo IPort::NewRegistryKey , ad eccezione del fatto che l'oggetto dispositivo e l'oggetto porta devono essere specificati in modo esplicito in una chiamata PcNewRegistryKey , ma sono semplicemente impliciti in una chiamata NewRegistryKey . PcNewRegistryKey viene usato principalmente dai driver dell'adattatore. I driver Miniport in genere chiamano NewRegistryKey .

I parametri OutRegistryKey e OuterUnknown seguono le convenzioni di conteggio dei riferimenti per gli oggetti COM.

Requisiti

Requisito	Valore
Client minimo supportato	Il driver di sistema PortCls implementa la funzione PcNewRegistryKey in Microsoft Windows 98/Me e nei sistemi operativi Windows 2000 e versioni successive.
Piattaforma di destinazione	Universale
Intestazione	portcls.h (include Portcls.h)
Libreria	Portcls.lib
IRQL	PASSIVE_LEVEL