iPXE
HiiConfigAccess.h
Go to the documentation of this file.
00001 /** @file
00002 
00003   The EFI HII results processing protocol invokes this type of protocol
00004   when it needs to forward results to a driver's configuration handler.
00005   This protocol is published by drivers providing and requesting
00006   configuration data from HII. It may only be invoked by HII.
00007 
00008 Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR>
00009 This program and the accompanying materials are licensed and made available under
00010 the terms and conditions of the BSD License that accompanies this distribution.
00011 The full text of the license may be found at
00012 http://opensource.org/licenses/bsd-license.php.
00013 
00014 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00015 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00016 
00017 **/
00018 
00019 
00020 #ifndef __EFI_HII_CONFIG_ACCESS_H__
00021 #define __EFI_HII_CONFIG_ACCESS_H__
00022 
00023 FILE_LICENCE ( BSD3 );
00024 
00025 #include <ipxe/efi/Protocol/FormBrowser2.h>
00026 
00027 #define EFI_HII_CONFIG_ACCESS_PROTOCOL_GUID  \
00028   { 0x330d4706, 0xf2a0, 0x4e4f, { 0xa3, 0x69, 0xb6, 0x6f, 0xa8, 0xd5, 0x43, 0x85 } }
00029 
00030 typedef struct _EFI_HII_CONFIG_ACCESS_PROTOCOL  EFI_HII_CONFIG_ACCESS_PROTOCOL;
00031 
00032 typedef UINTN EFI_BROWSER_ACTION;
00033 
00034 #define EFI_BROWSER_ACTION_CHANGING   0
00035 #define EFI_BROWSER_ACTION_CHANGED    1
00036 #define EFI_BROWSER_ACTION_RETRIEVE   2
00037 #define EFI_BROWSER_ACTION_FORM_OPEN  3
00038 #define EFI_BROWSER_ACTION_FORM_CLOSE 4
00039 #define EFI_BROWSER_ACTION_SUBMITTED  5
00040 #define EFI_BROWSER_ACTION_DEFAULT_STANDARD      0x1000
00041 #define EFI_BROWSER_ACTION_DEFAULT_MANUFACTURING 0x1001
00042 #define EFI_BROWSER_ACTION_DEFAULT_SAFE          0x1002
00043 #define EFI_BROWSER_ACTION_DEFAULT_PLATFORM      0x2000
00044 #define EFI_BROWSER_ACTION_DEFAULT_HARDWARE      0x3000
00045 #define EFI_BROWSER_ACTION_DEFAULT_FIRMWARE      0x4000
00046 
00047 /**
00048 
00049   This function allows the caller to request the current
00050   configuration for one or more named elements. The resulting
00051   string is in <ConfigAltResp> format. Any and all alternative
00052   configuration strings shall also be appended to the end of the
00053   current configuration string. If they are, they must appear
00054   after the current configuration. They must contain the same
00055   routing (GUID, NAME, PATH) as the current configuration string.
00056   They must have an additional description indicating the type of
00057   alternative configuration the string represents,
00058   "ALTCFG=<StringToken>". That <StringToken> (when
00059   converted from Hex UNICODE to binary) is a reference to a
00060   string in the associated string pack.
00061 
00062   @param This       Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
00063 
00064   @param Request    A null-terminated Unicode string in
00065                     <ConfigRequest> format. Note that this
00066                     includes the routing information as well as
00067                     the configurable name / value pairs. It is
00068                     invalid for this string to be in
00069                     <MultiConfigRequest> format.
00070                     If a NULL is passed in for the Request field,
00071                     all of the settings being abstracted by this function
00072                     will be returned in the Results field.  In addition,
00073                     if a ConfigHdr is passed in with no request elements,
00074                     all of the settings being abstracted for that particular
00075                     ConfigHdr reference will be returned in the Results Field.
00076 
00077   @param Progress   On return, points to a character in the
00078                     Request string. Points to the string's null
00079                     terminator if request was successful. Points
00080                     to the most recent "&" before the first
00081                     failing name / value pair (or the beginning
00082                     of the string if the failure is in the first
00083                     name / value pair) if the request was not
00084                     successful.
00085 
00086   @param Results    A null-terminated Unicode string in
00087                     <MultiConfigAltResp> format which has all values
00088                     filled in for the names in the Request string.
00089                     String to be allocated by the called function.
00090 
00091   @retval EFI_SUCCESS             The Results string is filled with the
00092                                   values corresponding to all requested
00093                                   names.
00094 
00095   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the
00096                                   parts of the results that must be
00097                                   stored awaiting possible future
00098                                   protocols.
00099 
00100   @retval EFI_NOT_FOUND           A configuration element matching
00101                                   the routing data is not found.
00102                                   Progress set to the first character
00103                                   in the routing header.
00104 
00105   @retval EFI_INVALID_PARAMETER   Illegal syntax. Progress set
00106                                   to most recent "&" before the
00107                                   error or the beginning of the
00108                                   string.
00109 
00110   @retval EFI_INVALID_PARAMETER   Unknown name. Progress points
00111                                   to the & before the name in
00112                                   question.
00113 
00114 **/
00115 typedef
00116 EFI_STATUS
00117 (EFIAPI * EFI_HII_ACCESS_EXTRACT_CONFIG)(
00118   IN CONST  EFI_HII_CONFIG_ACCESS_PROTOCOL  *This,
00119   IN CONST  EFI_STRING                      Request,
00120   OUT       EFI_STRING                      *Progress,
00121   OUT       EFI_STRING                      *Results
00122 );
00123 
00124 
00125 /**
00126 
00127   This function applies changes in a driver's configuration.
00128   Input is a Configuration, which has the routing data for this
00129   driver followed by name / value configuration pairs. The driver
00130   must apply those pairs to its configurable storage. If the
00131   driver's configuration is stored in a linear block of data
00132   and the driver's name / value pairs are in <BlockConfig>
00133   format, it may use the ConfigToBlock helper function (above) to
00134   simplify the job.
00135 
00136   @param This           Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
00137 
00138   @param Configuration  A null-terminated Unicode string in
00139                         <ConfigString> format.
00140 
00141   @param Progress       A pointer to a string filled in with the
00142                         offset of the most recent '&' before the
00143                         first failing name / value pair (or the
00144                         beginn ing of the string if the failure
00145                         is in the first name / value pair) or
00146                         the terminating NULL if all was
00147                         successful.
00148 
00149   @retval EFI_SUCCESS             The results have been distributed or are
00150                                   awaiting distribution.
00151 
00152   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the
00153                                   parts of the results that must be
00154                                   stored awaiting possible future
00155                                   protocols.
00156 
00157   @retval EFI_INVALID_PARAMETERS  Passing in a NULL for the
00158                                   Results parameter would result
00159                                   in this type of error.
00160 
00161   @retval EFI_NOT_FOUND           Target for the specified routing data
00162                                   was not found
00163 
00164 **/
00165 typedef
00166 EFI_STATUS
00167 (EFIAPI * EFI_HII_ACCESS_ROUTE_CONFIG)(
00168   IN CONST  EFI_HII_CONFIG_ACCESS_PROTOCOL  *This,
00169   IN CONST  EFI_STRING                      Configuration,
00170   OUT       EFI_STRING                      *Progress
00171 );
00172 
00173 /**
00174 
00175   This function is called to provide results data to the driver.
00176   This data consists of a unique key that is used to identify
00177   which data is either being passed back or being asked for.
00178 
00179   @param  This                   Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
00180   @param  Action                 Specifies the type of action taken by the browser.
00181   @param  QuestionId             A unique value which is sent to the original
00182                                  exporting driver so that it can identify the type
00183                                  of data to expect. The format of the data tends to
00184                                  vary based on the opcode that generated the callback.
00185   @param  Type                   The type of value for the question.
00186   @param  Value                  A pointer to the data being sent to the original
00187                                  exporting driver.
00188   @param  ActionRequest          On return, points to the action requested by the
00189                                  callback function.
00190 
00191   @retval EFI_SUCCESS            The callback successfully handled the action.
00192   @retval EFI_OUT_OF_RESOURCES   Not enough storage is available to hold the
00193                                  variable and its data.
00194   @retval EFI_DEVICE_ERROR       The variable could not be saved.
00195   @retval EFI_UNSUPPORTED        The specified Action is not supported by the
00196                                  callback.
00197 **/
00198 typedef
00199 EFI_STATUS
00200 (EFIAPI *EFI_HII_ACCESS_FORM_CALLBACK)(
00201   IN     CONST EFI_HII_CONFIG_ACCESS_PROTOCOL   *This,
00202   IN     EFI_BROWSER_ACTION                     Action,
00203   IN     EFI_QUESTION_ID                        QuestionId,
00204   IN     UINT8                                  Type,
00205   IN OUT EFI_IFR_TYPE_VALUE                     *Value,
00206   OUT    EFI_BROWSER_ACTION_REQUEST             *ActionRequest
00207   )
00208   ;
00209 
00210 ///
00211 /// This protocol provides a callable interface between the HII and
00212 /// drivers. Only drivers which provide IFR data to HII are required
00213 /// to publish this protocol.
00214 ///
00215 struct _EFI_HII_CONFIG_ACCESS_PROTOCOL {
00216   EFI_HII_ACCESS_EXTRACT_CONFIG     ExtractConfig;
00217   EFI_HII_ACCESS_ROUTE_CONFIG       RouteConfig;
00218   EFI_HII_ACCESS_FORM_CALLBACK      Callback;
00219 } ;
00220 
00221 extern EFI_GUID gEfiHiiConfigAccessProtocolGuid;
00222 
00223 #endif
00224 
00225