[This function is retained only for backward compatibility. Use ExpandEnvironmentStrings instead.]
Parses an input string that contains references to one or more environment variables and replaces them with their fully expanded values.
DWORD DoEnvironmentSubstA( LPSTR pszSrc, UINT cchSrc );
A pointer to a null-terminated string that contains references to one or more environment variables, each in the following form. Case is ignored.
Any character in the string that is not enclosed in '%' characters is ignored and returned unchanged. Therefore, if your string contains multiple environment variables, you can use any character other than '%' as a separator, including spaces or no separator.
When this function returns successfully, each %VariableName% is replaced with its expanded value. The replacement rules are the same as those used by the command interpreter. If the variable name is not found on the system, the %variableName% is left as it was submitted on entry.
If this function fails due to the expanded string being too large for the buffer, the contents of this buffer are left unchanged.
The size, in characters, of the buffer pointed to by pszSrc. Note that the buffer must be large enough to hold the returned string.
If the expanded string fits in the buffer, TRUE is returned in the HIWORD and the length, in characters, of the new pszSrc is returned in the LOWORD.
If the expanded string is too large for the buffer, FALSE is returned in the HIWORD and cchSrc in the LOWORD.
Parameters must contain valid, non-NULL values. You must validate these values. Failure to do so can provide unexpected results.
Because the string that is returned in pszSrc will typically be longer than the input string, make sure that the buffer is large enough to hold the expanded version of the string. The allotted size of the cchSrc buffer for ANSI strings must be one larger than the buffer for a Unicode string. When dealing with ANSI strings, use the formula buffer size = string length + terminating null character + 1 to determine the minimum correct buffer size.
Because environment variables can be added by the user or applications, the complete list is system-dependent. The following environment variables are standard and are available to both interactive applications and services.
The following console application demonstrates the use of DoEnvironmentSubstW.
#include "stdafx.h" #include "windows.h" #include "windef.h" #include "shellapi.h"
|Minimum supported client||Windows XP [desktop apps only]|
|Minimum supported server||Windows 2000 Server [desktop apps only]|
|DLL||Shell32.dll (version 4.0 or later)|