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 353