MdeModulePkg/Include/Protocol/DisplayProtocol.h

/** @file
  FormDiplay protocol to show Form

Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
SPDX-License-Identifier: BSD-2-Clause-Patent

**/

#ifndef __DISPLAY_PROTOCOL_H__
#define __DISPLAY_PROTOCOL_H__

#include <Protocol/FormBrowser2.h>

#define EDKII_FORM_DISPLAY_ENGINE_PROTOCOL_GUID  \
  { 0x9bbe29e9, 0xfda1, 0x41ec, { 0xad, 0x52, 0x45, 0x22, 0x13, 0x74, 0x2d, 0x2e } }

//
// Do nothing.
//
#define BROWSER_ACTION_NONE  BIT16
//
// ESC Exit
//
#define BROWSER_ACTION_FORM_EXIT  BIT17

#define BROWSER_SUCCESS                   0x0
#define BROWSER_ERROR                     BIT31
#define BROWSER_SUBMIT_FAIL               BROWSER_ERROR | 0x01
#define BROWSER_NO_SUBMIT_IF              BROWSER_ERROR | 0x02
#define BROWSER_FORM_NOT_FOUND            BROWSER_ERROR | 0x03
#define BROWSER_FORM_SUPPRESS             BROWSER_ERROR | 0x04
#define BROWSER_PROTOCOL_NOT_FOUND        BROWSER_ERROR | 0x05
#define BROWSER_INCONSISTENT_IF           BROWSER_ERROR | 0x06
#define BROWSER_WARNING_IF                BROWSER_ERROR | 0x07
#define BROWSER_SUBMIT_FAIL_NO_SUBMIT_IF  BROWSER_ERROR | 0x08
#define BROWSER_RECONNECT_REQUIRED        BROWSER_ERROR | 0x09
#define BROWSER_RECONNECT_FAIL            BROWSER_ERROR | 0x0A
#define BROWSER_RECONNECT_SAVE_CHANGES    BROWSER_ERROR | 0x0B

#define FORM_DISPLAY_ENGINE_STATEMENT_VERSION_1  0x10000
#define FORM_DISPLAY_ENGINE_VERSION_1            0x10000

typedef struct {
  //
  // HII Data Type
  //
  UINT8                 Type;
  //
  // Buffer Data and Length if Type is EFI_IFR_TYPE_BUFFER or EFI_IFR_TYPE_STRING
  //
  UINT8                 *Buffer;
  UINT16                BufferLen;
  EFI_IFR_TYPE_VALUE    Value;
} EFI_HII_VALUE;

#define DISPLAY_QUESTION_OPTION_SIGNATURE  SIGNATURE_32 ('Q', 'O', 'P', 'T')

typedef struct {
  UINTN                    Signature;
  LIST_ENTRY               Link;
  //
  // OneOfOption Data
  //
  EFI_IFR_ONE_OF_OPTION    *OptionOpCode;
  //
  // Option ImageId and AnimationId
  //
  EFI_IMAGE_ID             ImageId;
  EFI_ANIMATION_ID         AnimationId;
} DISPLAY_QUESTION_OPTION;

#define DISPLAY_QUESTION_OPTION_FROM_LINK(a)  CR (a, DISPLAY_QUESTION_OPTION, Link, DISPLAY_QUESTION_OPTION_SIGNATURE)

typedef struct _FORM_DISPLAY_ENGINE_STATEMENT  FORM_DISPLAY_ENGINE_STATEMENT;
typedef struct _FORM_DISPLAY_ENGINE_FORM       FORM_DISPLAY_ENGINE_FORM;

#define STATEMENT_VALID    0x0
#define STATEMENT_INVALID  BIT31

#define INCOSISTENT_IF_TRUE  STATEMENT_INVALID | 0x01
#define WARNING_IF_TRUE      STATEMENT_INVALID | 0x02
#define STRING_TOO_LONG      STATEMENT_INVALID | 0x03
// ... to be extended.

typedef struct {
  //
  // StringId for INCONSITENT_IF or WARNING_IF
  //
  EFI_STRING_ID    StringId;
  //
  // TimeOut for WARNING_IF
  //
  UINT8            TimeOut;
} STATEMENT_ERROR_INFO;

/**
  Perform value check for a question.

  @param  Form       Form where Statement is in.
  @param  Statement  Value will check for it.
  @param  Value      New value will be checked.

  @retval Status     Value Status

**/
typedef
UINT32
(EFIAPI *VALIDATE_QUESTION)(
  IN FORM_DISPLAY_ENGINE_FORM      *Form,
  IN FORM_DISPLAY_ENGINE_STATEMENT *Statement,
  IN EFI_HII_VALUE                 *Value,
  OUT STATEMENT_ERROR_INFO         *ErrorInfo
  );

/**
  Perform Password check.
  Passwork may be encrypted by driver that requires the specific check.

  @param  Form             Form where Password Statement is in.
  @param  Statement        Password statement
  @param  PasswordString   Password string to be checked. It may be NULL.
                           NULL means to restore password.
                           "" string can be used to checked whether old password does exist.

  @return Status     Status of Password check.
**/
typedef
EFI_STATUS
(EFIAPI *PASSWORD_CHECK)(
  IN FORM_DISPLAY_ENGINE_FORM      *Form,
  IN FORM_DISPLAY_ENGINE_STATEMENT *Statement,
  IN EFI_STRING                    PasswordString  OPTIONAL
  );

#define FORM_DISPLAY_ENGINE_STATEMENT_SIGNATURE  SIGNATURE_32 ('F', 'S', 'T', 'A')

//
// Attribute for Statement and Form
//
#define HII_DISPLAY_NONE      0
#define HII_DISPLAY_GRAYOUT   BIT0
#define HII_DISPLAY_LOCK      BIT1
#define HII_DISPLAY_READONLY  BIT2
#define HII_DISPLAY_MODAL     BIT3
#define HII_DISPLAY_SUPPRESS  BIT4

struct _FORM_DISPLAY_ENGINE_STATEMENT {
  UINTN                Signature;
  //
  // Version for future structure extension
  //
  UINTN                Version;
  //
  // link to all the statement which will show in the display form.
  //
  LIST_ENTRY           DisplayLink;
  //
  // Pointer to statement opcode.
  // for Guided Opcode. All buffers will be here if GUIDED opcode scope is set.
  //
  EFI_IFR_OP_HEADER    *OpCode;
  //
  // Question CurrentValue
  //
  EFI_HII_VALUE        CurrentValue;
  //
  // Flag to describe whether setting is changed or not.
  // Displayer may depend on it to show it with the different color.
  //
  BOOLEAN              SettingChangedFlag;
  //
  // nested Statement list inside of EFI_IFR_SUBTITLE
  //
  LIST_ENTRY           NestStatementList;
  //
  // nested EFI_IFR_ONE_OF_OPTION list (QUESTION_OPTION)
  //
  LIST_ENTRY           OptionListHead;
  //
  // Statement attributes: GRAYOUT, LOCK and READONLY
  //
  UINT32               Attribute;

  //
  // ValidateQuestion to do InconsistIf check
  // It may be NULL if any value is valid.
  //
  VALIDATE_QUESTION    ValidateQuestion;

  //
  // Password additional check. It may be NULL when the additional check is not required.
  //
  PASSWORD_CHECK       PasswordCheck;

  //
  // Statement ImageId and AnimationId
  //
  EFI_IMAGE_ID         ImageId;
  EFI_ANIMATION_ID     AnimationId;
};

#define FORM_DISPLAY_ENGINE_STATEMENT_FROM_LINK(a)  CR (a, FORM_DISPLAY_ENGINE_STATEMENT, DisplayLink, FORM_DISPLAY_ENGINE_STATEMENT_SIGNATURE)

#define BROWSER_HOT_KEY_SIGNATURE  SIGNATURE_32 ('B', 'H', 'K', 'S')

typedef struct {
  UINTN            Signature;
  LIST_ENTRY       Link;

  EFI_INPUT_KEY    *KeyData;
  //
  // Action is Discard, Default, Submit, Reset and Exit.
  //
  UINT32           Action;
  UINT16           DefaultId;
  //
  // HotKey Help String
  //
  EFI_STRING       HelpString;
} BROWSER_HOT_KEY;

#define BROWSER_HOT_KEY_FROM_LINK(a)  CR (a, BROWSER_HOT_KEY, Link, BROWSER_HOT_KEY_SIGNATURE)

#define FORM_DISPLAY_ENGINE_FORM_SIGNATURE  SIGNATURE_32 ('F', 'F', 'R', 'M')

struct _FORM_DISPLAY_ENGINE_FORM {
  UINTN                            Signature;
  //
  // Version for future structure extension
  //
  UINTN                            Version;
  //
  // Statement List inside of Form
  //
  LIST_ENTRY                       StatementListHead;
  //
  // Statement List outside of Form
  //
  LIST_ENTRY                       StatementListOSF;
  //
  // The input screen dimenstions info.
  //
  EFI_SCREEN_DESCRIPTOR            *ScreenDimensions;
  //
  // FormSet information
  //
  EFI_GUID                         FormSetGuid;
  //
  // HiiHandle can be used to get String, Image or Animation
  //
  EFI_HII_HANDLE                   HiiHandle;

  //
  // Form ID and Title.
  //
  UINT16                           FormId;
  EFI_STRING_ID                    FormTitle;
  //
  // Form Attributes: Lock, Modal.
  //
  UINT32                           Attribute;
  //
  // Flag to describe whether setting is changed or not.
  // Displayer depends on it to show ChangedFlag.
  //
  BOOLEAN                          SettingChangedFlag;

  //
  // Statement to be HighLighted
  //
  FORM_DISPLAY_ENGINE_STATEMENT    *HighLightedStatement;
  //
  // Event to notify Displayer that FormData is updated to be refreshed.
  //
  EFI_EVENT                        FormRefreshEvent;
  //
  // Additional Hotkey registered by BrowserEx protocol.
  //
  LIST_ENTRY                       HotKeyListHead;

  //
  // Form ImageId and AnimationId
  //
  EFI_IMAGE_ID                     ImageId;
  EFI_ANIMATION_ID                 AnimationId;

  //
  // If Status is error, display needs to handle it.
  //
  UINT32                           BrowserStatus;
  //
  // String for error status. It may be NULL.
  //
  EFI_STRING                       ErrorString;
};

#define FORM_DISPLAY_ENGINE_FORM_FROM_LINK(a)  CR (a, FORM_DISPLAY_ENGINE_FORM, Link, FORM_DISPLAY_ENGINE_FORM_SIGNATURE)

typedef struct {
  FORM_DISPLAY_ENGINE_STATEMENT    *SelectedStatement; // Selected Statement and InputValue

  EFI_HII_VALUE                    InputValue;

  UINT32                           Action;           // If SelectedStatement is NULL, Action will be used.
                                                     // Trig Action (Discard, Default, Submit, Reset and Exit)
  UINT16                           DefaultId;
} USER_INPUT;

/**
  Display one form, and return user input.

  @param FormData                Form Data to be shown.
  @param UserInputData           User input data.

  @retval EFI_SUCCESS            Form Data is shown, and user input is got.
**/
typedef
EFI_STATUS
(EFIAPI *FORM_DISPLAY)(
  IN FORM_DISPLAY_ENGINE_FORM  *FormData,
  OUT USER_INPUT               *UserInputData
  );

/**
  Exit Display and Clear Screen to the original state.

**/
typedef
VOID
(EFIAPI *EXIT_DISPLAY)(
  VOID
  );

/**
  Confirm how to handle the changed data.

  @return Action of Submit, Discard and None
**/
typedef
UINTN
(EFIAPI *CONFIRM_DATA_CHANGE)(
  VOID
  );

typedef struct {
  FORM_DISPLAY           FormDisplay;
  EXIT_DISPLAY           ExitDisplay;
  CONFIRM_DATA_CHANGE    ConfirmDataChange;
} EDKII_FORM_DISPLAY_ENGINE_PROTOCOL;

extern EFI_GUID  gEdkiiFormDisplayEngineProtocolGuid;
#endif