Instructions

4.9 Instructions

4.9.1 Instructions basiques

Les instructions utilisées par NSIS dans ses scripts sont une sorte de croisement entre le PHP et l'assembleur. Il n'y a aucune construction réelle de langage de haut niveau, mais les instructions en elles-mêmes sont (dans leur majeure partie) de haut niveau, et vous avez de solides possibilités de traitement des chaines de caractères (ex. vous n'avez plus besoin de vous inquiéter lors de la concaténation de chaînes de caractères, etc.). Vous avez en gros 25 registres (20 généralistes, 5 spéciaux), ainsi qu'une pile.

4.9.1.1 Delete

[/REBOOTOK] fichier

Supprime fichier (qui peut être un fichier ou bien un filtre, mais doit être spécifié à l'aide d'un nom de répertoire complet) sur le système cible. Si /REBOOTOK est spécifié, et que le fichier ne peut être supprimé, alors le fichier sera supprimé au reboot (redémarrage) du système -- si le fichier doit être supprimé au redémarrage, le flag de reboot est levé. Le flag d'erreur est levé si les fichier sont trouvés, mais ne peuvent être supprimés. Le flag d'erreur n'est pas levé si l'on essaye de supprimé un fichier qui n'existe pas.

Delete $INSTDIR\unfichier.dat

4.9.1.2 Exec

commande

Exécute le programme spécifié et continue immédiatement. Notez que le fichier spécifié doit exister sur le système cible, et non sur le système utilisé à la compilation. $OUTDIR est utilisé comme répertoire de travail. Le flag d'erreur sera levé si le processus ne peut pas être lancé. Notez que, si la commande contient des espaces, vous devrez la faire contenir dans des guillemets délimiteurs pour ne pas la confondre avec les paramètres. ex.: Exec '"$INSTDIR\commande.exe" paramètres'. Si vous n'utilisez pas les guillemets, cela ne fonctionnera pas sous 9x avec ou sans paramètres.

Exec '"$INSTDIR\unprogramme.exe"'
Exec '"$INSTDIR\unprogramme.exe" des paramètres'

4.9.1.3 ExecShell

action commande [paramètres] [SW_SHOWNORMAL | SW_SHOWMAXIMIZED | SW_SHOWMINIMIZED]

Exécute le programme spécifié en utilisant ShellExecute. Notez que l'action est très souvent "open" (ouvrir), "print" (imprimer), etc., mais peut être une chaîne vide (action par défaut). Les paramètres et le type d'affichage sont optionnels. $OUTDIR est utilisé comme répertoire de travail. Le flag d'erreur est levé dans le cas ou le processus ne peut être lancé.

ExecShell "open" "http://nsis.sf.net/"
ExecShell "open" "$INSTDIR\readme.txt"

4.9.1.4 ExecWait

commande [var_utilisateur(code de sortie)]

Exécute le programme spécifié et attend que le processus exécuté se termine. Voir Exec pour plus d'informations. Si aucune variable n'est spécifiée, ExecWait lève un flag d'erreur si le programme retourne un code d'erreur différent de zéro, ou s'il se produit une erreur. Si une variable est spécifiée, ExecWait placera le code de retour dans la variable (et ne lèvera de flag d'erreur que si une erreur survient; si une erreur survient, le contenu de la variable utilisateur sera indéfini). Notez que, si la commande intègre des espaces, vous devrez la mettre entre guillemets pour les séparer. ex : ExecWait '"$INSTDIR\commande.exe" paramètres'. Si vous n'utilisez pas les guillemets, cela ne fonctionnera pas sous 9x avec ou sans paramètres.

ExecWait '"$INSTDIR\unprogramme.exe"'
ExecWait '"$INSTDIR\unprogramme.exe"' $0
DetailPrint "retour de programme: $0"

4.9.1.5 File

[/nonfatal] [/a] ([/r] (fichier|caract_spéciaux) [...] | /oname=fichier.dat dansFichier.dat)

Ajoute un (des) fichier(s) à extraire dans le répertoire de destination courant ($OUTDIR).

Notez que le nom du fichier est $OUTDIR\nom_de_fichier.
Si l'option /oname=X est utilisée, le nom deviendra $OUTDIR\$X. En utilisant l'option /oname=, seul un fichier peut être spécifié, et le nom du fichier peut contenir des variables (ou un répertoire complet, ex. $SYSDIR\nimportequoi.dll). Si le nom de sortie contient des espaces, mettez entre guillemet le paramètre en entier, en incluant /oname, comme dans l'exemple ci-dessous.
Les caractères spéciaux (* ?) sont supportés.
Si l'option /r est utilisée, les fichiers et répertoires seront ajoutés récursivement. Si aucun filtre n'est utilisé (ex. File /r C:\plouf\monrep), alors l'arborescence complète ira dans $OUTDIR\monrep. Pour le mettre dans $OUTDIR, utilisez File /r C:\plouf\mydir\*.*
Utilisez l'option /x pour exclure des fichiers ou répertoires.
Si l'option /a est utilisée, alors des attributs des fichiers ajoutés seront gardés.
La commande File défini un flag d'erreur si le mode d'écrasement automatique est placé en 'try' (essayer) et que le fichier ne peut être écrasé, ou que si ce mode est 'on' (actif), que le fichier ne peut être écrasé et que l'utilisateur sélectionne ignorer.
Si l'option /nonfatal est utilisé, un avertissement sera retourné si aucun fichier n'a été trouvé, au lieu d'une erreur.

File something.exe
File /a something.exe
File *.exe
File /r *.dat
File /r data
File /oname=$TEMP\temp.dat somefile.ext
File "/oname=$TEMP\name with spaces.dat" somefile.ext
File /nonfatal "un fichier qui ne devrait pas exister"
File /r /x CVS myproject
File /r /x *.res /x *.obj /x *.pch source

Note: quand vous utilisez le paramètre /r, les répertoires ET les fichiers correspondant seront recherchés. Ceci est toujours fait avec ou sans l'utilisation de jokers, même si le chemin donné correspond parfaitement à un répertoire. Ceci signifie, que la structure de répertoire suivante:

<DIR> quelquechose
  fichier.dat
  unautre.dat
<DIR> dir
  quelquechose
  <DIR> dir2
    fichier2.dat
<DIR> unautre
  <DIR> quelquechose
    readme.txt

Avec l'utilisation de File suivante:

File /r quelquechose

correspondra au répertoire quelquechose du répertoire racine, au fichier nommé quelquechose dans le répertoire nommé dir et au répertoire nommé quelquechose dans le répertoire nommé unautre. Pour ne correspondre qu'au répertoire quelquechose dans le répertoirre racine, utilisez:

File /r quelquechose\*.*

4.9.1.6 Rename

[/REBOOTOK] fichier_source fichier_dest

Renomme le fichier_source en fichier_dest. La fonction est similaire à l'API win32 MoveFile, ce qui signifie que vous pouvez déplacer un fichier situé n'importe où sur le système, vers un emplacement n'importe où sur le système, et que vous pouvez déplacer un répertoire vers un autre emplacement du lecteur. Si /REBOOTOK est spécifié, et que le fichier ne peut être écrit, alors le fichier sera déplacé au reboot (redémarrage) du système -- si le fichier doit être déplacé au redémarrage, le flag de reboot sera levé. Le flag d'erreur est levé si le fichier ne peut être renommé (et que /REBOOTOK n'est pas utilisé) ou que le fichier source n'existe pas.

Si aucun chemin absolu n'est spécifié le répertoire courant sera utilisé. Le répertoire courant est le répertoire défini avec le dernier SetOutPath. Si vous n'avez pas utilisé SetOutPath le répertoire courant est $EXEDIR.

Rename $INSTDIR\file.ext $INSTDIR\file.dat

4.9.1.7 ReserveFile

[/nonfatal] [/r] fichier [fichier...]

Réserve un fichier dans le bloc de données pour une utilisation ultérieure. Comme les fichiers sont ajoutés dans l'ordre ou ils sont appelés dans le script, les fichiers utilisés dans la fonction .onInit, par exemple, peuvent être ajoutés en dernier et ralentir le chargement de l'installation. D'où l'utilité de cette commande qui vous autorise à accélérer le processus de chargement en incluant le fichier en haut du bloc de données, et n'obligera pas NSIS à le rechercher dans tout le bloc de données compressé.

Voir File pour plus d'informations sur le paramètre.

4.9.1.8 RMDir

[/r/REBOOTOK] répertoire

Supprime le répertoire spécifié (qui doit être un chemin complet sans joker). Sans /r, le répertoire ne sera supprimé que s'il est vide. Si /r est spécifié, la suppression sera récursivement : ainsi, tous les fichiers et sous-répertoires seront supprimés. Si /REBOOTOK est spécifié que le répertoire ne peut pas être écrasé, alors le répertoire sera supprimé au redémarrage du système -- si le répertoire est supprimé au redémarrage, le flag de redémarrage est levé. Le flag d'erreur est levé si le répertoire ne peut pas être supprimé.

RMDir $INSTDIR
RMDir $INSTDIR\data
RMDir /r /REBOOTOK $INSTDIR
RMDir /REBOOTOK $INSTDIR\DLLs

Notez que le répertoire de travail ne peut pas être supprimé. Le répertoire courant est défini par SetOutPath. Par exemple, l'exemple suivant ne supprimera pas le répertoire.

SetOutPath $TEMP\dir
RMDir $TEMP\dir

L'exemple suivant réussira à supprimer le répertoire.

SetOutPath $TEMP\dir
SetOutPath $TEMP
RMDir $TEMP\dir

4.9.1.9 SetOutPath

destination

Défini le répertoire de destination ($OUTDIR) et le créé (récursivement, si nécessaire), s'il n'existe pas. Doit être un chemin complet et est habituellement $INSTDIR (vous pouvez spécifier $INSTDIR si vous êtes trop fainéants pour un "-").

SetOutPath $INSTDIR
File program.exe

4.9.2 Instructions de gestion du registre et des fichiers INI

Dans toutes les instructions registre ci-dessous, utilisez une chaîne vide (symbolisée par deux guillemets sans rien entre - "") comme le nom de la clé affichée comme "Par défaut" dans regedit.exe.

Si aucun chemin complet n'est spécifié pour aucune instruction de traitement de l'INI, le répertoire de Windows sera utilisé.

4.9.2.1 DeleteINISec

fichier_ini section

Supprime une section entière [section] dans fichier_ini. Si la section ne peut pas être supprimée du fichier ini, le flag d'erreur est levé. Le flag d'erreur n'est pas levé si la section n'a pas pu être trouvée.

WriteINIStr $TEMP\something.ini section1 something 123
WriteINIStr $TEMP\something.ini section1 somethingelse 1234
WriteINIStr $TEMP\something.ini section2 nsis true
DeleteINISec $TEMP\something.ini section1

4.9.2.2 DeleteINIStr

fichier_ini section nom

Supprime chaîne de la section [section] dans fichier_ini. Si la chaîne ne peut être supprimée du fichier ini, le flag d'erreur est levé. Le flag d'erreur n'est pas levé si la chaîne n'a pas pu être trouvée.

WriteINIStr $TEMP\something.ini section1 something 123
WriteINIStr $TEMP\something.ini section1 somethingelse 1234
DeleteINIStr $TEMP\something.ini section1 somethingelse

4.9.2.3 DeleteRegKey

[/ifempty] clé_racine sous-clé

Supprime une clé du registre. Si /ifempty (si vide) est spécifié, la clé du registre ne sera supprimée que si elle ne contient aucune sous-clé (sinon, l'arborescence entière du registre sera supprimée). Les valeurs valides pour clé_racine sont listées dans l'aide de WriteRegStr. Le flag d'erreur est levé si la clé ne peut être supprimée du registre (ou si elle n'existe tout simplement pas).

DeleteRegKey HKLM "Software\My Company\My Software"
DeleteRegKey /ifempty HKLM "Software\A key that might have subkeys"

4.9.2.4 DeleteRegValue

clé_racine sous-clé clé

Supprime une valeur dans le registre. Les valeurs valides pour clé_racine sont listées dans l'aide de WriteRegStr. Le flag d'erreur est levé si la valeur ne peut être supprimée du registre (ou si elle n'existe pas).

DeleteRegValue HKLM "Software\My Company\My Software" "some value"

4.9.2.5 EnumRegKey

var_utilisateur(destination) clé_racine sous-clé index

Défini la variable utilisateur $x avec le nom de la clé de registre 'index' ième dans clé_racine\sousclé. Les valeurs valides pour clé_racine sont listées dans l'aide de WriteRegStr. Retourne une chaîne vide s'il n'existe plus d'autres clés, et retourne une chaîne vide et lève le flag d'erreur en cas d'erreur.

StrCpy $0 0
loop:
  EnumRegKey $1 HKLM Software $0
  StrCmp $1 "" done
  IntOp $0 $0 + 1
  MessageBox MB_YESNO|MB_ICONQUESTION "$1$\n$\nPlus?" IDYES loop
done:

4.9.2.6 EnumRegValue

var_utilisateur(destination) clé_racine sous-clé index

Défini la variable utilisateur $x avec le nom de la valeur de registre 'index' ième dans clé_racine\sousclé. Les valeurs valides pour clé_racine sont listées dans l'aide de WriteRegStr. Retourne une chaîne vide et lève le flag d'erreur s'il n'existe plus d'autres clés ou en cas d'erreur.

StrCpy $0 0
loop:
  EnumRegValue $1 HKLM Software\Microsoft\Windows\CurrentVersion $0
  StrCmp $1 "" done
  IntOp $0 $0 + 1
  ReadRegStr $2 HKLM Software\Microsoft\Windows\CurrentVersion $1
  MessageBox MB_YESNO|MB_ICONQUESTION "$1 = $2$\n$\nPlus?" IDYES loop
done:

4.9.2.7 ExpandEnvStrings

var_utilisateur(destination) chaîne

Développe les variables d'environnement de string dans la variable utilisateur $x. Si une variable d'environnement n'existe pas, elle ne sera pas remplacée. Par exemple, si vous utilisez "%var%" et var n'existe pas, le résultat sera "%var". Si une erreur survient lors de la lecture de la chaîne, la variable utilisateur reste vide, et le flag d'erreur est levé.

ExpandEnvStrings $0 "WINDIR=%WINDIR%$\nTEMP=%TEMP%"

4.9.2.8 FlushINI

fichier_ini

Met à jour le fichier INI. Windows 9x garde toutes les modifications du fichier INI en mémoire. Cette commande permet de forcer l'écriture des modifications sur le disque. Utilisez-la si vous modifiez le fichier INI manuellement, le supprimez, le déplacez ou le copiez juste après l'avoir modifié avec WriteINIStr, DeleteINISec ou DeleteINStr.

WriteINIStr $TEMP\something.ini test test test
FlushINI $TEMP\something.ini
Delete $TEMP\something.ini

4.9.2.9 ReadEnvStr

var_utilisateur(destination) nom

Lit depuis la chaîne d'environnement "nom" et stocke la valeur dans la variable utilisateur $x. Si une erreur survient lors de la lecture de la chaîne, la variable utilisateur reste vide, et le flag d'erreur est levé.

ReadEnvStr $0 WINDIR
ReadEnvStr $1 TEMP

4.9.2.10 ReadINIStr

var_utilisateur(destination) fichier_ini section entrée

Lit depuis entrée dans [section] de fichier_ini est stocke la valeur dans la variable utilisateur $x. Le flag d'erreur est levé et $x prendra la valeur chaîne vide si l'entrée n'est pas trouvée.

ReadINIStr $0 $INSTDIR\winamp.ini winamp outname

4.9.2.11 ReadRegDWORD

var_utilisateur(destination) clé_racine sous-clé nom

Lit un DWORD de 32 bits depuis le registre vers la variable utilisateur $x. Les valeurs valides pour clé_racine sont listées dans l'aide de WriteRegStr. Le flag d'erreur est levé et $x comprendra une chaîne vide ("", soit 0) si le DWORD n'est pas présent. Si la valeur est présente, mais n'est pas de type DWORD, elle sera lue comme une chaîne de caractères et le flag d'erreur sera levé.

ReadRegDWORD $0 HKLM Software\NSIS VersionBuild

4.9.2.12 ReadRegStr

var_utilisateur(destination) clé_racine sous-clé nom

Lit depuis le registre dans la variable utilisateur $x. Les valeurs valides pour clé_racine sont listées dans l'aide de WriteRegStr. Le flag d'erreur est levé et $x comprendra une chaîne vide ("") si la chaîne n'est pas présente. Si la valeur est présente, mais est de type REG_DWORD, elle sera lue, convertie en chaîne de caractères et le flag d'erreur sera levé.

ReadRegStr $0 HKLM Software\NSIS ""
DetailPrint "NSIS est installé à: $0"

4.9.2.13 WriteINIStr

fichier_ini section entré valeur

Ecrit entrée=valeur dans [section] de fichier_ini. Le flag d'erreur est levé si la chaîne ne peut être écrite dans le fichier ini.

WriteINIStr $TEMP\something.ini section1 something 123
WriteINIStr $TEMP\something.ini section1 somethingelse 1234
WriteINIStr $TEMP\something.ini section2 nsis true

4.9.2.14 WriteRegBin

clé_racine sous-clé nom valeur

Cette commande écrit un bloc de données binaires dans le registre. Les valeurs correctes sont listées dans l'aide de WriteRegStr. Valeur est en hexadécimal (ex. DEADBEEF01223211151). Le flag d'erreur est levé si la donnée binaire ne peut être écrite dans le registre. Si la clé n'existe pas, elle sera créée.

WriteRegBin HKLM "Software\My Company\My Software" "Binary Value" DEADBEEF01223211151

4.9.2.15 WriteRegDWORD

clé_racine sous-clé nom valeur

Cette commande écrit un dword (entier de 32 bits) dans le registre (une variable utilisateur peut être spécifiée). Les valeurs valides pour clé_racine sont listées dans l'aide de WriteRegStr. Le flag d'erreur est levé si le dword ne peut être écrit dans le registre. Si la clé n'existe pas, elle sera créée.

WriteRegDWORD HKLM "Software\My Company\My Software" "DWORD Value" 0xDEADBEEF

4.9.2.16 WriteRegStr

clé_racine sous-clé nom valeur

Ecrit une chaîne dans le registre. Voir WriteRegExpandStr pour plus de détails.

WriteRegStr HKLM "Software\My Company\My Software" "String Value" "dead beef"

4.9.2.17 WriteRegExpandStr

clé_racine sous-clé nom valeur

Ecrit une chaîne dans le registre. Clé_racine doit être :

HKCR ou HKEY_CLASSES_ROOT
HKLM ou HKEY_LOCAL_MACHINE
HKCU ou HKEY_CURRENT_USER
HKU ou HKEY_USERS
HKCC ou HKEY_CURRENT_CONFIG
HKDD ou HKEY_DYN_DATA
HKPD ou HKEY_PERFORMANCE_DATA

Le flag d'erreur est levé si la chaîne ne peut être écrite dans le registre. Le type de chaîne sera REG_SZ pour WriteRegStr, ou REG_EXPAND_STR pour WriteRegExpandStr. Si la clé n'existe pas, elle sera créée.

WriteRegExpandStr HKLM "Software\My Company\My Software" "Expand String Value" "%WINDIR%\notepad.exe"

4.9.3 Instructions d'intérêt général

4.9.3.1 CallInstDLL

fichier_dll [/NOUNLOAD] nom_fonction

Appelle une fonction appelée nom_fonction dans l'extension DLL de NSIS, un plug-in. Voir le plugin exemple pour un exemple. Les extensions DLL peuvent accéder à la pile et aux variables. Utilisez /NOUNLOAD pour forcer l'installation à laisser une DLL chargée en mémoire. Note : Pour extraire automatiquement et appeler des DLLs de plugins, utilisez une commande de plugin au lieu de CallInstDLL.

Push "un paramètre"
Push "un autre paramètre"
CallInstDLL $INSTDIR\unedll.dll une fonction

4.9.3.2 CopyFiles

[/SILENT] [/FILESONLY] fichiers_sur_sys_distant destination [taille_des_fichiers_en_ko]

Copie des fichiers depuis la source vers la destination du système d'installation. Utile avec $EXEDIR si vous désirez copier le medium d'installation, ou bien vous copier depuis un emplacement vers un autre du système. Utilise SHFileOperation, ainsi, l'utilisateur pourra voir une fenêtre d'état sur l'opération de copie, si celle-ci est importante (pour le désactiver, utilisez /SILENT). Le dernier paramètre spécifie la taille de la copie (en kilo octets), afin que l'installation puisse calculer l'espace disque nécessaire. En cas d'erreur, ou si l'utilisateur annule la copie (seulement possible si /SILENT a été omis), le flag d'erreur est levé. Si /FILESONLY est spécifié, seuls les fichiers sont copiés.

Si aucun répertoire absolu n'est spécifié, le répertoire courant sera utilisé. Le répertoire courant est le dossier définit par la dernière instruction SetOutPath appelée. Si vous n'avez pas encore appelé SetOutPath, le répertoire courant est $EXEDIR.

CreateDirectory $INSTDIR\backup
CopyFiles $INSTDIR\*.dat $INSTDIR\backup

4.9.3.3 CreateDirectory

rep_a_creer

Créé (récursivement, si nécessaire) le répertoire spécifié. Le flag d'erreur est levé si le répertoire ne peut pas être créé.

Vous devez toujours spécifier un répertoire absolu.

CreateDirectory $INSTDIR\un\répertoire

4.9.3.4 CreateShortCut

lien.lnk cible.ext [paramètres [icone.ext [index_icone [options_execution [raccourci_clavier [description]]]]]]

Créé un raccourci 'lien.lnk' qui est relié à 'cible.ext', avec comme paramètre optionnel 'paramètres'. L'icône utilisée pour ce raccourci est 'icone.ext,index_icone'; pour une icone par défaut, utilisez des chaînes vides pour icone.ext et index_icone. options_execution peut être: SW_SHOWNORMAL (fenêtre normale), SW_SHOWMAXIMIZED (fenêtre maximisée), SW_SHOWMINIMIZED (fenêtre minimisée) ou bien une chaîne vide. raccourci_clavier peut être de la forme 'flag|c' ou flag peut être une combinaison (utilisation de |) de: ALT, CONTROL, EXT, ou SHIFT. c est le caractère à utiliser (a-z, A-Z, 0-9, F1-F24, etc). Notez qu'aucun espace n'est autorisé pour cette chaîne. Un bon exemple serait "ALT|CONTROL|F8". $OUTDIR est utilisé comme répertoire de travail. Vous pouvez le modifier en utilisant SetOutPath avant de créer le raccourci. Description doit être la description du raccourci, ou le commentaire sous XP. Le flag d'erreur est levé si le raccourci ne peut pas être créé (ex. le répertoire n'existe pas, ou toute autre erreur).

CreateDirectory "$SMPROGRAMS\Ma Compagnie"
CreateShortCut "$SMPROGRAMS\Ma Compagnie\Mon Programme.lnk" "$INSTDIR\Mon Programme.exe" \
  "des paramètres de ligne de commande "$INSTDIR\Mon Programme.exe" 2 SW_SHOWNORMAL \
  ALT|CTRL|SHIFT|F5 "une description"

4.9.3.5 GetDLLVersion

fichier var_utilisateur(dword haut de destination) var_utilisateur(dword bas de destination)

Récupère les informations de version de la DLL (ou de n'importe quel exécutable contenant les informations de versions) dans "fichier". Défini les variables utilisateur avec les dwords haut et bas par les informations de version en cas de succès; en cas d'échec les variables sont vides et le flag d'erreur est levé. L'exemple suivant lit la version d'une DLL et la copie dans une version lisible par un humain dans la variable $0 :

GetDllVersion "$INSTDIR\MaDLL.dll" $R0 $R1
IntOp $R2 $R0 / 0x00010000
IntOp $R3 $R0 & 0x0000FFFF
IntOp $R4 $R1 / 0x00010000
IntOp $R5 $R1 & 0x0000FFFF
StrCpy $0 "$R2.$R3.$R4.$R5"

4.9.3.6 GetDLLVersionLocal

fichier_local var_utilisateur(dword haut de destination) var_utilisateur(dword bas de destination)

C'est identique à GetDLLVersion, mais n'agit que sur le système sur lequel a été créé l'installation (il ne se compile que dans deux commandes StrCpy). Définit les deux variables avec les informations de version des DLL du système de compilation.

4.9.3.7 GetFileTime

fichier var_utilisateur(dword haut de destination) var_utilisateur(dword bas de destination)

Récupère la date de dernière modification de "fichier". Stocke les dwords haut et bas de la date dans les variables utilisateurs en cas de succès; en cas d'échec, les variables sont vides, et le flag d'erreur est levé.

4.9.3.8 GetFileTimeLocal

fichier_local var_utilisateur(dword haut de destination) var_utilisateur(dword bas de destination)

Identique à GetFileTime, mais n'agit que sur le système sur lequel a été créé l'installation (il ne se compile que dans deux commandes StrCpy). Définit les deux variables avec la date du fichier du système de compilation.

4.9.3.9 GetFullPathName

[/SHORT] var_utilisateur(destination) rep_ou_fichier

Assigne à la variable utilisateur $x, le répertoire complet du fichier spécifié. Si la partie répertoire du fichier n'est pas retrouvée, le flag d'erreur est levé et $x sera vide. Si /SHORT est spécifié, le répertoire est converti en forme courte (8+3). Mais si /SHORT n'est pas spécifié, le chemin n'est pas converti en sa forme longue. Pour obtenir le nom de chemin long, appelez GetLongPathName avec le plug-in System. Notez que GetLongPathName n'est disponible que sous Windows 98, Windows 2000 et ultérieur.

StrCpy $INSTDIR $PROGRAMFILES\NSIS
SetOutPath $INSTDIR
GetFullPathName $0 ..
DetailPrint $0 # will print C:\Program Files
GetFullPathName /SHORT $0 $INSTDIR
DetailPrint $0 # will print C:\Progra~1\NSIS

StrCpy $0 C:\Progra~1\NSIS
System::Call 'kernel32::GetLongPathName(t r0, t .r1, i ${NSIS_MAX_STRLEN}) i .r2'
StrCmp $2 error +2
StrCpy $0 $1
DetailPrint $0 # will print C:\Program Files\NSIS, where supported

4.9.3.10 GetTempFileName

var_utilisateur(destination) [rep_base]

Assigne à la variable utilisateur $x, le nom d'un fichier temporaire. Le fichier sera créé, et vous pourrez l'utilisez comme bon vous semble. Le nom du fichier temporaire à la garantie d'être unique. Si vous voulez que le fichier temporaire soit créé dans un autre répertoire que le répertoire temporaire de Windows, spécifiez un rep_base. Supprimez le fichier après l'avoir utilisé.

GetTempFileName $0
File /oname=$0 quelquechose.dat
# fait quelque chose avec quelquechose.dat
Delete $0

4.9.3.11 SearchPath

var_utilisateur(destination) fichier

Assigne à la variable utilisateur $x, le répertoire complet d'un fichier passé en second paramètre. Le flag d'erreur sera levé et $x sera vide si le fichier ne peut être trouvé. Utilisez SearchPath() pour rechercher sur le système des répertoires de ce fichier.

4.9.3.12 SetFileAttributes

fichier attribut1|attribut2|...

Définit les attributs de 'fichier'. Les attributs valides peuvent être combinés à l'aide de | et sont:

NORMAL ou FILE_ATTRIBUTE_NORMAL (vous pouvez utiliser 0 pour abréger)
ARCHIVE ou FILE_ATTRIBUTE_ARCHIVE
HIDDEN ou FILE_ATTRIBUTE_HIDDEN
OFFLINE ou FILE_ATTRIBUTE_OFFLINE
READONLY ou FILE_ATTRIBUTE_READONLY
SYSTEM ou FILE_ATTRIBUTE_SYSTEM
TEMPORARY ou FILE_ATTRIBUTE_TEMPORARY

Le flag d'erreur sera levé si les attributs ne peuvent être modifiés (ex. le fichier n'existe pas, ou vous ne possédez pas les permissions adéquates). Vous ne pouvez que définir des attributs. Il n'est pas possible de les retirer. Si vous voulez supprimer un attribut, utilisez NORMAL. De cette manière, tous les attributs sont supprimés. Cette commande ne gère pas les caractères spéciaux.

4.9.3.13 RegDLL

fichier_dll [nom_point_d_entrée]

Charge la DLL spécifiée et appelle DllRegisterServer (ou nom_point_d_entrée si spécifié). Le flag d'erreur est levé si une erreur se produit (ex. impossibilité de charger la DLL, d'initialiser OLE, de trouver le point d'entrée, ou la fonction a retourné autre chose que ERROR_SUCCESS (=0)).

Utilisez SetOutPath le répertoire courant des DLLs dépendant d'autres DLLs qui sont désormais dans le path ou dans le répertoire Windows. Par exemple, si tout_follette.dll dépend de bar.dll qui est situé dans $INSTDIR, utilisez :

 SetOutPath $INSTDIR
 RegDLL $INSTDIR\tout_follette.dll

4.9.3.14 UnRegDLL

fichier_dll

Enlève de la mémoire la DLL spécifiée et appelle DllUnregisterServer. Le flag d'erreur est levé si une erreur survient (ex. impossibilité de charger la DLL, d'initialiser OLE, de trouver le point d'entrée, ou une fonction a retourné autre chose que ERROR_SUCCESS (=0)).

4.9.4 Instructions de contrôle de flux

4.9.4.1 Abort

message_utilisateur

Annule l'installation, arrête l'exécution du script, et affiche message_utilisateur dans l'affichage de l'état. Note: vous pouvez l'utiliser depuis des fonctions d'interaction à des fins spécifiques. Les fonctions d'interactions associées aux pages utiliseront aussi Abort à des fins spécifiques.

Abort
Abort "impossible d'installer"

4.9.4.2 Call

nom_fonction | :nom_label | variable_utilisateur(entrée)

Appelle la fonction nommée nom_fonction, le label nommé nom_label, ou une variable qui spécifie une adresse. Une adresse est retournée par GetCurrentAddress, GetFunctionAddress ou GetLabelAddress. Un appel retourne quand il rencontre une instruction Return. Les sections et fonctions sont terminées automatiquement par une instruction Return. Les fonctions de désinstallation ne peuvent pas être appelées depuis les fonctions de l'installateur et les sections, et vice-versa.

Function func
  Call :label
  DetailPrint "#1: This will only appear 1 time."
label:
  DetailPrint "#2: This will appear before and after message #1."
  Call :.global_label
FunctionEnd

Section
  Call func
  Return

.global_label:
  DetailPrint "#3: The global label was called"
SectionEnd

4.9.4.3 ClearErrors

Efface le flag d'erreur.

ClearErrors
IfErrors 0 +2
  MessageBox MB_OK "ce message ne se verra jamais"

4.9.4.4 GetCurrentAddress

var_utilisateur(destination)

Obtient l'adresse de l'instruction en cours (GetCurrentAddress) et la stocke dans la variable utilisateur. Cette variable utilisateur peut être passée par Call ou Goto.

Function func
  DetailPrint "fonction"
  IntOp $0 $0 + 2
  Call $0
  DetailPrint "fin fonction"
FunctionEnd

Section
  DetailPrint "section"
  DetailPrint "section"
  GetCurrentAddress $0
  Goto callFunc

  DetailPrint "retour à la section"
  Return

callFunc:
  Call func
  DetailPrint "fin section"
SectionEnd

4.9.4.5 GetFunctionAddress

var_utilisateur(destination) fonction

Obtient l'adresse de la fonction et la stocke dans la variable utilisateur. Cette variable utilisateur peut être passée par Call ou Goto. Notez que si vous faites un Goto une adresse qui est la le résultat de GetFunctionAddress, votre fonction ne sera jamais retournée (lorsque la fonction appelée par Goto retourne une valeur, vous retournez une valeur instantanément).

Function func
  DetailPrint "fonction"
FunctionEnd

Section
  GetFunctionAddress $0 func
  Call $0
SectionEnd

4.9.4.6 GetLabelAddress

var_utilisateur(destination) titre

Obtient l'adresse du label et la stocke dans la variable utilisateur. Cette variable utilisateur peut être passée par Call ou Goto. Note que vous ne pourrez que l'appeler que pour des labels accessibles depuis votre fonction, mais vous pourrez l'appeler de n'importe où ensuite (ce qui peut être potentiellement dangereux). Notez que si vous appelez la valeur de retour de GetLabelAddress, le code sera exécuté jusqu'à ce qu'il revoit une valeur (explicitement ou implicitement à la fin de la fonction), et alors vous reviendrez à l'état après l'appel.

label:
DetailPrint "label"
GetLabelAddress $0 label
IntOp $0 $0 + 4
Goto $0
DetailPrint "fait"

4.9.4.7 Goto

label_a_atteindre | +pos| pos| var_utilisateur(cible)

Si le label est spécifié, aller au label 'label_a_atteindre:'.

Si +pos ou -pos est spécifié, le saut est relatif aux instructions de position. Goto +1 va à l'instruction suivante, Goto -1 retourne à l'instruction précédente, etc.

Si une variable utilisateur est spécifiée, on saute vers une adresse absolue (généralement, vous obtiendrez la valeur depuis la fonction GetLabelAddress). Les instructions de compilation et les SectionIn ne sont pas des instructions et les sauter n'auront aucun effet.

Goto label
Goto +2
Goto -2
Goto $0

4.9.4.8 IfAbort

aller_a_si_abandon [aller_a_si_non_abandon]

Si abort est appelé, il "retournera" vrai. Cela peut arriver si l'utilisateur choisit d'abandonner si un fichier ne peut pas être créé (ou écraser) ou si l'utilisateur a annulé de lui-même. Cette fonction ne peux être appelée que depuis une fonction leave de la page instfiles.

Page instfiles "" "" instfilesLeave

Function instfilesLeave
  IfAbort 0 +2
    MessageBox MB_OK "annulé par l'utilisateur"
FunctionEnd

4.9.4.9 IfErrors

aller_a_si_erreur [aller_a_si_pas_erreur]

Vérifie et efface le flag d'erreur, et, s'il est levé, il effectuera un goto aller_a_si_erreur , sinon, il effectuera un goto aller_a_si_pas_erreur. Le flag d'erreur est levé par une autre instruction lorsqu'une erreur récupérable survient (tel qu'essayer de supprimer un fichier en cours d'utilisation).

ClearErrors
File file.dat
IfErrors 0 +2
  Call ErrorHandler

4.9.4.10 IfFileExists

fichier_a_vérifier saut_si_présent [saut_sinon]

Vérifie l'existence de fichier(s) fichiers_a_vérifier (qui peut aussi être un filtre, ou un répertoire), et Goto saut_si_présent si le fichier existe, sinon, Goto saut_sinon. Si vous voulez vérifier pourvoir si un fichier est un répertoire, utilisez IfFileExists REPERTOIRE\*.*

IfFileExists $WINDIR\notepad.exe 0 +2
  MessageBox MB_OK "notepad est installé"

4.9.4.11 IfRebootFlag

[saut_si_present] [saut_sinon]

Vérifie la présence du flag de redémarrage, et saute à saut_si_present si le flag de redémarrage est levé, sinon, saute à saut_sinon. Le flag de redémarrage peut être levé par Delete et Rename, ou manuellement par SetRebootFlag.

IfRebootFlag 0 noreboot
  MessageBox MB_YESNO "un redémarrage est requis pour terminer l'installation. Voulez-vous redémarrer maintenant?" IDNO noreboot
    Reboot
noreboot:

4.9.4.12 IfSilent

[saut_si_silencieux] [saut_sinon]

Au moins un paramètre est requis. Vérifie le flag du mode silencieux, et saute vers saut_si_silencieux si l'installation est silencieuse, sinon saute vers saut_sinon. Le flag du mode silencieux peut être définit par SilentInstall, SilentUninstall, SetSilent ainsi que par l'utilisateur en passant /S en ligne de commandes.

IfSilent +2
  ExecWait '"$INSTDIR\programmenonsilencieux.exe"'

4.9.4.13 IntCmp

val1 val2 saut_si_egal [saut_si_val1_inf] [saut_si_val1_sup]

Compare deux entiers val1 et val2. Si val1 et val2 sont égaux, Goto saut_si_egal, sinon, si val1 < val2, Goto saut_si_val1_inf, sinon, si val1 > val2, Goto saut_si_val1_sup.

IntCmp $0 5 is5 lessthan5 morethan5
is5:
  DetailPrint "$$0 == 5"
  Goto done
lessthan5:
  DetailPrint "$$0 < 5"
  Goto done
morethan5:
  DetailPrint "$$0 > 5"
  Goto done
done:

4.9.4.14 IntCmpU

val1 val2 saut_si_egal [saut_si_val1_inf] [saut_si_val1_sup]

Compare deux entiers non signés val1 et val2. Si val1 et val2 sont égaux, Goto saut_si_egal, sinon, si val1 < val2, Goto saut_si_val1_inf, sinon, si val1 > val2, Goto saut_si_val1_sup. La comparaison est effectuée comme sur des entiers non signés.

4.9.4.15 MessageBox

liste_options_mb texte_messagebox [/SD return] [verif_retour aller_à] [verif_retour_2 aller_à_2]

Affiche une boite de dialogue contenant le texte "texte_messagebox". liste_options_mb doit être une ou plusieurs des options suivantes, délimitées par | (ex. MB_YESNO|MB_ICONSTOP).

MB_OK - Affichage avec un bouton OK
MB_OKCANCEL - Affichage avec les boutons OK ou Annuler
MB_ABORTRETRYIGNORE - Affichage avec les boutons Abandonner, Réessayer ou Ignorer
MB_RETRYCANCEL - Affichage avec les boutons Réessayer ou Annuler
MB_YESNO - Affichage avec les boutons Oui ou Non
MB_YESNOCANCEL - Affichage avec les boutons Oui, Non ou Annuler
MB_ICONEXCLAMATION - Affichage avec une icône d'exclamation
MB_ICONINFORMATION - Affichage avec une icône d'information
MB_ICONQUESTION - Affichage avec une icône de point d'interrogation
MB_USERICON - Affiche l'icône de l'installateur
MB_ICONSTOP - Affichage avec une icône stop
MB_TOPMOST - Fait que la boite de dialogue surplombe toutes les fenêtres
MB_SETFOREGROUND - Définit l'avant-plan
MB_RIGHT - Alignement du texte à droite
MB_DEFBUTTON1 - Bouton 1 est celui par défaut
MB_DEFBUTTON2 - Bouton 2 est celui par défaut
MB_DEFBUTTON3 - Bouton 3 est celui par défaut
MB_DEFBUTTON4 - Bouton 4 est celui par défaut

verif_retour peut être 0 (ou vide, ou laissé de côté), ou l'une des valeurs suivantes:

IDABORT - Bouton Abandonner
IDCANCEL - Bouton Annuler
IDIGNORE - Bouton Ignorer
IDNO - Bouton Non
IDOK - Bouton OK
IDRETRY - Bouton Réessayer
IDYES - Bouton Oui

Si la valeur de retour de la boite de dialogue est verif_retour, l'installation effectuera un Goto aller_à.

Utilisez le paramètre /SD avec une des valeurs verif_retour aller_à pour spécifier l'option utilisée lorsque l'installation est silencieuse. Voir section 4.12 pour plus d'informations.

MessageBox MB_OK "fenêtre simple de message"
MessageBox MB_YESNO "est-ce vrai?" IDYES true IDNO false
true:
  DetailPrint "c'est vrai!"
  Goto next
false:
  DetailPrint "c'est faux"
next:
MessageBox MB_YESNO "c'est vrai? (défauts oui si install silencieuse)" /SD IDYES IDNO false2
  DetailPrint "c'est vrai (ou silencieux)!"
  Goto next2
false2:
  DetailPrint "c'est faux"
next2:

4.9.4.16 Return

Retour d'une fonction ou d'une section.

Function func
  StrCmp $0 "return now" 0 +2
    Return
  # do stuff
FunctionEnd

Section
  Call func
  ;"Return" will return here
SectionEnd

4.9.4.17 Quit

Force l'installation à quitter aussitôt que possible. Après l'appel de Quit, l'installation quittera (aucune fonction ne pourra être exécutée alors).

4.9.4.18 SetErrors

Lève le flag d'erreur.

SetErrors
IfErrors 0 +2
  MessageBox MB_OK "Ce message sera toujours visible"

4.9.4.19 StrCmp

str1 str2 saut_si_egal [saut_si_inégal]

Compare (insensible à la casse) txt1 à txt2. Si txt1 et txt2 sont égaux, aller à saut_si_egal, sinon, Goto saut_si_inégal.

StrCmp $0 "une chaine" 0 +3
  DetailPrint '$$0 == "une chaine"'
  Goto +2
  DetailPrint '$$0 != "une chaine"'

4.9.4.20 StrCmpS

str1 str2 saut_si_egal [saut_si_inégal]

Comme StrCmp, mais sensible à la casse.

4.9.5 Instructions de gestion des fichiers

4.9.5.1 FileClose

index_fichier

Ferme un fichier ouvert avec FileOpen.

4.9.5.2 FileOpen

var_utilisateur(index_fichier) fichier mode_ouverture

Ouvre un fichier nommé "fichier", et défini l'index_fichier avec son identifiant. Le mode_ouverture doit être l'un des suivants : "r" (lecture),"w" (écriture, le contenu du fichier étant détruit) ou "a" (append, signifiant à la fois lecture et écriture, le contenu restant préservé). Dans tous les modes, le pointeur de fichier est placé au défaut du fichier. Si le fichier ne peut être ouvert, l'index_fichier est vide et le flag d'erreur est levé.

Si aucun chemin absolu n'est spécifié, le dossier courant est utilisé. Le dossier courant est le dossier défini par la dernière instruction SetOutPath. Si vous n'avez pas utilisé SetOutPath, le dossier courant est $EXEDIR.

FileOpen $0 $INSTDIR\file.dat r
FileClose $0

4.9.5.3 FileRead

index_fichier var_utilisateur(destination) [taille_max]

Lit une chaîne de caractères depuis un fichier ouvert à l'aide de FileOpen. La chaîne est lue jusqu'à une nouvelle ligne (ou un paire retour chariot nouvelle ligne), jusqu'à un octet null, ou même jusqu'à ce que taille_max soit atteinte (si spécifié). Par défaut les chaînes sont limitées à 1024 caractères (une version spéciale avec un NSIS_MAX_STRLEN plus grand peut être compilée ou téléchargée). Si la fin de fichier est lue et qu'une donnée ne soit plus disponible, la chaîne sera vide, et le flag d'erreur sera levé.

ClearErrors
FileOpen $0 $INSTDIR\file.dat r
IfErrors done
FileRead $0 $1
DetailPrint $1
FileClose $0
done:

4.9.5.4 FileReadByte

index_fichier var_utilisateur(destination)

Lit un octet depuis le fichier ouvert avec FileOpen. L'octet est stocké dans la variable utilisateur comme un entier (entre 0 et 255). Si la fin de fichier est atteinte, et qu'aucune donnée ne soit plus disponible, retour sera vide et le flag d'erreur sera levé

ClearErrors
FileOpen $0 $INSTDIR\file.dat r
IfErrors done
FileReadByte $0 $1
FileReadByte $0 $2
DetailPrint "$1 $2"
FileClose $0
done:

4.9.5.5 FileSeek

index_fichier pos [mode] [var_utilisateur(nvll_pos)]

Déplace le pointeur d'un fichier ouvert à l'aide de FileOpen. Si mode est omis ou spécifié comme SET, le fichier est positionné en "pos", selon le début du fichier. Si mode est spécifié comme CUR, alors le pointeur est déplacé de pos, selon le début du fichier. Si mode est spécifié comme END, le pointeur sera positionnera en relatif à EOF (Fin Du Fichier), selon lafin du fichier. Si le paramètre final "nvll_pos" est spécifié, la nouvelle position du fichier sera stockée dans cette variable.

ClearErrors
FileOpen $0 $INSTDIR\file.dat r
IfErrors done
FileSeek $0 -5 END
FileRead $0 $1
DetailPrint $1
FileClose $0
done:

4.9.5.6 FileWrite

index_fichier chaîne

Ecrit une chaîne dans un fichier ouvert à l'aide de FileOpen. Si une erreur apparait, le flag d'erreur est levé.

ClearErrors
FileOpen $0 $INSTDIR\file.dat w
IfErrors done
FileWrite $0 "some text"
FileClose $0
done:

4.9.5.7 FileWriteByte

index_fichier chaîne

Ecrit l'interprétation entière de 'chaîne' dans une fichier ouvert à l'aide de FileOpen. Bien entendu, vous pouvez entrer une valeur entière directement. Le code suivant écrit un "retour chariot / saut de ligne" - Entrée dans le fichier.

FileWriteByte index_fichier "13"
FileWriteByte index_fichier "10"

Si une erreur apparait, le flag d'erreur sera levé. Notez que l'octet bas de l'entier est utilisé, ex. écrire 256 est identique à écrire 0, etc.

4.9.5.8 FindClose

index_fichier

Ferme une recherche lancée par FindFirst.

4.9.5.9 FindFirst

var_utilisateur(index_recherche) var_utilisateur(fichier) spec_fichier

Effectue la recherche de 'spec_fichier', plaçant le premier fichier trouvé dans fichier (variable utilisateur). Il place aussi l'index de la recherche dans index_recherche (variable utilisateur). Si aucun fichier n'est trouvé, les deux variables sont vides, et le flag d'erreur est levé. A utiliser de préférence avec FindNext et FindClose. Notez que fichier ne contient pas l'arborescence.

FindFirst $0 $1 $INSTDIR\*.txt
loop:
  StrCmp $1 "" done
  DetailPrint $1
  FindNext $0 $1
  Goto loop
done:

4.9.5.10 FindNext

index_recherche var_utilisateur(fichier)

Continue une recherche débutée avec FindFirst. index_recherche doit être le même retourné par FindFirst. Si la recherche est terminée (plus de fichiers), fichier est vidé, et le flag d'erreur est levé. Notez que fichier ne contient pas le chemin.

4.9.6 Instructions de désinstallation

4.9.6.1 WriteUninstaller

[chemin\]executable.exe

Génère une désinstallation dans le fichier (et occasionnellement le répertoire) spécifié. Seulement valide à l'intérieur d'une section ou fonction d'installation, et requiert que vous possédiez la section de désinstallation dans votre script. Voir aussi Configuration de la désinstallation. Vous pouvez l'appeler une ou plusieurs fois pour écrire autant de copie du désinstalleur que vous le voulez.

WriteUninstaller $INSTDIR\uninstaller.exe

4.9.7 Instructions diverse

4.9.7.1 GetErrorLevel

variable_utilisateur(sortie niveau d'erreur)

Retourne le dernier niveau d'erreur défini par SetErrorLevel ou -1 si jamais utilisé.

GetErrorLevel $0
IntOp $0 $0 + 1
SetErrorLevel $0

4.9.7.2 GetInstDirError

variable_utilisateur(erreur)

Utilisez dans la fonction leave ou sur la page directory. Vérifie si le flag est défini si 'DirVerify leave' est utilisé. Les valeurs possibles sont :

0 : Aucune erreur

1 : Répertoire d'installation incorrect

2 : Pas assez d'espace disque sur le lecteur d'installation

!include LogicLib.nsh
PageEx directory
  DirVerify leave
  PageCallbacks "" "" dirLeave
PageExEnd

Function dirLeave
  GetInstDirError $0
  ${Switch} $0
    ${Case} 0
      MessageBox MB_OK "répertoire d'installation valide"
      ${Break}
    ${Case} 1
      MessageBox MB_OK "répertoire d'installation invalide!"
      Abort
      ${Break}
    ${Case} 2
      MessageBox MB_OK "pas assez d'espace libre!"
      Abort
      ${Break}
  ${EndSwitch}
FunctionEnd

4.9.7.3 InitPluginsDir

Définit le répertoire des plug-ins ($PLUGINSDIR) s'il n'a pas été préalablement initialisé.

InitPluginsDir
File /oname=$PLUGINSDIR\image.bmp image.bmp

4.9.7.4 Nop

Ne fait rien.

4.9.7.5 SetErrorLevel

niveau_erreur

Défini le niveau d'erreur de l'installateur ou de la désinstallation à error_level. Voir Error Levels pour plus d'informations.

IfRebootFlag 0 +2
  SetErrorLevel 4

4.9.7.6 SetRegView

32|64

Défini la vue du registre affectée par les commandes du registre. Sur Windows x64 il y a deux vues. Une pour les applications 32-bit et une pour les applications x64. Par défaut, les applications 32-bit lancées sous les systèmes x64 dans WOW64 accèdent seulement à la vue 32-bit. Avec SetRegView 64 ceci permet à l'installateur d'accéder à la vue x64 du registre.

Affecte DeleteRegKey, DeleteRegValue, EnumRegKey, EnumRegValue, ReadRegDWORD, ReadRegStr, WriteRegBin, WriteRegDWORD, WriteRegStr et WriteRegExpandStr.

N'affecte pas InstallDirRegKey. A la place le registre peut être lu avec ReadRegStr dans .onInit.

SetRegView 32
ReadRegStr $0 HKLM Software\Microsoft\Windows\CurrentVersion ProgramFilesDir
DetailPrit $0 # prints C:\Program Files (x86)
SetRegView 64
ReadRegStr $0 HKLM Software\Microsoft\Windows\CurrentVersion ProgramFilesDir
DetailPrit $0 # prints C:\Program Files

Function .onInit
  SetRegView 64
  ReadRegStr $INSTDIR HKLM Software\NSIS ""
  SetRegView 32
FunctionEnd

4.9.7.7 SetShellVarContext

current|all

Définit le contexte de $SMPROGRAMS et de d'autres dossiers systèmes. S'il est défini comme 'current' (courant), par défaut, les dossiers systèmes de l'utilisateur courant seront utilisés. S'il est défini en 'all' (tous), les dossiers systèmes communs à tous les utilisateurs ('all users') seront utilisés. Les dossiers communs peuvent ne pas être supportés par tous les systèmes d'exploitation. Si ces dossiers ne sont pas trouvés, alors les dossiers de l'utilisateur courant seront utilisés. Veuillez prendre en considération qu'un "utilisateur normal" n'a pas la possibilité d'écrire dans la zone all users. Seuls les administrateurs possèdent les droits d'accès complets dans la zone all users. Vous pouvez vérifier cela en utilisant le plug-in UserInfo. Voir Contrib\UserInfo\UserInfo.nsi pour un exemple.

Notez que, si utilisé dans la code de l'installateur, ceci n'affectera que l'installateur, et si utilisé dans le code du désinstallateur, ceci n'affectera que le désinstallateur. Pour affecter les deux, il doit être utilisé deux fois.

SetShellVarContext current
StrCpy $0 $DESKTOP
SetShellVarContext all
StrCpy $1 $DESKTOP
MessageBox MB_OK $0$\n$1

4.9.7.8 Sleep

temps_en_ms

Gèle l'exécution de l'installation de temps_en_ms millisecondes. temps_en_ms peut être une variable, ex. "$0" ou un nombre (ex. "666").

DetailPrint "sommeil..."
Sleep 3000
DetailPrint "Au travail"

4.9.8 Instructions de manipulation de chaînes de caractères

4.9.8.1 StrCpy

var_utilisateur(destination) chaîne [taillemax] [pos_depart]

Défini la variable utilisateur $x avec chaîne. Notez que chaîne peut contenir d'autres variables, ou la variable utilisateur elle-même (la concaténation des chaînes est possible de cette manière, etc.). Si taillemax est spécifié, a chaîne aura un nombre de caractères maximum de taillemax (si taillemax est négatif, la chaîne sera tronquée de val_abs(taillemax) caractères depuis la fin). Si pos_depart est spécifié, la source s'y positionne (si pos_offset est négatif, ce sera val_abs(pos_depart) depuis la fin de la chaîne).

StrCpy $0 "a string" # = "a string"
StrCpy $0 "a string" 3 # = "a s"
StrCpy $0 "a string" -1 # = "a strin"
StrCpy $0 "a string" "" 2 # = "string"
StrCpy $0 "a string" "" -3 # = "ing"
StrCpy $0 "a string" 3 -4 # = "rin"

4.9.8.2 StrLen

var_utilisateur(taille) chaîne

Défini la variable utilisateur $x avec la taille de chaîne.

StrLen $0 "123456" # = 6

4.9.9 Support des piles

4.9.9.1 Exch

[var_utilisateur] | index_pile

Lorsque qu'aucun paramètre n'est spécifié, échange les deux premier éléments de la pile. Lorsqu'un paramètre est spécifié, et que celui ci est la variable utilisateur, échange l'élément en haut de la pile avec le paramètre. Lorsqu'un paramètre est spécifié, et que celui ci est en entier positif, le paramètre Spécifie quel élément de la pile doit être échangé avec le haut de la pile. S'il n'y a pas assez d'éléments dans la pile pour accomplir cet échange, une erreur fatale se produira (pour vous aider à débugger votre code :).

Push 1
Push 2
Exch
Pop $0 # = 1

Push 1
Push 2
Push 3
Exch 2
Pop $0 # = 1

StrCpy $0 1
Push 2
Exch $0 # = 2
Pop $1 # = 1

4.9.9.2 Pop

var_utilisateur(destination)

Dépile une chaîne et la place dans la variable utilisateur $x. Si la pile est vide, le flag d'erreur est levé.

Push 1
Pop $0 # = 1

4.9.9.3 Push

chaîne

Place une chaîne en haut de la pile. La chaîne pourra ensuite être dépilé.

Push "a string"

4.9.10 Support des entiers

4.9.10.1 IntFmt

var_utilisateur(destination) format chaîne_nombre

Formate le nombre "chaîne_nombre" en utilisant le format "format", et stocke le résultat dans la variable utilisateur $x. Exemple de formats : "%08X" "%u" etc.

IntFmt $0 "0x%08X" 195948557
IntFmt $0 "%c" 0x41

4.9.10.2 IntOp

var_utilisateur(destination) valeur1 OP [valeur2]

Combine valeur1 et (selon l'OP) valeur2 dans la variable utilisateur spécifiée (user_var). OP est défini comme un des suivants:

+ AJOUTE valeur1 à valeur2
- SOUSTRAIT valeur2 de valeur1
* MULTIPLIE valeur1 et valeur2
/ DIVISE valeur1 par valeur2
% MODULE valeur1 par valeur2
| OU BINAIRE de valeur1 sur valeur2
& ET BINAIRE de valeur1 sur valeur2
^ OU EXCLUSIF BINAIRE de valeur1 sur valeur2
>> RIGHT SHIFTs valeur1 par valeur2
<< LEFT SHIFTs valeur1 par valeur2
~ NEGATION BINAIRE de valeur1 (ex. 7 devient 4294917288)
! NEGATION LOGIQUE de valeur1 (ex. 7 devient 0)
|| OU LOGIQUE de valeur1 sur valeur2
&& ET LOGIQUE de valeur1 sur valeur2

IntOp $0 1 + 1
IntOp $0 $0 + 1
IntOp $0 $0 << 2
IntOp $0 $0 ~
IntOp $0 $0 & 0xF

4.9.11 Instructions de redémarrage

4.9.11.1 Reboot

Redémarre l'ordinateur. Soyez attentif avec cette fonction. S'il y a une erreur en redémarrant, cette fonction lève le flag d'erreur et continue. Si le redémarrage est un succès, cette fonction ne retourne rien.

MessageBox MB_YESNO|MB_ICONQUESTION "Voulez-vous redémarrer le système?" IDNO +2
  Reboot

4.9.11.2 SetRebootFlag

true|false

Définit le flag de redémarrage par true (vrai) ou false (faux).

SetRebootFlag true
IfRebootFlag 0 +2
  MessageBox MB_OK "ce message sera toujours affiché"

4.9.12 Instructions de journalisation de l'installation

4.9.12.1 LogSet

on|off

Définit si oui ou non l'installation créera un journal en $INSTDIR\install.log. $INSTDIR doit avoir une valeur avant d'appeler cette fonction, ou cela ne marchera pas. Notez que l'option de compilation NSIS_CONFIG_LOG doit être définie (scons NSIS_CONFIG_LOG=yes), lors de la compilation (ce qui n'est pas fait par défaut) pour le supporter. Voir Compiler NSIS pour plus d'informations sur la recompilation de NSIS.

4.9.12.2 LogText

texte

Si le journal d'installation est activé, insère le texte "texte" dans le fichier journal.

IfFileExists $WINDIR\notepad.exe 0 +2
  LogText "$$WINDIR\notepad.exe existe"

4.9.13 Gestion des sections

4.9.13.1 SectionSetFlags

index_section flags_section

Définit les flags de la section. Le premier bit (le plus bas) indique si la section est ou pas activée, le second bit indique si la section est ou pas un groupe de section (ne pas modifier à moins de vraiment savoir ce que vous faites), le troisième bit indique si la section est ou pas une fin de groupe de section (là encore, ne pas modifier), le quatrième bit indique si la section est affichée en gras ou pas, le cinquième indique si la section est ou pas en lecture seule et le sixième bit indique si le groupe de section est ou pas automatiquement développée, le septième bit est défini pour les groupes de section qui sont partiellement sélectionnés, le huitième bit est utilisé de façon interne pour les groupes de sections partiellement sélectionnés et le neuvième bit est utilisé pour réfléchir le changement de nom de section. Le flag d'erreur est levé si une section hors limite est spécifiée.

Chaque flag a un nom, prefixé avec `SF_`:

!define SF_SELECTED   1
!define SF_SECGRP     2
!define SF_SECGRPEND  4
!define SF_BOLD       8
!define SF_RO         16
!define SF_EXPAND     32
!define SF_PSELECTED  64

Pour un exemple d'utilisation, voir le script one-section.nsi.

Pour plus de macros utiles et les définitions, voir Include\Sections.nsh.

Section test test_section_id
SectionEnd

Function .onInit
  # set section 'test' as selected and read-only
  IntOp $0 ${SF_SELECTED} | ${SF_RO}
  SectionSetFlags ${test_section_id} $0
FunctionEnd

4.9.13.2 SectionGetFlags

index_section var_utilisateur(destination)

Recherche le flags de la section. Voir SectionSetFlags pour la description des flags. Le flag d'erreur est levé si index_section n'est pas un index de section.

Section test test_section_id
SectionEnd

Function .onSelChange
  # keep section 'test' selected
  SectionGetFlags ${test_section_id} $0
  IntOp $0 $0 | ${SF_SELECTED}
  SectionSetFlags ${test_section_id} $0
FunctionEnd

4.9.13.3 SectionSetText

index_section texte_section

Définie la description pour la section index_section. Pour définir un groupe de section, vous devez utiliser - au début du texte. Si le texte est "" alors la section sera cachée. Le flag d'erreur est levé si index_section n'est pas un index de section.

Section "" test_section_id
SectionEnd

Function .onInit
  # change section's name to $WINDIR
  SectionSetText ${test_section_id} $WINDIR
FunctionEnd

4.9.13.4 SectionGetText

index_section var_utilisateur(destination)

Stocke la description de la section index_section dans la variable utilisateur. Si la section est invisible, la variable contiendra une chaîne vide. Le flag d'erreur est levé si index_section n'est pas un index de section.

Section test test_section_id
SectionEnd

Function .onInit
  # append $WINDIR to section's name
  SectionGetText ${test_section_id} $0
  StrCpy $0 "$0 - $WINDIR"
  SectionSetText ${test_section_id} $0
FunctionEnd

4.9.13.5 SectionSetInstTypes

index_section types_install

Définie les types d'installation pour lesquels la section spécifiée par index_section sera automatiquement activée. Notez que l'index des sections commence à zéro. Chaque bit de types_install est un flag indiquant si la section est ou pas dans ce type d'installation. Par exemple, si vous avez 3 types d'installation et que vous voulez que la première section soit inclue dans les types d'installation 1 et 3, alors la commande ressemblera à :

SectionSetInstTypes 0 5

car la valeur binaire de 5 est "00000101". Le flag d'erreur est levé si l'index de la section est hors limite.

Section test test_section_id
SectionEnd

Function .onInit
  # associate section 'test' with installation types 3 and 4
  SectionSetInstTypes ${test_section_id} 12
FunctionEnd

4.9.13.6 SectionGetInstTypes

index_section var_utilisateur(destination)

Retrouve le tableau des types d'installation associés à une section. Voir ci-dessus pour l'explication de SectionSetInstTypes pour avoir une description sur ce que contiendra la sortie. Le flag d'erreur est levé si l'index de la section est hors limite.

Section test test_section_id
SectionEnd

Function .onInit
  # associate section 'test' with installation types 5, on top of its existing associations
  SectionGetInstTypes ${test_section_id} $0
  IntOp $0 $0 | 16
  SectionSetInstTypes ${test_section_id} $0
FunctionEnd

4.9.13.7 SectionSetSize

index_section nouvelle_taille

Définit la taille de la section spécifiée par index_section. Notez que l'index de la première section est zéro. La valeur de la taille doit être en kilo octets et ne doit contenir que des nombres.

Section test test_section_id
SectionEnd

Function .onInit
  # set required size of section 'test' to 100 bytes
  SectionSetSize ${test_section_id} 100
FunctionEnd

4.9.13.8 SectionGetSize

index_section var_utilisateur

Récupère la taille de la section spécifiée par index_section et stocke dans la valeur dans la variable utilisateur fournie. Notez que l'index de la première section est zéro.

Section test test_section_id
SectionEnd

Function .onInit
  # increase required size of section 'test' by 100 bytes
  SectionGetSize ${test_section_id} $0
  IntOp $0 $0 + 100
  SectionSetSize ${test_section_id} $0
FunctionEnd

4.9.13.9 SetCurInstType

index_section

Définit le InstType courant. Le flag d'erreur n'est pas levé si un index hors limite a été spécifié.

SetCurInstType ne fonctionne que si la page des composants est présente.

4.9.13.10 GetCurInstType

var_utilisateur

Récupère le InstType courant et le stocke dans la valeur dans la variable utilisateur fournie. La valeur de ${NSIS_MAX_INST_TYPES} (32 par défaut) signifit que le type installation personnalisée a été sélectionné.

4.9.13.11 InstTypeSetText

index_installtypetexte

Défini le texte de l'InstType spécifié. Si le texte est vide, alors l'InstType est enlevé. En utilisant un nombre index_installtype non utilisé précédemment, vous pouvez en créer de nouveaux. Pour ajouter/supprimer des sections à ces types d'installation, voir SectionSetInstTypes. Contrairement à SectionIn, l'index commence à 0, ce qui signifie que le premier type d'installation a comme index 0.

InstType a
InstType b

Function .onInit
  # set first installation type's name to $WINDIR
  InstTypeSetText 0 $WINDIR
  # set second installation type's name to $TEMP
  InstTypeSetText 1 $TEMP
FunctionEnd

4.9.13.12 InstTypeGetText

index_installtype var_utilisateur

Récupère le texte du type d'installation spécifié.

InstType a
InstType b

Function .onInit
  InstTypeGetText 0 $0
  DetailPrint $0 # prints 'a'
  InstTypeGetText 1 $0
  DetailPrint $0 # prints 'b'
FunctionEnd

4.9.14 Instructions de l'interface utilisateur

4.9.14.1 BringToFront

Fait que la fenêtre d'installation soit visible et se trouve au-dessus de toutes les autres fenêtres (ex. si une commande est exécutée et qui se place au-dessus de l'installation, un BringToFront redonnera le focus à l'installation).

De récentes versions de Windows empêchent de placer une fenêtre en avant-plan. Si l'utilisateur travaille avec une autre application pendant l'installation, l'utilisateur sera informé en utilisant une autre méthode.

4.9.14.2 CreateFont

var_utilisateur(destination) police [hauteur] [largeur] [/ITALIC] [/UNDERLINE] [/STRIKE]

Créé une police et la place dans var_utilisateur. Pour plus d'informations sur les différents paramètres, allez voir la page MSDN à propos de la fonction CreateFont() de l'API Win32.

Vous pouvez obtenir la police utilisée par NSIS avec les LangStrings ^Font et ^FontSize.

!include WinMessages.nsh
GetDlgItem $0 $HWNDPARENT 1
CreateFont $1 "Times New Roman" "7" "700" /UNDERLINE
SendMessage $0 ${WM_SETFONT} $1 1

4.9.14.3 DetailPrint

message_utilisateur

Ajoute la chaîne "message_utilisateur" dans l'affichage des détails de l'installation.

DetailPrint "ce message sera affiché dans la fenêtre d'installation"

4.9.14.4 EnableWindow

hwnd (1|0)

Active ou désactive l'entrée souris et clavier sur la fenêtre ou contrôle spécifié. Les états possibles sont 0 (désactivé) ou 1 (activé).

GetDlgItem $0 $HWNDPARENT 1
EnableWindow $0 0
Sleep 1000
EnableWindow $0 1

4.9.14.5 FindWindow

var_utilisateur(destination) classe_fenêtre [titre_fenêtre] [fenêtre_parent] [fils_après]

Recherche une fenêtre. Réagit comme l'API win32 FindWindowEx(). Recherche par classe_fenêtre (et/ou titre_fenêtre si spécifié). Si fenêtre_parent ou fille_après sont spécifiés, la recherche sera restrictive d'autant. Si classe_fenêtre ou titre_fenêtre sont spécifiés comme "", ils ne seront pas utilisés par la recherche. Si la fenêtre n'est pas trouvée, la variable utilisateur retournée est 0. Pour obtenir le comportement du vieux FindWindow, utilisez FindWindow avec SendMessage.

FindWindow $0 "#32770" "" $HWNDPARENT
FindWindow $0 "my window class" "my window title"

4.9.14.6 GetDlgItem

var_utilisateur(destination) fenêtre id_elt

Recherche le handle d'un contrôle identifié par id_elt dans la boite de dialogue spécifiée fenêtre. Si vous voulez obtenir l'handle du contrôle à l'intérieur de la fenêtre, utilisez d'abord FindWindow var_utilisateur(destination) "#32770" "" $HWNDPARENT pour obtenir l'handle de la fenêtre en cours.

GetDlgItem $0 $HWNDPARENT 1 # next/install button

4.9.14.7 HideWindow

Cache l'installation.

4.9.14.8 IsWindow

HWND saut_si_fenêtre [saut_si_pas_fenêtre]

Si HWND est une fenêtre, Goto saut_si_fenêtre, sinon, Goto saut_si_pas_fenêtre (si spécifié).

GetDlgItem $0 $HWNDPARENT 1
IsWindow $0 0 +3
  MessageBox MB_OK "found a window"
  Goto +2
  MessageBox MB_OK "no window"

4.9.14.9 SendMessage

HWND msg wparam lparam [var_utilisateur(valeur_retour)] [/TIMEOUT=temps_en_ms]

Envoie un message à HWND. Si la variable utilisateur $x est spécifiée comme dernier paramètre(ou l'avant-dernier sur vous utilisez /TIMEOUT), la valeur de retour de SendMessage y sera stockée. Notez que lors de la spécification de 'msg', vous ne devrez utiliser que la valeur entière du message. Si vous voulez envoyer des chaînes de caractères, utilisez "STR:texte" comme wParam / lParam, ou vous en avez besoin.

WM_CLOSE 16
WM_COMMAND 273
WM_USER 1024

Incluez ${NSISDIR}\Examples\WinMessages.nsh pour obtenir tous les messages Windows définis dans votre script.

Pour envoyer une chaine en paramètre, placez STR: avant le paramètre, par exemple: "STR:Une chaîne".

Utilisez /TIMEOUT=temps_en_ms pour spécifier la durée en millisecondes de la période de time-out.

!include WinMessages.nsh
FindWindow $0 "Winamp v1.x"
SendMessage $0 ${WM_CLOSE} 0 0

4.9.14.10 SetAutoClose

true|false

Ecrase le flag de fermeture automatique de la fenêtre par défaut (spécifié pour l'installation en utilisant AutoCloseWindow, et à false pour la désinstallation). Mettez 'true' (vrai) pour que la fenêtre d'installation disparaisse immédiatement à la fin de l'installation, ou 'false' (faux) qui requière une fermeture manuelle.

4.9.14.11 SetBrandingImage

[/IMGID=id_element_dans_fenetre] [/RESIZETOFIT] chemin_vers_image.bmp

Définit le fichier image comment image de marque. Si aucun IMGID n'est spécifié, le premier contrôle d'image trouvé sera utilisé, ou bien le contrôle d'image créer par AddBrandingImage. Notez que cette image doit être présente sur la machine de l'utilisateur. Utilisez tout d'abord File pour l'y placer. Si /RESIZETOFIT est spécifié, l'image sera automatiquement retaillée (très pauvrement) à la taille du contrôle d'image. Si vous utilisez AddBrandingImage, vous pourrez obtenir la taille : en compilant votre script et regardez le retour de AddBrandingImage, il vous indiquera la taille. SetBrandingImage ne fonctionnera pas s'il est appelé depuis .onInit!

4.9.14.12 SetDetailsView

show|hide

Affiche (show) ou cache (hide) les détails, ceci dépendant du paramètre passé. Cela écrase l'affichage par défaut des détails, défini par ShowInstDetails.

4.9.14.13 SetDetailsPrint

none|listonly|textonly|both|lastused

Définit le mode utilisé par les commandes pour afficher leur état. None (aucune) fait taire les commandes, listonly (listage seul) fait que seul le texte d'état est ajouté à la liste, textonly (texte seul) fait que le texte d'état n'est affiché que dans la barre d'état, et both (les deux) active les deux (par défaut). Pour extraire beaucoup de petits fichiers, textonly est recommandé (spécialement sous win9x avec un défilement souple activé).

SetDetailsPrint none
File "secret file.dat"
SetDetailsPrint both

4.9.14.14 SetCtlColors

hwnd [/BRANDING] [couleur_texte] [transparent|couleur_arrplan]

Définit une couleur d'arrière-plan et de texte pour un contrôle statique, d'édition, un bouton ou une fenêtre. Utilisez GetDlgItem pour obtenir l'handle (HWND) du contrôle. Pour rendre le contrôle transparent, spécifiez "transparent" comme couleur d'arrière-plan. Vous pouvez aussi spécifier /BRANDING avec ou sans couleur de texte ou d'arrière-plan pour rendre le contrôle totalement gris (ou toute autre couleur spécifiée). C'est utilisé par le texte de du contrôle de marque dans MUI.

FindWindow $0 "#32770" "" $HWNDPARENT
GetDlgItem $0 $0 1006
SetCtlColors $0 0xFF0000 0x00FF00

Attention: Définir la couleur d'arrière-plan de cases à cocher sur "transparent" peut ne pas fonctionner correctement si vous utilisez XPStlye on. L'arrière-plan peut être complètement noir, au lieu d'être transparent, si vous utilisez certains thèmes Windows.

4.9.14.15 SetSilent

silent | normal

Définit l'installation en mode silencieux ou normal. Voir SilentInstall pour plus d'informations sur les installations silencieuses. Ne peut être utilisé que dans .onInit.

4.9.14.16 ShowWindow

hwnd état

Définit la visibilité d'une fenêtre. Les états possibles sont les mêmes que ceux de la fonction ShowWindow de Windows. Les constantes SW_* sont définies dans Include\WinMessages.NSH.

!include WinMessages.nsh
GetDlgItem $0 $HWNDPARENT 1
ShowWindow $0 ${SW_HIDE}
Sleep 1000
ShowWindow $0 ${SW_SHOW}

4.9.15 Instructions du multi-langue

4.9.15.1 LoadLanguageFile

fichier_langue.nlf

Charge un fichier de langue pour la construction d'une table de langue. Tous les fichiers de langue livrés avec NSIS sont placés dans Contrib\Language Files

Après avoir inséré le fichier de langue, ${LANG_langfile} sera défini comme identifiant de langue (par exemple, ${LANG_FRENCH} sera défini comme 1036). Utilisez le avec LangString, LicenseLangString, LangDLL et VIAddVersionKey.

4.9.15.2 LangString

nom id_langue chaîne

Définit une chaîne multilingue. Cela signifie que sa valeur sera différente (ou pas, c'est vous qui voyez) pour chaque langue. Cela vous permet de facilement rendre votre installation multilingue sans avoir à ajouter nombre de switchs à votre script.

Chaque chaîne de langue possède un nom qui l'identifie et une valeur par langue utilisée par l'installation. Elle peut être utilisée par n'importe quelle chaîne dans le script. Pour utiliser une chaîne de langue, tout ce que vous avez besoin d'ajouter à la chaîne est $(nom_LangString_ici) ou vous voulez que la LangString soit insérée.

Notes:

Contrairement aux defines qui utilisent des accolades - {}, les chaînes multi-langues utilisent les parenthèses - ().
Si vous modifiez la langue dans la fonction .onInit, notez que les chaînes de langue dnas .onInit utiliseront toujours la langue détectée, basée sur la langue par défaut de l'utilisateur Windows, car la langue n'est initialisée qu'après .onInit.
Toujours définir une chaîne de langue pour chaque langue dans votre script.
SI vous définissez l'ID de langue à 0, la dernière langue utilisée par LangString ou LoadLanguageFile sera utilisée.

Exemple d'utilisation :

 LangString message ${LANG_ENGLISH} "English message"
 LangString message ${LANG_FRENCH} "Message français"
 LangString message ${LANG_KOREAN} "**y a du coréen dans l'air**"

 MessageBox MB_OK "Traduction Google $(message)"

4.9.15.3 LicenseLangString

nom id_langue répertoire_licence

Identique à LangString, il charge les chaînes depuis un fichier texte/RTF file et définit un LangString spécial ne pouvant être utilisé que par LicenseData.

LicenseLangString license ${LANG_ENGLISH} license-english.txt
LicenseLangString license ${LANG_FRENCH} license-french.txt
LicenseLangString license ${LANG_GERMAN} license-german.txt

LicenseData $(license)

Précédent | Sommaire | Suivant