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