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

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

[out, optional] Attributes

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

戻り値

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

注釈

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

ハードウェア プラットフォームで使用できるファームウェア環境変数のセットは、ブート ファームウェアによって異なります。 これらの環境変数の場所もファームウェアによって指定されます。 たとえば、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 では、ファームウェア環境変数に対して次の属性が定義されています。

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

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

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

要件

こちらもご覧ください

ExSetFirmwareEnvironmentVariable

GetFirmwareEnvironmentVariable

UNICODE_STRING