DoEnvironmentSubstA, fonction (shellapi.h)
[Cette fonction est conservée uniquement pour des raisons de compatibilité descendante. Utilisez ExpandEnvironmentStrings à la place.]
Analyse une chaîne d’entrée qui contient des références à une ou plusieurs variables d’environnement et les remplace par leurs valeurs entièrement développées.
Syntaxe
DWORD DoEnvironmentSubstA(
[in, out] LPSTR pszSrc,
UINT cchSrc
);
Paramètres
[in, out] pszSrc
Type : LPTSTR
Pointeur vers une chaîne terminée par null qui contient des références à une ou plusieurs variables d’environnement, chacune sous la forme suivante. La casse est ignorée.
%VariableName%
Tout caractère de la chaîne qui n’est pas entouré de caractères '%' est ignoré et retourné inchangé. Par conséquent, si votre chaîne contient plusieurs variables d’environnement, vous pouvez utiliser n’importe quel caractère autre que « % » comme séparateur, y compris les espaces ou aucun séparateur.
Lorsque cette fonction retourne correctement, chaque %VariableName% est remplacé par sa valeur développée. Les règles de remplacement sont les mêmes que celles utilisées par l’interpréteur de commandes. Si le nom de la variable est introuvable sur le système, le %variableName% est laissé tel qu’il a été envoyé lors de l’entrée.
Si cette fonction échoue en raison d’une chaîne développée trop grande pour la mémoire tampon, le contenu de cette mémoire tampon reste inchangé.
cchSrc
Type : UINT
Taille, en caractères, de la mémoire tampon pointée par pszSrc. Notez que la mémoire tampon doit être suffisamment grande pour contenir la chaîne retournée.
Valeur retournée
Type : DWORD
Si la chaîne développée tient dans la mémoire tampon, TRUE est retourné dans hiword et la longueur, en caractères, du nouveau pszSrc est retournée dans le LOWORD.
Si la chaîne développée est trop grande pour la mémoire tampon, FALSE est retourné dans HIWORD et cchSrc dans le LOWORD.
Remarques
Les paramètres doivent contenir des valeurs valides, non NULL . Vous devez valider ces valeurs. Si vous ne le faites pas, vous pouvez obtenir des résultats inattendus.
Étant donné que la chaîne retournée dans pszSrc sera généralement plus longue que la chaîne d’entrée, assurez-vous que la mémoire tampon est suffisamment grande pour contenir la version développée de la chaîne. La taille allouée de la mémoire tampon cchSrc pour les chaînes ANSI doit être supérieure à celle de la mémoire tampon d’une chaîne Unicode. Lorsque vous traitez des chaînes ANSI, utilisez la formule taille de la mémoire tampon = longueur de chaîne + caractère null de fin + 1 pour déterminer la taille minimale correcte de la mémoire tampon.
Étant donné que les variables d’environnement peuvent être ajoutées par l’utilisateur ou les applications, la liste complète dépend du système. Les variables d’environnement suivantes sont standard et sont disponibles pour les applications et les services interactifs.
- ALLUSERSPROFILE
- APPDATA
- COMPUTERNAME
- LOCALAPPDATA
- NUMBER_OF_PROCESSORS
- Système d''exploitation
- PROCESSOR_ARCHITECTURE
- PROCESSOR_IDENTIFIER
- PROCESSOR_LEVEL
- PROCESSOR_REVISION
- ProgramData
- ProgramFiles
- PUBLIC
- %SystemDrive%
- SystemRoot
- USERPROFILE
- windir
- HOMEDRIVE
- HOMEPATH
- LOGONSERVER
- USERDOMAIN
- USERNAME
Exemples
L’application console suivante illustre l’utilisation de DoEnvironmentSubstW.
#include "stdafx.h"
#include "windows.h"
#include "windef.h"
#include "shellapi.h"
int _tmain(int argc, _TCHAR* argv[])
{
WCHAR szSrc[MAX_PATH] = L"%OS%;%HOMEPATH%";
DWORD result = DoEnvironmentSubstW(szSrc, MAX_PATH);
WORD success = HIWORD(result);
WORD string_length = LOWORD(result);
return 0;
}
Notes
L’en-tête shellapi.h définit DoEnvironmentSubst en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Configuration requise
Condition requise | Valeur |
---|---|
Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
Plateforme cible | Windows |
En-tête | shellapi.h |
Bibliothèque | Shell32.lib |
DLL | Shell32.dll (version 4.0 ou ultérieure) |