SetFirmwareEnvironmentVariableExA 함수(winbase.h)

  • 아티클

지정된 펌웨어 환경 변수의 값을 이 변수가 저장 및 유지 관리되는 방식을 나타내는 특성으로 설정합니다.

구문

BOOL SetFirmwareEnvironmentVariableExA(
  [in] LPCSTR lpName,
  [in] LPCSTR lpGuid,
  [in] PVOID  pValue,
  [in] DWORD  nSize,
  [in] DWORD  dwAttributes
);

매개 변수

[in] lpName

펌웨어 환경 변수의 이름입니다. 포인터는 NULL이 아니어야 합니다.

[in] lpGuid

펌웨어 환경 변수의 네임스페이스를 나타내는 GUID입니다. GUID는 "{xxxxxxxxxx-xxxx-xxxx-xxxx-xxxx}" 형식의 문자열이어야 합니다. 시스템에서 GUID 기반 네임스페이스를 지원하지 않는 경우 이 매개 변수는 무시됩니다. 포인터는 NULL이 아니어야 합니다.

[in] pValue

펌웨어 환경 변수의 새 값에 대한 포인터입니다.

[in] nSize

pValue 버퍼의 크기(바이트)입니다. dwAttributes를 통해 VARIABLE_ATTRIBUTE_APPEND_WRITE, VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS 또는 VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS 변수 특성을 설정하지 않으면 이 값을 0으로 설정하면 이 변수가 삭제됩니다.

[in] dwAttributes

변수와 연결된 UEFI 변수 특성을 설정하는 비트 마스크입니다. UEFI 사양 2.3.1, 섹션 7.2도 참조하세요.

값 의미
VARIABLE_ATTRIBUTE_NON_VOLATILE
0x00000001
 펌웨어 환경 변수는 비휘발성 메모리(예: NVRAM)에 저장됩니다.
VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS
0x00000002
 부팅 서비스 중에 펌웨어 환경 변수에 액세스할 수 있습니다.
VARIABLE_ATTRIBUTE_RUNTIME_ACCESS
0x00000004
 런타임에 펌웨어 환경 변수에 액세스할 수 있습니다.
참고 이 특성이 설정된 변수도 VARIABLE_ATTRIBUTE_BOOTSERVICE_ACCESS 설정해야 합니다.
 
VARIABLE_ATTRIBUTE_HARDWARE_ERROR_RECORD
0x00000008
 런타임에 발생하는 하드웨어 관련 오류를 나타냅니다.
VARIABLE_ATTRIBUTE_AUTHENTICATED_WRITE_ACCESS
0x00000010
 이 펌웨어 환경 변수에 쓰기 전에 충족해야 하는 인증 요구 사항을 나타냅니다. 자세한 내용은 UEFI 사양 2.3.1을 참조하세요.
VARIABLE_ATTRIBUTE_TIME_BASED_AUTHENTICATED_WRITE_ACCESS
0x00000020
 이 펌웨어 환경 변수에 쓰기 전에 충족해야 하는 인증 및 타임스탬프를 나타냅니다. 이 특성을 설정하면 pValue로 표시되는 버퍼는 전체(및 직렬화된) EFI_VARIABLE_AUTHENTICATION_2 설명자의 instance 시작합니다. 자세한 내용은 UEFI 사양 2.3.1을 참조하세요.
VARIABLE_ATTRIBUTE_APPEND_WRITE
0x00000040
 pValue 값으로 기존 환경 변수를 추가합니다. 펌웨어가 작업을 지원하지 않는 경우 SetFirmwareEnvironmentVariableEx 는 ERROR_INVALID_FUNCTION 반환합니다.

반환 값

함수가 성공하면 반환 값은 0이 아닌 값입니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다. 가능한 오류 코드에는 ERROR_INVALID_FUNCTION 포함됩니다.

설명

Windows 10 버전 1803부터 유니버설 Windows 앱은 UEFI 펌웨어 변수를 읽고 쓸 수 있습니다. 자세한 내용은 유니버설 Windows 앱에서 UEFI 펌웨어 변수 액세스를 참조하세요.

Windows 10 버전 1803부터는 UMDF(User-Mode Driver Framework) 드라이버에서도 UEFI 펌웨어 변수를 읽을 수 있습니다. UMDF 드라이버에서 UEFI 펌웨어 변수를 작성하는 것은 지원되지 않습니다.

펌웨어 환경 변수를 작성하려면 앱이 실행 중인 사용자 계정에 SE_SYSTEM_ENVIRONMENT_NAME 권한이 있어야 합니다. 유니버설 Windows 앱은 관리자 계정에서 실행되어야 하며 유니버설 Windows 앱의 Access UEFI 펌웨어 변수에 설명된 요구 사항을 따라야 합니다.

변수의 특성을 변경하는 올바른 방법은 변수를 삭제하고 다른 특성으로 다시 만드는 것입니다.

정확한 펌웨어 환경 변수 집합은 부팅 펌웨어에 의해 결정됩니다. 이러한 환경 변수의 위치도 펌웨어에 의해 지정됩니다. 예를 들어 UEFI 기반 시스템에서 NVRAM에는 시스템 부팅 설정을 지정하는 펌웨어 환경 변수가 포함되어 있습니다. 사용되는 특정 변수에 대한 자세한 내용은 UEFI 사양을 참조하세요. UEFI 및 Windows에 대한 자세한 내용은 UEFI 및 Windows를 참조하세요.

레거시 BIOS 기반 시스템에서는 펌웨어 변수가 지원되지 않습니다. SetFirmwareEnvironmentVariableEx 함수는 레거시 BIOS 기반 시스템에서 항상 실패하거나 레거시 BIOS 및 UEFI를 모두 지원하는 시스템에서 레거시 BIOS를 사용하여 Windows를 설치한 경우 항상 실패합니다. 이러한 조건을 식별하려면 lpName 매개 변수의 빈 문자열("")과 lpGuid 매개 변수에 대해 "{00000000-0000-0000-0000-000000000000}"와 같은 더미 GUID와 같은 더미 펌웨어 환경 이름을 사용하여 함수를 호출합니다. 레거시 BIOS 기반 시스템 또는 레거시 BIOS를 사용하여 Windows가 설치된 레거시 BIOS 및 UEFI를 모두 지원하는 시스템에서는 ERROR_INVALID_FUNCTION 함께 함수가 실패합니다. UEFI 기반 시스템에서는 더미 GUID 네임스페이스가 존재하지 않음을 나타내기 위해 ERROR_NOACCESS 같은 펌웨어 관련 오류와 함께 함수가 실패합니다.

참고

winbase.h 헤더는 SETFirmwareEnvironmentVariableEx를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

   
지원되는 최소 클라이언트 Windows 8 [데스크톱 앱 | UWP 앱]
지원되는 최소 서버 Windows Server 2012 [데스크톱 앱 | UWP 앱]
대상 플랫폼 Windows
헤더 winbase.h(Windows.h 포함)
라이브러리 Kernel32.lib
DLL Kernel32.dll

참고 항목

유니버설 Windows 앱에서 UEFI 펌웨어 변수에 액세스

GetFirmwareEnvironmentVariableEx

SetFirmwareEnvironmentVariable