| Win32::TieRegistry - des méthodes simples et puissantes pour manipuler le Registre [sur Win32 actuellement]. |
tie())use et import()]
Win32::TieRegistry - des méthodes simples et puissantes pour manipuler le Registre [sur Win32 actuellement].
use Win32::TieRegistry 0.20 ( UseOptionName=>UseOptionValue[,...] );
$Registry->SomeMethodCall(arg1,...);
$subKey= $Registry->{"Key\\SubKey\\"};
$valueData= $Registry->{"Key\\SubKey\\\\ValueName"};
$Registry->{"Key\\SubKey\\"}= { "NewSubKey" => {...} };
$Registry->{"Key\\SubKey\\\\ValueName"}= "NewValueData";
$Registry->{"\\ValueName"}= [ pack("fmt",$data), REG_DATATYPE ];
use Win32::TieRegistry( Delimiter=>"#", ArrayValues=>0 );
$pound= $Registry->Delimiter("/");
$diskKey= $Registry->{"LMachine/System/Disk/"}
or die "Can't read LMachine/System/Disk key: $^E\n";
$data= $key->{"/Information"}
or die "Can't read LMachine/System/Disk//Information value: $^E\n";
$remoteKey= $Registry->{"//ServerA/LMachine/System/"}
or die "Can't read //ServerA/LMachine/System/ key: $^E\n";
$remoteData= $remoteKey->{"Disk//Information"}
or die "Can't read ServerA's System/Disk//Information value: $^E\n";
foreach $entry ( keys(%$diskKey) ) {
...
}
foreach $subKey ( $diskKey->SubKeyNames ) {
...
}
$diskKey->AllowSave( 1 );
$diskKey->RegSaveKey( "C:/TEMP/DiskReg", [] );
Le module Win32::TieRegistry vous permet de manipuler le Registre via des objets [interface «orientée objet»] ou via des hachages liés (par tie()). Mais vous utiliserez probablement la plupart du temps une référence à une combinaison des deux, c'est-à-dire une référence à un hachage lié qui a aussi été fait objet afin que vous puissiez mélanger les deux méthodes d'accès [comme montré ci-dessus].
Si vous n'avez pas obtenu ce module comme partie de libwin32, vous devriez obtenir une version récente de libwin32 du CPAN qui devrait inclure ce module et le module Win32API::Registry qu'il utilise.
Sautez directement à la section RÉSUMÉ si vous voulez vous jeter à l'eau et commencer à utiliser le Registre depuis Perl.
Accéder au Registre et le manipuler est extrêmement simple en utilisant Win32::TieRegistry. Une seule expression simple peut vous donner presque toute parcelle d'information stockée dans le Registre. Win32::TieRegistry vous donne aussi le plein accès aux fonctions brutes sous-jacentes de l'API afin que vous puissiez faire sur le Registre en Perl tout ce que vous pouvez faire en C. Mais l'interface «simple» a été soigneusement conçue pour manier elle-même presque toutes les opérations sans imposer de limite arbitraire, tout en fournissant des valeurs par défaut commodes de telle manière que vous n'ayez qu'a préciser les paramètres dont vous vous préoccupez.
Mais d'abord, une vue d'ensemble du Registre.
Le Registre est une forêt : une collection de plusieurs arborescences. La racine de chaque arbre est une clef. Ces clefs racines sont identifiées par des constantes prédéfinies dont les noms commencent par «HKEY_». Bien que toutes les clefs aient quelques attributs associés [une classe, un timbre horaire, et une information de sécurité], l'aspect le plus important des clefs est que chacune peut contenir des sous-clefs et peut contenir des valeurs.
Chaque sous-clef a un nom : une chaîne qui ne peut pas être vide et qui ne peut contenir
ni le caractère du délimiteur [backslash: '\\'] ni le caractère nul ['\0'].
Chaque sous-clef est aussi une clef et donc peut contenir des sous-clefs et des valeurs
[et une classe, un timbre horaire, et une information de sécurité]
Chaque valeur a un nom : une chaîne qui peut être vide et peut contenir
le caractère délimiteur [backslash: '\\'] et tout caractère à l'exception du
caractère nul '\0'. Chaque valeur a aussi une donnée associée. Chaque donnée
associée à une valeur est une succession d'octets contigus, ce qui est exactement
ce qu'est une valeur de chaîne pour Perl; donc les chaînes de Perl seront utilisées
pour représenter la donnée d'une valeur.
Chaque valeur a aussi un type de donnée qui précise comment interpréter la donnée de la valeur. Les types de donnée d'origine sont:
'%'], un nom de variable d'environnement puis un signe pour cent et qui
doit être remplacé par la valeur associée à cette variable d'environnement.
Le système ne fait pas automatiquement cette substitution.
Si votre système a le module SetDualVar installé, l'option DualBinVals()
non désactivée et si vous allez chercher une valeur REG_BINARY de 4 octets
ou moins, alors vous pouvez utiliser la valeur retournée dans un contexte numérique
pour obtenir la valeur numérique «désempaquetée».
Voir GetValue() pour plus d'information.
'\0'
supplémentaire à la fin de la liste. Notez que la liste peut inclure des
chaînes vides, donc utilisez la longueur de la valeur pour déterminer la
fin de la liste, et non pas la première occurrence de '\0\0'.
Il est préférable de mettre l'option SplitMultis() de manière que
Win32::TieRegistry éclate ces valeurs dans un tableau de chaînes pour vous.
La manière dont de telles valeurs sont interprétées dépend des options
DualBinVals() et DWordsToHex(). Voir GetValue() pour les détails.
Dans les appels sous-jacents du Registre, la plupart des endroits qui demande
un nom de sous-clef permettent aussi de passer un chemin de sous-clef -- une chaîne
de plusieurs noms de sous-clefs séparés par le caractère délimiteur, backslash ['\\'].
Par exemple, faire RegOpenKeyEx(HKEY_LOCAL_MACHINE,"SYSTEM\\DISK",...) est comme
ouvrir la sous-clef "SYSTEM" de HKEY_LOCAL_MACHINE, puis ouvrir
sa sous-clef "DISK", puis fermer la sous-clef "SYSTEM".
Toutes les fonctions de Win32::TieRegistry vous permettent d'utiliser
votre propre caractère délimiteur à la place du délimiteur système ['\\'].
Dans la plupart de nos exemples, nous utiliserons un slash normal ['/']
pour notre délimiteur car il facilite la lecture et limite les erreurs dans
l'écriture du code Perl puisque vous êtes obligés de mettre deux backslashes
pour chaque backslash que vous voulez dans une chaîne.
Notez que c'est vrai même quand on utilise les guillemets simples --
'\\HostName\LMachine\' est une chaîne non valide; elle doit être écrite
'\\\\HostName\\LMachine\\'.
Vous pouvez aussi vous connecter au Registre d'un autre ordinateur de votre réseau. Ceci sera expliqué en détails plus tard.
Bien que le Registre n'aie pas de clef racine simple, le module Win32::TieRegistry crée une clef racine virtuelle pour vous qui a toutes les clefs HKEY_* comme sous-clefs.
tie())Avant que vous puissiez utiliser un hachage lié, vous devez en créer un. Une manière de faire cela est :
use Win32::TieRegistry ( TiedHash => '%RegHash' );
qui exporte une variable %RegHash dans votre paquetage et la lie (avec tie())
à la clef de la racine virtuelle du Registre. Une autre méthode est :
my %RegHash;
use Win32::TieRegistry ( TiedHash => \%RegHash );
Il y a aussi plusieurs manières de lier un hachage à toute autre clef du Registre, qui seront examinées plus tard.
Notez que vous utiliserez très probablement $Registry au lieu d'utiliser
un hachage lié. $Registry est une référence à un hachage
qui a été liée à la clef de la racine virtuelle du Registre de votre ordinateur
[comme si $Registry= \%RegHash]. Donc vous pouvez utiliser $Registry->{Key}
plutôt que $RegHash{Key} et keys %{$Registry} plutôt que keys %RegHash,
par exemple.
Pour chaque hachage qui a été lié à une clef de Registre, la fonction
Perl keys retournera une liste contenant tous les noms des sous-clefs de la
clef avec un caractère délimiteur ajouté à la fin et contenant le nom de chacune
des valeurs de la clef avec un caractère délimiteur ajouté au début.
Par exemple :
keys( %{ $Registry->{"HKEY_CLASSES_ROOT\\batfile\\"} } )
pourra produire la liste suivante :
( "DefaultIcon\\", # La sous-clef nommée "DefaultIcon"
"shell\\", # La sous-clef nommée "shell"
"shellex\\", # La sous-clef nommée "shellex"
"\\", # La valeur par défaut [nommée ""]
"\\EditFlags" ) # La valeur nommée "EditFlags"
Pour la clef de la racine virtuelle, des noms abrégés de sous-clefs sont utilisés
comme indiqué ci-dessous. Vous pouvez utiliser le nom abrégé, le nom habituel
HKEY_*, ou toute valeur numérique pour accéder à ces clefs, mais ce sont toujours
les noms abrégés qui seront retournés par la fonction keys.
"SOFTWARE\\Classes" de la clef
HKEY_LOCAL_MACHINE.
HKEY_USERS.
".DEFAULT", qui est copiée comme nouvelle
sous-clef toutes les fois qu'un nouvel utilisateur est ajouté. Contient aussi
une sous-clef pour chaque utilisateur du système, bien que seules celles des
utilisateurs actifs [habituellement un seul] soient chargées à un moment donné.
ERROR_INSUFFICIENT_BUFFER. Par exemple, vous ne pouvez énumérer les noms des
clefs sans énumérer aussi les valeurs qui requièrent des tampons énormes; mais
la dimension exacte d'un tampon ne peut pas être obtenue au préalable parce que
RegQueryInfoKey() échoue toujours avec le message ERROR_INSUFFICIENT_BUFFER
pour HKEY_PERFORMANCE_DATA, quelle que soit la manière dont on fait l'appel.
Donc ce n'est pas très utile actuellement d'attacher un hash à cette clef.
Vous pouvez l'employer pour créer un objet à utiliser pour faire des appels
construits soigneusement avec les routines sous-jacentes Reg*().
[Utilisez le module Win32::PerfLib dans ce cas. NdT]
Un hachage lié est comme une variable hachage normale en Perl
-- vous lui donnez une chaîne clef entre accolades, [{ et }], et il vous
donne en retour une valeur [ou vous laisse mettre une valeur]. Pour les hachages
de Win32::TieRegistry , il y a deux types de valeurs qui seront retournées.
[0] et le type de la données est l'élément [1].
La chaîne clef que vous utilisez dans le hachage lié doit être interprétée pour déterminer si c'est un nom de valeur ou un nom de clé ou un chemin qui combinent plusieurs de celles-ci ou même encore autre chose. Il y a deux règles simples qui rendent cette interprétation facile et non équivoque:
Mettez un délimiteur après chaque nom clé.
Mettez un délimiteur devant chaque nom de valeur.
La manière dont la chaîne clef sera interprétée est gouvernée par les règles suivantes, dans l'ordre de leur énumération. Ces règles sont conçues pour «faire ce que vous avez eu l'intention de faire». La plupart du temps, vous n'aurez pas à penser à elles, surtout si vous suivez les deux règles simples précédentes. Après la liste des règles, nous donnons plusieurs exemples qui devraient être assez clairs, donc vous êtes libre de sauter à eux à moins que vous ne vous inquiétiez des détails.
Si la chaîne clef du hachage commence avec deux délimiteurs à la suite, alors ils devraient être suivis par le nom d'une machine distante au Registre de laquelle nous souhaitons nous connecter. Il peut y avoir à la suite un délimiteur et plusieurs autres noms de sous-clefs, etc. Si rien ne suit le nom de la machine, alors une racine virtuelle pour le Registre de la machine distante est créée, un hachage est lié à elle, et une référence à ce hachage est retournée.
"LMachine", une valeur HKEY_*, ou une valeur numérique].
Cette notation alternative est permise de manière à être plus de consistant avec la
méthode Open().
Pour toutes les autres clefs du Registre, le délimiteur de tête indique que le reste de la chaîne est un nom de valeur. Le délimiteur de tête est ôté et le reste de la chaîne [lequel peut être vide et peut contenir plusieurs délimiteurs] est utilisé comme un nom de valeur sans pousser l'analyse plus loin.
keys sur le hachage lié [ou si vous
avez appelé MemberNames sur l'objet] et si la chaîne clef de hachage correspond
exactement à l'une des chaînes retournées, alors l'analyse n'est pas poussée plus
loin. En d'autres termes, si la chaîne clef correspond exactement au nom d'une
sous-clef avec un délimiteur à la fin, alors une référence à un hachage attaché à
cette sous-clef est retournée [mais seulement si keys ou MemberNames a déjà été
appelé auparavant sur ce hachage lié].
Ceci est important seulement si vous avez sélectionné un délimiteur autre que le délimiteur système par défaut et que l'un des noms de sous-clef contient le délimiteur que vous avez choisi. Cette règle vous permet de travailler avec des sous-clefs qui contiennent dans leur nom le délimiteur que vous avez choisi, aussi longtemps que vous traversez seulement les sous-clefs un niveau à la fois et toujours en énumérant la liste de membres avant.
Le principal avantage de cela est que tout code Perl qui traverse récursivement un hachage travaillera sur des hachages liés aux clefs de Registre, même si un délimiteur différent de celui par défaut a été sélectionné.
Si vous lisez le hachage [fetching], alors nous utilisons d'abord
la chaîne clef comme un nom de valeur. S'il y a une valeur avec un nom correspondant
dans la clef du Registre auquel le hachage est lié, alors les données de la valeur
[et éventuellement le type des données] sont retournées. Sinon, nous essayons à nouveau
en utilisant la chaîne clef du hachage comme un nom de sous-clef. S'il y a une
sous-clef avec un nom correspondant, alors nous renvoyons une référence à un hachage
lié à cette sous-clef. Sinon nous retournons undef.
Si vous écrivez dans le hachage [storing], alors nous utilisons la chaîne clef comme un nom de sous-clef seulement si la valeur que vous enregistrez est une référence à une valeur de hachage. Sinon nous utilisons la chaîne clef comme un nom de valeur.
On trouvera ici quelques exemples montrant les différentes manières d'accéder à l'information contenue dans le Registre en utilisant des références à des hachages liés :
$tip18= $Registry->{"HKEY_LOCAL_MACHINE\\Software\\Microsoft\\"
. 'Windows\\CurrentVersion\\Explorer\\Tips\\\\18'};
Doit retourner le texte du «conseil important» numéro 18. Notez que deux backslashes,
"\\", sont exigés pour mettre un seul backslash dans une chaîne Perl entre
guillemets simples (') ou doubles ("). Notez que "\\" est ajouté à chaque
nom de clé [de "HKEY_LOCAL_MACHINE" jusqu'à "Tips"] et "\\" est préfixé
au nom de la valeur, "18".
$Registry->Delimiter("/");
$tip18= $Registry->{"HKEY_LOCAL_MACHINE/Software/Microsoft/"
. 'Windows/CurrentVersion/Explorer/Tips//18'};
Cela rend la lecture beaucoup plus facile. Dans tout le reste des exemples, on suppose que le délimiteur a été changé comme ci-dessus.
$ms= $Registry->{"LMachine/Software/Microsoft/"};
$tips= $ms->{"Windows/CurrentVersion/Explorer/Tips/"};
$tip18= $tips->{"/18"};
Fait la même chose que ci-dessus, mais ouvre plus de clefs de Registre, ce qui vous permet de réutiliser ces clefs intermédiaires efficacement. C'est légèrement moins efficace si vous ne réutilisez jamais ces clefs intermédiaires.
$tip18= $Registry->{"LMachine/Software/Microsoft/"}->
{"Windows/CurrentVersion/Explorer/Tips/"}->{"/18"};
Comme au-dessus, cela crée des objets clefs intermédiaires puis les utilise pour accéder à d'autres données. Une fois cette instruction finie, les objets clefs intermédiaires sont détruits. Plusieurs descripteurs dans le Registre sont ouverts et sont fermés par cette déclaration, donc c'est moins efficace, mais il y a des cas ou c'est utile.
$tip18= $Registry->{"LMachine/Software/Microsoft"}->
{"Windows/CurrentVersion/Explorer/Tips"}->{"/18"};
Parce que nous avons omis les délimiteurs de fin, Win32::TieRegistry ne sait pas
si les noms finaux, "Microsoft" et "Tips", sont des noms de sous-clefs ou des
noms de valeurs. Donc cette déclaration finit par exécuter le même code que l'exemple
suivant.
$tip18= $Registry->{"LMachine/Software/"}->{"Microsoft"}->
{"Windows/CurrentVersion/Explorer/"}->{"Tips"}->{"/18"};
Avec plus de chaînes a parcourir, plus d'objets temporaires sont créés et ensuite
détruits que dans notre premier exemple de chaînage. Aussi, quand "Microsoft" est
cherché Win32::TieRegistry essaie en premier de l'ouvrir comme une valeur et échoue
puis essaie de l'ouvrir comme une sous-clef. La même chose se passe quand il
traite "Tips".
$tips= $Registry->{"LMachine/Software/Microsoft/"}->
{"Windows/CurrentVersion/Explorer/Tips/"}
or die "Impossible de trouver les conseils Windows : $^E\n";
foreach( keys %$tips ) {
print "$_: ", $tips->{$_}, "\n";
}
Notez d'abord que, pour la première fois, nous vérifions s'il y a échec.
Nous supposons que la clef "Tips" ne contient aucune sous-clef. Sinon
l'instruction print afficherait quelque chose comme
"Win32::TieRegistry=HASH(0xc03ebc)" pour chaque sous-clef.
La sortie du code ci-dessus commencera par quelque chose comme :
/0: Si vous ignorez comment effectuer une opération, [...]
Vous pouvez utiliser la fonction Perl delete pour effacer une valeur d'une clef
de Registre ou pour effacer une sous-clef si cette sous-clef ne contient aucune sous-clef
elle-même. Voyez Plus d'Exemples, en dessous, pour davantage d'information.
Vous pouvez utiliser l'opérateur Perl d'assignation [=] pour créer de nouvelles clefs,
créer de nouvelles valeurs, ou remplacer des valeurs. Les valeurs que vous enregistrez
doivent être dans le même format que les valeurs que vous iriez chercher dans le hachage
lié. Par exemple, vous pouvez utiliser une seule instruction d'affectation pour copier
en entier un arbre du Registre. La déclaration suivante:
$Registry->{"LMachine/Software/Classes/Tie_Registry/"}=
$Registry->{"LMachine/Software/Classes/batfile/"};
crée une sous-clef "Tie_Registry" dans la sous-clef "Software\\Classes"
de la clef HKEY_LOCAL_MACHINE. Puis il la remplit avec des copies
de toutes les sous-clefs et valeurs contenues dans la clef "batfile" et toutes
ses sous-clefs. Notez que vous devez avoir appelé $Registry->ArrayValues(1)
pour que l'information sur le bon type de donnée soit copié.
Notez aussi que cette version de Win32::TieRegistry ne copie pas les attributs
des clefs tels que nom de classe et information de sécurité [cela est prévu pour une
future version].
L'instruction suivante crée un sous-arbre entier dans le Registre :
$Registry->{"LMachine/Software/FooCorp/"}= {
"FooWriter/" => {
"/Version" => "4.032",
"Startup/" => {
"/Title" => "Foo Writer Deluxe ][",
"/WindowSize" => [ pack("LL",$wid,$ht), "REG_BINARY" ],
"/TaskBarIcon" => [ "0x0001", "REG_DWORD" ],
},
"Compatibility/" => {
"/AutoConvert" => "Always",
"/Default Palette" => "Windows Colors",
},
},
"/License", => "0123-9C8EF1-09-FC",
};
Notez que tout sauf la dernière clef du Registre utilisée du côté gauche de l'assignement [c'est-à-dire, «LMachine/Software/» mais non «FooCorp/»] doit déjà exister pour que cette instruction réussisse.
En mettant un délimiteur au début ou à la fin de chaque nom de sous-clef ou nom de valeur, Win32::TieRegistry vous dira si vous essayez d'assigner de l'information d'une sous-clef à une valeur ou vice versa.
$tips= $Registry->{"LMachine/Software/Microsoft/"}->
{"Windows/CurrentVersion/Explorer/Tips/"}
or die "Impossible de trouver les conseils de Windows : $^E\n";
$tips{'/186'}= "Soyez très prudent quand vous faites des changements dans le Registre !";
$tips= $Registry->{"LMachine/Software/Microsoft/"}->
{"Windows/CurrentVersion/Explorer/Tips/"}
or die "Impossible de trouver les conseils de Windows : $^E\n";
$tip186= delete $tips{'/186'};
Notez que la fonction Perl delete retourne la valeur qui a été effacée.
$Registry->{"LMachine/Software/Microsoft/" .
"Windows/CurrentVersion/Explorer/Tips//186"}=
"Soyez très prudent quand vous faites des changements dans le Registre !";
$tip186= delete $Registry->{"LMachine/Software/Microsoft/Windows/" .
"CurrentVersion/Explorer/Tips//186"};
Notez que cela efface seulement la fin de ce que nous recherchons, la
valeur "186", et non pas toutes les clefs listées.
$tips= delete $Registry->{"CUser/Software/Microsoft/Windows/" .
"CurrentVersion/Explorer/Tips/"};
Cela efface la clef "Tips" des conseils Windows ("Tips") et les valeurs
qu'elle contient. La fonction delete retournera une référence à un hachage
[et non pas un hachage lié] contenant les noms de valeur et données de valeur
qui ont été effacées.
L'information qui doit être retournée est copiée du Registre dans un hachage Perl
normal avant que la clef soit effacée. Si la clef a beaucoup de sous-clefs, cette
copie peut prendre une quantité significative de mémoire et/ou de temps du processeur.
Aussi, vous pouvez mettre hors fonction ce processus en appelant la fonction membre
FastDelete :
$prevSetting= $regKey->FastDelete(1);
laquelle entraînera que toutes les opérations ultérieures d'effacement via $regKey
retourneront simplement une valeur vraie si elle réussissent. Cette optimisation
est faite automatiquement si vous utilisez delete dans un contexte vide.
delete pour effacer une clef ou une valeur du Registre et récupérez
la valeur de retour, alors Win32::TieRegistry recherche habituellement le contenu
courant de cette clef ou valeur, donc il peut la retourner si la suppression est réussie.
Si l'effacement réussit mais que la tentative de recherche du contenu ancien a échoué,
alors la valeur de retour de delete sera $^E pour la partie manquée de l'opération.
$Registry->{"LMachine/Software/Microsoft/Windows/" .
"CurrentVersion/Explorer/Tips/"}= $tips;
Cela rétablit ce que nous avons effacé juste avant. Notez que cette version de Win32::TieRegistry utilisera les valeurs par défaut pour les attributs des clefs [tel que nom de classe et sécurité] et ne restaurera pas les attributs antérieurs.
$res= delete $Registry->{"CUser/Software/Microsoft/Windows/"}
defined($res) || die "Can't delete URL key: $^E\n";
Puisque la clef «Windows» doit contenir des sous-clefs, cette instruction
delete ne doit pas faire de changements dans le Registre, retourner undef,
et fixer $^E à «Accès refusé».
$tips= $Registry->{"CUser/Software/Microsoft/Windows/" .
"CurrentVersion/Explorer/Tips/"};
delete $tips;
La fonction Perl delete exige que son argument soit une expression qui
se termine par la détermination d'un l'élément du hachage [ou une tranche du
hachage], ce qui n'est pas le cas ici. La fonction delete ne sait pas
d'où le hachage $tips provient et donc ne peut pas l'effacer.
Les fonctions membres suivantes sont définies pour être utilisées sur des objets Win32::TieRegistry :
new crée un nouvel objet Win32::TieRegistry.
new est essentiellement un synonyme de Open() donc voyez
Open() plus bas pour des informations sur les arguments qu'on peut
lui passer. Exemples:
$machKey= new Win32::TieRegistry "LMachine"
or die "Can't access HKEY_LOCAL_MACHINE key: $^E\n";
$userKey= Win32::TieRegistry->new("CUser")
or die "Can't access HKEY_CURRENT_USER key: $^E\n";
Notez que l'appel de new par une référence à un hachage lié retourne
un objet simple, et non une référence à un hachage lié.
Open ouvre une clef de Registre et retourne un nouvel objet
Win32::TieRegistry associé à cette clef de Registre. Si Open est appelé
par une référence à un hachage lié, alors Open renvoie une autre référence
à un hachage lié. Sinon, Open retourne un objet simple et vous devrez alors
utiliser TiedRef pour obtenir une référence à un hachage lié.
$sSubKey est une chaîne qui spécifie la sous-clef à ouvrir. Alternativement
$sSubKey peut être une référence à un tableau qui contient la liste des
sous-clefs de niveau de plus en plus profond qui spécifie le chemin à la
sous-clef qui doit être ouverte.
$rhOptions est une référence facultative à un hachage qui contient des options
supplémentaires. La méthode Open supporte deux options, "Delimiter" et
"Access", et $rhOptions doit avoir seulement zéro ou plus de ces chaînes
comme clefs. Voir la section «Exemples» plus bas pour plus d'information.
L'option "Delimiter" spécifie quelle chaîne [habituellement un unique caractère]
sera utilisé comme délimiteur ajouté à la fin des noms de sous-clefs et au
début des noms de valeurs. Si cette option n'est pas spécifiée, la nouvelle clef
[$subKey] hérite du délimiteur de l'ancienne clef [$key].
L'option "Access" spécifie le niveau d'accès à la clef du Registre
que vous souhaitez avoir une fois qu'elle est ouverte. Si cette option n'est
pas spécifiée, la nouvelle clef [$subKey] est ouverte avec le même niveau
d'accès que celui utilisé quand l'ancienne clef [$key] a été ouverte.
La racine virtuelle du Registre fait comme si elle avait été ouverte avec
l'accès KEY_READ()|KEY_WRITE() donc c'est l'accès par défaut quand on
ouvre un répertoire de clefs avec $Registry. Si vous ne projetez pas
de modifier une clef, vous devriez l'ouvrir avec l'accès KEY_READ puisque
vous n'avez pas besoin de l'accès KEY_WRITE sur elle ou l'une de
ses sous-clefs.
Si la valeur de l'option "Access" est une chaîne qui commence par "KEY_",
alors il devrait correspondre à un des niveaux d'accès prédéfinis
[probablement "KEY_READ", "KEY_WRITE", ou "KEY_ALL_ACCESS"]
exporté par le module Win32API::Registry. Sinon, une valeur numérique
est attendue. Pour une flexibilité maximale, incluez
use Win32::TieRegistry qw(:KEY_);, au début de votre script par exemple,
comme cela vous pourrez spécifier des niveaux d'accès plus compliqués tels que
KEY_READ()|KEY_WRITE().
Si $sSubKey ne commence pas avec le délimiteur [ou si $sSubKey est
une référence à un tableau], alors le chemin vers cette sous-clef à ouvrir
sera relatif au chemin de la clef originale [$key]. Si $sSubKey
commence avec un délimiteur unique, alors le chemin vers la sous-clef à
ouvrir sera relatif à la racine virtuelle du Registre sur n'importe quelle
machine où la clef originale réside. Si $sSubKey commence avec deux
délimiteurs consectutifs, alors ils doivent être suivis par un nom de
machine qui entraînera un appel à la méthode Connect().
Exemples:
$machKey= $Registry->Open( "LMachine", {Access=>KEY_READ(),Delimiter=>"/"} )
or die "Can't open HKEY_LOCAL_MACHINE key: $^E\n";
$swKey= $machKey->Open( "Software" );
$logonKey= $swKey->Open( "Microsoft/Windows NT/CurrentVersion/Winlogon/" );
$NTversKey= $swKey->Open( ["Microsoft","Windows NT","CurrentVersion"] );
$versKey= $swKey->Open( qw(Microsoft Windows CurrentVersion) );
$remoteKey= $Registry->Open( "//HostA/LMachine/System/", {Delimiter=>"/"} )
or die "Can't connect to HostA or can't open subkey: $^E\n";
Connect établit une connexion avec le Registre d'une machine distante
et ouvre une clef dans celui-ci, puis elle retourne un nouvel objet Win32::TieRegistry
associé à cette clef de Registre distant. Si Connect a été appelé avec
une référence à un hachage lié, alors la valeur du retour sera aussi une référence
à un hachage lié [ou undef]. Sinon, si vous souhaitez utiliser l'objet retourné
comme un hachage lié [et non juste comme un objet], alors utilisez la méthode
TiedRef après Connect.
$sMachineName est le nom de la machine distante. Vous n'avez pas à faire
précéder le nom de la machine de deux caractères délimiteur.
$sKeyPath est une chaîne qui spécifie la clef distante à ouvrir. Alternativement
$sKeyPath peut être une référence à une valeur tableau qui contient la liste
des clefs de plus en plus profondes qui spécifient le chemin vers la clef à ouvrir.
$rhOptions est une référence facultative à un hachage contenant des options
supplémentaires. La méthode Connect supporte deux options, "Delimiter"
et "Access". Voyez la documentation de la méthode Open pour plus d'information
sur ces options.
$sKeyPath est déjà relative à la racine virtuelle du Registre de la machine
distante. Un délimiteur simple en tête de sKeyPath sera ignoré et n'est pas exigé.
$sKeyPath peut être vide auquel cas Connect retournera un objet
qui représentera la clef de la racine virtuelle du Registre distant.
Chaque utilistaion suivante de Open sur cette clef de la racine virtuelle
appelera la fonction système RegConnectRegistry.
La méthode Connect peut être appelée via n'importe quel objet
Win32::TieRegistry, et non pas seulement $Registry. Les attributs,
tels que le niveau désiré d'accès et le délimiteur, seront hérités de l'objet
utilisé mais $sKeyPath sera toujours relatif à la racine virtuelle du
Registre de la machine distante.
Exemples:
$remMachKey= $Registry->Connect( "HostA", "LMachine", {Delimiter->"/"} )
or die "Can't connect to HostA's HKEY_LOCAL_MACHINE key: $^E\n";
$remVersKey= $remMachKey->Connect( "www.microsoft.com",
"LMachine/Software/Microsoft/Inetsrv/CurrentVersion/",
{ Access=>KEY_READ, Delimiter=>"/" } )
or die "Can't check what version of IIS Microsoft is running: $^E\n";
$remVersKey= $remMachKey->Connect( "www",
qw(LMachine Software Microsoft Inetsrv CurrentVersion) )
or die "Can't check what version of IIS we are running: $^E\n";
$obj == $obj->ObjectRef].
Pour une référence à un hachage lié [s'il est aussi un objet], ObjectRef
retourne l'objet auquel le hachage est lié.
Surtout utile pour débugger, puisque taper x $Registry essaiera d'afficher
à l'écran le contenu entier de votre Registre. Mais la commande du débogueur
x $Registry->ObjectRef donnera à l'écran juste les détails de l'implémentation
de l'objet sous-jacent.
Si l'option facultative $bFlush est spécifiée et à une valeur vraie, alors
RegFlushKey() sera appelé, ce qui n'est presque jamais nécessaire.
$ValueData est habituellement une simple chaîne Perl qui contient la donnée
de la valeur [empaquetée à l'intérieur]. Pour certains types de données, cependant,
$ValueData peut être traité comme décrit ci-dessous.
$ValueType est la constante REG_* qui décrit le type de données de la
valeur entreposée dans $ValueData. Si l'option DualTypes() est activée,
alors $ValueType sera une valeur duale. C'est-à-dire, qu'utilisé dans un
contexte numérique, $ValueType donnera la valeur numérique d'une constante
REG_*. Alors qu'utilisé dans un contexte non-numérique, $ValueType
retournera le nom de la constante REG_ *, par exemple "REG_SZ"
[notez les guillemets]. Par conséquent, les deux conditions suivantes peuvent
être vraies en même temps :
$ValueType == REG_SZ()
$ValueType eq "REG_SZ"
FixSzNulls() est activée, alors le '\0' final sera ôté
[sauf s'il n'y en a pas] avant que les valeurs de type REG_SZ et
REG_EXPAND_SZ soient retournées. Notez que SetValue() ajoutera un '\0'
final dans des circonstances semblables.
SplitMultis() est activée, alors les valeurs de ce type sont
retournées sous la forme d'une référence à un tableau contenant les chaînes.
Par exemple, une valeur qui, avec SplitMultis() inactivé, serait retourné
comme:
"Value1\000Value2\000\000"
sera retourné, avec SplitMultis() activé, comme
[ "Value1", "Value2" ]
DualBinVals() est activée, alors la valeur est retournée comme
un scalaire contenant à la fois une chaîne et un nombre [un peu comme la variable
$! -- voir le paragraphe sur SetDualVar pour plus d'information]
où la partie numérique est la «valeur non compactée». Utilisez la valeur retournée
dans un contexte numérique pour accéder à cette partie de la valeur. Par exemple:
$num= 0 + $Registry->{"CUser/Console//ColorTable01"}; # 0 + force le contexte numérique
Si l'option DWordsToHex() est inactivée, la partie chaîne de la valeur retournée
est une chaîne compactée de 4 octets [utilisez unpack("L",$value) pour obtenir
la valeur numérique.]
Si DWordsToHex() est activée, la partie chaîne de la valeur retournée est une
chaîne de 10 caractères en hexa [avec 0x en tête]. Vous pouvez utiliser hex($value)
pour obtenir la valeur numérique.
Notez que SetValue() comprendra correctement chacun de ces formats des valeurs
retournées, que l'option DualBinVals() soit activée ou non.
MemberNames() et les hachages liés.
Une fois que vous avez demandé cette information, elle est mise en cache
dans l'objet et les futures demandes rendront toujours la même liste à moins
que la méthode Flush() n'ait été appelée.
MemberNames() et les hachages liés.
Une fois que vous avez demandé cette information, elle est mise en cache
dans l'objet et les futures demandes rendront toujours la même liste à moins
que la méthode Flush() n'ait été appelée.
SubKeyNames().
SubKeyNames().
Chaque temps est une structure FILETIME empaqueté dans une chaîne Perl.
Une fois que vous avez demandé cette information, elle est mise en cache
dans l'objet et les futures demandes rendront toujours la même liste à moins
que la méthode Flush() n'ait été appelée.
Notez qu'un nom de valeur pourrait se terminer par un délimiteur [ou pourrait être
"" afin que le nom du membre retourné soit juste un délimiteur] donc la présence
ou absence du délimiteur en tête est ce qui devrait être utilisé pour déterminer si
un nom particulier est une sous-clef ou une valeur, et non pas la présence ou l'absence
d'un délimiteur à la fin.
Une fois que vous avez demandé cette information, elle est mise en cache
dans l'objet et les futures demandes rendront toujours la même liste à moins
que la méthode Flush() n'ait été appelée.
FILETIME, empaquetée dans une chaîne Perl, indiquant quand
la clef à été modifiée la dernière fois.
SECURITY_DESCRIPTOR associé
à cette clef de Registre.
Sans argument, retourne un hachage [et non une référence à un hachage] où les clefs sont les noms des items donnés précédemment et les valeurs sont les informations décrites précédemment. Par exemple :
%info= ( "CntValues" => 25, # La clef contient 25 valeurs.
"MaxValNameLen" => 20, # L'une d'elles à un nom de 20 caractères.
"MaxValDataLen" => 42, # L'une d'elles à une valeur sur 42 octets.
"CntSubKeys" => 1, # La clef a 1 sous-clef immédiate.
"MaxSubKeyLen" => 13, # L'une d'elles à un nom de 12 caractères.
"MaxSubClassLen" => 0, # Toutes ont pour nom de classe "".
"SecurityLen" => 232, # Un SECURITY_DESCRIPTOR est de 232 octets.
"LastWrite" => "\x90mZ\cX{\xA3\xBD\cA\c@\cA"
# La clef a été modifiée la dernière fois le 1998/06/01 16:29:32 GMT
);
Avec des arguments, chacun doit être le nom d'un item donné au-dessus. La valeur de retour est l'information associée avec les noms listés. En d'autres termes:
return $key->Information( @names );
retourne la même liste que :
%info= $key->Information;
return @info{@names};
Le délimiteur par défaut est le «backslash» ('\\') mais il est hérité de
l'objet utilisé pour créer un nouvel objet et peut être spécifié par une option
quand un nouvel objet est créé.
HKEY pour la clef de Registre associée
comme une valeur entière [integer]. Cette valeur peut alors être utilisée pour
des appels avec Reg*() de Win32API::Registry. Cependant, c'est habituellement
plus facile d'appelez Win32API::Registry directement via :
$key->RegNotifyChangeKeyValue( ... );
Pour la racine virtuelle du Registre local ou distant, Handle() retourne "NONE".
$Registry->Open(), elle rouvrirait la même clef du Registre [sauf dans le cas
rare où un des noms clés contient $key->Delimiter].
"" pour les clefs du Registre local.
KEY_*.
RegOpenKeyEx()
du système d'exploitation. Pour Win32, c'est toujours un «backslash» ("\\").
"LMachine", vers
leurs constantes associées HKEY_*. À l'origine pour usage interne et sujet
à changement.
tie %hash, ref($key), $key;
puisque ref($key) est la classe [paquetage] à laquelle attacher le hachage
et TIEHASH() retourne juste ses arguments, $key, [sans appeler new()]
quand il voit que c'est déjà un objet béni.
S'il est déjà une référence à un hachage lié [c'est aussi un objet], il retourne
juste lui-même [$ref == $ref->TiedRef].
Principalement utilisé en interne.
ArrayValues en permettant aussi
d'activer ou de désactiver cette option.
Quand l'option est inactivée, les valeurs du Registre demandée via un hachage lié
sont juste retournée comme des valeurs scalaires [tout comme GetValue() dans
un contexte scalaire]. Quand l'option est activée, elles sont rendues comme une
référence à un tableau contenant la valeur de la donnée en élément [0] et
le type de la donnée en élément [1].
TieValues en permettant aussi
d'activer ou de désactiver cette option.
Activer cette option n'est pas encore possible avec cette version de Win32::TieRegistry. Dans une future version, activer cette option entraînera que les valeurs du Registre retournées d'un hachage lié seront dans un tableau lié que l'on pourra utiliser pour modifier la valeur dans le Registre.
FastDelete en permettant aussi
d'activer ou de désactiver cette option.
Quand l'option est activée, un effacement réussi d'une clef de Registre
[via un hachage lié] retourne simplement 1.
Quand l'option est désactivée, un effacement réussi d'une clef de Registre [via un hachage lié et dans un contexte non vide] retourne une référence à un hachage qui contient les valeurs présentes dans la clef avant qu'elles ne soient effacées. Ce hachage est juste semblable au hachage retourné quand on référence la clef avant de l'effacer, excepté que c'est un hachage ordinaire et non un hachage lié au paquetage Win32::TieRegistry.
Notez qu'effacer une clef de registre ou une valeur via un hachage lié dans un contexte vide prévient toute perte de temps système à construire une valeur du retour appropriée.
Notez qu'effacer une valeur de registre via un hachage lié [dans un contexte non vide] retourne la valeur de la donnée même si FastDelete est activée.
SplitMultis en permettant aussi
d'activer ou de désactiver cette option.
Si l'option est activée, les valeurs du Registre de type REG_MULTI_SZ
sont retournées sous la forme d'une référence à un tableau de chaîne. Voir
GetValue() pour plus d'information.
DWordsToHex en permettant aussi
d'activer ou de désactiver cette option.
Si l'option est activée, les valeurs du Registre de type REG_DWORD
sont retournées sous la forme d'une chaîne hexa de 4 caractères précédés
de "0x". Voir GetValue() pour plus d'information.
FixSzNulls en permettant aussi
d'activer ou de désactiver cette option.
Si l'option est activée, les valeurs du Registre de type REG_SZ et
REG_EXPAND_SZ ont un '\0' ajouté à la fin avant qu'elles ne soient
fixées et le '\0' final est retiré avant qu'elles ne soient retournées.
Voir GetValue() et SetValue() pour plus d'information.
DualTypes en permettant aussi
d'activer ou de désactiver cette option.
Si l'option est activée, les types de données sont retournées comme un combiné
numérique/chaîne contenant à la fois la valeur numérique d'un constante REG_*
et la valeur chaîne du nom de la constante.
Voir GetValue() pour plus d'information.
DualBinVals en permettant aussi
d'activer ou de désactiver cette option.
Si l'option est activée, les valeur de donnée du Registre de type REG_BINARY
et de taille inférieure à 4 octets, ainsi que les valeurs du Registre de type REG_DWORD,
sont retournées comme un combiné numérique/chaîne où la valeur numérique est la
valeur binaire «désempaquetée» comme si elle était retournée par :
hex reverse unpack( "h*", $valData )
sur un ordinateur «petit indien». [serait hex unpack("H*",$valData) sur
un ordinateur «grand indien» si ce module était jamais porté sur l'un d'eux.]
Voir GetValue() pour plus d'information.
GetOptions()
Delimiter FixSzNulls DWordsToHex
ArrayValues SplitMultis DualBinVals
TieValues FastDelete DualTypes
Passez un ou plusieurs des noms précités (en chaînes) pour récupérer un tableau des états courants correspondants dans le même ordre:
my( $fastDel, $delim )= $key->GetOptions("FastDelete","Delimiter");
Ne passez aucun argument pour récupérer une référence à un hachage dont les clefs sont les noms des options précités et les valeurs sont les états courants correspondants pour chaque option :
my $href= $key->GetOptions();
my $delim= $href->{Delimiter};
Passez une seule référence à un hachage pour avoir les paires clef/valeur précitées ajouté au hachage référencé. Dans ce cas, la valeur de retour est l'objet original de telle manière que des méthodes supplémentaires puissent être enchaînées après l'appel à GetOptions :
my %oldOpts; $key->GetOptions( \%oldOpts )->SetOptions( Delimiter => "/" );
Delimiter FixSzNulls DWordsToHex AllowLoad
ArrayValues SplitMultis DualBinVals AllowSave
TieValues FastDelete DualTypes
Pour AllowLoad et AllowSave, plutôt que l'état précédent, SetOptions
retourne si oui ou non le changement est un succès.
En contexte scalaire, retourne seulement le dernier item. La dernière
option peut aussi être "ref" ou "r" [laquelle n'a
pas besoin d'être suivi d'une valeur] pour autoriser le chaînage :
$key->SetOptions(AllowSave=>1,"ref")->RegSaveKey(...)
$ValueName est le nom de la valeur à ajouter ou remplacer et ne doit
pas être préfixée d'un délimiteur. La casse est ignorée.
$ValueType est supposé être REG_SZ s'il est omis. Autrement,
il doit être l'une des constantes REG_*.
$ValueData est la donnée à stocker dans la valeur, probablement une
chaîne obtenue avec pack. Les autres formats supportés pour les données
de valeur sont listés ci-dessous pour chaque $ValueType possible.
'\0' final
obligatoire, s'il manque. Cela peut être désactivé en mettant hors fonction
l'option FixSzNulls.
$key->SetValue( "Val1\000Value2\000LastVal\000\000", "REG_MULTI_SZ" );
$key->SetValue( ["Val1","Value2","LastVal"], "REG_MULTI_SZ" );
Notez que si les deux nuls finaux obligatoires ("\000\000") manquent,
cette version de SetValue() ne les ajoutera pas.
"0x" inclus et totalisant plus que 4 octets. Ceux-ci seront
condensé en une chaîne de 4 octets par :
$data= pack( "L", hex($data) );
SetValue() ne peut pas la distinguer d'une chaîne produite avec pack
qui correspondrait aussi à une valeur numérique et donc le traiterait
comme une chaîne produite avec pack.
Un autre format d'appel :
$okay= $key->SetValue( $ValueName, [ $ValueData, $ValueType ] );
[deux arguments, le second est une référence à un tableau qui contient
la données de la valeur et le type de la valeur] est fourni pour faciliter
l'utilisation des hachages liés avec SetValue().
RegCreateKeyEx() alors, s'il réussit, crée
un objet associé à la [éventuellement nouvelle] sous-clef.
$subKey est le nom d'une sous-clef [ou un chemin vers une sous-clef] qui
doit être créée ou a mise à jour. Ce peut être aussi une référence à un
tableau contenant une liste de noms de sous-clefs.
Le deuxième argument, s'il existe, doit être une référence à un hachage
qui spécifie des options qui doivent être passées à RegCreateKeyEx() ou bien
qui doivent être utilisées quand l'objet associé est créé. Les items
suivants sont autorisées comme clefs dans ce hachage d'options :
$subKey et utilisé
dans le nouvel objet. Par défauts $key->Delimiter.
KEY_*.
"", car nous n'avons jamais vu une seule utilisation de cette
information.
REG_CREATED_NEW_KEY(), soit REG_OPENED_EXISTING_KEY()
suivant qu'une nouvelle clef a été créée ou qu'une clef existante a été ouverte.
Par exemple, si vous faites use Win32::TieRegistry qw(REG_CREATED_NEW_KEY) alors
vous pouvez utiliser REG_CREATED_NEW_KEY() pour faire une comparaison avec la
valeur numérique entreposée dans le scalaire référencé.
Si l'option DualTypes est établie, alors, en plus de la valeur numérique décrite
ci-dessus, le scalaire référencé aura aussi une valeur chaîne égale à
"REG_CREATED_NEW_KEY" ou "REG_OPENED_EXISTING_KEY", comme approprié.
SECURITY_ATTRIBUTES condensée
avec pack dans une chaîne Perl.
Voyez Win32API::Registry::RegCreateKeyEx() pour plus d'information.
Volatile=1 est la même chose que spécifier
Options=REG_OPTION_VOLATILE.
Access est ignorée. Si le processus appelant
a établi "SeBackupPrivilege", alors la sous-clef est ouverte avec accès
KEY_READ comme l'utilisateur "LocalSystem" qui doit avoir accès à toutes
les sous-clefs. Si le processus appelant a établi "SeRestorePrivilege", alors
la sous-clef est ouverte avec accès KEY_WRITE comme l'utilisateur "LocalSystem"
qui doit avoir accès à toutes les sous-clefs.
Cette option est ignorée sous Windows 95. Spécifier Backup=1 est la même
chose que spécifier Options=REG_OPTION_BACKUP_RESTORE.
RegOpenKeyEx().
La valeur pour cette option doit être une valeur numérique obtenue par combinaison
de zéro ou plusieurs des masques de bits REG_OPTION_*. Vous pouvez
utiliser les options Volatile et/ou Backup au lieu de celle-ci.
Utilisé pour créer ou mettre à jour une clef du Registre et n'importe quel nombre de sous-clefs ou de valeurs sous cette clef ou ses sous-clefs.
$subKey est le nom d'une sous-clef à créer [ou un chemin de sous-clefs
séparées par des délimiteurs]. Si cette sous-clef existe déjà, alors elle
est mise à jour.
\%Contents est une référence à un hachage qui contient des paires de noms
de valeur avec données de valeur et/ou des noms de sous-clefs avec des références
vers des hachages semblables à \%Contents. Chacun de ceux-ci entraîne
la création ou la mise à jour d'une valeur ou d'une sous-clef de $subKey.
Si $Contents{""} existe et est une référence à un hachage, alors il est utilisé
comme argument d'options quand CreateKey() est appelé pour $subKey.
Cela vous permet de spécifier...
if( defined( $$data{""} ) && "HASH" eq ref($$data{""}) ) {
$self= $this->CreateKey( $subKey, delete $$data{""} );
$file est un fichier ruche, c'est-à-dire un fichier créé en appelant
RegSaveKey(). Le chemin $file est interprété relativement à
%SystemRoot%/System32/config sur la machine où réside $key.
$newSubKey est le nom à donner à la nouvelle clef. Si $newSubKey
est spécifié, alors $key doit être HKEY_LOCAL_MACHINE ou
HKEY_USERS de l'ordinateur local ou d'un ordinateur distant et
$newSubKey ne doit pas contenir d'occurrences de délimiteur ou de
délimiteur de l'OS.
Si $newSubKey n'est pas spécifié, alors c'est comme si $key était
$Registry->{LMachine} et $newSubKey était "PerlTie:999" où
"999" est réellement un nombre incrémenté chaque fois que
ce processus appelle Load().
Vous pouvez spécifier comme dernier argument une référence à un hachage
contenant des options. Vous pouvez spécifier les mêmes options que celles
que vous pouvez spécifier avec Open(). Voyez Open() pour plus
d'information sur celles-ci. De plus, vous pouvez spécifier l'option
"NewSubKey". La valeur de cette option est interprétée exactement comme
si elle avait été spécifiée comme paramètre de $newSubKey et
supplante toute option $newSubKey qui aurait été spécifiée.
La ruche est déchargée automatiquement quand l'objet retourné [$newKey]
est détruit. Les objets clés de Registre ouverts avec la ruche garderont
une référence vers l'objet $newKey afin qu'il ne soit pas détruit avant
ces clefs ne soient fermées.
Load(). Ne peut pas décharger
d'autres ruches. $key doit être la valeur de retour d'un appel antérieur
à Load(). $key est fermé et alors la ruche est déchargée.
"ReBackupPrivilege" pour le processus courant.
Vous devrez probablement activer ce privilège avant que vous ne puissiez utiliser
RegSaveKey().
La valeur de retour indique que l'opération a réussi, non que le privilège a été permis précédemment.
"ReRestorePrivilege" pour le processus courant.
Vous devrez probablement activer ce privilège avant que vous ne puissiez utiliser
RegLoadKey(), RegUnLoadKey(), RegReplaceKey(), ou RegRestoreKey et donc
Load() et UnLoad().
La valeur de retour indique que l'opération a réussi, non que le privilège a été permis précédemment.
use et import()]Pour n'avoir rien d'importé dans votre paquetage, utilisez quelque chose comme cela :
use Win32::TieRegistry 0.20 ();
ce qui vérifiera que vous avez au moins la version 0.20 mais n'appellera
pas import(). Le fichier Changes peut être utile pour déterminer ce
que, dans les versions antérieures de Win32::TieRegistry, vous voulez
supporter dans votre script.
Le code
use Win32::TieRegistry;
importe la variable $Registry dans votre paquetage et la fixe
comme référence à un hachage lié à une copie de l'objet racine virtuelle
du Registre avec les options par défaut. Un inconvénient de cet «usage par
défaut» est que Perl ne supporte pas le contrôle de version du module quand
vous l'utilisez.
Alternativement, vous pouvez spécifier une liste d'arguments sur la ligne
use qui sera passée à la méthode Win32::TieRegistry->import() pour
contrôler quels items importer dans votre paquetage. Ces arguments
tombent dans les catégories générales suivantes:
$scalar dans
votre paquetage (ou le paquetage nommé «pack») et l'initialise.
$scalar.
%hash dans
votre paquetage (ou le paquetage nommé «pack») et l'initialise.
%hash.
$scalar dans
votre paquetage (ou le paquetage nommé «pack») et l'initialise.
$scalar.
Vous pouvez spécifier aussi ":KEY_", ":REG_", et aussi ":HKEY_"
pour importer un ensemble entier de constantes.
Voir la documentation de Win32API::Registry pour plus d'information.
SetOptions(), chacune étant suivie de la
valeur à utiliser pour cette option. Un objet racine virtuelle de Registre
est créé, toutes ces options sont mises pour lui, ensuite chaque variable
devant être importée/fixée est associée à cet objet.
En plus, les options spéciales suivantes sont disponibles :
$Exporter::ExportLevel et a la même signification.
Voyez le module Exporter pour plus d'information.
Ce module a été écrit en accentuant fortement la commodité d'utilisation
du module. Par conséquent, à la plupart des endroits où vous pouvez spécifier
une constante comme REG_SZ(), vous pouvez aussi spécifier une chaîne qui
contient le nom de la constante, "REG_SZ". C'est commode parce que vous
n'avez pas dû importer cette constante symbolique.
Perl accentue aussi la commodité de programmation en faisant en sorte que
le code REG_SZ puisse être utilisé pour signifier REG_SZ() ou "REG_SZ"
ou être illégal.
Notez qu'utiliser ®_SZ (comme nous l'avons vu dans beaucoup de code
Perl pour Win32) n'est pas une bonne idée depuis qu'il passe le tableau courant
@_ à la routine constant() du module qui, au moins, peut vous donner un
avertissement sous -w.
Bien que ce soit essentiellement une question de style, le moyen «le plus sûr» est
probablement d'inscrire toutes les constantes dans la déclaration
use Win32::TieRegistry, de spécifiez use strict
[ou au moins use strict qw(subs)], et d'utiliser des noms nus de constante
quand vous voulez la valeur numérique. Cela détectera à la compilation les
noms de constante mal écrits.
use strict;
my $Registry;
use Win32::TieRegistry 0.20 (
TiedRef => \$Registry, Delimiter => "/", ArrayValues => 1,
SplitMultis => 1, AllowLoad => 1,
qw( REG_SZ REG_EXPAND_SZ REG_DWORD REG_BINARY REG_MULTI_SZ
KEY_READ KEY_WRITE KEY_ALL_ACCESS ),
);
$Registry->{"LMachine/Software/FooCorp/"}= {
"FooWriter/" => {
"/Fonts" => [ ["Times","Courier","Lucinda"], REG_MULTI_SZ ],
"/WindowSize" => [ pack("LL",24,80), REG_BINARY ],
"/TaskBarIcon" => [ "0x0001", REG_DWORD ],
},
} or die "Can't create Software/FooCorp/: $^E\n";
Si vous ne voulez pas utiliser use strict qw(subs), le deuxième moyen
le plus sûr est semblable au précédent, mais consiste à utiliser la forme
REG_SZ() pour les constantes quand c'est possible et à citer des noms
de constante entre guillemets quand c'est nécessaire.
Notez que qw() est une manière de mettre des guillemets.
use Win32::TieRegistry 0.20 qw(
TiedRef $Registry
Delimiter / ArrayValues 1 SplitMultis 1 AllowLoad 1
REG_SZ REG_EXPAND_SZ REG_DWORD REG_BINARY REG_MULTI_SZ
KEY_READ KEY_WRITE KEY_ALL_ACCESS
);
$Registry->{"LMachine/Software/FooCorp/"}= {
"FooWriter/" => {
"/Fonts" => [ ["Times","Courier","Lucinda"], REG_MULTI_SZ() ],
"/WindowSize" => [ pack("LL",24,80), REG_BINARY() ],
"/TaskBarIcon" => [ "0x0001", REG_DWORD() ],
},
} or die "Can't create Software/FooCorp/: $^E\n";
Les exemples dans ce document utilisent principalement l'usage des guillemets
autour des noms de constante ("REG_SZ") puisque ça marche indépendamment
des constantes que vous avez importées et que vous utilisiez ou non use strict
dans votre script. Ce n'est pas le meilleur choix pour vous dans de vrais
scripts (contrairement aux exemples) parce que c'est moins efficace et n'est
pas supporté par la plupart des autres modules similaires.
La plupart des choses peuvent être faites plus facilement via un hachage lié. Sautez jusqu'au Résumé pour les hachages liés afin de commencer rapidement.
Voici des exemples rapides qui documentent les fonctionnalités les plus communes de toutes les méthodes [à l'exception de quelques-unes qui sont presque inutiles].
# Juste un autre façon de faire Open() :
$key= new Win32::TieRegistry "LMachine\\Software\\",
{ Access=>KEY_READ()|KEY_WRITE(), Delimiter=>"\\" };
# Ouverture d'une clef de Registre :
$subKey= $key->Open( "SubKey/SubSubKey/",
{ Access=>KEY_ALL_ACCESS, Delimiter=>"/" } );
# Connexion à une clef de Registre d'une machine distante :
$remKey= $Registry->Connect( "MachineName", "LMachine/",
{ Access=>KEY_READ, Delimiter=>"/" } );
# Obtenir la donnée d'une valeur :
$valueString= $key->GetValue("ValueName");
( $valueString, $valueType )= $key->GetValue("ValueName");
# Obtenir la liste des noms de valeur :
@valueNames= $key->ValueNames;
# Obtenir la liste des noms des sous-clefs :
@subKeyNames= $key->SubKeyNames;
# Obtenir la liste combinée des noms de valeur (avec les délimiteurs de tête)
# et des nom de sous-clef (avec les délimiteurs de queue):
@memberNames= $key->MemberNames;
# Obtenir toute l'information au sujet d'une clef :
%keyInfo= $key->Information;
# keys(%keyInfo)= qw( Class LastWrite SecurityLen
# CntSubKeys MaxSubKeyLen MaxSubClassLen
# CntValues MaxValNameLen MaxValDataLen );
# Obtenir une information choisie au sujet d'une clef :
( $class, $cntSubKeys )= $key->Information( "Class", "CntSubKeys" );
# Obtenir et/ou fixer le délimiteur :
$delim= $key->Delimiter;
$oldDelim= $key->Delimiter( $newDelim );
# Obtenir le "chemin" d'une clef ouverte
$path= $key->Path;
# Par exemple, "/CUser/Control Panel/Mouse/"
# ou "//HostName/LMachine/System/DISK/".
# Obtenir le nom de la machine d'où provient la clef :
$mach= $key->Machine;
# Habituellement "" indiquera que la clef est sur la machine locale.
# Contrôler différentes options (voyez la documentation principale pour les descriptions) :
$oldBool= $key->ArrayValues( $newBool );
$oldBool= $key->FastDelete( $newBool );
$oldBool= $key->FixSzNulls( $newBool );
$oldBool= $key->SplitMultis( $newBool );
$oldBool= $key->DWordsToHex( $newBool );
$oldBool= $key->DualBinVals( $newBool );
$oldBool= $key->DualTypes( $newBool );
@oldBools= $key->SetOptions( ArrayValues=>1, FastDelete=>1, FixSzNulls=>0,
Delimiter=>"/", AllowLoad=>1, AllowSave=>1 );
@oldBools= $key->GetOptions( ArrayValues, FastDelete, FixSzNulls );
# Ajouter ou changer une valeur :
$key->SetValue( "ValueName", $valueDataString );
$key->SetValue( "ValueName", pack($format,$valueData), "REG_BINARY" );
# Ajouter ou changer une clef :
$key->CreateKey( "SubKeyName" );
$key->CreateKey( "SubKeyName",
{ Access=>"KEY_ALL_ACCESS", Class=>"ClassName",
Delimiter=>"/", Volatile=>1, Backup=>1 } );
# Charger un fichier ruche autonome dans un Registre connecté
$newKey= $Registry->Load( "C:/Path/To/Hive/FileName" );
$newKey= $key->Load( "C:/Path/To/Hive/FileName", "NewSubKeyName",
{ Access=>"KEY_READ" } );
# Décharger un Registre d'un fichier ruche chargé via la méthode Load()
$newKey->UnLoad;
# Autorisez-vous/Interdissez-vous vous-même de charger un fichier ruche.
$success= $Registry->AllowLoad( $bool );
# Autorisez-vous/Interdissez-vous vous-même de sauver une clef de Registre dans un fichier ruche
$success= $Registry->AllowSave( $bool );
# Sauver une clef de Registre dans un nouveau fichier ruche :
$key->RegSaveKey( "C:/Path/To/Hive/FileName", [] );
Voyez Win32API::Registry pour plus d'information sur ces méthodes.
Ces méthodes sont fournies pour faciliter le codage et sont identiques
au fonctions de Win32API::Registry sauf qu'elles ne prennent pas
un handle de clef de Registre, mais obtiennent ce handle de l'objet
invoqué [$key].
$key->RegGetKeySecurity( $iSecInfo, $sSecDesc, $lenSecDesc );
$key->RegLoadKey( $sSubKeyName, $sPathToFile );
$key->RegNotifyChangeKeyValue(
$bWatchSubtree, $iNotifyFilter, $hEvent, $bAsync );
$key->RegQueryMultipleValues(
$structValueEnts, $cntValueEnts, $Buffer, $lenBuffer );
$key->RegReplaceKey( $sSubKeyName, $sPathToNewFile, $sPathToBackupFile );
$key->RegRestoreKey( $sPathToFile, $iFlags );
$key->RegSetKeySecurity( $iSecInfo, $sSecDesc );
$key->RegUnLoadKey( $sSubKeyName );
Pour les apprenants pressés, ce peut être la seule section que vous ayez besoin de lire. Toujours attacher un délimiteur à la fin de chaque nom de clef de Registre et toujours ajouter un délimiteur au début de chaque nom de valeur du Registre.
use Win32::TieRegistry ( Delimiter=>"/", ArrayValues=>1 );
$Registry->Delimiter("/"); # Fixe le délimiteur à "/".
$swKey= $Registry->{"LMachine/Software/"};
$winKey= $swKey->{"Microsoft/Windows/CurrentVersion/"};
$userKey= $Registry->
{"CUser/Software/Microsoft/Windows/CurrentVersion/"};
$remoteKey= $Registry->{"//HostName/LMachine/"};
$progDir= $winKey->{"/ProgramFilesDir"}; # "C:\\Program Files"
$tip21= $winKey->{"Explorer/Tips//21"}; # Texte du conseil #21.
$winKey->ArrayValues(1);
( $devPath, $type )= $winKey->{"/DevicePath"};
# $devPath eq "%SystemRoot%\\inf"
# $type eq "REG_EXPAND_SZ" [si le module SetDualVar.pm est installé]
# $type == REG_EXPAND_SZ() [si vous avez fait C<use Win32::TieRegistry qw(:REG_)>]
$winKey->{"Setup//SourcePath"}= "\\\\SwServer\\SwShare\\Windows";
# Simple. Assume le type de donnée REG_SZ.
$winKey->{"Setup//Installation Sources"}=
[ "D:\x00\\\\SwServer\\SwShare\\Windows\0\0", "REG_MULTI_SZ" ];
# "\x00" et "\0" utilisés pour marquer la fin de chaque chaîne et la fin de liste.
$winKey->{"Setup//Installation Sources"}=
[ ["D:","\\\\SwServer\\SwShare\\Windows"], "REG_MULTI_SZ" ];
# Méthode alternative, plus facile à lire.
$userKey->{"Explorer/Tips//DisplayInitialTipWindow"}=
[ pack("L",0), "REG_DWORD" ];
$userKey->{"Explorer/Tips//Next"}= [ pack("S",3), "REG_BINARY" ];
$userKey->{"Explorer/Tips//Show"}= [ pack("L",0), "REG_BINARY" ];
$swKey->{"FooCorp/"}= {
"FooWriter/" => {
"/Version" => "4.032",
"Startup/" => {
"/Title" => "Foo Writer Deluxe ][",
"/WindowSize" => [ pack("LL",$wid,$ht), "REG_BINARY" ],
"/TaskBarIcon" => [ "0x0001", "REG_DWORD" ],
},
"Compatibility/" => {
"/AutoConvert" => "Always",
"/Default Palette" => "Windows Colors",
},
},
"/License", => "0123-9C8EF1-09-FC",
};
@members= keys( %{$swKey} );
@subKeys= grep( m#^/#, keys( %{$swKey->{"Classes/batfile/"}} ) );
# @subKeys= ( "/", "/EditFlags" );
@valueNames= grep( ! m#^/#, keys( %{$swKey->{"Classes/batfile/"}} ) );
# @valueNames= ( "DefaultIcon/", "shell/", "shellex/" );
$oldValue= delete $userKey->{"Explorer/Tips//Next"};
$oldValues= delete $userKey->{"Explorer/Tips/"};
# $oldValues sera une référence à un hachage contenant les clefs et valeurs effacées
$oldValues will be reference to hash containing deleted keys values.
undef $swKey; # Manière explicite de fermer une clef.
$winKey= "Anything else"; # Fermeture implicite d'une clef.
exit 0; # Fermeture implicite de toutes les clefs.
À l'origine, ce module était appelé Tie::Registry.
Changer le code qui utilisait Tie::Registry en Win32::TieRegistry
est facile puisque le nom du module ne devrait être mentionné qu'une fois
seulement, dans la ligne use. Cependant, trouver tous les endroits où
est utilisé Tie::Registry n'étant pas toujours si simple, vous pouvez
installer le module Tie/Registry.pm que nous incluons dans la distribution
pour permettre la compatibilité ascendante.
Tye McQueen. Voir http://www.metronet.com/~tye/ ou e-mail tye@metronet.com pour les rapports de bug.
Win32API::Registry - Fournit un accès à Reg*(), HKEY_*,
KEY_*, REG_* [requis].
Win32::WinError - Définit les valeurs ERROR_* [facultatif].
SetDualVar - Pour rendre les valeurs REG_* comme des valeurs combinées
chaîne/entier [facultatif].
Perl5.004_02 a des bugs qui font que Win32::TieRegistry échoue par des manières étranges et subtiles.
Utiliser Win32::TieRegistry avec des versions de Perl antérieures à 5.005
peut être délicate ou impossible. La plupart des notes à ce sujet ont
été enlevées de la documentation (elles sont plutôt compliquées et embrouillées).
Cela inclut des références à $^E qui ne sont peut être pas pertinentes.
Parce que les hachages de Perl sont sensibles à la casse, certaines recherches sont aussi sensibles à la casse. En particulier, les clefs racine («Classes», «CUser», «LMachine», «Users», «PerfData», «CConfig», «DynData», et HKEY_*) doivent toujours être entrées en respectant les lettres majuscules et minuscules. Aussi, la règle spéciale pour la correspondance des noms de sous-clef qui contiennent le délimiteur utilisateur sélectionné fonctionne seulement si la casse correspond. Toute consultation de nom de clef ou de nom de valeur devraient être insensible à la casse parce que les appels à Reg*() sous-jacents ignorent la casse.
L'information au sujet de chaque clef est mise en cache quand vous utilisez un hachage lié. Ce cache n'est pas vidé ni mis à jour quand des changements sont faits, même quand le même hachage lié est utilisé pour faire les changements.
Les mises en oeuvre courantes de la phase de «destruction globale» de Perl
peuvent faire que les objets retournés par Load() soient détruits pendant que
les clefs dans la ruche sont encore ouvertes, si ces objets existent encore quand
le script commence se terminer. Quand cela arrive, le UnLoad() automatique
rapportera un échec et la ruche restera chargée dans le Registre.
Essayer de charger avec Load() un fichier ruche qui est localisé quelque part sur
le réseau local peut effacer silencieusement toutes les données de la ruche.
C'est un bug des APIs Win32, et non pas du code Perl ou de modules.
Ce module n'essaie pas de vous protéger de ce bug.
Il n'y a pas de suite de test.
Les items suivants sont désirés par l'auteur et pourront apparaître dans une future version du module.
RegNotifyChangeKeyValue() pour garder à jour les caches du hachage
lié même quand ce sont d'autres programmes qui font des changements.
warn or die.
Pour les opérations complexes, comme copier un sous-arbre entier, fournit un accès à l'information détaillée au sujet des erreurs (et peut-être quelques avertissements) qui ont été rencontrées. Laissez l'utilisateur contrôler la suite de l'opération complexe malgré les erreurs.
Cette traduction française correspond à la version anglaise distribuée avec perl 5.8.0. Pour en savoir plus concernant ces traductions, consultez http://www.enstimac.fr/Perl/ .
Jean-Louis Morel <jl_morel@bribes.org>
| Win32::TieRegistry - des méthodes simples et puissantes pour manipuler le Registre [sur Win32 actuellement]. |