Funzione PcNewRegistryKey (portcls.h)
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 |
Vedi anche
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per