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