=head1 NOM Win32 - Interfaces à quelques fonctions de l'API Win32 =head1 DESCRIPTION Perl sous Win32 contient plusieurs fonctions pour accéder à des APIs Win32. Quelques-unes sont incluses dans Perl lui-même (sous Win32) et quelques autres ne sont disponibles seulement qu'après avoir appelé le module Win32 explicitement : use Win32; Dans la liste alphabétique suivante, les fonctions intégrées sont marquées [CORE] et les autres [EXT]. =head2 Liste alphabétique des fonctions Win32 =over =item Win32::AbortSystemShutdown(MACHINE) [EXT] Interrompt un arrêt du système (lancé par la fonction InitiateSystemShutdown) sur la MACHINE spécifiée. =item Win32::BuildNumber() [CORE] Retourne le numéro de construction d'ActivePerl. Cette fonction n'est disponible que pour la distribution binaire d'ActivePerl. =item Win32::CopyFile(SOURCE, DESTINATION, ECRASER) [CORE] La fonction Win32::CopyFile() copie un fichier existant vers un nouveau fichier. Toute les informations du fichier comme sa date de création et ses attributs seront copiées sur le nouveau fichier. Cependant les informations de sécurité ne sont B copiées. Si le fichier de destination existe déjà, il ne sera récrit que si le paramètre ECRASER est vrai. Toutefois, sur un fichier protégé contre l'écriture la copie n'aura pas lieu ; vous devrez d'abord utiliser unlink() vous-même. =item Win32::DomainName() [CORE] Retourne le nom de domaine du Réseau Microsoft dans lequel se trouve le propriétaire du processus. Cette fonction ne fonctionne B sous Windows 9x. =item Win32::ExpandEnvironmentStrings(CHAINE) [EXT] Prend CHAINE et remplace toutes les variables d'environnement rencontrées par leurs valeurs. Les références aux variables de l'environnement prennent la forme C<%NomDeVariable%>. La casse est ignorée pendant la recherche de NomDeVariable dans l'environnement. Si la variable n'est pas trouvée alors le texte original C<%NomDeVariable%> est retenu. A le même effet que : $chaine =~ s/%([^%]*)%/$ENV{$1} || "%$1%"/eg =item Win32::FormatMessage(CODEERREUR) [CORE] Convertit le numéro d'erreur fourni ( par exemple par Win32::GetLastError()) en une chaîne descriptive. Analogue à la fonction perror() de la bibliothèque standard C. Notez que C<$^E> utilisé dans un contexte scalaire à le même effet. C:\> perl -e "$^E = 26; print $^E;" Impossible d'accéder au disque ou à la disquette spécifié =item Win32::FsType() [CORE] Retourne le nom du système de fichiers du lecteur actif courant (comme 'FAT' ou 'NTFS'). En contexte de liste, renvoie trois valeurs : (FSTYPE, FLAGS, MAXCOMPLEN). FSTYPE est le nom du système de fichier comme précédemment. FLAGS est une combinaison de valeurs prises dans la table suivante : 0x00000001 supporte la casse des noms de fichier 0x00000002 préserve la casse des noms de fichier 0x00000004 supporte Unicode dans les noms de fichier 0x00000008 préserve et fixe les ACLs (Access Control List) 0x00000010 supporte la compression des fichiers 0x00000020 supporte les quotas sur les disques 0x00000040 supporte les fichiers dispersés (sparse files) 0x00000080 supporte les 'reparse points' 0x00000100 supporte le stockage à distance 0x00008000 est un volume compressé (ex: DoubleSpace) 0x00010000 supporte les identificateurs d'objet 0x00020000 supporte l' EFS (Encrypted File System) MAXCOMPLEN est la longueur maximum d'un composant de nom de fichier (la portion entre deux backslashes) du système de fichiers. =item Win32::FreeLibrary(HANDLE) [EXT] Décharge une bibliothèque à lien dynamique (dll). Le HANDLE n'est plus valide après cet appel. Voir L pour des informations concernant le chargement dynamique d'une bibliothèque. =item Win32::GetArchName() [EXT] L'utilisation de cette fonction est désapprouvée. Equivalent à $ENV{PROCESSOR_ARCHITECTURE}. Ne marche pas sous Win9X. =item Win32::GetChipName() [EXT] Retourne le type du processeur : 386, 486 ou 586 pour les processeur Intel, 21064 pour les puces Alpha. =item Win32::GetCwd() [CORE] Retourne le répertoire courant. Cette fonction ne retourne pas un chemin UNC puisque les fonctionnalités requises pour une telle fonction ne sont pas disponibles sous Windows 95. =item Win32::GetFolderPath(FOLDER [, CREATE]) [EXT] Retourne le chemin complet d'un des répertoire spéciaux de Windows. Le répertoire sera créé s'il n'existe pas et si l'argument optionnel CREATE est vrai. Les constantes FOLDER suivantes sont définies par le module Win32 mais ne sont exportées que sur demande : CSIDL_ADMINTOOLS CSIDL_APPDATA CSIDL_CDBURN_AREA CSIDL_COMMON_ADMINTOOLS CSIDL_COMMON_APPDATA CSIDL_COMMON_DESKTOPDIRECTORY CSIDL_COMMON_DOCUMENTS CSIDL_COMMON_FAVORITES CSIDL_COMMON_MUSIC CSIDL_COMMON_PICTURES CSIDL_COMMON_PROGRAMS CSIDL_COMMON_STARTMENU CSIDL_COMMON_STARTUP CSIDL_COMMON_TEMPLATES CSIDL_COMMON_VIDEO CSIDL_COOKIES CSIDL_DESKTOP CSIDL_DESKTOPDIRECTORY CSIDL_FAVORITES CSIDL_FONTS CSIDL_HISTORY CSIDL_INTERNET_CACHE CSIDL_LOCAL_APPDATA CSIDL_MYMUSIC CSIDL_MYPICTURES CSIDL_MYVIDEO CSIDL_NETHOOD CSIDL_PERSONAL CSIDL_PRINTHOOD CSIDL_PROFILE CSIDL_PROGRAMS CSIDL_PROGRAM_FILES CSIDL_PROGRAM_FILES_COMMON CSIDL_RECENT CSIDL_RESOURCES CSIDL_RESOURCES_LOCALIZED CSIDL_SENDTO CSIDL_STARTMENU CSIDL_STARTUP CSIDL_SYSTEM CSIDL_TEMPLATES CSIDL_WINDOWS Notez que tous ces répertoires ne sont pas définis pour toutes les versions de Windows. Reportez-vous, s'il vous plait, à la documentation MSDN des constantes CSIDL, disponible actuellement à: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/enums/csidl.asp =item Win32::GetFullPathName(NOMFICHIER) [CORE] GetFullPathName combine le NOMFICHIER avec le nom du répertoire courant et retourne un chemin pleinement qualifié (c-à-d absolu). En contexte de liste, deux éléments (CHEMIN, FILE) sont retournés, où CHEMIN est le nom de chemin complet (y compris le dernier backslash) et FILE est juste le nom de fichier. Rien n'est fait pour convertir les composants 8.3 dans le NOMFICHIER fourni en noms longs ou vice-versa. Comparez avec Win32::GetShortPathName et Win32::GetLongPathName. =item Win32::GetLastError() [CORE] Retourne le numéro de la dernière erreur engendrée par un appel à une fonction de l'API Win32. Notez que C<$^E>, utilisé dans un contexte numérique, donne la même valeur. =item Win32::GetLongPathName(NOMCHEMIN) [CORE] Retourne une représentation de NOMCHEMIN qui utilise des composants de noms longs (si possible). Le résultat n'est pas nécessairement plus long que NOMCHEMIN. Rien n'est fait pour convertir NOMCHEMIN en chemin absolu. Comparez avec Win32::GetShortPathName et Win32::GetFullPathName. =item Win32::GetNextAvailDrive() [CORE] Retourne une chaîne de la forme ":" où est la lettre du premier lecteur libre. =item Win32::GetOSVersion() [CORE] Retourne le tableau (STRING, MAJOR, MINOR, BUILD, ID), dont les éléments sont, respectivement : une chaîne de description arbitraire, le numéro majeur du système d'exploitation, le numéro mineur, le numéro de construction, un chiffre indiquant le système d'exploitation actuel. Les valeurs pour ID sont 0 pour Win32s, 1 pour Windows 9X/Me et 2 pour Windows NT/2000/XP/2003. En contexte scalaire, la fonction retourne juste ID. Les valeurs actuellement connues pour ID MAJOR et MINOR sont : OS ID MAJOR MINOR Win32s 0 - - Windows 95 1 4 0 Windows 98 1 4 10 Windows Me 1 4 90 Windows NT 3.51 2 3 51 Windows NT 4 2 4 0 Windows 2000 2 5 0 Windows XP 2 5 1 Windows Server 2003 2 5 2 Sous Windows NT 4 SP6 et suivants cette fonction retourne les valeurs additionnelles suivantes : SPMAJOR, SPMINOR, SUITEMASK, PRODUCTTYPE. SPMAJOR et SPMINOR sont les numéros de version du dernier "service pack" installé. SUITEMASK est un champ de bits qui identifie les "suites" disponibles sur le système. Les bits connus sont : VER_SUITE_SMALLBUSINESS 0x00000001 VER_SUITE_ENTERPRISE 0x00000002 VER_SUITE_BACKOFFICE 0x00000004 VER_SUITE_COMMUNICATIONS 0x00000008 VER_SUITE_TERMINAL 0x00000010 VER_SUITE_SMALLBUSINESS_RESTRICTED 0x00000020 VER_SUITE_EMBEDDEDNT 0x00000040 VER_SUITE_DATACENTER 0x00000080 VER_SUITE_SINGLEUSERTS 0x00000100 VER_SUITE_PERSONAL 0x00000200 VER_SUITE_BLADE 0x00000400 VER_SUITE_EMBEDDED_RESTRICTED 0x00000800 VER_SUITE_SECURITY_APPLIANCE 0x00001000 Les noms VER_SUITE_xxx ci-dessus ne sont listés que pour référence à la documentation Microsoft. Le module Win32 ne fournit pas de noms symboliques pour ces constantes. PRODUCTTYPE fournit une information supplémentaire à propos du système. Ce peut être une des valeurs entières suivantes : 1 - Workstation (NT 4, 2000 Pro, XP Home, XP Pro) 2 - Domaincontroller 3 - Server =item Win32::GetOSName() [EXT] En contexte scalaire, retourne le nom du système d'exploitation Win32 utilisé. En contexte de liste, retourne une liste à deux éléments dont le premier est le nom du système d'exploitation et le second est composé de l'édition (pour Win9x) ou des "service packs" installés. Ce dernier élément est, en gros, équivalent au premier item retourné par GetOSVersion() en contexte de liste. Actuellement, les valeurs possibles pour le nom de l'OS sont : Win32s Win95 Win98 WinMe WinNT3.51 WinNT4 Win2000 WinXP/.Net Win2003 Cette routine est juste une interface simple à GetOSVersion(). Les demandes plus spécifiques ou plus exigeantes devraient utiliser cette dernière fonction. Une autre option serait d'utiliser POSIX::uname(), cependant cette fonction semble ne rapporter que le nom de famille de l'OS et non pas son nom spécifique. En contexte scalaire, elle retourne juste le ID. Le nom "WinXP/.Net" est utilisé seulement pour des raisons historiques, afin de maintenir la compatibilité avec les version antérieures du module Win32. "Windows .NET Server" a été renommé "Windows 2003 Server" avant la version finale et utilise des numéros de version majeur/mineur différents de ceux de Windows XP. =item Win32::GetShortPathName(NOMCHEMIN) [CORE] Retourne une représentation de NOMCHEMIN composée seulement de composants en noms courts (8.3).Le résultat n'est pas nécessairement plus court que NOMCHEMIN. Comparez avec Win32::GetFullPathName et Win32::GetLongPathName. =item Win32::GetProcAddress(INSTANCE, PROCNAME) [EXT] Retourne l'adresse d'une fonction interne d'une bibliothèque chargée. L'information sur ce qu'on peut faire avec cette adresse a été perdue dans la nuits des temps. Utilisez le module Win32::API au lieu de cette fonction dépréciée. =item Win32::GetTickCount() [CORE] Retourne le nombre de millisecondes écoulée depuis le dernier démarrage du système. La résolution est limitée par le rythme du battement de l'horloge du système (à peu près 10ms sur WinNT et 55ms sur Win9X). =item Win32::InitiateSystemShutdown(MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT) [EXT] Arrête la MACHINE spécifiée, en prévenant les utilisateurs avec le MESSAGE fourni, dans l'intervalle de temps précisé par TIMEOUT. Force la fermeture de tous les documents sans demander aux utilisateurs si FORCECLOSE est vrai, et redémarre la machine si REBOOT est vrai. Cette fonction ne fonctionne que sur WinNT. =item Win32::IsAdminUser() [EXT] Retourne non zéro si le compte, dans le contexte de sécurité duquel tourne le processus/thread, appartient au groupe local d'Administrateurs du domaine système intégré; retourne 0 sinon. Retourne undef et affiche un warning si une erreur se produit. Cette fonction retourne toujours 1 sous Win9x. =item Win32::IsWinNT() [CORE] Retourne une valeur non nulle si le sous-système Win32 est Windows NT. =item Win32::IsWin95() [CORE] Retourne une valeur non nulle si le sous-système Win32 est Windows 95. =item Win32::LoadLibrary(LIBNAME) [EXT] Charge en mémoire une bibliothèque à liens dynamiques (dll) et retourne son handle de module. Ce handle peut être utilisé avec Win32::GetProcAddress et Win32::FreeLibrary. Cette fonction est dépréciée. Utilisez le module Win32::API à la place. =item Win32::LoginName() [CORE] Retourne le nom d'utilisateur du propriétaire du processus perl courant. =item Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE) [EXT] Recherche ACCOUNT sur le SYSTEM et retourne le nom de domaine, le SID (Security IDentifier) et le type de SID. =item Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE) [EXT] Recherche SID sur le SYSTEM et retourne le nom de compte, le nom de domaine et le type de SID. =item Win32::MsgBox(MESSAGE [, FLAGS [, TITRE]]) [EXT] Crée une boîte de dialogue contenant le MESSAGE. FLAGS spécifie l'icône et les boutons exigés d'après la table suivante : 0 = OK 1 = OK et Annuler 2 = Abandonner, Recommencer et Ignorer 3 = Oui, Non et Ignorer 4 = Oui et Non 5 = Recommencer et Annuler MB_ICONSTOP "X" dans un cercle rouge MB_ICONQUESTION point d'interrogation dans une bulle MB_ICONEXCLAMATION point d'exclamation dans un triangle jaune MB_ICONINFORMATION "i" dans une bulle TITRE spécifie un titre optionnel pour la fenêtre. La valeur par défaut est "Perl". La fonction retourne l'id-menu du bouton qui a été pressé : 0 Erreur 1 OK 2 Annuler 3 Abandonner 4 Recommencer 5 Ignorer 6 Oui 7 Non =item Win32::NodeName() [CORE] Retourne le nom du noeud du Réseau Microsoft de la machine courante. =item Win32::RegisterServer(LIBRARYNAME) [EXT] Charge la DLL LIBRARYNAME et appelle la fonction DllRegisterServer. =item Win32::SetChildShowWindow(SHOWWINDOW) [CORE] Fixe la valeur du paramètre I des processus fils démarrés par system(). Par défaut system() crée une nouvelle fenêtre console pour le processus fils si Perl lui-même ne tourne pas depuis une console. L'appel de SetChildShowWindow(0) rendra ces nouvelles consoles invisibles. L'appel SetChildShowWindow() sans argument ramène system() à son comportement par défaut. La valeur retournée par SetChildShowWindow() est sa valeur précédente ou C. [EXT] Les constantes symboliques suivantes pour SHOWWINDOW sont disponibles (mais non exportées) par le module Win32: SW_HIDE, SW_SHOWNORMAL, SW_SHOWMINIMIZED, SW_SHOWMAXIMIZED et SW_SHOWNOACTIVATE. =item Win32::SetCwd(NEWDIRECTORY) [CORE] Fixe le répertoire courant actif. Cette fonction ne marche pas avec les chemins UNC puisque les fonctionnalités requises pour une telle fonction ne sont pas disponibles sous Windows 95. =item Win32::SetLastError(ERROR) [CORE] Fixe la valeur de la dernière erreur rencontrée à ERROR. C'est cette valeur qui sera retournée par la fonction Win32::GetLastError(). =item Win32::Sleep(TIME) [CORE] Fait une pause de TIME millisecondes. Les intervalles de temps sont rendus disponibles aux autres processus et aux threads. =item Win32::Spawn(COMMAND, ARGS, PID) [CORE] Engendre un nouveau processus qui utilise la COMMANDe indiquée, en lui passant ses arguments dans la chaîne ARGS. Le pid du nouveau processus est placé dans PID. Cette fonction est dépréciée. S'il vous plaît, utilisez le module Win32::Process à la place. =item Win32::UnregisterServer(LIBRARYNAME) [EXT] Charge la DLL LIBRARYNAME et appelle la fonction DllUnregisterServer. =back =head1 VERSION FRANÇAISE Cette traduction française correspond à la version anglaise distribuée avec perl 5.8.4. Pour en savoir plus concernant ces traductions, consultez http://www.enstimac.fr/Perl/ . =head1 TRADUCTION EN FRANÇAIS Jean-Louis Morel =cut