Subrata Banik | 20fe24b | 2021-12-09 02:46:38 +0530 | [diff] [blame] | 1 | /** @file |
| 2 | |
| 3 | The EFI HII results processing protocol invokes this type of protocol |
| 4 | when it needs to forward results to a driver's configuration handler. |
| 5 | This protocol is published by drivers providing and requesting |
| 6 | configuration data from HII. It may only be invoked by HII. |
| 7 | |
| 8 | Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> |
| 9 | SPDX-License-Identifier: BSD-2-Clause-Patent |
| 10 | |
| 11 | @par Revision Reference: |
| 12 | This Protocol was introduced in UEFI Specification 2.1. |
| 13 | |
| 14 | **/ |
| 15 | |
| 16 | |
| 17 | #ifndef __EFI_HII_CONFIG_ACCESS_H__ |
| 18 | #define __EFI_HII_CONFIG_ACCESS_H__ |
| 19 | |
| 20 | #include <Protocol/FormBrowser2.h> |
| 21 | |
| 22 | #define EFI_HII_CONFIG_ACCESS_PROTOCOL_GUID \ |
| 23 | { 0x330d4706, 0xf2a0, 0x4e4f, { 0xa3, 0x69, 0xb6, 0x6f, 0xa8, 0xd5, 0x43, 0x85 } } |
| 24 | |
| 25 | typedef struct _EFI_HII_CONFIG_ACCESS_PROTOCOL EFI_HII_CONFIG_ACCESS_PROTOCOL; |
| 26 | |
| 27 | typedef UINTN EFI_BROWSER_ACTION; |
| 28 | |
| 29 | #define EFI_BROWSER_ACTION_CHANGING 0 |
| 30 | #define EFI_BROWSER_ACTION_CHANGED 1 |
| 31 | #define EFI_BROWSER_ACTION_RETRIEVE 2 |
| 32 | #define EFI_BROWSER_ACTION_FORM_OPEN 3 |
| 33 | #define EFI_BROWSER_ACTION_FORM_CLOSE 4 |
| 34 | #define EFI_BROWSER_ACTION_SUBMITTED 5 |
| 35 | #define EFI_BROWSER_ACTION_DEFAULT_STANDARD 0x1000 |
| 36 | #define EFI_BROWSER_ACTION_DEFAULT_MANUFACTURING 0x1001 |
| 37 | #define EFI_BROWSER_ACTION_DEFAULT_SAFE 0x1002 |
| 38 | #define EFI_BROWSER_ACTION_DEFAULT_PLATFORM 0x2000 |
| 39 | #define EFI_BROWSER_ACTION_DEFAULT_HARDWARE 0x3000 |
| 40 | #define EFI_BROWSER_ACTION_DEFAULT_FIRMWARE 0x4000 |
| 41 | |
| 42 | /** |
| 43 | |
| 44 | This function allows the caller to request the current |
| 45 | configuration for one or more named elements. The resulting |
| 46 | string is in <ConfigAltResp> format. Any and all alternative |
| 47 | configuration strings shall also be appended to the end of the |
| 48 | current configuration string. If they are, they must appear |
| 49 | after the current configuration. They must contain the same |
| 50 | routing (GUID, NAME, PATH) as the current configuration string. |
| 51 | They must have an additional description indicating the type of |
| 52 | alternative configuration the string represents, |
| 53 | "ALTCFG=<StringToken>". That <StringToken> (when |
| 54 | converted from Hex UNICODE to binary) is a reference to a |
| 55 | string in the associated string pack. |
| 56 | |
| 57 | @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. |
| 58 | |
| 59 | @param Request A null-terminated Unicode string in |
| 60 | <ConfigRequest> format. Note that this |
| 61 | includes the routing information as well as |
| 62 | the configurable name / value pairs. It is |
| 63 | invalid for this string to be in |
| 64 | <MultiConfigRequest> format. |
| 65 | If a NULL is passed in for the Request field, |
| 66 | all of the settings being abstracted by this function |
| 67 | will be returned in the Results field. In addition, |
| 68 | if a ConfigHdr is passed in with no request elements, |
| 69 | all of the settings being abstracted for that particular |
| 70 | ConfigHdr reference will be returned in the Results Field. |
| 71 | |
| 72 | @param Progress On return, points to a character in the |
| 73 | Request string. Points to the string's null |
| 74 | terminator if request was successful. Points |
| 75 | to the most recent "&" before the first |
| 76 | failing name / value pair (or the beginning |
| 77 | of the string if the failure is in the first |
| 78 | name / value pair) if the request was not |
| 79 | successful. |
| 80 | |
| 81 | @param Results A null-terminated Unicode string in |
| 82 | <MultiConfigAltResp> format which has all values |
| 83 | filled in for the names in the Request string. |
| 84 | String to be allocated by the called function. |
| 85 | |
| 86 | @retval EFI_SUCCESS The Results string is filled with the |
| 87 | values corresponding to all requested |
| 88 | names. |
| 89 | |
| 90 | @retval EFI_OUT_OF_RESOURCES Not enough memory to store the |
| 91 | parts of the results that must be |
| 92 | stored awaiting possible future |
| 93 | protocols. |
| 94 | |
| 95 | @retval EFI_NOT_FOUND A configuration element matching |
| 96 | the routing data is not found. |
| 97 | Progress set to the first character |
| 98 | in the routing header. |
| 99 | |
| 100 | @retval EFI_INVALID_PARAMETER Illegal syntax. Progress set |
| 101 | to most recent "&" before the |
| 102 | error or the beginning of the |
| 103 | string. |
| 104 | |
| 105 | @retval EFI_INVALID_PARAMETER Unknown name. Progress points |
| 106 | to the & before the name in |
| 107 | question. |
| 108 | |
| 109 | **/ |
| 110 | typedef |
| 111 | EFI_STATUS |
| 112 | (EFIAPI * EFI_HII_ACCESS_EXTRACT_CONFIG)( |
| 113 | IN CONST EFI_HII_CONFIG_ACCESS_PROTOCOL *This, |
| 114 | IN CONST EFI_STRING Request, |
| 115 | OUT EFI_STRING *Progress, |
| 116 | OUT EFI_STRING *Results |
| 117 | ); |
| 118 | |
| 119 | |
| 120 | /** |
| 121 | |
| 122 | This function applies changes in a driver's configuration. |
| 123 | Input is a Configuration, which has the routing data for this |
| 124 | driver followed by name / value configuration pairs. The driver |
| 125 | must apply those pairs to its configurable storage. If the |
| 126 | driver's configuration is stored in a linear block of data |
| 127 | and the driver's name / value pairs are in <BlockConfig> |
| 128 | format, it may use the ConfigToBlock helper function (above) to |
| 129 | simplify the job. |
| 130 | |
| 131 | @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. |
| 132 | |
| 133 | @param Configuration A null-terminated Unicode string in |
| 134 | <ConfigString> format. |
| 135 | |
| 136 | @param Progress A pointer to a string filled in with the |
| 137 | offset of the most recent '&' before the |
| 138 | first failing name / value pair (or the |
| 139 | beginn ing of the string if the failure |
| 140 | is in the first name / value pair) or |
| 141 | the terminating NULL if all was |
| 142 | successful. |
| 143 | |
| 144 | @retval EFI_SUCCESS The results have been distributed or are |
| 145 | awaiting distribution. |
| 146 | |
| 147 | @retval EFI_OUT_OF_RESOURCES Not enough memory to store the |
| 148 | parts of the results that must be |
| 149 | stored awaiting possible future |
| 150 | protocols. |
| 151 | |
| 152 | @retval EFI_INVALID_PARAMETERS Passing in a NULL for the |
| 153 | Results parameter would result |
| 154 | in this type of error. |
| 155 | |
| 156 | @retval EFI_NOT_FOUND Target for the specified routing data |
| 157 | was not found |
| 158 | |
| 159 | **/ |
| 160 | typedef |
| 161 | EFI_STATUS |
| 162 | (EFIAPI * EFI_HII_ACCESS_ROUTE_CONFIG)( |
| 163 | IN CONST EFI_HII_CONFIG_ACCESS_PROTOCOL *This, |
| 164 | IN CONST EFI_STRING Configuration, |
| 165 | OUT EFI_STRING *Progress |
| 166 | ); |
| 167 | |
| 168 | /** |
| 169 | |
| 170 | This function is called to provide results data to the driver. |
| 171 | This data consists of a unique key that is used to identify |
| 172 | which data is either being passed back or being asked for. |
| 173 | |
| 174 | @param This Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL. |
| 175 | @param Action Specifies the type of action taken by the browser. |
| 176 | @param QuestionId A unique value which is sent to the original |
| 177 | exporting driver so that it can identify the type |
| 178 | of data to expect. The format of the data tends to |
| 179 | vary based on the opcode that generated the callback. |
| 180 | @param Type The type of value for the question. |
| 181 | @param Value A pointer to the data being sent to the original |
| 182 | exporting driver. |
| 183 | @param ActionRequest On return, points to the action requested by the |
| 184 | callback function. |
| 185 | |
| 186 | @retval EFI_SUCCESS The callback successfully handled the action. |
| 187 | @retval EFI_OUT_OF_RESOURCES Not enough storage is available to hold the |
| 188 | variable and its data. |
| 189 | @retval EFI_DEVICE_ERROR The variable could not be saved. |
| 190 | @retval EFI_UNSUPPORTED The specified Action is not supported by the |
| 191 | callback. |
| 192 | **/ |
| 193 | typedef |
| 194 | EFI_STATUS |
| 195 | (EFIAPI *EFI_HII_ACCESS_FORM_CALLBACK)( |
| 196 | IN CONST EFI_HII_CONFIG_ACCESS_PROTOCOL *This, |
| 197 | IN EFI_BROWSER_ACTION Action, |
| 198 | IN EFI_QUESTION_ID QuestionId, |
| 199 | IN UINT8 Type, |
| 200 | IN OUT EFI_IFR_TYPE_VALUE *Value, |
| 201 | OUT EFI_BROWSER_ACTION_REQUEST *ActionRequest |
| 202 | ) |
| 203 | ; |
| 204 | |
| 205 | /// |
| 206 | /// This protocol provides a callable interface between the HII and |
| 207 | /// drivers. Only drivers which provide IFR data to HII are required |
| 208 | /// to publish this protocol. |
| 209 | /// |
| 210 | struct _EFI_HII_CONFIG_ACCESS_PROTOCOL { |
| 211 | EFI_HII_ACCESS_EXTRACT_CONFIG ExtractConfig; |
| 212 | EFI_HII_ACCESS_ROUTE_CONFIG RouteConfig; |
| 213 | EFI_HII_ACCESS_FORM_CALLBACK Callback; |
| 214 | } ; |
| 215 | |
| 216 | extern EFI_GUID gEfiHiiConfigAccessProtocolGuid; |
| 217 | |
| 218 | #endif |
| 219 | |
| 220 | |