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