2 Mde UEFI library functions.
4 Copyright (c) 2006 - 2007, Intel Corporation<BR>
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13 Module Name: UefiLib.c
18 // Include common header file for this module.
20 #include "UefiLibInternal.h"
23 Compare whether two names of languages are identical.
25 @param Language1 Name of language 1.
26 @param Language2 Name of language 2.
28 @retval TRUE Language 1 and language 2 are the same.
29 @retval FALSE Language 1 and language 2 are not the same.
34 CompareIso639LanguageCode (
35 IN CONST CHAR8
*Language1
,
36 IN CONST CHAR8
*Language2
42 Name1
= ReadUnaligned24 ((CONST UINT32
*) Language1
);
43 Name2
= ReadUnaligned24 ((CONST UINT32
*) Language2
);
45 return (BOOLEAN
) (Name1
== Name2
);
49 This function searches the list of configuration tables stored in the EFI System
50 Table for a table with a GUID that matches TableGuid. If a match is found,
51 then a pointer to the configuration table is returned in Table, and EFI_SUCCESS
52 is returned. If a matching GUID is not found, then EFI_NOT_FOUND is returned.
54 @param TableGuid Pointer to table's GUID type..
55 @param Table Pointer to the table associated with TableGuid in the EFI System Table.
57 @retval EFI_SUCCESS A configuration table matching TableGuid was found.
58 @retval EFI_NOT_FOUND A configuration table matching TableGuid could not be found.
63 EfiGetSystemConfigurationTable (
64 IN EFI_GUID
*TableGuid
,
68 EFI_SYSTEM_TABLE
*SystemTable
;
71 ASSERT (TableGuid
!= NULL
);
72 ASSERT (Table
!= NULL
);
76 for (Index
= 0; Index
< SystemTable
->NumberOfTableEntries
; Index
++) {
77 if (CompareGuid (TableGuid
, &(SystemTable
->ConfigurationTable
[Index
].VendorGuid
))) {
78 *Table
= SystemTable
->ConfigurationTable
[Index
].VendorTable
;
87 This function causes the notification function to be executed for every protocol
88 of type ProtocolGuid instance that exists in the system when this function is
89 invoked. In addition, every time a protocol of type ProtocolGuid instance is
90 installed or reinstalled, the notification function is also executed.
92 @param ProtocolGuid Supplies GUID of the protocol upon whose installation the event is fired.
93 @param NotifyTpl Supplies the task priority level of the event notifications.
94 @param NotifyFunction Supplies the function to notify when the event is signaled.
95 @param NotifyContext The context parameter to pass to NotifyFunction.
96 @param Registration A pointer to a memory location to receive the registration value.
98 @return The notification event that was created.
103 EfiCreateProtocolNotifyEvent(
104 IN EFI_GUID
*ProtocolGuid
,
105 IN EFI_TPL NotifyTpl
,
106 IN EFI_EVENT_NOTIFY NotifyFunction
,
107 IN VOID
*NotifyContext
, OPTIONAL
108 OUT VOID
**Registration
118 Status
= gBS
->CreateEvent (
125 ASSERT_EFI_ERROR (Status
);
128 // Register for protocol notifactions on this event
131 Status
= gBS
->RegisterProtocolNotify (
137 ASSERT_EFI_ERROR (Status
);
140 // Kick the event so we will perform an initial pass of
141 // current installed drivers
144 gBS
->SignalEvent (Event
);
149 This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.
150 This event is signaled with EfiNamedEventSignal(). This provide the ability for
151 one or more listeners on the same event named by the GUID specified by Name.
153 @param Name Supplies GUID name of the event.
154 @param NotifyTpl Supplies the task priority level of the event notifications.
155 @param NotifyFunction Supplies the function to notify when the event is signaled.
156 @param NotifyContext The context parameter to pass to NotifyFunction.
157 @param Registration A pointer to a memory location to receive the registration value.
159 @retval EFI_SUCCESS A named event was created.
160 @retval EFI_OUT_OF_RESOURCES There are not enough resource to create the named event.
165 EfiNamedEventListen (
166 IN CONST EFI_GUID
*Name
,
167 IN EFI_TPL NotifyTpl
,
168 IN EFI_EVENT_NOTIFY NotifyFunction
,
169 IN CONST VOID
*NotifyContext
, OPTIONAL
170 OUT VOID
*Registration OPTIONAL
175 VOID
*RegistrationLocal
;
180 Status
= gBS
->CreateEvent (
184 (VOID
*) NotifyContext
,
187 ASSERT_EFI_ERROR (Status
);
190 // The Registration is not optional to RegisterProtocolNotify().
191 // To make it optional to EfiNamedEventListen(), may need to substitute with a local.
193 if (Registration
!= NULL
) {
194 RegistrationLocal
= Registration
;
196 RegistrationLocal
= &RegistrationLocal
;
200 // Register for an installation of protocol interface
203 Status
= gBS
->RegisterProtocolNotify (
208 ASSERT_EFI_ERROR (Status
);
214 This function signals the named event specified by Name. The named event must
215 have been created with EfiNamedEventListen().
217 @param Name Supplies GUID name of the event.
219 @retval EFI_SUCCESS A named event was signaled.
220 @retval EFI_OUT_OF_RESOURCES There are not enough resource to signal the named event.
225 EfiNamedEventSignal (
226 IN CONST EFI_GUID
*Name
233 Status
= gBS
->InstallProtocolInterface (
236 EFI_NATIVE_INTERFACE
,
239 ASSERT_EFI_ERROR (Status
);
241 Status
= gBS
->UninstallProtocolInterface (
246 ASSERT_EFI_ERROR (Status
);
252 Returns the current TPL.
254 This function returns the current TPL. There is no EFI service to directly
255 retrieve the current TPL. Instead, the RaiseTPL() function is used to raise
256 the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level
257 can then immediately be restored back to the current TPL level with a call
262 @retvale EFI_TPL The current TPL.
273 Tpl
= gBS
->RaiseTPL (TPL_HIGH_LEVEL
);
274 gBS
->RestoreTPL (Tpl
);
281 This function initializes a basic mutual exclusion lock to the released state
282 and returns the lock. Each lock provides mutual exclusion access at its task
283 priority level. Since there is no preemption or multiprocessor support in EFI,
284 acquiring the lock only consists of raising to the locks TPL.
286 @param Lock A pointer to the lock data structure to initialize.
287 @param Priority EFI TPL associated with the lock.
295 IN OUT EFI_LOCK
*Lock
,
299 ASSERT (Lock
!= NULL
);
300 ASSERT (Priority
<= TPL_HIGH_LEVEL
);
302 Lock
->Tpl
= Priority
;
303 Lock
->OwnerTpl
= TPL_APPLICATION
;
304 Lock
->Lock
= EfiLockReleased
;
309 This function raises the system's current task priority level to the task
310 priority level of the mutual exclusion lock. Then, it places the lock in the
313 @param Priority The task priority level of the lock.
322 ASSERT (Lock
!= NULL
);
323 ASSERT (Lock
->Lock
== EfiLockReleased
);
325 Lock
->OwnerTpl
= gBS
->RaiseTPL (Lock
->Tpl
);
326 Lock
->Lock
= EfiLockAcquired
;
330 This function raises the system's current task priority level to the task
331 priority level of the mutual exclusion lock. Then, it attempts to place the
332 lock in the acquired state.
334 @param Lock A pointer to the lock to acquire.
336 @retval EFI_SUCCESS The lock was acquired.
337 @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.
342 EfiAcquireLockOrFail (
347 ASSERT (Lock
!= NULL
);
348 ASSERT (Lock
->Lock
!= EfiLockUninitialized
);
350 if (Lock
->Lock
== EfiLockAcquired
) {
352 // Lock is already owned, so bail out
354 return EFI_ACCESS_DENIED
;
357 Lock
->OwnerTpl
= gBS
->RaiseTPL (Lock
->Tpl
);
359 Lock
->Lock
= EfiLockAcquired
;
365 This function transitions a mutual exclusion lock from the acquired state to
366 the released state, and restores the system's task priority level to its
369 @param Lock A pointer to the lock to release.
380 ASSERT (Lock
!= NULL
);
381 ASSERT (Lock
->Lock
== EfiLockAcquired
);
383 Tpl
= Lock
->OwnerTpl
;
385 Lock
->Lock
= EfiLockReleased
;
387 gBS
->RestoreTPL (Tpl
);
391 Tests whether a controller handle is being managed by a specific driver.
393 This function tests whether the driver specified by DriverBindingHandle is
394 currently managing the controller specified by ControllerHandle. This test
395 is performed by evaluating if the the protocol specified by ProtocolGuid is
396 present on ControllerHandle and is was opened by DriverBindingHandle with an
397 attribute of EFI_OPEN_PROTOCOL_BY_DRIVER.
398 If ProtocolGuid is NULL, then ASSERT().
400 @param ControllerHandle A handle for a controller to test.
401 @param DriverBindingHandle Specifies the driver binding handle for the
403 @param ProtocolGuid Specifies the protocol that the driver specified
404 by DriverBindingHandle opens in its Start()
407 @retval EFI_SUCCESS ControllerHandle is managed by the driver
408 specifed by DriverBindingHandle.
409 @retval EFI_UNSUPPORTED ControllerHandle is not managed by the driver
410 specifed by DriverBindingHandle.
415 EfiTestManagedDevice (
416 IN CONST EFI_HANDLE ControllerHandle
,
417 IN CONST EFI_HANDLE DriverBindingHandle
,
418 IN CONST EFI_GUID
*ProtocolGuid
422 VOID
*ManagedInterface
;
424 ASSERT (ProtocolGuid
!= NULL
);
426 Status
= gBS
->OpenProtocol (
428 (EFI_GUID
*) ProtocolGuid
,
432 EFI_OPEN_PROTOCOL_BY_DRIVER
434 if (!EFI_ERROR (Status
)) {
437 (EFI_GUID
*) ProtocolGuid
,
441 return EFI_UNSUPPORTED
;
444 if (Status
!= EFI_ALREADY_STARTED
) {
445 return EFI_UNSUPPORTED
;
452 Tests whether a child handle is a child device of the controller.
454 This function tests whether ChildHandle is one of the children of
455 ControllerHandle. This test is performed by checking to see if the protocol
456 specified by ProtocolGuid is present on ControllerHandle and opened by
457 ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
458 If ProtocolGuid is NULL, then ASSERT().
460 @param ControllerHandle A handle for a (parent) controller to test.
461 @param ChildHandle A child handle to test.
462 @param ConsumsedGuid Supplies the protocol that the child controller
463 opens on its parent controller.
465 @retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle.
466 @retval EFI_UNSUPPORTED ChildHandle is not a child of the
473 IN CONST EFI_HANDLE ControllerHandle
,
474 IN CONST EFI_HANDLE ChildHandle
,
475 IN CONST EFI_GUID
*ProtocolGuid
479 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
*OpenInfoBuffer
;
483 ASSERT (ProtocolGuid
!= NULL
);
486 // Retrieve the list of agents that are consuming the specific protocol
487 // on ControllerHandle.
489 Status
= gBS
->OpenProtocolInformation (
491 (EFI_GUID
*) ProtocolGuid
,
495 if (EFI_ERROR (Status
)) {
496 return EFI_UNSUPPORTED
;
500 // Inspect if ChildHandle is one of the agents.
502 Status
= EFI_UNSUPPORTED
;
503 for (Index
= 0; Index
< EntryCount
; Index
++) {
504 if ((OpenInfoBuffer
[Index
].ControllerHandle
== ChildHandle
) &&
505 (OpenInfoBuffer
[Index
].Attributes
& EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER
) != 0) {
506 Status
= EFI_SUCCESS
;
511 FreePool (OpenInfoBuffer
);
516 This function looks up a Unicode string in UnicodeStringTable.
517 If Language is a member of SupportedLanguages and a Unicode
518 string is found in UnicodeStringTable that matches the
519 language code specified by Language, then it is returned in
522 @param Language A pointer to the ISO 639-2
523 language code for the Unicode
524 string to look up and return.
526 @param SupportedLanguages A pointer to the set of ISO
528 codes that the Unicode string
529 table supports. Language must
530 be a member of this set.
532 @param UnicodeStringTable A pointer to the table of
535 @param UnicodeString A pointer to the Unicode
536 string from UnicodeStringTable
537 that matches the language
538 specified by Language.
540 @retval EFI_SUCCESS The Unicode string that
541 matches the language specified
542 by Language was found in the
543 table of Unicoide strings
544 UnicodeStringTable, and it was
545 returned in UnicodeString.
547 @retval EFI_INVALID_PARAMETER Language is NULL.
549 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
550 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
552 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
554 @retval EFI_UNSUPPORTED The language specified by
555 Language is not a member
556 ofSupportedLanguages.
558 @retval EFI_UNSUPPORTED The language specified by
559 Language is not supported by
565 LookupUnicodeString (
566 IN CONST CHAR8
*Language
,
567 IN CONST CHAR8
*SupportedLanguages
,
568 IN CONST EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
,
569 OUT CHAR16
**UnicodeString
573 // Make sure the parameters are valid
575 if (Language
== NULL
|| UnicodeString
== NULL
) {
576 return EFI_INVALID_PARAMETER
;
580 // If there are no supported languages, or the Unicode String Table is empty, then the
581 // Unicode String specified by Language is not supported by this Unicode String Table
583 if (SupportedLanguages
== NULL
|| UnicodeStringTable
== NULL
) {
584 return EFI_UNSUPPORTED
;
588 // Make sure Language is in the set of Supported Languages
590 while (*SupportedLanguages
!= 0) {
591 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
594 // Search the Unicode String Table for the matching Language specifier
596 while (UnicodeStringTable
->Language
!= NULL
) {
597 if (CompareIso639LanguageCode (Language
, UnicodeStringTable
->Language
)) {
600 // A matching string was found, so return it
602 *UnicodeString
= UnicodeStringTable
->UnicodeString
;
606 UnicodeStringTable
++;
609 return EFI_UNSUPPORTED
;
612 SupportedLanguages
+= 3;
615 return EFI_UNSUPPORTED
;
621 This function looks up a Unicode string in UnicodeStringTable.
622 If Language is a member of SupportedLanguages and a Unicode
623 string is found in UnicodeStringTable that matches the
624 language code specified by Language, then it is returned in
627 @param Language A pointer to the ISO 639-2 or
628 RFC 3066 language code for the
629 Unicode string to look up and
632 @param SupportedLanguages A pointer to the set of ISO
633 639-2 or RFC 3066 language
634 codes that the Unicode string
635 table supports. Language must
636 be a member of this set.
638 @param UnicodeStringTable A pointer to the table of
641 @param UnicodeString A pointer to the Unicode
642 string from UnicodeStringTable
643 that matches the language
644 specified by Language.
646 @param Iso639Language Specify the language code
647 format supported. If true,
648 then the format follow ISO
649 639-2. If false, then it
652 @retval EFI_SUCCESS The Unicode string that
653 matches the language specified
654 by Language was found in the
655 table of Unicoide strings
656 UnicodeStringTable, and it was
657 returned in UnicodeString.
659 @retval EFI_INVALID_PARAMETER Language is NULL.
661 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
663 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
665 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.
667 @retval EFI_UNSUPPORTED The language specified by
668 Language is not a member
669 ofSupportedLanguages.
671 @retval EFI_UNSUPPORTED The language specified by
672 Language is not supported by
678 LookupUnicodeString2 (
679 IN CONST CHAR8
*Language
,
680 IN CONST CHAR8
*SupportedLanguages
,
681 IN CONST EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
,
682 OUT CHAR16
**UnicodeString
,
683 IN BOOLEAN Iso639Language
688 CHAR8
*LanguageString
;
691 // Make sure the parameters are valid
693 if (Language
== NULL
|| UnicodeString
== NULL
) {
694 return EFI_INVALID_PARAMETER
;
698 // If there are no supported languages, or the Unicode String Table is empty, then the
699 // Unicode String specified by Language is not supported by this Unicode String Table
701 if (SupportedLanguages
== NULL
|| UnicodeStringTable
== NULL
) {
702 return EFI_UNSUPPORTED
;
706 // Make sure Language is in the set of Supported Languages
709 while (*SupportedLanguages
!= 0) {
710 if (Iso639Language
) {
711 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
715 SupportedLanguages
+= 3;
717 for (Index
= 0; SupportedLanguages
[Index
] != 0 && SupportedLanguages
[Index
] != ';'; Index
++);
718 if (AsciiStrnCmp(SupportedLanguages
, Language
, Index
) == 0) {
722 SupportedLanguages
+= Index
;
723 for (; *SupportedLanguages
!= 0 && *SupportedLanguages
== ';'; SupportedLanguages
++);
728 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
731 return EFI_UNSUPPORTED
;
735 // Search the Unicode String Table for the matching Language specifier
737 while (UnicodeStringTable
->Language
!= NULL
) {
738 LanguageString
= UnicodeStringTable
->Language
;
739 while (0 != *LanguageString
) {
740 for (Index
= 0 ;LanguageString
[Index
] != 0 && LanguageString
[Index
] != ';'; Index
++);
741 if (AsciiStrnCmp(LanguageString
, Language
, Index
) == 0) {
742 *UnicodeString
= UnicodeStringTable
->UnicodeString
;
745 LanguageString
+= Index
;
746 for (Index
= 0 ;LanguageString
[Index
] != 0 && LanguageString
[Index
] == ';'; Index
++);
748 UnicodeStringTable
++;
751 return EFI_UNSUPPORTED
;
757 This function adds a Unicode string to UnicodeStringTable.
758 If Language is a member of SupportedLanguages then
759 UnicodeString is added to UnicodeStringTable. New buffers are
760 allocated for both Language and UnicodeString. The contents
761 of Language and UnicodeString are copied into these new
762 buffers. These buffers are automatically freed when
763 FreeUnicodeStringTable() is called.
765 @param Language A pointer to the ISO 639-2
766 language code for the Unicode
769 @param SupportedLanguages A pointer to the set of ISO
770 639-2 language codes that the
771 Unicode string table supports.
772 Language must be a member of
775 @param UnicodeStringTable A pointer to the table of
778 @param UnicodeString A pointer to the Unicode
781 @retval EFI_SUCCESS The Unicode string that
782 matches the language specified
783 by Language was found in the
784 table of Unicode strings
785 UnicodeStringTable, and it was
786 returned in UnicodeString.
788 @retval EFI_INVALID_PARAMETER Language is NULL.
790 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
792 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
794 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
796 @retval EFI_ALREADY_STARTED A Unicode string with language
797 Language is already present in
800 @retval EFI_OUT_OF_RESOURCES There is not enough memory to
801 add another Unicode string to
804 @retval EFI_UNSUPPORTED The language specified by
805 Language is not a member of
812 IN CONST CHAR8
*Language
,
813 IN CONST CHAR8
*SupportedLanguages
,
814 IN EFI_UNICODE_STRING_TABLE
**UnicodeStringTable
,
815 IN CONST CHAR16
*UnicodeString
818 UINTN NumberOfEntries
;
819 EFI_UNICODE_STRING_TABLE
*OldUnicodeStringTable
;
820 EFI_UNICODE_STRING_TABLE
*NewUnicodeStringTable
;
821 UINTN UnicodeStringLength
;
824 // Make sure the parameter are valid
826 if (Language
== NULL
|| UnicodeString
== NULL
|| UnicodeStringTable
== NULL
) {
827 return EFI_INVALID_PARAMETER
;
831 // If there are no supported languages, then a Unicode String can not be added
833 if (SupportedLanguages
== NULL
) {
834 return EFI_UNSUPPORTED
;
838 // If the Unicode String is empty, then a Unicode String can not be added
840 if (UnicodeString
[0] == 0) {
841 return EFI_INVALID_PARAMETER
;
845 // Make sure Language is a member of SupportedLanguages
847 while (*SupportedLanguages
!= 0) {
848 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
851 // Determine the size of the Unicode String Table by looking for a NULL Language entry
854 if (*UnicodeStringTable
!= NULL
) {
855 OldUnicodeStringTable
= *UnicodeStringTable
;
856 while (OldUnicodeStringTable
->Language
!= NULL
) {
857 if (CompareIso639LanguageCode (Language
, OldUnicodeStringTable
->Language
)) {
858 return EFI_ALREADY_STARTED
;
861 OldUnicodeStringTable
++;
867 // Allocate space for a new Unicode String Table. It must hold the current number of
868 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
871 NewUnicodeStringTable
= AllocatePool ((NumberOfEntries
+ 2) * sizeof (EFI_UNICODE_STRING_TABLE
));
872 if (NewUnicodeStringTable
== NULL
) {
873 return EFI_OUT_OF_RESOURCES
;
877 // If the current Unicode String Table contains any entries, then copy them to the
878 // newly allocated Unicode String Table.
880 if (*UnicodeStringTable
!= NULL
) {
882 NewUnicodeStringTable
,
884 NumberOfEntries
* sizeof (EFI_UNICODE_STRING_TABLE
)
889 // Allocate space for a copy of the Language specifier
891 NewUnicodeStringTable
[NumberOfEntries
].Language
= AllocateCopyPool (3, Language
);
892 if (NewUnicodeStringTable
[NumberOfEntries
].Language
== NULL
) {
893 gBS
->FreePool (NewUnicodeStringTable
);
894 return EFI_OUT_OF_RESOURCES
;
898 // Compute the length of the Unicode String
900 for (UnicodeStringLength
= 0; UnicodeString
[UnicodeStringLength
] != 0; UnicodeStringLength
++)
904 // Allocate space for a copy of the Unicode String
906 NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
= AllocateCopyPool (
907 (UnicodeStringLength
+ 1) * sizeof (CHAR16
),
910 if (NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
== NULL
) {
911 gBS
->FreePool (NewUnicodeStringTable
[NumberOfEntries
].Language
);
912 gBS
->FreePool (NewUnicodeStringTable
);
913 return EFI_OUT_OF_RESOURCES
;
917 // Mark the end of the Unicode String Table
919 NewUnicodeStringTable
[NumberOfEntries
+ 1].Language
= NULL
;
920 NewUnicodeStringTable
[NumberOfEntries
+ 1].UnicodeString
= NULL
;
923 // Free the old Unicode String Table
925 if (*UnicodeStringTable
!= NULL
) {
926 gBS
->FreePool (*UnicodeStringTable
);
930 // Point UnicodeStringTable at the newly allocated Unicode String Table
932 *UnicodeStringTable
= NewUnicodeStringTable
;
937 SupportedLanguages
+= 3;
940 return EFI_UNSUPPORTED
;
946 This function adds a Unicode string to UnicodeStringTable.
947 If Language is a member of SupportedLanguages then
948 UnicodeString is added to UnicodeStringTable. New buffers are
949 allocated for both Language and UnicodeString. The contents
950 of Language and UnicodeString are copied into these new
951 buffers. These buffers are automatically freed when
952 FreeUnicodeStringTable() is called.
954 @param Language A pointer to the ISO 639-2 or
955 RFC 3066 language code for the
956 Unicode string to add.
958 @param SupportedLanguages A pointer to the set of ISO
959 639-2 or RFC 3.66 language
960 codes that the Unicode string
961 table supports. Language must
962 be a member of this set.
964 @param UnicodeStringTable A pointer to the table of
967 @param UnicodeString A pointer to the Unicode
970 @param Iso639Language Specify the language code
971 format supported. If true,
972 then the format follow ISO
973 639-2. If false, then it
976 @retval EFI_SUCCESS The Unicode string that
977 matches the language specified
978 by Language was found in the
979 table of Unicode strings
980 UnicodeStringTable, and it was
981 returned in UnicodeString.
983 @retval EFI_INVALID_PARAMETER Language is NULL.
985 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.
987 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.
989 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.
991 @retval EFI_ALREADY_STARTED A Unicode string with language
992 Language is already present in
995 @retval EFI_OUT_OF_RESOURCES There is not enough memory to
996 add another Unicode string to
999 @retval EFI_UNSUPPORTED The language specified by
1000 Language is not a member of
1007 IN CONST CHAR8
*Language
,
1008 IN CONST CHAR8
*SupportedLanguages
,
1009 IN EFI_UNICODE_STRING_TABLE
**UnicodeStringTable
,
1010 IN CONST CHAR16
*UnicodeString
,
1011 IN BOOLEAN Iso639Language
1014 UINTN NumberOfEntries
;
1015 EFI_UNICODE_STRING_TABLE
*OldUnicodeStringTable
;
1016 EFI_UNICODE_STRING_TABLE
*NewUnicodeStringTable
;
1017 UINTN UnicodeStringLength
;
1020 CHAR8
*LanguageString
;
1023 // Make sure the parameter are valid
1025 if (Language
== NULL
|| UnicodeString
== NULL
|| UnicodeStringTable
== NULL
) {
1026 return EFI_INVALID_PARAMETER
;
1030 // If there are no supported languages, then a Unicode String can not be added
1032 if (SupportedLanguages
== NULL
) {
1033 return EFI_UNSUPPORTED
;
1037 // If the Unicode String is empty, then a Unicode String can not be added
1039 if (UnicodeString
[0] == 0) {
1040 return EFI_INVALID_PARAMETER
;
1044 // Make sure Language is a member of SupportedLanguages
1047 while (*SupportedLanguages
!= 0) {
1048 if (Iso639Language
) {
1049 if (CompareIso639LanguageCode (Language
, SupportedLanguages
)) {
1053 SupportedLanguages
+= 3;
1055 for (Index
= 0; SupportedLanguages
[Index
] != 0 && SupportedLanguages
[Index
] != ';'; Index
++);
1056 if (AsciiStrnCmp(SupportedLanguages
, Language
, Index
) == 0) {
1060 SupportedLanguages
+= Index
;
1061 for (; *SupportedLanguages
!= 0 && *SupportedLanguages
== ';'; SupportedLanguages
++);
1066 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED
1069 return EFI_UNSUPPORTED
;
1073 // Determine the size of the Unicode String Table by looking for a NULL Language entry
1075 NumberOfEntries
= 0;
1076 if (*UnicodeStringTable
!= NULL
) {
1077 OldUnicodeStringTable
= *UnicodeStringTable
;
1078 while (OldUnicodeStringTable
->Language
!= NULL
) {
1079 LanguageString
= OldUnicodeStringTable
->Language
;
1081 while (*LanguageString
) {
1082 for (Index
= 0; LanguageString
[Index
] != 0 && LanguageString
[Index
] != ';'; Index
++);
1084 if (AsciiStrnCmp (Language
, LanguageString
, Index
) == 0) {
1085 return EFI_ALREADY_STARTED
;
1087 LanguageString
+= Index
;
1088 for (; *LanguageString
!= 0 && *LanguageString
== ';'; LanguageString
++);
1090 OldUnicodeStringTable
++;
1096 // Allocate space for a new Unicode String Table. It must hold the current number of
1097 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table
1100 NewUnicodeStringTable
= AllocatePool ((NumberOfEntries
+ 2) * sizeof (EFI_UNICODE_STRING_TABLE
));
1101 if (NewUnicodeStringTable
== NULL
) {
1102 return EFI_OUT_OF_RESOURCES
;
1106 // If the current Unicode String Table contains any entries, then copy them to the
1107 // newly allocated Unicode String Table.
1109 if (*UnicodeStringTable
!= NULL
) {
1111 NewUnicodeStringTable
,
1112 *UnicodeStringTable
,
1113 NumberOfEntries
* sizeof (EFI_UNICODE_STRING_TABLE
)
1118 // Allocate space for a copy of the Language specifier
1120 NewUnicodeStringTable
[NumberOfEntries
].Language
= AllocateCopyPool (AsciiStrSize(Language
), Language
);
1121 if (NewUnicodeStringTable
[NumberOfEntries
].Language
== NULL
) {
1122 gBS
->FreePool (NewUnicodeStringTable
);
1123 return EFI_OUT_OF_RESOURCES
;
1127 // Compute the length of the Unicode String
1129 for (UnicodeStringLength
= 0; UnicodeString
[UnicodeStringLength
] != 0; UnicodeStringLength
++);
1132 // Allocate space for a copy of the Unicode String
1134 NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
= AllocateCopyPool (StrSize (UnicodeString
), UnicodeString
);
1135 if (NewUnicodeStringTable
[NumberOfEntries
].UnicodeString
== NULL
) {
1136 gBS
->FreePool (NewUnicodeStringTable
[NumberOfEntries
].Language
);
1137 gBS
->FreePool (NewUnicodeStringTable
);
1138 return EFI_OUT_OF_RESOURCES
;
1142 // Mark the end of the Unicode String Table
1144 NewUnicodeStringTable
[NumberOfEntries
+ 1].Language
= NULL
;
1145 NewUnicodeStringTable
[NumberOfEntries
+ 1].UnicodeString
= NULL
;
1148 // Free the old Unicode String Table
1150 if (*UnicodeStringTable
!= NULL
) {
1151 gBS
->FreePool (*UnicodeStringTable
);
1155 // Point UnicodeStringTable at the newly allocated Unicode String Table
1157 *UnicodeStringTable
= NewUnicodeStringTable
;
1163 This function frees the table of Unicode strings in UnicodeStringTable.
1164 If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.
1165 Otherwise, each language code, and each Unicode string in the Unicode string
1166 table are freed, and EFI_SUCCESS is returned.
1168 @param UnicodeStringTable A pointer to the table of Unicode strings.
1170 @retval EFI_SUCCESS The Unicode string table was freed.
1175 FreeUnicodeStringTable (
1176 IN EFI_UNICODE_STRING_TABLE
*UnicodeStringTable
1182 // If the Unicode String Table is NULL, then it is already freed
1184 if (UnicodeStringTable
== NULL
) {
1189 // Loop through the Unicode String Table until we reach the end of table marker
1191 for (Index
= 0; UnicodeStringTable
[Index
].Language
!= NULL
; Index
++) {
1194 // Free the Language string from the Unicode String Table
1196 gBS
->FreePool (UnicodeStringTable
[Index
].Language
);
1199 // Free the Unicode String from the Unicode String Table
1201 if (UnicodeStringTable
[Index
].UnicodeString
!= NULL
) {
1202 gBS
->FreePool (UnicodeStringTable
[Index
].UnicodeString
);
1207 // Free the Unicode String Table itself
1209 gBS
->FreePool (UnicodeStringTable
);