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