MdeModulePkg/Include/Protocol/FormBrowserEx.h

   1 /** @file
   2   Extension Form Browser Protocol provides the services that can be used to
   3   register the different hot keys for the standard Browser actions described in UEFI specification.
   4
   5 Copyright (c) 2011 - 2018, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials are licensed and made available under
   7 the terms and conditions of the BSD License that accompanies this distribution.
   8 The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php.
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef __FORM_BROWSER_EXTENSION_H__
  17 #define __FORM_BROWSER_EXTENSION_H__
  18
  19 #define FORM_BROWSER_EXTENSION_PROTOCOL_GUID  \
  20   { 0x1f73b18d, 0x4630, 0x43c1, { 0xa1, 0xde, 0x6f, 0x80, 0x85, 0x5d, 0x7d, 0xa4 } }
  21
  22 typedef struct _EDKII_FORM_BROWSER_EXTENSION_PROTOCOL   EDKII_FORM_BROWSER_EXTENSION_PROTOCOL;
  23
  24 //
  25 // To be compatible, keep EFI_FORM_BROWSER_EXTENSION_PROTOCOL definition
  26 //
  27 typedef EDKII_FORM_BROWSER_EXTENSION_PROTOCOL   EFI_FORM_BROWSER_EXTENSION_PROTOCOL;
  28
  29 //
  30 // Return value of SAVE_REMINDER() that describes whether the changed data is saved or discarded.
  31 //
  32 #define BROWSER_NO_CHANGES          0
  33 #define BROWSER_SAVE_CHANGES        1
  34 #define BROWSER_DISCARD_CHANGES     2
  35 #define BROWSER_KEEP_CURRENT        3
  36
  37 //
  38 // Browser actions. They can be cominbed together.
  39 // If more than one actions are specified, the action with low bit will be executed first.
  40 //
  41 #define BROWSER_ACTION_UNREGISTER   0
  42 #define BROWSER_ACTION_DISCARD      BIT0
  43 #define BROWSER_ACTION_DEFAULT      BIT1
  44 #define BROWSER_ACTION_SUBMIT       BIT2
  45 #define BROWSER_ACTION_RESET        BIT3
  46 #define BROWSER_ACTION_EXIT         BIT4
  47 #define BROWSER_ACTION_GOTO         BIT5
  48
  49 //
  50 // Scope for Browser action. It may be Form, FormSet or System level.
  51 //
  52 typedef enum {
  53   FormLevel,
  54   FormSetLevel,
  55   SystemLevel,
  56   MaxLevel
  57 } BROWSER_SETTING_SCOPE;
  58
  59 /**
  60   Configure what scope the hot key will impact.
  61   All hot keys have the same scope. The mixed hot keys with the different level are not supported.
  62   If no scope is set, the default scope will be FormSet level.
  63   After all registered hot keys are removed, previous Scope can reset to another level.
  64
  65   @param[in] Scope               Scope level to be set.
  66
  67   @retval EFI_SUCCESS            Scope is set correctly.
  68   @retval EFI_INVALID_PARAMETER  Scope is not the valid value specified in BROWSER_SETTING_SCOPE.
  69   @retval EFI_UNSPPORTED         Scope level is different from current one that the registered hot keys have.
  70
  71 **/
  72 typedef
  73 EFI_STATUS
  74 (EFIAPI *SET_SCOPE) (
  75   IN BROWSER_SETTING_SCOPE Scope
  76   );
  77
  78 /**
  79   Register the hot key with its browser action, or unregistered the hot key.
  80   If the action value is zero, the hot key will be unregistered if it has been registered.
  81   If the same hot key has been registered, the new action and help string will override the previous ones.
  82
  83   @param[in] KeyData     A pointer to a buffer that describes the keystroke
  84                          information for the hot key. Its type is EFI_INPUT_KEY to
  85                          be supported by all ConsoleIn devices.
  86   @param[in] Action      Action value that describes what action will be trigged when the hot key is pressed.
  87   @param[in] DefaultId   Specifies the type of defaults to retrieve, which is only for DEFAULT action.
  88   @param[in] HelpString  Help string that describes the hot key information.
  89                          Its value may be NULL for the unregistered hot key.
  90
  91   @retval EFI_SUCCESS            Hot key is registered or unregistered.
  92   @retval EFI_INVALID_PARAMETER  KeyData is NULL.
  93 **/
  94 typedef
  95 EFI_STATUS
  96 (EFIAPI *REGISTER_HOT_KEY) (
  97   IN EFI_INPUT_KEY *KeyData,
  98   IN UINT32        Action,
  99   IN UINT16        DefaultId,
 100   IN EFI_STRING    HelpString OPTIONAL
 101   );
 102
 103 /**
 104   This handler is responsbile for the left things on normal boot after all UI forms are closed.
 105   For example, it can continue to boot the first boot option.
 106
 107   It will be used only when EXIT action is trigged as system level.
 108 **/
 109 typedef
 110 VOID
 111 (EFIAPI *EXIT_HANDLER) (
 112   VOID
 113   );
 114
 115 /**
 116   Register Exit handler function.
 117   When more than one handler function is registered, the latter one will override the previous one.
 118   When NULL handler is specified, the previous Exit handler will be unregistered.
 119
 120   @param[in] Handler      Pointer to handler function.
 121
 122 **/
 123 typedef
 124 VOID
 125 (EFIAPI *REGISTER_EXIT_HANDLER) (
 126   IN EXIT_HANDLER Handler
 127   );
 128
 129 /**
 130   Create reminder to let user to choose save or discard the changed browser data.
 131   Caller can use it to actively check the changed browser data.
 132
 133   @retval BROWSER_NO_CHANGES       No browser data is changed.
 134   @retval BROWSER_SAVE_CHANGES     The changed browser data is saved.
 135   @retval BROWSER_DISCARD_CHANGES  The changed browser data is discard.
 136   @retval BROWSER_KEEP_CURRENT     Browser keep current changes.
 137
 138 **/
 139 typedef
 140 UINT32
 141 (EFIAPI *SAVE_REMINDER)(
 142   VOID
 143   );
 144
 145 struct _EDKII_FORM_BROWSER_EXTENSION_PROTOCOL {
 146   SET_SCOPE              SetScope;
 147   REGISTER_HOT_KEY       RegisterHotKey;
 148   REGISTER_EXIT_HANDLER  RegiserExitHandler;
 149   SAVE_REMINDER          SaveReminder;
 150 };
 151
 152 extern EFI_GUID gEfiFormBrowserExProtocolGuid;
 153 extern EFI_GUID gEdkiiFormBrowserExProtocolGuid;
 154
 155 #endif
 156