MdePkg/Include/Protocol/HiiConfigRouting.h

   1 /** @file
   2   The file provides services to manage the movement of
   3   configuration data from drivers to configuration applications.
   4   It then serves as the single point to receive configuration
   5   information from configuration applications, routing the
   6   results to the appropriate drivers.
   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 __HII_CONFIG_ROUTING_H__
  18 #define __HII_CONFIG_ROUTING_H__
  19
  20 #define EFI_HII_CONFIG_ROUTING_PROTOCOL_GUID \
  21   { 0x587e72d7, 0xcc50, 0x4f79, { 0x82, 0x09, 0xca, 0x29, 0x1f, 0xc1, 0xa1, 0x0f } }
  22
  23
  24 typedef struct _EFI_HII_CONFIG_ROUTING_PROTOCOL EFI_HII_CONFIG_ROUTING_PROTOCOL;
  25
  26 /**
  27
  28   This function allows the caller to request the current
  29   configuration for one or more named elements from one or more
  30   drivers. The resulting string is in the standard HII
  31   configuration string format. If Successful, Results contains an
  32   equivalent string with "=" and the values associated with all
  33   names added in. The expected implementation is for each
  34   <ConfigRequest> substring in the Request to call the HII
  35   Configuration Routing Protocol ExtractProtocol function for the
  36   driver corresponding to the <ConfigHdr> at the start of the
  37   <ConfigRequest> substring. The request fails if no driver
  38   matches the <ConfigRequest> substring. Note: Alternative
  39   configuration strings may also be appended to the end of the
  40   current configuration string. If they are, they must appear
  41   after the current configuration. They must contain the same
  42   routing (GUID, NAME, PATH) as the current configuration string.
  43   They must have an additional description indicating the type of
  44   alternative configuration the string represents,
  45   "ALTCFG=<StringToken>". That <StringToken> (when converted from
  46   hexadecimal (encoded as text) to binary) is a reference to a string in the
  47   associated string pack. As an example, assume that the Request
  48   string is:
  49   GUID=...&NAME=00480050&PATH=...&Fred&George&Ron&Neville A result
  50   might be:
  51   GUID=...&NAME=00480050&PATH=...&Fred=16&George=16&Ron=12&Neville=11&
  52   GUID=...&NAME=00480050&PATH=...&ALTCFG=0037&Fred=12&Neville=7
  53
  54   @param This       Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL
  55                     instance.
  56
  57   @param Request    A null-terminated string in <MultiConfigRequest> format.
  58
  59   @param Progress   On return, points to a character in the
  60                     Request string. Points to the string's null
  61                     terminator if the request was successful. Points
  62                     to the most recent '&' before the first
  63                     failing name / value pair (or the beginning
  64                     of the string if the failure is in the first
  65                     name / value pair) if the request was not
  66                     successful
  67
  68   @param Results    A null-terminated string in <MultiConfigAltResp> format
  69                     which has all values filled in for the names in the
  70                     Request string.
  71
  72   @retval EFI_SUCCESS             The Results string is filled with the
  73                                   values corresponding to all requested
  74                                   names.
  75
  76   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the
  77                                   parts of the results that must be
  78                                   stored awaiting possible future
  79                                   protocols.
  80
  81   @retval EFI_INVALID_PARAMETER   For example, passing in a NULL
  82                                   for the Request parameter
  83                                   would result in this type of
  84                                   error. The Progress parameter
  85                                   is set to NULL.
  86
  87   @retval EFI_NOT_FOUND           Routing data doesn't match any
  88                                   known driver. Progress set to
  89                                   the "G" in "GUID" of the
  90                                   routing header that doesn't
  91                                   match. Note: There is no
  92                                   requirement that all routing
  93                                   data be validated before any
  94                                   configuration extraction.
  95
  96   @retval EFI_INVALID_PARAMETER   Illegal syntax. Progress set
  97                                   to the most recent & before the
  98                                   error, or the beginning of the
  99                                   string.
 100   @retval EFI_INVALID_PARAMETER   The ExtractConfig function of the
 101                                   underlying HII Configuration
 102                                   Access Protocol returned
 103                                   EFI_INVALID_PARAMETER. Progress
 104                                   set to most recent & before the
 105                                   error or the beginning of the
 106                                   string.
 107
 108 **/
 109 typedef
 110 EFI_STATUS
 111 (EFIAPI * EFI_HII_EXTRACT_CONFIG)(
 112   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 113   IN CONST  EFI_STRING                      Request,
 114   OUT       EFI_STRING                      *Progress,
 115   OUT       EFI_STRING                      *Results
 116 );
 117
 118 /**
 119   This function allows the caller to request the current configuration
 120   for the entirety of the current HII database and returns the data in
 121   a null-terminated string.
 122
 123   This function allows the caller to request the current
 124   configuration for all of the current HII database. The results
 125   include both the current and alternate configurations as
 126   described in ExtractConfig() above.
 127
 128   @param This     Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 129
 130   @param  Results Null-terminated Unicode string in
 131                   <MultiConfigAltResp> format which has all values
 132                   filled in for the entirety of the current HII
 133                   database. String to be allocated by the  called
 134                   function. De-allocation is up to the caller.
 135
 136   @retval EFI_SUCCESS             The Results string is filled with the
 137                                   values corresponding to all requested
 138                                   names.
 139
 140   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the
 141                                   parts of the results that must be
 142                                   stored awaiting possible future
 143                                   protocols.
 144
 145   @retval EFI_INVALID_PARAMETERS  For example, passing in a NULL
 146                                   for the Results parameter
 147                                   would result in this type of
 148                                   error.
 149
 150 **/
 151 typedef
 152 EFI_STATUS
 153 (EFIAPI * EFI_HII_EXPORT_CONFIG)(
 154   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 155   OUT       EFI_STRING                      *Results
 156 );
 157
 158 /**
 159
 160   This function routes the results of processing forms to the
 161   appropriate targets. It scans for <ConfigHdr> within the string
 162   and passes the header and subsequent body to the driver whose
 163   location is described in the <ConfigHdr>. Many <ConfigHdr>s may
 164   appear as a single request. The expected implementation is to
 165   hand off the various <ConfigResp> substrings to the
 166   Configuration Access Protocol RouteConfig routine corresponding
 167   to the driver whose routing information is defined by the
 168   <ConfigHdr> in turn.
 169
 170   @param This           Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 171
 172   @param Configuration  A null-terminated string in <MulltiConfigResp> format.
 173
 174   @param Progress       A pointer to a string filled in with the
 175                         offset of the most recent '&' before the
 176                         first failing name / value pair (or the
 177                         beginning of the string if the failure is in
 178                         the first name / value pair), or the
 179                         terminating NULL if all was successful.
 180
 181   @retval EFI_SUCCESS             The results have been distributed or are
 182                                   awaiting distribution.
 183
 184   @retval EFI_OUT_OF_RESOURCES    Not enough memory to store the
 185                                   parts of the results that must be
 186                                   stored awaiting possible future
 187                                   protocols.
 188
 189   @retval EFI_INVALID_PARAMETERS  Passing in a NULL for the
 190                                   Results parameter would result
 191                                   in this type of error.
 192
 193   @retval EFI_NOT_FOUND           The target for the specified routing data
 194                                   was not found.
 195
 196 **/
 197 typedef
 198 EFI_STATUS
 199 (EFIAPI * EFI_HII_ROUTE_CONFIG)(
 200   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 201   IN CONST  EFI_STRING                      Configuration,
 202   OUT       EFI_STRING                      *Progress
 203 );
 204
 205
 206 /**
 207
 208   This function extracts the current configuration from a block of
 209   bytes. To do so, it requires that the ConfigRequest string
 210   consists of a list of <BlockName> formatted names. It uses the
 211   offset in the name to determine the index into the Block to
 212   start the extraction and the width of each name to determine the
 213   number of bytes to extract. These are mapped to a string
 214   using the equivalent of the C "%x" format (with optional leading
 215   spaces). The call fails if, for any (offset, width) pair in
 216   ConfigRequest, offset+value >= BlockSize.
 217
 218   @param This      Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 219
 220   @param ConfigRequest  A null-terminated string in <ConfigRequest> format.
 221
 222   @param Block      An array of bytes defining the block's
 223                     configuration.
 224
 225   @param BlockSize  The length in bytes of Block.
 226
 227   @param Config     The filled-in configuration string. String
 228                     allocated by the function. Returned only if
 229                     call is successful. The null-terminated string
 230                     will be <ConfigResp> format.
 231
 232   @param Progress   A pointer to a string filled in with the
 233                     offset of the most recent '&' before the
 234                     first failing name / value pair (or the
 235                     beginning of the string if the failure is in
 236                     the first name / value pair), or the
 237                     terminating NULL if all was successful.
 238
 239   @retval EFI_SUCCESS             The request succeeded. Progress points
 240                                   to the null terminator at the end of the
 241                                   ConfigRequest string.
 242
 243   @retval EFI_OUT_OF_RESOURCES    Not enough memory to allocate
 244                                   Config. Progress points to the
 245                                   first character of ConfigRequest.
 246
 247   @retval EFI_INVALID_PARAMETERS  Passing in a NULL for the
 248                                   ConfigRequest or Block
 249                                   parameter would result in this
 250                                   type of error. Progress points
 251                                   to the first character of
 252                                   ConfigRequest.
 253
 254   @retval EFI_NOT_FOUND           The target for the specified routing data
 255                                   was not found. Progress points to the
 256                                   'G' in "GUID" of the errant routing
 257                                   data.
 258   @retval EFI_DEVICE_ERROR        The block is not large enough. Progress undefined.
 259
 260   @retval EFI_INVALID_PARAMETER   Encountered non <BlockName>
 261                                   formatted string. Block is
 262                                   left updated and Progress
 263                                   points at the '&' preceding
 264                                   the first non-<BlockName>.
 265
 266 **/
 267 typedef
 268 EFI_STATUS
 269 (EFIAPI * EFI_HII_BLOCK_TO_CONFIG)(
 270   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 271   IN CONST  EFI_STRING                      ConfigRequest,
 272   IN CONST  UINT8                           *Block,
 273   IN CONST  UINTN                           BlockSize,
 274   OUT       EFI_STRING                      *Config,
 275   OUT       EFI_STRING                      *Progress
 276 );
 277
 278
 279
 280 /**
 281   This function maps a configuration containing a series of
 282   <BlockConfig> formatted name value pairs in ConfigResp into a
 283   Block so it may be stored in a linear mapped storage such as a
 284   UEFI Variable. If present, the function skips GUID, NAME, and
 285   PATH in <ConfigResp>. It stops when it finds a non-<BlockConfig>
 286   name / value pair (after skipping the routing header) or when it
 287   reaches the end of the string.
 288   Example Assume an existing block containing: 00 01 02 03 04 05
 289   And the ConfigResp string is:
 290   OFFSET=4&WIDTH=1&VALUE=7&OFFSET=0&WIDTH=2&VALUE=AA55
 291   The results are
 292   55 AA 02 07 04 05
 293
 294   @param This           Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 295
 296   @param ConfigResp     A null-terminated string in <ConfigResp> format.
 297
 298   @param Block          A possibly null array of bytes
 299                         representing the current block. Only
 300                         bytes referenced in the ConfigResp
 301                         string in the block are modified. If
 302                         this parameter is null or if the
 303                         BlockLength parameter is (on input)
 304                         shorter than required by the
 305                         Configuration string, only the BlockSize
 306                         parameter is updated, and an appropriate
 307                         status (see below) is returned.
 308
 309   @param BlockSize      The length of the Block in units of UINT8.
 310                         On input, this is the size of the Block. On
 311                         output, if successful, contains the largest
 312                         index of the modified byte in the Block, or
 313                         the required buffer size if the Block is not
 314                         large enough.
 315
 316   @param Progress       On return, points to an element of the
 317                         ConfigResp string filled in with the offset
 318                         of the most recent "&" before the first
 319                         failing name / value pair (or the beginning
 320                         of the string if the failure is in the first
 321                         name / value pair), or the terminating NULL
 322                         if all was successful.
 323
 324   @retval EFI_SUCCESS            The request succeeded. Progress points to the null
 325                                  terminator at the end of the ConfigResp string.
 326   @retval EFI_OUT_OF_RESOURCES   Not enough memory to allocate Config. Progress
 327                                  points to the first character of ConfigResp.
 328   @retval EFI_INVALID_PARAMETER  Passing in a NULL for the ConfigResp or
 329                                  Block parameter would result in this type of
 330                                  error. Progress points to the first character of
 331                                          ConfigResp.
 332   @retval EFI_INVALID_PARAMETER  Encountered non <BlockName> formatted name /
 333                                  value pair. Block is left updated and
 334                                  Progress points at the '&' preceding the first
 335                                  non-<BlockName>.
 336   @retval EFI_DEVICE_ERROR       Block not large enough. Progress undefined.
 337   @retval EFI_NOT_FOUND          Target for the specified routing data was not found.
 338                                  Progress points to the "G" in "GUID" of the errant
 339                                  routing data.
 340   @retval EFI_BUFFER_TOO_SMALL   Block not large enough. Progress undefined.
 341                                  BlockSize is updated with the required buffer size.
 342
 343 **/
 344 typedef
 345 EFI_STATUS
 346 (EFIAPI * EFI_HII_CONFIG_TO_BLOCK)(
 347   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 348   IN CONST  EFI_STRING                      ConfigResp,
 349   IN OUT    UINT8                           *Block,
 350   IN OUT    UINTN                           *BlockSize,
 351   OUT       EFI_STRING                      *Progress
 352 );
 353
 354 /**
 355   This helper function is to be called by drivers to extract portions of
 356   a larger configuration string.
 357
 358   @param This              A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 359   @param ConfigResp        A null-terminated string in <ConfigAltResp> format.
 360   @param Guid              A pointer to the GUID value to search for in the
 361                            routing portion of the ConfigResp string when retrieving
 362                            the requested data. If Guid is NULL, then all GUID
 363                            values will be searched for.
 364   @param Name              A pointer to the NAME value to search for in the
 365                            routing portion of the ConfigResp string when retrieving
 366                            the requested data. If Name is NULL, then all Name
 367                            values will be searched for.
 368   @param DevicePath        A pointer to the PATH value to search for in the
 369                            routing portion of the ConfigResp string when retrieving
 370                            the requested data. If DevicePath is NULL, then all
 371                            DevicePath values will be searched for.
 372   @param AltCfgId          A pointer to the ALTCFG value to search for in the
 373                            routing portion of the ConfigResp string when retrieving
 374                            the requested data.  If this parameter is NULL,
 375                            then the current setting will be retrieved.
 376   @param AltCfgResp        A pointer to a buffer which will be allocated by the
 377                            function which contains the retrieved string as requested.
 378                            This buffer is only allocated if the call was successful.
 379                            The null-terminated string will be <ConfigResp> format.
 380
 381   @retval EFI_SUCCESS             The request succeeded. The requested data was extracted
 382                                   and placed in the newly allocated AltCfgResp buffer.
 383   @retval EFI_OUT_OF_RESOURCES    Not enough memory to allocate AltCfgResp.
 384   @retval EFI_INVALID_PARAMETER   Any parameter is invalid.
 385   @retval EFI_NOT_FOUND           The target for the specified routing data was not found.
 386 **/
 387 typedef
 388 EFI_STATUS
 389 (EFIAPI * EFI_HII_GET_ALT_CFG)(
 390   IN  CONST EFI_HII_CONFIG_ROUTING_PROTOCOL    *This,
 391   IN  CONST EFI_STRING                         ConfigResp,
 392   IN  CONST EFI_GUID                           *Guid,
 393   IN  CONST EFI_STRING                         Name,
 394   IN  CONST EFI_DEVICE_PATH_PROTOCOL           *DevicePath,
 395   IN  CONST UINT16                             *AltCfgId,
 396   OUT EFI_STRING                               *AltCfgResp
 397   );
 398
 399 ///
 400 /// This protocol defines the configuration routing interfaces
 401 /// between external applications and the HII. There may only be one
 402 /// instance of this protocol in the system.
 403 ///
 404 struct _EFI_HII_CONFIG_ROUTING_PROTOCOL {
 405   EFI_HII_EXTRACT_CONFIG  ExtractConfig;
 406   EFI_HII_EXPORT_CONFIG   ExportConfig;
 407   EFI_HII_ROUTE_CONFIG    RouteConfig;
 408   EFI_HII_BLOCK_TO_CONFIG BlockToConfig;
 409   EFI_HII_CONFIG_TO_BLOCK ConfigToBlock;
 410   EFI_HII_GET_ALT_CFG     GetAltConfig;
 411 };
 412
 413 extern EFI_GUID gEfiHiiConfigRoutingProtocolGuid;
 414
 415
 416 #endif
 417