ExGetFirmwareEnvironmentVariable 関数 (wdm.h)

[アーティクル]
03/14/2023

ExGetFirmwareEnvironmentVariable ルーチンは、指定されたシステムファームウェア環境変数の値を取得します。

構文

NTSTATUS ExGetFirmwareEnvironmentVariable(
  [in]            PUNICODE_STRING VariableName,
  [in]            LPGUID          VendorGuid,
  [out, optional] PVOID           Value,
  [in, out]       PULONG          ValueLength,
  [out, optional] PULONG          Attributes
);

パラメーター

[in] VariableName

指定した環境変数の名前を含む UNICODE_STRING 構造体へのポインター。

[in] VendorGuid

指定した環境変数に関連付けられているベンダーを識別する GUID へのポインター。環境変数は、ベンダーの GUID に基づいて名前空間にグループ化されます。一部のハードウェアプラットフォームでは、ベンダー GUID がサポートされていない場合があります。これらのプラットフォームでは、すべての変数が 1 つの共通名前空間にグループ化され、 VendorGuid パラメーターは無視されます。

[out, optional] Value

ルーチンが指定した環境変数の値を書き込む呼び出し元によって割り当てられたバッファーへのポインター。

[in, out] ValueLength

バッファーサイズを含む場所へのポインター。エントリの場合、このパラメーターが指す場所には、呼び出し元が指定した Value バッファーのサイズ (バイト単位) が含まれます。終了する前に、ルーチンは変数値のサイズ (バイト単位) をこの場所に書き込みます。ルーチンがSTATUS_SUCCESSを返す場合、*ValueLength 出力値は Value バッファーに書き込まれたデータのバイト数です。ルーチンが STATUS_BUFFER_TOO_SMALLを返す場合、*ValueLength は必要なバッファーサイズです。

[out, optional] Attributes

ルーチンが指定した環境変数の属性を書き込む場所へのポインター。このパラメーターは省略可能であり、呼び出し元が属性を必要としない場合は NULL に設定できます。詳細については、「解説」を参照してください。

戻り値

ExGetFirmwareEnvironmentVariable は、成功した場合STATUS_SUCCESSを返します。可能な戻り値には、次のエラー状態コードが含まれます。

リターンコード	説明
STATUS_INSUFFICIENT_RESOURCES	使用可能なシステムリソースは、要求された操作を完了するには不十分です。
STATUS_BUFFER_TOO_SMALL	Value バッファーが小さすぎます。
STATUS_VARIABLE_NOT_FOUND	要求された変数が存在しません。
STATUS_INVALID_PARAMETER	パラメーターの 1 つが無効です。
STATUS_NOT_IMPLEMENTED	このルーチンは、このプラットフォームではサポートされていません。
STATUS_UNSUCCESSFUL	ファームウェアから認識できないエラーが返されました。

注釈

システムファームウェア環境変数には、ハードウェアプラットフォームに実装されているブートファームウェア環境と、ファームウェア環境で実行されるオペレーティングシステムローダーとその他のソフトウェアの間で渡されるデータ値が含まれます。

ハードウェアプラットフォームで使用できるファームウェア環境変数のセットは、ブートファームウェアによって異なります。これらの環境変数の場所もファームウェアによって指定されます。たとえば、UEFI ベースのプラットフォームでは、NVRAM には、システムブート設定を指定するファームウェア環境変数が含まれています。使用される特定の変数の詳細については、 UEFI Web サイトの「Unified Extensible Firmware Interface Specification」を参照してください。 UEFI と Windows の詳細については、「 UEFI と Windows」を参照してください。

ファームウェア環境変数は、レガシ BIOS ベースのプラットフォームではサポートされていません。 ExGetFirmwareEnvironmentVariable の呼び出しは、レガシ BIOS ベースのプラットフォームでは常に失敗します。また、Windows がレガシ BIOS と UEFI の両方をサポートするプラットフォームにレガシ BIOS を使用してインストールされている場合も失敗します。これらの条件を識別するには、まず uuidgen または同様のツールを使用して、ランダムな一意の GUID を静的に生成します。次に、このルーチンを呼び出して特定の変数名を検索し、その GUID を VendorGuid パラメーターとして指定します。

レガシ BIOS ベースのプラットフォーム、またはレガシ BIOS と UEFI の両方をサポートしているが、Windows がレガシ BIOS を使用してインストールされているプラットフォームでは、この関数は STATUS_NOT_IMPLEMENTED で失敗します。 UEFI ベースのプラットフォームでは、ダミー GUID 名前空間が存在しないことを示すために、STATUS_VARIABLE_NOT_FOUNDなどのファームウェアに固有のエラーで関数が失敗します。

呼び出し元が NULL 以外の Attributes パラメーターを指定した場合、ルーチンは、指定されたシステムファームウェア環境変数の属性を Attributes が指す場所に書き込みます。 UEFI 仕様のバージョン 2.3.1 では、ファームウェア環境変数に対して次の属性が定義されています。

変数名	値
EFI_VARIABLE_NON_VOLATILE	0x00000001
EFI_VARIABLE_BOOTSERVICE_ACCESS	0x00000002
EFI_VARIABLE_RUNTIME_ACCESS	0x00000004
EFI_VARIABLE_HARDWARE_ERROR_RECORD	0x00000008
EFI_VARIABLE_AUTHENTICATED_WRITE_ACCESS	0x00000010
EFI_VARIABLE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS	0x00000020
EFI_VARIABLE_APPEND_WRITE	0x00000040

これらの属性値はフラグビットとして定義されます。 Attributes が指す ULONG 変数に書き込まれる値は、前の表の 1 つ以上の属性の 0 またはビットごとの OR です。詳細については、UEFI Web サイトの UEFI 仕様を参照してください。

バックアップデータストアを作成する場合は、必要に応じて ExSetFirmwareEnvironmentVariable ルーチンを呼び出して復元できるように、この関数を使用してプラットフォームのすべてのブート設定を保存できます。

ExGetFirmwareEnvironmentVariable は、Win32 GetFirmwareEnvironmentVariable 関数と同等のカーネルモードです。

要件

要件	値
サポートされている最小のクライアント	Windows 8以降で使用できます。
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

こちらもご覧ください

ExSetFirmwareEnvironmentVariable

GetFirmwareEnvironmentVariable

UNICODE_STRING

次の方法で共有

ExGetFirmwareEnvironmentVariable 関数 (wdm.h)

構文

パラメーター

戻り値

注釈

要件

こちらもご覧ください

フィードバック

その他のリソース