Fungsi GetFirmwareEnvironmentVariableA (winbase.h)

Artikel
08/27/2023

Mengambil nilai variabel lingkungan firmware yang ditentukan.

Sintaks

DWORD GetFirmwareEnvironmentVariableA(
  [in]  LPCSTR lpName,
  [in]  LPCSTR lpGuid,
  [out] PVOID  pBuffer,
  [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}" di mana 'x' mewakili nilai heksadesimal.

[out] pBuffer

Penunjuk ke buffer yang menerima nilai variabel lingkungan firmware yang ditentukan.

[in] nSize

Ukuran buffer pBuffer , dalam byte.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah jumlah byte yang disimpan dalam buffer pBuffer .

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 Unified Extensible Firmware Interface (UEFI). Lihat Mengakses variabel firmware UEFI dari Aplikasi Universal Windows untuk detailnya.

Untuk membaca 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.

Dimulai dengan Windows 10, versi 1803, membaca variabel Unified Extensible Firmware Interface (UEFI) juga didukung dari driver User-Mode Driver Framework (UMDF). Menulis variabel UEFI dari driver UMDF tidak didukung.

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 GetFirmwareEnvironmentVariable 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 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.

Jika Anda membuat aplikasi cadangan, Anda dapat menggunakan fungsi ini untuk menyimpan semua pengaturan boot untuk sistem sehingga dapat dipulihkan menggunakan fungsi SetFirmwareEnvironmentVariable jika diperlukan.

GetFirmwareEnvironmentVariable adalah mode pengguna yang setara dengan rutinitas mode kernel ExGetFirmwareEnvironmentVariable .

Catatan

Header winbase.h mendefinisikan GetFirmwareEnvironmentVariable 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 Vista, Windows XP dengan SP1 [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2003 [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 Universal Windows

GetFirmwareEnvironmentVariableEx

SetFirmwareEnvironmentVariable

Fungsi Informasi Sistem

Bagikan melalui