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 和 LOWORD 中的 cchSrc 中返回 FALSE。

注解

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

由于 pszSrc 中返回的字符串通常比输入字符串长，因此请确保缓冲区足够大，可以容纳字符串的扩展版本。 ANSI 字符串的 cchSrc 缓冲区的分配大小必须比 Unicode 字符串的缓冲区大 1。 处理 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
与文件系统文件夹对应的环境变量可以映射到等效的 CSIDL，或者可通过 SHGetFolderLocation 或 SHGetKnownFolderPath 获取 KNOWNFOLDERID 值。 CSIDL 和 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 [仅限桌面应用]
目标平台 Windows
标头 shellapi.h
Library Shell32.lib
DLL Shell32.dll (4.0 或更高版本)