1 /** @file 2 Public include file for the HII Library 3 4 Copyright (c) 2007 - 2018, Intel Corporation. All rights reserved.<BR> 5 SPDX-License-Identifier: BSD-2-Clause-Patent 6 7 **/ 8 9 #ifndef __HII_LIB_H__ 10 #define __HII_LIB_H__ 11 12 //////////////////////////////////////////////////////// 13 //////////////////////////////////////////////////////// 14 // HiiLib Functions 15 //////////////////////////////////////////////////////// 16 //////////////////////////////////////////////////////// 17 18 /** 19 Registers a list of packages in the HII Database and returns the HII Handle 20 associated with that registration. If an HII Handle has already been registered 21 with the same PackageListGuid and DeviceHandle, then NULL is returned. If there 22 are not enough resources to perform the registration, then NULL is returned. 23 If an empty list of packages is passed in, then NULL is returned. If the size of 24 the list of package is 0, then NULL is returned. 25 26 The variable arguments are pointers that point to package headers defined 27 by UEFI VFR compiler and StringGather tool. 28 29 #pragma pack (push, 1) 30 typedef struct { 31 UINT32 BinaryLength; 32 EFI_HII_PACKAGE_HEADER PackageHeader; 33 } EDKII_AUTOGEN_PACKAGES_HEADER; 34 #pragma pack (pop) 35 36 @param[in] PackageListGuid The GUID of the package list. 37 @param[in] DeviceHandle If not NULL, the Device Handle on which 38 an instance of DEVICE_PATH_PROTOCOL is installed. 39 This Device Handle uniquely defines the device that 40 the added packages are associated with. 41 @param[in] ... The variable argument list that contains pointers 42 to packages terminated by a NULL. 43 44 @retval NULL An HII Handle has already been registered in the HII Database with 45 the same PackageListGuid and DeviceHandle. 46 @retval NULL The HII Handle could not be created. 47 @retval NULL An empty list of packages was passed in. 48 @retval NULL All packages are empty. 49 @retval Other The HII Handle associated with the newly registered package list. 50 51 **/ 52 EFI_HII_HANDLE 53 EFIAPI 54 HiiAddPackages ( 55 IN CONST EFI_GUID *PackageListGuid, 56 IN EFI_HANDLE DeviceHandle OPTIONAL, 57 ... 58 ) 59 ; 60 61 /** 62 Removes a package list from the HII database. 63 64 If HiiHandle is NULL, then ASSERT(). 65 If HiiHandle is not a valid EFI_HII_HANDLE in the HII database, then ASSERT(). 66 67 @param[in] HiiHandle The handle that was previously registered in the HII database 68 69 **/ 70 VOID 71 EFIAPI 72 HiiRemovePackages ( 73 IN EFI_HII_HANDLE HiiHandle 74 ) 75 ; 76 77 /** 78 This function creates a new string in String Package or updates an existing 79 string in a String Package. If StringId is 0, then a new string is added to 80 a String Package. If StringId is not zero, then a string in String Package is 81 updated. If SupportedLanguages is NULL, then the string is added or updated 82 for all the languages that the String Package supports. If SupportedLanguages 83 is not NULL, then the string is added or updated for the set of languages 84 specified by SupportedLanguages. 85 86 If HiiHandle is NULL, then ASSERT(). 87 If String is NULL, then ASSERT(). 88 89 @param[in] HiiHandle A handle that was previously registered in the 90 HII Database. 91 @param[in] StringId If zero, then a new string is created in the 92 String Package associated with HiiHandle. If 93 non-zero, then the string specified by StringId 94 is updated in the String Package associated 95 with HiiHandle. 96 @param[in] String A pointer to the Null-terminated Unicode string 97 to add or update in the String Package associated 98 with HiiHandle. 99 @param[in] SupportedLanguages A pointer to a Null-terminated ASCII string of 100 language codes. If this parameter is NULL, then 101 String is added or updated in the String Package 102 associated with HiiHandle for all the languages 103 that the String Package supports. If this 104 parameter is not NULL, then String is added 105 or updated in the String Package associated with 106 HiiHandle for the set of languages specified by 107 SupportedLanguages. The format of 108 SupportedLanguages must follow the language 109 format assumed in the HII Database. 110 111 @retval 0 The string could not be added or updated in the String Package. 112 @retval Other The EFI_STRING_ID of the newly added or updated string. 113 114 **/ 115 EFI_STRING_ID 116 EFIAPI 117 HiiSetString ( 118 IN EFI_HII_HANDLE HiiHandle, 119 IN EFI_STRING_ID StringId, OPTIONAL 120 IN CONST EFI_STRING String, 121 IN CONST CHAR8 *SupportedLanguages OPTIONAL 122 ) 123 ; 124 125 /** 126 Retrieves a string from a string package in a specific language. If the language 127 is not specified, then a string from a string package in the current platform 128 language is retrieved. If the string cannot be retrieved using the specified 129 language or the current platform language, then the string is retrieved from 130 the string package in the first language the string package supports. The 131 returned string is allocated using AllocatePool(). The caller is responsible 132 for freeing the allocated buffer using FreePool(). 133 134 If HiiHandle is NULL, then ASSERT(). 135 If StringId is 0, then ASSERT(). 136 137 @param[in] HiiHandle A handle that was previously registered in the HII Database. 138 @param[in] StringId The identifier of the string to retrieved from the string 139 package associated with HiiHandle. 140 @param[in] Language The language of the string to retrieve. If this parameter 141 is NULL, then the current platform language is used. The 142 format of Language must follow the language format assumed in 143 the HII Database. 144 145 @retval NULL The string specified by StringId is not present in the string package. 146 @retval Other The string was returned. 147 148 **/ 149 EFI_STRING 150 EFIAPI 151 HiiGetString ( 152 IN EFI_HII_HANDLE HiiHandle, 153 IN EFI_STRING_ID StringId, 154 IN CONST CHAR8 *Language OPTIONAL 155 ) 156 ; 157 158 /** 159 Retrieves a string from a string package named by GUID, in the specified language. 160 If the language is not specified, then a string from a string package in the 161 current platform language is retrieved. If the string cannot be retrieved 162 using the specified language or the current platform language, then the string 163 is retrieved from the string package in the first language the string package 164 supports. The returned string is allocated using AllocatePool(). The caller 165 is responsible for freeing the allocated buffer using FreePool(). 166 167 If PackageListGuid is NULL, then ASSERT(). 168 If StringId is 0, then ASSERT(). 169 170 @param[in] PackageListGuid The GUID of a package list that was previously 171 registered in the HII Database. 172 @param[in] StringId The identifier of the string to retrieved from the 173 string package associated with PackageListGuid. 174 @param[in] Language The language of the string to retrieve. If this 175 parameter is NULL, then the current platform 176 language is used. The format of Language must 177 follow the language format assumed in the HII Database. 178 179 @retval NULL The package list specified by PackageListGuid is not present in the 180 HII Database. 181 @retval NULL The string specified by StringId is not present in the string package. 182 @retval Other The string was returned. 183 184 **/ 185 EFI_STRING 186 EFIAPI 187 HiiGetPackageString ( 188 IN CONST EFI_GUID *PackageListGuid, 189 IN EFI_STRING_ID StringId, 190 IN CONST CHAR8 *Language OPTIONAL 191 ) 192 ; 193 194 /** 195 Retrieves the array of all the HII Handles or the HII handles of a specific 196 package list GUID in the HII Database. 197 This array is terminated with a NULL HII Handle. 198 This function allocates the returned array using AllocatePool(). 199 The caller is responsible for freeing the array with FreePool(). 200 201 @param[in] PackageListGuid An optional parameter that is used to request 202 HII Handles associated with a specific 203 Package List GUID. If this parameter is NULL, 204 then all the HII Handles in the HII Database 205 are returned. If this parameter is not NULL, 206 then zero or more HII Handles associated with 207 PackageListGuid are returned. 208 209 @retval NULL No HII handles were found in the HII database 210 @retval NULL The array of HII Handles could not be retrieved 211 @retval Other A pointer to the NULL terminated array of HII Handles 212 213 **/ 214 EFI_HII_HANDLE * 215 EFIAPI 216 HiiGetHiiHandles ( 217 IN CONST EFI_GUID *PackageListGuid OPTIONAL 218 ) 219 ; 220 221 /** 222 This function allows a caller to extract the form set opcode form the Hii Handle. 223 The returned buffer is allocated using AllocatePool().The caller is responsible 224 for freeing the allocated buffer using FreePool(). 225 226 @param Handle The HII handle. 227 @param Buffer On return, points to a pointer which point to the buffer that contain the formset opcode. 228 @param BufferSize On return, points to the length of the buffer. 229 230 @retval EFI_OUT_OF_RESOURCES No enough memory resource is allocated. 231 @retval EFI_NOT_FOUND Can't find the package data for the input Handle. 232 @retval EFI_INVALID_PARAMETER The input parameters are not correct. 233 @retval EFI_SUCCESS Get the formset opcode from the hii handle successfully. 234 235 **/ 236 EFI_STATUS 237 EFIAPI 238 HiiGetFormSetFromHiiHandle( 239 IN EFI_HII_HANDLE Handle, 240 OUT EFI_IFR_FORM_SET **Buffer, 241 OUT UINTN *BufferSize 242 ); 243 244 /** 245 Retrieves a pointer to a Null-terminated ASCII string containing the list 246 of languages that an HII handle in the HII Database supports. The returned 247 string is allocated using AllocatePool(). The caller is responsible for freeing 248 the returned string using FreePool(). The format of the returned string follows 249 the language format assumed in the HII Database. 250 251 If HiiHandle is NULL, then ASSERT(). 252 253 @param[in] HiiHandle A handle that was previously registered in the HII Database. 254 255 @retval NULL HiiHandle is not registered in the HII database 256 @retval NULL There are not enough resources available to retrieve the supported 257 languages. 258 @retval NULL The list of supported languages could not be retrieved. 259 @retval Other A pointer to the Null-terminated ASCII string of supported languages. 260 261 **/ 262 CHAR8 * 263 EFIAPI 264 HiiGetSupportedLanguages ( 265 IN EFI_HII_HANDLE HiiHandle 266 ) 267 ; 268 269 /** 270 Allocates and returns a Null-terminated Unicode <ConfigHdr> string using routing 271 information that includes a GUID, an optional Unicode string name, and a device 272 path. The string returned is allocated with AllocatePool(). The caller is 273 responsible for freeing the allocated string with FreePool(). 274 275 The format of a <ConfigHdr> is as follows: 276 277 GUID=<HexCh>32&NAME=<Char>NameLength&PATH=<HexChar>DevicePathSize<Null> 278 279 @param[in] Guid The pointer to an EFI_GUID that is the routing information 280 GUID. Each of the 16 bytes in Guid is converted to 281 a 2 Unicode character hexadecimal string. This is 282 an optional parameter that may be NULL. 283 @param[in] Name The pointer to a Null-terminated Unicode string that is 284 the routing information NAME. This is an optional 285 parameter that may be NULL. Each 16-bit Unicode 286 character in Name is converted to a 4 character Unicode 287 hexadecimal string. 288 @param[in] DriverHandle The driver handle that supports a Device Path Protocol 289 that is the routing information PATH. Each byte of 290 the Device Path associated with DriverHandle is converted 291 to a two (Unicode) character hexadecimal string. 292 293 @retval NULL DriverHandle does not support the Device Path Protocol. 294 @retval NULL DriverHandle does not support the Device Path Protocol. 295 @retval Other A pointer to the Null-terminate Unicode <ConfigHdr> string 296 297 **/ 298 EFI_STRING 299 EFIAPI 300 HiiConstructConfigHdr ( 301 IN CONST EFI_GUID *Guid, OPTIONAL 302 IN CONST CHAR16 *Name, OPTIONAL 303 IN EFI_HANDLE DriverHandle 304 ); 305 306 /** 307 Reset the default value specified by DefaultId to the driver 308 configuration specified by the Request string. 309 310 NULL request string support depends on the ExportConfig interface of 311 HiiConfigRouting protocol in UEFI specification. 312 313 @param Request A null-terminated Unicode string in 314 <MultiConfigRequest> format. It can be NULL. 315 If it is NULL, all configurations for the 316 entirety of the current HII database will be reset. 317 @param DefaultId Specifies the type of defaults to retrieve. 318 319 @retval TRUE The default value was set successfully. 320 @retval FALSE The default value was not found. 321 **/ 322 BOOLEAN 323 EFIAPI 324 HiiSetToDefaults ( 325 IN CONST EFI_STRING Request, OPTIONAL 326 IN UINT16 DefaultId 327 ); 328 329 /** 330 Validate the current configuration by parsing the IFR opcode in HII form. 331 332 NULL request string support depends on the ExportConfig interface of 333 HiiConfigRouting protocol in the UEFI specification. 334 335 @param Request A null-terminated Unicode string in 336 <MultiConfigRequest> format. It can be NULL. 337 If it is NULL, all current configurations for the 338 entirety of the current HII database will be validated. 339 340 @retval TRUE The current configuration is valid. 341 @retval FALSE The current configuration is invalid. 342 **/ 343 BOOLEAN 344 EFIAPI 345 HiiValidateSettings ( 346 IN CONST EFI_STRING Request OPTIONAL 347 ); 348 349 /** 350 Determines if the routing data specified by GUID and NAME match a <ConfigHdr>. 351 352 If ConfigHdr is NULL, then ASSERT(). 353 354 @param[in] ConfigHdr Either <ConfigRequest> or <ConfigResp>. 355 @param[in] Guid The GUID of the storage. 356 @param[in] Name The NAME of the storage. 357 358 @retval TRUE Routing information matches <ConfigHdr>. 359 @retval FALSE Routing information does not match <ConfigHdr>. 360 361 **/ 362 BOOLEAN 363 EFIAPI 364 HiiIsConfigHdrMatch ( 365 IN CONST EFI_STRING ConfigHdr, 366 IN CONST EFI_GUID *Guid, OPTIONAL 367 IN CONST CHAR16 *Name OPTIONAL 368 ); 369 370 /** 371 Retrieves uncommitted data from the Form Browser and converts it to a binary 372 buffer. 373 374 @param[in] VariableGuid The pointer to an EFI_GUID structure. This is an optional 375 parameter that may be NULL. 376 @param[in] VariableName The pointer to a Null-terminated Unicode string. This 377 is an optional parameter that may be NULL. 378 @param[in] BufferSize The length in bytes of buffer to hold retrieved data. 379 @param[out] Buffer The buffer of data to be updated. 380 381 @retval FALSE The uncommitted data could not be retrieved. 382 @retval TRUE The uncommitted data was retrieved. 383 384 **/ 385 BOOLEAN 386 EFIAPI 387 HiiGetBrowserData ( 388 IN CONST EFI_GUID *VariableGuid, OPTIONAL 389 IN CONST CHAR16 *VariableName, OPTIONAL 390 IN UINTN BufferSize, 391 OUT UINT8 *Buffer 392 ); 393 394 /** 395 Updates uncommitted data in the Form Browser. 396 397 If Buffer is NULL, then ASSERT(). 398 399 @param[in] VariableGuid The pointer to an EFI_GUID structure. This is an optional 400 parameter that may be NULL. 401 @param[in] VariableName The pointer to a Null-terminated Unicode string. This 402 is an optional parameter that may be NULL. 403 @param[in] BufferSize The length, in bytes, of Buffer. 404 @param[in] Buffer The buffer of data to commit. 405 @param[in] RequestElement An optional field to specify which part of the 406 buffer data will be send back to Browser. If NULL, 407 the whole buffer of data will be committed to 408 Browser. 409 <RequestElement> ::= &OFFSET=<Number>&WIDTH=<Number>* 410 411 @retval FALSE The uncommitted data could not be updated. 412 @retval TRUE The uncommitted data was updated. 413 414 **/ 415 BOOLEAN 416 EFIAPI 417 HiiSetBrowserData ( 418 IN CONST EFI_GUID *VariableGuid, OPTIONAL 419 IN CONST CHAR16 *VariableName, OPTIONAL 420 IN UINTN BufferSize, 421 IN CONST UINT8 *Buffer, 422 IN CONST CHAR16 *RequestElement OPTIONAL 423 ); 424 425 ///////////////////////////////////////// 426 ///////////////////////////////////////// 427 /// IFR Functions 428 ///////////////////////////////////////// 429 ///////////////////////////////////////// 430 431 /** 432 Returns a UINT64 value that contains bitfields for Hour, Minute, and Second. 433 The lower 8-bits of Hour are placed in bits 0..7. The lower 8-bits of Minute 434 are placed in bits 8..15, and the lower 8-bits of Second are placed in bits 435 16..23. This format was selected because it can be easily translated to 436 an EFI_HII_TIME structure in an EFI_IFR_TYPE_VALUE union. 437 438 @param Hour The hour value to be encoded. 439 @param Minute The minute value to be encoded. 440 @param Second The second value to be encoded. 441 442 @return A 64-bit containing Hour, Minute, and Second. 443 **/ 444 #define EFI_HII_TIME_UINT64(Hour, Minute, Second) \ 445 (UINT64)((Hour & 0xff) | ((Minute & 0xff) << 8) | ((Second & 0xff) << 16)) 446 447 /** 448 Returns a UINT64 value that contains bit fields for Year, Month, and Day. 449 The lower 16-bits of Year are placed in bits 0..15. The lower 8-bits of Month 450 are placed in bits 16..23, and the lower 8-bits of Day are placed in bits 451 24..31. This format was selected because it can be easily translated to 452 an EFI_HII_DATE structure in an EFI_IFR_TYPE_VALUE union. 453 454 @param Year The year value to be encoded. 455 @param Month The month value to be encoded. 456 @param Day The day value to be encoded. 457 458 @return A 64-bit containing Year, Month, and Day. 459 **/ 460 #define EFI_HII_DATE_UINT64(Year, Month, Day) \ 461 (UINT64)((Year & 0xffff) | ((Month & 0xff) << 16) | ((Day & 0xff) << 24)) 462 463 /** 464 Allocates and returns a new OpCode Handle. OpCode Handles must be freed with 465 HiiFreeOpCodeHandle(). 466 467 @retval NULL There are not enough resources to allocate a new OpCode Handle. 468 @retval Other A new OpCode handle. 469 470 **/ 471 VOID * 472 EFIAPI 473 HiiAllocateOpCodeHandle ( 474 VOID 475 ); 476 477 /** 478 Frees an OpCode Handle that was previously allocated with HiiAllocateOpCodeHandle(). 479 When an OpCode Handle is freed, all of the opcodes associated with the OpCode 480 Handle are also freed. 481 482 If OpCodeHandle is NULL, then ASSERT(). 483 484 @param[in] OpCodeHandle The handle to the buffer of opcodes. 485 486 **/ 487 VOID 488 EFIAPI 489 HiiFreeOpCodeHandle ( 490 VOID *OpCodeHandle 491 ); 492 493 /** 494 Append raw opcodes to an OpCodeHandle. 495 496 If OpCodeHandle is NULL, then ASSERT(). 497 If RawBuffer is NULL, then ASSERT(); 498 499 @param[in] OpCodeHandle The handle to the buffer of opcodes. 500 @param[in] RawBuffer The buffer of opcodes to append. 501 @param[in] RawBufferSize The size, in bytes, of Buffer. 502 503 @retval NULL There is not enough space left in Buffer to add the opcode. 504 @retval Other A pointer to the appended opcodes. 505 506 **/ 507 UINT8 * 508 EFIAPI 509 HiiCreateRawOpCodes ( 510 IN VOID *OpCodeHandle, 511 IN UINT8 *RawBuffer, 512 IN UINTN RawBufferSize 513 ); 514 515 /** 516 Create EFI_IFR_END_OP opcode. 517 518 If OpCodeHandle is NULL, then ASSERT(). 519 520 @param[in] OpCodeHandle Handle to the buffer of opcodes. 521 522 @retval NULL There is not enough space left in Buffer to add the opcode. 523 @retval Other A pointer to the created opcode. 524 525 **/ 526 UINT8 * 527 EFIAPI 528 HiiCreateEndOpCode ( 529 IN VOID *OpCodeHandle 530 ); 531 532 /** 533 Create EFI_IFR_ONE_OF_OPTION_OP opcode. 534 535 If OpCodeHandle is NULL, then ASSERT(). 536 If Type is invalid, then ASSERT(). 537 If Flags is invalid, then ASSERT(). 538 539 @param[in] OpCodeHandle The handle to the buffer of opcodes. 540 @param[in] StringId StringId for the option. 541 @param[in] Flags The flags for the option. 542 @param[in] Type The type for the option. 543 @param[in] Value The value for the option. 544 545 @retval NULL There is not enough space left in Buffer to add the opcode. 546 @retval Other A pointer to the created opcode. 547 548 **/ 549 UINT8 * 550 EFIAPI 551 HiiCreateOneOfOptionOpCode ( 552 IN VOID *OpCodeHandle, 553 IN UINT16 StringId, 554 IN UINT8 Flags, 555 IN UINT8 Type, 556 IN UINT64 Value 557 ); 558 559 /** 560 Create EFI_IFR_DEFAULT_OP opcode. 561 562 If OpCodeHandle is NULL, then ASSERT(). 563 If Type is invalid, then ASSERT(). 564 565 @param[in] OpCodeHandle The handle to the buffer of opcodes. 566 @param[in] DefaultId The DefaultId for the default. 567 @param[in] Type The type for the default. 568 @param[in] Value The value for the default. 569 570 @retval NULL There is not enough space left in Buffer to add the opcode. 571 @retval Other A pointer to the created opcode. 572 573 **/ 574 UINT8 * 575 EFIAPI 576 HiiCreateDefaultOpCode ( 577 IN VOID *OpCodeHandle, 578 IN UINT16 DefaultId, 579 IN UINT8 Type, 580 IN UINT64 Value 581 ); 582 583 /** 584 Create EFI_IFR_GUID opcode. 585 586 If OpCodeHandle is NULL, then ASSERT(). 587 If Guid is NULL, then ASSERT(). 588 If OpCodeSize < sizeof (EFI_IFR_GUID), then ASSERT(). 589 590 @param[in] OpCodeHandle The handle to the buffer of opcodes. 591 @param[in] Guid The pointer to EFI_GUID of this guided opcode. 592 @param[in] GuidOpCode The pointer to an EFI_IFR_GUID opcode. This is an 593 optional parameter that may be NULL. If this 594 parameter is NULL, then the GUID extension 595 region of the created opcode is filled with zeros. 596 If this parameter is not NULL, then the GUID 597 extension region of GuidData will be copied to 598 the GUID extension region of the created opcode. 599 @param[in] OpCodeSize The size, in bytes, of created opcode. This value 600 must be >= sizeof(EFI_IFR_GUID). 601 602 @retval NULL There is not enough space left in Buffer to add the opcode. 603 @retval Other A pointer to the created opcode. 604 605 **/ 606 UINT8 * 607 EFIAPI 608 HiiCreateGuidOpCode ( 609 IN VOID *OpCodeHandle, 610 IN CONST EFI_GUID *Guid, 611 IN CONST VOID *GuidOpCode, OPTIONAL 612 IN UINTN OpCodeSize 613 ); 614 615 /** 616 Create EFI_IFR_ACTION_OP opcode. 617 618 If OpCodeHandle is NULL, then ASSERT(). 619 If any reserved bits are set in QuestionFlags, then ASSERT(). 620 621 @param[in] OpCodeHandle The handle to the buffer of opcodes. 622 @param[in] QuestionId The Question ID. 623 @param[in] Prompt The String ID for Prompt. 624 @param[in] Help The String ID for Help. 625 @param[in] QuestionFlags The flags in the Question Header. 626 @param[in] QuestionConfig The String ID for the configuration. 627 628 @retval NULL There is not enough space left in Buffer to add the opcode. 629 @retval Other A pointer to the created opcode. 630 631 **/ 632 UINT8 * 633 EFIAPI 634 HiiCreateActionOpCode ( 635 IN VOID *OpCodeHandle, 636 IN EFI_QUESTION_ID QuestionId, 637 IN EFI_STRING_ID Prompt, 638 IN EFI_STRING_ID Help, 639 IN UINT8 QuestionFlags, 640 IN EFI_STRING_ID QuestionConfig 641 ); 642 643 /** 644 Create EFI_IFR_SUBTITLE_OP opcode. 645 646 If OpCodeHandle is NULL, then ASSERT(). 647 If any reserved bits are set in Flags, then ASSERT(). 648 If Scope > 1, then ASSERT(). 649 650 @param[in] OpCodeHandle The handle to the buffer of opcodes. 651 @param[in] Prompt The string ID for Prompt. 652 @param[in] Help The string ID for Help. 653 @param[in] Flags The subtitle opcode flags. 654 @param[in] Scope 1 if this opcode is the beginning of a new scope. 655 0 if this opcode is within the current scope. 656 657 @retval NULL There is not enough space left in Buffer to add the opcode. 658 @retval Other A pointer to the created opcode. 659 660 **/ 661 UINT8 * 662 EFIAPI 663 HiiCreateSubTitleOpCode ( 664 IN VOID *OpCodeHandle, 665 IN EFI_STRING_ID Prompt, 666 IN EFI_STRING_ID Help, 667 IN UINT8 Flags, 668 IN UINT8 Scope 669 ); 670 671 /** 672 Create EFI_IFR_REF_OP opcode. 673 674 If OpCodeHandle is NULL, then ASSERT(). 675 If any reserved bits are set in QuestionFlags, then ASSERT(). 676 677 @param[in] OpCodeHandle The handle to the buffer of opcodes. 678 @param[in] FormId The Destination Form ID. 679 @param[in] Prompt The string ID for Prompt. 680 @param[in] Help The string ID for Help. 681 @param[in] QuestionFlags The flags in Question Header 682 @param[in] QuestionId Question ID. 683 684 @retval NULL There is not enough space left in Buffer to add the opcode. 685 @retval Other A pointer to the created opcode. 686 687 **/ 688 UINT8 * 689 EFIAPI 690 HiiCreateGotoOpCode ( 691 IN VOID *OpCodeHandle, 692 IN EFI_FORM_ID FormId, 693 IN EFI_STRING_ID Prompt, 694 IN EFI_STRING_ID Help, 695 IN UINT8 QuestionFlags, 696 IN EFI_QUESTION_ID QuestionId 697 ); 698 699 /** 700 Create EFI_IFR_REF_OP, EFI_IFR_REF2_OP, EFI_IFR_REF3_OP and EFI_IFR_REF4_OP opcode. 701 702 When RefDevicePath is not zero, EFI_IFR_REF4 opcode will be created. 703 When RefDevicePath is zero and RefFormSetId is not NULL, EFI_IFR_REF3 opcode will be created. 704 When RefDevicePath is zero, RefFormSetId is NULL and RefQuestionId is not zero, EFI_IFR_REF2 opcode will be created. 705 When RefDevicePath is zero, RefFormSetId is NULL and RefQuestionId is zero, EFI_IFR_REF opcode will be created. 706 707 If OpCodeHandle is NULL, then ASSERT(). 708 If any reserved bits are set in QuestionFlags, then ASSERT(). 709 710 @param[in] OpCodeHandle The handle to the buffer of opcodes. 711 @param[in] RefFormId The Destination Form ID. 712 @param[in] Prompt The string ID for Prompt. 713 @param[in] Help The string ID for Help. 714 @param[in] QuestionFlags The flags in Question Header 715 @param[in] QuestionId Question ID. 716 @param[in] RefQuestionId The question on the form to which this link is referring. 717 If its value is zero, then the link refers to the top of the form. 718 @param[in] RefFormSetId The form set to which this link is referring. If its value is NULL, and RefDevicePath is 719 zero, then the link is to the current form set. 720 @param[in] RefDevicePath The string identifier that specifies the string containing the text representation of 721 the device path to which the form set containing the form specified by FormId. 722 If its value is zero, then the link refers to the current page. 723 724 @retval NULL There is not enough space left in Buffer to add the opcode. 725 @retval Other A pointer to the created opcode. 726 727 **/ 728 UINT8 * 729 EFIAPI 730 HiiCreateGotoExOpCode ( 731 IN VOID *OpCodeHandle, 732 IN EFI_FORM_ID RefFormId, 733 IN EFI_STRING_ID Prompt, 734 IN EFI_STRING_ID Help, 735 IN UINT8 QuestionFlags, 736 IN EFI_QUESTION_ID QuestionId, 737 IN EFI_QUESTION_ID RefQuestionId, 738 IN EFI_GUID *RefFormSetId, OPTIONAL 739 IN EFI_STRING_ID RefDevicePath 740 ); 741 742 /** 743 Create EFI_IFR_CHECKBOX_OP opcode. 744 745 If OpCodeHandle is NULL, then ASSERT(). 746 If any reserved bits are set in QuestionFlags, then ASSERT(). 747 If any reserved bits are set in CheckBoxFlags, then ASSERT(). 748 749 @param[in] OpCodeHandle The handle to the buffer of opcodes. 750 @param[in] QuestionId The question ID. 751 @param[in] VarStoreId The storage ID. 752 @param[in] VarOffset Offset in Storage or String ID of the name (VarName) 753 for this name/value pair. 754 @param[in] Prompt The string ID for Prompt. 755 @param[in] Help The string ID for Help. 756 @param[in] QuestionFlags The flags in Question Header. 757 @param[in] CheckBoxFlags The flags for checkbox opcode. 758 @param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This 759 is an optional parameter that may be NULL. 760 761 @retval NULL There is not enough space left in Buffer to add the opcode. 762 @retval Other A pointer to the created opcode. 763 764 **/ 765 UINT8 * 766 EFIAPI 767 HiiCreateCheckBoxOpCode ( 768 IN VOID *OpCodeHandle, 769 IN EFI_QUESTION_ID QuestionId, 770 IN EFI_VARSTORE_ID VarStoreId, 771 IN UINT16 VarOffset, 772 IN EFI_STRING_ID Prompt, 773 IN EFI_STRING_ID Help, 774 IN UINT8 QuestionFlags, 775 IN UINT8 CheckBoxFlags, 776 IN VOID *DefaultsOpCodeHandle OPTIONAL 777 ); 778 779 /** 780 Create EFI_IFR_NUMERIC_OP opcode. 781 782 If OpCodeHandle is NULL, then ASSERT(). 783 If any reserved bits are set in QuestionFlags, then ASSERT(). 784 If any reserved bits are set in NumericFlags, then ASSERT(). 785 786 @param[in] OpCodeHandle The handle to the buffer of opcodes. 787 @param[in] QuestionId The question ID. 788 @param[in] VarStoreId The storage ID. 789 @param[in] VarOffset Offset in Storage or String ID of the name (VarName) 790 for this name/value pair. 791 @param[in] Prompt The string ID for Prompt. 792 @param[in] Help The string ID for Help. 793 @param[in] QuestionFlags The flags in Question Header. 794 @param[in] NumericFlags The flags for a numeric opcode. 795 @param[in] Minimum The numeric minimum value. 796 @param[in] Maximum The numeric maximum value. 797 @param[in] Step The numeric step for edit. 798 @param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This 799 is an optional parameter that may be NULL. 800 801 @retval NULL There is not enough space left in Buffer to add the opcode. 802 @retval Other A pointer to the created opcode. 803 804 **/ 805 UINT8 * 806 EFIAPI 807 HiiCreateNumericOpCode ( 808 IN VOID *OpCodeHandle, 809 IN EFI_QUESTION_ID QuestionId, 810 IN EFI_VARSTORE_ID VarStoreId, 811 IN UINT16 VarOffset, 812 IN EFI_STRING_ID Prompt, 813 IN EFI_STRING_ID Help, 814 IN UINT8 QuestionFlags, 815 IN UINT8 NumericFlags, 816 IN UINT64 Minimum, 817 IN UINT64 Maximum, 818 IN UINT64 Step, 819 IN VOID *DefaultsOpCodeHandle OPTIONAL 820 ); 821 822 /** 823 Create EFI_IFR_STRING_OP opcode. 824 825 If OpCodeHandle is NULL, then ASSERT(). 826 If any reserved bits are set in QuestionFlags, then ASSERT(). 827 If any reserved bits are set in StringFlags, then ASSERT(). 828 829 @param[in] OpCodeHandle The handle to the buffer of opcodes. 830 @param[in] QuestionId The question ID. 831 @param[in] VarStoreId The storage ID. 832 @param[in] VarOffset Offset in Storage or String ID of the name (VarName) 833 for this name/value pair. 834 @param[in] Prompt The string ID for Prompt. 835 @param[in] Help The string ID for Help. 836 @param[in] QuestionFlags The flags in Question Header. 837 @param[in] StringFlags The flags for a string opcode. 838 @param[in] MinSize The string minimum length. 839 @param[in] MaxSize The string maximum length. 840 @param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This 841 is an optional parameter that may be NULL. 842 843 @retval NULL There is not enough space left in Buffer to add the opcode. 844 @retval Other A pointer to the created opcode. 845 846 **/ 847 UINT8 * 848 EFIAPI 849 HiiCreateStringOpCode ( 850 IN VOID *OpCodeHandle, 851 IN EFI_QUESTION_ID QuestionId, 852 IN EFI_VARSTORE_ID VarStoreId, 853 IN UINT16 VarOffset, 854 IN EFI_STRING_ID Prompt, 855 IN EFI_STRING_ID Help, 856 IN UINT8 QuestionFlags, 857 IN UINT8 StringFlags, 858 IN UINT8 MinSize, 859 IN UINT8 MaxSize, 860 IN VOID *DefaultsOpCodeHandle OPTIONAL 861 ); 862 863 /** 864 Create EFI_IFR_ONE_OF_OP opcode. 865 866 If OpCodeHandle is NULL, then ASSERT(). 867 If any reserved bits are set in QuestionFlags, then ASSERT(). 868 If any reserved bits are set in OneOfFlags, then ASSERT(). 869 870 @param[in] OpCodeHandle The handle to the buffer of opcodes. 871 @param[in] QuestionId The question ID. 872 @param[in] VarStoreId The storage ID. 873 @param[in] VarOffset Offset in Storage or String ID of the name (VarName) 874 for this name/value pair. 875 @param[in] Prompt The string ID for Prompt. 876 @param[in] Help The string ID for Help. 877 @param[in] QuestionFlags The flags in Question Header. 878 @param[in] OneOfFlags The flags for a oneof opcode. 879 @param[in] OptionsOpCodeHandle The handle for a buffer of ONE_OF_OPTION opcodes. 880 @param[in] DefaultsOpCodeHandle The handle for a buffer of DEFAULT opcodes. This 881 is an optional parameter that may be NULL. 882 883 @retval NULL There is not enough space left in Buffer to add the opcode. 884 @retval Other A pointer to the created opcode. 885 886 **/ 887 UINT8 * 888 EFIAPI 889 HiiCreateOneOfOpCode ( 890 IN VOID *OpCodeHandle, 891 IN EFI_QUESTION_ID QuestionId, 892 IN EFI_VARSTORE_ID VarStoreId, 893 IN UINT16 VarOffset, 894 IN EFI_STRING_ID Prompt, 895 IN EFI_STRING_ID Help, 896 IN UINT8 QuestionFlags, 897 IN UINT8 OneOfFlags, 898 IN VOID *OptionsOpCodeHandle, 899 IN VOID *DefaultsOpCodeHandle OPTIONAL 900 ); 901 902 /** 903 Create EFI_IFR_ORDERED_LIST_OP opcode. 904 905 If OpCodeHandle is NULL, then ASSERT(). 906 If any reserved bits are set in QuestionFlags, then ASSERT(). 907 If any reserved bits are set in OrderedListFlags, then ASSERT(). 908 909 @param[in] OpCodeHandle The handle to the buffer of opcodes. 910 @param[in] QuestionId The question ID. 911 @param[in] VarStoreId The storage ID. 912 @param[in] VarOffset Offset in Storage or String ID of the name (VarName) 913 for this name/value pair. 914 @param[in] Prompt The string ID for Prompt. 915 @param[in] Help The string ID for Help. 916 @param[in] QuestionFlags The flags in Question Header. 917 @param[in] OrderedListFlags The flags for an ordered list opcode. 918 @param[in] DataType The type for option value. 919 @param[in] MaxContainers Maximum count for options in this ordered list 920 @param[in] OptionsOpCodeHandle The handle for a buffer of ONE_OF_OPTION opcodes. 921 @param[in] DefaultsOpCodeHandle Handle for a buffer of DEFAULT opcodes. This 922 is an optional parameter that may be NULL. 923 924 @retval NULL There is not enough space left in Buffer to add the opcode. 925 @retval Other A pointer to the created opcode. 926 927 **/ 928 UINT8 * 929 EFIAPI 930 HiiCreateOrderedListOpCode ( 931 IN VOID *OpCodeHandle, 932 IN EFI_QUESTION_ID QuestionId, 933 IN EFI_VARSTORE_ID VarStoreId, 934 IN UINT16 VarOffset, 935 IN EFI_STRING_ID Prompt, 936 IN EFI_STRING_ID Help, 937 IN UINT8 QuestionFlags, 938 IN UINT8 OrderedListFlags, 939 IN UINT8 DataType, 940 IN UINT8 MaxContainers, 941 IN VOID *OptionsOpCodeHandle, 942 IN VOID *DefaultsOpCodeHandle OPTIONAL 943 ); 944 945 /** 946 Create EFI_IFR_TEXT_OP opcode. 947 948 If OpCodeHandle is NULL, then ASSERT(). 949 950 @param[in] OpCodeHandle Handle to the buffer of opcodes. 951 @param[in] Prompt String ID for Prompt. 952 @param[in] Help String ID for Help. 953 @param[in] TextTwo String ID for TextTwo. 954 955 @retval NULL There is not enough space left in Buffer to add the opcode. 956 @retval Other A pointer to the created opcode. 957 958 **/ 959 UINT8 * 960 EFIAPI 961 HiiCreateTextOpCode ( 962 IN VOID *OpCodeHandle, 963 IN EFI_STRING_ID Prompt, 964 IN EFI_STRING_ID Help, 965 IN EFI_STRING_ID TextTwo 966 ); 967 968 /** 969 Create EFI_IFR_DATE_OP opcode. 970 971 If OpCodeHandle is NULL, then ASSERT(). 972 If any reserved bits are set in QuestionFlags, then ASSERT(). 973 If any reserved bits are set in DateFlags, then ASSERT(). 974 975 @param[in] OpCodeHandle Handle to the buffer of opcodes. 976 @param[in] QuestionId Question ID 977 @param[in] VarStoreId Storage ID, optional. If DateFlags is not 978 QF_DATE_STORAGE_NORMAL, this parameter is ignored. 979 @param[in] VarOffset Offset in Storage or String ID of the name (VarName) 980 for this name/value pair, optional. If DateFlags is not 981 QF_DATE_STORAGE_NORMAL, this parameter is ignored. 982 @param[in] Prompt String ID for Prompt 983 @param[in] Help String ID for Help 984 @param[in] QuestionFlags Flags in Question Header 985 @param[in] DateFlags Flags for date opcode 986 @param[in] DefaultsOpCodeHandle Handle for a buffer of DEFAULT opcodes. This 987 is an optional parameter that may be NULL. 988 989 @retval NULL There is not enough space left in Buffer to add the opcode. 990 @retval Other A pointer to the created opcode. 991 992 **/ 993 UINT8 * 994 EFIAPI 995 HiiCreateDateOpCode ( 996 IN VOID *OpCodeHandle, 997 IN EFI_QUESTION_ID QuestionId, 998 IN EFI_VARSTORE_ID VarStoreId, OPTIONAL 999 IN UINT16 VarOffset, OPTIONAL 1000 IN EFI_STRING_ID Prompt, 1001 IN EFI_STRING_ID Help, 1002 IN UINT8 QuestionFlags, 1003 IN UINT8 DateFlags, 1004 IN VOID *DefaultsOpCodeHandle OPTIONAL 1005 ); 1006 1007 /** 1008 Create EFI_IFR_TIME_OP opcode. 1009 1010 If OpCodeHandle is NULL, then ASSERT(). 1011 If any reserved bits are set in QuestionFlags, then ASSERT(). 1012 If any reserved bits are set in TimeFlags, then ASSERT(). 1013 1014 @param[in] OpCodeHandle Handle to the buffer of opcodes. 1015 @param[in] QuestionId Question ID 1016 @param[in] VarStoreId Storage ID, optional. If TimeFlags is not 1017 QF_TIME_STORAGE_NORMAL, this parameter is ignored. 1018 @param[in] VarOffset Offset in Storage or String ID of the name (VarName) 1019 for this name/value pair, optional. If TimeFlags is not 1020 QF_TIME_STORAGE_NORMAL, this parameter is ignored. 1021 @param[in] Prompt String ID for Prompt 1022 @param[in] Help String ID for Help 1023 @param[in] QuestionFlags Flags in Question Header 1024 @param[in] TimeFlags Flags for time opcode 1025 @param[in] DefaultsOpCodeHandle Handle for a buffer of DEFAULT opcodes. This 1026 is an optional parameter that may be NULL. 1027 1028 @retval NULL There is not enough space left in Buffer to add the opcode. 1029 @retval Other A pointer to the created opcode. 1030 1031 **/ 1032 UINT8 * 1033 EFIAPI 1034 HiiCreateTimeOpCode ( 1035 IN VOID *OpCodeHandle, 1036 IN EFI_QUESTION_ID QuestionId, 1037 IN EFI_VARSTORE_ID VarStoreId, OPTIONAL 1038 IN UINT16 VarOffset, OPTIONAL 1039 IN EFI_STRING_ID Prompt, 1040 IN EFI_STRING_ID Help, 1041 IN UINT8 QuestionFlags, 1042 IN UINT8 TimeFlags, 1043 IN VOID *DefaultsOpCodeHandle OPTIONAL 1044 ); 1045 1046 /** 1047 This function updates a form that has previously been registered with the HII 1048 Database. This function will perform at most one update operation. 1049 1050 The form to update is specified by Handle, FormSetGuid, and FormId. Binary 1051 comparisons of IFR opcodes are performed from the beginning of the form being 1052 updated until an IFR opcode is found that exactly matches the first IFR opcode 1053 specified by StartOpCodeHandle. The following rules are used to determine if 1054 an insert, replace, or delete operation is performed: 1055 1056 1) If no matches are found, then NULL is returned. 1057 2) If a match is found, and EndOpCodeHandle is NULL, then all of the IFR opcodes 1058 from StartOpCodeHandle except the first opcode are inserted immediately after 1059 the matching IFR opcode in the form to be updated. 1060 3) If a match is found, and EndOpCodeHandle is not NULL, then a search is made 1061 from the matching IFR opcode until an IFR opcode exactly matches the first 1062 IFR opcode specified by EndOpCodeHandle. If no match is found for the first 1063 IFR opcode specified by EndOpCodeHandle, then NULL is returned. If a match 1064 is found, then all of the IFR opcodes between the start match and the end 1065 match are deleted from the form being updated and all of the IFR opcodes 1066 from StartOpCodeHandle except the first opcode are inserted immediately after 1067 the matching start IFR opcode. If StartOpCcodeHandle only contains one 1068 IFR instruction, then the result of this operation will delete all of the IFR 1069 opcodes between the start end matches. 1070 1071 If HiiHandle is NULL, then ASSERT(). 1072 If StartOpCodeHandle is NULL, then ASSERT(). 1073 1074 @param[in] HiiHandle The HII Handle of the form to update. 1075 @param[in] FormSetGuid The Formset GUID of the form to update. This 1076 is an optional parameter that may be NULL. 1077 If it is NULL, all FormSet will be updated. 1078 @param[in] FormId The ID of the form to update. 1079 @param[in] StartOpCodeHandle An OpCode Handle that contains the set of IFR 1080 opcodes to be inserted or replaced in the form. 1081 The first IFR instruction in StartOpCodeHandle 1082 is used to find matching IFR opcode in the 1083 form. 1084 @param[in] EndOpCodeHandle An OpCcode Handle that contains the IFR opcode 1085 that marks the end of a replace operation in 1086 the form. This is an optional parameter that 1087 may be NULL. If it is NULL, then the IFR 1088 opcodes specified by StartOpCodeHandle are 1089 inserted into the form. 1090 1091 @retval EFI_OUT_OF_RESOURCES Not enough memory resources are allocated. 1092 @retval EFI_NOT_FOUND The following cases will return EFI_NOT_FOUND: 1093 1) The form specified by HiiHandle, FormSetGuid, 1094 and FormId could not be found in the HII Database. 1095 2) No IFR opcodes in the target form match the first 1096 IFR opcode in StartOpCodeHandle. 1097 3) EndOpCOde is not NULL, and no IFR opcodes in the 1098 target form following a matching start opcode match 1099 the first IFR opcode in EndOpCodeHandle. 1100 @retval EFI_SUCCESS The matched form is updated by StartOpcode. 1101 1102 **/ 1103 EFI_STATUS 1104 EFIAPI 1105 HiiUpdateForm ( 1106 IN EFI_HII_HANDLE HiiHandle, 1107 IN EFI_GUID *FormSetGuid, OPTIONAL 1108 IN EFI_FORM_ID FormId, 1109 IN VOID *StartOpCodeHandle, 1110 IN VOID *EndOpCodeHandle OPTIONAL 1111 ); 1112 1113 #endif 1114