MdeModulePkg/Include/Protocol/DisplayProtocol.h

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