ShellEnvVar.h 8.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280
  1. /** @file
  2. function definitions for shell environment functions.
  3. the following includes are required:
  4. //#include <Guid/ShellVariableGuid.h>
  5. //#include <Library/UefiRuntimeServicesTableLib.h>
  6. Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
  7. SPDX-License-Identifier: BSD-2-Clause-Patent
  8. **/
  9. #ifndef _SHELL_ENVIRONMENT_VARIABLE_HEADER_
  10. #define _SHELL_ENVIRONMENT_VARIABLE_HEADER_
  11. typedef struct {
  12. LIST_ENTRY Link;
  13. CHAR16 *Key;
  14. CHAR16 *Val;
  15. UINT32 Atts;
  16. } ENV_VAR_LIST;
  17. //
  18. // The list is used to cache the environment variables.
  19. //
  20. extern ENV_VAR_LIST gShellEnvVarList;
  21. /**
  22. Reports whether an environment variable is Volatile or Non-Volatile.
  23. @param EnvVarName The name of the environment variable in question
  24. @param Volatile Return TRUE if the environment variable is volatile
  25. @retval EFI_SUCCESS The volatile attribute is returned successfully
  26. @retval others Some errors happened.
  27. **/
  28. EFI_STATUS
  29. IsVolatileEnv (
  30. IN CONST CHAR16 *EnvVarName,
  31. OUT BOOLEAN *Volatile
  32. );
  33. /**
  34. Delete a Non-Volatile environment variable.
  35. This will use the Runtime Services call SetVariable to remove a non-volatile variable.
  36. @param EnvVarName The name of the environment variable in question
  37. @retval EFI_SUCCESS The variable was deleted successfully
  38. @retval other An error occurred
  39. @sa SetVariable
  40. **/
  41. #define SHELL_DELETE_ENVIRONMENT_VARIABLE(EnvVarName) \
  42. (gRT->SetVariable((CHAR16*)EnvVarName, \
  43. &gShellVariableGuid, \
  44. 0, \
  45. 0, \
  46. NULL))
  47. /**
  48. Set a Non-Volatile environment variable.
  49. This will use the Runtime Services call SetVariable to set a non-volatile variable.
  50. @param EnvVarName The name of the environment variable in question
  51. @param BufferSize UINTN size of Buffer
  52. @param Buffer Pointer to value to set variable to
  53. @retval EFI_SUCCESS The variable was changed successfully
  54. @retval other An error occurred
  55. @sa SetVariable
  56. **/
  57. #define SHELL_SET_ENVIRONMENT_VARIABLE_NV(EnvVarName, BufferSize, Buffer) \
  58. (gRT->SetVariable((CHAR16*)EnvVarName, \
  59. &gShellVariableGuid, \
  60. EFI_VARIABLE_NON_VOLATILE|EFI_VARIABLE_BOOTSERVICE_ACCESS, \
  61. BufferSize, \
  62. (VOID*)Buffer))
  63. /**
  64. Get an environment variable.
  65. This will use the Runtime Services call GetVariable to get a variable.
  66. @param EnvVarName The name of the environment variable in question
  67. @param BufferSize Pointer to the UINTN size of Buffer
  68. @param Buffer Pointer buffer to get variable value into
  69. @retval EFI_SUCCESS The variable's value was retrieved successfully
  70. @retval other An error occurred
  71. @sa SetVariable
  72. **/
  73. #define SHELL_GET_ENVIRONMENT_VARIABLE(EnvVarName, BufferSize, Buffer) \
  74. (gRT->GetVariable((CHAR16*)EnvVarName, \
  75. &gShellVariableGuid, \
  76. 0, \
  77. BufferSize, \
  78. Buffer))
  79. /**
  80. Get an environment variable.
  81. This will use the Runtime Services call GetVariable to get a variable.
  82. @param EnvVarName The name of the environment variable in question
  83. @param Atts Pointer to the UINT32 for attributes (or NULL)
  84. @param BufferSize Pointer to the UINTN size of Buffer
  85. @param Buffer Pointer buffer to get variable value into
  86. @retval EFI_SUCCESS The variable's value was retrieved successfully
  87. @retval other An error occurred
  88. @sa SetVariable
  89. **/
  90. #define SHELL_GET_ENVIRONMENT_VARIABLE_AND_ATTRIBUTES(EnvVarName, Atts, BufferSize, Buffer) \
  91. (gRT->GetVariable((CHAR16*)EnvVarName, \
  92. &gShellVariableGuid, \
  93. Atts, \
  94. BufferSize, \
  95. Buffer))
  96. /**
  97. Set a Volatile environment variable.
  98. This will use the Runtime Services call SetVariable to set a volatile variable.
  99. @param EnvVarName The name of the environment variable in question
  100. @param BufferSize UINTN size of Buffer
  101. @param Buffer Pointer to value to set variable to
  102. @retval EFI_SUCCESS The variable was changed successfully
  103. @retval other An error occurred
  104. @sa SetVariable
  105. **/
  106. #define SHELL_SET_ENVIRONMENT_VARIABLE_V(EnvVarName, BufferSize, Buffer) \
  107. (gRT->SetVariable((CHAR16*)EnvVarName, \
  108. &gShellVariableGuid, \
  109. EFI_VARIABLE_BOOTSERVICE_ACCESS, \
  110. BufferSize, \
  111. (VOID*)Buffer))
  112. /**
  113. Creates a list of all Shell-Guid-based environment variables.
  114. @param[in, out] List The pointer to pointer to LIST_ENTRY object for
  115. storing this list.
  116. @retval EFI_SUCCESS the list was created successfully.
  117. **/
  118. EFI_STATUS
  119. GetEnvironmentVariableList (
  120. IN OUT LIST_ENTRY *List
  121. );
  122. /**
  123. Sets a list of all Shell-Guid-based environment variables. this will
  124. also eliminate all pre-existing shell environment variables (even if they
  125. are not on the list).
  126. This function will also deallocate the memory from List.
  127. @param[in] List The pointer to LIST_ENTRY from
  128. GetShellEnvVarList().
  129. @retval EFI_SUCCESS The list was Set successfully.
  130. **/
  131. EFI_STATUS
  132. SetEnvironmentVariableList (
  133. IN LIST_ENTRY *List
  134. );
  135. /**
  136. sets all Shell-Guid-based environment variables. this will
  137. also eliminate all pre-existing shell environment variables (even if they
  138. are not on the list).
  139. @param[in] Environment Points to a NULL-terminated array of environment
  140. variables with the format 'x=y', where x is the
  141. environment variable name and y is the value.
  142. @retval EFI_SUCCESS The command executed successfully.
  143. @retval EFI_INVALID_PARAMETER The parameter is invalid.
  144. @retval EFI_OUT_OF_RESOURCES Out of resources.
  145. @sa SetEnvironmentVariableList
  146. **/
  147. EFI_STATUS
  148. SetEnvironmentVariables (
  149. IN CONST CHAR16 **Environment
  150. );
  151. /**
  152. free function for ENV_VAR_LIST objects.
  153. @param[in] List The pointer to pointer to list.
  154. **/
  155. VOID
  156. FreeEnvironmentVariableList (
  157. IN LIST_ENTRY *List
  158. );
  159. /**
  160. Find an environment variable in the gShellEnvVarList.
  161. @param Key The name of the environment variable.
  162. @param Value The value of the environment variable, the buffer
  163. shoule be freed by the caller.
  164. @param ValueSize The size in bytes of the environment variable
  165. including the tailing CHAR_NULL.
  166. @param Atts The attributes of the variable.
  167. @retval EFI_SUCCESS The command executed successfully.
  168. @retval EFI_NOT_FOUND The environment variable is not found in
  169. gShellEnvVarList.
  170. **/
  171. EFI_STATUS
  172. ShellFindEnvVarInList (
  173. IN CONST CHAR16 *Key,
  174. OUT CHAR16 **Value,
  175. OUT UINTN *ValueSize,
  176. OUT UINT32 *Atts OPTIONAL
  177. );
  178. /**
  179. Add an environment variable into gShellEnvVarList.
  180. @param Key The name of the environment variable.
  181. @param Value The value of environment variable.
  182. @param ValueSize The size in bytes of the environment variable
  183. including the tailing CHAR_NULL
  184. @param Atts The attributes of the variable.
  185. @retval EFI_SUCCESS The environment variable was added to list successfully.
  186. @retval others Some errors happened.
  187. **/
  188. EFI_STATUS
  189. ShellAddEnvVarToList (
  190. IN CONST CHAR16 *Key,
  191. IN CONST CHAR16 *Value,
  192. IN UINTN ValueSize,
  193. IN UINT32 Atts
  194. );
  195. /**
  196. Remove a specified environment variable in gShellEnvVarList.
  197. @param Key The name of the environment variable.
  198. @retval EFI_SUCCESS The command executed successfully.
  199. @retval EFI_NOT_FOUND The environment variable is not found in
  200. gShellEnvVarList.
  201. **/
  202. EFI_STATUS
  203. ShellRemvoeEnvVarFromList (
  204. IN CONST CHAR16 *Key
  205. );
  206. /**
  207. Initialize the gShellEnvVarList and cache all Shell-Guid-based environment
  208. variables.
  209. **/
  210. EFI_STATUS
  211. ShellInitEnvVarList (
  212. VOID
  213. );
  214. /**
  215. Destructe the gShellEnvVarList.
  216. **/
  217. VOID
  218. ShellFreeEnvVarList (
  219. VOID
  220. );
  221. #endif //_SHELL_ENVIRONMENT_VARIABLE_HEADER_