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 - 2013, Intel Corporation. All rights reserved.<BR>
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.
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.
18 #ifndef _SHELL_COMMAND_LIB_
19 #define _SHELL_COMMAND_LIB_
22 #include <ShellBase.h>
24 #include <Protocol/EfiShell.h>
25 #include <Protocol/EfiShellParameters.h>
26 #include <Protocol/UnicodeCollation.h>
27 #include <Protocol/SimpleFileSystem.h>
29 #include <Library/UefiBootServicesTableLib.h>
32 // The extern global protocol poionters.
34 extern EFI_UNICODE_COLLATION_PROTOCOL
*gUnicodeCollation
;
35 extern CONST CHAR16
* SupportLevel
[];
38 // The map list objects.
42 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
44 CHAR16
*CurrentDirectoryPath
;
47 /// List of Mappings - DeviceName and Drive Letter(ism).
48 extern SHELL_MAP_LIST gShellMapList
;
49 /// Pointer to node of current directory in the mMapList.
50 extern SHELL_MAP_LIST
*gShellCurDir
;
53 Returns the help MAN fileName for a given shell command.
55 @retval !NULL The unicode string of the MAN filename.
56 @retval NULL An error ocurred.
61 (EFIAPI
*SHELL_GET_MAN_FILENAME
)(
66 Runs a shell command on a given command line.
68 The specific operation of a given shell command is specified in the UEFI Shell
69 Specification 2.0, or in the source of the given command.
71 Upon completion of the command run the shell protocol and environment variables
72 may have been updated due to the operation.
74 @param[in] ImageHandle The ImageHandle to the app, or NULL if
75 the command built into shell.
76 @param[in] SystemTable The pointer to the system table.
78 @retval RETURN_SUCCESS The shell command was sucessful.
79 @retval RETURN_UNSUPPORTED The command is not supported.
83 (EFIAPI
*SHELL_RUN_COMMAND
)(
84 IN EFI_HANDLE ImageHandle
,
85 IN EFI_SYSTEM_TABLE
*SystemTable
89 Registers the handlers of type SHELL_RUN_COMMAND and
90 SHELL_GET_MAN_FILENAME for each shell command.
92 If the ShellSupportLevel is greater than the value of
93 PcdShellSupportLevel, then return RETURN_UNSUPPORTED.
95 Registers the the handlers specified by GetHelpInfoHandler and CommandHandler
96 with the command specified by CommandString. If the command named by
97 CommandString has already been registered, then return
98 RETURN_ALREADY_STARTED.
100 If there are not enough resources available to register the handlers, then
101 RETURN_OUT_OF_RESOURCES is returned.
103 If CommandString is NULL, then ASSERT().
104 If GetHelpInfoHandler is NULL, then ASSERT().
105 If CommandHandler is NULL, then ASSERT().
106 If ProfileName is NULL, then ASSERT().
108 @param[in] CommandString The pointer to the command name. This is the
109 name to look for on the command line in
111 @param[in] CommandHandler The pointer to a function that runs the
113 @param[in] GetManFileName The pointer to a function that provides man
115 @param[in] ShellMinSupportLevel The minimum Shell Support Level which has this
117 @param[in] ProfileName The profile name to require for support of this
119 @param[in] CanAffectLE Indicates whether this command's return value
120 can change the LASTERROR environment variable.
121 @param[in] HiiHandle The handle of this command's HII entry.
122 @param[in] ManFormatHelp The HII locator for the help text.
124 @retval RETURN_SUCCESS The handlers were registered.
125 @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to
126 register the shell command.
127 @retval RETURN_UNSUPPORTED The ShellMinSupportLevel was higher than the
128 currently allowed support level.
129 @retval RETURN_ALREADY_STARTED The CommandString represents a command that
130 is already registered. Only one handler set for
131 a given command is allowed.
132 @sa SHELL_GET_MAN_FILENAME
133 @sa SHELL_RUN_COMMAND
137 ShellCommandRegisterCommandName (
138 IN CONST CHAR16
*CommandString
,
139 IN SHELL_RUN_COMMAND CommandHandler
,
140 IN SHELL_GET_MAN_FILENAME GetManFileName
,
141 IN UINT32 ShellMinSupportLevel
,
142 IN CONST CHAR16
*ProfileName
,
143 IN CONST BOOLEAN CanAffectLE
,
144 IN CONST EFI_HANDLE HiiHandle
,
145 IN CONST EFI_STRING_ID ManFormatHelp
149 Checks if a command string has been registered for CommandString, and if so, it runs
150 the previously registered handler for that command with the command line.
152 If CommandString is NULL, then ASSERT().
154 If Sections is specified, then each section name listed will be compared in a case sensitive
155 manner to the section names described in Appendix B UEFI Shell 2.0 Specification. If the section exists,
156 it is appended to the returned help text. If the section does not exist, no
157 information is returned. If Sections is NULL, then all help text information
158 available is returned.
160 @param[in] CommandString The pointer to the command name. This is the name
161 found on the command line in the shell.
162 @param[in, out] RetVal The pointer to the return value from the command handler.
164 @param[in, out] CanAffectLE Indicates whether this command's return value
165 needs to be placed into LASTERROR environment variable.
167 @retval RETURN_SUCCESS The handler was run.
168 @retval RETURN_NOT_FOUND The CommandString did not match a registered
170 @sa SHELL_RUN_COMMAND
174 ShellCommandRunCommandHandler (
175 IN CONST CHAR16
*CommandString
,
176 IN OUT SHELL_STATUS
*RetVal
,
177 IN OUT BOOLEAN
*CanAffectLE OPTIONAL
181 Checks if a command string has been registered for CommandString, and if so, it
182 returns the MAN filename specified for that command.
184 If CommandString is NULL, then ASSERT().
186 @param[in] CommandString The pointer to the command name. This is the name
187 found on the command line in the shell.
189 @retval NULL The CommandString was not a registered command.
190 @retval other The name of the MAN file.
191 @sa SHELL_GET_MAN_FILENAME
195 ShellCommandGetManFileNameHandler (
196 IN CONST CHAR16
*CommandString
202 CHAR16
*CommandString
;
206 Get the list of all available shell internal commands. This is a linked list,
207 via the LIST_ENTRY structure. Enumerate through it using the BaseLib linked
208 list functions. Do not modify the values.
210 @param[in] Sort TRUE to alphabetically sort the values first. FALSE otherwise.
212 @return A linked list of all available shell commands.
216 ShellCommandGetCommandList (
217 IN CONST BOOLEAN Sort
222 CHAR16
*CommandString
;
227 Registers aliases to be set as part of the initialization of the shell application.
229 If Command is NULL, then ASSERT().
230 If Alias is NULL, then ASSERT().
232 @param[in] Command The pointer to the Command.
233 @param[in] Alias The pointer to Alias.
235 @retval RETURN_SUCCESS The handlers were registered.
236 @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to
237 register the shell command.
241 ShellCommandRegisterAlias (
242 IN CONST CHAR16
*Command
,
243 IN CONST CHAR16
*Alias
247 Get the list of all shell alias commands. This is a linked list,
248 via LIST_ENTRY structure. Enumerate through it using the BaseLib linked
249 list functions. Do not modify the values.
251 @return A linked list of all requested shell aliases.
255 ShellCommandGetInitAliasList (
260 Determine if a given alias is on the list of built in aliases.
262 @param[in] Alias The alias to test for.
264 @retval TRUE The alias is a built in alias.
265 @retval FALSE The alias is not a built in alias.
269 ShellCommandIsOnAliasList (
270 IN CONST CHAR16
*Alias
274 Checks if a command is already on the list.
276 @param[in] CommandString The command string to check for on the list.
278 @retval TRUE CommandString represents a registered command.
279 @retval FALSE CommandString does not represent a registered command.
283 ShellCommandIsCommandOnList (
284 IN CONST CHAR16
*CommandString
288 Get the help text for a command.
290 @param[in] CommandString The command name.
292 @retval NULL No help text was found.
293 @return The string of the help text. The caller required to free.
297 ShellCommandGetCommandHelp (
298 IN CONST CHAR16
*CommandString
302 Function to make sure that the above pointers are valid.
311 Function to determine current state of ECHO. Echo determines if lines from scripts
312 and ECHO commands are enabled.
314 @retval TRUE Echo is currently enabled.
315 @retval FALSE Echo is currently disabled.
319 ShellCommandGetEchoState (
324 Function to set current state of ECHO. Echo determines if lines from scripts
325 and ECHO commands are enabled.
327 @param[in] State TRUE to enable Echo, FALSE otherwise.
331 ShellCommandSetEchoState (
338 Indicate that the current shell or script should exit.
340 @param[in] ScriptOnly TRUE if exiting a script; FALSE otherwise.
341 @param[in] ErrorCode The 64 bit error code to return.
345 ShellCommandRegisterExit (
346 IN BOOLEAN ScriptOnly
,
347 IN CONST UINT64 ErrorCode
351 Retrieve the Exit code.
353 @return the value passed into RegisterExit.
357 ShellCommandGetExitCode (
362 Retrieve the Exit indicator.
364 @retval TRUE Exit was indicated.
365 @retval FALSE Exit was not indicated.
369 ShellCommandGetExit (
374 Retrieve the Exit script indicator.
376 If ShellCommandGetExit returns FALSE, then the return from this is undefined.
378 @retval TRUE ScriptOnly was indicated.
379 @retval FALSE ScriptOnly was not indicated.
383 ShellCommandGetScriptExit (
388 LIST_ENTRY Link
; ///< List enumerator items.
389 UINTN Line
; ///< What line of the script file this was on.
390 CHAR16
*Cl
; ///< The original command line.
391 VOID
*Data
; ///< The data structure format dependant upon Command. (not always used)
392 BOOLEAN Reset
; ///< Reset the command (it must be treated like a initial run (but it may have data already))
393 } SCRIPT_COMMAND_LIST
;
396 CHAR16
*ScriptName
; ///< The filename of this script.
397 CHAR16
**Argv
; ///< The parmameters to the script file.
398 UINTN Argc
; ///< The count of parameters.
399 LIST_ENTRY CommandList
; ///< The script converted to a list of commands (SCRIPT_COMMAND_LIST objects).
400 SCRIPT_COMMAND_LIST
*CurrentCommand
; ///< The command currently being operated. If !=NULL must be a member of CommandList.
401 LIST_ENTRY SubstList
; ///< A list of current script loop alias' (ALIAS_LIST objects) (Used for the for %-based replacement).
405 Function to return a pointer to the currently running script file object.
407 @retval NULL A script file is not currently running.
408 @return A pointer to the current script file object.
412 ShellCommandGetCurrentScriptFile (
417 Function to set a new script as the currently running one.
419 This function will correctly stack and unstack nested scripts.
421 @param[in] Script The pointer to new script information structure. If NULL,
422 it removes and de-allocates the topmost Script structure.
424 @return A pointer to the current running script file after this
425 change. It is NULL if removing the final script.
429 ShellCommandSetNewScript (
430 IN SCRIPT_FILE
*Script OPTIONAL
434 Function to cleanup all memory from a SCRIPT_FILE structure.
436 @param[in] Script The pointer to the structure to cleanup.
440 DeleteScriptFileStruct (
441 IN SCRIPT_FILE
*Script
445 Function to get the current Profile string.
447 This is used to retrieve what profiles were installed.
449 @retval NULL There are no installed profiles.
450 @return A semicolon-delimited list of profiles.
454 ShellCommandGetProfileList (
459 MappingTypeFileSystem
,
462 } SHELL_MAPPING_TYPE
;
465 Function to generate the next default mapping name.
467 If the return value is not NULL then it must be callee freed.
469 @param Type What kind of mapping name to make.
471 @retval NULL a memory allocation failed.
472 @return a new map name string
476 ShellCommandCreateNewMappingName(
477 IN CONST SHELL_MAPPING_TYPE Type
481 Function to initialize the table for creating consistent map names.
483 @param[out] Table The pointer to pointer to pointer to DevicePathProtocol object.
485 @retval EFI_SUCCESS The table was created successfully.
489 ShellCommandConsistMappingInitialize (
490 EFI_DEVICE_PATH_PROTOCOL
***Table
494 Function to uninitialize the table for creating consistent map names.
496 The parameter must have been received from ShellCommandConsistMappingInitialize.
498 @param[out] Table The pointer to pointer to DevicePathProtocol object.
500 @retval EFI_SUCCESS The table was deleted successfully.
504 ShellCommandConsistMappingUnInitialize (
505 EFI_DEVICE_PATH_PROTOCOL
**Table
509 Create a consistent mapped name for the device specified by DevicePath
512 This must be called after ShellCommandConsistMappingInitialize() and
513 before ShellCommandConsistMappingUnInitialize() is called.
515 @param[in] DevicePath The pointer to the dev path for the device.
516 @param[in] Table The Table of mapping information.
518 @retval NULL A consistent mapped name could not be created.
519 @return A pointer to a string allocated from pool with the device name.
523 ShellCommandConsistMappingGenMappingName (
524 IN EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
525 IN EFI_DEVICE_PATH_PROTOCOL
**Table
529 Function to search the list of mappings for the first matching node on the
530 list based on the MapKey.
532 @param[in] MapKey The pointer to the string key to search for in the map.
534 @return the node on the list.
538 ShellCommandFindMapItem (
539 IN CONST CHAR16
*MapKey
543 Function to add a map node to the list of map items and update the "path" environment variable (optionally).
545 If Path is TRUE (during initialization only), the path environment variable will also be updated to include
546 default paths on the new map name...
548 Path should be FALSE when this function is called from the protocol SetMap function.
550 @param[in] Name The human readable mapped name.
551 @param[in] DevicePath The Device Path for this map.
552 @param[in] Flags The Flags attribute for this map item.
553 @param[in] Path TRUE to update path, FALSE to skip this step (should only be TRUE during initialization).
555 @retval EFI_SUCCESS The addition was sucessful.
556 @retval EFI_OUT_OF_RESOURCES A memory allocation failed.
557 @retval EFI_INVALID_PARAMETER A parameter was invalid.
561 ShellCommandAddMapItemAndUpdatePath(
562 IN CONST CHAR16
*Name
,
563 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
564 IN CONST UINT64 Flags
,
565 IN CONST BOOLEAN Path
569 Creates the default map names for each device path in the system with
570 a protocol depending on the Type.
572 Also sets up the default path environment variable if Type is FileSystem.
574 @retval EFI_SUCCESS All map names were created sucessfully.
575 @retval EFI_NOT_FOUND No protocols were found in the system.
576 @return Error returned from gBS->LocateHandle().
582 ShellCommandCreateInitialMappingsAndPaths(
587 Converts a SHELL_FILE_HANDLE to an EFI_FILE_PROTOCOL*.
589 @param[in] Handle The SHELL_FILE_HANDLE to convert.
591 @return a EFI_FILE_PROTOCOL* representing the same file.
595 ConvertShellHandleToEfiFileProtocol(
596 IN CONST SHELL_FILE_HANDLE Handle
600 Remove a SHELL_FILE_HANDLE frmo the list of SHELL_FILE_HANDLES.
602 @param[in] Handle The SHELL_FILE_HANDLE to remove.
604 @retval TRUE The item was removed.
605 @retval FALSE The item was not found.
609 ShellFileHandleRemove(
610 IN CONST SHELL_FILE_HANDLE Handle
614 Converts a EFI_FILE_PROTOCOL* to an SHELL_FILE_HANDLE.
616 @param[in] Handle The pointer to EFI_FILE_PROTOCOL to convert.
617 @param[in] Path The path to the file for verification.
619 @return a SHELL_FILE_HANDLE representing the same file.
623 ConvertEfiFileProtocolToShellHandle(
624 IN CONST EFI_FILE_PROTOCOL
*Handle
,
625 IN CONST CHAR16
*Path
629 Find the path that was logged with the specified SHELL_FILE_HANDLE.
631 @param[in] Handle The SHELL_FILE_HANDLE to query on.
633 @return A pointer to the path for the file.
637 ShellFileHandleGetPath(
638 IN CONST SHELL_FILE_HANDLE Handle
643 Function to determine if a SHELL_FILE_HANDLE is at the end of the file.
645 This will NOT work on directories.
647 If Handle is NULL, then ASSERT.
649 @param[in] Handle the file handle
651 @retval TRUE the position is at the end of the file
652 @retval FALSE the position is not at the end of the file
657 IN SHELL_FILE_HANDLE Handle
666 Frees any BUFFER_LIST defined type.
668 @param[in] List The pointer to the list head.
676 #endif //_SHELL_COMMAND_LIB_