MdeModulePkg/Include/Protocol/DisplayProtocol.h

   1 /** @file
   2   FormDiplay protocol to show Form
   3
   4 Copyright (c) 2013 - 2014, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials are licensed and made available under
   6 the terms and conditions of the BSD License that accompanies this distribution.
   7 The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php.
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __DISPLAY_PROTOCOL_H__
  16 #define __DISPLAY_PROTOCOL_H__
  17
  18 #include <Protocol/FormBrowser2.h>
  19
  20 #define EDKII_FORM_DISPLAY_ENGINE_PROTOCOL_GUID  \
  21   { 0x9bbe29e9, 0xfda1, 0x41ec, { 0xad, 0x52, 0x45, 0x22, 0x13, 0x74, 0x2d, 0x2e } }
  22
  23 //
  24 // Do nothing.
  25 //
  26 #define BROWSER_ACTION_NONE         BIT16
  27 //
  28 // ESC Exit
  29 //
  30 #define BROWSER_ACTION_FORM_EXIT    BIT17
  31
  32 #define BROWSER_SUCCESS                   0x0
  33 #define BROWSER_ERROR                     BIT31
  34 #define BROWSER_SUBMIT_FAIL               BROWSER_ERROR | 0x01
  35 #define BROWSER_NO_SUBMIT_IF              BROWSER_ERROR | 0x02
  36 #define BROWSER_FORM_NOT_FOUND            BROWSER_ERROR | 0x03
  37 #define BROWSER_FORM_SUPPRESS             BROWSER_ERROR | 0x04
  38 #define BROWSER_PROTOCOL_NOT_FOUND        BROWSER_ERROR | 0x05
  39 #define BROWSER_INCONSISTENT_IF           BROWSER_ERROR | 0x06
  40 #define BROWSER_WARNING_IF                BROWSER_ERROR | 0x07
  41 #define BROWSER_SUBMIT_FAIL_NO_SUBMIT_IF  BROWSER_ERROR | 0x08
  42
  43 #define FORM_DISPLAY_ENGINE_STATEMENT_VERSION_1  0x10000
  44 #define FORM_DISPLAY_ENGINE_VERSION_1            0x10000
  45
  46 typedef struct {
  47   //
  48   // HII Data Type
  49   //
  50   UINT8               Type;
  51   //
  52   // Buffer Data and Length if Type is EFI_IFR_TYPE_BUFFER or EFI_IFR_TYPE_STRING
  53   //
  54   UINT8               *Buffer;
  55   UINT16              BufferLen;
  56   EFI_IFR_TYPE_VALUE  Value;
  57 } EFI_HII_VALUE;
  58
  59 #define DISPLAY_QUESTION_OPTION_SIGNATURE  SIGNATURE_32 ('Q', 'O', 'P', 'T')
  60
  61 typedef struct {
  62   UINTN                  Signature;
  63   LIST_ENTRY             Link;
  64   //
  65   // OneOfOption Data
  66   //
  67   EFI_IFR_ONE_OF_OPTION  *OptionOpCode;
  68   //
  69   // Option ImageId and AnimationId
  70   //
  71   EFI_IMAGE_ID           ImageId;
  72   EFI_ANIMATION_ID       AnimationId;
  73 } DISPLAY_QUESTION_OPTION;
  74
  75 #define DISPLAY_QUESTION_OPTION_FROM_LINK(a)  CR (a, DISPLAY_QUESTION_OPTION, Link, DISPLAY_QUESTION_OPTION_SIGNATURE)
  76
  77 typedef struct _FORM_DISPLAY_ENGINE_STATEMENT FORM_DISPLAY_ENGINE_STATEMENT;
  78 typedef struct _FORM_DISPLAY_ENGINE_FORM      FORM_DISPLAY_ENGINE_FORM;
  79
  80 #define STATEMENT_VALID             0x0
  81 #define STATEMENT_INVALID           BIT31
  82
  83 #define INCOSISTENT_IF_TRUE         STATEMENT_INVALID | 0x01
  84 #define WARNING_IF_TRUE             STATEMENT_INVALID | 0x02
  85 #define STRING_TOO_LONG             STATEMENT_INVALID | 0x03
  86 // ... to be extended.
  87
  88 typedef struct {
  89   //
  90   // StringId for INCONSITENT_IF or WARNING_IF
  91   //
  92   EFI_STRING_ID  StringId;
  93   //
  94   // TimeOut for WARNING_IF
  95   //
  96   UINT8          TimeOut;
  97 } STATEMENT_ERROR_INFO;
  98
  99 /**
 100   Perform value check for a question.
 101
 102   @param  Form       Form where Statement is in.
 103   @param  Statement  Value will check for it.
 104   @param  Value      New value will be checked.
 105
 106   @retval Status     Value Status
 107
 108 **/
 109 typedef
 110 UINT32
 111 (EFIAPI *VALIDATE_QUESTION) (
 112   IN FORM_DISPLAY_ENGINE_FORM      *Form,
 113   IN FORM_DISPLAY_ENGINE_STATEMENT *Statement,
 114   IN EFI_HII_VALUE                 *Value,
 115   OUT STATEMENT_ERROR_INFO         *ErrorInfo
 116   );
 117
 118 /**
 119   Perform Password check.
 120   Passwork may be encrypted by driver that requires the specific check.
 121
 122   @param  Form             Form where Password Statement is in.
 123   @param  Statement        Password statement
 124   @param  PasswordString   Password string to be checked. It may be NULL.
 125                            NULL means to restore password.
 126                            "" string can be used to checked whether old password does exist.
 127
 128   @return Status     Status of Password check.
 129 **/
 130 typedef
 131 EFI_STATUS
 132 (EFIAPI *PASSWORD_CHECK) (
 133   IN FORM_DISPLAY_ENGINE_FORM      *Form,
 134   IN FORM_DISPLAY_ENGINE_STATEMENT *Statement,
 135   IN EFI_STRING                    PasswordString  OPTIONAL
 136   );
 137
 138 #define FORM_DISPLAY_ENGINE_STATEMENT_SIGNATURE  SIGNATURE_32 ('F', 'S', 'T', 'A')
 139
 140 //
 141 // Attribute for Statement and Form
 142 //
 143 #define HII_DISPLAY_NONE             0
 144 #define HII_DISPLAY_GRAYOUT          BIT0
 145 #define HII_DISPLAY_LOCK             BIT1
 146 #define HII_DISPLAY_READONLY         BIT2
 147 #define HII_DISPLAY_MODAL            BIT3
 148 #define HII_DISPLAY_SUPPRESS         BIT4
 149
 150 struct _FORM_DISPLAY_ENGINE_STATEMENT{
 151   UINTN                 Signature;
 152   //
 153   // Version for future structure extension
 154   //
 155   UINTN                 Version;
 156   //
 157   // link to all the statement which will show in the display form.
 158   //
 159   LIST_ENTRY            DisplayLink;
 160   //
 161   // Pointer to statement opcode.
 162   // for Guided Opcode. All buffers will be here if GUIDED opcode scope is set.
 163   //
 164   EFI_IFR_OP_HEADER     *OpCode;
 165   //
 166   // Question CurrentValue
 167   //
 168   EFI_HII_VALUE         CurrentValue;
 169   //
 170   // Flag to describe whether setting is changed or not.
 171   // Displayer may depend on it to show it with the different color.
 172   //
 173   BOOLEAN               SettingChangedFlag;
 174   //
 175   // nested Statement list inside of EFI_IFR_SUBTITLE
 176   //
 177   LIST_ENTRY            NestStatementList;
 178   //
 179   // nested EFI_IFR_ONE_OF_OPTION list (QUESTION_OPTION)
 180   //
 181   LIST_ENTRY            OptionListHead;
 182   //
 183   // Statement attributes: GRAYOUT, LOCK and READONLY
 184   //
 185   UINT32                Attribute;
 186
 187   //
 188   // ValidateQuestion to do InconsistIf check
 189   // It may be NULL if any value is valid.
 190   //
 191   VALIDATE_QUESTION     ValidateQuestion;
 192
 193   //
 194   // Password additional check. It may be NULL when the additional check is not required.
 195   //
 196   PASSWORD_CHECK        PasswordCheck;
 197
 198   //
 199   // Statement ImageId and AnimationId
 200   //
 201   EFI_IMAGE_ID          ImageId;
 202   EFI_ANIMATION_ID      AnimationId;
 203 };
 204
 205 #define FORM_DISPLAY_ENGINE_STATEMENT_FROM_LINK(a)  CR (a, FORM_DISPLAY_ENGINE_STATEMENT, DisplayLink, FORM_DISPLAY_ENGINE_STATEMENT_SIGNATURE)
 206
 207 #define BROWSER_HOT_KEY_SIGNATURE  SIGNATURE_32 ('B', 'H', 'K', 'S')
 208
 209 typedef struct {
 210   UINTN                 Signature;
 211   LIST_ENTRY            Link;
 212
 213   EFI_INPUT_KEY         *KeyData;
 214   //
 215   // Action is Discard, Default, Submit, Reset and Exit.
 216   //
 217   UINT32                 Action;
 218   UINT16                 DefaultId;
 219   //
 220   // HotKey Help String
 221   //
 222   EFI_STRING             HelpString;
 223 } BROWSER_HOT_KEY;
 224
 225 #define BROWSER_HOT_KEY_FROM_LINK(a)  CR (a, BROWSER_HOT_KEY, Link, BROWSER_HOT_KEY_SIGNATURE)
 226
 227 #define FORM_DISPLAY_ENGINE_FORM_SIGNATURE  SIGNATURE_32 ('F', 'F', 'R', 'M')
 228
 229 struct _FORM_DISPLAY_ENGINE_FORM {
 230   UINTN                Signature;
 231   //
 232   // Version for future structure extension
 233   //
 234   UINTN                Version;
 235   //
 236   // Statement List inside of Form
 237   //
 238   LIST_ENTRY            StatementListHead;
 239   //
 240   // Statement List outside of Form
 241   //
 242   LIST_ENTRY            StatementListOSF;
 243   //
 244   // The input screen dimenstions info.
 245   //
 246   EFI_SCREEN_DESCRIPTOR *ScreenDimensions;
 247   //
 248   // FormSet information
 249   //
 250   EFI_GUID             FormSetGuid;
 251   //
 252   // HiiHandle can be used to get String, Image or Animation
 253   //
 254   EFI_HII_HANDLE       HiiHandle;
 255
 256   //
 257   // Form ID and Title.
 258   //
 259   UINT16               FormId;
 260   EFI_STRING_ID        FormTitle;
 261   //
 262   // Form Attributes: Lock, Modal.
 263   //
 264   UINT32               Attribute;
 265   //
 266   // Flag to describe whether setting is changed or not.
 267   // Displayer depends on it to show ChangedFlag.
 268   //
 269   BOOLEAN              SettingChangedFlag;
 270
 271   //
 272   // Statement to be HighLighted
 273   //
 274   FORM_DISPLAY_ENGINE_STATEMENT *HighLightedStatement;
 275   //
 276   // Event to notify Displayer that FormData is updated to be refreshed.
 277   //
 278   EFI_EVENT              FormRefreshEvent;
 279   //
 280   // Additional Hotkey registered by BrowserEx protocol.
 281   //
 282   LIST_ENTRY             HotKeyListHead;
 283
 284   //
 285   // Form ImageId and AnimationId
 286   //
 287   EFI_IMAGE_ID         ImageId;
 288   EFI_ANIMATION_ID     AnimationId;
 289
 290   //
 291   // If Status is error, display needs to handle it.
 292   //
 293   UINT32               BrowserStatus;
 294   //
 295   // String for error status. It may be NULL.
 296   //
 297   EFI_STRING           ErrorString;
 298 };
 299
 300 #define FORM_DISPLAY_ENGINE_FORM_FROM_LINK(a)  CR (a, FORM_DISPLAY_ENGINE_FORM, Link, FORM_DISPLAY_ENGINE_FORM_SIGNATURE)
 301
 302 typedef struct {
 303   FORM_DISPLAY_ENGINE_STATEMENT  *SelectedStatement; // Selected Statement and InputValue
 304
 305   EFI_HII_VALUE                  InputValue;
 306
 307   UINT32                         Action;             // If SelectedStatement is NULL, Action will be used.
 308                                                      // Trig Action (Discard, Default, Submit, Reset and Exit)
 309   UINT16                         DefaultId;
 310 } USER_INPUT;
 311
 312 /**
 313   Display one form, and return user input.
 314
 315   @param FormData                Form Data to be shown.
 316   @param UserInputData           User input data.
 317
 318   @retval EFI_SUCCESS            Form Data is shown, and user input is got.
 319 **/
 320 typedef
 321 EFI_STATUS
 322 (EFIAPI *FORM_DISPLAY) (
 323   IN FORM_DISPLAY_ENGINE_FORM  *FormData,
 324   OUT USER_INPUT               *UserInputData
 325 );
 326
 327 /**
 328   Exit Display and Clear Screen to the original state.
 329
 330 **/
 331 typedef
 332 VOID
 333 (EFIAPI *EXIT_DISPLAY) (
 334   VOID
 335 );
 336
 337 /**
 338   Confirm how to handle the changed data.
 339
 340   @return Action of Submit, Discard and None
 341 **/
 342 typedef
 343 UINTN
 344 (EFIAPI *CONFIRM_DATA_CHANGE) (
 345   VOID
 346 );
 347
 348 typedef struct {
 349   FORM_DISPLAY        FormDisplay;
 350   EXIT_DISPLAY        ExitDisplay;
 351   CONFIRM_DATA_CHANGE ConfirmDataChange;
 352 } EDKII_FORM_DISPLAY_ENGINE_PROTOCOL;
 353
 354 extern EFI_GUID gEdkiiFormDisplayEngineProtocolGuid;
 355 #endif