Metodo IPort::NewRegistryKey (portcls.h)

Il metodo NewRegistryKey apre una chiave del Registro di sistema esistente o crea una nuova chiave nel Registro di sistema. Il metodo crea un oggetto chiave del Registro di sistema per rappresentare la chiave e restituisce un riferimento a questo oggetto al chiamante. Il chiamante accede quindi alla chiave tramite l'interfaccia IRegistryKey dell'oggetto.

Sintassi

NTSTATUS NewRegistryKey(
  PREGISTRYKEY       *OutRegistryKey,
  PUNKNOWN           OuterUnknown,
  ULONG              RegistryKeyType,
  ACCESS_MASK        DesiredAccess,
  POBJECT_ATTRIBUTES ObjectAttributes,
  ULONG              CreateOptions,
  PULONG             Disposition
);

Parametri

OutRegistryKey

Puntatore a una variabile puntatore allocata dal chiamante in cui il metodo scrive il riferimento all'oggetto IRegistryKey. Questo oggetto rappresenta la chiave del Registro di sistema che viene aperta o creata. Il chiamante deve specificare un valore di puntatore non NULL valido per questo parametro.

OuterUnknown

Puntatore all'interfaccia IUnknown di un oggetto che deve aggregare l'oggetto chiave del Registro di sistema. Questo parametro è facoltativo e, Se l'aggregazione non è obbligatoria, specificare questo parametro come NULL.

RegistryKeyType

Specifica il tipo di chiave del Registro di sistema a cui il chiamante richiede l'accesso. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

DesiredAccess

Maschera di controllo di accesso che specifica il tipo di accesso richiesto dal chiamante alla chiave. Questo parametro è di tipo ACCESS_MASK. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

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, il metodo non usa questo parametro. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

CreateOptions

Flag che indicano le opzioni di creazione. Può essere zero se non si desidera. Questo parametro è obbligatorio se RegistryKeyType ha il valore GeneralRegistryKey; in caso contrario, il metodo non usa questo parametro. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Disposition

Puntatore a una variabile ULONG allocata dal chiamante in cui il metodo scrive un valore di stato che indica se è stata creata una nuova chiave o se è stata aperta una chiave esistente. Questo parametro è facoltativo e può essere specificato come NULL se il chiamante non richiede il valore di stato. Il metodo usa questo parametro solo se RegistryKeyType ha il valore GeneralRegistryKey. Il metodo non usa il parametro per gli altri tipi di chiave. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Valore restituito

Questo metodo restituisce NTSTATUS che contiene STATUS_SUCCESS se la chiamata ha avuto esito positivo. In caso contrario, il metodo restituisce un codice di errore appropriato.

Commenti

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

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

Il chiamante deve impostare il parametro RegistryKeyType su uno dei valori di enumerazione illustrati nella tabella seguente.

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 dell'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 NewRegistryKey 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 il tipo di chiave è GeneralRegistryKey e il puntatore del descrittore di sicurezza nella struttura ObjectAttributes è NULL o il puntatore ACL nel descrittore di sicurezza è NULL, la nuova chiave creata dalla chiamata erediterà l'ACL della chiave padre per impostazione predefinita.

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

Il metodo NewRegistryKey è simile alla funzione PcNewRegistryKey, 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 in genere chiamato dai driver dell'adattatore. I driver Miniport in genere chiamano NewRegistryKey.

Dopo aver creato o aperto una chiave del Registro di sistema tramite una chiamata a NewRegistryKey o PcNewRegistryKey, il metodo IRegistryKey::NewSubKey può essere usato per creare sottochiavi in tale chiave.

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

Requisiti

Vedi anche

IPort