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