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