DoEnvironmentSubstA 関数 (shellapi.h)

  • [アーティクル]

[この関数は下位互換性のためにのみ保持されます。 代わりに ExpandEnvironmentStrings を 使用してください。]

1 つ以上の環境変数への参照を含む入力文字列を解析し、それらを完全に展開された値に置き換えます。

構文

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

パラメーター

[in, out] pszSrc

種類: LPTSTR

次の形式の 1 つ以上の環境変数への参照を含む null で終わる文字列へのポインター。 大文字と小文字は無視されます。

%VariableName%

'%' 文字で囲まれていない文字列内の文字はすべて無視され、変更されずに返されます。 したがって、文字列に複数の環境変数が含まれている場合は、区切り記号として '%' 以外の任意の文字 (スペースを含む)、または区切り記号を使用できません。

この関数が正常に返されると、各 %VariableName% は展開された値に置き換えられます。 置換規則は、コマンド インタープリターで使用されるものと同じです。 変数名がシステムで見つからない場合、%variableName% はエントリ時に送信されたとおりに残ります。

展開された文字列がバッファーに対して大きすぎるためにこの関数が失敗した場合、このバッファーの内容は変更されません。

cchSrc

型: UINT

pszSrc が指すバッファーのサイズ (文字単位)。 バッファーは、返される文字列を保持するのに十分な大きさである必要があることに注意してください。

戻り値

型: DWORD

展開された文字列がバッファーに収まる場合は、 HIWORD で TRUE が返され、新しい pszSrc の長さが LOWORD で返されます。

展開された文字列がバッファーに対して大きすぎる場合、 HIWORD では FALSE 、LOWORD では cchSrc が返されます。

注釈

パラメーターには、有効な 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 または 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 プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして DoEnvironmentSubst を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー shellapi.h
Library Shell32.lib
[DLL] Shell32.dll (バージョン 4.0 以降)