1 /** @file 2 FormDiplay protocol to show Form 3 4 Copyright (c) 2013 - 2015, 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 359