47. EFI_HII_DATABASE_PROTOCOL의 NewPackageList를 사용하여 문자열 패키지가 포함된 HII 패키지 목록 게시

파트 3: NewPackageList 및 GetString 프로토콜 함수를 사용하여 모든 것을 결합하기

이제 마침내 HII 데이터베이스에 패키지 목록을 등록할 수 있다. 다음은 또 한번 NewPackageList에 대한 설명이다.

EFI_HII_DATABASE_PROTOCOL.NewPackageList()

Summary:
Adds the packages in the package list to the HII database.

Prototype:
typedef
EFI_STATUS
(EFIAPI *EFI_HII_DATABASE_NEW_PACK) (
 IN CONST EFI_HII_DATABASE_PROTOCOL *This,
 IN CONST EFI_HII_PACKAGE_LIST_HEADER *PackageList,
 IN CONST EFI_HANDLE DriverHandle, OPTIONAL
 OUT EFI_HII_HANDLE *Handle
 );

Parameters:
This		A pointer to the EFI_HII_DATABASE_PROTOCOL instance
PackageList	A pointer to an EFI_HII_PACKAGE_LIST_HEADER structure
DriverHandle	Associate the package list with this EFI handle
Handle		A pointer to the EFI_HII_HANDLE instance
Description	This function adds the packages in the package list to the database and returns a handle. If there is a
		EFI_DEVICE_PATH_PROTOCOL associated with the DriverHandle, then this function will create a
		package of type EFI_PACKAGE_TYPE_DEVICE_PATH and add it to the package list.

우리는 이미 PackageList 배열을 채웠으므로 이 함수를 다음과 같이 사용할 수 있다.

  EFI_HII_HANDLE Handle;
  EFI_STATUS Status = gHiiDatabase->NewPackageList(gHiiDatabase, PackageListHdr, NULL, &Handle);
  if (EFI_ERROR(Status))
  {
    Print(L"Can't register HII Package list %g, status = %r\n", gHIIStringsCGuid, Status);
  }

이제 우리의 패키지 목록에 대한 EFI_HII_HANDLE Handle 이 있으므로 HII 데이터베이스에서 문자열을 가져오는 것을 시도해볼 차례이다.

이를 위해 다른 HII 데이터베이스 프로토콜인 EFI_HII_STRING_PROTOCOL의 GetString을 활용할 수 있다.

EFI_HII_STRING_PROTOCOL.GetString()

Summary:
Returns information about a string in a specific language, associated with a package list.

Prototype:
typedef
EFI_STATUS
(EFIAPI *EFI_HII_GET_STRING) (
 IN CONST EFI_HII_STRING_PROTOCOL *This,
 IN CONST CHAR8 *Language,
 IN EFI_HII_HANDLE PackageList,
 IN EFI_STRING_ID StringId,
 OUT EFI_STRING String,
 IN OUT UINTN *StringSize,
 OUT EFI_FONT_INFO **StringFontInfo OPTIONAL
 );
 
Parameters:
This			A pointer to the EFI_HII_STRING_PROTOCOL instance.
PackageList		The package list in the HII database to search for the specified string.
Language		Points to the language for the retrieved string. Callers of interfaces that require RFC
				4646 language codes to retrieve a Unicode string must use the RFC 4647 algorithm to
				lookup the Unicode string with the closest matching RFC 4646 language code.
StringId		The string’s id, which is unique within PackageList.
String			Points to the new null-terminated string.
StringSize		On entry, points to the size of the buffer pointed to by String, in bytes. On return,
				points to the length of the string, in bytes.
StringFontInfo	Points to a buffer that will be callee allocated and will have the string's font
				information into this buffer. The caller is responsible for freeing this buffer. If the
				parameter is NULL a buffer will not be allocated and the string font information will
				not be returned.

Description:
This function retrieves the string specified by StringId which is associated with the specified
PackageList in the language Language and copies it into the buffer specified by String.

다시 한번 설명하지만 알 수 없는 크기의 리소스를 가져올 때 사용하는 표준 UEFI체계가 있다.

먼저 StringSize=0으로 GetString()을 호출한다. 이 함수는 EFI_BUFFER_TOO_SMALL을 반환하지만 필요한 값으로 StringSize를 채우게 된다. 그런 다음 이번에는 올바른 StringSize를 사용하여 GetString을 한 번 더 호출한다.

우리의 애플리케이션에 UefiHiiServicesLib를 포함했기 때문에 EFI_HII_STRING_PROTOCOL을 찾기 위해 LocateProtocol을 수행할 필요가 없으며 대신 단순히 gHiiString 변수를 사용할 수 있다.

다음은 단순히 (ld, Language)조합을 제공하여 EFI_HII_HANDLE을 이용해 패키지 목록에서 문자열을 출력하기 위한 PrintStringFromHiiHandle 함수이다.

EFI_STATUS PrintStringFromHiiHandle(EFI_HII_HANDLE* Handle, CHAR8* Language, UINTN StringId)
{
  EFI_STRING String = NULL;
  UINTN StringSize = 0;
  EFI_STATUS Status = gHiiString->GetString(gHiiString, Language, *Handle, StringId, String, &StringSize, NULL);

  if (Status != EFI_BUFFER_TOO_SMALL) {
    return Status;
  }

  String = AllocateZeroPool(StringSize);
  if (String == NULL) {
    return Status;
  }

  Status = gHiiString->GetString(gHiiString, Language, *Handle, StringId, String, &StringSize, NULL);

  Print(L"Status = %r, %s\n", Status, String);

  FreePool(String);

  return EFI_SUCCESS;
}

우리의 패키지를 등록한 후에는 다음과 같이 사용할 수 있다.

  PrintStringFromHiiHandle(&Handle, "en-US", 1);
  PrintStringFromHiiHandle(&Handle, "en-US", 2);
  PrintStringFromHiiHandle(&Handle, "fr-FR", 1);
  PrintStringFromHiiHandle(&Handle, "fr-FR", 2);

이제 모든 것을 결합하고 우리의 앱을 빌드하고 OVMF에서 실행시키면 다음과 같은 값을 얻을 수 있다.

FS0:\> HIIStringsC.efi
Status = Success, English
Status = Success, Hello
Status = Success, French
Status = Success, Bonjour

우리가 만들었던 ShowHII 애플리케이션을 실행시키면 패키지가 추가된 것을 볼 수도 있다.

FS0:\> ShowHII.efi
...
PackageList[20]: GUID=8E0B8ED3-14F7-499D-A224-AEE89DC97FA3; size=0xC0
        Package[0]: type=STRINGS; size=0x53
        Package[1]: type=STRINGS; size=0x55
        Package[2]: type=END; size=0x4

HIIStringsC 애플리케이션을 다시 실행시키면 오류가 발생하는 것을 알아챌 수 있다.

FS0:\> HIIStringsC.efi
Can't register HII Package list 8E0B8ED3-14F7-499D-A224-AEE89DC97FA3, status = Invalid Parameter

이 오류는 동일한 GUID로 두 개의 패키지 목록을 등록할 수 없기 때문에 발생한다.