Metodo IRegistryKey::NewSubKey (portcls.h)

Articolo
08/07/2023

Il NewSubKey metodo crea una nuova sottochiave del Registro di sistema o apre una sottochiave esistente sotto la chiave rappresentata dall'oggetto IRegistryKey .

Sintassi

NTSTATUS NewSubKey(
  [out]           IRegistryKey    **RegistrySubKey,
  [in]            PUNKNOWN        OuterUnknown,
  [in]            ACCESS_MASK     DesiredAccess,
  [in]            PUNICODE_STRING SubKeyName,
  [in]            ULONG           CreateOptions,
  [out, optional] PULONG          Disposition
);

Parametri

[out] RegistrySubKey

Puntatore di output per la nuova sottochiave. Questo parametro punta a una variabile puntatore allocata dal chiamante in cui il metodo scrive il puntatore nel nuovo oggetto IRegistryKey . Questo oggetto rappresenta la sottochiave da aprire o creare. Specificare un valore di puntatore non NULL valido per questo parametro.

[in] 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.

[in] DesiredAccess

Specifica il tipo di accesso richiesto dal chiamante per la sottochiave che viene aperta o creata. Questo parametro è di tipo ACCESS_MASK. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in] SubKeyName

Puntatore al nome da assegnare alla sottochiave. Questo parametro deve essere un puntatore non NULL valido a una struttura inizializzata di tipo UNICODE_STRING.

[in] CreateOptions

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

[out, optional] Disposition

Puntatore di output per il valore di eliminazione. Questo parametro punta 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 ne ha bisogno. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Valore restituito

NewSubKey restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo nell'output di un puntatore IRegistryKey valido tramite il parametro RegistrySubKey . In caso contrario, il metodo restituisce un codice di errore appropriato.

Commenti

Se esiste già, il NewSubKey metodo apre la chiave del Registro di sistema specificata oppure crea una nuova chiave nel Registro di sistema, se non esiste. Il metodo restituisce un puntatore all'interfaccia IRegistryKey della nuova chiave tramite il parametro RegistrySubKey . Il metodo restituisce anche un valore di stato tramite il parametro Disposition facoltativo per indicare se la chiave è stata aperta o creata.

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

Il parametro DesiredAccess è una maschera di controllo di accesso che specifica il tipo di controllo di accesso necessario al chiamante per l'accesso tramite l'oggetto RegistrySubKey . Questa maschera non deve essere confusa con l'elenco di controllo di accesso (ACL) che controlla l'accesso da parte degli utenti alla sottochiave del Registro di sistema. Quando il metodo PcNewRegistryKey o IPort::NewRegistryKey crea 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. Quando il NewSubKey metodo crea una nuova sottochiave del Registro di sistema, tuttavia, tale sottochiave eredita semplicemente l'ACL dalla chiave padre. Il NewSubKey metodo non fornisce alcun mezzo per specificare un elenco di controllo di accesso diverso da quello della chiave padre.

I parametri RegistrySubKey ed OuterUnknown seguono le convenzioni di conteggio dei riferimenti per gli oggetti COM.