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 cleanup all memory from a SCRIPT_FILE structure.
425 @param[in] Script The pointer to the structure to cleanup.
429 DeleteScriptFileStruct (
430 IN SCRIPT_FILE
*Script
434 Function to get the current Profile string.
436 This is used to retrieve what profiles were installed.
438 @retval NULL There are no installed profiles.
439 @return A semicolon-delimited list of profiles.
443 ShellCommandGetProfileList (
448 MappingTypeFileSystem
,
451 } SHELL_MAPPING_TYPE
;
454 Function to generate the next default mapping name.
456 If the return value is not NULL then it must be callee freed.
458 @param Type What kind of mapping name to make.
460 @retval NULL a memory allocation failed.
461 @return a new map name string
465 ShellCommandCreateNewMappingName(
466 IN CONST SHELL_MAPPING_TYPE Type
470 Function to initialize the table for creating consistent map names.
472 @param[out] Table The pointer to pointer to pointer to DevicePathProtocol object.
474 @retval EFI_SUCCESS The table was created successfully.
478 ShellCommandConsistMappingInitialize (
479 EFI_DEVICE_PATH_PROTOCOL
***Table
483 Function to uninitialize the table for creating consistent map names.
485 The parameter must have been received from ShellCommandConsistMappingInitialize.
487 @param[out] Table The pointer to pointer to DevicePathProtocol object.
489 @retval EFI_SUCCESS The table was deleted successfully.
493 ShellCommandConsistMappingUnInitialize (
494 EFI_DEVICE_PATH_PROTOCOL
**Table
498 Create a consistent mapped name for the device specified by DevicePath
501 This must be called after ShellCommandConsistMappingInitialize() and
502 before ShellCommandConsistMappingUnInitialize() is called.
504 @param[in] DeviecPath The pointer to the dev path for the device.
505 @param[in] Table The Table of mapping information.
507 @retval NULL A consistent mapped name could not be created.
508 @return A pointer to a string allocated from pool with the device name.
512 ShellCommandConsistMappingGenMappingName (
513 IN EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
514 IN EFI_DEVICE_PATH_PROTOCOL
**Table
518 Function to search the list of mappings for the first matching node on the
519 list based on the MapKey.
521 @param[in] MapKey The pointer to the string key to search for in the map.
523 @return the node on the list.
527 ShellCommandFindMapItem (
528 IN CONST CHAR16
*MapKey
532 Function to add a map node to the list of map items and update the "path" environment variable (optionally).
534 If Path is TRUE (during initialization only), the path environment variable will also be updated to include
535 default paths on the new map name...
537 Path should be FALSE when this function is called from the protocol SetMap function.
539 @param[in] Name The human readable mapped name.
540 @param[in] DevicePath The Device Path for this map.
541 @param[in] Flags The Flags attribute for this map item.
542 @param[in] Path TRUE to update path, FALSE to skip this step (should only be TRUE during initialization).
544 @retval EFI_SUCCESS The addition was sucessful.
545 @retval EFI_OUT_OF_RESOURCES A memory allocation failed.
546 @retval EFI_INVALID_PARAMETER A parameter was invalid.
550 ShellCommandAddMapItemAndUpdatePath(
551 IN CONST CHAR16
*Name
,
552 IN CONST EFI_DEVICE_PATH_PROTOCOL
*DevicePath
,
553 IN CONST UINT64 Flags
,
554 IN CONST BOOLEAN Path
558 Creates the default map names for each device path in the system with
559 a protocol depending on the Type.
561 Also sets up the default path environment variable if Type is FileSystem.
563 @retval EFI_SUCCESS All map names were created sucessfully.
564 @retval EFI_NOT_FOUND No protocols were found in the system.
565 @return Error returned from gBS->LocateHandle().
571 ShellCommandCreateInitialMappingsAndPaths(
576 Function to standardize the directory indicators to \ characters.
578 @param[in,out] Path The pointer to the path string to fix.
580 @retval NULL The operation failed.
581 @return The Path pointer.
585 ShellCommandCleanPath (
590 Converts a SHELL_FILE_HANDLE to an EFI_FILE_PROTOCOL*.
592 @param[in] Handle The SHELL_FILE_HANDLE to convert.
594 @return a EFI_FILE_PROTOCOL* representing the same file.
598 ConvertShellHandleToEfiFileProtocol(
599 IN CONST SHELL_FILE_HANDLE Handle
603 Remove a SHELL_FILE_HANDLE frmo the list of SHELL_FILE_HANDLES.
605 @param[in] Handle The SHELL_FILE_HANDLE to remove.
607 @retval TRUE The item was removed.
608 @retval FALSE The item was not found.
612 ShellFileHandleRemove(
613 IN CONST SHELL_FILE_HANDLE Handle
617 Converts a EFI_FILE_PROTOCOL* to an SHELL_FILE_HANDLE.
619 @param[in] Handle The pointer to EFI_FILE_PROTOCOL to convert.
620 @param[in] Path The path to the file for verification.
622 @return a SHELL_FILE_HANDLE representing the same file.
626 ConvertEfiFileProtocolToShellHandle(
627 IN CONST EFI_FILE_PROTOCOL
*Handle
,
628 IN CONST CHAR16
*Path
632 Find the path that was logged with the specified SHELL_FILE_HANDLE.
634 @param[in] Handle The SHELL_FILE_HANDLE to query on.
636 @return A pointer to the path for the file.
640 ShellFileHandleGetPath(
641 IN CONST SHELL_FILE_HANDLE Handle
646 Function to determine if a SHELL_FILE_HANDLE is at the end of the file.
648 This will NOT work on directories.
650 If Handle is NULL, then ASSERT.
652 @param[in] Handle the file handle
654 @retval TRUE the position is at the end of the file
655 @retval FALSE the position is not at the end of the file
660 IN SHELL_FILE_HANDLE Handle
664 Function to read a single line from a SHELL_FILE_HANDLE. The \n is not included in the returned
665 buffer. The returned buffer must be callee freed.
667 If the position upon start is 0, then the Ascii Boolean will be set. This should be
668 maintained and not changed for all operations with the same file.
670 @param[in] Handle SHELL_FILE_HANDLE to read from.
671 @param[in,out] Ascii Boolean value for indicating whether the file is
672 Ascii (TRUE) or UCS2 (FALSE).
674 @return The line of text from the file.
676 @sa ShellFileHandleReadLine
680 ShellFileHandleReturnLine(
681 IN SHELL_FILE_HANDLE Handle
,
682 IN OUT BOOLEAN
*Ascii
686 Function to read a single line (up to but not including the \n) from a SHELL_FILE_HANDLE.
688 If the position upon start is 0, then the Ascii Boolean will be set. This should be
689 maintained and not changed for all operations with the same file.
691 @param[in] Handle SHELL_FILE_HANDLE to read from.
692 @param[in,out] Buffer The pointer to buffer to read into.
693 @param[in,out] Size The pointer to number of bytes in Buffer.
694 @param[in] Truncate If the buffer is large enough, this has no effect.
695 If the buffer is is too small and Truncate is TRUE,
696 the line will be truncated.
697 If the buffer is is too small and Truncate is FALSE,
698 then no read will occur.
700 @param[in,out] Ascii Boolean value for indicating whether the file is
701 Ascii (TRUE) or UCS2 (FALSE).
703 @retval EFI_SUCCESS The operation was successful. The line is stored in
705 @retval EFI_INVALID_PARAMETER Handle was NULL.
706 @retval EFI_INVALID_PARAMETER Size was NULL.
707 @retval EFI_BUFFER_TOO_SMALL Size was not large enough to store the line.
708 Size was updated to the minimum space required.
709 @sa ShellFileHandleRead
713 ShellFileHandleReadLine(
714 IN SHELL_FILE_HANDLE Handle
,
715 IN OUT CHAR16
*Buffer
,
718 IN OUT BOOLEAN
*Ascii
727 Frees any BUFFER_LIST defined type.
729 @param[in] List The pointer to the list head.
738 Chops off last directory or file entry in a path by changing the last '\' to a CHAR_NULL
740 @param[in,out] PathToReturn The pointer to the path to modify.
742 @retval FALSE No directory was found to chop off.
743 @retval TRUE A directory was chopped off.
748 IN OUT CHAR16
*PathToReturn
752 Function to clean up paths. Removes the following items:
753 single periods in the path (no need for the current directory tag)
754 double periods in the path and removes a single parent directory.
756 This will be done inline and the resultant string may be be 'too big'.
758 @param[in] PathToReturn The pointer to the string containing the path.
760 @return PathToReturn is always returned.
765 IN CHAR16
*PathToReturn
768 #endif //_SHELL_COMMAND_LIB_