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 - 2010, 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   Reports whether an environment variable is Volatile or Non-Volatile
  32
  33   This will use the Runtime Services call GetVariable to to search for the variable.
  34
  35   @param EnvVarName             The name of the environment variable in question
  36
  37   @retval TRUE                  This environment variable is Volatile
  38   @retval FALSE                 This environment variable is NON-Volatile
  39 **/
  40 BOOLEAN
  41 EFIAPI
  42 IsVolatileEnv (
  43   IN CONST CHAR16 *EnvVarName
  44   );
  45
  46 /**
  47   Delete a Non-Violatile environment variable.
  48
  49   This will use the Runtime Services call SetVariable to remove a non-violatile variable.
  50
  51   @param EnvVarName             The name of the environment variable in question
  52
  53   @retval EFI_SUCCESS           The variable was deleted sucessfully
  54   @retval other                 An error ocurred
  55   @sa SetVariable
  56 **/
  57 #define SHELL_DELETE_ENVIRONMENT_VARIABLE(EnvVarName) \
  58   (gRT->SetVariable((CHAR16*)EnvVarName, \
  59   &gShellVariableGuid,          \
  60   0,                            \
  61   0,                            \
  62   NULL))
  63
  64 /**
  65   Set a Non-Violatile environment variable.
  66
  67   This will use the Runtime Services call SetVariable to set a non-violatile variable.
  68
  69   @param EnvVarName             The name of the environment variable in question
  70   @param BufferSize             UINTN size of Buffer
  71   @param Buffer                 Pointer to value to set variable to
  72
  73   @retval EFI_SUCCESS           The variable was changed sucessfully
  74   @retval other                 An error ocurred
  75   @sa SetVariable
  76 **/
  77 #define SHELL_SET_ENVIRONMENT_VARIABLE_NV(EnvVarName,BufferSize,Buffer)  \
  78   (gRT->SetVariable((CHAR16*)EnvVarName,                          \
  79   &gShellVariableGuid,                                            \
  80   EFI_VARIABLE_NON_VOLATILE|EFI_VARIABLE_BOOTSERVICE_ACCESS,      \
  81   BufferSize,                                                     \
  82   (VOID*)Buffer))
  83
  84 /**
  85   Get an environment variable.
  86
  87   This will use the Runtime Services call GetVariable to get a variable.
  88
  89   @param EnvVarName             The name of the environment variable in question
  90   @param BufferSize             Pointer to the UINTN size of Buffer
  91   @param Buffer                 Pointer buffer to get variable value into
  92
  93   @retval EFI_SUCCESS           The variable's value was retrieved sucessfully
  94   @retval other                 An error ocurred
  95   @sa SetVariable
  96 **/
  97 #define SHELL_GET_ENVIRONMENT_VARIABLE(EnvVarName,BufferSize,Buffer)    \
  98   (gRT->GetVariable((CHAR16*)EnvVarName,                        \
  99   &gShellVariableGuid,                                          \
 100   0,                                                            \
 101   BufferSize,                                                   \
 102   Buffer))
 103
 104 /**
 105   Get an environment variable.
 106
 107   This will use the Runtime Services call GetVariable to get a variable.
 108
 109   @param EnvVarName             The name of the environment variable in question
 110   @param Atts                   Pointer to the UINT32 for attributes (or NULL)
 111   @param BufferSize             Pointer to the UINTN size of Buffer
 112   @param Buffer                 Pointer buffer to get variable value into
 113
 114   @retval EFI_SUCCESS           The variable's value was retrieved sucessfully
 115   @retval other                 An error ocurred
 116   @sa SetVariable
 117 **/
 118 #define SHELL_GET_ENVIRONMENT_VARIABLE_AND_ATTRIBUTES(EnvVarName,Atts,BufferSize,Buffer)    \
 119   (gRT->GetVariable((CHAR16*)EnvVarName,                        \
 120   &gShellVariableGuid,                                          \
 121   Atts,                                                            \
 122   BufferSize,                                                   \
 123   Buffer))
 124
 125 /**
 126   Set a Violatile environment variable.
 127
 128   This will use the Runtime Services call SetVariable to set a violatile variable.
 129
 130   @param EnvVarName             The name of the environment variable in question
 131   @param BufferSize             UINTN size of Buffer
 132   @param Buffer                 Pointer to value to set variable to
 133
 134   @retval EFI_SUCCESS           The variable was changed sucessfully
 135   @retval other                 An error ocurred
 136   @sa SetVariable
 137 **/
 138 #define SHELL_SET_ENVIRONMENT_VARIABLE_V(EnvVarName,BufferSize,Buffer) \
 139   (gRT->SetVariable((CHAR16*)EnvVarName,                      \
 140   &gShellVariableGuid,                                        \
 141   EFI_VARIABLE_BOOTSERVICE_ACCESS,                            \
 142   BufferSize,                                                 \
 143   (VOID*)Buffer))
 144
 145 /**
 146   Creates a list of all Shell-Guid-based environment variables.
 147
 148   @param[in,out] List           The pointer to pointer to LIST_ENTRY object for
 149                                 storing this list.
 150
 151   @retval EFI_SUCCESS           the list was created sucessfully.
 152 **/
 153 EFI_STATUS
 154 EFIAPI
 155 GetEnvironmentVariableList(
 156   IN OUT LIST_ENTRY *List
 157   );
 158
 159 /**
 160   Sets a list of all Shell-Guid-based environment variables.  this will
 161   also eliminate all pre-existing shell environment variables (even if they
 162   are not on the list).
 163
 164   This function will also deallocate the memory from List.
 165
 166   @param[in] List               The pointer to LIST_ENTRY from
 167                                 GetShellEnvVarList().
 168
 169   @retval EFI_SUCCESS           The list was Set sucessfully.
 170 **/
 171 EFI_STATUS
 172 EFIAPI
 173 SetEnvironmentVariableList(
 174   IN LIST_ENTRY *List
 175   );
 176
 177 /**
 178   sets all Shell-Guid-based environment variables.  this will
 179   also eliminate all pre-existing shell environment variables (even if they
 180   are not on the list).
 181
 182   @param[in] Environment    Points to a NULL-terminated array of environment
 183                             variables with the format 'x=y', where x is the
 184                             environment variable name and y is the value.
 185
 186   @retval EFI_SUCCESS       The command executed successfully.
 187   @retval EFI_INVALID_PARAMETER The parameter is invalid.
 188   @retval EFI_OUT_OF_RESOURCES Out of resources.
 189
 190   @sa SetEnvironmentVariableList
 191 **/
 192 EFI_STATUS
 193 EFIAPI
 194 SetEnvironmentVariables(
 195   IN CONST CHAR16 **Environment
 196   );
 197
 198 /**
 199   free function for ENV_VAR_LIST objects.
 200
 201   @param[in] List               The pointer to pointer to list.
 202 **/
 203 VOID
 204 EFIAPI
 205 FreeEnvironmentVariableList(
 206   IN LIST_ENTRY *List
 207   );
 208
 209 #endif //_SHELL_ENVIRONMENT_VARIABLE_HEADER_
 210