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   @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 EFIAPI
 160 GetEnvironmentVariableList(
 161   IN OUT LIST_ENTRY *List
 162   );
 163
 164 /**
 165   Sets a list of all Shell-Guid-based environment variables.  this will
 166   also eliminate all pre-existing shell environment variables (even if they
 167   are not on the list).
 168
 169   This function will also deallocate the memory from List.
 170
 171   @param[in] List               The pointer to LIST_ENTRY from
 172                                 GetShellEnvVarList().
 173
 174   @retval EFI_SUCCESS           The list was Set sucessfully.
 175 **/
 176 EFI_STATUS
 177 EFIAPI
 178 SetEnvironmentVariableList(
 179   IN LIST_ENTRY *List
 180   );
 181
 182 /**
 183   sets all Shell-Guid-based environment variables.  this will
 184   also eliminate all pre-existing shell environment variables (even if they
 185   are not on the list).
 186
 187   @param[in] Environment    Points to a NULL-terminated array of environment
 188                             variables with the format 'x=y', where x is the
 189                             environment variable name and y is the value.
 190
 191   @retval EFI_SUCCESS       The command executed successfully.
 192   @retval EFI_INVALID_PARAMETER The parameter is invalid.
 193   @retval EFI_OUT_OF_RESOURCES Out of resources.
 194
 195   @sa SetEnvironmentVariableList
 196 **/
 197 EFI_STATUS
 198 EFIAPI
 199 SetEnvironmentVariables(
 200   IN CONST CHAR16 **Environment
 201   );
 202
 203 /**
 204   free function for ENV_VAR_LIST objects.
 205
 206   @param[in] List               The pointer to pointer to list.
 207 **/
 208 VOID
 209 EFIAPI
 210 FreeEnvironmentVariableList(
 211   IN LIST_ENTRY *List
 212   );
 213
 214 /**
 215   Find an environment variable in the gShellEnvVarList.
 216
 217   @param Key        The name of the environment variable.
 218   @param Value      The value of the environment variable, the buffer
 219                     shoule be freed by the caller.
 220   @param ValueSize  The size in bytes of the environment variable
 221                     including the tailing CHAR_NULL.
 222   @param Atts       The attributes of the variable.
 223
 224   @retval EFI_SUCCESS       The command executed successfully.
 225   @retval EFI_NOT_FOUND     The environment variable is not found in
 226                             gShellEnvVarList.
 227
 228 **/
 229 EFI_STATUS
 230 ShellFindEnvVarInList (
 231   IN  CONST CHAR16    *Key,
 232   OUT CHAR16          **Value,
 233   OUT UINTN           *ValueSize,
 234   OUT UINT32          *Atts OPTIONAL
 235   );
 236
 237 /**
 238   Add an environment variable into gShellEnvVarList.
 239
 240   @param Key        The name of the environment variable.
 241   @param Value      The value of environment variable.
 242   @param ValueSize  The size in bytes of the environment variable
 243                     including the tailing CHAR_NULL
 244   @param Atts       The attributes of the variable.
 245
 246   @retval EFI_SUCCESS  The environment variable was added to list successfully.
 247   @retval others       Some errors happened.
 248
 249 **/
 250 EFI_STATUS
 251 ShellAddEnvVarToList (
 252   IN CONST CHAR16     *Key,
 253   IN CONST CHAR16     *Value,
 254   IN UINTN            ValueSize,
 255   IN UINT32           Atts
 256   );
 257
 258 /**
 259   Remove a specified environment variable in gShellEnvVarList.
 260
 261   @param Key        The name of the environment variable.
 262
 263   @retval EFI_SUCCESS       The command executed successfully.
 264   @retval EFI_NOT_FOUND     The environment variable is not found in
 265                             gShellEnvVarList.
 266 **/
 267 EFI_STATUS
 268 ShellRemvoeEnvVarFromList (
 269   IN CONST CHAR16           *Key
 270   );
 271
 272 /**
 273   Initialize the gShellEnvVarList and cache all Shell-Guid-based environment
 274   variables.
 275
 276 **/
 277 EFI_STATUS
 278 ShellInitEnvVarList (
 279   VOID
 280   );
 281
 282 /**
 283   Destructe the gShellEnvVarList.
 284
 285 **/
 286 VOID
 287 ShellFreeEnvVarList (
 288   VOID
 289   );
 290
 291 #endif //_SHELL_ENVIRONMENT_VARIABLE_HEADER_
 292