DoEnvironmentSubstA, fonction (shellapi.h)

Article
08/26/2023

[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

Les éléments suivants sont disponibles uniquement pour les applications interactives.

HOMEDRIVE
HOMEPATH
LOGONSERVER
USERDOMAIN
USERNAME

Les variables d’environnement qui correspondent aux dossiers du système de fichiers peuvent être mappées à une valeur CSIDL ou KNOWNFOLDERID équivalente peuvent être obtenues via SHGetFolderLocation ou SHGetKnownFolderPath. Les CSIDL et KNOWNFOLDERIDs sont plus fiables que les noms de variables d’environnement et doivent être utilisés dans la mesure du possible.

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)

Partager via