DoEnvironmentSubstW 函数 (shellapi.h)

[保留此函数仅用于向后兼容。 请改用 ExpandEnvironmentStrings 。]

分析包含对一个或多个环境变量的引用的输入字符串，并将其替换为其完全扩展的值。

语法

DWORD DoEnvironmentSubstW(
  [in, out] LPWSTR pszSrc,
            UINT   cchSrc
);

参数

[in, out] pszSrc

类型： LPTSTR

指向以 null 结尾的字符串的指针，该字符串包含对一个或多个环境变量的引用，每个变量采用以下形式。 忽略大小写。

%VariableName%

字符串中未包含在“%”字符中的任何字符将被忽略并返回原样。 因此，如果字符串包含多个环境变量，则可以使用除“%”以外的任何字符作为分隔符，包括空格或无分隔符。

当此函数成功返回时，每个 %VariableName% 将替换为其扩展值。 替换规则与命令解释器使用的规则相同。 如果在系统上找不到变量名称，则会保留 %variableName% 作为输入时提交的变量名称。

如果此函数由于扩展字符串对于缓冲区太大而失败，则此缓冲区的内容保持不变。

cchSrc

类型： UINT

pszSrc 指向的缓冲区的大小（以字符为单位）。 请注意，缓冲区必须足够大才能保存返回的字符串。

返回值

类型：DWORD

如果扩展的字符串适合缓冲区，则 HIWORD 中返回 TRUE ，并在 LOWORD 中返回新 pszSrc 的长度（以字符为单位）。

如果扩展的字符串对于缓冲区来说太大，则会在 LOWORD 的 HIWORD 和 cchSrc 中返回 FALSE。

注解

参数必须包含有效的非 NULL 值。 必须验证这些值。 否则可能会产生意外的结果。

由于 pszSrc 中返回的字符串通常比输入字符串长，因此请确保缓冲区足够大，足以容纳字符串的扩展版本。 ANSI 字符串的 cchSrc 缓冲区的分配大小必须大于 Unicode 字符串的缓冲区大小。 处理 ANSI 字符串时，请使用公式 缓冲区大小 = 字符串长度 + 终止 null 字符 + 1 来确定最小正确缓冲区大小。

由于环境变量可由用户或应用程序添加，因此完整列表依赖于系统。 以下环境变量是标准环境变量，可用于交互式应用程序和服务。

• ALLUSERSPROFILE
• APPDATA
• COMPUTERNAME
• LOCALAPPDATA
• NUMBER_OF_PROCESSORS
• (OS)
• PROCESSOR_ARCHITECTURE
• PROCESSOR_IDENTIFIER
• PROCESSOR_LEVEL
• PROCESSOR_REVISION
• ProgramData
• ProgramFiles
• PUBLIC
• SystemDrive
• SystemRoot
• USERPROFILE
• windir

• HOMEDRIVE
• HOMEPATH
• LOGONSERVER
• USERDOMAIN
• USERNAME

示例

以下控制台应用程序演示了 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;
}

要求