Condividi tramite


Funzione SetFirmwareEnvironmentVariableExA (winbase.h)

Imposta il valore della variabile di ambiente firmware specificata come attributi che indicano come viene archiviata e gestita questa variabile.

Sintassi

BOOL SetFirmwareEnvironmentVariableExA(
  [in] LPCSTR lpName,
  [in] LPCSTR lpGuid,
  [in] PVOID  pValue,
  [in] DWORD  nSize,
  [in] DWORD  dwAttributes
);

Parametri

[in] lpName

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

[in] 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-xxxxxxxxxxxx}". Se il sistema non supporta gli spazi dei nomi basati su GUID, questo parametro viene ignorato. Il puntatore non deve essere NULL.

[in] pValue

Puntatore al nuovo valore per la variabile di ambiente firmware.

[in] nSize

Dimensioni del buffer pValue , in byte. A meno che l'attributo VARIABLE_ATTRIBUTE_APPEND_WRITE, VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS o VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS variabile sia impostato tramite dwAttributes, l'impostazione di questo valore su zero comporterà l'eliminazione di questa variabile.

[in] dwAttributes

Maschera di bit per impostare gli attributi della variabile UEFI associati alla variabile. Vedere anche la specifica UEFI 2.3.1, sezione 7.2.

Valore Significato
VARIABLE_ATTRIBUTE_NON_VOLATILE
0x00000001
La variabile di ambiente del firmware viene archiviata in memoria non volatile ,ad esempio NVRAM.
VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS
0x00000002
È possibile accedere alla variabile di ambiente del firmware durante il servizio di avvio.
VARIABLE_ATTRIBUTE_RUNTIME_ACCESS
0x00000004
È possibile accedere alla variabile di ambiente del firmware in fase di esecuzione.
Nota Anche le variabili con questo set di attributi devono avere VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS impostato.
 
VARIABLE_ATTRIBUTE_HARDWARE_ERROR_RECORD
0x00000008
Indica gli errori correlati all'hardware rilevati in fase di esecuzione.
VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS
0x00000010
Indica un requisito di autenticazione che deve essere soddisfatto prima della scrittura in questa variabile di ambiente del firmware. Per altre informazioni, vedere la specifica UEFI 2.3.1.
VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS
0x00000020
Indica i requisiti di autenticazione e timestamp che devono essere soddisfatti prima di scrivere in questa variabile di ambiente del firmware. Quando questo attributo viene impostato, il buffer, rappresentato da pValue, inizierà con un'istanza di un descrittore completo (e serializzato) EFI_VARIABLE_AUTHENTICATION_2. Per altre informazioni, vedere la specifica UEFI 2.3.1.
VARIABLE_ATTRIBUTE_APPEND_WRITE
0x00000040
Aggiungere una variabile di ambiente esistente con il valore di pValue. Se il firmware non supporta l'operazione, SetFirmwareEnvironmentVariableEx restituirà ERROR_INVALID_FUNCTION.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un valore diverso da zero.

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

Commenti

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

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

Per scrivere una variabile di ambiente firmware, 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.

Il metodo corretto per modificare gli attributi di una variabile consiste nell'eliminare la variabile e ricrearla con attributi diversi.

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 SetFirmwareEnvironmentVariableEx avrà sempre esito negativo in un sistema legacy basato su BIOS 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 "{00000000-0000-0000-0000-000000000000}" 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 tramite 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.

Nota

L'intestazione winbase.h definisce SetFirmwareEnvironmentVariableEx 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

   
Client minimo supportato Windows 8 [app desktop | App UWP]
Server minimo supportato Windows Server 2012 [app desktop | App UWP]
Piattaforma di destinazione Windows
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

GetFirmwareEnvironmentVariableEx

SetFirmwareEnvironmentVariable