[mirror_edk2.git] / OvmfPkg / Include / Library / SerializeVariablesLib.h

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