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