通过

DoEnvironmentSubstA 函数 （shellapi.h）

  • 项目

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

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

语法

DWORD DoEnvironmentSubstA(
  [in, out] LPSTR pszSrc,
            UINT  cchSrc
);

参数

[in, out] pszSrc

类型：LPTSTR

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

%VariableName%

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

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

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

cchSrc

类型：UINT

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

返回值

类型：DWORD

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

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

言论

参数必须包含有效的非NULL 值。 必须验证这些值。 未能这样做可能会提供意外的结果。

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

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

  • ALLUSERSPROFILE
  • APPDATA
  • COMPUTERNAME
  • LOCALAPPDATA
  • NUMBER_OF_PROCESSORS
  • 操作系统
  • PROCESSOR_ARCHITECTURE
  • PROCESSOR_IDENTIFIER
  • PROCESSOR_LEVEL
  • PROCESSOR_REVISION
  • ProgramData
  • ProgramFiles
  • 公共
  • SystemDrive
  • SystemRoot
  • USERPROFILE
  • windir
以下功能仅适用于交互式应用程序。
  • HOMEDRIVE
  • HOMEPATH
  • LOGONSERVER
  • USERDOMAIN
  • USERNAME
与文件系统文件夹对应的环境变量可以映射到等效的 CSIDL，也可以通过 SHGetFolderLocation 或 SHGetKnownFolderPathSHGetFolderLocation获取与文件系统文件夹对应的 CSIDL 值。 CSID 和 KNOWNFOLDERID 比环境变量名称更可靠，应尽可能使用。

例子

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

注意

shellapi.h 标头将 DoEnvironmentSubst 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows XP [仅限桌面应用]
支持的最低服务器 Windows 2000 Server [仅限桌面应用]
目标平台 窗户
标头 shellapi.h
库 Shell32.lib
DLL Shell32.dll（版本 4.0 或更高版本）