22.2 _winreg - Accesso al registro di Windows

Disponibilità: Windows.

Nuovo nella versione 2.0.

Queste funzioni rendono disponibili le API del registro di Windows a Python. Anziché utilizzare un intero come gestore del registro, viene utilizzato un oggetto gestore per assicurare che i gestori siano chiusi correttamente, anche se il programmatore si dimentica di chiuderli esplicitamente.

Questo modulo rende disponibile un'interfaccia di basso livello al registro di Windows; nel futuro è atteso un nuovo modulo winreg che fornisca un'interfaccia di alto livello alle API del registro.

Questo modulo offre le seguenti funzioni:

CloseKey( hkey)
Chiude una chiave di registro precedentemente aperta. L'argomento hkey specifica la chiave precedentemente aperta.

Notare che hkey non permette di chiudere la chiave di registro se hkey è ancora attiva (handle.Close() chiude la chiave di registro quando l'oggetto hkey viene distrutto da Python).

ConnectRegistry( computer_name, key)
Stabilisce una connessione ad un gestore di registro predefinito su un'altro computer e restituisce l'oggetto gestore.

computer_name è il nome del computer remoto, nella forma r"\\computername". Se None, viene utilizzato il computer locale.

key è il gestore predefinito a cui connettersi.

Il valore restituito è il gestore della chiave aperta. Se la funzione fallisce, viene sollevata l'eccezione EnvironmentError.

CreateKey( key, sub_key)
Crea o apre la specifica chiave, restituendo l'oggetto gestore.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

sub_key è una stringa che indica la chiave che viene aperta o creata da questo metodo.

Se key è una delle chiavi predefinite, sub_key può essere None. In questo caso, il gestore restituito è lo stesso gestore della chiave passato alla funzione.

Se key esiste, questa funzione apre la chiave esistente.

Il valore restituito è il gestore della chiave aperta. Se la funzione fallisce, viene sollevata l'eccezione EnvironmentError.

DeleteKey( key, sub_key)
Cancella la chiave specifica.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

sub_key è la stringa che deve essere una sottochiave della chiave identificata dal parametro key. Questo valore non deve essere None e la chiave può non avere sottochiavi.

Questo metodo non può cancellare chiavi con sottochiavi.

Se il metodo ha successo, l'intera chiave, inclusi tutti i suoi valori, vengono cancellati. Se il metodo fallisce, viene sollevata un'eccezione di tipo EnvironmentError.

DeleteValue( key, value)
Cancella un valore da una chiave di registro.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

value è una stringa che identifica il valore da rimuovere.

EnumKey( key, index)
Numera le sottochiavi di una chiave di registro aperta, restituendo una stringa.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

index è un intero the identifica l'indice della chiave da recuperare.

La funzione restituisce il nome di una delle sottochiavi ogni volta che viene chiamata. Viene tipicamente chiamata ripetutamente finché non viene sollevata un'eccezione EnvironmentError, ad indicare che non ci sono più valori disponibili.

EnumValue( key, index)
Numera i valori di una chiave di registro aperta, restituendo una tupla.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

index è un intero the identifica l'indice del valore da restituire.

La funzione recupera il nome di una sottochiave ogni volta che viene chiamata. Viene tipicamente chiamata ripetutamente finché non viene sollevata un'eccezione di tipo EnvironmentError, ad indicare che non ci sono più valori disponibili.

Il risultato è una tupla di 3 elementi:

Indice  Significato 
0 Una stringa che identifica il nome del valore
1 Un oggetto che contiene i dati del valore il cui tipo dipende dal tipo di registro sottostante
2 Un intero che identifica il tipo dei dati del valore

FlushKey( key)
Scrive tutti gli attributi di una chiave nel registro.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

Non è necessario chiamare RegFlushKey per cambiare una chiave. I cambiamenti nel registro vengono salvati su disco dal registro utilizzando il suo pigro sistema di flush. Al contrario di CloseKey(), il metodo FlushKey() restituisce tutti i suoi dati quando questi sono stati scritti nel registro. Un'applicazione deve chiamare FlushKey() solo se deve essere assolutamente certa che i cambiamenti siano stati salvati su disco.

Se non si è sicuri che la chiamata a FlushKey() sia necessaria, probabilmente non lo è.

RegLoadKey( key, sub_key, file_name)
Crea una sottochiave sotto la specifica chiave ed immagazzina le informazioni di registrazione da uno specifico file nella sottochiave.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

sub_key è una stringa che identifica la sottochiave da caricare.

file_name è il nome del file da cui caricare i dati del registro. Questo file deve essere stato creato con la funzione SaveKey(). Su un file system FAT (file allocation table), il nome del file può non avere un'estensione.

Una chiamata a LoadKey() fallisce se il processo chiamante non ha il privilegio SE_RESTORE_PRIVILEGE. Notare che i privilegi sono diversi dai permessi - vedere la documentazione di Win32 per maggiori dettagli al riguardo.

Se la chiave key è un gestore restituito da ConnectRegistry(), il percorso specificato in fileName è relativo al computer remoto.

La documentazione di Win32 dà per scontato che key debba essere nell'albero di HKEY_USER o HKEY_LOCAL_MACHINE. Questo può essere o non essere vero.

OpenKey( key, sub_key[, res = 0][, sam = KEY_READ])
Apre una chiave specifica, restituendo un oggetto gestore.

key è una chiave già aperta, oppure una delle costanti predefinite HKEY_*.

sub_key è una stringa che identifica la sottochiave da aprire.

res è un intero riservato e deve essere zero. Il valore predefinito è zero.

sam è un intero che specifica una maschera di accesso che descrive l'accesso di sicurezza desiderato per la chiave. Il valore predefinito è KEY_READ.

Il risultato è un nuovo gestore per la specifica chiave.

Se la funzione fallisce, viene sollevata un'eccezione EnvironmentError.

OpenKeyEx( )
Le funzionalità di OpenKeyEx() vengono fornite da OpenKey(), utilizzando gli argomenti predefiniti.

QueryInfoKey( key)
Restituisce informazioni su una chiave, sotto forma di tuple.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

Il risultato è una tupla di 3 elementi:

Indice  Significato 
0 Un intero che fornisce il numero di sottochiavi della chiave corrente.
1 Un intero che fornisce il numero di valori di questa chiave.
2 Un intero long che indica la data di modifica della chiave, espressa in centinaia di nanosecondi dal primo gennaio 1970.

QueryValue( key, sub_key)
Restituisce informazioni su una chiave, sotto forma di stringa.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

sub_key è una stringa che contiene il nome della sottochiave con il valore associato. Se questo parametro ha come valore None o è vuoto, la funzione recupera il valore impostato dal metodo SetValue() per la chiave identificata da key.

I valori nel registro hanno nome, tipo e dati componenti. Questo metodo recupera i dati per il primo valore della chiave che ha come nome NULL. Ma la chiamata alle API sottostanti non restituiscono il tipo, NON USARE!!!

QueryValueEx( key, value_name)
Restituisce il tipo e i dati di uno nome di un valore specificato, associato ad una chiave di registro aperta.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

value_name è una stringa che indica il valore da interrogare.

Il risultato è una tupla di 2 elementi:

Indice  Significato 
0 Il valore dell'elemento del registro.
1 Un intero che specifica il tipo del registro per questo valore.

SaveKey( key, file_name)
Salva la chiave specificata e tutte le sue sottochiavi nel file specificato.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

file_name è il nome del file in cui salvare i dati del registro. Questo file non può esistere. Se il nome del file include un'estensione, non può essere utilizzato in un file system FAT dai metodi LoadKey(), ReplaceKey() o RestoreKey().

Se key rappresenta una chiave su un computer remoto, il percorso descritto da file_name è relativo al computer remoto. Il chiamante di questo metodo deve avere il privilegio di sicurezza SeBackupPrivilege. Notare che i privilegi sono diversi dai permessi - vedere la documentazione di Win32 per maggiori dettagli.

Questa funzione passa NULL come security_attributes alle API.

SetValue( key, sub_key, type, value)
Associa un valore con la chiave specificata.

key è una chiave aperta oppure una delle costanti predefinite HKEY_*.

sub_key è una stringa che identifica la sottochiave a cui è associato il valore.

type è un intero che specifica il tipo dei dati. Attualmente questo deve essere REG_SZ, a significare che solo le stringhe vengono supportate. Utilizzare la funzione SetValueEx() per supportare altri tipi di dati.

value è una stringa che specifica il nuovo valore.

Se la chiave specificata dal parametro sub_key non esiste, la funzione SetValue() la crea.

La lunghezza dei valori è limitata dalla memoria disponibile. I valori lunghi (più di 2048 byte) devono essere immagazzinati come file, con il nome del file immagazzinato nel registro di configurazione. Questo aiuta il registro ad essere efficiente.

La chiave identificata dal parametro key deve essere aperta con accesso KEY_SET_VALUE.

SetValueEx( key, value_name, reserved, type, value)
Immagazzina dati nel campo valore di una chiave aperta.

key è una chiave già aperta oppure una delle costanti predefinite HKEY_*.

sub_key è una stringa che indica la sottochiave a cui il valore è associato.

type è un intero che specifica il tipo dei dati. Questo deve essere una delle seguenti costanti definite in questo modulo:

Costanti  Significato 
REG_BINARY Dati binari in qualunque forma.
REG_DWORD Un numero a 32-bit.
REG_DWORD_LITTLE_ENDIAN Un numero a 32 bit in formato little-endian.
REG_DWORD_BIG_ENDIAN Un numero a 32 bit in formato big-endian.
REG_EXPAND_SZ Una stringa null-terminata contenente un riferimento alle variabili d'ambiente ("%PATH%").
REG_LINK Un link simbolico Unicode.
REG_MULTI_SZ Una sequenza di stringhe null-terminate, terminate da due caratteri null. Python gestisce queste terminazioni automaticamente.
REG_NONE Nessun tipo di valore definito.
REG_RESOURCE_LIST Una lista di risorse di dispositivi-driver.
REG_SZ Una stringa null-terminata.

reserved può essere qualsiasi cosa; il valore zero viene sempre passato alle API.

value è una stringa che specifica il nuovo valore.

Questo metodo può anche impostare ulteriori valori e tipi di informazioni per la chiave specifica. La chiave identificata dal parametro key deve essere stata aperta con l'accesso KEY_SET_VALUE.

Per aprire la chiave, utilizzare i metodi CreateKeyEx() o OpenKey().

Le lunghezze dei valori vengono limitate dalla memoria disponibile. I valori lunghi (più di 2048 bytes) devono essere immagazzinati come file, il cui nome verrà immagazzinato nel registro di configurazione. Questo aiuta il registro ad operare in modo efficiente.



Subsections
Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.