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