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