ShellPkg/Application/Shell/ShellParametersProtocol.h

   1 /** @file
   2   Member functions of EFI_SHELL_PARAMETERS_PROTOCOL and functions for creation,
   3   manipulation, and initialization of EFI_SHELL_PARAMETERS_PROTOCOL.
   4
   5   Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  The full text of the license may be found at
   9   http://opensource.org/licenses/bsd-license.php
  10
  11   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _SHELL_PARAMETERS_PROTOCOL_PROVIDER_HEADER_
  17 #define _SHELL_PARAMETERS_PROTOCOL_PROVIDER_HEADER_
  18
  19 #include <Uefi.h>
  20
  21 #include <Protocol/SimpleFileSystem.h>
  22 #include <Protocol/EfiShellParameters.h>
  23 #include <Protocol/LoadedImage.h>
  24
  25 #include <Guid/ShellVariableGuid.h>
  26
  27 #include <Library/UefiBootServicesTableLib.h>
  28 #include <Library/UefiRuntimeServicesTableLib.h>
  29 #include <Library/MemoryAllocationLib.h>
  30 #include <Library/UefiLib.h>
  31 #include <Library/DebugLib.h>
  32 #include <Library/ShellLib.h>
  33 #include <Library/FileHandleLib.h>
  34
  35 #include "ShellEnvVar.h"
  36 #include "FileHandleWrappers.h"
  37 #include "Shell.h"
  38
  39 /**
  40   creates a new EFI_SHELL_PARAMETERS_PROTOCOL instance and populates it and then
  41   installs it on our handle and if there is an existing version of the protocol
  42   that one is cached for removal later.
  43
  44   @param[in,out] NewShellParameters on a successful return, a pointer to pointer
  45                                      to the newly installed interface.
  46   @param[in,out] RootShellInstance  on a successful return, pointer to boolean.
  47                                      TRUE if this is the root shell instance.
  48
  49   @retval EFI_SUCCESS               the operation completed successfully.
  50   @return other                     the operation failed.
  51   @sa ReinstallProtocolInterface
  52   @sa InstallProtocolInterface
  53   @sa ParseCommandLineToArgs
  54 **/
  55 EFI_STATUS
  56 EFIAPI
  57 CreatePopulateInstallShellParametersProtocol (
  58   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  **NewShellParameters,
  59   IN OUT BOOLEAN                        *RootShellInstance
  60   );
  61
  62 /**
  63   frees all memory used by createion and installation of shell parameters protocol
  64   and if there was an old version installed it will restore that one.
  65
  66   @param NewShellParameters the interface of EFI_SHELL_PARAMETERS_PROTOCOL that is
  67   being cleaned up.
  68
  69   @retval EFI_SUCCESS     the cleanup was successful
  70   @return other           the cleanup failed
  71   @sa ReinstallProtocolInterface
  72   @sa UninstallProtocolInterface
  73 **/
  74 EFI_STATUS
  75 EFIAPI
  76 CleanUpShellParametersProtocol (
  77   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  *NewShellParameters
  78   );
  79
  80 /**
  81   Funcion will replace the current Argc and Argv in the ShellParameters protocol
  82   structure by parsing NewCommandLine.  The current values are returned to the
  83   user.
  84
  85   @param[in,out] ShellParameters       pointer to parameter structure to modify
  86   @param[in] NewCommandLine             the new command line to parse and use
  87   @param[out] OldArgv                   pointer to old list of parameters
  88   @param[out] OldArgc                   pointer to old number of items in Argv list
  89
  90   @retval   EFI_SUCCESS                 operation was sucessful, Argv and Argc are valid
  91   @retval   EFI_OUT_OF_RESOURCES        a memory allocation failed.
  92 **/
  93 EFI_STATUS
  94 EFIAPI
  95 UpdateArgcArgv(
  96   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  *ShellParameters,
  97   IN CONST CHAR16                       *NewCommandLine,
  98   OUT CHAR16                            ***OldArgv,
  99   OUT UINTN                             *OldArgc
 100   );
 101
 102 /**
 103   Funcion will replace the current Argc and Argv in the ShellParameters protocol
 104   structure with Argv and Argc.  The current values are de-allocated and the
 105   OldArgv must not be deallocated by the caller.
 106
 107   @param[in,out] ShellParameters       pointer to parameter structure to modify
 108   @param[in] OldArgv                   pointer to old list of parameters
 109   @param[in] OldArgc                   pointer to old number of items in Argv list
 110 **/
 111 VOID
 112 EFIAPI
 113 RestoreArgcArgv(
 114   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  *ShellParameters,
 115   IN CHAR16                             ***OldArgv,
 116   IN UINTN                              *OldArgc
 117   );
 118
 119 /**
 120   Funcion will replace the current StdIn and StdOut in the ShellParameters protocol
 121   structure by parsing NewCommandLine.  The current values are returned to the
 122   user.
 123
 124   If OldStdIn or OldStdOut is NULL then that value is not returned.
 125
 126   @param[in,out] ShellParameters        Pointer to parameter structure to modify.
 127   @param[in] NewCommandLine             The new command line to parse and use.
 128   @param[out] OldStdIn                  Pointer to old StdIn.
 129   @param[out] OldStdOut                 Pointer to old StdOut.
 130   @param[out] OldStdErr                 Pointer to old StdErr.
 131
 132   @retval   EFI_SUCCESS                 Operation was sucessful, Argv and Argc are valid.
 133   @retval   EFI_OUT_OF_RESOURCES        A memory allocation failed.
 134 **/
 135 EFI_STATUS
 136 EFIAPI
 137 UpdateStdInStdOutStdErr(
 138   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  *ShellParameters,
 139   IN CONST CHAR16                       *NewCommandLine,
 140   OUT SHELL_FILE_HANDLE                 *OldStdIn OPTIONAL,
 141   OUT SHELL_FILE_HANDLE                 *OldStdOut OPTIONAL,
 142   OUT SHELL_FILE_HANDLE                 *OldStdErr OPTIONAL
 143   );
 144
 145 /**
 146   Funcion will replace the current StdIn and StdOut in the ShellParameters protocol
 147   structure with StdIn and StdOut.  The current values are de-allocated.
 148
 149   @param[in,out] ShellParameters       pointer to parameter structure to modify
 150   @param[out] OldStdIn                 Pointer to old StdIn.
 151   @param[out] OldStdOut                Pointer to old StdOut.
 152   @param[out] OldStdErr                Pointer to old StdErr.
 153 **/
 154 EFI_STATUS
 155 EFIAPI
 156 RestoreStdInStdOutStdErr (
 157   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  *ShellParameters,
 158   OUT SHELL_FILE_HANDLE                 *OldStdIn OPTIONAL,
 159   OUT SHELL_FILE_HANDLE                 *OldStdOut OPTIONAL,
 160   OUT SHELL_FILE_HANDLE                 *OldStdErr OPTIONAL
 161   );
 162
 163 /**
 164   function to populate Argc and Argv.
 165
 166   This function parses the CommandLine and divides it into standard C style Argc/Argv
 167   parameters for inclusion in EFI_SHELL_PARAMETERS_PROTOCOL.  this supports space
 168   delimited and quote surrounded parameter definition.
 169
 170   @param[in] CommandLine        String of command line to parse
 171   @param[in,out] Argv           pointer to array of strings; one for each parameter
 172   @param[in,out] Argc           pointer to number of strings in Argv array
 173
 174   @return EFI_SUCCESS           the operation was sucessful
 175   @return EFI_OUT_OF_RESOURCES  a memory allocation failed.
 176 **/
 177 EFI_STATUS
 178 EFIAPI
 179 ParseCommandLineToArgs(
 180   IN CONST CHAR16 *CommandLine,
 181   IN OUT CHAR16 ***Argv,
 182   IN OUT UINTN *Argc
 183   );
 184
 185 /**
 186   return the next parameter from a command line string;
 187
 188   This function moves the next parameter from Walker into TempParameter and moves
 189   Walker up past that parameter for recursive calling.  When the final parameter
 190   is moved *Walker will be set to NULL;
 191
 192   Temp Parameter must be large enough to hold the parameter before calling this
 193   function.
 194
 195   @param[in,out] Walker        pointer to string of command line.  Adjusted to
 196                                 reminaing command line on return
 197   @param[in,out] TempParameter pointer to string of command line item extracted.
 198
 199 **/
 200 VOID
 201 EFIAPI
 202 GetNextParameter(
 203   CHAR16 **Walker,
 204   CHAR16 **TempParameter
 205   );
 206
 207 #endif //_SHELL_PARAMETERS_PROTOCOL_PROVIDER_HEADER_
 208