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 #define FORM_DISPLAY_ENGINE_PROTOCOL_GUID  \
  19   { 0x9bbe29e9, 0xfda1, 0x41ec, { 0xad, 0x52, 0x45, 0x22, 0x13, 0x74, 0x2d, 0x2e } }
  20
  21 #define FORM_DISPLAY_ENGINE_STATEMENT_VERSION  0x10000
  22 #define FORM_DISPLAY_ENGINE_VERSION       0x10000
  23
  24 typedef struct _FORM_DISPLAY_ENGINE_PROTOCOL   FORM_DISPLAY_ENGINE_PROTOCOL;
  25
  26 typedef struct {
  27   UINT8               Type;       // HII Data Type
  28   UINT8               *Buffer;    // Buffer Data and Length if Type is EFI_IFR_TYPE_BUFFER or EFI_IFR_TYPE_STRING
  29   UINT16              BufferLen;
  30   EFI_IFR_TYPE_VALUE  Value;
  31 } EFI_HII_VALUE;
  32
  33 #define DISPLAY_QUESTION_OPTION_SIGNATURE  SIGNATURE_32 ('Q', 'O', 'P', 'T')
  34
  35 typedef struct {
  36   UINTN                  Signature;
  37   LIST_ENTRY             Link;
  38   EFI_IFR_ONE_OF_OPTION  OptionOpCode;   // OneOfOption Data
  39   EFI_IMAGE_ID           ImageId;        // Option ImageId and AnimationId
  40   EFI_ANIMATION_ID       AnimationId;
  41 } DISPLAY_QUESTION_OPTION;
  42
  43 #define DISPLAY_QUESTION_OPTION_FROM_LINK(a)  CR (a, DISPLAY_QUESTION_OPTION, Link, DISPLAY_QUESTION_OPTION_SIGNATURE)
  44
  45
  46 typedef struct _FORM_DISPLAY_ENGINE_STATEMENT FORM_DISPLAY_ENGINE_STATEMENT;
  47
  48 //
  49 // Attribute for Statement and Form
  50 //
  51 #define HII_DISPLAY_GRAYOUT          BIT0
  52 #define HII_DISPLAY_LOCK             BIT1
  53 #define HII_DISPLAY_READONLY         BIT2
  54 #define HII_DISPLAY_MODAL            BIT3
  55
  56 #define FORM_DISPLAY_ENGINE_FORM_SIGNATURE  SIGNATURE_32 ('F', 'F', 'R', 'M')
  57
  58 typedef struct {
  59   UINTN                         Signature;
  60   UINTN                         Version;                    // Version for future structure extension
  61   LIST_ENTRY                    StatementListHead;          // Statement List inside of Form
  62   EFI_GUID                      FormSetGuid;                // FormSet information
  63   EFI_HII_HANDLE                HiiHandle;                  // HiiHandle can be used to get String, Image or Animation
  64   UINT16                        FormId;                     // Form ID and Title.
  65   EFI_STRING_ID                 FormTitle;
  66   UINT32                        Attribute;                  // Form Attributes: Lock, Modal.
  67   BOOLEAN                       SettingChangedFlag;         // Flag to describe whether setting is changed or not.
  68   FORM_DISPLAY_ENGINE_STATEMENT *HighLightedStatement;      // Statement to be HighLighted
  69   EFI_GUID                      *FormRefreshEventGuid;      // EventGuid to notify Displayer that FormData is updated to be refreshed.
  70   LIST_ENTRY                    HotKeyListHead;             // Additional Hotkey registered by BrowserEx protocol.
  71   EFI_IMAGE_ID                  ImageId;                    // Form ImageId and AnimationId
  72   EFI_ANIMATION_ID              AnimationId;
  73 } FORM_DISPLAY_ENGINE_FORM;
  74
  75 #define FORM_DISPLAY_ENGINE_FORM_FROM_LINK(a)  CR (a, FORM_DISPLAY_ENGINE_FORM, Link, FORM_DISPLAY_ENGINE_FORM_SIGNATURE)
  76
  77 /**
  78   Perform value check for a question.
  79
  80   @param  Form       Form where Statement is in.
  81   @param  Statement  Value will check for it.
  82   @param  Value      New value will be checked.
  83
  84   @retval TRUE   Input Value is valid.
  85   @retval FALSE  Input Value is invalid.
  86 **/
  87 typedef
  88 BOOLEAN
  89 (EFIAPI *VALIDATE_QUESTION) (
  90   IN FORM_DISPLAY_ENGINE_FORM      *Form,
  91   IN FORM_DISPLAY_ENGINE_STATEMENT *Statement,
  92   IN EFI_HII_VALUE                 *Value
  93   );
  94
  95 /**
  96   Perform Password check.
  97   Passwork may be encrypted by driver that requires the specific check.
  98
  99   @param  Form             Form where Password Statement is in.
 100   @param  Statement        Password statement
 101   @param  PasswordString   Password string to be checked. It may be NULL.
 102
 103   @return Status     Status of Password check.
 104 **/
 105 typedef
 106 EFI_STATUS
 107 (EFIAPI *PASSWORD_CHECK) (
 108   IN FORM_DISPLAY_ENGINE_FORM      *Form,
 109   IN FORM_DISPLAY_ENGINE_STATEMENT *Statement,
 110   IN EFI_STRING                    *PasswordString  OPTIONAL
 111   );
 112
 113 #define FORM_DISPLAY_ENGINE_STATEMENT_SIGNATURE  SIGNATURE_32 ('F', 'S', 'T', 'A')
 114
 115 struct _FORM_DISPLAY_ENGINE_STATEMENT{
 116   UINTN                 Signature;
 117   UINTN                 Version;              // Version for future structure extension
 118   LIST_ENTRY            DisplayLink;          // link to all the statement which will show in the display form.
 119   EFI_IFR_OP_HEADER     *OpCode;              // Pointer to statement opcode.
 120                                               // for Guided Opcode. All buffers will be here if GUIDED opcode scope is set.
 121   EFI_HII_VALUE         CurrentValue;         // Question CurrentValue
 122   BOOLEAN               SettingChangedFlag;   // Flag to describe whether setting is changed or not.
 123                                               // Displayer may depend on it to show it with the different color.
 124   LIST_ENTRY            NestStatementList;    // nested Statement list inside of EFI_IFR_SUBTITLE
 125   LIST_ENTRY            OptionListHead;       // nested EFI_IFR_ONE_OF_OPTION list (QUESTION_OPTION)
 126   UINT32                Attribute;            // Statement attributes: GRAYOUT, LOCK and READONLY
 127   VALIDATE_QUESTION     ValidateQuestion;     // ValidateQuestion to do InconsistIf check
 128   EFI_STRING_ID         InConsistentStringId; // InConsistentString popup will be used when ValidateQuestion returns FASLE.
 129                                               // If this ID is zero, then Display can customize error message for the invalid value.
 130   PASSWORD_CHECK        PasswordCheck;        // Password additional check. It may be NULL when the additional check is not required.
 131   EFI_IMAGE_ID          ImageId;              // Statement ImageId and AnimationId
 132   EFI_ANIMATION_ID      AnimationId;
 133 };
 134
 135 #define FORM_DISPLAY_ENGINE_STATEMENT_FROM_LINK(a)  CR (a, FORM_DISPLAY_ENGINE_STATEMENT, DisplayLink, FORM_DISPLAY_ENGINE_STATEMENT_SIGNATURE)
 136
 137 typedef struct {
 138   UINTN                  Signature;
 139   LIST_ENTRY             Link;
 140   EFI_INPUT_KEY          KeyData;
 141   UINT32                 Action;        // Action is Discard, Default, Submit, Reset and Exit.
 142   UINT16                 DefaultId;
 143   EFI_STRING             HelpString;    // HotKey Help String
 144 } HOTKEY_INFO;
 145
 146 typedef struct {
 147   FORM_DISPLAY_ENGINE_STATEMENT  *SelectedStatement; // Selected Statement and InputValue
 148   EFI_HII_VALUE                  InputValue;
 149   UINT32                         Action;             // If SelectedStatement is NULL, Action will be used.
 150                                                      // Trig Action (Discard, Default, Submit, Reset and Exit)
 151   UINT16                         DefaultId;
 152 } USER_INPUT;
 153
 154 /**
 155   Display one form, and return user input.
 156
 157   @param FormData                Form Data to be shown.
 158   @param UserInputData           User input data.
 159
 160   @retval EFI_SUCCESS            Form Data is shown, and user input is got.
 161 **/
 162 typedef
 163 EFI_STATUS
 164 (EFIAPI *FORM_DISPLAY) (
 165   IN FORM_DISPLAY_ENGINE_FORM  *FormData,
 166   OUT USER_INPUT               *UserInputData
 167 );
 168
 169 /**
 170   Exit Display and Clear Screen to the original state.
 171
 172 **/
 173 typedef
 174 VOID
 175 (EFIAPI *EXIT_DISPLAY) (
 176   VOID
 177 );
 178
 179 /**
 180   Confirm how to handle the changed data.
 181
 182   @return Action of Submit, Discard and None
 183 **/
 184 typedef
 185 UINTN
 186 (EFIAPI *CONFIRM_DATA_CHANGE) (
 187   VOID
 188 );
 189
 190 struct _FORM_DISPLAY_ENGINE_PROTOCOL {
 191   FORM_DISPLAY        FormDisplay;
 192   EXIT_DISPLAY        ExitDisplay;
 193   CONFIRM_DATA_CHANGE ConfirmDataChange;
 194 };
 195
 196 extern EFI_GUID gEfiFormDisplayEngineProtocolGuid;
 197 #endif