OvmfPkg/Include/Library/SerializeVariablesLib.h

   1 /** @file
   2   Serialize & Deserialize UEFI Variables
   3
   4   Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __SERIALIZE_VARIABLES_LIB__
  16 #define __SERIALIZE_VARIABLES_LIB__
  17
  18
  19 /**
  20   Callback function for each variable
  21
  22   @param[in] Context - Context as sent to the iteration function
  23   @param[in] VariableName - Refer to RuntimeServices GetNextVariableName
  24   @param[in] VendorGuid - Refer to RuntimeServices GetNextVariableName
  25   @param[in] Attributes - Refer to RuntimeServices GetVariable
  26   @param[in] DataSize - Refer to RuntimeServices GetVariable
  27   @param[in] Data - Refer to RuntimeServices GetVariable
  28
  29   @retval RETURN_SUCCESS         Continue iterating through the variables
  30   @return Any RETURN_ERROR       Stop iterating through the variables
  31
  32 **/
  33 typedef
  34 RETURN_STATUS
  35 (EFIAPI *VARIABLE_SERIALIZATION_ITERATION_CALLBACK)(
  36   IN  VOID                         *Context,
  37   IN  CHAR16                       *VariableName,
  38   IN  EFI_GUID                     *VendorGuid,
  39   IN  UINT32                       Attributes,
  40   IN  UINTN                        DataSize,
  41   IN  VOID                         *Data
  42   );
  43
  44
  45 /**
  46   Creates a new variable serialization instance
  47
  48   @param[out]  Handle - Handle for a variable serialization instance
  49
  50   @retval      RETURN_SUCCESS - The variable serialization instance was
  51                  successfully created.
  52   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
  53                  create the variable serialization instance.
  54
  55 **/
  56 RETURN_STATUS
  57 EFIAPI
  58 SerializeVariablesNewInstance (
  59   OUT EFI_HANDLE                      *Handle
  60   );
  61
  62
  63 /**
  64   Free memory associated with a variable serialization instance
  65
  66   @param[in]  Handle - Handle for a variable serialization instance
  67
  68   @retval      RETURN_SUCCESS - The variable serialization instance was
  69                  successfully freed.
  70   @retval      RETURN_INVALID_PARAMETER - Handle was not a valid
  71                  variable serialization instance.
  72
  73 **/
  74 RETURN_STATUS
  75 EFIAPI
  76 SerializeVariablesFreeInstance (
  77   IN EFI_HANDLE Handle
  78   );
  79
  80
  81 /**
  82   Creates a new variable serialization instance using the given
  83   binary representation of the variables to fill the new instance
  84
  85   @param[out] Handle - Handle for a variable serialization instance
  86   @param[in]  Buffer - A buffer with the serialized representation
  87                 of the variables.  Must be the same format as produced
  88                 by SerializeVariablesToBuffer.
  89   @param[in]  Size - This is the size of the binary representation
  90                 of the variables.
  91
  92   @retval      RETURN_SUCCESS - The binary representation was successfully
  93                  imported into a new variable serialization instance
  94   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
  95                  create the new variable serialization instance
  96
  97 **/
  98 RETURN_STATUS
  99 EFIAPI
 100 SerializeVariablesNewInstanceFromBuffer (
 101   OUT EFI_HANDLE                          *Handle,
 102   IN  VOID                                *Buffer,
 103   IN  UINTN                               Size
 104   );
 105
 106
 107 /**
 108   Iterates all variables found with RuntimeServices GetNextVariableName
 109
 110   @param[in]   CallbackFunction - Function called for each variable instance
 111   @param[in]   Context - Passed to each call of CallbackFunction
 112
 113   @retval      RETURN_SUCCESS - All variables were iterated without the
 114                  CallbackFunction returning an error
 115   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
 116                  iterate through the variables
 117   @return      Any of RETURN_ERROR indicates an error reading the variable
 118                  or an error was returned from CallbackFunction
 119
 120 **/
 121 RETURN_STATUS
 122 EFIAPI
 123 SerializeVariablesIterateSystemVariables (
 124   IN VARIABLE_SERIALIZATION_ITERATION_CALLBACK CallbackFunction,
 125   IN VOID                                      *Context
 126   );
 127
 128
 129 /**
 130   Iterates all variables found in the variable serialization instance
 131
 132   @param[in]   Handle - Handle for a variable serialization instance
 133   @param[in]   CallbackFunction - Function called for each variable instance
 134   @param[in]   Context - Passed to each call of CallbackFunction
 135
 136   @retval      RETURN_SUCCESS - All variables were iterated without the
 137                  CallbackFunction returning an error
 138   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
 139                  iterate through the variables
 140   @return      Any of RETURN_ERROR indicates an error reading the variable
 141                  or an error was returned from CallbackFunction
 142
 143 **/
 144 RETURN_STATUS
 145 EFIAPI
 146 SerializeVariablesIterateInstanceVariables (
 147   IN EFI_HANDLE                                Handle,
 148   IN VARIABLE_SERIALIZATION_ITERATION_CALLBACK CallbackFunction,
 149   IN VOID                                      *Context
 150   );
 151
 152
 153 /**
 154   Sets all variables found in the variable serialization instance
 155
 156   @param[in]   Handle - Handle for a variable serialization instance
 157
 158   @retval      RETURN_SUCCESS - All variables were set successfully
 159   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
 160                  set all the variables
 161   @return      Any of RETURN_ERROR indicates an error reading the variables
 162                  or in attempting to set a variable
 163
 164 **/
 165 RETURN_STATUS
 166 EFIAPI
 167 SerializeVariablesSetSerializedVariables (
 168   IN EFI_HANDLE                       Handle
 169   );
 170
 171
 172 /**
 173   Adds a variable to the variable serialization instance
 174
 175   @param[in] Handle - Handle for a variable serialization instance
 176   @param[in] VariableName - Refer to RuntimeServices GetVariable
 177   @param[in] VendorGuid - Refer to RuntimeServices GetVariable
 178   @param[in] Attributes - Refer to RuntimeServices GetVariable
 179   @param[in] DataSize - Refer to RuntimeServices GetVariable
 180   @param[in] Data - Refer to RuntimeServices GetVariable
 181
 182   @retval      RETURN_SUCCESS - All variables were set successfully
 183   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
 184                  add the variable
 185
 186 **/
 187 RETURN_STATUS
 188 EFIAPI
 189 SerializeVariablesAddVariable (
 190   IN EFI_HANDLE                   Handle,
 191   IN CHAR16                       *VariableName,
 192   IN EFI_GUID                     *VendorGuid,
 193   IN UINT32                       Attributes,
 194   IN UINTN                        DataSize,
 195   IN VOID                         *Data
 196   );
 197
 198
 199 /**
 200   Serializes the variables known to this instance into the
 201   provided buffer.
 202
 203   @param[in]     Handle - Handle for a variable serialization instance
 204   @param[out]    Buffer - A buffer to store the binary representation
 205                    of the variables.
 206   @param[in,out] Size - On input this is the size of the buffer.
 207                    On output this is the size of the binary representation
 208                    of the variables.
 209
 210   @retval      RETURN_SUCCESS - The binary representation was successfully
 211                  completed and returned in the buffer.
 212   @retval      RETURN_OUT_OF_RESOURCES - There we not enough resources to
 213                  save the variables to the buffer.
 214   @retval      RETURN_INVALID_PARAMETER - Handle was not a valid
 215                  variable serialization instance or
 216                  Size or Buffer were NULL.
 217
 218 **/
 219 RETURN_STATUS
 220 EFIAPI
 221 SerializeVariablesToBuffer (
 222   IN     EFI_HANDLE                       Handle,
 223   OUT    VOID                             *Buffer,
 224   IN OUT UINTN                            *Size
 225   );
 226
 227
 228 #endif
 229