DoEnvironmentSubstA, fonction (shellapi.h)

Article
11/20/2024

[Cette fonction est conservée uniquement pour la 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 placé entre les 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 est retournée avec succès, 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, la %variableName% est laissée telle qu’elle a été envoyée lors de l’entrée.

Si cette fonction échoue en raison de la chaîne développée trop volumineuse 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 de retour

Type : DWORD

Si la chaîne développée s’adapte à la mémoire tampon, TRUE est retournée dans hiWORD et la longueur, en caractères, du nouveau pszSrc est retourné dans le LOWORD.

Si la chaîne développée est trop grande pour la mémoire tampon, FALSE est retournée dans hiword et cchSrc dans loWORD.

Remarques

Les paramètres doivent contenir des valeurs de NULL valides non. Vous devez valider ces valeurs. L’échec de cette opération peut fournir 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 à la mémoire tampon d’une chaîne Unicode. Lorsque vous traitez de 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 services interactifs.

ALLUSERSPROFILE
APPDATA
COMPUTERNAME
LOCALAPPDATA
NUMBER_OF_PROCESSORS
OS
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
NOM D’UTILISATEUR

Les variables d’environnement qui correspondent aux dossiers de système de fichiers peuvent être mappées à une valeur CSIDL équivalente ou KNOWNFOLDERID 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;
}

Note

L’en-tête shellapi.h définit DoEnvironmentSubst comme 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. Le mélange 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	shellapi.h
bibliothèque	Shell32.lib
DLL	Shell32.dll (version 4.0 ou ultérieure)

Partager via