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
  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_GRAYOUT          BIT0
 141 #define HII_DISPLAY_LOCK             BIT1
 142 #define HII_DISPLAY_READONLY         BIT2
 143 #define HII_DISPLAY_MODAL            BIT3
 144
 145 struct _FORM_DISPLAY_ENGINE_STATEMENT{
 146   UINTN                 Signature;
 147   //
 148   // Version for future structure extension
 149   //
 150   UINTN                 Version;
 151   //
 152   // link to all the statement which will show in the display form.
 153   //
 154   LIST_ENTRY            DisplayLink;
 155   //
 156   // Pointer to statement opcode.
 157   // for Guided Opcode. All buffers will be here if GUIDED opcode scope is set.
 158   //
 159   EFI_IFR_OP_HEADER     *OpCode;
 160   //
 161   // Question CurrentValue
 162   //
 163   EFI_HII_VALUE         CurrentValue;
 164   //
 165   // Flag to describe whether setting is changed or not.
 166   // Displayer may depend on it to show it with the different color.
 167   //
 168   BOOLEAN               SettingChangedFlag;
 169   //
 170   // nested Statement list inside of EFI_IFR_SUBTITLE
 171   //
 172   LIST_ENTRY            NestStatementList;
 173   //
 174   // nested EFI_IFR_ONE_OF_OPTION list (QUESTION_OPTION)
 175   //
 176   LIST_ENTRY            OptionListHead;
 177   //
 178   // Statement attributes: GRAYOUT, LOCK and READONLY
 179   //
 180   UINT32                Attribute;
 181
 182   //
 183   // ValidateQuestion to do InconsistIf check
 184   // It may be NULL if any value is valid.
 185   //
 186   VALIDATE_QUESTION     ValidateQuestion;
 187
 188   //
 189   // Password additional check. It may be NULL when the additional check is not required.
 190   //
 191   PASSWORD_CHECK        PasswordCheck;
 192
 193   //
 194   // Statement ImageId and AnimationId
 195   //
 196   EFI_IMAGE_ID          ImageId;
 197   EFI_ANIMATION_ID      AnimationId;
 198 };
 199
 200 #define FORM_DISPLAY_ENGINE_STATEMENT_FROM_LINK(a)  CR (a, FORM_DISPLAY_ENGINE_STATEMENT, DisplayLink, FORM_DISPLAY_ENGINE_STATEMENT_SIGNATURE)
 201
 202 #define BROWSER_HOT_KEY_SIGNATURE  SIGNATURE_32 ('B', 'H', 'K', 'S')
 203
 204 typedef struct {
 205   UINTN                 Signature;
 206   LIST_ENTRY            Link;
 207
 208   EFI_INPUT_KEY         *KeyData;
 209   //
 210   // Action is Discard, Default, Submit, Reset and Exit.
 211   //
 212   UINT32                 Action;
 213   UINT16                 DefaultId;
 214   //
 215   // HotKey Help String
 216   //
 217   EFI_STRING             HelpString;
 218 } BROWSER_HOT_KEY;
 219
 220 #define BROWSER_HOT_KEY_FROM_LINK(a)  CR (a, BROWSER_HOT_KEY, Link, BROWSER_HOT_KEY_SIGNATURE)
 221
 222 #define FORM_DISPLAY_ENGINE_FORM_SIGNATURE  SIGNATURE_32 ('F', 'F', 'R', 'M')
 223
 224 struct _FORM_DISPLAY_ENGINE_FORM {
 225   UINTN                Signature;
 226   //
 227   // Version for future structure extension
 228   //
 229   UINTN                Version;
 230   //
 231   // Statement List inside of Form
 232   //
 233   LIST_ENTRY            StatementListHead;
 234   //
 235   // Statement List outside of Form
 236   //
 237   LIST_ENTRY            StatementListOSF;
 238   //
 239   // The input screen dimenstions info.
 240   //
 241   EFI_SCREEN_DESCRIPTOR *ScreenDimensions;
 242   //
 243   // FormSet information
 244   //
 245   EFI_GUID             FormSetGuid;
 246   //
 247   // HiiHandle can be used to get String, Image or Animation
 248   //
 249   EFI_HII_HANDLE       HiiHandle;
 250
 251   //
 252   // Form ID and Title.
 253   //
 254   UINT16               FormId;
 255   EFI_STRING_ID        FormTitle;
 256   //
 257   // Form Attributes: Lock, Modal.
 258   //
 259   UINT32               Attribute;
 260   //
 261   // Flag to describe whether setting is changed or not.
 262   // Displayer depends on it to show ChangedFlag.
 263   //
 264   BOOLEAN              SettingChangedFlag;
 265
 266   //
 267   // Statement to be HighLighted
 268   //
 269   FORM_DISPLAY_ENGINE_STATEMENT *HighLightedStatement;
 270   //
 271   // Event to notify Displayer that FormData is updated to be refreshed.
 272   //
 273   EFI_EVENT              FormRefreshEvent;
 274   //
 275   // Additional Hotkey registered by BrowserEx protocol.
 276   //
 277   LIST_ENTRY             HotKeyListHead;
 278
 279   //
 280   // Form ImageId and AnimationId
 281   //
 282   EFI_IMAGE_ID         ImageId;
 283   EFI_ANIMATION_ID     AnimationId;
 284
 285   //
 286   // If Status is error, display needs to handle it.
 287   //
 288   UINT32               BrowserStatus;
 289   //
 290   // String for error status. It may be NULL.
 291   //
 292   EFI_STRING           ErrorString;
 293 };
 294
 295 #define FORM_DISPLAY_ENGINE_FORM_FROM_LINK(a)  CR (a, FORM_DISPLAY_ENGINE_FORM, Link, FORM_DISPLAY_ENGINE_FORM_SIGNATURE)
 296
 297 typedef struct {
 298   FORM_DISPLAY_ENGINE_STATEMENT  *SelectedStatement; // Selected Statement and InputValue
 299
 300   EFI_HII_VALUE                  InputValue;
 301
 302   UINT32                         Action;             // If SelectedStatement is NULL, Action will be used.
 303                                                      // Trig Action (Discard, Default, Submit, Reset and Exit)
 304   UINT16                         DefaultId;
 305 } USER_INPUT;
 306
 307 /**
 308   Display one form, and return user input.
 309
 310   @param FormData                Form Data to be shown.
 311   @param UserInputData           User input data.
 312
 313   @retval EFI_SUCCESS            Form Data is shown, and user input is got.
 314 **/
 315 typedef
 316 EFI_STATUS
 317 (EFIAPI *FORM_DISPLAY) (
 318   IN FORM_DISPLAY_ENGINE_FORM  *FormData,
 319   OUT USER_INPUT               *UserInputData
 320 );
 321
 322 /**
 323   Exit Display and Clear Screen to the original state.
 324
 325 **/
 326 typedef
 327 VOID
 328 (EFIAPI *EXIT_DISPLAY) (
 329   VOID
 330 );
 331
 332 /**
 333   Confirm how to handle the changed data.
 334
 335   @return Action of Submit, Discard and None
 336 **/
 337 typedef
 338 UINTN
 339 (EFIAPI *CONFIRM_DATA_CHANGE) (
 340   VOID
 341 );
 342
 343 typedef struct {
 344   FORM_DISPLAY        FormDisplay;
 345   EXIT_DISPLAY        ExitDisplay;
 346   CONFIRM_DATA_CHANGE ConfirmDataChange;
 347 } EDKII_FORM_DISPLAY_ENGINE_PROTOCOL;
 348
 349 extern EFI_GUID gEdkiiFormDisplayEngineProtocolGuid;
 350 #endif