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