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 - 2010, 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/DevicePathToText.h>
28 #include <Protocol/SimpleFileSystem.h>
30 #include <Library/UefiBootServicesTableLib.h>
33 // The extern global protocol poionters.
35 extern EFI_SHELL_PROTOCOL
*gEfiShellProtocol
;
36 extern EFI_SHELL_PARAMETERS_PROTOCOL
*gEfiShellParametersProtocol
;
37 extern EFI_UNICODE_COLLATION_PROTOCOL
*gUnicodeCollation
;
38 extern EFI_DEVICE_PATH_TO_TEXT_PROTOCOL
*gDevPathToText
;
39 extern CONST CHAR16
* SupportLevel
[];
42 // The map list objects.
46 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
48 CHAR16
*CurrentDirectoryPath
;
51 /// List of Mappings - DeviceName and Drive Letter(ism).
52 extern SHELL_MAP_LIST gShellMapList
;
53 /// Pointer to node of current directory in the mMapList.
54 extern SHELL_MAP_LIST
*gShellCurDir
;
57 Returns the help MAN fileName for a given shell command.
59 @retval !NULL The unicode string of the MAN filename.
60 @retval NULL An error ocurred.
65 (EFIAPI
*SHELL_GET_MAN_FILENAME
)(
70 Runs a shell command on a given command line.
72 The specific operation of a given shell command is specified in the UEFI Shell
73 Specification 2.0, or in the source of the given command.
75 Upon completion of the command run the shell protocol and environment variables
76 may have been updated due to the operation.
78 @param[in] ImageHandle The ImageHandle to the app, or NULL if
79 the command built into shell.
80 @param[in] SystemTable The pointer to the system table.
82 @retval RETURN_SUCCESS The shell command was sucessful.
83 @retval RETURN_UNSUPPORTED The command is not supported.
87 (EFIAPI
*SHELL_RUN_COMMAND
)(
88 IN EFI_HANDLE ImageHandle
,
89 IN EFI_SYSTEM_TABLE
*SystemTable
93 Registers the handlers of type SHELL_RUN_COMMAND and
94 SHELL_GET_MAN_FILENAME for each shell command.
96 If the ShellSupportLevel is greater than the value of
97 PcdShellSupportLevel, then return RETURN_UNSUPPORTED.
99 Registers the the handlers specified by GetHelpInfoHandler and CommandHandler
100 with the command specified by CommandString. If the command named by
101 CommandString has already been registered, then return
102 RETURN_ALREADY_STARTED.
104 If there are not enough resources available to register the handlers, then
105 RETURN_OUT_OF_RESOURCES is returned.
107 If CommandString is NULL, then ASSERT().
108 If GetHelpInfoHandler is NULL, then ASSERT().
109 If CommandHandler is NULL, then ASSERT().
110 If ProfileName is NULL, then ASSERT().
112 @param[in] CommandString The pointer to the command name. This is the
113 name to look for on the command line in
115 @param[in] CommandHandler The pointer to a function that runs the
117 @param[in] GetManFileName The pointer to a function that provides man
119 @param[in] ShellMinSupportLevel The minimum Shell Support Level which has this
121 @param[in] ProfileName The profile name to require for support of this
123 @param[in] CanAffectLE Indicates whether this command's return value
124 can change the LASTERROR environment variable.
125 @param[in] HiiHandle The handle of this command's HII entry.
126 @param[in] ManFormatHelp The HII locator for the help text.
128 @retval RETURN_SUCCESS The handlers were registered.
129 @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to
130 register the shell command.
131 @retval RETURN_UNSUPPORTED The ShellMinSupportLevel was higher than the
132 currently allowed support level.
133 @retval RETURN_ALREADY_STARTED The CommandString represents a command that
134 is already registered. Only one handler set for
135 a given command is allowed.
136 @sa SHELL_GET_MAN_FILENAME
137 @sa SHELL_RUN_COMMAND
141 ShellCommandRegisterCommandName (
142 IN CONST CHAR16
*CommandString
,
143 IN SHELL_RUN_COMMAND CommandHandler
,
144 IN SHELL_GET_MAN_FILENAME GetManFileName
,
145 IN UINT32 ShellMinSupportLevel
,
146 IN CONST CHAR16
*ProfileName
,
147 IN CONST BOOLEAN CanAffectLE
,
148 IN CONST EFI_HANDLE HiiHandle
,
149 IN CONST EFI_STRING_ID ManFormatHelp
153 Checks if a command string has been registered for CommandString, and if so, it runs
154 the previously registered handler for that command with the command line.
156 If CommandString is NULL, then ASSERT().
158 If Sections is specified, then each section name listed will be compared in a case sensitive
159 manner to the section names described in Appendix B UEFI Shell 2.0 Specification. If the section exists,
160 it is appended to the returned help text. If the section does not exist, no
161 information is returned. If Sections is NULL, then all help text information
162 available is returned.
164 @param[in] CommandString The pointer to the command name. This is the name
165 found on the command line in the shell.
166 @param[in,out] RetVal The pointer to the return value from the command handler.
168 @param[in,out] CanAffectLE Indicates whether this command's return value
169 needs to be placed into LASTERROR environment variable.
171 @retval RETURN_SUCCESS The handler was run.
172 @retval RETURN_NOT_FOUND The CommandString did not match a registered
174 @sa SHELL_RUN_COMMAND
178 ShellCommandRunCommandHandler (
179 IN CONST CHAR16
*CommandString
,
180 IN OUT SHELL_STATUS
*RetVal
,
181 IN OUT BOOLEAN
*CanAffectLE OPTIONAL
185 Checks if a command string has been registered for CommandString, and if so, it
186 returns the MAN filename specified for that command.
188 If CommandString is NULL, then ASSERT().
190 @param[in] CommandString The pointer to the command name. This is the name
191 found on the command line in the shell.
193 @retval NULL The CommandString was not a registered command.
194 @retval other The name of the MAN file.
195 @sa SHELL_GET_MAN_FILENAME
199 ShellCommandGetManFileNameHandler (
200 IN CONST CHAR16
*CommandString
206 CHAR16
*CommandString
;
210 Get the list of all available shell internal commands. This is a linked list,
211 via the LIST_ENTRY structure. Enumerate through it using the BaseLib linked
212 list functions. Do not modify the values.
214 @return A linked list of all available shell commands.
218 ShellCommandGetCommandList (
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.
346 ShellCommandRegisterExit (
347 IN BOOLEAN ScriptOnly
351 Retrieve the Exit indicator.
353 @retval TRUE Exit was indicated.
354 @retval FALSE Exit was not indicated.
358 ShellCommandGetExit (
363 Retrieve the Exit script indicator.
365 If ShellCommandGetExit returns FALSE, then the return from this is undefined.
367 @retval TRUE ScriptOnly was indicated.
368 @retval FALSE ScriptOnly was not indicated.
372 ShellCommandGetScriptExit (
377 LIST_ENTRY Link
; ///< List enumerator items.
378 UINTN Line
; ///< What line of the script file this was on.
379 CHAR16
*Cl
; ///< The original command line.
380 VOID
*Data
; ///< The data structure format dependant upon Command. (not always used)
381 BOOLEAN Reset
; ///< Reset the command (it must be treated like a initial run (but it may have data already))
382 } SCRIPT_COMMAND_LIST
;
385 CHAR16
*ScriptName
; ///< The filename of this script.
386 CHAR16
**Argv
; ///< The parmameters to the script file.
387 UINTN Argc
; ///< The count of parameters.
388 LIST_ENTRY CommandList
; ///< The script converted to a list of commands (SCRIPT_COMMAND_LIST objects).
389 SCRIPT_COMMAND_LIST
*CurrentCommand
; ///< The command currently being operated. If !=NULL must be a member of CommandList.
390 LIST_ENTRY SubstList
; ///< A list of current script loop alias' (ALIAS_LIST objects) (Used for the for %-based replacement).
394 Function to return a pointer to the currently running script file object.
396 @retval NULL A script file is not currently running.
397 @return A pointer to the current script file object.
401 ShellCommandGetCurrentScriptFile (
406 Function to set a new script as the currently running one.
408 This function will correctly stack and unstack nested scripts.
410 @param[in] Script The pointer to new script information structure. If NULL,
411 it removes and de-allocates the topmost Script structure.
413 @return A pointer to the current running script file after this
414 change. It is NULL if removing the final script.
418 ShellCommandSetNewScript (
419 IN SCRIPT_FILE
*Script OPTIONAL
423 Function to get the current Profile string.
425 This is used to retrieve what profiles were installed.
427 @retval NULL There are no installed profiles.
428 @return A semicolon-delimited list of profiles.
432 ShellCommandGetProfileList (
437 MappingTypeFileSystem
,
440 } SHELL_MAPPING_TYPE
;
443 Function to generate the next default mapping name.
445 If the return value is not NULL then it must be callee freed.
447 @param Type What kind of mapping name to make.
449 @retval NULL a memory allocation failed.
450 @return a new map name string
454 ShellCommandCreateNewMappingName(
455 IN CONST SHELL_MAPPING_TYPE Type
459 Function to initialize the table for creating consistent map names.
461 @param[out] Table The pointer to pointer to pointer to DevicePathProtocol object.
463 @retval EFI_SUCCESS The table was created successfully.
467 ShellCommandConsistMappingInitialize (
468 EFI_DEVICE_PATH_PROTOCOL
***Table
472 Function to uninitialize the table for creating consistent map names.
474 The parameter must have been received from ShellCommandConsistMappingInitialize.
476 @param[out] Table The pointer to pointer to DevicePathProtocol object.
478 @retval EFI_SUCCESS The table was deleted successfully.
482 ShellCommandConsistMappingUnInitialize (
483 EFI_DEVICE_PATH_PROTOCOL
**Table
487 Create a consistent mapped name for the device specified by DevicePath
490 This must be called after ShellCommandConsistMappingInitialize() and
491 before ShellCommandConsistMappingUnInitialize() is called.
493 @param[in] DeviecPath The pointer to the dev path for the device.
494 @param[in] Table The Table of mapping information.
496 @retval NULL A consistent mapped name could not be created.
497 @return A pointer to a string allocated from pool with the device name.
501 ShellCommandConsistMappingGenMappingName (
502 IN EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
503 IN EFI_DEVICE_PATH_PROTOCOL
**Table
507 Function to search the list of mappings for the first matching node on the
508 list based on the MapKey.
510 @param[in] MapKey The pointer to the string key to search for in the map.
512 @return the node on the list.
516 ShellCommandFindMapItem (
517 IN CONST CHAR16
*MapKey
521 Function to add a map node to the list of map items and update the "path" environment variable (optionally).
523 If Path is TRUE (during initialization only), the path environment variable will also be updated to include
524 default paths on the new map name...
526 Path should be FALSE when this function is called from the protocol SetMap function.
528 @param[in] Name The human readable mapped name.
529 @param[in] DevicePath The Device Path for this map.
530 @param[in] Flags The Flags attribute for this map item.
531 @param[in] Path TRUE to update path, FALSE to skip this step (should only be TRUE during initialization).
533 @retval EFI_SUCCESS The addition was sucessful.
534 @retval EFI_OUT_OF_RESOURCES A memory allocation failed.
535 @retval EFI_INVALID_PARAMETER A parameter was invalid.
539 ShellCommandAddMapItemAndUpdatePath(
540 IN CONST CHAR16
*Name
,
541 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
542 IN CONST UINT64 Flags
,
543 IN CONST BOOLEAN Path
547 Creates the default map names for each device path in the system with
548 a protocol depending on the Type.
550 Also sets up the default path environment variable if Type is FileSystem.
552 @retval EFI_SUCCESS All map names were created sucessfully.
553 @retval EFI_NOT_FOUND No protocols were found in the system.
554 @return Error returned from gBS->LocateHandle().
560 ShellCommandCreateInitialMappingsAndPaths(
565 Function to standardize the directory indicators to \ characters.
567 @param[in,out] Path The pointer to the path string to fix.
569 @retval NULL The operation failed.
570 @return The Path pointer.
574 ShellCommandCleanPath (
579 Converts a SHELL_FILE_HANDLE to an EFI_FILE_PROTOCOL*.
581 @param[in] Handle The SHELL_FILE_HANDLE to convert.
583 @return a EFI_FILE_PROTOCOL* representing the same file.
587 ConvertShellHandleToEfiFileProtocol(
588 IN CONST SHELL_FILE_HANDLE Handle
592 Remove a SHELL_FILE_HANDLE frmo the list of SHELL_FILE_HANDLES.
594 @param[in] Handle The SHELL_FILE_HANDLE to remove.
596 @retval TRUE The item was removed.
597 @retval FALSE The item was not found.
601 ShellFileHandleRemove(
602 IN CONST SHELL_FILE_HANDLE Handle
606 Converts a EFI_FILE_PROTOCOL* to an SHELL_FILE_HANDLE.
608 @param[in] Handle The pointer to EFI_FILE_PROTOCOL to convert.
609 @param[in] Path The path to the file for verification.
611 @return a SHELL_FILE_HANDLE representing the same file.
615 ConvertEfiFileProtocolToShellHandle(
616 IN CONST EFI_FILE_PROTOCOL
*Handle
,
617 IN CONST CHAR16
*Path
621 Find the path that was logged with the specified SHELL_FILE_HANDLE.
623 @param[in] Handle The SHELL_FILE_HANDLE to query on.
625 @return A pointer to the path for the file.
629 ShellFileHandleGetPath(
630 IN CONST SHELL_FILE_HANDLE Handle
635 Function to determine if a SHELL_FILE_HANDLE is at the end of the file.
637 This will NOT work on directories.
639 If Handle is NULL, then ASSERT.
641 @param[in] Handle the file handle
643 @retval TRUE the position is at the end of the file
644 @retval FALSE the position is not at the end of the file
649 IN SHELL_FILE_HANDLE Handle
653 Function to read a single line from a SHELL_FILE_HANDLE. The \n is not included in the returned
654 buffer. The returned buffer must be callee freed.
656 If the position upon start is 0, then the Ascii Boolean will be set. This should be
657 maintained and not changed for all operations with the same file.
659 @param[in] Handle SHELL_FILE_HANDLE to read from.
660 @param[in,out] Ascii Boolean value for indicating whether the file is
661 Ascii (TRUE) or UCS2 (FALSE).
663 @return The line of text from the file.
665 @sa ShellFileHandleReadLine
669 ShellFileHandleReturnLine(
670 IN SHELL_FILE_HANDLE Handle
,
671 IN OUT BOOLEAN
*Ascii
675 Function to read a single line (up to but not including the \n) from a SHELL_FILE_HANDLE.
677 If the position upon start is 0, then the Ascii Boolean will be set. This should be
678 maintained and not changed for all operations with the same file.
680 @param[in] Handle SHELL_FILE_HANDLE to read from.
681 @param[in,out] Buffer The pointer to buffer to read into.
682 @param[in,out] Size The pointer to number of bytes in Buffer.
683 @param[in] Truncate If the buffer is large enough, this has no effect.
684 If the buffer is is too small and Truncate is TRUE,
685 the line will be truncated.
686 If the buffer is is too small and Truncate is FALSE,
687 then no read will occur.
689 @param[in,out] Ascii Boolean value for indicating whether the file is
690 Ascii (TRUE) or UCS2 (FALSE).
692 @retval EFI_SUCCESS The operation was successful. The line is stored in
694 @retval EFI_INVALID_PARAMETER Handle was NULL.
695 @retval EFI_INVALID_PARAMETER Size was NULL.
696 @retval EFI_BUFFER_TOO_SMALL Size was not large enough to store the line.
697 Size was updated to the minimum space required.
698 @sa ShellFileHandleRead
702 ShellFileHandleReadLine(
703 IN SHELL_FILE_HANDLE Handle
,
704 IN OUT CHAR16
*Buffer
,
707 IN OUT BOOLEAN
*Ascii
716 Frees any BUFFER_LIST defined type.
718 @param[in] List The pointer to the list head.
727 Chops off last directory or file entry in a path by changing the last '\' to a CHAR_NULL
729 @param[in,out] PathToReturn The pointer to the path to modify.
731 @retval FALSE No directory was found to chop off.
732 @retval TRUE A directory was chopped off.
737 IN OUT CHAR16
*PathToReturn
741 Function to clean up paths. Removes the following items:
742 single periods in the path (no need for the current directory tag)
743 double periods in the path and removes a single parent directory.
745 This will be done inline and the resultant string may be be 'too big'.
747 @param[in] PathToReturn The pointer to the string containing the path.
749 @return PathToReturn is always returned.
754 IN CHAR16
*PathToReturn
757 #endif //_SHELL_COMMAND_LIB_