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