ShellPkg/Application/Shell/ShellEnvVar.h

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