Функция DoEnvironmentSubstA (shellapi.h)

Статья
11/20/2024

[Эта функция сохраняется только для обратной совместимости. Вместо этого используйте ExpandEnvironmentStrings.]

Анализирует входную строку, содержащую ссылки на одну или несколько переменных среды, и заменяет их полностью развернутыми значениями.

Синтаксис

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

Параметры

[in, out] pszSrc

Тип: LPTSTR

Указатель на строку, завершающуюся значением NULL, которая содержит ссылки на одну или несколько переменных среды, каждая из которых содержится в следующей форме. Регистр игнорируется.

%VariableName%

Любой символ в строке, которая не заключена в символы%', игнорируется и возвращается без изменений. Таким образом, если строка содержит несколько переменных среды, можно использовать любой символ, отличный от "%" в качестве разделителя, включая пробелы или без разделителя.

При успешном возвращении этой функции каждое %VariableName% заменяется его развернутым значением. Правила замены совпадают с правилами, используемыми интерпретатором команд. Если имя переменной не найдено в системе,% переменной %остается, как она была отправлена на запись.

Если эта функция завершается ошибкой из-за слишком большого размера развернутой строки для буфера, содержимое этого буфера остается неизменным.

cchSrc

Тип: UINT

Размер буфера в символах, на который указывает pszSrc. Обратите внимание, что буфер должен быть достаточно большим для хранения возвращаемой строки.

Возвращаемое значение

Тип: DWORD

Если развернутая строка помещается в буфер, TRUE возвращается в HIWORD и длине символов нового pszSrc возвращается в LOWORD.

Если развернутая строка слишком велика для буфера, FALSE возвращается в HIWORD и cchSrc в LOWORD.

Замечания

Параметры должны содержать допустимые, незначения NULL. Эти значения необходимо проверить. Не удается сделать это, что может дать непредвиденные результаты.

Так как строка, возвращаемая в pszSrc, обычно будет длиннее входной строки, убедитесь, что буфер достаточно велик, чтобы сохранить развернутую версию строки. Выделенный размер буфера cchSrc для строк ANSI должен быть больше, чем буфер для строки Юникода. При работе со строками ANSI используйте формулу размер буфера = длину строки и завершающее значение NULL + 1, чтобы определить минимальный правильный размер буфера.

Так как переменные среды могут быть добавлены пользователем или приложениями, полный список зависит от системы. Следующие переменные среды являются стандартными и доступны как интерактивным приложениям, так и службам.

ALLUSERSPROFILE
APPDATA
ИМЯ КОМПЬЮТЕРА
LOCALAPPDATA
NUMBER_OF_PROCESSORS
ОС
PROCESSOR_ARCHITECTURE
PROCESSOR_IDENTIFIER
PROCESSOR_LEVEL
PROCESSOR_REVISION
ProgramData
ProgramFiles
ОБЩЕСТВЕННЫЙ
SystemDrive
SystemRoot
USERPROFILE
windir

Следующие возможности доступны только для интерактивных приложений.

HOMEDRIVE
HOMEPATH
LOGONSERVER
USERDOMAIN
ИМЯ ПОЛЬЗОВАТЕЛЯ

Переменные среды, соответствующие папкам файловой системы, можно сопоставить с эквивалентными CSIDL или значениеМ KNOWNFOLDERID можно получить через SHGetFolderLocation или SHGetKnownFolderPath. CSIDLs и 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 как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	shellapi.h
библиотеки	Shell32.lib
DLL	Shell32.dll (версия 4.0 или более поздняя версия)

Поделиться через