2 The file contain all library functions and definitions for IFR opcode creation and
3 related Form Browser utility Operations.
5 Copyright (c) 2007 - 2008, Intel Corporation
6 All rights reserved. This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #ifndef _IFR_SUPPORT_LIBRARY_H
17 #define _IFR_SUPPORT_LIBRARY_H
20 #include <Protocol/HiiFont.h>
21 #include <Protocol/HiiImage.h>
22 #include <Protocol/HiiString.h>
23 #include <Protocol/HiiDatabase.h>
24 #include <Protocol/HiiConfigRouting.h>
25 #include <Protocol/HiiConfigAccess.h>
26 #include <Protocol/FormBrowser2.h>
27 #include <Protocol/SimpleTextOut.h>
29 #include <Guid/GlobalVariable.h>
32 // The architectural variable "Lang" and "LangCodes" are deprecated in UEFI
33 // specification. While, UEFI specification also states that these deprecated
34 // variables may be provided for backwards compatibility.
36 #define EFI_LANGUAGE_VARIABLE L"Lang"
37 #define EFI_LANGUAGE_CODES_VARIABLE L"LangCodes"
39 #define UEFI_LANGUAGE_VARIABLE L"PlatformLang"
40 #define UEFI_LANGUAGE_CODES_VARIABLE L"PlatformLangCodes"
43 // Limited buffer size recommended by RFC4646 (4.3. Length Considerations)
44 // (42 characters plus a NULL terminator)
46 #define RFC_3066_ENTRY_SIZE (42 + 1)
47 #define ISO_639_2_ENTRY_SIZE 3
49 #define INVALID_VARSTORE_ID 0
51 #define QUESTION_FLAGS (EFI_IFR_FLAG_READ_ONLY | EFI_IFR_FLAG_CALLBACK | EFI_IFR_FLAG_RESET_REQUIRED | EFI_IFR_FLAG_OPTIONS_ONLY)
52 #define QUESTION_FLAGS_MASK (~QUESTION_FLAGS)
54 extern EFI_HII_DATABASE_PROTOCOL
*gIfrLibHiiDatabase
;
55 extern EFI_HII_STRING_PROTOCOL
*gIfrLibHiiString
;
59 EFI_STRING_ID StringToken
;
60 EFI_IFR_TYPE_VALUE Value
;
67 // Buffer size allocated for Data.
72 // Offset in Data to append the newly created opcode binary.
73 // It will be adjusted automatically in Create***OpCode(), and should be
74 // initialized to 0 before invocation of a serial of Create***OpCode()
79 // The destination buffer for created op-codes
82 } EFI_HII_UPDATE_DATA
;
86 Create EFI_IFR_END_OP opcode.
88 If Data is NULL or Data->Data is NULL, then ASSERT.
90 @param Data Destination for the created opcode binary
92 @retval EFI_SUCCESS Opcode create success
93 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
99 IN OUT EFI_HII_UPDATE_DATA
*Data
104 Create EFI_IFR_DEFAULT_OP opcode.
106 @param Value Value for the default
107 @param Type Type for the default
108 @param Data Destination for the created opcode binary
110 @retval EFI_SUCCESS Opcode create success
111 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
112 @retval EFI_INVALID_PARAMETER The type is not valid.
117 CreateDefaultOpCode (
118 IN EFI_IFR_TYPE_VALUE
*Value
,
120 IN OUT EFI_HII_UPDATE_DATA
*Data
125 Create EFI_IFR_ACTION_OP opcode.
127 @param QuestionId Question ID
128 @param Prompt String ID for Prompt
129 @param Help String ID for Help
130 @param QuestionFlags Flags in Question Header
131 @param QuestionConfig String ID for configuration
132 @param Data Destination for the created opcode binary
134 @retval EFI_SUCCESS Opcode create success
135 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
136 @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
142 IN EFI_QUESTION_ID QuestionId
,
143 IN EFI_STRING_ID Prompt
,
144 IN EFI_STRING_ID Help
,
145 IN UINT8 QuestionFlags
,
146 IN EFI_STRING_ID QuestionConfig
,
147 IN OUT EFI_HII_UPDATE_DATA
*Data
152 Create EFI_IFR_SUBTITLE_OP opcode.
154 @param Prompt String ID for Prompt
155 @param Help String ID for Help
156 @param Flags Subtitle opcode flags
157 @param Scope Subtitle Scope bit
158 @param Data Destination for the created opcode binary
160 @retval EFI_SUCCESS Opcode create success
161 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
166 CreateSubTitleOpCode (
167 IN EFI_STRING_ID Prompt
,
168 IN EFI_STRING_ID Help
,
171 IN OUT EFI_HII_UPDATE_DATA
*Data
176 Create EFI_IFR_TEXT_OP opcode.
178 @param Prompt String ID for Prompt
179 @param Help String ID for Help
180 @param TextTwo String ID for text two
181 @param Data Destination for the created opcode binary
183 @retval EFI_SUCCESS Opcode create success
184 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
190 IN EFI_STRING_ID Prompt
,
191 IN EFI_STRING_ID Help
,
192 IN EFI_STRING_ID TextTwo
,
193 IN OUT EFI_HII_UPDATE_DATA
*Data
198 Create EFI_IFR_REF_OP opcode.
200 @param FormId Destination Form ID
201 @param Prompt String ID for Prompt
202 @param Help String ID for Help
203 @param QuestionFlags Flags in Question Header
204 @param QuestionId Question ID
205 @param Data Destination for the created opcode binary
207 @retval EFI_SUCCESS Opcode create success
208 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
209 @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
215 IN EFI_FORM_ID FormId
,
216 IN EFI_STRING_ID Prompt
,
217 IN EFI_STRING_ID Help
,
218 IN UINT8 QuestionFlags
,
219 IN EFI_QUESTION_ID QuestionId
,
220 IN OUT EFI_HII_UPDATE_DATA
*Data
225 Create EFI_IFR_ONE_OF_OPTION_OP opcode.
227 @param OptionCount The number of options.
228 @param OptionsList The list of Options.
229 @param Type The data type.
230 @param Data Destination for the created opcode binary
232 @retval EFI_SUCCESS Opcode create success
233 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
238 CreateOneOfOptionOpCode (
239 IN UINTN OptionCount
,
240 IN IFR_OPTION
*OptionsList
,
242 IN OUT EFI_HII_UPDATE_DATA
*Data
247 Create EFI_IFR_ONE_OF_OP opcode.
249 @param QuestionId Question ID
250 @param VarStoreId Storage ID
251 @param VarOffset Offset in Storage
252 @param Prompt String ID for Prompt
253 @param Help String ID for Help
254 @param QuestionFlags Flags in Question Header
255 @param OneOfFlags Flags for oneof opcode
256 @param OptionsList List of options
257 @param OptionCount Number of options in option list
258 @param Data Destination for the created opcode binary
260 @retval EFI_SUCCESS Opcode create success
261 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
262 @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
268 IN EFI_QUESTION_ID QuestionId
,
269 IN EFI_VARSTORE_ID VarStoreId
,
271 IN EFI_STRING_ID Prompt
,
272 IN EFI_STRING_ID Help
,
273 IN UINT8 QuestionFlags
,
275 IN IFR_OPTION
*OptionsList
,
276 IN UINTN OptionCount
,
277 IN OUT EFI_HII_UPDATE_DATA
*Data
282 Create EFI_IFR_ORDERED_LIST_OP opcode.
284 @param QuestionId Question ID
285 @param VarStoreId Storage ID
286 @param VarOffset Offset in Storage
287 @param Prompt String ID for Prompt
288 @param Help String ID for Help
289 @param QuestionFlags Flags in Question Header
290 @param OrderedListFlags Flags for ordered list opcode
291 @param DataType Type for option value
292 @param MaxContainers Maximum count for options in this ordered list
293 @param OptionsList List of options
294 @param OptionCount Number of options in option list
295 @param Data Destination for the created opcode binary
297 @retval EFI_SUCCESS Opcode create success
298 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
299 @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
304 CreateOrderedListOpCode (
305 IN EFI_QUESTION_ID QuestionId
,
306 IN EFI_VARSTORE_ID VarStoreId
,
308 IN EFI_STRING_ID Prompt
,
309 IN EFI_STRING_ID Help
,
310 IN UINT8 QuestionFlags
,
311 IN UINT8 OrderedListFlags
,
313 IN UINT8 MaxContainers
,
314 IN IFR_OPTION
*OptionsList
,
315 IN UINTN OptionCount
,
316 IN OUT EFI_HII_UPDATE_DATA
*Data
321 Create EFI_IFR_CHECKBOX_OP opcode.
323 @param QuestionId Question ID
324 @param VarStoreId Storage ID
325 @param VarOffset Offset in Storage
326 @param Prompt String ID for Prompt
327 @param Help String ID for Help
328 @param QuestionFlags Flags in Question Header
329 @param CheckBoxFlags Flags for checkbox opcode
330 @param Data Destination for the created opcode binary
332 @retval EFI_SUCCESS Opcode create success
333 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
334 @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
339 CreateCheckBoxOpCode (
340 IN EFI_QUESTION_ID QuestionId
,
341 IN EFI_VARSTORE_ID VarStoreId
,
343 IN EFI_STRING_ID Prompt
,
344 IN EFI_STRING_ID Help
,
345 IN UINT8 QuestionFlags
,
346 IN UINT8 CheckBoxFlags
,
347 IN OUT EFI_HII_UPDATE_DATA
*Data
352 Create EFI_IFR_NUMERIC_OP opcode.
354 @param QuestionId Question ID
355 @param VarStoreId Storage ID
356 @param VarOffset Offset in Storage
357 @param Prompt String ID for Prompt
358 @param Help String ID for Help
359 @param QuestionFlags Flags in Question Header
360 @param NumericFlags Flags for numeric opcode
361 @param Minimum Numeric minimum value
362 @param Maximum Numeric maximum value
363 @param Step Numeric step for edit
364 @param Default Numeric default value
365 @param Data Destination for the created opcode binary
367 @retval EFI_SUCCESS Opcode create success
368 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
369 @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
374 CreateNumericOpCode (
375 IN EFI_QUESTION_ID QuestionId
,
376 IN EFI_VARSTORE_ID VarStoreId
,
378 IN EFI_STRING_ID Prompt
,
379 IN EFI_STRING_ID Help
,
380 IN UINT8 QuestionFlags
,
381 IN UINT8 NumericFlags
,
386 IN OUT EFI_HII_UPDATE_DATA
*Data
391 Create EFI_IFR_STRING_OP opcode.
393 @param QuestionId Question ID
394 @param VarStoreId Storage ID
395 @param VarOffset Offset in Storage
396 @param Prompt String ID for Prompt
397 @param Help String ID for Help
398 @param QuestionFlags Flags in Question Header
399 @param StringFlags Flags for string opcode
400 @param MinSize String minimum length
401 @param MaxSize String maximum length
402 @param Data Destination for the created opcode binary
404 @retval EFI_SUCCESS Opcode create success
405 @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
406 @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
412 IN EFI_QUESTION_ID QuestionId
,
413 IN EFI_VARSTORE_ID VarStoreId
,
415 IN EFI_STRING_ID Prompt
,
416 IN EFI_STRING_ID Help
,
417 IN UINT8 QuestionFlags
,
418 IN UINT8 StringFlags
,
421 IN OUT EFI_HII_UPDATE_DATA
*Data
426 Converts the unicode character of the string from uppercase to lowercase.
428 @param Str String to be converted
441 Converts binary buffer to Unicode string in reversed byte order to BufToHexString().
443 @param Str String for output
444 @param Buffer Binary buffer.
445 @param BufferSize Size of the buffer in bytes.
447 @retval EFI_SUCCESS The function completed successfully.
460 Converts Hex String to binary buffer in reversed byte order to HexStringToBuf().
462 @param Buffer Pointer to buffer that receives the data.
463 @param BufferSize Length in bytes of the buffer to hold converted
464 data. If routine return with EFI_SUCCESS,
465 containing length of converted data. If routine
466 return with EFI_BUFFER_TOO_SMALL, containg length
468 @param Str String to be converted from.
470 @retval EFI_SUCCESS The function completed successfully.
476 IN OUT UINT8
*Buffer
,
477 IN OUT UINTN
*BufferSize
,
483 Convert binary representation Config string (e.g. "0041004200430044") to the
484 original string (e.g. "ABCD"). Config string appears in <ConfigHdr> (i.e.
485 "&NAME=<string>"), or Name/Value pair in <ConfigBody> (i.e. "label=<string>").
487 @param UnicodeString Original Unicode string.
488 @param StrBufferLen On input: Length in bytes of buffer to hold the Unicode string.
489 Includes tailing '\0' character.
491 If return EFI_SUCCESS, containing length of Unicode string buffer.
492 If return EFI_BUFFER_TOO_SMALL, containg length of string buffer desired.
493 @param ConfigString Binary representation of Unicode String, <string> := (<HexCh>4)+
495 @retval EFI_SUCCESS Routine success.
496 @retval EFI_BUFFER_TOO_SMALL The string buffer is too small.
501 ConfigStringToUnicode (
502 IN OUT CHAR16
*UnicodeString
,
503 IN OUT UINTN
*StrBufferLen
,
504 IN CHAR16
*ConfigString
509 Convert Unicode string to binary representation Config string, e.g.
510 "ABCD" => "0041004200430044". Config string appears in <ConfigHdr> (i.e.
511 "&NAME=<string>"), or Name/Value pair in <ConfigBody> (i.e. "label=<string>").
513 @param ConfigString Binary representation of Unicode String, <string> := (<HexCh>4)+
514 @param StrBufferLen On input: Length in bytes of buffer to hold the Unicode string.
515 Includes tailing '\0' character.
517 If return EFI_SUCCESS, containing length of Unicode string buffer.
518 If return EFI_BUFFER_TOO_SMALL, containg length of string buffer desired.
519 @param UnicodeString Original Unicode string.
521 @retval EFI_SUCCESS Routine success.
522 @retval EFI_BUFFER_TOO_SMALL The string buffer is too small.
527 UnicodeToConfigString (
528 IN OUT CHAR16
*ConfigString
,
529 IN OUT UINTN
*StrBufferLen
,
530 IN CHAR16
*UnicodeString
535 Construct <ConfigHdr> using routing information GUID/NAME/PATH.
537 @param ConfigHdr Pointer to the ConfigHdr string.
538 @param StrBufferLen On input: Length in bytes of buffer to hold the
539 ConfigHdr string. Includes tailing '\0' character.
540 On output: If return EFI_SUCCESS, containing
541 length of ConfigHdr string buffer. If return
542 EFI_BUFFER_TOO_SMALL, containg length of string
544 @param Guid Routing information: GUID.
545 @param Name Routing information: NAME.
546 @param DriverHandle Driver handle which contains the routing
549 @retval EFI_SUCCESS Routine success.
550 @retval EFI_BUFFER_TOO_SMALL The ConfigHdr string buffer is too small.
556 IN OUT CHAR16
*ConfigHdr
,
557 IN OUT UINTN
*StrBufferLen
,
559 IN CHAR16
*Name
, OPTIONAL
560 IN EFI_HANDLE
*DriverHandle
566 Search BlockName "&OFFSET=Offset&WIDTH=Width" in a string.
568 @param String The string to be searched in.
569 @param Offset Offset in BlockName.
570 @param Width Width in BlockName.
572 @retval TRUE Block name found.
573 @retval FALSE Block name not found.
579 IN OUT CHAR16
*String
,
586 This routine is invoked by ConfigAccess.Callback() to retrived uncommitted data from Form Browser.
588 @param VariableGuid An optional field to indicate the target variable
590 @param VariableName An optional field to indicate the target
591 human-readable variable name.
592 @param BufferSize On input: Length in bytes of buffer to hold
593 retrived data. On output: If return
594 EFI_BUFFER_TOO_SMALL, containg length of buffer
596 @param Buffer Buffer to hold retrived data.
598 @retval EFI_SUCCESS Routine success.
599 @retval EFI_BUFFER_TOO_SMALL The intput buffer is too small.
605 EFI_GUID
*VariableGuid
, OPTIONAL
606 CHAR16
*VariableName
, OPTIONAL
613 This routine is invoked by ConfigAccess.Callback() to update uncommitted data of Form Browser.
615 @param VariableGuid An optional field to indicate the target variable
617 @param VariableName An optional field to indicate the target
618 human-readable variable name.
619 @param BufferSize Length in bytes of buffer to hold retrived data.
620 @param Buffer Buffer to hold retrived data.
621 @param RequestElement An optional field to specify which part of the
622 buffer data will be send back to Browser. If NULL,
623 the whole buffer of data will be committed to
624 Browser. <RequestElement> ::=
625 &OFFSET=<Number>&WIDTH=<Number>*
627 @retval EFI_SUCCESS Routine success.
628 @retval Other Updating Browser uncommitted data failed.
634 EFI_GUID
*VariableGuid
, OPTIONAL
635 CHAR16
*VariableName
, OPTIONAL
638 CHAR16
*RequestElement OPTIONAL
643 Draw a dialog and return the selected key.
645 @param NumberOfLines The number of lines for the dialog box
646 @param KeyValue The EFI_KEY value returned if HotKey is TRUE..
647 @param String Pointer to the first string in the list
648 @param ... A series of (quantity == NumberOfLines - 1) text
649 strings which will be used to construct the dialog
652 @retval EFI_SUCCESS Displayed dialog and received user interaction
653 @retval EFI_INVALID_PARAMETER One of the parameters was invalid.
660 IN UINTN NumberOfLines
,
661 OUT EFI_INPUT_KEY
*KeyValue
,