SetFirmwareEnvironmentVariableExW

指定したファームウェア環境変数の値と、その変数がどのように保存・維持されるかを示す属性を設定する。

SetFirmwareEnvironmentVariableExW lpName, lpGuid, pValue, nSize, dwAttributes

lpName : [wstr] ファームウェア環境変数の名前。ポインタは NULL であってはならない。
lpGuid : [wstr] ファームウェア環境変数の名前空間を表す GUID。GUID は "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}" 形式の文字列でなければならない。システムが GUID ベースの名前空間をサポートしない場合は無視される。ポインタは NULL であってはならない。
pValue : [intptr] ファームウェア環境変数の新しい値へのポインタ。
nSize : [int] pValue バッファのサイズ (バイト単位)。dwAttributes で VARIABLE_ATTRIBUTE_APPEND_WRITE、VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS、VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS のいずれかが設定されていない限り、この値をゼロに設定すると変数が削除される。
dwAttributes : [int] 変数に関連付ける UEFI 変数属性を設定するビットマスク。UEFI 仕様 2.3.1 セクション 7.2 も参照。

(プラグイン / モジュール : kernel32.dll)

解説

指定したファームウェア環境変数の値と、その変数がどのように保存・維持されるかを示す属性を設定する。

[戻り値]
関数が成功した場合、戻り値は非ゼロである。失敗した場合はゼロである。拡張エラー情報を取得するには GetLastError
を呼び出す。エラーコードには ERROR_INVALID_FUNCTION が含まれる可能性がある。

[備考]
Windows 10 バージョン 1803 以降、ユニバーサル Windows アプリは UEFI
ファームウェア変数の読み書きが可能である。詳細は「ユニバーサル Windows アプリからの UEFI
ファームウェア変数アクセス」を参照。Windows 10 バージョン 1803 以降、UEFI ファームウェア変数の読み取りは
User-Mode Driver Framework (UMDF) ドライバからもサポートされる。UMDF
ドライバからの書き込みはサポートされない。ファームウェア環境変数を書き込むには、アプリを実行中のユーザーアカウントが
SE_SYSTEM_ENVIRONMENT_NAME 特権を持つ必要がある。ユニバーサル Windows
アプリは管理者アカウントから実行し、「ユニバーサル Windows アプリからの UEFI
ファームウェア変数アクセス」で概説される要件に従う必要がある。変数の属性を変更する正しい方法は、その変数を削除してから異なる属性で再作成することである。正確なファームウェア環境変数の集合は起動ファームウェアによって決まる。これらの環境変数の位置もファームウェアが指定する。例えば
UEFI ベースのシステムでは、NVRAM にシステム起動設定を指定するファームウェア環境変数が含まれる。使用される特定変数については
UEFI 仕様を参照。UEFI と Windows に関する詳細は「UEFI と Windows」を参照。ファームウェア変数はレガシー
BIOS ベースのシステムではサポートされない。SetFirmwareEnvironmentVariableEx 関数はレガシー BIOS
ベースのシステム、またはレガシー BIOS と UEFI の両方をサポートするシステムに Windows がレガシー BIOS
でインストールされている場合、常に失敗する。これらの条件を識別するには、lpName にダミーのファームウェア環境名 (例: 空文字列
"")、lpGuid にダミー GUID (例: "{00000000-0000-0000-0000-000000000000}")
を指定して関数を呼ぶ。レガシー BIOS ベースのシステム、またはレガシー BIOS で Windows
がインストールされている両対応システムでは、関数は ERROR_INVALID_FUNCTION で失敗する。UEFI
ベースのシステムでは、ダミー GUID 名前空間が存在しないことを示すファームウェア固有のエラー (ERROR_NOACCESS など)
で失敗する。
> [!NOTE] > winbase.h ヘッダは SetFirmwareEnvironmentVariableEx を、UNICODE
プリプロセッサ定数の定義に応じて ANSI 版または Unicode
版を自動選択するエイリアスとして定義する。エンコーディング中立なエイリアスと中立でないコードを混在させると、コンパイルエラーや実行時エラーを引き起こすことがある。詳細は
[関数プロトタイプの規約](/windows/win32/intl/conventions-for-function-prototypes)
を参照。

情報