Fungsi SetFirmwareEnvironmentVariableExA (winbase.h)
Mengatur nilai variabel lingkungan firmware yang ditentukan sebagai atribut yang menunjukkan bagaimana variabel ini disimpan dan dipertahankan.
Sintaks
BOOL SetFirmwareEnvironmentVariableExA(
[in] LPCSTR lpName,
[in] LPCSTR lpGuid,
[in] PVOID pValue,
[in] DWORD nSize,
[in] DWORD dwAttributes
);
Parameter
[in] lpName
Nama variabel lingkungan firmware. Penunjuk tidak boleh NULL.
[in] lpGuid
GUID yang mewakili namespace variabel lingkungan firmware. GUID harus berupa string dalam format "{xxxxxxxxx-xxxx-xxxx-xxxx-xxxx-xxxxxxxx}". Jika sistem tidak mendukung namespace berbasis GUID, parameter ini diabaikan. Penunjuk tidak boleh NULL.
[in] pValue
Penunjuk ke nilai baru untuk variabel lingkungan firmware.
[in] nSize
Ukuran buffer pValue , dalam byte. Kecuali atribut variabel VARIABLE_ATTRIBUTE_APPEND_WRITE, VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS, atau VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS diatur melalui dwAttributes, mengatur nilai ini ke nol akan menghasilkan penghapusan variabel ini.
[in] dwAttributes
Bitmask untuk mengatur atribut variabel UEFI yang terkait dengan variabel . Lihat juga UEFI Spec 2.3.1, Bagian 7.2.
| Nilai | Makna |
|---|---|
|
Variabel lingkungan firmware disimpan dalam memori non-volatil (misalnya NVRAM). |
|
Variabel lingkungan firmware dapat diakses selama layanan boot. |
|
Variabel lingkungan firmware dapat diakses saat runtime.
Catatan Variabel dengan set atribut ini, juga harus memiliki set VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS .
|
|
Menunjukkan kesalahan terkait perangkat keras yang ditemui saat runtime. |
|
Menunjukkan persyaratan autentikasi yang harus dipenuhi sebelum menulis ke variabel lingkungan firmware ini. Untuk informasi selengkapnya, lihat spesifikasi UEFI 2.3.1. |
|
Menunjukkan persyaratan autentikasi dan stempel waktu yang harus dipenuhi sebelum menulis ke variabel lingkungan firmware ini. Ketika atribut ini diatur, buffer, yang diwakili oleh pValue, akan dimulai dengan instans deskriptor EFI_VARIABLE_AUTHENTICATION_2 lengkap (dan diserialisasikan). Untuk informasi selengkapnya, lihat spesifikasi UEFI 2.3.1. |
|
Tambahkan variabel lingkungan yang ada dengan nilai pValue. Jika firmware tidak mendukung operasi, SetFirmwareEnvironmentVariableEx akan mengembalikan ERROR_INVALID_FUNCTION. |
Mengembalikan nilai
Jika fungsi berhasil, nilai yang dikembalikan adalah nilai bukan nol.
Jika fungsi gagal, nilai yang dikembalikan adalah nol. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError. Kemungkinan kode kesalahan termasuk ERROR_INVALID_FUNCTION.
Keterangan
Dimulai dengan Windows 10, versi 1803, aplikasi Universal Windows dapat membaca dan menulis variabel firmware UEFI. Lihat Mengakses variabel firmware UEFI dari Aplikasi Windows Universal untuk detailnya.
Dimulai dengan Windows 10, versi 1803, membaca variabel firmware UEFI juga didukung dari driver User-Mode Driver Framework (UMDF). Menulis variabel firmware UEFI dari driver UMDF tidak didukung.
Untuk menulis variabel lingkungan firmware, akun pengguna yang dijalankan aplikasi harus memiliki hak istimewa SE_SYSTEM_ENVIRONMENT_NAME . Aplikasi Universal Windows harus dijalankan dari akun administrator dan mengikuti persyaratan yang diuraikan dalam Mengakses variabel firmware UEFI dari Aplikasi Universal Windows.
Metode yang benar untuk mengubah atribut variabel adalah menghapus variabel dan membuatnya kembali dengan atribut yang berbeda.
Kumpulan variabel lingkungan firmware yang tepat ditentukan oleh firmware boot. Lokasi variabel lingkungan ini juga ditentukan oleh firmware. Misalnya, pada sistem berbasis UEFI, NVRAM berisi variabel lingkungan firmware yang menentukan pengaturan boot sistem. Untuk informasi tentang variabel tertentu yang digunakan, lihat spesifikasi UEFI. Untuk informasi selengkapnya tentang UEFI dan Windows, lihat UEFI dan Windows.
Variabel firmware tidak didukung pada sistem berbasis BIOS warisan. Fungsi SetFirmwareEnvironmentVariableEx akan selalu gagal pada sistem berbasis BIOS warisan, atau jika Windows diinstal menggunakan BIOS warisan pada sistem yang mendukung BIOS warisan dan UEFI. Untuk mengidentifikasi kondisi ini, panggil fungsi dengan nama lingkungan firmware dummy seperti string kosong ("") untuk parameter lpName dan GUID dummy seperti "{00000000-0000-0000-0000-000000000000}" untuk parameter lpGuid . Pada sistem berbasis BIOS warisan, atau pada sistem yang mendukung BIOS warisan dan UEFI di mana Windows diinstal menggunakan BIOS warisan, fungsi akan gagal dengan ERROR_INVALID_FUNCTION. Pada sistem berbasis UEFI, fungsi akan gagal dengan kesalahan khusus untuk firmware, seperti ERROR_NOACCESS, untuk menunjukkan bahwa namespace GUID dummy tidak ada.
Catatan
Header winbase.h mendefinisikan SetFirmwareEnvironmentVariableEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
| Klien minimum yang didukung | Windows 8 [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2012 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | winbase.h (termasuk Windows.h) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |
Lihat juga
Mengakses variabel firmware UEFI dari Aplikasi Windows Universal