2 Provides interface to shell internal functions for shell commands.
4 This library is for use ONLY by shell commands linked into the shell application.
5 This library will not funciton if it is used for UEFI Shell 2.0 Applications.
7 Copyright (c) 2009 - 2016, Intel Corporation. All rights reserved.<BR>
8 (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>
9 (C) Copyright 2013-2014 Hewlett-Packard Development Company, L.P.<BR>
10 This program and the accompanying materials
11 are licensed and made available under the terms and conditions of the BSD License
12 which accompanies this distribution. The full text of the license may be found at
13 http://opensource.org/licenses/bsd-license.php.
15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
16 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
20 #ifndef _SHELL_COMMAND_LIB_
21 #define _SHELL_COMMAND_LIB_
24 #include <ShellBase.h>
26 #include <Protocol/EfiShell.h>
27 #include <Protocol/EfiShellParameters.h>
28 #include <Protocol/UnicodeCollation.h>
29 #include <Protocol/SimpleFileSystem.h>
31 #include <Library/UefiBootServicesTableLib.h>
34 // The extern global protocol poionters.
36 extern EFI_UNICODE_COLLATION_PROTOCOL
*gUnicodeCollation
;
37 extern CONST CHAR16
* SupportLevel
[];
40 // The map list objects.
44 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
46 CHAR16
*CurrentDirectoryPath
;
49 /// List of Mappings - DeviceName and Drive Letter(ism).
50 extern SHELL_MAP_LIST gShellMapList
;
51 /// Pointer to node of current directory in the mMapList.
52 extern SHELL_MAP_LIST
*gShellCurDir
;
55 Returns the help MAN fileName for a given shell command.
57 @retval !NULL The unicode string of the MAN filename.
58 @retval NULL An error ocurred.
63 (EFIAPI
*SHELL_GET_MAN_FILENAME
)(
68 Runs a shell command on a given command line.
70 The specific operation of a given shell command is specified in the UEFI Shell
71 Specification 2.0, or in the source of the given command.
73 Upon completion of the command run the shell protocol and environment variables
74 may have been updated due to the operation.
76 @param[in] ImageHandle The ImageHandle to the app, or NULL if
77 the command built into shell.
78 @param[in] SystemTable The pointer to the system table.
80 @retval RETURN_SUCCESS The shell command was sucessful.
81 @retval RETURN_UNSUPPORTED The command is not supported.
85 (EFIAPI
*SHELL_RUN_COMMAND
)(
86 IN EFI_HANDLE ImageHandle
,
87 IN EFI_SYSTEM_TABLE
*SystemTable
91 Registers the handlers of type SHELL_RUN_COMMAND and
92 SHELL_GET_MAN_FILENAME for each shell command.
94 If the ShellSupportLevel is greater than the value of
95 PcdShellSupportLevel, then return RETURN_UNSUPPORTED.
97 Registers the the handlers specified by GetHelpInfoHandler and CommandHandler
98 with the command specified by CommandString. If the command named by
99 CommandString has already been registered, then return
100 RETURN_ALREADY_STARTED.
102 If there are not enough resources available to register the handlers, then
103 RETURN_OUT_OF_RESOURCES is returned.
105 If CommandString is NULL, then ASSERT().
106 If GetHelpInfoHandler is NULL, then ASSERT().
107 If CommandHandler is NULL, then ASSERT().
108 If ProfileName is NULL, then ASSERT().
110 @param[in] CommandString The pointer to the command name. This is the
111 name to look for on the command line in
113 @param[in] CommandHandler The pointer to a function that runs the
115 @param[in] GetManFileName The pointer to a function that provides man
117 @param[in] ShellMinSupportLevel The minimum Shell Support Level which has this
119 @param[in] ProfileName The profile name to require for support of this
121 @param[in] CanAffectLE Indicates whether this command's return value
122 can change the LASTERROR environment variable.
123 @param[in] HiiHandle The handle of this command's HII entry.
124 @param[in] ManFormatHelp The HII locator for the help text.
126 @retval RETURN_SUCCESS The handlers were registered.
127 @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to
128 register the shell command.
129 @retval RETURN_UNSUPPORTED The ShellMinSupportLevel was higher than the
130 currently allowed support level.
131 @retval RETURN_ALREADY_STARTED The CommandString represents a command that
132 is already registered. Only one handler set for
133 a given command is allowed.
134 @sa SHELL_GET_MAN_FILENAME
135 @sa SHELL_RUN_COMMAND
139 ShellCommandRegisterCommandName (
140 IN CONST CHAR16
*CommandString
,
141 IN SHELL_RUN_COMMAND CommandHandler
,
142 IN SHELL_GET_MAN_FILENAME GetManFileName
,
143 IN UINT32 ShellMinSupportLevel
,
144 IN CONST CHAR16
*ProfileName
,
145 IN CONST BOOLEAN CanAffectLE
,
146 IN CONST EFI_HANDLE HiiHandle
,
147 IN CONST EFI_STRING_ID ManFormatHelp
151 Checks if a command string has been registered for CommandString, and if so, it runs
152 the previously registered handler for that command with the command line.
154 If CommandString is NULL, then ASSERT().
156 If Sections is specified, then each section name listed will be compared in a case sensitive
157 manner to the section names described in Appendix B UEFI Shell 2.0 Specification. If the section exists,
158 it is appended to the returned help text. If the section does not exist, no
159 information is returned. If Sections is NULL, then all help text information
160 available is returned.
162 @param[in] CommandString The pointer to the command name. This is the name
163 found on the command line in the shell.
164 @param[in, out] RetVal The pointer to the return value from the command handler.
166 @param[in, out] CanAffectLE Indicates whether this command's return value
167 needs to be placed into LASTERROR environment variable.
169 @retval RETURN_SUCCESS The handler was run.
170 @retval RETURN_NOT_FOUND The CommandString did not match a registered
172 @sa SHELL_RUN_COMMAND
176 ShellCommandRunCommandHandler (
177 IN CONST CHAR16
*CommandString
,
178 IN OUT SHELL_STATUS
*RetVal
,
179 IN OUT BOOLEAN
*CanAffectLE OPTIONAL
183 Checks if a command string has been registered for CommandString, and if so, it
184 returns the MAN filename specified for that command.
186 If CommandString is NULL, then ASSERT().
188 @param[in] CommandString The pointer to the command name. This is the name
189 found on the command line in the shell.
191 @retval NULL The CommandString was not a registered command.
192 @retval other The name of the MAN file.
193 @sa SHELL_GET_MAN_FILENAME
197 ShellCommandGetManFileNameHandler (
198 IN CONST CHAR16
*CommandString
204 CHAR16
*CommandString
;
208 Get the list of all available shell internal commands. This is a linked list,
209 via the LIST_ENTRY structure. Enumerate through it using the BaseLib linked
210 list functions. Do not modify the values.
212 @param[in] Sort TRUE to alphabetically sort the values first. FALSE otherwise.
214 @return A linked list of all available shell commands.
218 ShellCommandGetCommandList (
219 IN CONST BOOLEAN Sort
224 CHAR16
*CommandString
;
229 Registers aliases to be set as part of the initialization of the shell application.
231 If Command is NULL, then ASSERT().
232 If Alias is NULL, then ASSERT().
234 @param[in] Command The pointer to the Command.
235 @param[in] Alias The pointer to Alias.
237 @retval RETURN_SUCCESS The handlers were registered.
238 @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to
239 register the shell command.
243 ShellCommandRegisterAlias (
244 IN CONST CHAR16
*Command
,
245 IN CONST CHAR16
*Alias
249 Get the list of all shell alias commands. This is a linked list,
250 via LIST_ENTRY structure. Enumerate through it using the BaseLib linked
251 list functions. Do not modify the values.
253 @return A linked list of all requested shell aliases.
257 ShellCommandGetInitAliasList (
262 Determine if a given alias is on the list of built in aliases.
264 @param[in] Alias The alias to test for.
266 @retval TRUE The alias is a built in alias.
267 @retval FALSE The alias is not a built in alias.
271 ShellCommandIsOnAliasList (
272 IN CONST CHAR16
*Alias
276 Checks if a command is already on the list.
278 @param[in] CommandString The command string to check for on the list.
280 @retval TRUE CommandString represents a registered command.
281 @retval FALSE CommandString does not represent a registered command.
285 ShellCommandIsCommandOnList (
286 IN CONST CHAR16
*CommandString
290 Get the help text for a command.
292 @param[in] CommandString The command name.
294 @retval NULL No help text was found.
295 @return The string of the help text. The caller required to free.
299 ShellCommandGetCommandHelp (
300 IN CONST CHAR16
*CommandString
304 Function to make sure that the above pointers are valid.
313 Function to determine current state of ECHO. Echo determines if lines from scripts
314 and ECHO commands are enabled.
316 @retval TRUE Echo is currently enabled.
317 @retval FALSE Echo is currently disabled.
321 ShellCommandGetEchoState (
326 Function to set current state of ECHO. Echo determines if lines from scripts
327 and ECHO commands are enabled.
329 @param[in] State TRUE to enable Echo, FALSE otherwise.
333 ShellCommandSetEchoState (
340 Indicate that the current shell or script should exit.
342 @param[in] ScriptOnly TRUE if exiting a script; FALSE otherwise.
343 @param[in] ErrorCode The 64 bit error code to return.
347 ShellCommandRegisterExit (
348 IN BOOLEAN ScriptOnly
,
349 IN CONST UINT64 ErrorCode
353 Retrieve the Exit code.
355 @return the value passed into RegisterExit.
359 ShellCommandGetExitCode (
364 Retrieve the Exit indicator.
366 @retval TRUE Exit was indicated.
367 @retval FALSE Exit was not indicated.
371 ShellCommandGetExit (
376 Retrieve the Exit script indicator.
378 If ShellCommandGetExit returns FALSE, then the return from this is undefined.
380 @retval TRUE ScriptOnly was indicated.
381 @retval FALSE ScriptOnly was not indicated.
385 ShellCommandGetScriptExit (
390 LIST_ENTRY Link
; ///< List enumerator items.
391 UINTN Line
; ///< What line of the script file this was on.
392 CHAR16
*Cl
; ///< The original command line.
393 VOID
*Data
; ///< The data structure format dependant upon Command. (not always used)
394 BOOLEAN Reset
; ///< Reset the command (it must be treated like a initial run (but it may have data already))
395 } SCRIPT_COMMAND_LIST
;
398 CHAR16
*ScriptName
; ///< The filename of this script.
399 CHAR16
**Argv
; ///< The parmameters to the script file.
400 UINTN Argc
; ///< The count of parameters.
401 LIST_ENTRY CommandList
; ///< The script converted to a list of commands (SCRIPT_COMMAND_LIST objects).
402 SCRIPT_COMMAND_LIST
*CurrentCommand
; ///< The command currently being operated. If !=NULL must be a member of CommandList.
403 LIST_ENTRY SubstList
; ///< A list of current script loop alias' (ALIAS_LIST objects) (Used for the for %-based replacement).
407 Function to return a pointer to the currently running script file object.
409 @retval NULL A script file is not currently running.
410 @return A pointer to the current script file object.
414 ShellCommandGetCurrentScriptFile (
419 Function to set a new script as the currently running one.
421 This function will correctly stack and unstack nested scripts.
423 @param[in] Script The pointer to new script information structure. If NULL,
424 it removes and de-allocates the topmost Script structure.
426 @return A pointer to the current running script file after this
427 change. It is NULL if removing the final script.
431 ShellCommandSetNewScript (
432 IN SCRIPT_FILE
*Script OPTIONAL
436 Function to cleanup all memory from a SCRIPT_FILE structure.
438 @param[in] Script The pointer to the structure to cleanup.
442 DeleteScriptFileStruct (
443 IN SCRIPT_FILE
*Script
447 Function to get the current Profile string.
449 This is used to retrieve what profiles were installed.
451 @retval NULL There are no installed profiles.
452 @return A semicolon-delimited list of profiles.
456 ShellCommandGetProfileList (
461 MappingTypeFileSystem
,
464 } SHELL_MAPPING_TYPE
;
467 Function to generate the next default mapping name.
469 If the return value is not NULL then it must be callee freed.
471 @param Type What kind of mapping name to make.
473 @retval NULL a memory allocation failed.
474 @return a new map name string
478 ShellCommandCreateNewMappingName(
479 IN CONST SHELL_MAPPING_TYPE Type
483 Function to initialize the table for creating consistent map names.
485 @param[out] Table The pointer to pointer to pointer to DevicePathProtocol object.
487 @retval EFI_SUCCESS The table was created successfully.
491 ShellCommandConsistMappingInitialize (
492 EFI_DEVICE_PATH_PROTOCOL
***Table
496 Function to uninitialize the table for creating consistent map names.
498 The parameter must have been received from ShellCommandConsistMappingInitialize.
500 @param[out] Table The pointer to pointer to DevicePathProtocol object.
502 @retval EFI_SUCCESS The table was deleted successfully.
506 ShellCommandConsistMappingUnInitialize (
507 EFI_DEVICE_PATH_PROTOCOL
**Table
511 Create a consistent mapped name for the device specified by DevicePath
514 This must be called after ShellCommandConsistMappingInitialize() and
515 before ShellCommandConsistMappingUnInitialize() is called.
517 @param[in] DevicePath The pointer to the dev path for the device.
518 @param[in] Table The Table of mapping information.
520 @retval NULL A consistent mapped name could not be created.
521 @return A pointer to a string allocated from pool with the device name.
525 ShellCommandConsistMappingGenMappingName (
526 IN EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
527 IN EFI_DEVICE_PATH_PROTOCOL
**Table
531 Function to search the list of mappings for the first matching node on the
532 list based on the MapKey.
534 @param[in] MapKey The pointer to the string key to search for in the map.
536 @return the node on the list.
540 ShellCommandFindMapItem (
541 IN CONST CHAR16
*MapKey
545 Function to add a map node to the list of map items and update the "path" environment variable (optionally).
547 If Path is TRUE (during initialization only), the path environment variable will also be updated to include
548 default paths on the new map name...
550 Path should be FALSE when this function is called from the protocol SetMap function.
552 @param[in] Name The human readable mapped name.
553 @param[in] DevicePath The Device Path for this map.
554 @param[in] Flags The Flags attribute for this map item.
555 @param[in] Path TRUE to update path, FALSE to skip this step (should only be TRUE during initialization).
557 @retval EFI_SUCCESS The addition was sucessful.
558 @retval EFI_OUT_OF_RESOURCES A memory allocation failed.
559 @retval EFI_INVALID_PARAMETER A parameter was invalid.
563 ShellCommandAddMapItemAndUpdatePath(
564 IN CONST CHAR16
*Name
,
565 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
566 IN CONST UINT64 Flags
,
567 IN CONST BOOLEAN Path
571 Creates the default map names for each device path in the system with
572 a protocol depending on the Type.
574 Also sets up the default path environment variable if Type is FileSystem.
576 @retval EFI_SUCCESS All map names were created sucessfully.
577 @retval EFI_NOT_FOUND No protocols were found in the system.
578 @return Error returned from gBS->LocateHandle().
584 ShellCommandCreateInitialMappingsAndPaths(
589 Add mappings for any devices without one. Do not change any existing maps.
591 @retval EFI_SUCCESS The operation was successful.
595 ShellCommandUpdateMapping (
600 Converts a SHELL_FILE_HANDLE to an EFI_FILE_PROTOCOL*.
602 @param[in] Handle The SHELL_FILE_HANDLE to convert.
604 @return a EFI_FILE_PROTOCOL* representing the same file.
608 ConvertShellHandleToEfiFileProtocol(
609 IN CONST SHELL_FILE_HANDLE Handle
613 Remove a SHELL_FILE_HANDLE frmo the list of SHELL_FILE_HANDLES.
615 @param[in] Handle The SHELL_FILE_HANDLE to remove.
617 @retval TRUE The item was removed.
618 @retval FALSE The item was not found.
622 ShellFileHandleRemove(
623 IN CONST SHELL_FILE_HANDLE Handle
627 Converts a EFI_FILE_PROTOCOL* to an SHELL_FILE_HANDLE.
629 @param[in] Handle The pointer to EFI_FILE_PROTOCOL to convert.
630 @param[in] Path The path to the file for verification.
632 @return a SHELL_FILE_HANDLE representing the same file.
636 ConvertEfiFileProtocolToShellHandle(
637 IN CONST EFI_FILE_PROTOCOL
*Handle
,
638 IN CONST CHAR16
*Path
642 Find the path that was logged with the specified SHELL_FILE_HANDLE.
644 @param[in] Handle The SHELL_FILE_HANDLE to query on.
646 @return A pointer to the path for the file.
650 ShellFileHandleGetPath(
651 IN CONST SHELL_FILE_HANDLE Handle
656 Function to determine if a SHELL_FILE_HANDLE is at the end of the file.
658 This will NOT work on directories.
660 If Handle is NULL, then ASSERT.
662 @param[in] Handle the file handle
664 @retval TRUE the position is at the end of the file
665 @retval FALSE the position is not at the end of the file
670 IN SHELL_FILE_HANDLE Handle
679 Frees any BUFFER_LIST defined type.
681 @param[in] List The pointer to the list head.
690 Function printing hex output to the console.
692 @param[in] Indent Number of spaces to indent.
693 @param[in] Offset Offset to start with.
694 @param[in] DataSize Length of data.
695 @param[in] UserData Pointer to some data.
706 Dump HEX data into buffer.
708 @param[in] Buffer HEX data to be dumped in Buffer.
709 @param[in] Indent How many spaces to indent the output.
710 @param[in] Offset The offset of the printing.
711 @param[in] DataSize The size in bytes of UserData.
712 @param[in] UserData The data to print out.
722 #endif //_SHELL_COMMAND_LIB_