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 - 2012, 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 "Shell.h"
  20
  21 typedef enum {
  22   Internal_Command,
  23   Script_File_Name,
  24   Efi_Application,
  25   File_Sys_Change,
  26   Unknown_Invalid
  27 } SHELL_OPERATION_TYPES;
  28
  29 /**
  30   creates a new EFI_SHELL_PARAMETERS_PROTOCOL instance and populates it and then
  31   installs it on our handle and if there is an existing version of the protocol
  32   that one is cached for removal later.
  33
  34   @param[in, out] NewShellParameters on a successful return, a pointer to pointer
  35                                      to the newly installed interface.
  36   @param[in, out] RootShellInstance  on a successful return, pointer to boolean.
  37                                      TRUE if this is the root shell instance.
  38
  39   @retval EFI_SUCCESS               the operation completed successfully.
  40   @return other                     the operation failed.
  41   @sa ReinstallProtocolInterface
  42   @sa InstallProtocolInterface
  43   @sa ParseCommandLineToArgs
  44 **/
  45 EFI_STATUS
  46 CreatePopulateInstallShellParametersProtocol (
  47   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  **NewShellParameters,
  48   IN OUT BOOLEAN                        *RootShellInstance
  49   );
  50
  51 /**
  52   frees all memory used by createion and installation of shell parameters protocol
  53   and if there was an old version installed it will restore that one.
  54
  55   @param NewShellParameters the interface of EFI_SHELL_PARAMETERS_PROTOCOL that is
  56   being cleaned up.
  57
  58   @retval EFI_SUCCESS     the cleanup was successful
  59   @return other           the cleanup failed
  60   @sa ReinstallProtocolInterface
  61   @sa UninstallProtocolInterface
  62 **/
  63 EFI_STATUS
  64 CleanUpShellParametersProtocol (
  65   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  *NewShellParameters
  66   );
  67
  68 /**
  69   Funcion will replace the current Argc and Argv in the ShellParameters protocol
  70   structure by parsing NewCommandLine.  The current values are returned to the
  71   user.
  72
  73   @param[in, out] ShellParameters       pointer to parameter structure to modify
  74   @param[in] NewCommandLine             the new command line to parse and use
  75   @param[in] Type                       the type of operation.
  76   @param[out] OldArgv                   pointer to old list of parameters
  77   @param[out] OldArgc                   pointer to old number of items in Argv list
  78
  79   @retval   EFI_SUCCESS                 operation was sucessful, Argv and Argc are valid
  80   @retval   EFI_OUT_OF_RESOURCES        a memory allocation failed.
  81 **/
  82 EFI_STATUS
  83 UpdateArgcArgv(
  84   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  *ShellParameters,
  85   IN CONST CHAR16                       *NewCommandLine,
  86   IN SHELL_OPERATION_TYPES              Type,
  87   OUT CHAR16                            ***OldArgv,
  88   OUT UINTN                             *OldArgc
  89   );
  90
  91 /**
  92   Funcion will replace the current Argc and Argv in the ShellParameters protocol
  93   structure with Argv and Argc.  The current values are de-allocated and the
  94   OldArgv must not be deallocated by the caller.
  95
  96   @param[in, out] ShellParameters       pointer to parameter structure to modify
  97   @param[in] OldArgv                    pointer to old list of parameters
  98   @param[in] OldArgc                    pointer to old number of items in Argv list
  99 **/
 100 VOID
 101 RestoreArgcArgv(
 102   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  *ShellParameters,
 103   IN CHAR16                             ***OldArgv,
 104   IN UINTN                              *OldArgc
 105   );
 106
 107 typedef struct {
 108   EFI_SIMPLE_TEXT_INPUT_PROTOCOL        *ConIn;
 109   EFI_HANDLE                            ConInHandle;
 110   EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL       *ConOut;
 111   EFI_HANDLE                            ConOutHandle;
 112   EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL       *ErrOut;
 113   EFI_HANDLE                            ErrOutHandle;
 114 } SYSTEM_TABLE_INFO;
 115
 116 /**
 117   Funcion will replace the current StdIn and StdOut in the ShellParameters protocol
 118   structure by parsing NewCommandLine.  The current values are returned to the
 119   user.
 120
 121   This will also update the system table.
 122
 123   @param[in, out] ShellParameters        Pointer to parameter structure to modify.
 124   @param[in] NewCommandLine              The new command line to parse and use.
 125   @param[out] OldStdIn                   Pointer to old StdIn.
 126   @param[out] OldStdOut                  Pointer to old StdOut.
 127   @param[out] OldStdErr                  Pointer to old StdErr.
 128   @param[out] SystemTableInfo            Pointer to old system table information.
 129
 130   @retval   EFI_SUCCESS                 Operation was sucessful, Argv and Argc are valid.
 131   @retval   EFI_OUT_OF_RESOURCES        A memory allocation failed.
 132 **/
 133 EFI_STATUS
 134 UpdateStdInStdOutStdErr(
 135   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  *ShellParameters,
 136   IN CHAR16                             *NewCommandLine,
 137   OUT SHELL_FILE_HANDLE                 *OldStdIn,
 138   OUT SHELL_FILE_HANDLE                 *OldStdOut,
 139   OUT SHELL_FILE_HANDLE                 *OldStdErr,
 140   OUT SYSTEM_TABLE_INFO                 *SystemTableInfo
 141   );
 142
 143 /**
 144   Funcion will replace the current StdIn and StdOut in the ShellParameters protocol
 145   structure with StdIn and StdOut.  The current values are de-allocated.
 146
 147   @param[in, out] ShellParameters      Pointer to parameter structure to modify.
 148   @param[in] OldStdIn                  Pointer to old StdIn.
 149   @param[in] OldStdOut                 Pointer to old StdOut.
 150   @param[in] OldStdErr                 Pointer to old StdErr.
 151   @param[in] SystemTableInfo           Pointer to old system table information.
 152 **/
 153 EFI_STATUS
 154 RestoreStdInStdOutStdErr (
 155   IN OUT EFI_SHELL_PARAMETERS_PROTOCOL  *ShellParameters,
 156   IN  SHELL_FILE_HANDLE                 *OldStdIn,
 157   IN  SHELL_FILE_HANDLE                 *OldStdOut,
 158   IN  SHELL_FILE_HANDLE                 *OldStdErr,
 159   IN  SYSTEM_TABLE_INFO                 *SystemTableInfo
 160   );
 161
 162 /**
 163   function to populate Argc and Argv.
 164
 165   This function parses the CommandLine and divides it into standard C style Argc/Argv
 166   parameters for inclusion in EFI_SHELL_PARAMETERS_PROTOCOL.  this supports space
 167   delimited and quote surrounded parameter definition.
 168
 169   @param[in] CommandLine          String of command line to parse
 170   @param[in] StripQuotation       if TRUE then strip the quotation marks surrounding
 171                                   the parameters.
 172   @param[in, out] Argv            pointer to array of strings; one for each parameter
 173   @param[in, out] Argc            pointer to number of strings in Argv array
 174
 175   @return EFI_SUCCESS           the operation was sucessful
 176   @return EFI_OUT_OF_RESOURCES  a memory allocation failed.
 177 **/
 178 EFI_STATUS
 179 ParseCommandLineToArgs(
 180   IN CONST CHAR16 *CommandLine,
 181   IN BOOLEAN      StripQuotation,
 182   IN OUT CHAR16   ***Argv,
 183   IN OUT UINTN    *Argc
 184   );
 185
 186 /**
 187   return the next parameter from a command line string;
 188
 189   This function moves the next parameter from Walker into TempParameter and moves
 190   Walker up past that parameter for recursive calling.  When the final parameter
 191   is moved *Walker will be set to NULL;
 192
 193   Temp Parameter must be large enough to hold the parameter before calling this
 194   function.
 195
 196   @param[in, out] Walker          pointer to string of command line.  Adjusted to
 197                                   reminaing command line on return
 198   @param[in, out] TempParameter   pointer to string of command line item extracted.
 199   @param[in]      Length          Length of (*TempParameter) in bytes
 200   @param[in]      StripQuotation  if TRUE then strip the quotation marks surrounding
 201                                   the parameters.
 202
 203   @return   EFI_INALID_PARAMETER  A required parameter was NULL or pointed to a NULL or empty string.
 204   @return   EFI_NOT_FOUND         A closing " could not be found on the specified string
 205 **/
 206 EFI_STATUS
 207 GetNextParameter(
 208   IN OUT CHAR16   **Walker,
 209   IN OUT CHAR16   **TempParameter,
 210   IN CONST UINTN  Length,
 211   IN BOOLEAN      StripQuotation
 212   );
 213
 214 #endif //_SHELL_PARAMETERS_PROTOCOL_PROVIDER_HEADER_
 215