Fungsi SetFirmwareEnvironmentVariableA (winbase.h)

2024-11-20

Mengatur nilai variabel lingkungan firmware yang ditentukan.

Sintaksis

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

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". Jika sistem tidak mendukung namespace berbasis GUID, parameter ini diabaikan.

[in] pValue

Penunjuk ke nilai baru untuk variabel lingkungan firmware.

[in] nSize

Ukuran buffer pBuffer , dalam byte. Jika parameter ini nol, variabel lingkungan firmware akan dihapus.

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, panggil GetLastError. Kemungkinan kode kesalahan termasuk ERROR_INVALID_FUNCTION.

Komentar

Dimulai dengan Windows 10, versi 1803, aplikasi Universal Windows dapat membaca dan menulis variabel firmware UEFI. Lihat Mengakses variabel firmware UEFI dari Universal Windows App 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 Universal Windows App.

Set 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 SetFirmwareEnvironmentVariable 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 "" untuk parameter lpGuid . Pada sistem berbasis BIOS warisan, atau pada sistem yang mendukung BIOS warisan dan UEFI tempat 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.

SetFirmwareEnvironmentVariable setara dengan ExSetFirmwareEnvironmentVariable rutinitas mode kernel.

Nota

Header winbase.h mendefinisikan SetFirmwareEnvironmentVariable 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

Syarat	Nilai
klien minimum yang didukung	Windows Vista, Windows XP dengan SP1 [aplikasi desktop \| Aplikasi UWP]
server minimum yang didukung	Windows Server 2003 [aplikasi desktop \| Aplikasi UWP]
Platform Target	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

Mengakses variabel firmware UEFI dari Universal Windows App

GetFirmwareEnvironmentVariable

SetFirmwareEnvironmentVariableEx

Fungsi Informasi Sistem

Bagikan melalui