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