Fungsi GetFirmwareEnvironmentVariableExW (winbase.h)

Artikel
20/11/2024

Mengambil nilai variabel lingkungan firmware yang ditentukan dan atributnya.

Sintaksis

DWORD GetFirmwareEnvironmentVariableExW(
  LPCWSTR lpName,
  LPCWSTR lpGuid,
  PVOID   pBuffer,
  DWORD   nSize,
  PDWORD  pdwAttribubutes
);

Parameter

lpName

Nama variabel lingkungan firmware. Penunjuk tidak boleh null.

lpGuid

GUID yang mewakili namespace variabel lingkungan firmware. GUID harus berupa string dalam format "{xxxxxxxxx-xxxx-xxxx-xxxx-xxxxx" di mana 'x' mewakili nilai heksadesimal. Penunjuk tidak boleh null.

pBuffer

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

nSize

Ukuran pValue buffer, dalam byte.

pdwAttribubutes

Bitmask mengidentifikasi atribut variabel UEFI yang terkait dengan variabel . Lihat SetFirmwareEnvironmentVariableEx untuk definisi bitmask.

Mengembalikan nilai

Jika fungsi berhasil, nilai pengembalian adalah jumlah byte yang disimpan dalam buffer pValue .

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.

Untuk membaca variabel lingkungan firmware UEFI, 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.

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

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.

Catatan

Header winbase.h mendefinisikan GetFirmwareEnvironmentVariableEx 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 8 [aplikasi desktop \| Aplikasi UWP]
server minimum yang didukung	Windows Server 2012 [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

Bagikan melalui