Funzione DoEnvironmentSubstA (shellapi.h)

Articolo
11/20/2024

[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 le 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 che contiene riferimenti a una o più variabili di ambiente, ognuna nella forma seguente. La distinzione tra maiuscole e minuscole viene ignorata.

%VariableName%

Qualsiasi carattere nella stringa non racchiuso tra '%' 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 viene restituita correttamente, ogni %VariableName% viene sostituito con il relativo valore espanso. Le regole di sostituzione sono uguali a quelle usate dall'interprete dei comandi. Se il nome della variabile non viene trovato nel sistema, il %variableName% viene lasciato come inviato alla voce.

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

cchSrc

Tipo: UINT

Dimensione, in caratteri, del buffer a cui punta pszSrc. Si noti che il buffer deve essere sufficientemente grande da contenere la stringa restituita.

Valore restituito

Tipo: DWORD

Se la stringa espansa rientra nel buffer, TRUE viene restituita in HIWORD e la lunghezza, in caratteri, del nuovo pszSrc viene restituito in LOWORD.

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

Osservazioni

I parametri devono contenere valori di NULL validi e non. È necessario convalidare questi valori. In caso contrario, può fornire risultati imprevisti.

Poiché la stringa restituita in pszSrc in genere sarà più lunga della stringa di input, assicurarsi che il buffer sia sufficientemente grande da contenere la versione espansa della stringa. Le dimensioni assegnate del buffer cchSrc per le stringhe ANSI devono essere maggiori del buffer per una stringa Unicode. Quando si gestiscono stringhe ANSI, usare la formula dimensione del buffer = 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 le applicazioni interattive che per i servizi.

ALLUSERSPROFILE
APPDATA
COMPUTERNAME
LOCALAPPDATA
NUMBER_OF_PROCESSORS
Sistema operativo
PROCESSOR_ARCHITECTURE
PROCESSOR_IDENTIFIER
PROCESSOR_LEVEL
PROCESSOR_REVISION
ProgramData
Programmi
PUBBLICO
SystemDrive
SystemRoot
USERPROFILE
vento

Di seguito sono disponibili solo applicazioni interattive.

HOMEDRIVE
HOMEPATH
LOGONSERVER
USERDOMAIN
NOME UTENTE

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

Esempi

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;
}

Nota

L'intestazione shellapi.h definisce DoEnvironmentSubst come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	shellapi.h
libreria	Shell32.lib
dll	Shell32.dll (versione 4.0 o successiva)

Condividi tramite