DoEnvironmentSubstW 関数 (shellapi.h)

  • [アーティクル]

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

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

構文

DWORD DoEnvironmentSubstW(
  [in, out] LPWSTR 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 を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

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