ExGetFirmwareEnvironmentVariable 関数 (wdm.h)

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

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

[out, optional] Attributes

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

戻り値

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

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

解説

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

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

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

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

呼び出し元が NULL 以外の 属性 パラメーターを指定した場合、ルーチンは、指定されたシステム ファームウェア環境変数の属性を 、属性が指す場所に書き込みます。 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 変数に書き込まれる値は、0 であるか、前の表の 1 つ以上の属性のビットごとの 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