EdkCompatibilityPkg/Foundation/Efi/Protocol/HiiConfigRouting/HiiConfigRouting.h

   1 /*++
   2
   3 Copyright (c) 2007, Intel Corporation. All rights reserved.<BR>
   4 This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14   HiiConfigRouting.h
  15
  16 Abstract:
  17
  18   EFI_HII_CONFIG_ROUTING_PROTOCOL as defined in UEFI 2.1 spec.
  19
  20 --*/
  21
  22 #ifndef __EFI_HII_CONFIG_ROUTING_H__
  23 #define __EFI_HII_CONFIG_ROUTING_H__
  24
  25 #include "EfiHii.h"
  26
  27 #define EFI_HII_CONFIG_ROUTING_PROTOCOL_GUID \
  28   { \
  29     0x587e72d7, 0xcc50, 0x4f79, {0x82, 0x09, 0xca, 0x29, 0x1f, 0xc1, 0xa1, 0x0f} \
  30   }
  31
  32 //
  33 // Forward reference for pure ANSI compatability
  34 //
  35 EFI_FORWARD_DECLARATION (EFI_HII_CONFIG_ROUTING_PROTOCOL);
  36
  37 typedef
  38 EFI_STATUS
  39 (EFIAPI *EFI_HII_EXTRACT_CONFIG) (
  40   IN  CONST EFI_HII_CONFIG_ROUTING_PROTOCOL  *This,
  41   IN  CONST EFI_STRING                       Request,
  42   OUT EFI_STRING                             *Progress,
  43   OUT EFI_STRING                             *Results
  44   )
  45 /*++
  46
  47   Routine Description:
  48     This function allows a caller to extract the current configuration
  49     for one or more named elements from one or more drivers.
  50
  51   Arguments:
  52     This                   - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
  53     Request                - A null-terminated Unicode string in <MultiConfigRequest> format.
  54     Progress               - On return, points to a character in the Request string. Points to the string's null
  55                              terminator if request was successful. Points to the most recent '&' before the first
  56                              failing name / value pair (or the beginning of the string if the failure is in the first
  57                              name / value pair) if the request was not successful.
  58     Results                - Null-terminated Unicode string in <MultiConfigAltResp> format which has all
  59                              values filled in for the names in the Request string. String to be allocated by the called
  60                              function.
  61
  62   Returns:
  63     EFI_SUCCESS            - The Results string is filled with the values
  64                              corresponding to all requested names.
  65     EFI_OUT_OF_RESOURCES   - Not enough memory to store the parts of the results
  66                              that must be stored awaiting possible future
  67                              protocols.
  68     EFI_NOT_FOUND          - Routing data doesn't match any known driver.
  69                              Progress set to the 'G' in "GUID" of the routing
  70                              header that doesn't match. Note: There is no
  71                              requirement that all routing data be validated before
  72                              any configuration extraction.
  73     EFI_INVALID_PARAMETER  - For example, passing in a NULL for the Request
  74                              parameter would result in this type of error. The
  75                              Progress parameter is set to NULL.
  76
  77     EFI_INVALID_PARAMETER  - Illegal syntax. Progress set to most recent & before
  78                              the error or the beginning of the string.
  79
  80     EFI_INVALID_PARAMETER  - Unknown name. Progress points to the & before
  81                              the name in question.
  82
  83 --*/
  84 ;
  85
  86 typedef
  87 EFI_STATUS
  88 (EFIAPI *EFI_HII_EXPORT_CONFIG) (
  89   IN  CONST EFI_HII_CONFIG_ROUTING_PROTOCOL  *This,
  90   OUT EFI_STRING                             *Results
  91   )
  92 /*++
  93
  94   Routine Description:
  95     This function allows the caller to request the current configuration for the
  96     entirety of the current HII database and returns the data in a null-terminated Unicode string.
  97
  98   Arguments:
  99     This                   - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 100     Results                - Null-terminated Unicode string in <MultiConfigAltResp> format which has all
 101                              values filled in for the names in the Request string. String to be allocated by the called
 102                              function. De-allocation is up to the caller.
 103
 104   Returns:
 105     EFI_SUCCESS            - The Results string is filled with the values
 106                              corresponding to all requested names.
 107     EFI_OUT_OF_RESOURCES   - Not enough memory to store the parts of the results
 108                              that must be stored awaiting possible future
 109                              protocols.
 110     EFI_INVALID_PARAMETER  - For example, passing in a NULL for the Results
 111                              parameter would result in this type of error.
 112
 113 --*/
 114 ;
 115
 116 typedef
 117 EFI_STATUS
 118 (EFIAPI *EFI_HII_ROUTE_CONFIG) (
 119   IN  EFI_HII_CONFIG_ROUTING_PROTOCOL        *This,
 120   IN  CONST EFI_STRING                       Configuration,
 121   OUT EFI_STRING                             *Progress
 122   )
 123 /*++
 124
 125   Routine Description:
 126     This function processes the results of processing forms and routes it to the
 127     appropriate handlers or storage.
 128
 129   Arguments:
 130     This                   - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 131     Configuration          - A null-terminated Unicode string in <MulltiConfigResp> format.
 132     Progress               - A pointer to a string filled in with the offset of the most recent "&" before the first
 133                              failing name / value pair (or the beginning of the string if the failure is in the first
 134                              name / value pair) or the terminating NULL if all was successful.
 135
 136   Returns:
 137     EFI_SUCCESS            - The results have been distributed or are awaiting
 138                              distribution.
 139     EFI_OUT_OF_RESOURCES   - Not enough memory to store the parts of the results
 140                              that must be stored awaiting possible future
 141                              protocols.
 142     EFI_INVALID_PARAMETER  - Passing in a NULL for the Configuration
 143                              parameter would result in this type of error.
 144     EFI_NOT_FOUND          - Target for the specified routing data was not found.
 145
 146 --*/
 147 ;
 148
 149
 150 typedef
 151 EFI_STATUS
 152 (EFIAPI *EFI_HII_BLOCK_TO_CONFIG) (
 153   IN  CONST EFI_HII_CONFIG_ROUTING_PROTOCOL  *This,
 154   IN  CONST EFI_STRING                       ConfigRequest,
 155   IN  CONST UINT8                            *Block,
 156   IN  CONST UINTN                            BlockSize,
 157   OUT EFI_STRING                             *Config,
 158   OUT EFI_STRING                             *Progress
 159   )
 160 /*++
 161
 162   Routine Description:
 163     This helper function is to be called by drivers to map configuration data stored
 164     in byte array ("block") formats such as UEFI Variables into current configuration strings.
 165
 166   Arguments:
 167     This                   - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 168     ConfigRequest          - A null-terminated Unicode string in <ConfigRequest> format.
 169     Block                  - Array of bytes defining the block's configuration.
 170     BlockSize              - Length in bytes of Block.
 171     Config                 - Filled-in configuration string. String allocated by the function.
 172                               Returned only if call is successful.
 173     Progress               - A pointer to a string filled in with the offset of the most recent "&" before the first
 174                              failing name / value pair (or the beginning of the string if the failure is in the first
 175                              name / value pair) or the terminating NULL if all was successful.
 176
 177   Returns:
 178     EFI_SUCCESS            - The request succeeded. Progress points to the null
 179                              terminator at the end of the ConfigRequest
 180                              string.
 181     EFI_OUT_OF_RESOURCES   - Not enough memory to allocate Config.
 182                              Progress points to the first character of
 183                              ConfigRequest.
 184     EFI_INVALID_PARAMETER  - Passing in a NULL for the ConfigRequest or
 185                              Block parameter would result in this type of
 186                              error. Progress points to the first character of
 187                              ConfigRequest.
 188     EFI_NOT_FOUND          - Target for the specified routing data was not found.
 189                              Progress points to the "G" in "GUID" of the
 190                              errant routing data.
 191     EFI_DEVICE_ERROR       - Block not large enough. Progress undefined.
 192     EFI_INVALID_PARAMETER  - Encountered non <BlockName> formatted string.
 193                              Block is left updated and Progress points at the "&"
 194                              preceding the first non-<BlockName>.
 195
 196 --*/
 197 ;
 198
 199 typedef
 200 EFI_STATUS
 201 (EFIAPI *EFI_HII_CONFIG_TO_BLOCK) (
 202   IN     CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
 203   IN     CONST EFI_STRING                      ConfigResp,
 204   IN OUT UINT8                                 *Block,
 205   IN OUT UINTN                                 *BlockSize,
 206   OUT    EFI_STRING                            *Progress
 207   )
 208 /*++
 209
 210   Routine Description:
 211     This helper function is to be called by drivers to map configuration strings
 212     to configurations stored in byte array ("block") formats such as UEFI Variables.
 213
 214   Arguments:
 215     This                   - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 216     ConfigResp             - A null-terminated Unicode string in <ConfigResp> format.
 217     Block                  - A possibly null array of bytes representing the current block.
 218                              Only bytes referenced in the ConfigResp string in the block are modified.
 219                              If this parameter is null or if the *BlockSize parameter is (on input)
 220                              shorter than required by the Configuration string, only the BlockSize
 221                              parameter is updated and an appropriate status (see below) is returned.
 222
 223     BlockSize              - The length of the Block in units of UINT8. On input, this is the size of the Block.
 224                              On output, if successful, contains the index of the last modified byte in the Block.
 225
 226     Progress               - On return, points to an element of the ConfigResp string filled in with the offset of
 227                              the most recent "&" before the first failing name / value pair (or the beginning of the
 228                              string if the failure is in the first name / value pair) or the terminating NULL if all was
 229                              successful.
 230   Returns:
 231     EFI_SUCCESS            - The request succeeded. Progress points to the null
 232                              terminator at the end of the ConfigResp
 233                              string.
 234     EFI_OUT_OF_RESOURCES   - Not enough memory to allocate Config.
 235                              Progress points to the first character of
 236                              ConfigResp.
 237     EFI_INVALID_PARAMETER  - Passing in a NULL for the ConfigResp or
 238                              Block parameter would result in this type of error.
 239                              Progress points to the first character of
 240                              ConfigResp.
 241     EFI_NOT_FOUND          - Target for the specified routing data was not found.
 242                              Progress points to the "G" in "GUID" of the
 243                              errant routing data.
 244     EFI_INVALID_PARAMETER  - Encountered non <BlockName> formatted name /
 245                              value pair. Block is left updated and
 246                              Progress points at the "&" preceding the first
 247                              non-<BlockName>.
 248
 249 --*/
 250 ;
 251
 252 typedef
 253 EFI_STATUS
 254 (EFIAPI * EFI_HII_GET_ALT_CFG) (
 255   IN  CONST EFI_HII_CONFIG_ROUTING_PROTOCOL    *This,
 256   IN  CONST EFI_STRING                         Configuration,
 257   IN  CONST EFI_GUID                           *Guid,
 258   IN  CONST EFI_STRING                         Name,
 259   IN  CONST EFI_DEVICE_PATH_PROTOCOL           *DevicePath,
 260   IN  CONST UINT16                             *AltCfgId,
 261   OUT EFI_STRING                               *AltCfgResp
 262   )
 263 /*++
 264
 265   Routine Description:
 266     This helper function is to be called by drivers to extract portions of
 267     a larger configuration string.
 268
 269   Arguments:
 270     This                   - A pointer to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.
 271     Configuration          - A null-terminated Unicode string in <MultiConfigAltResp> format.
 272     Guid                   - A pointer to the GUID value to search for in the
 273                              routing portion of the ConfigResp string when retrieving
 274                              the requested data. If Guid is NULL, then all GUID
 275                              values will be searched for.
 276     Name                   - A pointer to the NAME value to search for in the
 277                              routing portion of the ConfigResp string when retrieving
 278                              the requested data. If Name is NULL, then all Name
 279                              values will be searched for.
 280     DevicePath             - A pointer to the PATH value to search for in the
 281                              routing portion of the ConfigResp string when retrieving
 282                              the requested data. If DevicePath is NULL, then all
 283                              DevicePath values will be searched for.
 284     AltCfgId               - A pointer to the ALTCFG value to search for in the
 285                              routing portion of the ConfigResp string when retrieving
 286                              the requested data.  If this parameter is NULL,
 287                              then the current setting will be retrieved.
 288     AltCfgResp             - A pointer to a buffer which will be allocated by the
 289                              function which contains the retrieved string as requested.
 290                              This buffer is only allocated if the call was successful.
 291
 292   Returns:
 293     EFI_SUCCESS            - The request succeeded. The requested data was extracted
 294                              and placed in the newly allocated AltCfgResp buffer.
 295     EFI_OUT_OF_RESOURCES   - Not enough memory to allocate AltCfgResp.
 296     EFI_INVALID_PARAMETER  - Any parameter is invalid.
 297     EFI_NOT_FOUND          - Target for the specified routing data was not found.
 298
 299 --*/
 300 ;
 301
 302
 303 struct _EFI_HII_CONFIG_ROUTING_PROTOCOL {
 304   EFI_HII_EXTRACT_CONFIG    ExtractConfig;
 305   EFI_HII_EXPORT_CONFIG     ExportConfig;
 306   EFI_HII_ROUTE_CONFIG      RouteConfig;
 307   EFI_HII_BLOCK_TO_CONFIG   BlockToConfig;
 308   EFI_HII_CONFIG_TO_BLOCK   ConfigToBlock;
 309   EFI_HII_GET_ALT_CFG       GetAltConfig;
 310 };
 311
 312 extern EFI_GUID gEfiHiiConfigRoutingProtocolGuid;
 313
 314 #endif