ShellPkg: Apply uncrustify changes

[mirror_edk2.git] / ShellPkg / Library / UefiShellLevel3CommandsLib / Help.c

/** @file\r
  Main file for Help shell level 3 function.\r
\r
  Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved. <BR>\r
  Copyright (c) 2014, ARM Limited. All rights reserved. <BR>\r
  (C) Copyright 2015 Hewlett-Packard Development Company, L.P.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#include "UefiShellLevel3CommandsLib.h"\r
\r
#include <Library/ShellLib.h>\r
#include <Library/HandleParsingLib.h>\r
\r
#include <Protocol/ShellDynamicCommand.h>\r
\r
/**\r
   function to insert string items into a list in the correct alphabetical place\r
\r
   the resultant list is a double NULL terminated list of NULL terminated strings.\r
\r
   upon successful return the memory must be caller freed (unless passed back in\r
   via a loop where it will get reallocated).\r
\r
   @param[in,out] DestList    double pointer to the list. may be NULL.\r
   @param[in,out] DestSize    pointer to the size of list. may be 0, if DestList is NULL.\r
   @param[in]     Item        the item to insert.\r
\r
   @retval EFI_SUCCESS        the operation was successful.\r
**/\r
EFI_STATUS\r
LexicalInsertIntoList (\r
  IN OUT   CHAR16  **DestList,\r
  IN OUT   UINTN   *DestSize,\r
  IN CONST CHAR16  *Item\r
  )\r
{\r
  CHAR16  *NewList;\r
  INTN    LexicalMatchValue;\r
  CHAR16  *LexicalSpot;\r
  UINTN   SizeOfAddedNameInBytes;\r
\r
  //\r
  // If there are none, then just return with success\r
  //\r
  if ((Item == NULL) || (*Item == CHAR_NULL) || (StrLen (Item) == 0)) {\r
    return (EFI_SUCCESS);\r
  }\r
\r
  NewList = *DestList;\r
\r
  SizeOfAddedNameInBytes = StrSize (Item);\r
  NewList                = ReallocatePool (*DestSize, (*DestSize) + SizeOfAddedNameInBytes, NewList);\r
  (*DestSize)            = (*DestSize) + SizeOfAddedNameInBytes;\r
\r
  //\r
  // Find the correct spot in the list\r
  //\r
  for (LexicalSpot = NewList\r
       ; LexicalSpot != NULL && LexicalSpot < NewList + (*DestSize)\r
       ; LexicalSpot += StrLen (LexicalSpot) + 1\r
       )\r
  {\r
    //\r
    // Get Lexical Comparison Value between PrevCommand and Command list entry\r
    //\r
    LexicalMatchValue = gUnicodeCollation->StriColl (\r
                                             gUnicodeCollation,\r
                                             (CHAR16 *)LexicalSpot,\r
                                             (CHAR16 *)Item\r
                                             );\r
    //\r
    // The new item goes before this one.\r
    //\r
    if ((LexicalMatchValue > 0) || (StrLen (LexicalSpot) == 0)) {\r
      if (StrLen (LexicalSpot) != 0) {\r
        //\r
        // Move this and all other items out of the way\r
        //\r
        CopyMem (\r
          LexicalSpot + (SizeOfAddedNameInBytes/sizeof (CHAR16)),\r
          LexicalSpot,\r
          (*DestSize) - SizeOfAddedNameInBytes - ((LexicalSpot - NewList) * sizeof (CHAR16))\r
          );\r
      }\r
\r
      //\r
      // Stick this one in place\r
      //\r
      StrCpyS (LexicalSpot, SizeOfAddedNameInBytes/sizeof (CHAR16), Item);\r
      break;\r
    }\r
  }\r
\r
  *DestList = NewList;\r
  return (EFI_SUCCESS);\r
}\r
\r
/**\r
   function to add each command name from the linked list to the string list.\r
\r
   the resultant list is a double NULL terminated list of NULL terminated strings.\r
\r
   @param[in,out] DestList    double pointer to the list. may be NULL.\r
   @param[in,out] DestSize    pointer to the size of list. may be 0, if DestList is NULL.\r
   @param[in]     SourceList  the double linked list of commands.\r
\r
   @retval EFI_SUCCESS        the operation was successful.\r
**/\r
EFI_STATUS\r
CopyListOfCommandNames (\r
  IN OUT   CHAR16        **DestList,\r
  IN OUT   UINTN         *DestSize,\r
  IN CONST COMMAND_LIST  *SourceList\r
  )\r
{\r
  CONST COMMAND_LIST  *Node;\r
\r
  for ( Node = (COMMAND_LIST *)GetFirstNode (&SourceList->Link)\r
        ; SourceList != NULL && !IsListEmpty (&SourceList->Link) && !IsNull (&SourceList->Link, &Node->Link)\r
        ; Node = (COMMAND_LIST *)GetNextNode (&SourceList->Link, &Node->Link)\r
        )\r
  {\r
    LexicalInsertIntoList (DestList, DestSize, Node->CommandString);\r
  }\r
\r
  return (EFI_SUCCESS);\r
}\r
\r
/**\r
   function to add each dynamic command name to the string list.\r
\r
   the resultant list is a double NULL terminated list of NULL terminated strings.\r
\r
   @param[in,out] DestList    double pointer to the list. may be NULL.\r
   @param[in,out] DestSize    pointer to the size of list. may be 0, if DestList is NULL.\r
\r
   @retval EFI_SUCCESS        the operation was successful.\r
   @return an error from HandleProtocol\r
**/\r
STATIC\r
EFI_STATUS\r
CopyListOfCommandNamesWithDynamic (\r
  IN OUT  CHAR16  **DestList,\r
  IN OUT  UINTN   *DestSize\r
  )\r
{\r
  EFI_HANDLE                          *CommandHandleList;\r
  CONST EFI_HANDLE                    *NextCommand;\r
  EFI_SHELL_DYNAMIC_COMMAND_PROTOCOL  *DynamicCommand;\r
  EFI_STATUS                          Status;\r
\r
  CommandHandleList = GetHandleListByProtocol (&gEfiShellDynamicCommandProtocolGuid);\r
\r
  //\r
  // If there are none, then just return with success\r
  //\r
  if (CommandHandleList == NULL) {\r
    return (EFI_SUCCESS);\r
  }\r
\r
  Status = EFI_SUCCESS;\r
\r
  //\r
  // Append those to the list.\r
  //\r
  for (NextCommand = CommandHandleList; *NextCommand != NULL && !EFI_ERROR (Status); NextCommand++) {\r
    Status = gBS->HandleProtocol (\r
                    *NextCommand,\r
                    &gEfiShellDynamicCommandProtocolGuid,\r
                    (VOID **)&DynamicCommand\r
                    );\r
\r
    if (EFI_ERROR (Status)) {\r
      continue;\r
    }\r
\r
    Status = LexicalInsertIntoList (DestList, DestSize, DynamicCommand->CommandName);\r
  }\r
\r
  SHELL_FREE_NON_NULL (CommandHandleList);\r
  return (Status);\r
}\r
\r
/**\r
  Attempt to print help from a dynamically added command.\r
\r
  @param[in]  CommandToGetHelpOn  The unicode name of the command that help is\r
                                  requested on.\r
  @param[in]  SectionToGetHelpOn  Pointer to the section specifier(s).\r
  @param[in]  PrintCommandText    Print the command followed by the help content\r
                                  or just help.\r
\r
  @retval EFI_SUCCESS             The help was displayed\r
  @retval EFI_NOT_FOUND           The command name could not be found\r
  @retval EFI_DEVICE_ERROR        The help data format was incorrect.\r
**/\r
EFI_STATUS\r
PrintDynamicCommandHelp (\r
  IN CONST CHAR16  *CommandToGetHelpOn,\r
  IN CONST CHAR16  *SectionToGetHelpOn,\r
  IN BOOLEAN       PrintCommandText\r
  )\r
{\r
  EFI_STATUS                          Status;\r
  BOOLEAN                             Found;\r
  EFI_HANDLE                          *CommandHandleList;\r
  EFI_HANDLE                          *NextCommand;\r
  EFI_SHELL_DYNAMIC_COMMAND_PROTOCOL  *DynamicCommand;\r
\r
  Status            = EFI_NOT_FOUND;\r
  Found             = FALSE;\r
  CommandHandleList = NULL;\r
\r
  CommandHandleList = GetHandleListByProtocol (&gEfiShellDynamicCommandProtocolGuid);\r
\r
  if (CommandHandleList == NULL) {\r
    //\r
    // not found or out of resources\r
    //\r
    return Status;\r
  }\r
\r
  for (NextCommand = CommandHandleList; *NextCommand != NULL; NextCommand++) {\r
    Status = gBS->HandleProtocol (\r
                    *NextCommand,\r
                    &gEfiShellDynamicCommandProtocolGuid,\r
                    (VOID **)&DynamicCommand\r
                    );\r
\r
    if (EFI_ERROR (Status)) {\r
      continue;\r
    }\r
\r
    //\r
    // Check execution break flag when printing multiple command help information.\r
    //\r
    if (ShellGetExecutionBreakFlag ()) {\r
      break;\r
    }\r
\r
    if ((gUnicodeCollation->MetaiMatch (gUnicodeCollation, (CHAR16 *)DynamicCommand->CommandName, (CHAR16 *)CommandToGetHelpOn)) ||\r
        ((gEfiShellProtocol->GetAlias (CommandToGetHelpOn, NULL) != NULL) && (gUnicodeCollation->MetaiMatch (gUnicodeCollation, (CHAR16 *)DynamicCommand->CommandName, (CHAR16 *)(gEfiShellProtocol->GetAlias (CommandToGetHelpOn, NULL))))))\r
    {\r
      // Print as Shell Help if in ManPage format.\r
      Status = ShellPrintHelp (\r
                 DynamicCommand->CommandName,\r
                 SectionToGetHelpOn,\r
                 PrintCommandText\r
                 );\r
      if (Status == EFI_DEVICE_ERROR) {\r
        ShellPrintHiiEx (\r
          -1,\r
          -1,\r
          NULL,\r
          STRING_TOKEN (STR_HELP_INV),\r
          gShellLevel3HiiHandle,\r
          DynamicCommand->CommandName\r
          );\r
      } else if (EFI_ERROR (Status)) {\r
        ShellPrintHiiEx (\r
          -1,\r
          -1,\r
          NULL,\r
          STRING_TOKEN (STR_HELP_NF),\r
          gShellLevel3HiiHandle,\r
          DynamicCommand->CommandName\r
          );\r
      } else {\r
        Found = TRUE;\r
      }\r
    }\r
  }\r
\r
  SHELL_FREE_NON_NULL (CommandHandleList);\r
\r
  return (Found ? EFI_SUCCESS : Status);\r
}\r
\r
STATIC CONST SHELL_PARAM_ITEM  ParamList[] = {\r
  { L"-usage",   TypeFlag     },\r
  { L"-section", TypeMaxValue },\r
  { L"-verbose", TypeFlag     },\r
  { L"-v",       TypeFlag     },\r
  { NULL,        TypeMax      }\r
};\r
\r
/**\r
  Function for 'help' command.\r
\r
  @param[in] ImageHandle  Handle to the Image (NULL if Internal).\r
  @param[in] SystemTable  Pointer to the System Table (NULL if Internal).\r
**/\r
SHELL_STATUS\r
EFIAPI\r
ShellCommandRunHelp (\r
  IN EFI_HANDLE        ImageHandle,\r
  IN EFI_SYSTEM_TABLE  *SystemTable\r
  )\r
{\r
  EFI_STATUS    Status;\r
  LIST_ENTRY    *Package;\r
  CHAR16        *ProblemParam;\r
  SHELL_STATUS  ShellStatus;\r
  CHAR16        *SortedCommandList;\r
  CONST CHAR16  *CurrentCommand;\r
  CHAR16        *CommandToGetHelpOn;\r
  CHAR16        *SectionToGetHelpOn;\r
  CHAR16        *HiiString;\r
  BOOLEAN       Found;\r
  BOOLEAN       PrintCommandText;\r
  UINTN         SortedCommandListSize;\r
\r
  PrintCommandText   = TRUE;\r
  ProblemParam       = NULL;\r
  ShellStatus        = SHELL_SUCCESS;\r
  CommandToGetHelpOn = NULL;\r
  SectionToGetHelpOn = NULL;\r
  SortedCommandList  = NULL;\r
  Found              = FALSE;\r
\r
  //\r
  // initialize the shell lib (we must be in non-auto-init...)\r
  //\r
  Status = ShellInitialize ();\r
  ASSERT_EFI_ERROR (Status);\r
\r
  Status = CommandInit ();\r
  ASSERT_EFI_ERROR (Status);\r
\r
  //\r
  // parse the command line\r
  //\r
  Status = ShellCommandLineParse (ParamList, &Package, &ProblemParam, TRUE);\r
  if (EFI_ERROR (Status)) {\r
    if ((Status == EFI_VOLUME_CORRUPTED) && (ProblemParam != NULL)) {\r
      ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_GEN_PROBLEM), gShellLevel3HiiHandle, L"help", ProblemParam);\r
      FreePool (ProblemParam);\r
      ShellStatus = SHELL_INVALID_PARAMETER;\r
    } else {\r
      ASSERT (FALSE);\r
    }\r
  } else {\r
    //\r
    // Check for conflicting parameters.\r
    //\r
    if (  ShellCommandLineGetFlag (Package, L"-usage")\r
       && ShellCommandLineGetFlag (Package, L"-section")\r
       && (ShellCommandLineGetFlag (Package, L"-verbose") || ShellCommandLineGetFlag (Package, L"-v"))\r
          )\r
    {\r
      ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_GEN_PARAM_CON), gShellLevel3HiiHandle, L"help");\r
      ShellStatus = SHELL_INVALID_PARAMETER;\r
    } else if (ShellCommandLineGetRawValue (Package, 2) != NULL) {\r
      ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_GEN_TOO_MANY), gShellLevel3HiiHandle, L"help");\r
      ShellStatus = SHELL_INVALID_PARAMETER;\r
    } else {\r
      //\r
      // Get the command name we are getting help on\r
      //\r
      ASSERT (CommandToGetHelpOn == NULL);\r
      StrnCatGrow (&CommandToGetHelpOn, NULL, ShellCommandLineGetRawValue (Package, 1), 0);\r
      if ((CommandToGetHelpOn == NULL) && ShellCommandLineGetFlag (Package, L"-?")) {\r
        //\r
        // If we dont have a command and we got a simple -?\r
        // we are looking for help on help command.\r
        //\r
        StrnCatGrow (&CommandToGetHelpOn, NULL, L"help", 0);\r
      }\r
\r
      if (CommandToGetHelpOn == NULL) {\r
        StrnCatGrow (&CommandToGetHelpOn, NULL, L"*", 0);\r
        ASSERT (SectionToGetHelpOn == NULL);\r
        StrnCatGrow (&SectionToGetHelpOn, NULL, L"NAME", 0);\r
      } else {\r
        PrintCommandText = FALSE;\r
        ASSERT (SectionToGetHelpOn == NULL);\r
        //\r
        // Get the section name for the given command name\r
        //\r
        if (ShellCommandLineGetFlag (Package, L"-section")) {\r
          StrnCatGrow (&SectionToGetHelpOn, NULL, ShellCommandLineGetValue (Package, L"-section"), 0);\r
        } else if (ShellCommandLineGetFlag (Package, L"-usage")) {\r
          StrnCatGrow (&SectionToGetHelpOn, NULL, L"NAME,SYNOPSIS", 0);\r
        } else if (ShellCommandLineGetFlag (Package, L"-verbose") || ShellCommandLineGetFlag (Package, L"-v")) {\r
        } else {\r
          //\r
          // The output of help <command> will display NAME, SYNOPSIS, OPTIONS, DESCRIPTION, and EXAMPLES sections.\r
          //\r
          StrnCatGrow (&SectionToGetHelpOn, NULL, L"NAME,SYNOPSIS,OPTIONS,DESCRIPTION,EXAMPLES", 0);\r
        }\r
      }\r
\r
      if (gUnicodeCollation->StriColl (gUnicodeCollation, CommandToGetHelpOn, L"special") == 0) {\r
        //\r
        // we need info on the special characters\r
        //\r
        ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_HELP_SC_HEADER), gShellLevel3HiiHandle);\r
        HiiString = HiiGetString (gShellLevel3HiiHandle, STRING_TOKEN (STR_HELP_SC_DATA), NULL);\r
        ShellPrintEx (-1, -1, L"%s", HiiString);\r
        FreePool (HiiString);\r
        Found = TRUE;\r
      } else {\r
        SortedCommandList     = NULL;\r
        SortedCommandListSize = 0;\r
        CopyListOfCommandNames (&SortedCommandList, &SortedCommandListSize, ShellCommandGetCommandList (TRUE));\r
        CopyListOfCommandNamesWithDynamic (&SortedCommandList, &SortedCommandListSize);\r
\r
        for (CurrentCommand = SortedCommandList\r
             ; CurrentCommand != NULL && CurrentCommand < SortedCommandList + SortedCommandListSize/sizeof (CHAR16) && *CurrentCommand != CHAR_NULL\r
             ; CurrentCommand += StrLen (CurrentCommand) + 1\r
             )\r
        {\r
          //\r
          // Checking execution break flag when print multiple command help information.\r
          //\r
          if (ShellGetExecutionBreakFlag ()) {\r
            break;\r
          }\r
\r
          if ((gUnicodeCollation->MetaiMatch (gUnicodeCollation, (CHAR16 *)CurrentCommand, CommandToGetHelpOn)) ||\r
              ((gEfiShellProtocol->GetAlias (CommandToGetHelpOn, NULL) != NULL) && (gUnicodeCollation->MetaiMatch (gUnicodeCollation, (CHAR16 *)CurrentCommand, (CHAR16 *)(gEfiShellProtocol->GetAlias (CommandToGetHelpOn, NULL))))))\r
          {\r
            //\r
            // We have a command to look for help on.\r
            //\r
            Status = ShellPrintHelp (CurrentCommand, SectionToGetHelpOn, PrintCommandText);\r
            if (EFI_ERROR (Status)) {\r
              //\r
              // now try to match against the dynamic command list and print help\r
              //\r
              Status = PrintDynamicCommandHelp (CurrentCommand, SectionToGetHelpOn, PrintCommandText);\r
            }\r
\r
            if (Status == EFI_DEVICE_ERROR) {\r
              ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_HELP_INV), gShellLevel3HiiHandle, CurrentCommand);\r
            } else if (EFI_ERROR (Status)) {\r
              ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_HELP_NF), gShellLevel3HiiHandle, CurrentCommand);\r
            } else {\r
              Found = TRUE;\r
            }\r
          }\r
        }\r
\r
        //\r
        // Search the .man file for Shell applications (Shell external commands).\r
        //\r
        if (!Found) {\r
          Status = ShellPrintHelp (CommandToGetHelpOn, SectionToGetHelpOn, FALSE);\r
          if (Status == EFI_DEVICE_ERROR) {\r
            ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_HELP_INV), gShellLevel3HiiHandle, CommandToGetHelpOn);\r
          } else if (EFI_ERROR (Status)) {\r
            ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_HELP_NF), gShellLevel3HiiHandle, CommandToGetHelpOn);\r
          } else {\r
            Found = TRUE;\r
          }\r
        }\r
      }\r
\r
      if (!Found) {\r
        ShellStatus = SHELL_NOT_FOUND;\r
      }\r
\r
      //\r
      // free the command line package\r
      //\r
      ShellCommandLineFreeVarList (Package);\r
    }\r
  }\r
\r
  if ((CommandToGetHelpOn != NULL) && (StrCmp (CommandToGetHelpOn, L"*") == 0)) {\r
    //\r
    // If '*' then the command entered was 'Help' without qualifiers, This footer\r
    // provides additional info on help switches\r
    //\r
    ShellPrintHiiEx (-1, -1, NULL, STRING_TOKEN (STR_HELP_FOOTER), gShellLevel3HiiHandle);\r
  }\r
\r
  if (CommandToGetHelpOn != NULL) {\r
    FreePool (CommandToGetHelpOn);\r
  }\r
\r
  if (SectionToGetHelpOn != NULL) {\r
    FreePool (SectionToGetHelpOn);\r
  }\r
\r
  SHELL_FREE_NON_NULL (SortedCommandList);\r
\r
  return (ShellStatus);\r
}\r