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 - 2007, 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
 131                 instance.
 132
 133   @param Results  A null-terminated Unicode string in
 134                   <MultiConfigAltResp> format which has all
 135                   values filled in for the names in the Request
 136                   string. String to be allocated by this
 137                   function. De-allocation is up to the caller.
 138
 139   @retval EFI_SUCCESS   The Results string is filled with the
 140                         values corresponding to all requested
 141                         names.
 142
 143   @retval EFI_OUT_OF_MEMORY   Not enough memory to store the
 144                               parts of the results that must be
 145                               stored awaiting possible future
 146                               protocols.
 147
 148   @retval EFI_INVALID_PARAMETERS  For example, passing in a NULL
 149                                   for the Results parameter
 150                                   would result in this type of
 151                                   error.
 152
 153 **/
 154 typedef
 155 EFI_STATUS
 156 (EFIAPI * EFI_HII_ROUTING_EXPORT_CONFIG ) (
 157   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 158   OUT       EFI_STRING                      *Results
 159 );
 160
 161 /**
 162
 163   This function routes the results of processing forms to the
 164   appropriate targets. It scans for <ConfigHdr> within the string
 165   and passes the header and subsequent body to the driver whose
 166   location is described in the <ConfigHdr>. Many <ConfigHdr>s may
 167   appear as a single request. The expected implementation is to
 168   hand off the various <ConfigResp> substrings to the
 169   Configuration Access Protocol RouteConfig routine corresponding
 170   to the driver whose routing information is defined by the
 171   <ConfigHdr> in turn.
 172
 173   @param This   Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL
 174                 instance.
 175
 176   @param Configuration  A null-terminated Unicode string in
 177                         <MulltiConfigResp> format.
 178
 179   @param Progress   A pointer to a string filled in with the
 180                     offset of the most recent '&' before the
 181                     first failing name / value pair (or the
 182                     beginning of the string if the failure is in
 183                     the first name / value pair) or the
 184                     terminating NULL if all was successful.
 185
 186   @retval EFI_SUCCESS   The results have been distributed or are
 187                         awaiting distribution.
 188
 189   @retval EFI_OUT_OF_MEMORY   Not enough memory to store the
 190                               parts of the results that must be
 191                               stored awaiting possible future
 192                               protocols.
 193
 194   @retval EFI_INVALID_PARAMETERS  Passing in a NULL for the
 195                                   Results parameter would result
 196                                   in this type of error.
 197
 198   @retval EFI_NOT_FOUND   Target for the specified routing data
 199                           was not found
 200
 201 **/
 202 typedef
 203 EFI_STATUS
 204 (EFIAPI * EFI_HII_ROUTING_ROUTE_CONFIG ) (
 205   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 206   IN CONST  EFI_STRING                      Configuration,
 207   OUT       EFI_STRING                      *Progress
 208 );
 209
 210
 211 /**
 212
 213   This function extracts the current configuration from a block of
 214   bytes. To do so, it requires that the ConfigRequest string
 215   consists of a list of <BlockName> formatted names. It uses the
 216   offset in the name to determine the index into the Block to
 217   start the extraction and the width of each name to determine the
 218   number of bytes to extract. These are mapped to a UNICODE value
 219   using the equivalent of the C "%x" format (with optional leading
 220   spaces). The call fails if, for any (offset, width) pair in
 221   ConfigRequest, offset+value >= BlockSize.
 222
 223   @param This   Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL
 224                 instance.
 225
 226   @param ConfigRequest  A null-terminated Unicode string in
 227                         <ConfigRequest> format.
 228
 229   @param Block  Array of bytes defining the block's
 230                 configuration.
 231
 232   @param BlockSize  Length in bytes of Block.
 233
 234   @param Config   Filled-in configuration string. String
 235                   allocated by the function. Returned only if
 236                   call is successful.
 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   @retval EFI_OUT_OF_MEMORY   Not enough memory to allocate
 249                               Config. Progress points to the
 250                               first character of ConfigRequest.
 251
 252   @retval EFI_INVALID_PARAMETERS  Passing in a NULL for the
 253                                   ConfigRequest or Block
 254                                   parameter would result in this
 255                                   type of error. Progress points
 256                                   to the first character of
 257                                   ConfigRequest.
 258
 259   @retval EFI_NOT_FOUND   Target for the specified routing data
 260                           was not found. Progress points to the
 261                           'G' in "GUID" of the errant routing
 262                           data. EFI_DEVICE_ERROR Block not large
 263                           enough. Progress undefined.
 264
 265   @retval EFI_INVALID_PARAMETER   Encountered non <BlockName>
 266                                   formatted string. Block is
 267                                   left updated and Progress
 268                                   points at the '&' preceding
 269                                   the first non-<BlockName>.
 270
 271 **/
 272 typedef
 273 EFI_STATUS
 274 (EFIAPI * EFI_HII_ROUTING_BLOCK_TO_CONFIG ) (
 275   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 276   IN CONST  EFI_STRING                      ConfigRequest,
 277   IN CONST  UINT8                           *Block,
 278   IN CONST  UINTN                           BlockSize,
 279   OUT       EFI_STRING                      **Config,
 280   OUT       EFI_STRING                      *Progress
 281 );
 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
 301                 instance.
 302
 303   @param ConfigResp   A  null-terminated Unicode string in
 304                       <ConfigResp> format.
 305
 306   @param CurrentBlock   A possibly null array of bytes
 307                         representing the current block. Only
 308                         bytes referenced in the ConfigResp
 309                         string in the block are modified. If
 310                         this parameter is null or if the
 311                         BlockLength parameter is (on input)
 312                         shorter than required by the
 313                         Configuration string, only the BlockSize
 314                         parameter is updated and an appropriate
 315                         status (see below) is returned.
 316
 317   @param BlockSize  The length of the Block in units of UINT8.
 318                     On input, this is the size of the Block. On
 319                     output, if successful, contains the index of
 320                     the last modified byte in the Block.
 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 **/
 331 typedef
 332 EFI_STATUS
 333 (EFIAPI * EFI_HII_ROUTING_CONFIG_TO_BLOCK ) (
 334   IN CONST  EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 335   IN CONST  EFI_STRING                      *ConfigResp,
 336   IN CONST  UINT8                           *Block,
 337   IN OUT    UINTN                           *BlockSize,
 338   OUT       EFI_STRING                      *Progress
 339 );
 340
 341
 342 /**
 343
 344   This protocol defines the configuration routing interfaces
 345   between external applications and the HII. There may only be one
 346   instance of this protocol in the system.
 347
 348 **/
 349 struct _EFI_HII_CONFIG_ROUTING_PROTOCOL {
 350   EFI_HII_ROUTING_EXTRACT_CONFIG  ExtractConfig;
 351   EFI_HII_ROUTING_EXPORT_CONFIG   ExportConfig;
 352   EFI_HII_ROUTING_ROUTE_CONFIG    RouteConfig;
 353   EFI_HII_ROUTING_BLOCK_TO_CONFIG BlockToConfig;
 354   EFI_HII_ROUTING_CONFIG_TO_BLOCK ConfigToBlock;
 355 };
 356
 357 extern EFI_GUID gEfiHiiConfigRoutingProtocolGuid;
 358
 359
 360 #endif
 361