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   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