MdePkg UefiLib: Make the event empty function public
[mirror_edk2.git] / IntelFrameworkPkg / Library / FrameworkUefiLib / UefiLib.c
CommitLineData
79964ac8 1/** @file\r
bf428cb3 2 The UEFI Library provides functions and macros that simplify the development of \r
3 UEFI Drivers and UEFI Applications. These functions and macros help manage EFI \r
4 events, build simple locks utilizing EFI Task Priority Levels (TPLs), install \r
5 EFI Driver Model related protocols, manage Unicode string tables for UEFI Drivers, \r
6 and print messages on the console output and standard error devices.\r
79964ac8 7\r
4ea439fb 8 Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR>\r
2b3687db 9 This program and the accompanying materials\r
79964ac8 10 are licensed and made available under the terms and conditions of the BSD License\r
11 which accompanies this distribution. The full text of the license may be found at\r
12 http://opensource.org/licenses/bsd-license.php\r
13\r
14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
16\r
79964ac8 17**/\r
18\r
bf428cb3 19\r
20#include "UefiLibInternal.h"\r
79964ac8 21\r
22/**\r
23 Compare whether two names of languages are identical.\r
24\r
25 @param Language1 Name of language 1.\r
26 @param Language2 Name of language 2.\r
27\r
28 @retval TRUE Language 1 and language 2 are the same.\r
29 @retval FALSE Language 1 and language 2 are not the same.\r
30\r
31**/\r
79964ac8 32BOOLEAN\r
33CompareIso639LanguageCode (\r
34 IN CONST CHAR8 *Language1,\r
35 IN CONST CHAR8 *Language2\r
36 )\r
37{\r
38 UINT32 Name1;\r
39 UINT32 Name2;\r
40\r
41 Name1 = ReadUnaligned24 ((CONST UINT32 *) Language1);\r
42 Name2 = ReadUnaligned24 ((CONST UINT32 *) Language2);\r
43\r
44 return (BOOLEAN) (Name1 == Name2);\r
45}\r
46\r
47/**\r
bf428cb3 48 Retrieves a pointer to the system configuration table from the EFI System Table\r
49 based on a specified GUID.\r
50 \r
51 This function searches the list of configuration tables stored in the EFI System Table\r
52 for a table with a GUID that matches TableGuid. If a match is found, then a pointer to\r
53 the configuration table is returned in Table., and EFI_SUCCESS is returned. If a matching GUID\r
54 is not found, then EFI_NOT_FOUND is returned.\r
55 If TableGuid is NULL, then ASSERT().\r
56 If Table is NULL, then ASSERT().\r
79964ac8 57\r
58 @param TableGuid Pointer to table's GUID type..\r
59 @param Table Pointer to the table associated with TableGuid in the EFI System Table.\r
60\r
61 @retval EFI_SUCCESS A configuration table matching TableGuid was found.\r
62 @retval EFI_NOT_FOUND A configuration table matching TableGuid could not be found.\r
63\r
64**/\r
65EFI_STATUS\r
66EFIAPI\r
67EfiGetSystemConfigurationTable (\r
68 IN EFI_GUID *TableGuid,\r
69 OUT VOID **Table\r
70 )\r
71{\r
72 EFI_SYSTEM_TABLE *SystemTable;\r
73 UINTN Index;\r
74\r
75 ASSERT (TableGuid != NULL);\r
76 ASSERT (Table != NULL);\r
77\r
78 SystemTable = gST;\r
79 *Table = NULL;\r
80 for (Index = 0; Index < SystemTable->NumberOfTableEntries; Index++) {\r
81 if (CompareGuid (TableGuid, &(SystemTable->ConfigurationTable[Index].VendorGuid))) {\r
82 *Table = SystemTable->ConfigurationTable[Index].VendorTable;\r
83 return EFI_SUCCESS;\r
84 }\r
85 }\r
86\r
87 return EFI_NOT_FOUND;\r
88}\r
89\r
90/**\r
bf428cb3 91 Creates and returns a notification event and registers that event with all the protocol\r
92 instances specified by ProtocolGuid.\r
93\r
94 This function causes the notification function to be executed for every protocol of type\r
4ea439fb 95 ProtocolGuid instance that exists in the system when this function is invoked. If there are\r
96 no instances of ProtocolGuid in the handle database at the time this function is invoked,\r
97 then the notification function is still executed one time. In addition, every time a protocol\r
98 of type ProtocolGuid instance is installed or reinstalled, the notification function is also\r
99 executed. This function returns the notification event that was created. \r
bf428cb3 100 If ProtocolGuid is NULL, then ASSERT().\r
101 If NotifyTpl is not a legal TPL value, then ASSERT().\r
102 If NotifyFunction is NULL, then ASSERT().\r
103 If Registration is NULL, then ASSERT().\r
79964ac8 104\r
4ea439fb 105\r
79964ac8 106 @param ProtocolGuid Supplies GUID of the protocol upon whose installation the event is fired.\r
107 @param NotifyTpl Supplies the task priority level of the event notifications.\r
108 @param NotifyFunction Supplies the function to notify when the event is signaled.\r
109 @param NotifyContext The context parameter to pass to NotifyFunction.\r
110 @param Registration A pointer to a memory location to receive the registration value.\r
bf428cb3 111 This value is passed to LocateHandle() to obtain new handles that\r
112 have been added that support the ProtocolGuid-specified protocol. \r
79964ac8 113\r
114 @return The notification event that was created.\r
115\r
116**/\r
117EFI_EVENT\r
118EFIAPI\r
119EfiCreateProtocolNotifyEvent(\r
120 IN EFI_GUID *ProtocolGuid,\r
121 IN EFI_TPL NotifyTpl,\r
122 IN EFI_EVENT_NOTIFY NotifyFunction,\r
123 IN VOID *NotifyContext, OPTIONAL\r
124 OUT VOID **Registration\r
125 )\r
126{\r
127 EFI_STATUS Status;\r
128 EFI_EVENT Event;\r
129\r
bf428cb3 130 ASSERT (ProtocolGuid != NULL);\r
131 ASSERT (NotifyFunction != NULL);\r
132 ASSERT (Registration != NULL);\r
133\r
79964ac8 134 //\r
135 // Create the event\r
136 //\r
137\r
138 Status = gBS->CreateEvent (\r
93b0fbc8 139 EVT_NOTIFY_SIGNAL,\r
79964ac8 140 NotifyTpl,\r
141 NotifyFunction,\r
142 NotifyContext,\r
143 &Event\r
144 );\r
145 ASSERT_EFI_ERROR (Status);\r
146\r
147 //\r
4ea439fb 148 // Register for protocol notifications on this event\r
79964ac8 149 //\r
150\r
151 Status = gBS->RegisterProtocolNotify (\r
152 ProtocolGuid,\r
153 Event,\r
154 Registration\r
155 );\r
156\r
157 ASSERT_EFI_ERROR (Status);\r
158\r
159 //\r
160 // Kick the event so we will perform an initial pass of\r
161 // current installed drivers\r
162 //\r
163\r
164 gBS->SignalEvent (Event);\r
165 return Event;\r
166}\r
167\r
168/**\r
bf428cb3 169 Creates a named event that can be signaled with EfiNamedEventSignal().\r
170\r
79964ac8 171 This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.\r
bf428cb3 172 This event is signaled with EfiNamedEventSignal(). This provides the ability for one or more\r
173 listeners on the same event named by the GUID specified by Name. \r
174 If Name is NULL, then ASSERT().\r
175 If NotifyTpl is not a legal TPL value, then ASSERT().\r
176 If NotifyFunction is NULL, then ASSERT().\r
79964ac8 177\r
178 @param Name Supplies GUID name of the event.\r
179 @param NotifyTpl Supplies the task priority level of the event notifications.\r
180 @param NotifyFunction Supplies the function to notify when the event is signaled.\r
bf428cb3 181 @param NotifyContext The context parameter to pass to NotifyFunction. \r
79964ac8 182 @param Registration A pointer to a memory location to receive the registration value.\r
183\r
184 @retval EFI_SUCCESS A named event was created.\r
185 @retval EFI_OUT_OF_RESOURCES There are not enough resource to create the named event.\r
186\r
187**/\r
188EFI_STATUS\r
189EFIAPI\r
190EfiNamedEventListen (\r
191 IN CONST EFI_GUID *Name,\r
192 IN EFI_TPL NotifyTpl,\r
193 IN EFI_EVENT_NOTIFY NotifyFunction,\r
194 IN CONST VOID *NotifyContext, OPTIONAL\r
195 OUT VOID *Registration OPTIONAL\r
196 )\r
197{\r
198 EFI_STATUS Status;\r
199 EFI_EVENT Event;\r
200 VOID *RegistrationLocal;\r
201\r
bf428cb3 202 ASSERT (Name != NULL);\r
203 ASSERT (NotifyFunction != NULL);\r
204 ASSERT (NotifyTpl <= TPL_HIGH_LEVEL);\r
205 \r
79964ac8 206 //\r
207 // Create event\r
208 //\r
209 Status = gBS->CreateEvent (\r
93b0fbc8 210 EVT_NOTIFY_SIGNAL,\r
79964ac8 211 NotifyTpl,\r
212 NotifyFunction,\r
213 (VOID *) NotifyContext,\r
214 &Event\r
215 );\r
216 ASSERT_EFI_ERROR (Status);\r
217\r
218 //\r
219 // The Registration is not optional to RegisterProtocolNotify().\r
220 // To make it optional to EfiNamedEventListen(), may need to substitute with a local.\r
221 //\r
222 if (Registration != NULL) {\r
223 RegistrationLocal = Registration;\r
224 } else {\r
225 RegistrationLocal = &RegistrationLocal;\r
226 }\r
227\r
228 //\r
229 // Register for an installation of protocol interface\r
230 //\r
231\r
232 Status = gBS->RegisterProtocolNotify (\r
233 (EFI_GUID *) Name,\r
234 Event,\r
235 RegistrationLocal\r
236 );\r
237 ASSERT_EFI_ERROR (Status);\r
238\r
bf428cb3 239 return Status;\r
79964ac8 240}\r
241\r
242/**\r
bf428cb3 243 Signals a named event created with EfiNamedEventListen().\r
244\r
245 This function signals the named event specified by Name. The named event must have been\r
246 created with EfiNamedEventListen().\r
247 If Name is NULL, then ASSERT().\r
79964ac8 248\r
249 @param Name Supplies GUID name of the event.\r
250\r
251 @retval EFI_SUCCESS A named event was signaled.\r
252 @retval EFI_OUT_OF_RESOURCES There are not enough resource to signal the named event.\r
253\r
254**/\r
255EFI_STATUS\r
256EFIAPI\r
257EfiNamedEventSignal (\r
258 IN CONST EFI_GUID *Name\r
259 )\r
260{\r
261 EFI_STATUS Status;\r
262 EFI_HANDLE Handle;\r
263\r
bf428cb3 264 ASSERT(Name != NULL);\r
265\r
79964ac8 266 Handle = NULL;\r
267 Status = gBS->InstallProtocolInterface (\r
268 &Handle,\r
269 (EFI_GUID *) Name,\r
270 EFI_NATIVE_INTERFACE,\r
271 NULL\r
272 );\r
273 ASSERT_EFI_ERROR (Status);\r
274\r
275 Status = gBS->UninstallProtocolInterface (\r
276 Handle,\r
277 (EFI_GUID *) Name,\r
278 NULL\r
279 );\r
280 ASSERT_EFI_ERROR (Status);\r
281\r
bf428cb3 282 return Status;\r
79964ac8 283}\r
284\r
6212b948
LE
285/**\r
286 Signals an event group by placing a new event in the group temporarily and\r
287 signaling it.\r
288\r
289 @param[in] EventGroup Supplies the unique identifier of the event\r
290 group to signal.\r
291\r
292 @retval EFI_SUCCESS The event group was signaled successfully.\r
293 @retval EFI_INVALID_PARAMETER EventGroup is NULL.\r
294 @return Error codes that report problems about event\r
295 creation or signaling.\r
296**/\r
297EFI_STATUS\r
298EFIAPI\r
299EfiEventGroupSignal (\r
300 IN CONST EFI_GUID *EventGroup\r
301 )\r
302{\r
303 EFI_STATUS Status;\r
304 EFI_EVENT Event;\r
305\r
306 if (EventGroup == NULL) {\r
307 return EFI_INVALID_PARAMETER;\r
308 }\r
309\r
310 Status = gBS->CreateEventEx (\r
311 EVT_NOTIFY_SIGNAL,\r
312 TPL_CALLBACK,\r
313 InternalEmptyFunction,\r
314 NULL,\r
315 EventGroup,\r
316 &Event\r
317 );\r
318 if (EFI_ERROR (Status)) {\r
319 return Status;\r
320 }\r
321\r
322 Status = gBS->SignalEvent (Event);\r
323 gBS->CloseEvent (Event);\r
324\r
325 return Status;\r
326}\r
327\r
bf428cb3 328/** \r
79964ac8 329 Returns the current TPL.\r
330\r
bf428cb3 331 This function returns the current TPL. There is no EFI service to directly \r
332 retrieve the current TPL. Instead, the RaiseTPL() function is used to raise \r
333 the TPL to TPL_HIGH_LEVEL. This will return the current TPL. The TPL level \r
334 can then immediately be restored back to the current TPL level with a call \r
79964ac8 335 to RestoreTPL().\r
336\r
7459094d 337 @return The current TPL.\r
79964ac8 338\r
339**/\r
340EFI_TPL\r
341EFIAPI\r
342EfiGetCurrentTpl (\r
343 VOID\r
344 )\r
345{\r
346 EFI_TPL Tpl;\r
347\r
93b0fbc8 348 Tpl = gBS->RaiseTPL (TPL_HIGH_LEVEL);\r
79964ac8 349 gBS->RestoreTPL (Tpl);\r
350\r
351 return Tpl;\r
352}\r
353\r
354\r
355/**\r
bf428cb3 356 Initializes a basic mutual exclusion lock.\r
357\r
358 This function initializes a basic mutual exclusion lock to the released state \r
359 and returns the lock. Each lock provides mutual exclusion access at its task \r
79964ac8 360 priority level. Since there is no preemption or multiprocessor support in EFI,\r
361 acquiring the lock only consists of raising to the locks TPL.\r
bf428cb3 362 If Lock is NULL, then ASSERT().\r
363 If Priority is not a valid TPL value, then ASSERT().\r
79964ac8 364\r
365 @param Lock A pointer to the lock data structure to initialize.\r
366 @param Priority EFI TPL associated with the lock.\r
367\r
368 @return The lock.\r
369\r
370**/\r
371EFI_LOCK *\r
372EFIAPI\r
373EfiInitializeLock (\r
374 IN OUT EFI_LOCK *Lock,\r
375 IN EFI_TPL Priority\r
376 )\r
377{\r
378 ASSERT (Lock != NULL);\r
93b0fbc8 379 ASSERT (Priority <= TPL_HIGH_LEVEL);\r
79964ac8 380\r
381 Lock->Tpl = Priority;\r
93b0fbc8 382 Lock->OwnerTpl = TPL_APPLICATION;\r
79964ac8 383 Lock->Lock = EfiLockReleased ;\r
384 return Lock;\r
385}\r
386\r
387/**\r
bf428cb3 388 Acquires ownership of a lock.\r
389\r
390 This function raises the system's current task priority level to the task \r
391 priority level of the mutual exclusion lock. Then, it places the lock in the \r
79964ac8 392 acquired state.\r
bf428cb3 393 If Lock is NULL, then ASSERT().\r
394 If Lock is not initialized, then ASSERT().\r
395 If Lock is already in the acquired state, then ASSERT().\r
79964ac8 396\r
bf428cb3 397 @param Lock A pointer to the lock to acquire.\r
79964ac8 398\r
399**/\r
400VOID\r
401EFIAPI\r
402EfiAcquireLock (\r
403 IN EFI_LOCK *Lock\r
404 )\r
405{\r
406 ASSERT (Lock != NULL);\r
407 ASSERT (Lock->Lock == EfiLockReleased);\r
408\r
409 Lock->OwnerTpl = gBS->RaiseTPL (Lock->Tpl);\r
410 Lock->Lock = EfiLockAcquired;\r
411}\r
412\r
413/**\r
bf428cb3 414 Acquires ownership of a lock.\r
415\r
416 This function raises the system's current task priority level to the task priority\r
417 level of the mutual exclusion lock. Then, it attempts to place the lock in the acquired state.\r
418 If the lock is already in the acquired state, then EFI_ACCESS_DENIED is returned.\r
419 Otherwise, EFI_SUCCESS is returned.\r
420 If Lock is NULL, then ASSERT().\r
421 If Lock is not initialized, then ASSERT().\r
79964ac8 422\r
423 @param Lock A pointer to the lock to acquire.\r
424\r
425 @retval EFI_SUCCESS The lock was acquired.\r
426 @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.\r
427\r
428**/\r
429EFI_STATUS\r
430EFIAPI\r
431EfiAcquireLockOrFail (\r
432 IN EFI_LOCK *Lock\r
433 )\r
434{\r
435\r
436 ASSERT (Lock != NULL);\r
437 ASSERT (Lock->Lock != EfiLockUninitialized);\r
438\r
439 if (Lock->Lock == EfiLockAcquired) {\r
440 //\r
441 // Lock is already owned, so bail out\r
442 //\r
443 return EFI_ACCESS_DENIED;\r
444 }\r
445\r
446 Lock->OwnerTpl = gBS->RaiseTPL (Lock->Tpl);\r
447\r
448 Lock->Lock = EfiLockAcquired;\r
449\r
450 return EFI_SUCCESS;\r
451}\r
452\r
453/**\r
bf428cb3 454 Releases ownership of a lock.\r
455\r
456 This function transitions a mutual exclusion lock from the acquired state to \r
457 the released state, and restores the system's task priority level to its \r
79964ac8 458 previous level.\r
bf428cb3 459 If Lock is NULL, then ASSERT().\r
460 If Lock is not initialized, then ASSERT().\r
461 If Lock is already in the released state, then ASSERT().\r
79964ac8 462\r
463 @param Lock A pointer to the lock to release.\r
464\r
465**/\r
466VOID\r
467EFIAPI\r
468EfiReleaseLock (\r
469 IN EFI_LOCK *Lock\r
470 )\r
471{\r
472 EFI_TPL Tpl;\r
473\r
474 ASSERT (Lock != NULL);\r
475 ASSERT (Lock->Lock == EfiLockAcquired);\r
476\r
477 Tpl = Lock->OwnerTpl;\r
478\r
479 Lock->Lock = EfiLockReleased;\r
480\r
481 gBS->RestoreTPL (Tpl);\r
482}\r
483\r
b51e6bc4 484/**\r
485 Tests whether a controller handle is being managed by a specific driver.\r
486\r
79964ac8 487 This function tests whether the driver specified by DriverBindingHandle is\r
488 currently managing the controller specified by ControllerHandle. This test\r
489 is performed by evaluating if the the protocol specified by ProtocolGuid is\r
490 present on ControllerHandle and is was opened by DriverBindingHandle with an\r
bf428cb3 491 attribute of EFI_OPEN_PROTOCOL_BY_DRIVER. \r
79964ac8 492 If ProtocolGuid is NULL, then ASSERT().\r
b51e6bc4 493\r
494 @param ControllerHandle A handle for a controller to test.\r
495 @param DriverBindingHandle Specifies the driver binding handle for the\r
496 driver.\r
497 @param ProtocolGuid Specifies the protocol that the driver specified\r
498 by DriverBindingHandle opens in its Start()\r
499 function.\r
500\r
501 @retval EFI_SUCCESS ControllerHandle is managed by the driver\r
4ea439fb 502 specified by DriverBindingHandle.\r
b51e6bc4 503 @retval EFI_UNSUPPORTED ControllerHandle is not managed by the driver\r
4ea439fb 504 specified by DriverBindingHandle.\r
b51e6bc4 505\r
79964ac8 506**/\r
507EFI_STATUS\r
508EFIAPI\r
509EfiTestManagedDevice (\r
510 IN CONST EFI_HANDLE ControllerHandle,\r
511 IN CONST EFI_HANDLE DriverBindingHandle,\r
512 IN CONST EFI_GUID *ProtocolGuid\r
513 )\r
514{\r
515 EFI_STATUS Status;\r
516 VOID *ManagedInterface;\r
517\r
518 ASSERT (ProtocolGuid != NULL);\r
519\r
520 Status = gBS->OpenProtocol (\r
521 ControllerHandle,\r
522 (EFI_GUID *) ProtocolGuid,\r
523 &ManagedInterface,\r
524 DriverBindingHandle,\r
525 ControllerHandle,\r
526 EFI_OPEN_PROTOCOL_BY_DRIVER\r
527 );\r
528 if (!EFI_ERROR (Status)) {\r
529 gBS->CloseProtocol (\r
530 ControllerHandle,\r
531 (EFI_GUID *) ProtocolGuid,\r
532 DriverBindingHandle,\r
533 ControllerHandle\r
534 );\r
535 return EFI_UNSUPPORTED;\r
536 }\r
537\r
538 if (Status != EFI_ALREADY_STARTED) {\r
539 return EFI_UNSUPPORTED;\r
540 }\r
541\r
542 return EFI_SUCCESS;\r
543}\r
544\r
b51e6bc4 545/**\r
546 Tests whether a child handle is a child device of the controller.\r
547\r
79964ac8 548 This function tests whether ChildHandle is one of the children of\r
549 ControllerHandle. This test is performed by checking to see if the protocol\r
550 specified by ProtocolGuid is present on ControllerHandle and opened by\r
551 ChildHandle with an attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.\r
552 If ProtocolGuid is NULL, then ASSERT().\r
b51e6bc4 553\r
bf428cb3 554 @param ControllerHandle A handle for a (parent) controller to test. \r
b51e6bc4 555 @param ChildHandle A child handle to test.\r
7459094d 556 @param ProtocolGuid Supplies the protocol that the child controller\r
bf428cb3 557 opens on its parent controller. \r
b51e6bc4 558\r
559 @retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle.\r
560 @retval EFI_UNSUPPORTED ChildHandle is not a child of the\r
561 ControllerHandle.\r
562\r
79964ac8 563**/\r
564EFI_STATUS\r
565EFIAPI\r
566EfiTestChildHandle (\r
567 IN CONST EFI_HANDLE ControllerHandle,\r
568 IN CONST EFI_HANDLE ChildHandle,\r
569 IN CONST EFI_GUID *ProtocolGuid\r
570 )\r
571{\r
572 EFI_STATUS Status;\r
573 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY *OpenInfoBuffer;\r
574 UINTN EntryCount;\r
575 UINTN Index;\r
576\r
577 ASSERT (ProtocolGuid != NULL);\r
578\r
579 //\r
580 // Retrieve the list of agents that are consuming the specific protocol\r
581 // on ControllerHandle.\r
582 //\r
583 Status = gBS->OpenProtocolInformation (\r
584 ControllerHandle,\r
585 (EFI_GUID *) ProtocolGuid,\r
586 &OpenInfoBuffer,\r
587 &EntryCount\r
588 );\r
589 if (EFI_ERROR (Status)) {\r
590 return EFI_UNSUPPORTED;\r
591 }\r
592\r
593 //\r
594 // Inspect if ChildHandle is one of the agents.\r
595 //\r
596 Status = EFI_UNSUPPORTED;\r
597 for (Index = 0; Index < EntryCount; Index++) {\r
598 if ((OpenInfoBuffer[Index].ControllerHandle == ChildHandle) &&\r
599 (OpenInfoBuffer[Index].Attributes & EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER) != 0) {\r
600 Status = EFI_SUCCESS;\r
601 break;\r
602 }\r
603 }\r
604\r
605 FreePool (OpenInfoBuffer);\r
606 return Status;\r
607}\r
608\r
609/**\r
bf428cb3 610 This function looks up a Unicode string in UnicodeStringTable.\r
79964ac8 611\r
bf428cb3 612 If Language is a member of SupportedLanguages and a Unicode string is found in\r
613 UnicodeStringTable that matches the language code specified by Language, then it\r
614 is returned in UnicodeString.\r
615\r
616 @param Language A pointer to the ISO 639-2 language code for the \r
79964ac8 617 Unicode string to look up and return.\r
bf428cb3 618 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes \r
619 that the Unicode string table supports. Language \r
79964ac8 620 must be a member of this set.\r
621 @param UnicodeStringTable A pointer to the table of Unicode strings.\r
622 @param UnicodeString A pointer to the Unicode string from UnicodeStringTable\r
623 that matches the language specified by Language.\r
624\r
bf428cb3 625 @retval EFI_SUCCESS The Unicode string that matches the language \r
79964ac8 626 specified by Language was found\r
4ea439fb 627 in the table of Unicode strings UnicodeStringTable, \r
79964ac8 628 and it was returned in UnicodeString.\r
bf428cb3 629 @retval EFI_INVALID_PARAMETER Language is NULL.\r
630 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.\r
631 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.\r
632 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL.\r
633 @retval EFI_UNSUPPORTED The language specified by Language is not a \r
79964ac8 634 member of SupportedLanguages.\r
bf428cb3 635 @retval EFI_UNSUPPORTED The language specified by Language is not \r
79964ac8 636 supported by UnicodeStringTable.\r
637\r
638**/\r
639EFI_STATUS\r
640EFIAPI\r
641LookupUnicodeString (\r
642 IN CONST CHAR8 *Language,\r
643 IN CONST CHAR8 *SupportedLanguages,\r
644 IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable,\r
645 OUT CHAR16 **UnicodeString\r
646 )\r
647{\r
648 //\r
649 // Make sure the parameters are valid\r
650 //\r
651 if (Language == NULL || UnicodeString == NULL) {\r
652 return EFI_INVALID_PARAMETER;\r
653 }\r
654\r
655 //\r
656 // If there are no supported languages, or the Unicode String Table is empty, then the\r
657 // Unicode String specified by Language is not supported by this Unicode String Table\r
658 //\r
659 if (SupportedLanguages == NULL || UnicodeStringTable == NULL) {\r
660 return EFI_UNSUPPORTED;\r
661 }\r
662\r
663 //\r
664 // Make sure Language is in the set of Supported Languages\r
665 //\r
666 while (*SupportedLanguages != 0) {\r
667 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {\r
668\r
669 //\r
670 // Search the Unicode String Table for the matching Language specifier\r
671 //\r
672 while (UnicodeStringTable->Language != NULL) {\r
673 if (CompareIso639LanguageCode (Language, UnicodeStringTable->Language)) {\r
674\r
675 //\r
676 // A matching string was found, so return it\r
677 //\r
678 *UnicodeString = UnicodeStringTable->UnicodeString;\r
679 return EFI_SUCCESS;\r
680 }\r
681\r
682 UnicodeStringTable++;\r
683 }\r
684\r
685 return EFI_UNSUPPORTED;\r
686 }\r
687\r
688 SupportedLanguages += 3;\r
689 }\r
690\r
691 return EFI_UNSUPPORTED;\r
692}\r
693\r
bf428cb3 694\r
695\r
696/**\r
697 This function looks up a Unicode string in UnicodeStringTable.\r
698\r
699 If Language is a member of SupportedLanguages and a Unicode string is found in\r
700 UnicodeStringTable that matches the language code specified by Language, then\r
701 it is returned in UnicodeString.\r
702\r
703 @param Language A pointer to an ASCII string containing the ISO 639-2 or the\r
704 RFC 4646 language code for the Unicode string to look up and\r
705 return. If Iso639Language is TRUE, then this ASCII string is\r
706 not assumed to be Null-terminated, and only the first three\r
4ea439fb 707 characters are used. If Iso639Language is FALSE, then this ASCII\r
bf428cb3 708 string must be Null-terminated. \r
709 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains a\r
710 set of ISO 639-2 or RFC 4646 language codes that the Unicode\r
711 string table supports. Language must be a member of this set.\r
712 If Iso639Language is TRUE, then this string contains one or more\r
713 ISO 639-2 language codes with no separator characters. If Iso639Language\r
714 is FALSE, then is string contains one or more RFC 4646 language\r
715 codes separated by ';'.\r
716 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE\r
717 is defined in "Related Definitions".\r
718 @param UnicodeString A pointer to the Null-terminated Unicode string from UnicodeStringTable\r
719 that matches the language specified by Language.\r
720 @param Iso639Language Specifies the supported language code format. If it is TRUE, then\r
721 Language and SupportedLanguages follow ISO 639-2 language code format.\r
722 Otherwise, they follow RFC 4646 language code format.\r
723\r
724\r
725 @retval EFI_SUCCESS The Unicode string that matches the language specified by Language\r
726 was found in the table of Unicode strings UnicodeStringTable, and\r
727 it was returned in UnicodeString.\r
728 @retval EFI_INVALID_PARAMETER Language is NULL. \r
729 @retval EFI_INVALID_PARAMETER UnicodeString is NULL. \r
730 @retval EFI_UNSUPPORTED SupportedLanguages is NULL. \r
731 @retval EFI_UNSUPPORTED UnicodeStringTable is NULL. \r
732 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages. \r
733 @retval EFI_UNSUPPORTED The language specified by Language is not supported by UnicodeStringTable.\r
734\r
735**/\r
736EFI_STATUS\r
bf428cb3 737EFIAPI\r
738LookupUnicodeString2 (\r
739 IN CONST CHAR8 *Language,\r
740 IN CONST CHAR8 *SupportedLanguages,\r
741 IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable,\r
742 OUT CHAR16 **UnicodeString,\r
743 IN BOOLEAN Iso639Language\r
744 )\r
745{\r
746 BOOLEAN Found;\r
747 UINTN Index;\r
748 CHAR8 *LanguageString;\r
749\r
750 //\r
751 // Make sure the parameters are valid\r
752 //\r
753 if (Language == NULL || UnicodeString == NULL) {\r
754 return EFI_INVALID_PARAMETER;\r
755 }\r
756\r
757 //\r
758 // If there are no supported languages, or the Unicode String Table is empty, then the\r
759 // Unicode String specified by Language is not supported by this Unicode String Table\r
760 //\r
761 if (SupportedLanguages == NULL || UnicodeStringTable == NULL) {\r
762 return EFI_UNSUPPORTED;\r
763 }\r
764\r
765 //\r
766 // Make sure Language is in the set of Supported Languages\r
767 //\r
768 Found = FALSE;\r
769 while (*SupportedLanguages != 0) {\r
770 if (Iso639Language) {\r
771 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {\r
772 Found = TRUE;\r
773 break;\r
774 }\r
775 SupportedLanguages += 3;\r
776 } else {\r
777 for (Index = 0; SupportedLanguages[Index] != 0 && SupportedLanguages[Index] != ';'; Index++);\r
778 if ((AsciiStrnCmp(SupportedLanguages, Language, Index) == 0) && (Language[Index] == 0)) {\r
779 Found = TRUE;\r
780 break;\r
781 }\r
782 SupportedLanguages += Index;\r
783 for (; *SupportedLanguages != 0 && *SupportedLanguages == ';'; SupportedLanguages++);\r
784 }\r
785 }\r
786\r
787 //\r
788 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED\r
789 //\r
790 if (!Found) {\r
791 return EFI_UNSUPPORTED;\r
792 }\r
793\r
794 //\r
795 // Search the Unicode String Table for the matching Language specifier\r
796 //\r
797 while (UnicodeStringTable->Language != NULL) {\r
798 LanguageString = UnicodeStringTable->Language;\r
799 while (0 != *LanguageString) {\r
800 for (Index = 0 ;LanguageString[Index] != 0 && LanguageString[Index] != ';'; Index++);\r
801 if (AsciiStrnCmp(LanguageString, Language, Index) == 0) {\r
802 *UnicodeString = UnicodeStringTable->UnicodeString;\r
803 return EFI_SUCCESS;\r
804 }\r
805 LanguageString += Index;\r
806 for (Index = 0 ;LanguageString[Index] != 0 && LanguageString[Index] == ';'; Index++);\r
807 }\r
808 UnicodeStringTable++;\r
809 }\r
810\r
811 return EFI_UNSUPPORTED;\r
812}\r
813\r
814\r
79964ac8 815/**\r
816 This function adds a Unicode string to UnicodeStringTable.\r
bf428cb3 817\r
818 If Language is a member of SupportedLanguages then UnicodeString is added to \r
819 UnicodeStringTable. New buffers are allocated for both Language and \r
820 UnicodeString. The contents of Language and UnicodeString are copied into \r
821 these new buffers. These buffers are automatically freed when \r
79964ac8 822 FreeUnicodeStringTable() is called.\r
823\r
bf428cb3 824 @param Language A pointer to the ISO 639-2 language code for the Unicode \r
79964ac8 825 string to add.\r
826 @param SupportedLanguages A pointer to the set of ISO 639-2 language codes\r
827 that the Unicode string table supports.\r
828 Language must be a member of this set.\r
829 @param UnicodeStringTable A pointer to the table of Unicode strings.\r
830 @param UnicodeString A pointer to the Unicode string to add.\r
831\r
bf428cb3 832 @retval EFI_SUCCESS The Unicode string that matches the language \r
833 specified by Language was found in the table of \r
834 Unicode strings UnicodeStringTable, and it was \r
79964ac8 835 returned in UnicodeString.\r
836 @retval EFI_INVALID_PARAMETER Language is NULL.\r
837 @retval EFI_INVALID_PARAMETER UnicodeString is NULL.\r
838 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string.\r
839 @retval EFI_UNSUPPORTED SupportedLanguages is NULL.\r
bf428cb3 840 @retval EFI_ALREADY_STARTED A Unicode string with language Language is \r
79964ac8 841 already present in UnicodeStringTable.\r
bf428cb3 842 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another \r
79964ac8 843 Unicode string to UnicodeStringTable.\r
bf428cb3 844 @retval EFI_UNSUPPORTED The language specified by Language is not a \r
79964ac8 845 member of SupportedLanguages.\r
846\r
847**/\r
848EFI_STATUS\r
849EFIAPI\r
850AddUnicodeString (\r
851 IN CONST CHAR8 *Language,\r
852 IN CONST CHAR8 *SupportedLanguages,\r
853 IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable,\r
854 IN CONST CHAR16 *UnicodeString\r
855 )\r
856{\r
857 UINTN NumberOfEntries;\r
858 EFI_UNICODE_STRING_TABLE *OldUnicodeStringTable;\r
859 EFI_UNICODE_STRING_TABLE *NewUnicodeStringTable;\r
860 UINTN UnicodeStringLength;\r
861\r
862 //\r
863 // Make sure the parameter are valid\r
864 //\r
865 if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {\r
866 return EFI_INVALID_PARAMETER;\r
867 }\r
868\r
869 //\r
870 // If there are no supported languages, then a Unicode String can not be added\r
871 //\r
872 if (SupportedLanguages == NULL) {\r
873 return EFI_UNSUPPORTED;\r
874 }\r
875\r
876 //\r
877 // If the Unicode String is empty, then a Unicode String can not be added\r
878 //\r
879 if (UnicodeString[0] == 0) {\r
880 return EFI_INVALID_PARAMETER;\r
881 }\r
882\r
883 //\r
884 // Make sure Language is a member of SupportedLanguages\r
885 //\r
886 while (*SupportedLanguages != 0) {\r
887 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {\r
888\r
889 //\r
890 // Determine the size of the Unicode String Table by looking for a NULL Language entry\r
891 //\r
892 NumberOfEntries = 0;\r
893 if (*UnicodeStringTable != NULL) {\r
894 OldUnicodeStringTable = *UnicodeStringTable;\r
895 while (OldUnicodeStringTable->Language != NULL) {\r
896 if (CompareIso639LanguageCode (Language, OldUnicodeStringTable->Language)) {\r
897 return EFI_ALREADY_STARTED;\r
898 }\r
899\r
900 OldUnicodeStringTable++;\r
901 NumberOfEntries++;\r
902 }\r
903 }\r
904\r
905 //\r
906 // Allocate space for a new Unicode String Table. It must hold the current number of\r
907 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table\r
908 // marker\r
909 //\r
910 NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));\r
911 if (NewUnicodeStringTable == NULL) {\r
912 return EFI_OUT_OF_RESOURCES;\r
913 }\r
914\r
915 //\r
916 // If the current Unicode String Table contains any entries, then copy them to the\r
917 // newly allocated Unicode String Table.\r
918 //\r
919 if (*UnicodeStringTable != NULL) {\r
920 CopyMem (\r
921 NewUnicodeStringTable,\r
922 *UnicodeStringTable,\r
923 NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)\r
924 );\r
925 }\r
926\r
927 //\r
928 // Allocate space for a copy of the Language specifier\r
929 //\r
930 NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (3, Language);\r
931 if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {\r
932 gBS->FreePool (NewUnicodeStringTable);\r
933 return EFI_OUT_OF_RESOURCES;\r
934 }\r
935\r
936 //\r
937 // Compute the length of the Unicode String\r
938 //\r
939 for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++)\r
940 ;\r
941\r
942 //\r
943 // Allocate space for a copy of the Unicode String\r
944 //\r
945 NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (\r
946 (UnicodeStringLength + 1) * sizeof (CHAR16),\r
947 UnicodeString\r
948 );\r
949 if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {\r
950 gBS->FreePool (NewUnicodeStringTable[NumberOfEntries].Language);\r
951 gBS->FreePool (NewUnicodeStringTable);\r
952 return EFI_OUT_OF_RESOURCES;\r
953 }\r
954\r
955 //\r
956 // Mark the end of the Unicode String Table\r
957 //\r
958 NewUnicodeStringTable[NumberOfEntries + 1].Language = NULL;\r
959 NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString = NULL;\r
960\r
961 //\r
962 // Free the old Unicode String Table\r
963 //\r
964 if (*UnicodeStringTable != NULL) {\r
965 gBS->FreePool (*UnicodeStringTable);\r
966 }\r
967\r
968 //\r
969 // Point UnicodeStringTable at the newly allocated Unicode String Table\r
970 //\r
971 *UnicodeStringTable = NewUnicodeStringTable;\r
972\r
973 return EFI_SUCCESS;\r
974 }\r
975\r
976 SupportedLanguages += 3;\r
977 }\r
978\r
979 return EFI_UNSUPPORTED;\r
980}\r
981\r
bf428cb3 982\r
983/**\r
984 This function adds the Null-terminated Unicode string specified by UnicodeString\r
985 to UnicodeStringTable.\r
986\r
987 If Language is a member of SupportedLanguages then UnicodeString is added to\r
988 UnicodeStringTable. New buffers are allocated for both Language and UnicodeString.\r
989 The contents of Language and UnicodeString are copied into these new buffers.\r
990 These buffers are automatically freed when EfiLibFreeUnicodeStringTable() is called.\r
991\r
992 @param Language A pointer to an ASCII string containing the ISO 639-2 or\r
993 the RFC 4646 language code for the Unicode string to add.\r
994 If Iso639Language is TRUE, then this ASCII string is not\r
995 assumed to be Null-terminated, and only the first three\r
996 chacters are used. If Iso639Language is FALSE, then this\r
997 ASCII string must be Null-terminated.\r
998 @param SupportedLanguages A pointer to a Null-terminated ASCII string that contains\r
999 a set of ISO 639-2 or RFC 4646 language codes that the Unicode\r
1000 string table supports. Language must be a member of this set.\r
1001 If Iso639Language is TRUE, then this string contains one or more\r
1002 ISO 639-2 language codes with no separator characters.\r
1003 If Iso639Language is FALSE, then is string contains one or more\r
1004 RFC 4646 language codes separated by ';'.\r
1005 @param UnicodeStringTable A pointer to the table of Unicode strings. Type EFI_UNICODE_STRING_TABLE\r
1006 is defined in "Related Definitions".\r
1007 @param UnicodeString A pointer to the Unicode string to add. \r
1008 @param Iso639Language Specifies the supported language code format. If it is TRUE,\r
1009 then Language and SupportedLanguages follow ISO 639-2 language code format.\r
1010 Otherwise, they follow RFC 4646 language code format.\r
1011\r
1012 @retval EFI_SUCCESS The Unicode string that matches the language specified by\r
1013 Language was found in the table of Unicode strings UnicodeStringTable,\r
1014 and it was returned in UnicodeString. \r
1015 @retval EFI_INVALID_PARAMETER Language is NULL. \r
1016 @retval EFI_INVALID_PARAMETER UnicodeString is NULL. \r
1017 @retval EFI_INVALID_PARAMETER UnicodeString is an empty string. \r
1018 @retval EFI_UNSUPPORTED SupportedLanguages is NULL. \r
1019 @retval EFI_ALREADY_STARTED A Unicode string with language Language is already present in\r
1020 UnicodeStringTable. \r
1021 @retval EFI_OUT_OF_RESOURCES There is not enough memory to add another Unicode string UnicodeStringTable. \r
1022 @retval EFI_UNSUPPORTED The language specified by Language is not a member of SupportedLanguages.\r
1023\r
1024**/\r
1025EFI_STATUS\r
1026EFIAPI\r
1027AddUnicodeString2 (\r
1028 IN CONST CHAR8 *Language,\r
1029 IN CONST CHAR8 *SupportedLanguages,\r
1030 IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable,\r
1031 IN CONST CHAR16 *UnicodeString,\r
1032 IN BOOLEAN Iso639Language\r
1033 )\r
1034{\r
1035 UINTN NumberOfEntries;\r
1036 EFI_UNICODE_STRING_TABLE *OldUnicodeStringTable;\r
1037 EFI_UNICODE_STRING_TABLE *NewUnicodeStringTable;\r
1038 UINTN UnicodeStringLength;\r
1039 BOOLEAN Found;\r
1040 UINTN Index;\r
1041 CHAR8 *LanguageString;\r
1042\r
1043 //\r
1044 // Make sure the parameter are valid\r
1045 //\r
1046 if (Language == NULL || UnicodeString == NULL || UnicodeStringTable == NULL) {\r
1047 return EFI_INVALID_PARAMETER;\r
1048 }\r
1049\r
1050 //\r
1051 // If there are no supported languages, then a Unicode String can not be added\r
1052 //\r
1053 if (SupportedLanguages == NULL) {\r
1054 return EFI_UNSUPPORTED;\r
1055 }\r
1056\r
1057 //\r
1058 // If the Unicode String is empty, then a Unicode String can not be added\r
1059 //\r
1060 if (UnicodeString[0] == 0) {\r
1061 return EFI_INVALID_PARAMETER;\r
1062 }\r
1063\r
1064 //\r
1065 // Make sure Language is a member of SupportedLanguages\r
1066 //\r
1067 Found = FALSE;\r
1068 while (*SupportedLanguages != 0) {\r
1069 if (Iso639Language) {\r
1070 if (CompareIso639LanguageCode (Language, SupportedLanguages)) {\r
1071 Found = TRUE;\r
1072 break;\r
1073 }\r
1074 SupportedLanguages += 3;\r
1075 } else {\r
1076 for (Index = 0; SupportedLanguages[Index] != 0 && SupportedLanguages[Index] != ';'; Index++);\r
1077 if (AsciiStrnCmp(SupportedLanguages, Language, Index) == 0) {\r
1078 Found = TRUE;\r
1079 break;\r
1080 }\r
1081 SupportedLanguages += Index;\r
1082 for (; *SupportedLanguages != 0 && *SupportedLanguages == ';'; SupportedLanguages++);\r
1083 }\r
1084 }\r
1085\r
1086 //\r
1087 // If Language is not a member of SupportedLanguages, then return EFI_UNSUPPORTED\r
1088 //\r
1089 if (!Found) {\r
1090 return EFI_UNSUPPORTED;\r
1091 }\r
1092\r
1093 //\r
1094 // Determine the size of the Unicode String Table by looking for a NULL Language entry\r
1095 //\r
1096 NumberOfEntries = 0;\r
1097 if (*UnicodeStringTable != NULL) {\r
1098 OldUnicodeStringTable = *UnicodeStringTable;\r
1099 while (OldUnicodeStringTable->Language != NULL) {\r
1100 LanguageString = OldUnicodeStringTable->Language;\r
1101\r
1102 while (*LanguageString != 0) {\r
1103 for (Index = 0; LanguageString[Index] != 0 && LanguageString[Index] != ';'; Index++);\r
1104\r
1105 if (AsciiStrnCmp (Language, LanguageString, Index) == 0) { \r
1106 return EFI_ALREADY_STARTED;\r
1107 }\r
1108 LanguageString += Index;\r
1109 for (; *LanguageString != 0 && *LanguageString == ';'; LanguageString++);\r
1110 }\r
1111 OldUnicodeStringTable++;\r
1112 NumberOfEntries++;\r
1113 }\r
1114 }\r
1115\r
1116 //\r
1117 // Allocate space for a new Unicode String Table. It must hold the current number of\r
1118 // entries, plus 1 entry for the new Unicode String, plus 1 entry for the end of table\r
1119 // marker\r
1120 //\r
1121 NewUnicodeStringTable = AllocatePool ((NumberOfEntries + 2) * sizeof (EFI_UNICODE_STRING_TABLE));\r
1122 if (NewUnicodeStringTable == NULL) {\r
1123 return EFI_OUT_OF_RESOURCES;\r
1124 }\r
1125\r
1126 //\r
1127 // If the current Unicode String Table contains any entries, then copy them to the\r
1128 // newly allocated Unicode String Table.\r
1129 //\r
1130 if (*UnicodeStringTable != NULL) {\r
1131 CopyMem (\r
1132 NewUnicodeStringTable,\r
1133 *UnicodeStringTable,\r
1134 NumberOfEntries * sizeof (EFI_UNICODE_STRING_TABLE)\r
1135 );\r
1136 }\r
1137\r
1138 //\r
1139 // Allocate space for a copy of the Language specifier\r
1140 //\r
1141 NewUnicodeStringTable[NumberOfEntries].Language = AllocateCopyPool (AsciiStrSize(Language), Language);\r
1142 if (NewUnicodeStringTable[NumberOfEntries].Language == NULL) {\r
1143 gBS->FreePool (NewUnicodeStringTable);\r
1144 return EFI_OUT_OF_RESOURCES;\r
1145 }\r
1146\r
1147 //\r
1148 // Compute the length of the Unicode String\r
1149 //\r
1150 for (UnicodeStringLength = 0; UnicodeString[UnicodeStringLength] != 0; UnicodeStringLength++);\r
1151\r
1152 //\r
1153 // Allocate space for a copy of the Unicode String\r
1154 //\r
1155 NewUnicodeStringTable[NumberOfEntries].UnicodeString = AllocateCopyPool (StrSize (UnicodeString), UnicodeString);\r
1156 if (NewUnicodeStringTable[NumberOfEntries].UnicodeString == NULL) {\r
1157 gBS->FreePool (NewUnicodeStringTable[NumberOfEntries].Language);\r
1158 gBS->FreePool (NewUnicodeStringTable);\r
1159 return EFI_OUT_OF_RESOURCES;\r
1160 }\r
1161\r
1162 //\r
1163 // Mark the end of the Unicode String Table\r
1164 //\r
1165 NewUnicodeStringTable[NumberOfEntries + 1].Language = NULL;\r
1166 NewUnicodeStringTable[NumberOfEntries + 1].UnicodeString = NULL;\r
1167\r
1168 //\r
1169 // Free the old Unicode String Table\r
1170 //\r
1171 if (*UnicodeStringTable != NULL) {\r
1172 gBS->FreePool (*UnicodeStringTable);\r
1173 }\r
1174\r
1175 //\r
1176 // Point UnicodeStringTable at the newly allocated Unicode String Table\r
1177 //\r
1178 *UnicodeStringTable = NewUnicodeStringTable;\r
1179\r
1180 return EFI_SUCCESS;\r
1181}\r
1182\r
79964ac8 1183/**\r
1184 This function frees the table of Unicode strings in UnicodeStringTable.\r
bf428cb3 1185\r
79964ac8 1186 If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.\r
bf428cb3 1187 Otherwise, each language code, and each Unicode string in the Unicode string \r
79964ac8 1188 table are freed, and EFI_SUCCESS is returned.\r
1189\r
1190 @param UnicodeStringTable A pointer to the table of Unicode strings.\r
1191\r
1192 @retval EFI_SUCCESS The Unicode string table was freed.\r
1193\r
1194**/\r
1195EFI_STATUS\r
1196EFIAPI\r
1197FreeUnicodeStringTable (\r
1198 IN EFI_UNICODE_STRING_TABLE *UnicodeStringTable\r
1199 )\r
1200{\r
1201 UINTN Index;\r
1202\r
1203 //\r
1204 // If the Unicode String Table is NULL, then it is already freed\r
1205 //\r
1206 if (UnicodeStringTable == NULL) {\r
1207 return EFI_SUCCESS;\r
1208 }\r
1209\r
1210 //\r
1211 // Loop through the Unicode String Table until we reach the end of table marker\r
1212 //\r
1213 for (Index = 0; UnicodeStringTable[Index].Language != NULL; Index++) {\r
1214\r
1215 //\r
1216 // Free the Language string from the Unicode String Table\r
1217 //\r
1218 gBS->FreePool (UnicodeStringTable[Index].Language);\r
1219\r
1220 //\r
1221 // Free the Unicode String from the Unicode String Table\r
1222 //\r
1223 if (UnicodeStringTable[Index].UnicodeString != NULL) {\r
1224 gBS->FreePool (UnicodeStringTable[Index].UnicodeString);\r
1225 }\r
1226 }\r
1227\r
1228 //\r
1229 // Free the Unicode String Table itself\r
1230 //\r
1231 gBS->FreePool (UnicodeStringTable);\r
1232\r
1233 return EFI_SUCCESS;\r
1234}\r
4ea439fb 1235\r
1236/**\r
1237 Returns a pointer to an allocated buffer that contains the contents of a \r
1238 variable retrieved through the UEFI Runtime Service GetVariable(). The \r
1239 returned buffer is allocated using AllocatePool(). The caller is responsible\r
1240 for freeing this buffer with FreePool().\r
1241\r
1242 If Name is NULL, then ASSERT().\r
1243 If Guid is NULL, then ASSERT().\r
1244\r
1245 @param[in] Name Pointer to a Null-terminated Unicode string.\r
1246 @param[in] Guid Pointer to an EFI_GUID structure\r
1247\r
1248 @retval NULL The variable could not be retrieved.\r
1249 @retval NULL There are not enough resources available for the variable contents.\r
1250 @retval Other A pointer to allocated buffer containing the variable contents.\r
1251\r
1252**/\r
1253VOID *\r
1254EFIAPI\r
1255GetVariable (\r
1256 IN CONST CHAR16 *Name,\r
1257 IN CONST EFI_GUID *Guid\r
1258 )\r
1259{\r
1260 EFI_STATUS Status;\r
1261 UINTN Size;\r
1262 VOID *Value;\r
1263\r
1264 ASSERT (Name != NULL);\r
1265 ASSERT (Guid != NULL);\r
1266\r
1267 //\r
1268 // Try to get the variable size.\r
1269 //\r
1270 Value = NULL;\r
1271 Size = 0;\r
1272 Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &Size, Value);\r
1273 if (Status != EFI_BUFFER_TOO_SMALL) {\r
1274 return NULL;\r
1275 }\r
1276\r
1277 //\r
1278 // Allocate buffer to get the variable.\r
1279 //\r
1280 Value = AllocatePool (Size);\r
1281 if (Value == NULL) {\r
1282 return NULL;\r
1283 }\r
1284\r
1285 //\r
1286 // Get the variable data.\r
1287 //\r
1288 Status = gRT->GetVariable ((CHAR16 *) Name, (EFI_GUID *) Guid, NULL, &Size, Value);\r
1289 if (EFI_ERROR (Status)) {\r
1290 FreePool(Value);\r
1291 return NULL;\r
1292 }\r
1293\r
1294 return Value;\r
1295}\r
1296\r
1297\r
1298/**\r
1299 Returns a pointer to an allocated buffer that contains the contents of a \r
1300 variable retrieved through the UEFI Runtime Service GetVariable(). This \r
1301 function always uses the EFI_GLOBAL_VARIABLE GUID to retrieve variables.\r
1302 The returned buffer is allocated using AllocatePool(). The caller is \r
1303 responsible for freeing this buffer with FreePool().\r
1304\r
1305 If Name is NULL, then ASSERT().\r
1306\r
1307 @param[in] Name Pointer to a Null-terminated Unicode string.\r
1308\r
1309 @retval NULL The variable could not be retrieved.\r
1310 @retval NULL There are not enough resources available for the variable contents.\r
1311 @retval Other A pointer to allocated buffer containing the variable contents.\r
1312\r
1313**/\r
1314VOID *\r
1315EFIAPI\r
1316GetEfiGlobalVariable (\r
1317 IN CONST CHAR16 *Name\r
1318 )\r
1319{\r
1320 return GetVariable (Name, &gEfiGlobalVariableGuid);\r
1321}\r
1322\r
1323\r
1324/**\r
1325 Returns a pointer to an allocated buffer that contains the best matching language \r
1326 from a set of supported languages. \r
1327 \r
1328 This function supports both ISO 639-2 and RFC 4646 language codes, but language \r
1329 code types may not be mixed in a single call to this function. The language \r
1330 code returned is allocated using AllocatePool(). The caller is responsible for \r
1331 freeing the allocated buffer using FreePool(). This function supports a variable\r
1332 argument list that allows the caller to pass in a prioritized list of language \r
1333 codes to test against all the language codes in SupportedLanguages. \r
1334\r
1335 If SupportedLanguages is NULL, then ASSERT().\r
1336\r
1337 @param[in] SupportedLanguages A pointer to a Null-terminated ASCII string that\r
1338 contains a set of language codes in the format \r
1339 specified by Iso639Language.\r
1340 @param[in] Iso639Language If TRUE, then all language codes are assumed to be\r
1341 in ISO 639-2 format. If FALSE, then all language\r
1342 codes are assumed to be in RFC 4646 language format\r
1343 @param[in] ... A variable argument list that contains pointers to \r
1344 Null-terminated ASCII strings that contain one or more\r
1345 language codes in the format specified by Iso639Language.\r
1346 The first language code from each of these language\r
1347 code lists is used to determine if it is an exact or\r
1348 close match to any of the language codes in \r
1349 SupportedLanguages. Close matches only apply to RFC 4646\r
1350 language codes, and the matching algorithm from RFC 4647\r
1351 is used to determine if a close match is present. If \r
1352 an exact or close match is found, then the matching\r
1353 language code from SupportedLanguages is returned. If\r
1354 no matches are found, then the next variable argument\r
1355 parameter is evaluated. The variable argument list \r
1356 is terminated by a NULL.\r
1357\r
1358 @retval NULL The best matching language could not be found in SupportedLanguages.\r
1359 @retval NULL There are not enough resources available to return the best matching \r
1360 language.\r
1361 @retval Other A pointer to a Null-terminated ASCII string that is the best matching \r
1362 language in SupportedLanguages.\r
1363\r
1364**/\r
1365CHAR8 *\r
1366EFIAPI\r
1367GetBestLanguage (\r
1368 IN CONST CHAR8 *SupportedLanguages, \r
1369 IN BOOLEAN Iso639Language,\r
1370 ...\r
1371 )\r
1372{\r
1373 VA_LIST Args;\r
1374 CHAR8 *Language;\r
1375 UINTN CompareLength;\r
1376 UINTN LanguageLength;\r
1377 CONST CHAR8 *Supported;\r
1378 CHAR8 *BestLanguage;\r
1379\r
1380 ASSERT (SupportedLanguages != NULL);\r
1381\r
1382 VA_START (Args, Iso639Language);\r
1383 while ((Language = VA_ARG (Args, CHAR8 *)) != NULL) {\r
1384 //\r
1385 // Default to ISO 639-2 mode\r
1386 //\r
1387 CompareLength = 3;\r
1388 LanguageLength = MIN (3, AsciiStrLen (Language));\r
1389\r
1390 //\r
1391 // If in RFC 4646 mode, then determine the length of the first RFC 4646 language code in Language\r
1392 //\r
1393 if (!Iso639Language) {\r
1394 for (LanguageLength = 0; Language[LanguageLength] != 0 && Language[LanguageLength] != ';'; LanguageLength++);\r
1395 }\r
1396\r
1397 //\r
1398 // Trim back the length of Language used until it is empty\r
1399 //\r
1400 while (LanguageLength > 0) {\r
1401 //\r
1402 // Loop through all language codes in SupportedLanguages\r
1403 //\r
1404 for (Supported = SupportedLanguages; *Supported != '\0'; Supported += CompareLength) {\r
1405 //\r
1406 // In RFC 4646 mode, then Loop through all language codes in SupportedLanguages\r
1407 //\r
1408 if (!Iso639Language) {\r
1409 //\r
1410 // Skip ';' characters in Supported\r
1411 //\r
1412 for (; *Supported != '\0' && *Supported == ';'; Supported++);\r
1413 //\r
1414 // Determine the length of the next language code in Supported\r
1415 //\r
1416 for (CompareLength = 0; Supported[CompareLength] != 0 && Supported[CompareLength] != ';'; CompareLength++);\r
1417 //\r
1418 // If Language is longer than the Supported, then skip to the next language\r
1419 //\r
1420 if (LanguageLength > CompareLength) {\r
1421 continue;\r
1422 }\r
1423 }\r
1424 //\r
1425 // See if the first LanguageLength characters in Supported match Language\r
1426 //\r
1427 if (AsciiStrnCmp (Supported, Language, LanguageLength) == 0) {\r
1428 VA_END (Args);\r
1429 //\r
1430 // Allocate, copy, and return the best matching language code from SupportedLanguages\r
1431 //\r
1432 BestLanguage = AllocateZeroPool (CompareLength + 1);\r
1433 if (BestLanguage == NULL) {\r
1434 return NULL;\r
1435 }\r
1436 return CopyMem (BestLanguage, Supported, CompareLength);\r
1437 }\r
1438 }\r
1439\r
1440 if (Iso639Language) {\r
1441 //\r
1442 // If ISO 639 mode, then each language can only be tested once\r
1443 //\r
1444 LanguageLength = 0;\r
1445 } else {\r
1446 //\r
1447 // If RFC 4646 mode, then trim Language from the right to the next '-' character \r
1448 //\r
1449 for (LanguageLength--; LanguageLength > 0 && Language[LanguageLength] != '-'; LanguageLength--);\r
1450 }\r
1451 }\r
1452 }\r
1453 VA_END (Args);\r
1454\r
1455 //\r
1456 // No matches were found \r
1457 //\r
1458 return NULL;\r
1459}\r
1460\r
ff55dd3b
LE
1461/**\r
1462 An empty function to pass error checking of CreateEventEx ().\r
1463\r
1464 This empty function ensures that EVT_NOTIFY_SIGNAL_ALL is error\r
1465 checked correctly since it is now mapped into CreateEventEx() in UEFI 2.0.\r
1466\r
1467 @param Event Event whose notification function is being invoked.\r
1468 @param Context Pointer to the notification function's context,\r
1469 which is implementation-dependent.\r
1470\r
1471**/\r
1472VOID\r
1473EFIAPI\r
1474InternalEmptyFunction (\r
1475 IN EFI_EVENT Event,\r
1476 IN VOID *Context\r
1477 )\r
1478{\r
1479}\r