MdePkg/Include/Protocol/HiiConfigKeyword.h

   1 /** @file
   2   The file provides the mechanism to set and get the values
   3   associated with a keyword exposed through a x-UEFI- prefixed
   4   configuration language namespace.
   5
   6 Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
   7 This program and the accompanying materials are licensed and made available under
   8 the terms and conditions of the BSD License that accompanies this distribution.
   9 The full text of the license may be found at
  10 http://opensource.org/licenses/bsd-license.php.
  11
  12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15   @par Revision Reference:
  16   This Protocol was introduced in UEFI Specification 2.5.
  17
  18
  19 **/
  20
  21 #ifndef __EFI_CONFIG_KEYWORD_HANDLER_H__
  22 #define __EFI_CONFIG_KEYWORD_HANDLER_H__
  23
  24 #define EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL_GUID \
  25 { \
  26   0x0a8badd5, 0x03b8, 0x4d19, {0xb1, 0x28, 0x7b, 0x8f, 0x0e, 0xda, 0xa5, 0x96 } \
  27 }
  28
  29 //***********************************************************
  30 // Progress Errors
  31 //***********************************************************
  32 #define KEYWORD_HANDLER_NO_ERROR                       0x00000000
  33 #define KEYWORD_HANDLER_NAMESPACE_ID_NOT_FOUND         0x00000001
  34 #define KEYWORD_HANDLER_MALFORMED_STRING               0x00000002
  35 #define KEYWORD_HANDLER_KEYWORD_NOT_FOUND              0x00000004
  36 #define KEYWORD_HANDLER_INCOMPATIBLE_VALUE_DETECTED    0x00000008
  37 #define KEYWORD_HANDLER_ACCESS_NOT_PERMITTED           0x00000010
  38 #define KEYWORD_HANDLER_UNDEFINED_PROCESSING_ERROR     0x80000000
  39
  40 typedef struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL;
  41
  42 /**
  43
  44   This function accepts a <MultiKeywordResp> formatted string, finds the associated
  45   keyword owners, creates a <MultiConfigResp> string from it and forwards it to the
  46   EFI_HII_ROUTING_PROTOCOL.RouteConfig function.
  47
  48   If there is an issue in resolving the contents of the KeywordString, then the
  49   function returns an error and also sets the Progress and ProgressErr with the
  50   appropriate information about where the issue occurred and additional data about
  51   the nature of the issue.
  52
  53   In the case when KeywordString containing multiple keywords, when an EFI_NOT_FOUND
  54   error is generated during processing the second or later keyword element, the system
  55   storage associated with earlier keywords is not modified. All elements of the
  56   KeywordString must successfully pass all tests for format and access prior to making
  57   any modifications to storage.
  58
  59   In the case when EFI_DEVICE_ERROR is returned from the processing of a KeywordString
  60   containing multiple keywords, the state of storage associated with earlier keywords
  61   is undefined.
  62
  63
  64   @param This             Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance.
  65
  66   @param KeywordString    A null-terminated string in <MultiKeywordResp> format.
  67
  68   @param Progress         On return, points to a character in the KeywordString.
  69                           Points to the string's NULL terminator if the request
  70                           was successful. Points to the most recent '&' before
  71                           the first failing name / value pair (or the beginning
  72                           of the string if the failure is in the first name / value
  73                           pair) if the request was not successful.
  74
  75   @param ProgressErr      If during the processing of the KeywordString there was
  76                           a failure, this parameter gives additional information
  77                           about the possible source of the problem. The various
  78                           errors are defined in "Related Definitions" below.
  79
  80
  81   @retval EFI_SUCCESS             The specified action was completed successfully.
  82
  83   @retval EFI_INVALID_PARAMETER   One or more of the following are TRUE:
  84                                   1. KeywordString is NULL.
  85                                   2. Parsing of the KeywordString resulted in an
  86                                      error. See Progress and ProgressErr for more data.
  87
  88   @retval EFI_NOT_FOUND           An element of the KeywordString was not found.
  89                                   See ProgressErr for more data.
  90
  91   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
  92                                   See ProgressErr for more data.
  93
  94   @retval EFI_ACCESS_DENIED       The action violated system policy. See ProgressErr
  95                                   for more data.
  96
  97   @retval EFI_DEVICE_ERROR        An unexpected system error occurred. See ProgressErr
  98                                   for more data.
  99
 100 **/
 101 typedef
 102 EFI_STATUS
 103 (EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_SET_DATA) (
 104   IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL *This,
 105   IN CONST EFI_STRING                    KeywordString,
 106   OUT EFI_STRING                         *Progress,
 107   OUT UINT32                             *ProgressErr
 108   );
 109
 110
 111 /**
 112
 113   This function accepts a <MultiKeywordRequest> formatted string, finds the underlying
 114   keyword owners, creates a <MultiConfigRequest> string from it and forwards it to the
 115   EFI_HII_ROUTING_PROTOCOL.ExtractConfig function.
 116
 117   If there is an issue in resolving the contents of the KeywordString, then the function
 118   returns an EFI_INVALID_PARAMETER and also set the Progress and ProgressErr with the
 119   appropriate information about where the issue occurred and additional data about the
 120   nature of the issue.
 121
 122   In the case when KeywordString is NULL, or contains multiple keywords, or when
 123   EFI_NOT_FOUND is generated while processing the keyword elements, the Results string
 124   contains values returned for all keywords processed prior to the keyword generating the
 125   error but no values for the keyword with error or any following keywords.
 126
 127
 128   @param This           Pointer to the EFI_KEYWORD_HANDLER _PROTOCOL instance.
 129
 130   @param NameSpaceId    A null-terminated string containing the platform configuration
 131                         language to search through in the system. If a NULL is passed
 132                         in, then it is assumed that any platform configuration language
 133                         with the prefix of "x-UEFI-" are searched.
 134
 135   @param KeywordString  A null-terminated string in <MultiKeywordRequest> format. If a
 136                         NULL is passed in the KeywordString field, all of the known
 137                         keywords in the system for the NameSpaceId specified are
 138                         returned in the Results field.
 139
 140   @param Progress       On return, points to a character in the KeywordString. Points
 141                         to the string's NULL terminator if the request was successful.
 142                         Points to the most recent '&' before the first failing name / value
 143                         pair (or the beginning of the string if the failure is in the first
 144                         name / value pair) if the request was not successful.
 145
 146   @param ProgressErr    If during the processing of the KeywordString there was a
 147                         failure, this parameter gives additional information about the
 148                         possible source of the problem. See the definitions in SetData()
 149                         for valid value definitions.
 150
 151   @param Results        A null-terminated string in <MultiKeywordResp> format is returned
 152                         which has all the values filled in for the keywords in the
 153                         KeywordString. This is a callee-allocated field, and must be freed
 154                         by the caller after being used.
 155
 156   @retval EFI_SUCCESS             The specified action was completed successfully.
 157
 158   @retval EFI_INVALID_PARAMETER   One or more of the following are TRUE:
 159                                   1.Progress, ProgressErr, or Results is NULL.
 160                                   2.Parsing of the KeywordString resulted in an error. See
 161                                     Progress and ProgressErr for more data.
 162
 163
 164   @retval EFI_NOT_FOUND           An element of the KeywordString was not found. See
 165                                   ProgressErr for more data.
 166
 167   @retval EFI_NOT_FOUND           The NamespaceId specified was not found.  See ProgressErr
 168                                   for more data.
 169
 170   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.  See
 171                                   ProgressErr for more data.
 172
 173   @retval EFI_ACCESS_DENIED       The action violated system policy.  See ProgressErr for
 174                                   more data.
 175
 176   @retval EFI_DEVICE_ERROR        An unexpected system error occurred.  See ProgressErr
 177                                   for more data.
 178
 179 **/
 180 typedef
 181 EFI_STATUS
 182 (EFIAPI *EFI_CONFIG_KEYWORD_HANDLER_GET_DATA) (
 183   IN EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL  *This,
 184   IN CONST EFI_STRING                     NameSpaceId, OPTIONAL
 185   IN CONST EFI_STRING                     KeywordString, OPTIONAL
 186   OUT EFI_STRING                          *Progress,
 187   OUT UINT32                              *ProgressErr,
 188   OUT EFI_STRING                          *Results
 189   );
 190
 191 ///
 192 /// The EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL provides the mechanism
 193 /// to set and get the values associated with a keyword exposed
 194 /// through a x-UEFI- prefixed configuration language namespace
 195 ///
 196
 197 struct _EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL {
 198   EFI_CONFIG_KEYWORD_HANDLER_SET_DATA  SetData;
 199   EFI_CONFIG_KEYWORD_HANDLER_GET_DATA  GetData;
 200 };
 201
 202 extern EFI_GUID gEfiConfigKeywordHandlerProtocolGuid;
 203
 204 #endif
 205