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를 지원하지 않을 수 있습니다. 이러한 플랫폼에서 모든 변수는 하나의 공통 네임스페이스로 그룹화되고 VendorGuid 매개 변수는 무시됩니다.

[out, optional] Value

루틴이 지정된 환경 변수의 값을 쓰는 호출자 할당 버퍼에 대한 포인터입니다.

[in, out] ValueLength

버퍼 크기를 포함하는 위치에 대한 포인터입니다. 항목에서 이 매개 변수가 가리키는 위치에는 호출자가 제공한 값 버퍼의 크기(바이트)가 포함됩니다. 종료하기 전에 루틴은 변수 값의 크기(바이트)를 이 위치에 씁니다. 루틴이 STATUS_SUCCESS 반환하는 경우 *ValueLength 출력 값은 Value 버퍼에 기록된 데이터 바이트 수입니다. 루틴이 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 웹 사이트의 통합 확장 가능 펌웨어 인터페이스 사양을 참조하세요. 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이 아닌 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

이러한 특성 값은 플래그 비트로 정의됩니다. 특성이 가리키는 ULONG 변수에 기록된 값은 이전 표에 있는 하나 이상의 특성 중 0 또는 비트 OR입니다. 자세한 내용은 UEFI 웹 사이트의 UEFI 사양을 참조하세요.

백업 데이터 저장소를 만드는 경우 필요한 경우 ExSetFirmwareEnvironmentVariable 루틴을 호출하여 복원할 수 있도록 이 함수를 사용하여 플랫폼에 대한 모든 부팅 설정을 저장할 수 있습니다.

ExGetFirmwareEnvironmentVariable 은 Win32 GetFirmwareEnvironmentVariable 함수와 동일한 커널 모드입니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8 시작해서 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL

추가 정보

ExSetFirmwareEnvironmentVariable

GetFirmwareEnvironmentVariable

UNICODE_STRING