Funzione DoEnvironmentSubstA (shellapi.h)

[Questa funzione viene mantenuta solo per la compatibilità con le versioni precedenti. Usare invece ExpandEnvironmentStrings .]

Analizza una stringa di input che contiene riferimenti a una o più variabili di ambiente e li sostituisce con i relativi valori completamente espansi.

Sintassi

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

Parametri

[in, out] pszSrc

Tipo: LPTSTR

Puntatore a una stringa con terminazione null contenente riferimenti a una o più variabili di ambiente, ognuna nella forma seguente. Non viene fatta distinzione tra maiuscole e minuscole.

%VariableName%

Qualsiasi carattere nella stringa non racchiuso tra i caratteri '%' viene ignorato e restituito invariato. Pertanto, se la stringa contiene più variabili di ambiente, è possibile usare qualsiasi carattere diverso da '%' come separatore, inclusi gli spazi o nessun separatore.

Quando questa funzione restituisce correttamente, ogni %VariableName% viene sostituito con il relativo valore espanso. Le regole di sostituzione sono uguali a quelle usate dall'interprete del comando. Se il nome della variabile non viene trovato nel sistema, il %variableName% viene lasciato come inviato nella voce.

Se questa funzione non riesce a causa della stringa espansa troppo grande per il buffer, il contenuto del buffer viene lasciato invariato.

cchSrc

Tipo: UINT

Dimensioni, in caratteri, del buffer a cui punta pszSrc. Si noti che il buffer deve essere abbastanza grande per contenere la stringa restituita.

Valore restituito

Tipo: DWORD

Se la stringa espansa si adatta al buffer, TRUE viene restituita in HIWORD e la lunghezza, in caratteri, del nuovo pszSrc viene restituita in LOWORD.

Se la stringa espansa è troppo grande per il buffer, FALSE viene restituita in HIWORD e cchSrc in LOWORD.

Commenti

I parametri devono contenere valori non NULL validi. È necessario convalidare questi valori. In caso contrario, è possibile fornire risultati imprevisti.

Poiché la stringa restituita in pszSrc in genere sarà più lunga della stringa di input, assicurarsi che il buffer sia abbastanza grande per contenere la versione espansa della stringa. Le dimensioni assegnate del buffer cchSrc per le stringhe ANSI devono essere una maggiore del buffer per una stringa Unicode. Quando si tratta di stringhe ANSI, usare la dimensione del buffer della formula = lunghezza stringa + carattere null terminante + 1 per determinare la dimensione minima corretta del buffer.

Poiché le variabili di ambiente possono essere aggiunte dall'utente o dalle applicazioni, l'elenco completo dipende dal sistema. Le variabili di ambiente seguenti sono standard e sono disponibili sia per applicazioni interattive che per i servizi.

• ALLUSERSPROFILE
• APPDATA
• NOMECOMPUTER
• LOCALAPPDATA
• NUMBER_OF_PROCESSORS
• OS
• PROCESSOR_ARCHITECTURE
• PROCESSOR_IDENTIFIER
• PROCESSOR_LEVEL
• PROCESSOR_REVISION
• ProgramData
• ProgramFiles
• PUBLIC
• SystemDrive
• SystemRoot
• USERPROFILE
• Windir

Di seguito sono disponibili solo applicazioni interattive.

• HOMEDRIVE
• HOMEPATH
• LOGONSERVER
• USERDOMAIN
• USERNAME

È possibile eseguire il mapping delle variabili di ambiente corrispondenti alle cartelle del file system a un valore CSIDL o KNOWNFOLDERID equivalente tramite SHGetFolderLocation o SHGetKnownFolderPath. I nomi CSID e KNOWNFOLDERID sono più affidabili rispetto ai nomi delle variabili di ambiente e devono essere usati ogni volta che possibile.

Esempio

L'applicazione console seguente illustra l'uso di 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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	shellapi.h
Libreria	Shell32.lib
DLL	Shell32.dll (versione 4.0 o successiva)