DoEnvironmentSubstA-Funktion (shellapi.h)

Artikel
11/20/2024

[Diese Funktion wird nur aus Gründen der Abwärtskompatibilität beibehalten. Verwenden Sie stattdessen ExpandEnvironmentStrings.]

Analysiert eine Eingabezeichenfolge, die Verweise auf eine oder mehrere Umgebungsvariablen enthält, und ersetzt sie durch ihre vollständig erweiterten Werte.

Syntax

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

Parameter

[in, out] pszSrc

Typ: LPTSTR-

Ein Zeiger auf eine mit Null beendete Zeichenfolge, die Verweise auf eine oder mehrere Umgebungsvariablen enthält, jeweils in der folgenden Form. Der Fall wird ignoriert.

%VariableName%

Alle Zeichen in der Zeichenfolge, die nicht in '%' Zeichen eingeschlossen sind, werden ignoriert und unverändert zurückgegeben. Wenn ihre Zeichenfolge mehrere Umgebungsvariablen enthält, können Sie daher ein anderes Zeichen als "%" als Trennzeichen verwenden, einschließlich Leerzeichen oder kein Trennzeichen.

Wenn diese Funktion erfolgreich zurückgegeben wird, wird jedes %VariableName-% durch seinen erweiterten Wert ersetzt. Die Ersetzungsregeln sind identisch mit denen, die vom Befehlsdolmetscher verwendet werden. Wenn der Variablenname im System nicht gefunden wird, bleibt der %variableName-%, wie er beim Eintrag übermittelt wurde.

Wenn diese Funktion fehlschlägt, da die erweiterte Zeichenfolge für den Puffer zu groß ist, bleibt der Inhalt dieses Puffers unverändert.

cchSrc

Typ: UINT-

Die Größe des Puffers in Zeichen, auf den pszSrcverweist. Beachten Sie, dass der Puffer groß genug sein muss, um die zurückgegebene Zeichenfolge zu enthalten.

Rückgabewert

Typ: DWORD-

Wenn die erweiterte Zeichenfolge in den Puffer passt, wird TRUE- im HIWORD zurückgegeben, und die Länge des neuen pszSrc wird im LOWORD zurückgegeben.

Wenn die erweiterte Zeichenfolge für den Puffer zu groß ist, wird FALSE- im HIWORD- und cchSrc- im LOWORD zurückgegeben.

Bemerkungen

Parameter müssen gültige, nichtNULL- Werte enthalten. Sie müssen diese Werte überprüfen. Dies kann nicht zu unerwarteten Ergebnissen führen.

Da die in pszSrc- zurückgegebene Zeichenfolge in der Regel länger als die Eingabezeichenfolge ist, stellen Sie sicher, dass der Puffer groß genug ist, um die erweiterte Version der Zeichenfolge zu enthalten. Die zugewiesene Größe des cchSrc- Puffers für ANSI-Zeichenfolgen muss einen größer als der Puffer für eine Unicode-Zeichenfolge sein. Verwenden Sie beim Umgang mit ANSI-Zeichenfolgen die Formel Puffergröße = Zeichenfolgenlänge + Nullzeichen + 1, um die minimale richtige Puffergröße zu bestimmen.

Da Umgebungsvariablen vom Benutzer oder den Anwendungen hinzugefügt werden können, ist die vollständige Liste systemabhängig. Die folgenden Umgebungsvariablen sind Standard und stehen sowohl für interaktive Anwendungen als auch für Dienste zur Verfügung.

ALLUSERSPROFILE
APPDATA
COMPUTERNAME
LOCALAPPDATA
NUMBER_OF_PROCESSORS
OS
PROCESSOR_ARCHITECTURE
PROCESSOR_IDENTIFIER
PROCESSOR_LEVEL
PROCESSOR_REVISION
ProgramData
ProgramFiles
ÖFFENTLICH
SystemDrive
SystemRoot
USERPROFILE
windir

Im Folgenden sind nur interaktive Anwendungen verfügbar.

HOMEDRIVE
HOMEPATH
LOGONSERVER
USERDOMAIN
NUTZERNAME

Die Umgebungsvariablen, die Dateisystemordnern entsprechen, können einem entsprechenden CSIDL- oder KNOWNFOLDERID Wert über SHGetFolderLocation- oder SHGetKnownFolderPathabgerufen werden. CSIDLs und KNOWNFOLDERIDs sind zuverlässiger als Umgebungsvariablennamen und sollten nach Möglichkeit verwendet werden.

Beispiele

Die folgende Konsolenanwendung veranschaulicht die Verwendung von 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;
}

Anmerkung

Der shellapi.h-Header definiert DoEnvironmentSubst als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	shellapi.h
Library	Shell32.lib
DLL-	Shell32.dll (Version 4.0 oder höher)

Freigeben über