Share via

DoEnvironmentSubstA-Funktion (shellapi.h)

  • Artikel

[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 NULL-endende Zeichenfolge, die Verweise auf eine oder mehrere Umgebungsvariablen enthält, jeweils in der folgenden Form. Groß-/Kleinschreibung 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 jedes andere Zeichen als "%" als Trennzeichen verwenden, einschließlich Leerzeichen oder keinem Trennzeichen.

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

Wenn diese Funktion fehlschlägt, weil 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 pszSrc verweist. Beachten Sie, dass der Puffer groß genug sein muss, um die zurückgegebene Zeichenfolge zu enthalten.

Rückgabewert

Art: DWORD

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

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

Hinweise

Parameter müssen gültige Werte enthalten, die nicht NULL sind. Sie müssen diese Werte überprüfen. Andernfalls kann dies 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 größer sein als der Puffer für eine Unicode-Zeichenfolge. Verwenden Sie beim Umgang mit ANSI-Zeichenfolgen die Formelpuffergröße = Zeichenfolgenlänge + beendendes NULL-Zeichen + 1 , um die minimale richtige Puffergröße zu bestimmen.

Da Umgebungsvariablen vom Benutzer oder von 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
  • PUBLIC
  • SystemDrive
  • SystemRoot
  • USERPROFILE
  • windir
Die folgenden Sind nur für interaktive Anwendungen verfügbar.
  • HOMEDRIVE
  • HOMEPATH
  • LOGONSERVER
  • USERDOMAIN
  • USERNAME
Die Umgebungsvariablen, die Dateisystemordnern entsprechen, können einem entsprechenden CSIDL - oder KNOWNFOLDERID-Wert über SHGetFolderLocation oder SHGetKnownFolderPath zugeordnet werden. CSIDLs und KNOWNFOLDERIDs sind zuverlässiger als Namen von Umgebungsvariablen 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;
}

Hinweis

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
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile shellapi.h
Bibliothek Shell32.lib
DLL Shell32.dll (Version 4.0 oder höher)