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 QuestionId Question ID
228 @param OptionList 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 Flags 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
,
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
440 Converts binary buffer to Unicode string in reversed byte order to BufToHexString().
442 @param Str String for output
443 @param Buffer Binary buffer.
444 @param BufferSize Size of the buffer in bytes.
446 @retval EFI_SUCCESS The function completed successfully.
459 Converts Hex String to binary buffer in reversed byte order to HexStringToBuf().
461 @param Buffer Pointer to buffer that receives the data.
462 @param BufferSize Length in bytes of the buffer to hold converted
463 data. If routine return with EFI_SUCCESS,
464 containing length of converted data. If routine
465 return with EFI_BUFFER_TOO_SMALL, containg length
467 @param Str String to be converted from.
469 @retval EFI_SUCCESS The function completed successfully.
475 IN OUT UINT8
*Buffer
,
476 IN OUT UINTN
*BufferSize
,
482 Convert binary representation Config string (e.g. "0041004200430044") to the
483 original string (e.g. "ABCD"). Config string appears in <ConfigHdr> (i.e.
484 "&NAME=<string>"), or Name/Value pair in <ConfigBody> (i.e. "label=<string>").
486 @param UnicodeString Original Unicode string.
487 @param StrBufferLen On input: Length in bytes of buffer to hold the Unicode string.
488 Includes tailing '\0' character.
490 If return EFI_SUCCESS, containing length of Unicode string buffer.
491 If return EFI_BUFFER_TOO_SMALL, containg length of string buffer desired.
492 @param ConfigString Binary representation of Unicode String, <string> := (<HexCh>4)+
494 @retval EFI_SUCCESS Routine success.
495 @retval EFI_BUFFER_TOO_SMALL The string buffer is too small.
498 ConfigStringToUnicode (
499 IN OUT CHAR16
*UnicodeString
,
500 IN OUT UINTN
*StrBufferLen
,
501 IN CHAR16
*ConfigString
506 Convert Unicode string to binary representation Config string, e.g.
507 "ABCD" => "0041004200430044". Config string appears in <ConfigHdr> (i.e.
508 "&NAME=<string>"), or Name/Value pair in <ConfigBody> (i.e. "label=<string>").
510 @param ConfigString Binary representation of Unicode String, <string> := (<HexCh>4)+
511 @param StrBufferLen On input: Length in bytes of buffer to hold the Unicode string.
512 Includes tailing '\0' character.
514 If return EFI_SUCCESS, containing length of Unicode string buffer.
515 If return EFI_BUFFER_TOO_SMALL, containg length of string buffer desired.
516 @param UnicodeString Original Unicode string.
518 @retval EFI_SUCCESS Routine success.
519 @retval EFI_BUFFER_TOO_SMALL The string buffer is too small.
522 UnicodeToConfigString (
523 IN OUT CHAR16
*ConfigString
,
524 IN OUT UINTN
*StrBufferLen
,
525 IN CHAR16
*UnicodeString
530 Construct <ConfigHdr> using routing information GUID/NAME/PATH.
532 @param ConfigHdr Pointer to the ConfigHdr string.
533 @param StrBufferLen On input: Length in bytes of buffer to hold the
534 ConfigHdr string. Includes tailing '\0' character.
535 On output: If return EFI_SUCCESS, containing
536 length of ConfigHdr string buffer. If return
537 EFI_BUFFER_TOO_SMALL, containg length of string
539 @param Guid Routing information: GUID.
540 @param Name Routing information: NAME.
541 @param DriverHandle Driver handle which contains the routing
544 @retval EFI_SUCCESS Routine success.
545 @retval EFI_BUFFER_TOO_SMALL The ConfigHdr string buffer is too small.
551 IN OUT CHAR16
*ConfigHdr
,
552 IN OUT UINTN
*StrBufferLen
,
554 IN CHAR16
*Name
, OPTIONAL
555 IN EFI_HANDLE
*DriverHandle
561 Search BlockName "&OFFSET=Offset&WIDTH=Width" in a string.
563 @param String The string to be searched in.
564 @param Offset Offset in BlockName.
565 @param Width Width in BlockName.
567 @retval TRUE Block name found.
568 @retval FALSE Block name not found.
574 IN OUT CHAR16
*String
,
581 This routine is invoked by ConfigAccess.Callback() to retrived uncommitted data from Form Browser.
583 @param VariableGuid An optional field to indicate the target variable
585 @param VariableName An optional field to indicate the target
586 human-readable variable name.
587 @param BufferSize On input: Length in bytes of buffer to hold
588 retrived data. On output: If return
589 EFI_BUFFER_TOO_SMALL, containg length of buffer
591 @param Buffer Buffer to hold retrived data.
593 @retval EFI_SUCCESS Routine success.
594 @retval EFI_BUFFER_TOO_SMALL The intput buffer is too small.
600 EFI_GUID
*VariableGuid
, OPTIONAL
601 CHAR16
*VariableName
, OPTIONAL
608 This routine is invoked by ConfigAccess.Callback() to update uncommitted data of Form Browser.
610 @param VariableGuid An optional field to indicate the target variable
612 @param VariableName An optional field to indicate the target
613 human-readable variable name.
614 @param BufferSize Length in bytes of buffer to hold retrived data.
615 @param Buffer Buffer to hold retrived data.
616 @param RequestElement An optional field to specify which part of the
617 buffer data will be send back to Browser. If NULL,
618 the whole buffer of data will be committed to
619 Browser. <RequestElement> ::=
620 &OFFSET=<Number>&WIDTH=<Number>*
622 @retval EFI_SUCCESS Routine success.
623 @retval Other Updating Browser uncommitted data failed.
629 EFI_GUID
*VariableGuid
, OPTIONAL
630 CHAR16
*VariableName
, OPTIONAL
633 CHAR16
*RequestElement OPTIONAL
638 Draw a dialog and return the selected key.
640 @param NumberOfLines The number of lines for the dialog box
641 @param KeyValue The EFI_KEY value returned if HotKey is TRUE..
642 @param String Pointer to the first string in the list
643 @param ... A series of (quantity == NumberOfLines) text
644 strings which will be used to construct the dialog
647 @retval EFI_SUCCESS Displayed dialog and received user interaction
648 @retval EFI_INVALID_PARAMETER One of the parameters was invalid.
655 IN UINTN NumberOfLines
,
656 OUT EFI_INPUT_KEY
*KeyValue
,