MdeModulePkg/Include/Protocol/DisplayProtocol.h

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