共用方式為

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 的長度。

如果展開的字串對緩衝區而言太大，FALSE 會在 HIWORD 中傳回，並在 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 或 KNOWNFOLDERID 值，可以 透過SHGetFolderLocation 或 SHGetKnownFolderPath取得。 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 標頭會根據 UNICODE 預處理器常數的定義，將 DoEnvironmentSubst 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的 慣例。

要求

要求 價值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
支援的最低伺服器 Windows 2000 Server [僅限傳統型應用程式]
目標平臺 窗戶
標頭 shellapi.h
連結庫 Shell32.lib
DLL Shell32.dll 版（4.0 版或更新版本）