[mirror_edk2.git] / ShellPkg / Application / Shell / ShellEnvVar.h

/** @file\r
  function definitions for shell environment functions.\r
\r
  the following includes are required:\r
//#include <Guid/ShellVariableGuid.h>\r
//#include <Library/UefiRuntimeServicesTableLib.h>\r
\r
\r
  Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _SHELL_ENVIRONMENT_VARIABLE_HEADER_\r
#define _SHELL_ENVIRONMENT_VARIABLE_HEADER_\r
\r
typedef struct {\r
  LIST_ENTRY  Link;\r
  CHAR16      *Key;\r
  CHAR16      *Val;\r
  UINT32      Atts;\r
} ENV_VAR_LIST;\r
\r
//\r
// The list is used to cache the environment variables.\r
//\r
extern ENV_VAR_LIST    gShellEnvVarList;\r
\r
\r
/**\r
  Reports whether an environment variable is Volatile or Non-Volatile.\r
\r
  @param EnvVarName             The name of the environment variable in question\r
  @param Volatile               Return TRUE if the environment variable is volatile\r
\r
  @retval EFI_SUCCESS           The volatile attribute is returned successfully\r
  @retval others                Some errors happened.\r
**/\r
EFI_STATUS\r
IsVolatileEnv (\r
  IN CONST CHAR16 *EnvVarName,\r
  OUT BOOLEAN     *Volatile\r
  );\r
\r
/**\r
  Delete a Non-Volatile environment variable.\r
\r
  This will use the Runtime Services call SetVariable to remove a non-volatile variable.\r
\r
  @param EnvVarName             The name of the environment variable in question\r
\r
  @retval EFI_SUCCESS           The variable was deleted successfully\r
  @retval other                 An error occurred\r
  @sa SetVariable\r
**/\r
#define SHELL_DELETE_ENVIRONMENT_VARIABLE(EnvVarName) \\r
  (gRT->SetVariable((CHAR16*)EnvVarName, \\r
  &gShellVariableGuid,          \\r
  0,                            \\r
  0,                            \\r
  NULL))\r
\r
/**\r
  Set a Non-Volatile environment variable.\r
\r
  This will use the Runtime Services call SetVariable to set a non-volatile variable.\r
\r
  @param EnvVarName             The name of the environment variable in question\r
  @param BufferSize             UINTN size of Buffer\r
  @param Buffer                 Pointer to value to set variable to\r
\r
  @retval EFI_SUCCESS           The variable was changed successfully\r
  @retval other                 An error occurred\r
  @sa SetVariable\r
**/\r
#define SHELL_SET_ENVIRONMENT_VARIABLE_NV(EnvVarName,BufferSize,Buffer)  \\r
  (gRT->SetVariable((CHAR16*)EnvVarName,                          \\r
  &gShellVariableGuid,                                            \\r
  EFI_VARIABLE_NON_VOLATILE|EFI_VARIABLE_BOOTSERVICE_ACCESS,      \\r
  BufferSize,                                                     \\r
  (VOID*)Buffer))\r
\r
/**\r
  Get an environment variable.\r
\r
  This will use the Runtime Services call GetVariable to get a variable.\r
\r
  @param EnvVarName             The name of the environment variable in question\r
  @param BufferSize             Pointer to the UINTN size of Buffer\r
  @param Buffer                 Pointer buffer to get variable value into\r
\r
  @retval EFI_SUCCESS           The variable's value was retrieved successfully\r
  @retval other                 An error occurred\r
  @sa SetVariable\r
**/\r
#define SHELL_GET_ENVIRONMENT_VARIABLE(EnvVarName,BufferSize,Buffer)    \\r
  (gRT->GetVariable((CHAR16*)EnvVarName,                        \\r
  &gShellVariableGuid,                                          \\r
  0,                                                            \\r
  BufferSize,                                                   \\r
  Buffer))\r
\r
/**\r
  Get an environment variable.\r
\r
  This will use the Runtime Services call GetVariable to get a variable.\r
\r
  @param EnvVarName             The name of the environment variable in question\r
  @param Atts                   Pointer to the UINT32 for attributes (or NULL)\r
  @param BufferSize             Pointer to the UINTN size of Buffer\r
  @param Buffer                 Pointer buffer to get variable value into\r
\r
  @retval EFI_SUCCESS           The variable's value was retrieved successfully\r
  @retval other                 An error occurred\r
  @sa SetVariable\r
**/\r
#define SHELL_GET_ENVIRONMENT_VARIABLE_AND_ATTRIBUTES(EnvVarName,Atts,BufferSize,Buffer)    \\r
  (gRT->GetVariable((CHAR16*)EnvVarName,                        \\r
  &gShellVariableGuid,                                          \\r
  Atts,                                                            \\r
  BufferSize,                                                   \\r
  Buffer))\r
\r
/**\r
  Set a Volatile environment variable.\r
\r
  This will use the Runtime Services call SetVariable to set a volatile variable.\r
\r
  @param EnvVarName             The name of the environment variable in question\r
  @param BufferSize             UINTN size of Buffer\r
  @param Buffer                 Pointer to value to set variable to\r
\r
  @retval EFI_SUCCESS           The variable was changed successfully\r
  @retval other                 An error occurred\r
  @sa SetVariable\r
**/\r
#define SHELL_SET_ENVIRONMENT_VARIABLE_V(EnvVarName,BufferSize,Buffer) \\r
  (gRT->SetVariable((CHAR16*)EnvVarName,                      \\r
  &gShellVariableGuid,                                        \\r
  EFI_VARIABLE_BOOTSERVICE_ACCESS,                            \\r
  BufferSize,                                                 \\r
  (VOID*)Buffer))\r
\r
/**\r
  Creates a list of all Shell-Guid-based environment variables.\r
\r
  @param[in, out] List           The pointer to pointer to LIST_ENTRY object for\r
                                 storing this list.\r
\r
  @retval EFI_SUCCESS           the list was created successfully.\r
**/\r
EFI_STATUS\r
GetEnvironmentVariableList(\r
  IN OUT LIST_ENTRY *List\r
  );\r
\r
/**\r
  Sets a list of all Shell-Guid-based environment variables.  this will\r
  also eliminate all pre-existing shell environment variables (even if they\r
  are not on the list).\r
\r
  This function will also deallocate the memory from List.\r
\r
  @param[in] List               The pointer to LIST_ENTRY from\r
                                GetShellEnvVarList().\r
\r
  @retval EFI_SUCCESS           The list was Set successfully.\r
**/\r
EFI_STATUS\r
SetEnvironmentVariableList(\r
  IN LIST_ENTRY *List\r
  );\r
\r
/**\r
  sets all Shell-Guid-based environment variables.  this will\r
  also eliminate all pre-existing shell environment variables (even if they\r
  are not on the list).\r
\r
  @param[in] Environment    Points to a NULL-terminated array of environment\r
                            variables with the format 'x=y', where x is the\r
                            environment variable name and y is the value.\r
\r
  @retval EFI_SUCCESS       The command executed successfully.\r
  @retval EFI_INVALID_PARAMETER The parameter is invalid.\r
  @retval EFI_OUT_OF_RESOURCES Out of resources.\r
\r
  @sa SetEnvironmentVariableList\r
**/\r
EFI_STATUS\r
SetEnvironmentVariables(\r
  IN CONST CHAR16 **Environment\r
  );\r
\r
/**\r
  free function for ENV_VAR_LIST objects.\r
\r
  @param[in] List               The pointer to pointer to list.\r
**/\r
VOID\r
FreeEnvironmentVariableList(\r
  IN LIST_ENTRY *List\r
  );\r
\r
/**\r
  Find an environment variable in the gShellEnvVarList.\r
\r
  @param Key        The name of the environment variable.\r
  @param Value      The value of the environment variable, the buffer\r
                    shoule be freed by the caller.\r
  @param ValueSize  The size in bytes of the environment variable\r
                    including the tailing CHAR_NULL.\r
  @param Atts       The attributes of the variable.\r
\r
  @retval EFI_SUCCESS       The command executed successfully.\r
  @retval EFI_NOT_FOUND     The environment variable is not found in\r
                            gShellEnvVarList.\r
\r
**/\r
EFI_STATUS\r
ShellFindEnvVarInList (\r
  IN  CONST CHAR16    *Key,\r
  OUT CHAR16          **Value,\r
  OUT UINTN           *ValueSize,\r
  OUT UINT32          *Atts OPTIONAL\r
  );\r
\r
/**\r
  Add an environment variable into gShellEnvVarList.\r
\r
  @param Key        The name of the environment variable.\r
  @param Value      The value of environment variable.\r
  @param ValueSize  The size in bytes of the environment variable\r
                    including the tailing CHAR_NULL\r
  @param Atts       The attributes of the variable.\r
\r
  @retval EFI_SUCCESS  The environment variable was added to list successfully.\r
  @retval others       Some errors happened.\r
\r
**/\r
EFI_STATUS\r
ShellAddEnvVarToList (\r
  IN CONST CHAR16     *Key,\r
  IN CONST CHAR16     *Value,\r
  IN UINTN            ValueSize,\r
  IN UINT32           Atts\r
  );\r
\r
/**\r
  Remove a specified environment variable in gShellEnvVarList.\r
\r
  @param Key        The name of the environment variable.\r
\r
  @retval EFI_SUCCESS       The command executed successfully.\r
  @retval EFI_NOT_FOUND     The environment variable is not found in\r
                            gShellEnvVarList.\r
**/\r
EFI_STATUS\r
ShellRemvoeEnvVarFromList (\r
  IN CONST CHAR16           *Key\r
  );\r
\r
/**\r
  Initialize the gShellEnvVarList and cache all Shell-Guid-based environment\r
  variables.\r
\r
**/\r
EFI_STATUS\r
ShellInitEnvVarList (\r
  VOID\r
  );\r
\r
/**\r
  Destructe the gShellEnvVarList.\r
\r
**/\r
VOID\r
ShellFreeEnvVarList (\r
  VOID\r
  );\r
\r
#endif //_SHELL_ENVIRONMENT_VARIABLE_HEADER_\r
\r
Commit	Line	Data
a405b86d	1	/** @file\r
	2	function definitions for shell environment functions.\r
	3	\r
	4	the following includes are required:\r
	5	//#include <Guid/ShellVariableGuid.h>\r
	6	//#include <Library/UefiRuntimeServicesTableLib.h>\r
	7	\r
	8	\r
ba0014b9	9	Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>\r
56ba3746	10	SPDX-License-Identifier: BSD-2-Clause-Patent\r
a405b86d	11	\r
	12	**/\r
	13	\r
	14	#ifndef _SHELL_ENVIRONMENT_VARIABLE_HEADER_\r
	15	#define _SHELL_ENVIRONMENT_VARIABLE_HEADER_\r
	16	\r
	17	typedef struct {\r
	18	LIST_ENTRY Link;\r
	19	CHAR16 *Key;\r
	20	CHAR16 *Val;\r
	21	UINT32 Atts;\r
	22	} ENV_VAR_LIST;\r
	23	\r
b62bb885 QS	24	//\r
	25	// The list is used to cache the environment variables.\r
	26	//\r
	27	extern ENV_VAR_LIST gShellEnvVarList;\r
	28	\r
	29	\r
a405b86d	30	/**\r
31e5b912	31	Reports whether an environment variable is Volatile or Non-Volatile.\r
a405b86d	32	\r
a405b86d	33	@param EnvVarName The name of the environment variable in question\r
31e5b912	34	@param Volatile Return TRUE if the environment variable is volatile\r
a405b86d	35	\r
31e5b912 RN	36	@retval EFI_SUCCESS The volatile attribute is returned successfully\r
31e5b912 RN	37	@retval others Some errors happened.\r
a405b86d	38	**/\r
31e5b912	39	EFI_STATUS\r
a405b86d	40	IsVolatileEnv (\r
31e5b912 RN	41	IN CONST CHAR16 *EnvVarName,\r
31e5b912 RN	42	OUT BOOLEAN *Volatile\r
a405b86d	43	);\r
	44	\r
	45	/**\r
6a5033ca	46	Delete a Non-Volatile environment variable.\r
a405b86d	47	\r
6a5033ca	48	This will use the Runtime Services call SetVariable to remove a non-volatile variable.\r
a405b86d	49	\r
	50	@param EnvVarName The name of the environment variable in question\r
	51	\r
6a5033ca AC	52	@retval EFI_SUCCESS The variable was deleted successfully\r
6a5033ca AC	53	@retval other An error occurred\r
a405b86d	54	@sa SetVariable\r
	55	**/\r
	56	#define SHELL_DELETE_ENVIRONMENT_VARIABLE(EnvVarName) \\r
	57	(gRT->SetVariable((CHAR16*)EnvVarName, \\r
	58	&gShellVariableGuid, \\r
	59	0, \\r
	60	0, \\r
	61	NULL))\r
	62	\r
	63	/**\r
6a5033ca	64	Set a Non-Volatile environment variable.\r
a405b86d	65	\r
6a5033ca	66	This will use the Runtime Services call SetVariable to set a non-volatile variable.\r
a405b86d	67	\r
	68	@param EnvVarName The name of the environment variable in question\r
	69	@param BufferSize UINTN size of Buffer\r
	70	@param Buffer Pointer to value to set variable to\r
	71	\r
6a5033ca AC	72	@retval EFI_SUCCESS The variable was changed successfully\r
6a5033ca AC	73	@retval other An error occurred\r
a405b86d	74	@sa SetVariable\r
	75	**/\r
	76	#define SHELL_SET_ENVIRONMENT_VARIABLE_NV(EnvVarName,BufferSize,Buffer) \\r
	77	(gRT->SetVariable((CHAR16*)EnvVarName, \\r
	78	&gShellVariableGuid, \\r
	79	EFI_VARIABLE_NON_VOLATILE\|EFI_VARIABLE_BOOTSERVICE_ACCESS, \\r
	80	BufferSize, \\r
	81	(VOID*)Buffer))\r
	82	\r
	83	/**\r
	84	Get an environment variable.\r
	85	\r
	86	This will use the Runtime Services call GetVariable to get a variable.\r
	87	\r
	88	@param EnvVarName The name of the environment variable in question\r
	89	@param BufferSize Pointer to the UINTN size of Buffer\r
	90	@param Buffer Pointer buffer to get variable value into\r
	91	\r
6a5033ca AC	92	@retval EFI_SUCCESS The variable's value was retrieved successfully\r
6a5033ca AC	93	@retval other An error occurred\r
a405b86d	94	@sa SetVariable\r
	95	**/\r
	96	#define SHELL_GET_ENVIRONMENT_VARIABLE(EnvVarName,BufferSize,Buffer) \\r
	97	(gRT->GetVariable((CHAR16*)EnvVarName, \\r
	98	&gShellVariableGuid, \\r
	99	0, \\r
	100	BufferSize, \\r
	101	Buffer))\r
	102	\r
	103	/**\r
	104	Get an environment variable.\r
	105	\r
	106	This will use the Runtime Services call GetVariable to get a variable.\r
	107	\r
	108	@param EnvVarName The name of the environment variable in question\r
	109	@param Atts Pointer to the UINT32 for attributes (or NULL)\r
	110	@param BufferSize Pointer to the UINTN size of Buffer\r
	111	@param Buffer Pointer buffer to get variable value into\r
	112	\r
6a5033ca AC	113	@retval EFI_SUCCESS The variable's value was retrieved successfully\r
6a5033ca AC	114	@retval other An error occurred\r
a405b86d	115	@sa SetVariable\r
	116	**/\r
	117	#define SHELL_GET_ENVIRONMENT_VARIABLE_AND_ATTRIBUTES(EnvVarName,Atts,BufferSize,Buffer) \\r
	118	(gRT->GetVariable((CHAR16*)EnvVarName, \\r
	119	&gShellVariableGuid, \\r
	120	Atts, \\r
	121	BufferSize, \\r
	122	Buffer))\r
	123	\r
	124	/**\r
6a5033ca	125	Set a Volatile environment variable.\r
a405b86d	126	\r
6a5033ca	127	This will use the Runtime Services call SetVariable to set a volatile variable.\r
a405b86d	128	\r
	129	@param EnvVarName The name of the environment variable in question\r
	130	@param BufferSize UINTN size of Buffer\r
	131	@param Buffer Pointer to value to set variable to\r
	132	\r
6a5033ca AC	133	@retval EFI_SUCCESS The variable was changed successfully\r
6a5033ca AC	134	@retval other An error occurred\r
a405b86d	135	@sa SetVariable\r
	136	**/\r
	137	#define SHELL_SET_ENVIRONMENT_VARIABLE_V(EnvVarName,BufferSize,Buffer) \\r
	138	(gRT->SetVariable((CHAR16*)EnvVarName, \\r
	139	&gShellVariableGuid, \\r
	140	EFI_VARIABLE_BOOTSERVICE_ACCESS, \\r
	141	BufferSize, \\r
	142	(VOID*)Buffer))\r
	143	\r
	144	/**\r
	145	Creates a list of all Shell-Guid-based environment variables.\r
	146	\r
4ff7e37b ED	147	@param[in, out] List The pointer to pointer to LIST_ENTRY object for\r
4ff7e37b ED	148	storing this list.\r
a405b86d	149	\r
6a5033ca	150	@retval EFI_SUCCESS the list was created successfully.\r
a405b86d	151	**/\r
a405b86d	152	EFI_STATUS\r
a405b86d	153	GetEnvironmentVariableList(\r
	154	IN OUT LIST_ENTRY *List\r
	155	);\r
	156	\r
	157	/**\r
	158	Sets a list of all Shell-Guid-based environment variables. this will\r
	159	also eliminate all pre-existing shell environment variables (even if they\r
	160	are not on the list).\r
	161	\r
	162	This function will also deallocate the memory from List.\r
	163	\r
	164	@param[in] List The pointer to LIST_ENTRY from\r
	165	GetShellEnvVarList().\r
	166	\r
6a5033ca	167	@retval EFI_SUCCESS The list was Set successfully.\r
a405b86d	168	**/\r
a405b86d	169	EFI_STATUS\r
a405b86d	170	SetEnvironmentVariableList(\r
	171	IN LIST_ENTRY *List\r
	172	);\r
	173	\r
	174	/**\r
	175	sets all Shell-Guid-based environment variables. this will\r
	176	also eliminate all pre-existing shell environment variables (even if they\r
	177	are not on the list).\r
	178	\r
	179	@param[in] Environment Points to a NULL-terminated array of environment\r
	180	variables with the format 'x=y', where x is the\r
	181	environment variable name and y is the value.\r
	182	\r
	183	@retval EFI_SUCCESS The command executed successfully.\r
	184	@retval EFI_INVALID_PARAMETER The parameter is invalid.\r
	185	@retval EFI_OUT_OF_RESOURCES Out of resources.\r
	186	\r
	187	@sa SetEnvironmentVariableList\r
	188	**/\r
	189	EFI_STATUS\r
a405b86d	190	SetEnvironmentVariables(\r
	191	IN CONST CHAR16 **Environment\r
	192	);\r
	193	\r
	194	/**\r
	195	free function for ENV_VAR_LIST objects.\r
	196	\r
	197	@param[in] List The pointer to pointer to list.\r
	198	**/\r
	199	VOID\r
a405b86d	200	FreeEnvironmentVariableList(\r
	201	IN LIST_ENTRY *List\r
	202	);\r
	203	\r
b62bb885 QS	204	/**\r
	205	Find an environment variable in the gShellEnvVarList.\r
	206	\r
	207	@param Key The name of the environment variable.\r
	208	@param Value The value of the environment variable, the buffer\r
	209	shoule be freed by the caller.\r
	210	@param ValueSize The size in bytes of the environment variable\r
	211	including the tailing CHAR_NULL.\r
	212	@param Atts The attributes of the variable.\r
	213	\r
	214	@retval EFI_SUCCESS The command executed successfully.\r
	215	@retval EFI_NOT_FOUND The environment variable is not found in\r
	216	gShellEnvVarList.\r
	217	\r
	218	**/\r
	219	EFI_STATUS\r
	220	ShellFindEnvVarInList (\r
	221	IN CONST CHAR16 *Key,\r
	222	OUT CHAR16 **Value,\r
	223	OUT UINTN *ValueSize,\r
	224	OUT UINT32 *Atts OPTIONAL\r
	225	);\r
	226	\r
	227	/**\r
	228	Add an environment variable into gShellEnvVarList.\r
	229	\r
	230	@param Key The name of the environment variable.\r
	231	@param Value The value of environment variable.\r
	232	@param ValueSize The size in bytes of the environment variable\r
ffbc60a0	233	including the tailing CHAR_NULL\r
b62bb885 QS	234	@param Atts The attributes of the variable.\r
b62bb885 QS	235	\r
ffbc60a0 RN	236	@retval EFI_SUCCESS The environment variable was added to list successfully.\r
	237	@retval others Some errors happened.\r
	238	\r
b62bb885	239	**/\r
ffbc60a0	240	EFI_STATUS\r
b62bb885 QS	241	ShellAddEnvVarToList (\r
	242	IN CONST CHAR16 *Key,\r
	243	IN CONST CHAR16 *Value,\r
	244	IN UINTN ValueSize,\r
	245	IN UINT32 Atts\r
	246	);\r
	247	\r
	248	/**\r
	249	Remove a specified environment variable in gShellEnvVarList.\r
	250	\r
	251	@param Key The name of the environment variable.\r
	252	\r
	253	@retval EFI_SUCCESS The command executed successfully.\r
	254	@retval EFI_NOT_FOUND The environment variable is not found in\r
	255	gShellEnvVarList.\r
	256	**/\r
	257	EFI_STATUS\r
	258	ShellRemvoeEnvVarFromList (\r
	259	IN CONST CHAR16 *Key\r
	260	);\r
	261	\r
	262	/**\r
ba0014b9	263	Initialize the gShellEnvVarList and cache all Shell-Guid-based environment\r
b62bb885	264	variables.\r
ba0014b9	265	\r
b62bb885 QS	266	**/\r
	267	EFI_STATUS\r
	268	ShellInitEnvVarList (\r
	269	VOID\r
	270	);\r
	271	\r
	272	/**\r
	273	Destructe the gShellEnvVarList.\r
	274	\r
	275	**/\r
	276	VOID\r
	277	ShellFreeEnvVarList (\r
	278	VOID\r
	279	);\r
	280	\r
a405b86d	281	#endif //_SHELL_ENVIRONMENT_VARIABLE_HEADER_\r
a405b86d	282	\r