Funzione GetFirmwareEnvironmentVariableExA (winbase.h)

Articolo
11/20/2024

Recupera il valore della variabile di ambiente del firmware specificata e dei relativi attributi.

Sintassi

DWORD GetFirmwareEnvironmentVariableExA(
  LPCSTR lpName,
  LPCSTR lpGuid,
  PVOID  pBuffer,
  DWORD  nSize,
  PDWORD pdwAttribubutes
);

Parametri

lpName

Nome della variabile di ambiente del firmware. Il puntatore non deve essere NULL.

lpGuid

GUID che rappresenta lo spazio dei nomi della variabile di ambiente del firmware. Il GUID deve essere una stringa nel formato "{xxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxx}" dove 'x' rappresenta un valore esadecimale. Il puntatore non deve essere NULL.

pBuffer

Puntatore a un buffer che riceve il valore della variabile di ambiente del firmware specificata.

nSize

Dimensioni in byte del buffer pValue .

pdwAttribubutes

Maschera di bit che identifica gli attributi della variabile UEFI associati alla variabile. Vedere SetFirmwareEnvironmentVariableEx per la definizione della maschera di bit.

Valore restituito

Se la funzione ha esito positivo, il valore restituito corrisponde al numero di byte archiviati nel buffer pValue .

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError. I possibili codici di errore includono ERROR_INVALID_FUNCTION.

Osservazioni

A partire da Windows 10 versione 1803, le app di Windows universali possono leggere e scrivere variabili del firmware UEFI. Per informazioni dettagliate, vedi Accedere alle variabili del firmware UEFI da un'app di Windows universale.

Per leggere una variabile di ambiente del firmware UEFI, l'account utente in cui è in esecuzione l'app deve avere il privilegio SE_SYSTEM_ENVIRONMENT_NAME. Un'app di Windows universale deve essere eseguita da un account amministratore e seguire i requisiti descritti in Accedere alle variabili del firmware UEFI da un'app di Windows universale.

A partire da Windows 10, versione 1803, la lettura delle variabili UEFI (Unified Extensible Firmware Interface) è supportata anche dai driver User-Mode Driver Framework (UMDF). La scrittura di variabili UEFI dai driver UMDF non è supportata.

Il set esatto di variabili di ambiente del firmware è determinato dal firmware di avvio. La posizione di queste variabili di ambiente viene specificata anche dal firmware. Ad esempio, in un sistema basato su UEFI, NVRAM contiene variabili di ambiente del firmware che specificano le impostazioni di avvio del sistema. Per informazioni sulle variabili specifiche usate, vedere la specifica UEFI . Per altre informazioni su UEFI e Windows, vedere UEFI e Windows.

Le variabili del firmware non sono supportate in un sistema basato su BIOS legacy. La funzione GetFirmwareEnvironmentVariableEx avrà sempre esito negativo in un sistema basato su BIOS legacy o se Windows è stato installato usando BIOS legacy in un sistema che supporta sia BIOS legacy che UEFI. Per identificare queste condizioni, chiamare la funzione con un nome di ambiente firmware fittizio, ad esempio una stringa vuota ("") per il parametro lpName e un GUID fittizio, ad esempio "" per il parametro lpGuid. In un sistema basato su BIOS legacy o in un sistema che supporta sia BIOS legacy che UEFI in cui Windows è stato installato con BIOS legacy, la funzione avrà esito negativo con ERROR_INVALID_FUNCTION. In un sistema basato su UEFI, la funzione avrà esito negativo con un errore specifico del firmware, ad esempio ERROR_NOACCESS, per indicare che lo spazio dei nomi GUID fittizio non esiste.

Se si crea un'applicazione di backup, è possibile usare questa funzione per salvare tutte le impostazioni di avvio per il sistema in modo che possano essere ripristinate usando la funzione SetFirmwareEnvironmentVariable, se necessario.

Nota

L'intestazione winbase.h definisce GetFirmwareEnvironmentVariableEx 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 8 [app desktop \| App UWP]
server minimo supportato	Windows Server 2012 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	winbase.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll

Vedere anche

accedere alle variabili del firmware UEFI da un'app di Windows universale

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx

Condividi tramite