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