ホーム › UI.Shell › DoEnvironmentSubstA

DoEnvironmentSubstA

関数

文字列内の環境変数参照を実際の値に置換する。

DLLSHELL32.dll文字セットANSI (-A)呼出規約winapi対応OSWindows XP 以降

シグネチャ

// SHELL32.dll  (ANSI / -A)
#include <windows.h>

DWORD DoEnvironmentSubstA(
    LPSTR pszSrc,
    DWORD cchSrc
);

パラメーター

名前型方向説明

pszSrc

名前	型	方向	説明
pszSrc	LPSTR	inout	1 つ以上の環境変数への参照を含む null 終端文字列へのポインター。各参照は次の形式です。大文字と小文字は区別されません。 `%VariableName%` '%' 文字で囲まれていない文字列中の文字は無視され、変更されずに返されます。したがって、文字列に複数の環境変数が含まれる場合、'%' 以外の任意の文字を区切り文字として使用できます。スペースや、区切り文字なしも使用できます。この関数が正常に返ると、各 %VariableName% はその展開後の値に置き換えられます。置換規則はコマンドインタープリターが使用するものと同じです。変数名がシステム上で見つからない場合、%variableName% は入力時に指定されたまま残されます。展開後の文字列がバッファーに対して大きすぎてこの関数が失敗した場合、このバッファーの内容は変更されません。
cchSrc	DWORD	in	pszSrc が指すバッファーのサイズ(文字数)。バッファーは返される文字列を保持できる十分な大きさである必要があることに注意してください。

LPSTR

inout

1 つ以上の環境変数への参照を含む null 終端文字列へのポインター。各参照は次の形式です。大文字と小文字は区別されません。

%VariableName%

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

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

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

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

戻り値の型: DWORD

公式ドキュメント

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

戻り値

型: DWORD

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

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

解説(Remarks)

パラメーターには有効な、非 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 を定義しています。エンコーディング中立のエイリアスの使用を、エンコーディング中立でないコードと混在させると、コンパイルエラーや実行時エラーを引き起こす不一致につながる可能性があります。詳細については、関数プロトタイプの規則を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// SHELL32.dll  (ANSI / -A)
#include <windows.h>

DWORD DoEnvironmentSubstA(
    LPSTR pszSrc,
    DWORD cchSrc
);

[DllImport("SHELL32.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern uint DoEnvironmentSubstA(
    [MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder pszSrc,   // LPSTR in/out
    uint cchSrc   // DWORD
);

<DllImport("SHELL32.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function DoEnvironmentSubstA(
    <MarshalAs(UnmanagedType.LPStr)> pszSrc As System.Text.StringBuilder,   ' LPSTR in/out
    cchSrc As UInteger   ' DWORD
) As UInteger
End Function

' pszSrc : LPSTR in/out
' cchSrc : DWORD
Declare PtrSafe Function DoEnvironmentSubstA Lib "shell32" ( _
    ByVal pszSrc As String, _
    ByVal cchSrc As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

DoEnvironmentSubstA = ctypes.windll.shell32.DoEnvironmentSubstA
DoEnvironmentSubstA.restype = wintypes.DWORD
DoEnvironmentSubstA.argtypes = [
    wintypes.LPSTR,  # pszSrc : LPSTR in/out
    wintypes.DWORD,  # cchSrc : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('SHELL32.dll')
DoEnvironmentSubstA = Fiddle::Function.new(
  lib['DoEnvironmentSubstA'],
  [
    Fiddle::TYPE_VOIDP,  # pszSrc : LPSTR in/out
    -Fiddle::TYPE_INT,  # cchSrc : DWORD
  ],
  -Fiddle::TYPE_INT)

#[link(name = "shell32")]
extern "system" {
    fn DoEnvironmentSubstA(
        pszSrc: *mut u8,  // LPSTR in/out
        cchSrc: u32  // DWORD
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("SHELL32.dll", CharSet = CharSet.Ansi)]
public static extern uint DoEnvironmentSubstA([MarshalAs(UnmanagedType.LPStr)] System.Text.StringBuilder pszSrc, uint cchSrc);
"@
$api = Add-Type -MemberDefinition $sig -Name 'SHELL32_DoEnvironmentSubstA' -Namespace Win32 -PassThru
# $api::DoEnvironmentSubstA(pszSrc, cchSrc)

#uselib "SHELL32.dll"
#func global DoEnvironmentSubstA "DoEnvironmentSubstA" sptr, sptr
; DoEnvironmentSubstA varptr(pszSrc), cchSrc   ; 戻り値は stat
; pszSrc : LPSTR in/out -> "sptr"
; cchSrc : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "SHELL32.dll"
#cfunc global DoEnvironmentSubstA "DoEnvironmentSubstA" var, int
; res = DoEnvironmentSubstA(pszSrc, cchSrc)
; pszSrc : LPSTR in/out -> "var"
; cchSrc : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "SHELL32.dll"
#cfunc global DoEnvironmentSubstA "DoEnvironmentSubstA" sptr, int
; res = DoEnvironmentSubstA(varptr(pszSrc), cchSrc)
; pszSrc : LPSTR in/out -> "sptr"
; cchSrc : DWORD -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。