ShellPkg/Library/UefiShellLevel3CommandsLib/Help.c

   1 /** @file
   2   Main file for Help shell level 3 function.
   3
   4   Copyright (c) 2009 - 2014, Intel Corporation. All rights reserved. <BR>
   5   Copyright (c) 2014, ARM Limited. All rights reserved. <BR>
   6   (C) Copyright 2015 Hewlett-Packard Development Company, L.P.<BR>
   7
   8   This program and the accompanying materials
   9   are licensed and made available under the terms and conditions of the BSD License
  10   which accompanies this distribution.  The full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16 **/
  17
  18 #include "UefiShellLevel3CommandsLib.h"
  19
  20 #include <Library/ShellLib.h>
  21 #include <Library/HandleParsingLib.h>
  22
  23 #include <Protocol/EfiShellDynamicCommand.h>
  24
  25 /**
  26   Attempt to print help from a dynamically added command.
  27
  28   @param[in]  CommandToGetHelpOn  The unicode name of the command that help is
  29                                   requested on.
  30   @param[in]  SectionToGetHelpOn  Pointer to the section specifier(s).
  31   @param[in]  PrintCommandText    Print the command followed by the help content
  32                                   or just help.
  33
  34   @retval EFI_SUCCESS             The help was displayed
  35   @retval EFI_NOT_FOUND           The command name could not be found
  36   @retval EFI_DEVICE_ERROR        The help data format was incorrect.
  37 **/
  38 EFI_STATUS
  39 EFIAPI
  40 PrintDynamicCommandHelp(
  41   IN CHAR16  *CommandToGetHelpOn,
  42   IN CHAR16  *SectionToGetHelpOn,
  43   IN BOOLEAN  PrintCommandText
  44  )
  45 {
  46   EFI_STATUS                          Status;
  47   BOOLEAN                             Found;
  48   EFI_HANDLE                          *CommandHandleList;
  49   EFI_HANDLE                          *NextCommand;
  50   EFI_SHELL_DYNAMIC_COMMAND_PROTOCOL  *DynamicCommand;
  51
  52   Status = EFI_NOT_FOUND;
  53   Found = FALSE;
  54   CommandHandleList = NULL;
  55
  56   CommandHandleList = GetHandleListByProtocol(&gEfiShellDynamicCommandProtocolGuid);
  57
  58   if (CommandHandleList == NULL) {
  59     //
  60     // not found or out of resources
  61     //
  62     return Status;
  63   }
  64
  65   for (NextCommand = CommandHandleList; *NextCommand != NULL; NextCommand++) {
  66     Status = gBS->HandleProtocol(
  67       *NextCommand,
  68       &gEfiShellDynamicCommandProtocolGuid,
  69       (VOID **)&DynamicCommand
  70       );
  71
  72     if (EFI_ERROR(Status)) {
  73       continue;
  74     }
  75
  76     //
  77     // Check execution break flag when printing multiple command help information.
  78     //
  79     if (ShellGetExecutionBreakFlag ()) {
  80       break;
  81     }
  82
  83     if ((gUnicodeCollation->MetaiMatch (gUnicodeCollation, (CHAR16 *)DynamicCommand->CommandName, CommandToGetHelpOn)) ||
  84       (gEfiShellProtocol->GetAlias (CommandToGetHelpOn, NULL) != NULL && (gUnicodeCollation->MetaiMatch (gUnicodeCollation, (CHAR16 *)DynamicCommand->CommandName, (CHAR16*)(gEfiShellProtocol->GetAlias(CommandToGetHelpOn, NULL)))))) {
  85       // Print as Shell Help if in ManPage format.
  86       Status = ShellPrintHelp (DynamicCommand->CommandName, SectionToGetHelpOn,
  87                               PrintCommandText);
  88       if (Status == EFI_DEVICE_ERROR) {
  89         ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_HELP_INV),
  90                         gShellLevel3HiiHandle, DynamicCommand->CommandName);
  91       } else if (EFI_ERROR(Status)) {
  92         ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_HELP_NF),
  93                         gShellLevel3HiiHandle, DynamicCommand->CommandName);
  94       } else {
  95         Found = TRUE;
  96       }
  97     }
  98   }
  99
 100   return (Found ? EFI_SUCCESS : Status);
 101
 102 }
 103
 104 STATIC CONST SHELL_PARAM_ITEM ParamList[] = {
 105   {L"-usage", TypeFlag},
 106   {L"-section", TypeMaxValue},
 107   {L"-verbose", TypeFlag},
 108   {L"-v", TypeFlag},
 109   {NULL, TypeMax}
 110   };
 111
 112 /**
 113   Function for 'help' command.
 114
 115   @param[in] ImageHandle  Handle to the Image (NULL if Internal).
 116   @param[in] SystemTable  Pointer to the System Table (NULL if Internal).
 117 **/
 118 SHELL_STATUS
 119 EFIAPI
 120 ShellCommandRunHelp (
 121   IN EFI_HANDLE        ImageHandle,
 122   IN EFI_SYSTEM_TABLE  *SystemTable
 123   )
 124 {
 125   EFI_STATUS          Status;
 126   LIST_ENTRY          *Package;
 127   CHAR16              *ProblemParam;
 128   SHELL_STATUS        ShellStatus;
 129   CONST COMMAND_LIST  *CommandList;
 130   CONST COMMAND_LIST  *Node;
 131   CHAR16              *CommandToGetHelpOn;
 132   CHAR16              *SectionToGetHelpOn;
 133   CHAR16              *HiiString;
 134   BOOLEAN             Found;
 135   BOOLEAN             PrintCommandText;
 136
 137   PrintCommandText    = TRUE;
 138   ProblemParam        = NULL;
 139   ShellStatus         = SHELL_SUCCESS;
 140   CommandToGetHelpOn  = NULL;
 141   SectionToGetHelpOn  = NULL;
 142   Found               = FALSE;
 143
 144   //
 145   // initialize the shell lib (we must be in non-auto-init...)
 146   //
 147   Status = ShellInitialize();
 148   ASSERT_EFI_ERROR(Status);
 149
 150   Status = CommandInit();
 151   ASSERT_EFI_ERROR(Status);
 152
 153   //
 154   // parse the command line
 155   //
 156   Status = ShellCommandLineParse (ParamList, &Package, &ProblemParam, TRUE);
 157   if (EFI_ERROR(Status)) {
 158     if (Status == EFI_VOLUME_CORRUPTED && ProblemParam != NULL) {
 159       ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_GEN_PROBLEM), gShellLevel3HiiHandle, L"help", ProblemParam);
 160       FreePool(ProblemParam);
 161       ShellStatus = SHELL_INVALID_PARAMETER;
 162     } else {
 163       ASSERT(FALSE);
 164     }
 165   } else {
 166     //
 167     // Check for conflicting parameters.
 168     //
 169     if (ShellCommandLineGetFlag(Package, L"-usage")
 170       &&ShellCommandLineGetFlag(Package, L"-section")
 171       &&(ShellCommandLineGetFlag(Package, L"-verbose") || ShellCommandLineGetFlag(Package, L"-v"))
 172      ){
 173       ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_GEN_PARAM_CON), gShellLevel3HiiHandle, L"help");
 174       ShellStatus = SHELL_INVALID_PARAMETER;
 175     } else if (ShellCommandLineGetRawValue(Package, 2) != NULL) {
 176       ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_GEN_TOO_MANY), gShellLevel3HiiHandle, L"help");
 177       ShellStatus = SHELL_INVALID_PARAMETER;
 178     } else {
 179       //
 180       // Get the command name we are getting help on
 181       //
 182       ASSERT(CommandToGetHelpOn == NULL);
 183       StrnCatGrow(&CommandToGetHelpOn, NULL, ShellCommandLineGetRawValue(Package, 1), 0);
 184       if (CommandToGetHelpOn == NULL && ShellCommandLineGetFlag(Package, L"-?")) {
 185         //
 186         // If we dont have a command and we got a simple -?
 187         // we are looking for help on help command.
 188         //
 189         StrnCatGrow(&CommandToGetHelpOn, NULL, L"help", 0);
 190       }
 191
 192       if (CommandToGetHelpOn == NULL) {
 193         StrnCatGrow(&CommandToGetHelpOn, NULL, L"*", 0);
 194         ASSERT(SectionToGetHelpOn == NULL);
 195         StrnCatGrow(&SectionToGetHelpOn, NULL, L"NAME", 0);
 196       } else {
 197         PrintCommandText = FALSE;
 198         ASSERT(SectionToGetHelpOn == NULL);
 199         //
 200         // Get the section name for the given command name
 201         //
 202         if (ShellCommandLineGetFlag(Package, L"-section")) {
 203           StrnCatGrow(&SectionToGetHelpOn, NULL, ShellCommandLineGetValue(Package, L"-section"), 0);
 204         } else if (ShellCommandLineGetFlag(Package, L"-usage")) {
 205           StrnCatGrow(&SectionToGetHelpOn, NULL, L"NAME,SYNOPSIS", 0);
 206         } else if (ShellCommandLineGetFlag(Package, L"-verbose") || ShellCommandLineGetFlag(Package, L"-v")) {
 207         } else {
 208           //
 209           // The output of help <command> will display NAME, SYNOPSIS, OPTIONS, DESCRIPTION, and EXAMPLES sections.
 210           //
 211           StrnCatGrow (&SectionToGetHelpOn, NULL, L"NAME,SYNOPSIS,OPTIONS,DESCRIPTION,EXAMPLES", 0);
 212         }
 213       }
 214
 215       if (gUnicodeCollation->StriColl(gUnicodeCollation, CommandToGetHelpOn, L"special") == 0) {
 216         //
 217         // we need info on the special characters
 218         //
 219         ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_SC_HEADER), gShellLevel3HiiHandle);
 220         HiiString = HiiGetString(gShellLevel3HiiHandle, STRING_TOKEN(STR_HELP_SC_DATA), NULL);
 221         ShellPrintEx(-1, -1, L"%s", HiiString);
 222         FreePool(HiiString);
 223         Found = TRUE;
 224       } else {
 225         CommandList = ShellCommandGetCommandList(TRUE);
 226         ASSERT(CommandList != NULL);
 227         for ( Node = (COMMAND_LIST*)GetFirstNode(&CommandList->Link)
 228             ; CommandList != NULL && !IsListEmpty(&CommandList->Link) && !IsNull(&CommandList->Link, &Node->Link)
 229             ; Node = (COMMAND_LIST*)GetNextNode(&CommandList->Link, &Node->Link)
 230            ){
 231           //
 232           // Checking execution break flag when print multiple command help information.
 233           //
 234           if (ShellGetExecutionBreakFlag ()) {
 235             break;
 236           }
 237           if ((gUnicodeCollation->MetaiMatch(gUnicodeCollation, Node->CommandString, CommandToGetHelpOn)) ||
 238              (gEfiShellProtocol->GetAlias(CommandToGetHelpOn, NULL) != NULL && (gUnicodeCollation->MetaiMatch(gUnicodeCollation, Node->CommandString, (CHAR16*)(gEfiShellProtocol->GetAlias(CommandToGetHelpOn, NULL)))))) {
 239             //
 240             // We have a command to look for help on.
 241             //
 242             Status = ShellPrintHelp(Node->CommandString, SectionToGetHelpOn, PrintCommandText);
 243             if (Status == EFI_DEVICE_ERROR) {
 244                 ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_INV), gShellLevel3HiiHandle, Node->CommandString);
 245             } else if (EFI_ERROR(Status)) {
 246                 ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_NF), gShellLevel3HiiHandle, Node->CommandString);
 247             } else {
 248                 Found = TRUE;
 249             }
 250           }
 251         }
 252
 253         //
 254         // now try to match against the dynamic command list and print help
 255         //
 256         Status = PrintDynamicCommandHelp (CommandToGetHelpOn, SectionToGetHelpOn,
 257                                           PrintCommandText);
 258         if (!EFI_ERROR(Status)) {
 259           Found = TRUE;
 260         }
 261
 262         //
 263         // Search the .man file for Shell applications (Shell external commands).
 264         //
 265         if (!Found) {
 266           Status = ShellPrintHelp(CommandToGetHelpOn, SectionToGetHelpOn, FALSE);
 267           if (Status == EFI_DEVICE_ERROR) {
 268               ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_INV), gShellLevel3HiiHandle, CommandToGetHelpOn);
 269           } else if (EFI_ERROR(Status)) {
 270               ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_NF), gShellLevel3HiiHandle, CommandToGetHelpOn);
 271           } else {
 272             Found = TRUE;
 273           }
 274         }
 275       }
 276
 277       if (!Found) {
 278         ShellStatus = SHELL_NOT_FOUND;
 279       }
 280
 281       //
 282       // free the command line package
 283       //
 284       ShellCommandLineFreeVarList (Package);
 285     }
 286   }
 287
 288   if (CommandToGetHelpOn != NULL && StrCmp(CommandToGetHelpOn, L"*") == 0){
 289     //
 290     // If '*' then the command entered was 'Help' without qualifiers, This footer
 291     // provides additional info on help switches
 292     //
 293     ShellPrintHiiEx(-1, -1, NULL, STRING_TOKEN (STR_HELP_FOOTER), gShellLevel3HiiHandle);
 294   }
 295   if (CommandToGetHelpOn != NULL) {
 296     FreePool(CommandToGetHelpOn);
 297   }
 298   if (SectionToGetHelpOn != NULL) {
 299     FreePool(SectionToGetHelpOn);
 300   }
 301
 302   return (ShellStatus);
 303 }