diff options
Diffstat (limited to 'ShellPkg/Include/Library')
| -rw-r--r-- | ShellPkg/Include/Library/AcpiViewCommandLib.h | 92 | ||||
| -rw-r--r-- | ShellPkg/Include/Library/BcfgCommandLib.h | 90 | ||||
| -rw-r--r-- | ShellPkg/Include/Library/HandleParsingLib.h | 804 | ||||
| -rw-r--r-- | ShellPkg/Include/Library/ShellCEntryLib.h | 66 | ||||
| -rw-r--r-- | ShellPkg/Include/Library/ShellCommandLib.h | 1590 | ||||
| -rw-r--r-- | ShellPkg/Include/Library/ShellLib.h | 2862 |
6 files changed, 2752 insertions, 2752 deletions
diff --git a/ShellPkg/Include/Library/AcpiViewCommandLib.h b/ShellPkg/Include/Library/AcpiViewCommandLib.h index 7309cb7a1a..4a18342c3e 100644 --- a/ShellPkg/Include/Library/AcpiViewCommandLib.h +++ b/ShellPkg/Include/Library/AcpiViewCommandLib.h @@ -1,46 +1,46 @@ -/** @file
- Library providing 'acpiview' functionality to display and
- validate installed ACPI tables.
-
- Copyright (c) 2016 - 2020, ARM Limited. All rights reserved.<BR>
- SPDX-License-Identifier: BSD-2-Clause-Patent
-**/
-
-#ifndef ACPI_VIEW_COMMAND_LIB_H_
-#define ACPI_VIEW_COMMAND_LIB_H_
-
-/**
- Dump a buffer to a file. Print error message if a file cannot be created.
-
- @param[in] FileName The filename that shall be created to contain the buffer.
- @param[in] Buffer Pointer to buffer that shall be dumped.
- @param[in] BufferSize The size of buffer to be dumped in bytes.
-
- @return The number of bytes that were written
-**/
-UINTN
-EFIAPI
-ShellDumpBufferToFile (
- IN CONST CHAR16 *FileNameBuffer,
- IN CONST VOID *Buffer,
- IN CONST UINTN BufferSize
- );
-
-/**
- Display and validate ACPI tables.
-
- @param[in] ImageHandle Handle to the Image (NULL if internal).
- @param[in] SystemTable Pointer to the System Table (NULL if internal).
-
- @retval SHELL_INVALID_PARAMETER The command line invocation could not be parsed.
- @retval SHELL_NOT_FOUND The command failed.
- @retval SHELL_SUCCESS The command was successful.
-**/
-SHELL_STATUS
-EFIAPI
-ShellCommandRunAcpiView (
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
- );
-
-#endif // UEFI_SHELL_ACPIVIEW_COMMAND_LIB_H_
+/** @file + Library providing 'acpiview' functionality to display and + validate installed ACPI tables. + + Copyright (c) 2016 - 2020, ARM Limited. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent +**/ + +#ifndef ACPI_VIEW_COMMAND_LIB_H_ +#define ACPI_VIEW_COMMAND_LIB_H_ + +/** + Dump a buffer to a file. Print error message if a file cannot be created. + + @param[in] FileName The filename that shall be created to contain the buffer. + @param[in] Buffer Pointer to buffer that shall be dumped. + @param[in] BufferSize The size of buffer to be dumped in bytes. + + @return The number of bytes that were written +**/ +UINTN +EFIAPI +ShellDumpBufferToFile ( + IN CONST CHAR16 *FileNameBuffer, + IN CONST VOID *Buffer, + IN CONST UINTN BufferSize + ); + +/** + Display and validate ACPI tables. + + @param[in] ImageHandle Handle to the Image (NULL if internal). + @param[in] SystemTable Pointer to the System Table (NULL if internal). + + @retval SHELL_INVALID_PARAMETER The command line invocation could not be parsed. + @retval SHELL_NOT_FOUND The command failed. + @retval SHELL_SUCCESS The command was successful. +**/ +SHELL_STATUS +EFIAPI +ShellCommandRunAcpiView ( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable + ); + +#endif // UEFI_SHELL_ACPIVIEW_COMMAND_LIB_H_ diff --git a/ShellPkg/Include/Library/BcfgCommandLib.h b/ShellPkg/Include/Library/BcfgCommandLib.h index 649fe00f98..3acf236313 100644 --- a/ShellPkg/Include/Library/BcfgCommandLib.h +++ b/ShellPkg/Include/Library/BcfgCommandLib.h @@ -1,45 +1,45 @@ -/** @file
- Header file for BCFG command library.
-
- Copyright (c) 2014, Intel Corporation. All rights reserved.<BR>
- SPDX-License-Identifier: BSD-2-Clause-Patent
-
-**/
-
-#ifndef _BCFG_COMMAND_LIB_H_
-#define _BCFG_COMMAND_LIB_H_
-
-/**
- "Constructor" for the library.
-
- This will register the handler for the bcfg command.
-
- @param[in] ImageHandle the image handle of the process
- @param[in] SystemTable the EFI System Table pointer
- @param[in] Name the profile name to use
-
- @retval EFI_SUCCESS the shell command handlers were installed successfully
- @retval EFI_UNSUPPORTED the shell level required was not found.
-**/
-EFI_STATUS
-EFIAPI
-BcfgLibraryRegisterBcfgCommand (
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable,
- IN CONST CHAR16 *Name
- );
-
-/**
- "Destructor" for the library. free any resources.
-
- @param ImageHandle The image handle of the process.
- @param SystemTable The EFI System Table pointer.
-**/
-EFI_STATUS
-EFIAPI
-BcfgLibraryUnregisterBcfgCommand (
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
- );
-
-#endif
+/** @file + Header file for BCFG command library. + + Copyright (c) 2014, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _BCFG_COMMAND_LIB_H_ +#define _BCFG_COMMAND_LIB_H_ + +/** + "Constructor" for the library. + + This will register the handler for the bcfg command. + + @param[in] ImageHandle the image handle of the process + @param[in] SystemTable the EFI System Table pointer + @param[in] Name the profile name to use + + @retval EFI_SUCCESS the shell command handlers were installed successfully + @retval EFI_UNSUPPORTED the shell level required was not found. +**/ +EFI_STATUS +EFIAPI +BcfgLibraryRegisterBcfgCommand ( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable, + IN CONST CHAR16 *Name + ); + +/** + "Destructor" for the library. free any resources. + + @param ImageHandle The image handle of the process. + @param SystemTable The EFI System Table pointer. +**/ +EFI_STATUS +EFIAPI +BcfgLibraryUnregisterBcfgCommand ( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable + ); + +#endif diff --git a/ShellPkg/Include/Library/HandleParsingLib.h b/ShellPkg/Include/Library/HandleParsingLib.h index b86d69cb0e..6d78961475 100644 --- a/ShellPkg/Include/Library/HandleParsingLib.h +++ b/ShellPkg/Include/Library/HandleParsingLib.h @@ -1,402 +1,402 @@ -/** @file
- Provides interface to advanced shell functionality for parsing both handle and protocol database.
-
- Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved.<BR>
- SPDX-License-Identifier: BSD-2-Clause-Patent
-
-**/
-
-#ifndef __HANDLE_PARSING_LIB__
-#define __HANDLE_PARSING_LIB__
-
-#include <Uefi.h>
-
-/**
- Function to add a new GUID/Name mapping.
-
- This cannot overwrite an existing mapping.
-
- @param[in] Guid The Guid
- @param[in] TheName The Guid's name
- @param[in] Lang RFC4646 language code list or NULL
-
- @retval EFI_SUCCESS The operation was successful
- @retval EFI_ACCESS_DENIED There was a duplicate
- @retval EFI_OUT_OF_RESOURCES A memory allocation failed
-**/
-EFI_STATUS
-EFIAPI
-AddNewGuidNameMapping (
- IN CONST EFI_GUID *Guid,
- IN CONST CHAR16 *TheName,
- IN CONST CHAR8 *Lang OPTIONAL
- );
-
-/**
- Function to get the name of a protocol or struct from it's GUID.
-
- If Guid is NULL, then ASSERT.
-
- @param[in] Guid The GUID to look for the name of.
- @param[in] Lang The language to use.
-
- @return The pointer to a string of the name. The caller
- is responsible to free this memory.
-**/
-CHAR16 *
-EFIAPI
-GetStringNameFromGuid (
- IN CONST EFI_GUID *Guid,
- IN CONST CHAR8 *Lang OPTIONAL
- );
-
-/**
- Function to get the Guid for a protocol or struct based on it's string name.
-
- Do not free or modify the returned GUID.
-
- @param[in] Name The pointer to the string name.
- @param[in] Lang The pointer to the language code (string).
- @param[out] Guid The pointer to the pointer to the Guid.
-
- @retval EFI_SUCCESS The operation was successful.
-**/
-EFI_STATUS
-EFIAPI
-GetGuidFromStringName (
- IN CONST CHAR16 *Name,
- IN CONST CHAR8 *Lang OPTIONAL,
- OUT EFI_GUID **Guid
- );
-
-/**
- Function to dump protocol information from a handle.
-
- This function will return a allocated string buffer containing the
- information. The caller is responsible for freeing the memory.
-
- If Guid is NULL, ASSERT().
- If TheHandle is NULL, ASSERT().
-
- @param[in] TheHandle The handle to dump information from.
- @param[in] Guid The GUID of the protocol to dump.
- @param[in] Verbose TRUE for extra info. FALSE otherwise.
-
- @return The pointer to string.
- @retval NULL An error was encountered.
-**/
-CHAR16 *
-EFIAPI
-GetProtocolInformationDump (
- IN CONST EFI_HANDLE TheHandle,
- IN CONST EFI_GUID *Guid,
- IN CONST BOOLEAN Verbose
- );
-
-/**
- Function to retrieve the driver name (if possible) from the ComponentName or
- ComponentName2 protocol.
-
- The string returned must be callee freed.
-
- @param[in] TheHandle The driver handle to get the name of.
- @param[in] Language The language to use.
-
- @retval NULL The name could not be found.
- @return A pointer to the string name. Do not de-allocate the memory.
-**/
-CONST CHAR16 *
-EFIAPI
-GetStringNameFromHandle (
- IN CONST EFI_HANDLE TheHandle,
- IN CONST CHAR8 *Language
- );
-
-/**
- Get best support language for this driver.
-
- First base on the user input language to search, second base on the current
- platform used language to search, third get the first language from the
- support language list. The caller need to free the buffer of the best language.
-
- @param[in] SupportedLanguages The support languages for this driver.
- @param[in] InputLanguage The user input language.
- @param[in] Iso639Language Whether get language for ISO639.
-
- @return The best support language for this driver.
-**/
-CHAR8 *
-EFIAPI
-GetBestLanguageForDriver (
- IN CONST CHAR8 *SupportedLanguages,
- IN CONST CHAR8 *InputLanguage,
- IN BOOLEAN Iso639Language
- );
-
-#define HR_UNKNOWN 0
-#define HR_IMAGE_HANDLE BIT1
-#define HR_DRIVER_BINDING_HANDLE BIT2 // has driver binding
-#define HR_DEVICE_DRIVER BIT3 // device driver (hybrid?)
-#define HR_BUS_DRIVER BIT4 // a bus driver (hybrid?)
-#define HR_DRIVER_CONFIGURATION_HANDLE BIT5
-#define HR_DRIVER_DIAGNOSTICS_HANDLE BIT6
-#define HR_COMPONENT_NAME_HANDLE BIT7
-#define HR_DEVICE_HANDLE BIT8
-#define HR_PARENT_HANDLE BIT9
-#define HR_CONTROLLER_HANDLE BIT10
-#define HR_CHILD_HANDLE BIT11
-#define HR_VALID_MASK (BIT1|BIT2|BIT3|BIT4|BIT5|BIT6|BIT7|BIT8|BIT9|BIT10|BIT11)
-
-/**
- Gets all the related EFI_HANDLEs based on the mask supplied.
-
- This function will scan all EFI_HANDLES in the UEFI environment's handle database
- and return all the ones with the specified relationship (Mask) to the specified
- controller handle.
-
- If both DriverBindingHandle and ControllerHandle are NULL, then ASSERT.
- If MatchingHandleCount is NULL, then ASSERT.
-
- If MatchingHandleBuffer is not NULL upon a successful return, the memory must be
- caller freed.
-
- @param[in] DriverBindingHandle The handle with Driver Binding protocol on it.
- @param[in] ControllerHandle The handle with Device Path protocol on it.
- @param[in] Mask The mask of what relationship(s) is desired.
- @param[in] MatchingHandleCount The pointer to UINTN specifying number of HANDLES in
- MatchingHandleBuffer.
- @param[out] MatchingHandleBuffer On a successful return, a buffer of MatchingHandleCount
- EFI_HANDLEs with a terminating NULL EFI_HANDLE.
-
- @retval EFI_SUCCESS The operation was successful, and any related handles
- are in MatchingHandleBuffer.
- @retval EFI_NOT_FOUND No matching handles were found.
- @retval EFI_INVALID_PARAMETER A parameter was invalid or out of range.
- @sa ParseHandleDatabaseByRelationshipWithType
-**/
-EFI_STATUS
-EFIAPI
-ParseHandleDatabaseByRelationship (
- IN CONST EFI_HANDLE DriverBindingHandle OPTIONAL,
- IN CONST EFI_HANDLE ControllerHandle OPTIONAL,
- IN CONST UINTN Mask,
- IN UINTN *MatchingHandleCount,
- OUT EFI_HANDLE **MatchingHandleBuffer OPTIONAL
- );
-
-/**
- Gets all the related EFI_HANDLEs based on the mask supplied.
-
- This function scans all EFI_HANDLES in the UEFI environment's handle database
- and returns the ones with the specified relationship (Mask) to the specified
- controller handle.
-
- If both DriverBindingHandle and ControllerHandle are NULL, then ASSERT.
- If MatchingHandleCount is NULL, then ASSERT.
-
- If MatchingHandleBuffer is not NULL upon a successful return the memory must be
- caller freed.
-
- @param[in] DriverBindingHandle The handle with Driver Binding protocol on it.
- @param[in] ControllerHandle The handle with Device Path protocol on it.
- @param[in] MatchingHandleCount The pointer to UINTN that specifies the number of HANDLES in
- MatchingHandleBuffer.
- @param[out] MatchingHandleBuffer On a successful return, a buffer of MatchingHandleCount
- EFI_HANDLEs with a terminating NULL EFI_HANDLE.
- @param[out] HandleType An array of type information.
-
- @retval EFI_SUCCESS The operation was successful, and any related handles
- are in MatchingHandleBuffer.
- @retval EFI_NOT_FOUND No matching handles were found.
- @retval EFI_INVALID_PARAMETER A parameter was invalid or out of range.
-**/
-EFI_STATUS
-EFIAPI
-ParseHandleDatabaseByRelationshipWithType (
- IN CONST EFI_HANDLE DriverBindingHandle OPTIONAL,
- IN CONST EFI_HANDLE ControllerHandle OPTIONAL,
- IN UINTN *HandleCount,
- OUT EFI_HANDLE **HandleBuffer,
- OUT UINTN **HandleType
- );
-
-/**
- Gets handles for any parents of the passed in controller.
-
- @param[in] ControllerHandle The handle of the controller.
- @param[in] Count The pointer to the number of handles in
- MatchingHandleBuffer on return.
- @param[out] Buffer The buffer containing handles on a successful
- return.
- @retval EFI_SUCCESS The operation was successful.
- @sa ParseHandleDatabaseByRelationship
-**/
-#define PARSE_HANDLE_DATABASE_PARENTS(ControllerHandle, Count, Buffer) \
- ParseHandleDatabaseByRelationship(NULL, ControllerHandle, HR_PARENT_HANDLE, Count, Buffer)
-
-/**
- Gets handles for any UEFI drivers of the passed in controller.
-
- @param[in] ControllerHandle The handle of the controller.
- @param[in] Count The pointer to the number of handles in
- MatchingHandleBuffer on return.
- @param[out] Buffer The buffer containing handles on a successful
- return.
- @retval EFI_SUCCESS The operation was successful.
- @sa ParseHandleDatabaseByRelationship
-**/
-#define PARSE_HANDLE_DATABASE_UEFI_DRIVERS(ControllerHandle, Count, Buffer) \
- ParseHandleDatabaseByRelationship(NULL, ControllerHandle, HR_DRIVER_BINDING_HANDLE|HR_DEVICE_DRIVER, Count, Buffer)
-
-/**
- Gets handles for any children of the passed in controller by the passed in driver handle.
-
- @param[in] DriverHandle The handle of the driver.
- @param[in] ControllerHandle The handle of the controller.
- @param[in] Count The pointer to the number of handles in
- MatchingHandleBuffer on return.
- @param[out] Buffer The buffer containing handles on a successful
- return.
- @retval EFI_SUCCESS The operation was successful.
- @sa ParseHandleDatabaseByRelationship
-**/
-#define PARSE_HANDLE_DATABASE_MANAGED_CHILDREN(DriverHandle, ControllerHandle, Count, Buffer) \
- ParseHandleDatabaseByRelationship(DriverHandle, ControllerHandle, HR_CHILD_HANDLE|HR_DEVICE_HANDLE, Count, Buffer)
-
-/**
- Gets handles for any devices managed by the passed in driver.
-
- @param[in] DriverHandle The handle of the driver.
- @param[in] Count The pointer to the number of handles in
- MatchingHandleBuffer on return.
- @param[out] Buffer The buffer containing handles on a successful
- return.
- @retval EFI_SUCCESS The operation was successful.
- @sa ParseHandleDatabaseByRelationship
-**/
-#define PARSE_HANDLE_DATABASE_DEVICES(DriverHandle, Count, Buffer) \
- ParseHandleDatabaseByRelationship(DriverHandle, NULL, HR_CONTROLLER_HANDLE|HR_DEVICE_HANDLE, Count, Buffer)
-
-/**
- Gets handles for any child devices produced by the passed in driver.
-
- @param[in] DriverHandle The handle of the driver.
- @param[in] MatchingHandleCount The pointer to the number of handles in
- MatchingHandleBuffer on return.
- @param[out] MatchingHandleBuffer The buffer containing handles on a successful
- return.
- @retval EFI_SUCCESS The operation was successful.
- @sa ParseHandleDatabaseByRelationship
-**/
-EFI_STATUS
-EFIAPI
-ParseHandleDatabaseForChildDevices (
- IN CONST EFI_HANDLE DriverHandle,
- IN UINTN *MatchingHandleCount,
- OUT EFI_HANDLE **MatchingHandleBuffer OPTIONAL
- );
-
-/**
- Gets handles for any child controllers of the passed in controller.
-
- @param[in] ControllerHandle The handle of the "parent controller".
- @param[out] MatchingHandleCount The pointer to the number of handles in
- MatchingHandleBuffer on return.
- @param[out] MatchingHandleBuffer The buffer containing handles on a successful
- return.
- @retval EFI_SUCCESS The operation was successful.
- @sa ParseHandleDatabaseByRelationship
-**/
-EFI_STATUS
-EFIAPI
-ParseHandleDatabaseForChildControllers (
- IN CONST EFI_HANDLE ControllerHandle,
- OUT UINTN *MatchingHandleCount,
- OUT EFI_HANDLE **MatchingHandleBuffer OPTIONAL
- );
-
-/**
- Function to retrieve the human-friendly index of a given handle. If the handle
- does not have a index one will be automatically assigned. The index value is valid
- until the termination of the shell application.
-
- @param[in] TheHandle The handle to retrieve an index for.
-
- @retval 0 A memory allocation failed.
- @return The index of the handle.
-
-**/
-UINTN
-EFIAPI
-ConvertHandleToHandleIndex (
- IN CONST EFI_HANDLE TheHandle
- );
-
-/**
- Function to retrieve the EFI_HANDLE from the human-friendly index.
-
- @param[in] TheIndex The index to retrieve the EFI_HANDLE for.
-
- @retval NULL The index was invalid.
- @return The EFI_HANDLE that index represents.
-
-**/
-EFI_HANDLE
-EFIAPI
-ConvertHandleIndexToHandle (
- IN CONST UINTN TheIndex
- );
-
-/**
- Function to get all handles that support a given protocol or all handles.
-
- The caller is responsible to free this memory.
-
- @param[in] ProtocolGuid The guid of the protocol to get handles for. If NULL
- then the function will return all handles.
-
- @retval NULL A memory allocation failed.
- @return A NULL terminated list of handles.
-**/
-EFI_HANDLE *
-EFIAPI
-GetHandleListByProtocol (
- IN CONST EFI_GUID *ProtocolGuid OPTIONAL
- );
-
-/**
- Function to get all handles that support some protocols.
-
- The caller is responsible to free this memory.
-
- @param[in] ProtocolGuids A NULL terminated list of protocol GUIDs.
-
- @retval NULL A memory allocation failed.
- @retval NULL ProtocolGuids was NULL.
- @return A NULL terminated list of EFI_HANDLEs.
-**/
-EFI_HANDLE *
-EFIAPI
-GetHandleListByProtocolList (
- IN CONST EFI_GUID **ProtocolGuids
- );
-
-/**
- Return all supported GUIDs.
-
- @param[out] Guids The buffer to return all supported GUIDs.
- @param[in, out] Count On input, the count of GUIDs the buffer can hold,
- On output, the count of GUIDs to return.
-
- @retval EFI_INVALID_PARAMETER Count is NULL.
- @retval EFI_BUFFER_TOO_SMALL Buffer is not enough to hold all GUIDs.
- @retval EFI_SUCCESS GUIDs are returned successfully.
-**/
-EFI_STATUS
-EFIAPI
-GetAllMappingGuids (
- OUT EFI_GUID *Guids,
- IN OUT UINTN *Count
- );
-
-#endif // __HANDLE_PARSING_LIB__
+/** @file + Provides interface to advanced shell functionality for parsing both handle and protocol database. + + Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __HANDLE_PARSING_LIB__ +#define __HANDLE_PARSING_LIB__ + +#include <Uefi.h> + +/** + Function to add a new GUID/Name mapping. + + This cannot overwrite an existing mapping. + + @param[in] Guid The Guid + @param[in] TheName The Guid's name + @param[in] Lang RFC4646 language code list or NULL + + @retval EFI_SUCCESS The operation was successful + @retval EFI_ACCESS_DENIED There was a duplicate + @retval EFI_OUT_OF_RESOURCES A memory allocation failed +**/ +EFI_STATUS +EFIAPI +AddNewGuidNameMapping ( + IN CONST EFI_GUID *Guid, + IN CONST CHAR16 *TheName, + IN CONST CHAR8 *Lang OPTIONAL + ); + +/** + Function to get the name of a protocol or struct from it's GUID. + + If Guid is NULL, then ASSERT. + + @param[in] Guid The GUID to look for the name of. + @param[in] Lang The language to use. + + @return The pointer to a string of the name. The caller + is responsible to free this memory. +**/ +CHAR16 * +EFIAPI +GetStringNameFromGuid ( + IN CONST EFI_GUID *Guid, + IN CONST CHAR8 *Lang OPTIONAL + ); + +/** + Function to get the Guid for a protocol or struct based on it's string name. + + Do not free or modify the returned GUID. + + @param[in] Name The pointer to the string name. + @param[in] Lang The pointer to the language code (string). + @param[out] Guid The pointer to the pointer to the Guid. + + @retval EFI_SUCCESS The operation was successful. +**/ +EFI_STATUS +EFIAPI +GetGuidFromStringName ( + IN CONST CHAR16 *Name, + IN CONST CHAR8 *Lang OPTIONAL, + OUT EFI_GUID **Guid + ); + +/** + Function to dump protocol information from a handle. + + This function will return a allocated string buffer containing the + information. The caller is responsible for freeing the memory. + + If Guid is NULL, ASSERT(). + If TheHandle is NULL, ASSERT(). + + @param[in] TheHandle The handle to dump information from. + @param[in] Guid The GUID of the protocol to dump. + @param[in] Verbose TRUE for extra info. FALSE otherwise. + + @return The pointer to string. + @retval NULL An error was encountered. +**/ +CHAR16 * +EFIAPI +GetProtocolInformationDump ( + IN CONST EFI_HANDLE TheHandle, + IN CONST EFI_GUID *Guid, + IN CONST BOOLEAN Verbose + ); + +/** + Function to retrieve the driver name (if possible) from the ComponentName or + ComponentName2 protocol. + + The string returned must be callee freed. + + @param[in] TheHandle The driver handle to get the name of. + @param[in] Language The language to use. + + @retval NULL The name could not be found. + @return A pointer to the string name. Do not de-allocate the memory. +**/ +CONST CHAR16 * +EFIAPI +GetStringNameFromHandle ( + IN CONST EFI_HANDLE TheHandle, + IN CONST CHAR8 *Language + ); + +/** + Get best support language for this driver. + + First base on the user input language to search, second base on the current + platform used language to search, third get the first language from the + support language list. The caller need to free the buffer of the best language. + + @param[in] SupportedLanguages The support languages for this driver. + @param[in] InputLanguage The user input language. + @param[in] Iso639Language Whether get language for ISO639. + + @return The best support language for this driver. +**/ +CHAR8 * +EFIAPI +GetBestLanguageForDriver ( + IN CONST CHAR8 *SupportedLanguages, + IN CONST CHAR8 *InputLanguage, + IN BOOLEAN Iso639Language + ); + +#define HR_UNKNOWN 0 +#define HR_IMAGE_HANDLE BIT1 +#define HR_DRIVER_BINDING_HANDLE BIT2 // has driver binding +#define HR_DEVICE_DRIVER BIT3 // device driver (hybrid?) +#define HR_BUS_DRIVER BIT4 // a bus driver (hybrid?) +#define HR_DRIVER_CONFIGURATION_HANDLE BIT5 +#define HR_DRIVER_DIAGNOSTICS_HANDLE BIT6 +#define HR_COMPONENT_NAME_HANDLE BIT7 +#define HR_DEVICE_HANDLE BIT8 +#define HR_PARENT_HANDLE BIT9 +#define HR_CONTROLLER_HANDLE BIT10 +#define HR_CHILD_HANDLE BIT11 +#define HR_VALID_MASK (BIT1|BIT2|BIT3|BIT4|BIT5|BIT6|BIT7|BIT8|BIT9|BIT10|BIT11) + +/** + Gets all the related EFI_HANDLEs based on the mask supplied. + + This function will scan all EFI_HANDLES in the UEFI environment's handle database + and return all the ones with the specified relationship (Mask) to the specified + controller handle. + + If both DriverBindingHandle and ControllerHandle are NULL, then ASSERT. + If MatchingHandleCount is NULL, then ASSERT. + + If MatchingHandleBuffer is not NULL upon a successful return, the memory must be + caller freed. + + @param[in] DriverBindingHandle The handle with Driver Binding protocol on it. + @param[in] ControllerHandle The handle with Device Path protocol on it. + @param[in] Mask The mask of what relationship(s) is desired. + @param[in] MatchingHandleCount The pointer to UINTN specifying number of HANDLES in + MatchingHandleBuffer. + @param[out] MatchingHandleBuffer On a successful return, a buffer of MatchingHandleCount + EFI_HANDLEs with a terminating NULL EFI_HANDLE. + + @retval EFI_SUCCESS The operation was successful, and any related handles + are in MatchingHandleBuffer. + @retval EFI_NOT_FOUND No matching handles were found. + @retval EFI_INVALID_PARAMETER A parameter was invalid or out of range. + @sa ParseHandleDatabaseByRelationshipWithType +**/ +EFI_STATUS +EFIAPI +ParseHandleDatabaseByRelationship ( + IN CONST EFI_HANDLE DriverBindingHandle OPTIONAL, + IN CONST EFI_HANDLE ControllerHandle OPTIONAL, + IN CONST UINTN Mask, + IN UINTN *MatchingHandleCount, + OUT EFI_HANDLE **MatchingHandleBuffer OPTIONAL + ); + +/** + Gets all the related EFI_HANDLEs based on the mask supplied. + + This function scans all EFI_HANDLES in the UEFI environment's handle database + and returns the ones with the specified relationship (Mask) to the specified + controller handle. + + If both DriverBindingHandle and ControllerHandle are NULL, then ASSERT. + If MatchingHandleCount is NULL, then ASSERT. + + If MatchingHandleBuffer is not NULL upon a successful return the memory must be + caller freed. + + @param[in] DriverBindingHandle The handle with Driver Binding protocol on it. + @param[in] ControllerHandle The handle with Device Path protocol on it. + @param[in] MatchingHandleCount The pointer to UINTN that specifies the number of HANDLES in + MatchingHandleBuffer. + @param[out] MatchingHandleBuffer On a successful return, a buffer of MatchingHandleCount + EFI_HANDLEs with a terminating NULL EFI_HANDLE. + @param[out] HandleType An array of type information. + + @retval EFI_SUCCESS The operation was successful, and any related handles + are in MatchingHandleBuffer. + @retval EFI_NOT_FOUND No matching handles were found. + @retval EFI_INVALID_PARAMETER A parameter was invalid or out of range. +**/ +EFI_STATUS +EFIAPI +ParseHandleDatabaseByRelationshipWithType ( + IN CONST EFI_HANDLE DriverBindingHandle OPTIONAL, + IN CONST EFI_HANDLE ControllerHandle OPTIONAL, + IN UINTN *HandleCount, + OUT EFI_HANDLE **HandleBuffer, + OUT UINTN **HandleType + ); + +/** + Gets handles for any parents of the passed in controller. + + @param[in] ControllerHandle The handle of the controller. + @param[in] Count The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] Buffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +#define PARSE_HANDLE_DATABASE_PARENTS(ControllerHandle, Count, Buffer) \ + ParseHandleDatabaseByRelationship(NULL, ControllerHandle, HR_PARENT_HANDLE, Count, Buffer) + +/** + Gets handles for any UEFI drivers of the passed in controller. + + @param[in] ControllerHandle The handle of the controller. + @param[in] Count The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] Buffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +#define PARSE_HANDLE_DATABASE_UEFI_DRIVERS(ControllerHandle, Count, Buffer) \ + ParseHandleDatabaseByRelationship(NULL, ControllerHandle, HR_DRIVER_BINDING_HANDLE|HR_DEVICE_DRIVER, Count, Buffer) + +/** + Gets handles for any children of the passed in controller by the passed in driver handle. + + @param[in] DriverHandle The handle of the driver. + @param[in] ControllerHandle The handle of the controller. + @param[in] Count The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] Buffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +#define PARSE_HANDLE_DATABASE_MANAGED_CHILDREN(DriverHandle, ControllerHandle, Count, Buffer) \ + ParseHandleDatabaseByRelationship(DriverHandle, ControllerHandle, HR_CHILD_HANDLE|HR_DEVICE_HANDLE, Count, Buffer) + +/** + Gets handles for any devices managed by the passed in driver. + + @param[in] DriverHandle The handle of the driver. + @param[in] Count The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] Buffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +#define PARSE_HANDLE_DATABASE_DEVICES(DriverHandle, Count, Buffer) \ + ParseHandleDatabaseByRelationship(DriverHandle, NULL, HR_CONTROLLER_HANDLE|HR_DEVICE_HANDLE, Count, Buffer) + +/** + Gets handles for any child devices produced by the passed in driver. + + @param[in] DriverHandle The handle of the driver. + @param[in] MatchingHandleCount The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] MatchingHandleBuffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +EFI_STATUS +EFIAPI +ParseHandleDatabaseForChildDevices ( + IN CONST EFI_HANDLE DriverHandle, + IN UINTN *MatchingHandleCount, + OUT EFI_HANDLE **MatchingHandleBuffer OPTIONAL + ); + +/** + Gets handles for any child controllers of the passed in controller. + + @param[in] ControllerHandle The handle of the "parent controller". + @param[out] MatchingHandleCount The pointer to the number of handles in + MatchingHandleBuffer on return. + @param[out] MatchingHandleBuffer The buffer containing handles on a successful + return. + @retval EFI_SUCCESS The operation was successful. + @sa ParseHandleDatabaseByRelationship +**/ +EFI_STATUS +EFIAPI +ParseHandleDatabaseForChildControllers ( + IN CONST EFI_HANDLE ControllerHandle, + OUT UINTN *MatchingHandleCount, + OUT EFI_HANDLE **MatchingHandleBuffer OPTIONAL + ); + +/** + Function to retrieve the human-friendly index of a given handle. If the handle + does not have a index one will be automatically assigned. The index value is valid + until the termination of the shell application. + + @param[in] TheHandle The handle to retrieve an index for. + + @retval 0 A memory allocation failed. + @return The index of the handle. + +**/ +UINTN +EFIAPI +ConvertHandleToHandleIndex ( + IN CONST EFI_HANDLE TheHandle + ); + +/** + Function to retrieve the EFI_HANDLE from the human-friendly index. + + @param[in] TheIndex The index to retrieve the EFI_HANDLE for. + + @retval NULL The index was invalid. + @return The EFI_HANDLE that index represents. + +**/ +EFI_HANDLE +EFIAPI +ConvertHandleIndexToHandle ( + IN CONST UINTN TheIndex + ); + +/** + Function to get all handles that support a given protocol or all handles. + + The caller is responsible to free this memory. + + @param[in] ProtocolGuid The guid of the protocol to get handles for. If NULL + then the function will return all handles. + + @retval NULL A memory allocation failed. + @return A NULL terminated list of handles. +**/ +EFI_HANDLE * +EFIAPI +GetHandleListByProtocol ( + IN CONST EFI_GUID *ProtocolGuid OPTIONAL + ); + +/** + Function to get all handles that support some protocols. + + The caller is responsible to free this memory. + + @param[in] ProtocolGuids A NULL terminated list of protocol GUIDs. + + @retval NULL A memory allocation failed. + @retval NULL ProtocolGuids was NULL. + @return A NULL terminated list of EFI_HANDLEs. +**/ +EFI_HANDLE * +EFIAPI +GetHandleListByProtocolList ( + IN CONST EFI_GUID **ProtocolGuids + ); + +/** + Return all supported GUIDs. + + @param[out] Guids The buffer to return all supported GUIDs. + @param[in, out] Count On input, the count of GUIDs the buffer can hold, + On output, the count of GUIDs to return. + + @retval EFI_INVALID_PARAMETER Count is NULL. + @retval EFI_BUFFER_TOO_SMALL Buffer is not enough to hold all GUIDs. + @retval EFI_SUCCESS GUIDs are returned successfully. +**/ +EFI_STATUS +EFIAPI +GetAllMappingGuids ( + OUT EFI_GUID *Guids, + IN OUT UINTN *Count + ); + +#endif // __HANDLE_PARSING_LIB__ diff --git a/ShellPkg/Include/Library/ShellCEntryLib.h b/ShellPkg/Include/Library/ShellCEntryLib.h index ced72036d2..d3572e216e 100644 --- a/ShellPkg/Include/Library/ShellCEntryLib.h +++ b/ShellPkg/Include/Library/ShellCEntryLib.h @@ -1,33 +1,33 @@ -/** @file
- Provides application point extension for "C" style main function.
-
- Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
- SPDX-License-Identifier: BSD-2-Clause-Patent
-
-**/
-
-#ifndef _SHELL_C_ENTRY_LIB_
-#define _SHELL_C_ENTRY_LIB_
-
-/**
- UEFI application entry point which has an interface similar to a
- standard C main function.
-
- The ShellCEntryLib library instance wrappers the actual UEFI application
- entry point and calls this ShellAppMain function.
-
- @param[in] Argc The number of parameters.
- @param[in] Argv The array of pointers to parameters.
-
- @retval 0 The application exited normally.
- @retval Other An error occurred.
-
-**/
-INTN
-EFIAPI
-ShellAppMain (
- IN UINTN Argc,
- IN CHAR16 **Argv
- );
-
-#endif
+/** @file + Provides application point extension for "C" style main function. + + Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SHELL_C_ENTRY_LIB_ +#define _SHELL_C_ENTRY_LIB_ + +/** + UEFI application entry point which has an interface similar to a + standard C main function. + + The ShellCEntryLib library instance wrappers the actual UEFI application + entry point and calls this ShellAppMain function. + + @param[in] Argc The number of parameters. + @param[in] Argv The array of pointers to parameters. + + @retval 0 The application exited normally. + @retval Other An error occurred. + +**/ +INTN +EFIAPI +ShellAppMain ( + IN UINTN Argc, + IN CHAR16 **Argv + ); + +#endif diff --git a/ShellPkg/Include/Library/ShellCommandLib.h b/ShellPkg/Include/Library/ShellCommandLib.h index 0b185e3e57..5da31b9d2e 100644 --- a/ShellPkg/Include/Library/ShellCommandLib.h +++ b/ShellPkg/Include/Library/ShellCommandLib.h @@ -1,795 +1,795 @@ -/** @file
- Provides interface to shell internal functions for shell commands.
-
- This library is for use ONLY by shell commands linked into the shell application.
- This library will not function if it is used for UEFI Shell 2.0 Applications.
-
- Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
- (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>
- (C) Copyright 2013-2014 Hewlett-Packard Development Company, L.P.<BR>
- SPDX-License-Identifier: BSD-2-Clause-Patent
-
-**/
-
-#ifndef _SHELL_COMMAND_LIB_
-#define _SHELL_COMMAND_LIB_
-
-#include <Uefi.h>
-
-#include <Protocol/Shell.h>
-#include <Protocol/ShellParameters.h>
-#include <Protocol/UnicodeCollation.h>
-#include <Protocol/SimpleFileSystem.h>
-
-#include <Library/UefiBootServicesTableLib.h>
-
-//
-// The extern global protocol poionters.
-//
-extern EFI_UNICODE_COLLATION_PROTOCOL *gUnicodeCollation;
-extern CONST CHAR16 *SupportLevel[];
-
-//
-// The map list objects.
-//
-typedef struct {
- LIST_ENTRY Link;
- EFI_DEVICE_PATH_PROTOCOL *DevicePath;
- CHAR16 *MapName;
- CHAR16 *CurrentDirectoryPath;
- UINT64 Flags;
-} SHELL_MAP_LIST;
-/// List of Mappings - DeviceName and Drive Letter(ism).
-extern SHELL_MAP_LIST gShellMapList;
-/// Pointer to node of current directory in the mMapList.
-extern SHELL_MAP_LIST *gShellCurMapping;
-
-/**
- Returns the help MAN fileName for a given shell command.
-
- @retval !NULL The unicode string of the MAN filename.
- @retval NULL An error ocurred.
-
-**/
-typedef
-CONST CHAR16 *
-(EFIAPI *SHELL_GET_MAN_FILENAME)(
- VOID
- );
-
-/**
- Runs a shell command on a given command line.
-
- The specific operation of a given shell command is specified in the UEFI Shell
- Specification 2.0, or in the source of the given command.
-
- Upon completion of the command run the shell protocol and environment variables
- may have been updated due to the operation.
-
- @param[in] ImageHandle The ImageHandle to the app, or NULL if
- the command built into shell.
- @param[in] SystemTable The pointer to the system table.
-
- @retval RETURN_SUCCESS The shell command was successful.
- @retval RETURN_UNSUPPORTED The command is not supported.
-**/
-typedef
-SHELL_STATUS
-(EFIAPI *SHELL_RUN_COMMAND)(
- IN EFI_HANDLE ImageHandle,
- IN EFI_SYSTEM_TABLE *SystemTable
- );
-
-/**
- Registers the handlers of type SHELL_RUN_COMMAND and
- SHELL_GET_MAN_FILENAME for each shell command.
-
- If the ShellSupportLevel is greater than the value of
- PcdShellSupportLevel, then return RETURN_UNSUPPORTED.
-
- Registers the the handlers specified by GetHelpInfoHandler and CommandHandler
- with the command specified by CommandString. If the command named by
- CommandString has already been registered, then return
- RETURN_ALREADY_STARTED.
-
- If there are not enough resources available to register the handlers, then
- RETURN_OUT_OF_RESOURCES is returned.
-
- If CommandString is NULL, then ASSERT().
- If GetHelpInfoHandler is NULL, then ASSERT().
- If CommandHandler is NULL, then ASSERT().
- If ProfileName is NULL, then ASSERT().
-
- @param[in] CommandString The pointer to the command name. This is the
- name to look for on the command line in
- the shell.
- @param[in] CommandHandler The pointer to a function that runs the
- specified command.
- @param[in] GetManFileName The pointer to a function that provides man
- filename.
- @param[in] ShellMinSupportLevel The minimum Shell Support Level which has this
- function.
- @param[in] ProfileName The profile name to require for support of this
- function.
- @param[in] CanAffectLE Indicates whether this command's return value
- can change the LASTERROR environment variable.
- @param[in] HiiHandle The handle of this command's HII entry.
- @param[in] ManFormatHelp The HII locator for the help text.
-
- @retval RETURN_SUCCESS The handlers were registered.
- @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to
- register the shell command.
- @retval RETURN_UNSUPPORTED The ShellMinSupportLevel was higher than the
- currently allowed support level.
- @retval RETURN_ALREADY_STARTED The CommandString represents a command that
- is already registered. Only one handler set for
- a given command is allowed.
- @sa SHELL_GET_MAN_FILENAME
- @sa SHELL_RUN_COMMAND
-**/
-RETURN_STATUS
-EFIAPI
-ShellCommandRegisterCommandName (
- IN CONST CHAR16 *CommandString,
- IN SHELL_RUN_COMMAND CommandHandler,
- IN SHELL_GET_MAN_FILENAME GetManFileName,
- IN UINT32 ShellMinSupportLevel,
- IN CONST CHAR16 *ProfileName,
- IN CONST BOOLEAN CanAffectLE,
- IN CONST EFI_HII_HANDLE HiiHandle,
- IN CONST EFI_STRING_ID ManFormatHelp
- );
-
-/**
- Checks if a command string has been registered for CommandString, and if so, it runs
- the previously registered handler for that command with the command line.
-
- If CommandString is NULL, then ASSERT().
-
- If Sections is specified, then each section name listed will be compared in a case sensitive
- manner to the section names described in Appendix B UEFI Shell 2.0 Specification. If the section exists,
- it is appended to the returned help text. If the section does not exist, no
- information is returned. If Sections is NULL, then all help text information
- available is returned.
-
- @param[in] CommandString The pointer to the command name. This is the name
- found on the command line in the shell.
- @param[in, out] RetVal The pointer to the return value from the command handler.
-
- @param[in, out] CanAffectLE Indicates whether this command's return value
- needs to be placed into LASTERROR environment variable.
-
- @retval RETURN_SUCCESS The handler was run.
- @retval RETURN_NOT_FOUND The CommandString did not match a registered
- command name.
- @sa SHELL_RUN_COMMAND
-**/
-RETURN_STATUS
-EFIAPI
-ShellCommandRunCommandHandler (
- IN CONST CHAR16 *CommandString,
- IN OUT SHELL_STATUS *RetVal,
- IN OUT BOOLEAN *CanAffectLE OPTIONAL
- );
-
-/**
- Checks if a command string has been registered for CommandString, and if so, it
- returns the MAN filename specified for that command.
-
- If CommandString is NULL, then ASSERT().
-
- @param[in] CommandString The pointer to the command name. This is the name
- found on the command line in the shell.
-
- @retval NULL The CommandString was not a registered command.
- @retval other The name of the MAN file.
- @sa SHELL_GET_MAN_FILENAME
-**/
-CONST CHAR16 *
-EFIAPI
-ShellCommandGetManFileNameHandler (
- IN CONST CHAR16 *CommandString
- );
-
-typedef struct {
- LIST_ENTRY Link;
- CHAR16 *CommandString;
-} COMMAND_LIST;
-
-/**
- Get the list of all available shell internal commands. This is a linked list,
- via the LIST_ENTRY structure. Enumerate through it using the BaseLib linked
- list functions. Do not modify the values.
-
- @param[in] Sort TRUE to alphabetically sort the values first. FALSE otherwise.
-
- @return A linked list of all available shell commands.
-**/
-CONST COMMAND_LIST *
-EFIAPI
-ShellCommandGetCommandList (
- IN CONST BOOLEAN Sort
- );
-
-typedef struct {
- LIST_ENTRY Link;
- CHAR16 *CommandString;
- CHAR16 *Alias;
-} ALIAS_LIST;
-
-/**
- Registers aliases to be set as part of the initialization of the shell application.
-
- If Command is NULL, then ASSERT().
- If Alias is NULL, then ASSERT().
-
- @param[in] Command The pointer to the Command.
- @param[in] Alias The pointer to Alias.
-
- @retval RETURN_SUCCESS The handlers were registered.
- @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to
- register the shell command.
-**/
-RETURN_STATUS
-EFIAPI
-ShellCommandRegisterAlias (
- IN CONST CHAR16 *Command,
- IN CONST CHAR16 *Alias
- );
-
-/**
- Get the list of all shell alias commands. This is a linked list,
- via LIST_ENTRY structure. Enumerate through it using the BaseLib linked
- list functions. Do not modify the values.
-
- @return A linked list of all requested shell aliases.
-**/
-CONST ALIAS_LIST *
-EFIAPI
-ShellCommandGetInitAliasList (
- VOID
- );
-
-/**
- Determine if a given alias is on the list of built in aliases.
-
- @param[in] Alias The alias to test for.
-
- @retval TRUE The alias is a built in alias.
- @retval FALSE The alias is not a built in alias.
-**/
-BOOLEAN
-EFIAPI
-ShellCommandIsOnAliasList (
- IN CONST CHAR16 *Alias
- );
-
-/**
- Checks if a command is already on the list.
-
- @param[in] CommandString The command string to check for on the list.
-
- @retval TRUE CommandString represents a registered command.
- @retval FALSE CommandString does not represent a registered command.
-**/
-BOOLEAN
-EFIAPI
-ShellCommandIsCommandOnList (
- IN CONST CHAR16 *CommandString
- );
-
-/**
- Get the help text for a command.
-
- @param[in] CommandString The command name.
-
- @retval NULL No help text was found.
- @return The string of the help text. The caller required to free.
-**/
-CHAR16 *
-EFIAPI
-ShellCommandGetCommandHelp (
- IN CONST CHAR16 *CommandString
- );
-
-/**
- Function to make sure that the above pointers are valid.
-**/
-EFI_STATUS
-EFIAPI
-CommandInit (
- VOID
- );
-
-/**
- Function to determine current state of ECHO. Echo determines if lines from scripts
- and ECHO commands are enabled.
-
- @retval TRUE Echo is currently enabled.
- @retval FALSE Echo is currently disabled.
-**/
-BOOLEAN
-EFIAPI
-ShellCommandGetEchoState (
- VOID
- );
-
-/**
- Function to set current state of ECHO. Echo determines if lines from scripts
- and ECHO commands are enabled.
-
- @param[in] State TRUE to enable Echo, FALSE otherwise.
-**/
-VOID
-EFIAPI
-ShellCommandSetEchoState (
- IN BOOLEAN State
- );
-
-/**
- Indicate that the current shell or script should exit.
-
- @param[in] ScriptOnly TRUE if exiting a script; FALSE otherwise.
- @param[in] ErrorCode The 64 bit error code to return.
-**/
-VOID
-EFIAPI
-ShellCommandRegisterExit (
- IN BOOLEAN ScriptOnly,
- IN CONST UINT64 ErrorCode
- );
-
-/**
- Retrieve the Exit code.
-
- @return the value passed into RegisterExit.
-**/
-UINT64
-EFIAPI
-ShellCommandGetExitCode (
- VOID
- );
-
-/**
- Retrieve the Exit indicator.
-
- @retval TRUE Exit was indicated.
- @retval FALSE Exit was not indicated.
-**/
-BOOLEAN
-EFIAPI
-ShellCommandGetExit (
- VOID
- );
-
-/**
- Retrieve the Exit script indicator.
-
- If ShellCommandGetExit returns FALSE, then the return from this is undefined.
-
- @retval TRUE ScriptOnly was indicated.
- @retval FALSE ScriptOnly was not indicated.
-**/
-BOOLEAN
-EFIAPI
-ShellCommandGetScriptExit (
- VOID
- );
-
-typedef struct {
- LIST_ENTRY Link; ///< List enumerator items.
- UINTN Line; ///< What line of the script file this was on.
- CHAR16 *Cl; ///< The original command line.
- VOID *Data; ///< The data structure format dependant upon Command. (not always used)
- BOOLEAN Reset; ///< Reset the command (it must be treated like a initial run (but it may have data already))
-} SCRIPT_COMMAND_LIST;
-
-typedef struct {
- CHAR16 *ScriptName; ///< The filename of this script.
- CHAR16 **Argv; ///< The parmameters to the script file.
- UINTN Argc; ///< The count of parameters.
- LIST_ENTRY CommandList; ///< The script converted to a list of commands (SCRIPT_COMMAND_LIST objects).
- SCRIPT_COMMAND_LIST *CurrentCommand; ///< The command currently being operated. If !=NULL must be a member of CommandList.
- LIST_ENTRY SubstList; ///< A list of current script loop alias' (ALIAS_LIST objects) (Used for the for %-based replacement).
-} SCRIPT_FILE;
-
-/**
- Function to return a pointer to the currently running script file object.
-
- @retval NULL A script file is not currently running.
- @return A pointer to the current script file object.
-**/
-SCRIPT_FILE *
-EFIAPI
-ShellCommandGetCurrentScriptFile (
- VOID
- );
-
-/**
- Function to set a new script as the currently running one.
-
- This function will correctly stack and unstack nested scripts.
-
- @param[in] Script The pointer to new script information structure. If NULL,
- it removes and de-allocates the topmost Script structure.
-
- @return A pointer to the current running script file after this
- change. It is NULL if removing the final script.
-**/
-SCRIPT_FILE *
-EFIAPI
-ShellCommandSetNewScript (
- IN SCRIPT_FILE *Script OPTIONAL
- );
-
-/**
- Function to cleanup all memory from a SCRIPT_FILE structure.
-
- @param[in] Script The pointer to the structure to cleanup.
-**/
-VOID
-EFIAPI
-DeleteScriptFileStruct (
- IN SCRIPT_FILE *Script
- );
-
-/**
- Function to get the current Profile string.
-
- This is used to retrieve what profiles were installed.
-
- @retval NULL There are no installed profiles.
- @return A semicolon-delimited list of profiles.
-**/
-CONST CHAR16 *
-EFIAPI
-ShellCommandGetProfileList (
- VOID
- );
-
-typedef enum {
- MappingTypeFileSystem,
- MappingTypeBlockIo,
- MappingTypeMax
-} SHELL_MAPPING_TYPE;
-
-/**
- Function to generate the next default mapping name.
-
- If the return value is not NULL then it must be callee freed.
-
- @param Type What kind of mapping name to make.
-
- @retval NULL a memory allocation failed.
- @return a new map name string
-**/
-CHAR16 *
-EFIAPI
-ShellCommandCreateNewMappingName (
- IN CONST SHELL_MAPPING_TYPE Type
- );
-
-/**
- Function to initialize the table for creating consistent map names.
-
- @param[out] Table The pointer to pointer to pointer to DevicePathProtocol object.
-
- @retval EFI_SUCCESS The table was created successfully.
-**/
-EFI_STATUS
-EFIAPI
-ShellCommandConsistMappingInitialize (
- EFI_DEVICE_PATH_PROTOCOL ***Table
- );
-
-/**
- Function to uninitialize the table for creating consistent map names.
-
- The parameter must have been received from ShellCommandConsistMappingInitialize.
-
- @param[out] Table The pointer to pointer to DevicePathProtocol object.
-
- @retval EFI_SUCCESS The table was deleted successfully.
-**/
-EFI_STATUS
-EFIAPI
-ShellCommandConsistMappingUnInitialize (
- EFI_DEVICE_PATH_PROTOCOL **Table
- );
-
-/**
- Create a consistent mapped name for the device specified by DevicePath
- based on the Table.
-
- This must be called after ShellCommandConsistMappingInitialize() and
- before ShellCommandConsistMappingUnInitialize() is called.
-
- @param[in] DevicePath The pointer to the dev path for the device.
- @param[in] Table The Table of mapping information.
-
- @retval NULL A consistent mapped name could not be created.
- @return A pointer to a string allocated from pool with the device name.
-**/
-CHAR16 *
-EFIAPI
-ShellCommandConsistMappingGenMappingName (
- IN EFI_DEVICE_PATH_PROTOCOL *DevicePath,
- IN EFI_DEVICE_PATH_PROTOCOL **Table
- );
-
-/**
- Function to search the list of mappings for the first matching node on the
- list based on the MapKey.
-
- @param[in] MapKey The pointer to the string key to search for in the map.
-
- @return the node on the list.
-**/
-SHELL_MAP_LIST *
-EFIAPI
-ShellCommandFindMapItem (
- IN CONST CHAR16 *MapKey
- );
-
-/**
- Function to add a map node to the list of map items and update the "path" environment variable (optionally).
-
- If Path is TRUE (during initialization only), the path environment variable will also be updated to include
- default paths on the new map name...
-
- Path should be FALSE when this function is called from the protocol SetMap function.
-
- @param[in] Name The human readable mapped name.
- @param[in] DevicePath The Device Path for this map.
- @param[in] Flags The Flags attribute for this map item.
- @param[in] Path TRUE to update path, FALSE to skip this step (should only be TRUE during initialization).
-
- @retval EFI_SUCCESS The addition was successful.
- @retval EFI_OUT_OF_RESOURCES A memory allocation failed.
- @retval EFI_INVALID_PARAMETER A parameter was invalid.
-**/
-EFI_STATUS
-EFIAPI
-ShellCommandAddMapItemAndUpdatePath (
- IN CONST CHAR16 *Name,
- IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
- IN CONST UINT64 Flags,
- IN CONST BOOLEAN Path
- );
-
-/**
- Creates the default map names for each device path in the system with
- a protocol depending on the Type.
-
- Also sets up the default path environment variable if Type is FileSystem.
-
- @retval EFI_SUCCESS All map names were created successfully.
- @retval EFI_NOT_FOUND No protocols were found in the system.
- @return Error returned from gBS->LocateHandle().
-
- @sa LocateHandle
-**/
-EFI_STATUS
-EFIAPI
-ShellCommandCreateInitialMappingsAndPaths (
- VOID
- );
-
-/**
- Add mappings for any devices without one. Do not change any existing maps.
-
- @retval EFI_SUCCESS The operation was successful.
-**/
-EFI_STATUS
-EFIAPI
-ShellCommandUpdateMapping (
- VOID
- );
-
-/**
- Converts a SHELL_FILE_HANDLE to an EFI_FILE_PROTOCOL*.
-
- @param[in] Handle The SHELL_FILE_HANDLE to convert.
-
- @return a EFI_FILE_PROTOCOL* representing the same file.
-**/
-EFI_FILE_PROTOCOL *
-EFIAPI
-ConvertShellHandleToEfiFileProtocol (
- IN CONST SHELL_FILE_HANDLE Handle
- );
-
-/**
- Remove a SHELL_FILE_HANDLE frmo the list of SHELL_FILE_HANDLES.
-
- @param[in] Handle The SHELL_FILE_HANDLE to remove.
-
- @retval TRUE The item was removed.
- @retval FALSE The item was not found.
-**/
-BOOLEAN
-EFIAPI
-ShellFileHandleRemove (
- IN CONST SHELL_FILE_HANDLE Handle
- );
-
-/**
- Converts a EFI_FILE_PROTOCOL* to an SHELL_FILE_HANDLE.
-
- @param[in] Handle The pointer to EFI_FILE_PROTOCOL to convert.
- @param[in] Path The path to the file for verification.
-
- @return a SHELL_FILE_HANDLE representing the same file.
-**/
-SHELL_FILE_HANDLE
-EFIAPI
-ConvertEfiFileProtocolToShellHandle (
- IN CONST EFI_FILE_PROTOCOL *Handle,
- IN CONST CHAR16 *Path
- );
-
-/**
- Find the path that was logged with the specified SHELL_FILE_HANDLE.
-
- @param[in] Handle The SHELL_FILE_HANDLE to query on.
-
- @return A pointer to the path for the file.
-**/
-CONST CHAR16 *
-EFIAPI
-ShellFileHandleGetPath (
- IN CONST SHELL_FILE_HANDLE Handle
- );
-
-/**
- Function to determine if a SHELL_FILE_HANDLE is at the end of the file.
-
- This will NOT work on directories.
-
- If Handle is NULL, then ASSERT.
-
- @param[in] Handle the file handle
-
- @retval TRUE the position is at the end of the file
- @retval FALSE the position is not at the end of the file
-**/
-BOOLEAN
-EFIAPI
-ShellFileHandleEof (
- IN SHELL_FILE_HANDLE Handle
- );
-
-typedef struct {
- LIST_ENTRY Link;
- void *Buffer;
-} BUFFER_LIST;
-
-/**
- Frees any BUFFER_LIST defined type.
-
- @param[in] List The pointer to the list head.
-**/
-VOID
-EFIAPI
-FreeBufferList (
- IN BUFFER_LIST *List
- );
-
-/**
- Function printing hex output to the console.
-
- @param[in] Indent Number of spaces to indent.
- @param[in] Offset Offset to start with.
- @param[in] DataSize Length of data.
- @param[in] UserData Pointer to some data.
-**/
-VOID
-EFIAPI
-DumpHex (
- IN UINTN Indent,
- IN UINTN Offset,
- IN UINTN DataSize,
- IN VOID *UserData
- );
-
-/**
- Dump HEX data into buffer.
-
- @param[in] Buffer HEX data to be dumped in Buffer.
- @param[in] Indent How many spaces to indent the output.
- @param[in] Offset The offset of the printing.
- @param[in] DataSize The size in bytes of UserData.
- @param[in] UserData The data to print out.
-**/
-CHAR16 *
-EFIAPI
-CatSDumpHex (
- IN CHAR16 *Buffer,
- IN UINTN Indent,
- IN UINTN Offset,
- IN UINTN DataSize,
- IN VOID *UserData
- );
-
-//
-// Determines the ordering operation for ShellSortFileList().
-//
-typedef enum {
- //
- // Sort the EFI_SHELL_FILE_INFO objects by the FileName field, in increasing
- // order, using gUnicodeCollation->StriColl().
- //
- ShellSortFileListByFileName,
- //
- // Sort the EFI_SHELL_FILE_INFO objects by the FullName field, in increasing
- // order, using gUnicodeCollation->StriColl().
- //
- ShellSortFileListByFullName,
- ShellSortFileListMax
-} SHELL_SORT_FILE_LIST;
-
-/**
- Sort an EFI_SHELL_FILE_INFO list, optionally moving duplicates to a separate
- list.
-
- @param[in,out] FileList The list of EFI_SHELL_FILE_INFO objects to sort.
-
- If FileList is NULL on input, then FileList is
- considered an empty, hence already sorted, list.
-
- Otherwise, if (*FileList) is NULL on input, then
- EFI_INVALID_PARAMETER is returned.
-
- Otherwise, the caller is responsible for having
- initialized (*FileList)->Link with
- InitializeListHead(). No other fields in the
- (**FileList) head element are accessed by this
- function.
-
- On output, (*FileList) is sorted according to Order.
- If Duplicates is NULL on input, then duplicate
- elements are preserved, sorted stably, on
- (*FileList). If Duplicates is not NULL on input,
- then duplicates are moved (stably sorted) to the
- new, dynamically allocated (*Duplicates) list.
-
- @param[out] Duplicates If Duplicates is NULL on input, (*FileList) will be
- a monotonically ordered list on output, with
- duplicates stably sorted.
-
- If Duplicates is not NULL on input, (*FileList) will
- be a strictly monotonically oredered list on output,
- with duplicates separated (stably sorted) to
- (*Duplicates). All fields except Link will be
- zero-initialized in the (**Duplicates) head element.
- If no duplicates exist, then (*Duplicates) is set to
- NULL on output.
-
- @param[in] Order Determines the comparison operation between
- EFI_SHELL_FILE_INFO objects.
-
- @retval EFI_INVALID_PARAMETER (UINTN)Order is greater than or equal to
- (UINTN)ShellSortFileListMax. Neither the
- (*FileList) nor the (*Duplicates) list has
- been modified.
-
- @retval EFI_INVALID_PARAMETER (*FileList) was NULL on input. Neither the
- (*FileList) nor the (*Duplicates) list has
- been modified.
-
- @retval EFI_OUT_OF_RESOURCES Memory allocation failed. Neither the
- (*FileList) nor the (*Duplicates) list has
- been modified.
-
- @retval EFI_SUCCESS Sorting successful, including the case when
- FileList is NULL on input.
-**/
-EFI_STATUS
-EFIAPI
-ShellSortFileList (
- IN OUT EFI_SHELL_FILE_INFO **FileList,
- OUT EFI_SHELL_FILE_INFO **Duplicates OPTIONAL,
- IN SHELL_SORT_FILE_LIST Order
- );
-
-#endif //_SHELL_COMMAND_LIB_
+/** @file + Provides interface to shell internal functions for shell commands. + + This library is for use ONLY by shell commands linked into the shell application. + This library will not function if it is used for UEFI Shell 2.0 Applications. + + Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> + (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR> + (C) Copyright 2013-2014 Hewlett-Packard Development Company, L.P.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef _SHELL_COMMAND_LIB_ +#define _SHELL_COMMAND_LIB_ + +#include <Uefi.h> + +#include <Protocol/Shell.h> +#include <Protocol/ShellParameters.h> +#include <Protocol/UnicodeCollation.h> +#include <Protocol/SimpleFileSystem.h> + +#include <Library/UefiBootServicesTableLib.h> + +// +// The extern global protocol poionters. +// +extern EFI_UNICODE_COLLATION_PROTOCOL *gUnicodeCollation; +extern CONST CHAR16 *SupportLevel[]; + +// +// The map list objects. +// +typedef struct { + LIST_ENTRY Link; + EFI_DEVICE_PATH_PROTOCOL *DevicePath; + CHAR16 *MapName; + CHAR16 *CurrentDirectoryPath; + UINT64 Flags; +} SHELL_MAP_LIST; +/// List of Mappings - DeviceName and Drive Letter(ism). +extern SHELL_MAP_LIST gShellMapList; +/// Pointer to node of current directory in the mMapList. +extern SHELL_MAP_LIST *gShellCurMapping; + +/** + Returns the help MAN fileName for a given shell command. + + @retval !NULL The unicode string of the MAN filename. + @retval NULL An error ocurred. + +**/ +typedef +CONST CHAR16 * +(EFIAPI *SHELL_GET_MAN_FILENAME)( + VOID + ); + +/** + Runs a shell command on a given command line. + + The specific operation of a given shell command is specified in the UEFI Shell + Specification 2.0, or in the source of the given command. + + Upon completion of the command run the shell protocol and environment variables + may have been updated due to the operation. + + @param[in] ImageHandle The ImageHandle to the app, or NULL if + the command built into shell. + @param[in] SystemTable The pointer to the system table. + + @retval RETURN_SUCCESS The shell command was successful. + @retval RETURN_UNSUPPORTED The command is not supported. +**/ +typedef +SHELL_STATUS +(EFIAPI *SHELL_RUN_COMMAND)( + IN EFI_HANDLE ImageHandle, + IN EFI_SYSTEM_TABLE *SystemTable + ); + +/** + Registers the handlers of type SHELL_RUN_COMMAND and + SHELL_GET_MAN_FILENAME for each shell command. + + If the ShellSupportLevel is greater than the value of + PcdShellSupportLevel, then return RETURN_UNSUPPORTED. + + Registers the the handlers specified by GetHelpInfoHandler and CommandHandler + with the command specified by CommandString. If the command named by + CommandString has already been registered, then return + RETURN_ALREADY_STARTED. + + If there are not enough resources available to register the handlers, then + RETURN_OUT_OF_RESOURCES is returned. + + If CommandString is NULL, then ASSERT(). + If GetHelpInfoHandler is NULL, then ASSERT(). + If CommandHandler is NULL, then ASSERT(). + If ProfileName is NULL, then ASSERT(). + + @param[in] CommandString The pointer to the command name. This is the + name to look for on the command line in + the shell. + @param[in] CommandHandler The pointer to a function that runs the + specified command. + @param[in] GetManFileName The pointer to a function that provides man + filename. + @param[in] ShellMinSupportLevel The minimum Shell Support Level which has this + function. + @param[in] ProfileName The profile name to require for support of this + function. + @param[in] CanAffectLE Indicates whether this command's return value + can change the LASTERROR environment variable. + @param[in] HiiHandle The handle of this command's HII entry. + @param[in] ManFormatHelp The HII locator for the help text. + + @retval RETURN_SUCCESS The handlers were registered. + @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to + register the shell command. + @retval RETURN_UNSUPPORTED The ShellMinSupportLevel was higher than the + currently allowed support level. + @retval RETURN_ALREADY_STARTED The CommandString represents a command that + is already registered. Only one handler set for + a given command is allowed. + @sa SHELL_GET_MAN_FILENAME + @sa SHELL_RUN_COMMAND +**/ +RETURN_STATUS +EFIAPI +ShellCommandRegisterCommandName ( + IN CONST CHAR16 *CommandString, + IN SHELL_RUN_COMMAND CommandHandler, + IN SHELL_GET_MAN_FILENAME GetManFileName, + IN UINT32 ShellMinSupportLevel, + IN CONST CHAR16 *ProfileName, + IN CONST BOOLEAN CanAffectLE, + IN CONST EFI_HII_HANDLE HiiHandle, + IN CONST EFI_STRING_ID ManFormatHelp + ); + +/** + Checks if a command string has been registered for CommandString, and if so, it runs + the previously registered handler for that command with the command line. + + If CommandString is NULL, then ASSERT(). + + If Sections is specified, then each section name listed will be compared in a case sensitive + manner to the section names described in Appendix B UEFI Shell 2.0 Specification. If the section exists, + it is appended to the returned help text. If the section does not exist, no + information is returned. If Sections is NULL, then all help text information + available is returned. + + @param[in] CommandString The pointer to the command name. This is the name + found on the command line in the shell. + @param[in, out] RetVal The pointer to the return value from the command handler. + + @param[in, out] CanAffectLE Indicates whether this command's return value + needs to be placed into LASTERROR environment variable. + + @retval RETURN_SUCCESS The handler was run. + @retval RETURN_NOT_FOUND The CommandString did not match a registered + command name. + @sa SHELL_RUN_COMMAND +**/ +RETURN_STATUS +EFIAPI +ShellCommandRunCommandHandler ( + IN CONST CHAR16 *CommandString, + IN OUT SHELL_STATUS *RetVal, + IN OUT BOOLEAN *CanAffectLE OPTIONAL + ); + +/** + Checks if a command string has been registered for CommandString, and if so, it + returns the MAN filename specified for that command. + + If CommandString is NULL, then ASSERT(). + + @param[in] CommandString The pointer to the command name. This is the name + found on the command line in the shell. + + @retval NULL The CommandString was not a registered command. + @retval other The name of the MAN file. + @sa SHELL_GET_MAN_FILENAME +**/ +CONST CHAR16 * +EFIAPI +ShellCommandGetManFileNameHandler ( + IN CONST CHAR16 *CommandString + ); + +typedef struct { + LIST_ENTRY Link; + CHAR16 *CommandString; +} COMMAND_LIST; + +/** + Get the list of all available shell internal commands. This is a linked list, + via the LIST_ENTRY structure. Enumerate through it using the BaseLib linked + list functions. Do not modify the values. + + @param[in] Sort TRUE to alphabetically sort the values first. FALSE otherwise. + + @return A linked list of all available shell commands. +**/ +CONST COMMAND_LIST * +EFIAPI +ShellCommandGetCommandList ( + IN CONST BOOLEAN Sort + ); + +typedef struct { + LIST_ENTRY Link; + CHAR16 *CommandString; + CHAR16 *Alias; +} ALIAS_LIST; + +/** + Registers aliases to be set as part of the initialization of the shell application. + + If Command is NULL, then ASSERT(). + If Alias is NULL, then ASSERT(). + + @param[in] Command The pointer to the Command. + @param[in] Alias The pointer to Alias. + + @retval RETURN_SUCCESS The handlers were registered. + @retval RETURN_OUT_OF_RESOURCES There are not enough resources available to + register the shell command. +**/ +RETURN_STATUS +EFIAPI +ShellCommandRegisterAlias ( + IN CONST CHAR16 *Command, + IN CONST CHAR16 *Alias + ); + +/** + Get the list of all shell alias commands. This is a linked list, + via LIST_ENTRY structure. Enumerate through it using the BaseLib linked + list functions. Do not modify the values. + + @return A linked list of all requested shell aliases. +**/ +CONST ALIAS_LIST * +EFIAPI +ShellCommandGetInitAliasList ( + VOID + ); + +/** + Determine if a given alias is on the list of built in aliases. + + @param[in] Alias The alias to test for. + + @retval TRUE The alias is a built in alias. + @retval FALSE The alias is not a built in alias. +**/ +BOOLEAN +EFIAPI +ShellCommandIsOnAliasList ( + IN CONST CHAR16 *Alias + ); + +/** + Checks if a command is already on the list. + + @param[in] CommandString The command string to check for on the list. + + @retval TRUE CommandString represents a registered command. + @retval FALSE CommandString does not represent a registered command. +**/ +BOOLEAN +EFIAPI +ShellCommandIsCommandOnList ( + IN CONST CHAR16 *CommandString + ); + +/** + Get the help text for a command. + + @param[in] CommandString The command name. + + @retval NULL No help text was found. + @return The string of the help text. The caller required to free. +**/ +CHAR16 * +EFIAPI +ShellCommandGetCommandHelp ( + IN CONST CHAR16 *CommandString + ); + +/** + Function to make sure that the above pointers are valid. +**/ +EFI_STATUS +EFIAPI +CommandInit ( + VOID + ); + +/** + Function to determine current state of ECHO. Echo determines if lines from scripts + and ECHO commands are enabled. + + @retval TRUE Echo is currently enabled. + @retval FALSE Echo is currently disabled. +**/ +BOOLEAN +EFIAPI +ShellCommandGetEchoState ( + VOID + ); + +/** + Function to set current state of ECHO. Echo determines if lines from scripts + and ECHO commands are enabled. + + @param[in] State TRUE to enable Echo, FALSE otherwise. +**/ +VOID +EFIAPI +ShellCommandSetEchoState ( + IN BOOLEAN State + ); + +/** + Indicate that the current shell or script should exit. + + @param[in] ScriptOnly TRUE if exiting a script; FALSE otherwise. + @param[in] ErrorCode The 64 bit error code to return. +**/ +VOID +EFIAPI +ShellCommandRegisterExit ( + IN BOOLEAN ScriptOnly, + IN CONST UINT64 ErrorCode + ); + +/** + Retrieve the Exit code. + + @return the value passed into RegisterExit. +**/ +UINT64 +EFIAPI +ShellCommandGetExitCode ( + VOID + ); + +/** + Retrieve the Exit indicator. + + @retval TRUE Exit was indicated. + @retval FALSE Exit was not indicated. +**/ +BOOLEAN +EFIAPI +ShellCommandGetExit ( + VOID + ); + +/** + Retrieve the Exit script indicator. + + If ShellCommandGetExit returns FALSE, then the return from this is undefined. + + @retval TRUE ScriptOnly was indicated. + @retval FALSE ScriptOnly was not indicated. +**/ +BOOLEAN +EFIAPI +ShellCommandGetScriptExit ( + VOID + ); + +typedef struct { + LIST_ENTRY Link; ///< List enumerator items. + UINTN Line; ///< What line of the script file this was on. + CHAR16 *Cl; ///< The original command line. + VOID *Data; ///< The data structure format dependant upon Command. (not always used) + BOOLEAN Reset; ///< Reset the command (it must be treated like a initial run (but it may have data already)) +} SCRIPT_COMMAND_LIST; + +typedef struct { + CHAR16 *ScriptName; ///< The filename of this script. + CHAR16 **Argv; ///< The parmameters to the script file. + UINTN Argc; ///< The count of parameters. + LIST_ENTRY CommandList; ///< The script converted to a list of commands (SCRIPT_COMMAND_LIST objects). + SCRIPT_COMMAND_LIST *CurrentCommand; ///< The command currently being operated. If !=NULL must be a member of CommandList. + LIST_ENTRY SubstList; ///< A list of current script loop alias' (ALIAS_LIST objects) (Used for the for %-based replacement). +} SCRIPT_FILE; + +/** + Function to return a pointer to the currently running script file object. + + @retval NULL A script file is not currently running. + @return A pointer to the current script file object. +**/ +SCRIPT_FILE * +EFIAPI +ShellCommandGetCurrentScriptFile ( + VOID + ); + +/** + Function to set a new script as the currently running one. + + This function will correctly stack and unstack nested scripts. + + @param[in] Script The pointer to new script information structure. If NULL, + it removes and de-allocates the topmost Script structure. + + @return A pointer to the current running script file after this + change. It is NULL if removing the final script. +**/ +SCRIPT_FILE * +EFIAPI +ShellCommandSetNewScript ( + IN SCRIPT_FILE *Script OPTIONAL + ); + +/** + Function to cleanup all memory from a SCRIPT_FILE structure. + + @param[in] Script The pointer to the structure to cleanup. +**/ +VOID +EFIAPI +DeleteScriptFileStruct ( + IN SCRIPT_FILE *Script + ); + +/** + Function to get the current Profile string. + + This is used to retrieve what profiles were installed. + + @retval NULL There are no installed profiles. + @return A semicolon-delimited list of profiles. +**/ +CONST CHAR16 * +EFIAPI +ShellCommandGetProfileList ( + VOID + ); + +typedef enum { + MappingTypeFileSystem, + MappingTypeBlockIo, + MappingTypeMax +} SHELL_MAPPING_TYPE; + +/** + Function to generate the next default mapping name. + + If the return value is not NULL then it must be callee freed. + + @param Type What kind of mapping name to make. + + @retval NULL a memory allocation failed. + @return a new map name string +**/ +CHAR16 * +EFIAPI +ShellCommandCreateNewMappingName ( + IN CONST SHELL_MAPPING_TYPE Type + ); + +/** + Function to initialize the table for creating consistent map names. + + @param[out] Table The pointer to pointer to pointer to DevicePathProtocol object. + + @retval EFI_SUCCESS The table was created successfully. +**/ +EFI_STATUS +EFIAPI +ShellCommandConsistMappingInitialize ( + EFI_DEVICE_PATH_PROTOCOL ***Table + ); + +/** + Function to uninitialize the table for creating consistent map names. + + The parameter must have been received from ShellCommandConsistMappingInitialize. + + @param[out] Table The pointer to pointer to DevicePathProtocol object. + + @retval EFI_SUCCESS The table was deleted successfully. +**/ +EFI_STATUS +EFIAPI +ShellCommandConsistMappingUnInitialize ( + EFI_DEVICE_PATH_PROTOCOL **Table + ); + +/** + Create a consistent mapped name for the device specified by DevicePath + based on the Table. + + This must be called after ShellCommandConsistMappingInitialize() and + before ShellCommandConsistMappingUnInitialize() is called. + + @param[in] DevicePath The pointer to the dev path for the device. + @param[in] Table The Table of mapping information. + + @retval NULL A consistent mapped name could not be created. + @return A pointer to a string allocated from pool with the device name. +**/ +CHAR16 * +EFIAPI +ShellCommandConsistMappingGenMappingName ( + IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, + IN EFI_DEVICE_PATH_PROTOCOL **Table + ); + +/** + Function to search the list of mappings for the first matching node on the + list based on the MapKey. + + @param[in] MapKey The pointer to the string key to search for in the map. + + @return the node on the list. +**/ +SHELL_MAP_LIST * +EFIAPI +ShellCommandFindMapItem ( + IN CONST CHAR16 *MapKey + ); + +/** + Function to add a map node to the list of map items and update the "path" environment variable (optionally). + + If Path is TRUE (during initialization only), the path environment variable will also be updated to include + default paths on the new map name... + + Path should be FALSE when this function is called from the protocol SetMap function. + + @param[in] Name The human readable mapped name. + @param[in] DevicePath The Device Path for this map. + @param[in] Flags The Flags attribute for this map item. + @param[in] Path TRUE to update path, FALSE to skip this step (should only be TRUE during initialization). + + @retval EFI_SUCCESS The addition was successful. + @retval EFI_OUT_OF_RESOURCES A memory allocation failed. + @retval EFI_INVALID_PARAMETER A parameter was invalid. +**/ +EFI_STATUS +EFIAPI +ShellCommandAddMapItemAndUpdatePath ( + IN CONST CHAR16 *Name, + IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, + IN CONST UINT64 Flags, + IN CONST BOOLEAN Path + ); + +/** + Creates the default map names for each device path in the system with + a protocol depending on the Type. + + Also sets up the default path environment variable if Type is FileSystem. + + @retval EFI_SUCCESS All map names were created successfully. + @retval EFI_NOT_FOUND No protocols were found in the system. + @return Error returned from gBS->LocateHandle(). + + @sa LocateHandle +**/ +EFI_STATUS +EFIAPI +ShellCommandCreateInitialMappingsAndPaths ( + VOID + ); + +/** + Add mappings for any devices without one. Do not change any existing maps. + + @retval EFI_SUCCESS The operation was successful. +**/ +EFI_STATUS +EFIAPI +ShellCommandUpdateMapping ( + VOID + ); + +/** + Converts a SHELL_FILE_HANDLE to an EFI_FILE_PROTOCOL*. + + @param[in] Handle The SHELL_FILE_HANDLE to convert. + + @return a EFI_FILE_PROTOCOL* representing the same file. +**/ +EFI_FILE_PROTOCOL * +EFIAPI +ConvertShellHandleToEfiFileProtocol ( + IN CONST SHELL_FILE_HANDLE Handle + ); + +/** + Remove a SHELL_FILE_HANDLE frmo the list of SHELL_FILE_HANDLES. + + @param[in] Handle The SHELL_FILE_HANDLE to remove. + + @retval TRUE The item was removed. + @retval FALSE The item was not found. +**/ +BOOLEAN +EFIAPI +ShellFileHandleRemove ( + IN CONST SHELL_FILE_HANDLE Handle + ); + +/** + Converts a EFI_FILE_PROTOCOL* to an SHELL_FILE_HANDLE. + + @param[in] Handle The pointer to EFI_FILE_PROTOCOL to convert. + @param[in] Path The path to the file for verification. + + @return a SHELL_FILE_HANDLE representing the same file. +**/ +SHELL_FILE_HANDLE +EFIAPI +ConvertEfiFileProtocolToShellHandle ( + IN CONST EFI_FILE_PROTOCOL *Handle, + IN CONST CHAR16 *Path + ); + +/** + Find the path that was logged with the specified SHELL_FILE_HANDLE. + + @param[in] Handle The SHELL_FILE_HANDLE to query on. + + @return A pointer to the path for the file. +**/ +CONST CHAR16 * +EFIAPI +ShellFileHandleGetPath ( + IN CONST SHELL_FILE_HANDLE Handle + ); + +/** + Function to determine if a SHELL_FILE_HANDLE is at the end of the file. + + This will NOT work on directories. + + If Handle is NULL, then ASSERT. + + @param[in] Handle the file handle + + @retval TRUE the position is at the end of the file + @retval FALSE the position is not at the end of the file +**/ +BOOLEAN +EFIAPI +ShellFileHandleEof ( + IN SHELL_FILE_HANDLE Handle + ); + +typedef struct { + LIST_ENTRY Link; + void *Buffer; +} BUFFER_LIST; + +/** + Frees any BUFFER_LIST defined type. + + @param[in] List The pointer to the list head. +**/ +VOID +EFIAPI +FreeBufferList ( + IN BUFFER_LIST *List + ); + +/** + Function printing hex output to the console. + + @param[in] Indent Number of spaces to indent. + @param[in] Offset Offset to start with. + @param[in] DataSize Length of data. + @param[in] UserData Pointer to some data. +**/ +VOID +EFIAPI +DumpHex ( + IN UINTN Indent, + IN UINTN Offset, + IN UINTN DataSize, + IN VOID *UserData + ); + +/** + Dump HEX data into buffer. + + @param[in] Buffer HEX data to be dumped in Buffer. + @param[in] Indent How many spaces to indent the output. + @param[in] Offset The offset of the printing. + @param[in] DataSize The size in bytes of UserData. + @param[in] UserData The data to print out. +**/ +CHAR16 * +EFIAPI +CatSDumpHex ( + IN CHAR16 *Buffer, + IN UINTN Indent, + IN UINTN Offset, + IN UINTN DataSize, + IN VOID *UserData + ); + +// +// Determines the ordering operation for ShellSortFileList(). +// +typedef enum { + // + // Sort the EFI_SHELL_FILE_INFO objects by the FileName field, in increasing + // order, using gUnicodeCollation->StriColl(). + // + ShellSortFileListByFileName, + // + // Sort the EFI_SHELL_FILE_INFO objects by the FullName field, in increasing + // order, using gUnicodeCollation->StriColl(). + // + ShellSortFileListByFullName, + ShellSortFileListMax +} SHELL_SORT_FILE_LIST; + +/** + Sort an EFI_SHELL_FILE_INFO list, optionally moving duplicates to a separate + list. + + @param[in,out] FileList The list of EFI_SHELL_FILE_INFO objects to sort. + + If FileList is NULL on input, then FileList is + considered an empty, hence already sorted, list. + + Otherwise, if (*FileList) is NULL on input, then + EFI_INVALID_PARAMETER is returned. + + Otherwise, the caller is responsible for having + initialized (*FileList)->Link with + InitializeListHead(). No other fields in the + (**FileList) head element are accessed by this + function. + + On output, (*FileList) is sorted according to Order. + If Duplicates is NULL on input, then duplicate + elements are preserved, sorted stably, on + (*FileList). If Duplicates is not NULL on input, + then duplicates are moved (stably sorted) to the + new, dynamically allocated (*Duplicates) list. + + @param[out] Duplicates If Duplicates is NULL on input, (*FileList) will be + a monotonically ordered list on output, with + duplicates stably sorted. + + If Duplicates is not NULL on input, (*FileList) will + be a strictly monotonically oredered list on output, + with duplicates separated (stably sorted) to + (*Duplicates). All fields except Link will be + zero-initialized in the (**Duplicates) head element. + If no duplicates exist, then (*Duplicates) is set to + NULL on output. + + @param[in] Order Determines the comparison operation between + EFI_SHELL_FILE_INFO objects. + + @retval EFI_INVALID_PARAMETER (UINTN)Order is greater than or equal to + (UINTN)ShellSortFileListMax. Neither the + (*FileList) nor the (*Duplicates) list has + been modified. + + @retval EFI_INVALID_PARAMETER (*FileList) was NULL on input. Neither the + (*FileList) nor the (*Duplicates) list has + been modified. + + @retval EFI_OUT_OF_RESOURCES Memory allocation failed. Neither the + (*FileList) nor the (*Duplicates) list has + been modified. + + @retval EFI_SUCCESS Sorting successful, including the case when + FileList is NULL on input. +**/ +EFI_STATUS +EFIAPI +ShellSortFileList ( + IN OUT EFI_SHELL_FILE_INFO **FileList, + OUT EFI_SHELL_FILE_INFO **Duplicates OPTIONAL, + IN SHELL_SORT_FILE_LIST Order + ); + +#endif //_SHELL_COMMAND_LIB_ diff --git a/ShellPkg/Include/Library/ShellLib.h b/ShellPkg/Include/Library/ShellLib.h index f41bc4851c..cbfd3c2004 100644 --- a/ShellPkg/Include/Library/ShellLib.h +++ b/ShellPkg/Include/Library/ShellLib.h @@ -1,1431 +1,1431 @@ -/** @file
- Provides interface to shell functionality for shell commands and applications.
-
- Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
- Copyright 2018 Dell Technologies.<BR>
- SPDX-License-Identifier: BSD-2-Clause-Patent
-
-**/
-
-#ifndef __SHELL_LIB__
-#define __SHELL_LIB__
-
-#include <Uefi.h>
-#include <Guid/FileInfo.h>
-#include <Protocol/SimpleFileSystem.h>
-#include <Protocol/LoadedImage.h>
-#include <Protocol/EfiShellInterface.h>
-#include <Protocol/EfiShellEnvironment2.h>
-#include <Protocol/Shell.h>
-#include <Protocol/ShellParameters.h>
-
-#define SHELL_FREE_NON_NULL(Pointer) \
- do { \
- if ((Pointer) != NULL) { \
- FreePool((Pointer)); \
- (Pointer) = NULL; \
- } \
- } while(FALSE)
-
-extern EFI_SHELL_PARAMETERS_PROTOCOL *gEfiShellParametersProtocol;
-extern EFI_SHELL_PROTOCOL *gEfiShellProtocol;
-
-/**
- Return a clean, fully-qualified version of an input path. If the return value
- is non-NULL the caller must free the memory when it is no longer needed.
-
- If asserts are disabled, and if the input parameter is NULL, NULL is returned.
-
- If there is not enough memory available to create the fully-qualified path or
- a copy of the input path, NULL is returned.
-
- If there is no working directory, a clean copy of Path is returned.
-
- Otherwise, the current file system or working directory (as appropriate) is
- prepended to Path and the resulting path is cleaned and returned.
-
- NOTE: If the input path is an empty string, then the current working directory
- (if it exists) is returned. In other words, an empty input path is treated
- exactly the same as ".".
-
- @param[in] Path A pointer to some file or directory path.
-
- @retval NULL The input path is NULL or out of memory.
-
- @retval non-NULL A pointer to a clean, fully-qualified version of Path.
- If there is no working directory, then a pointer to a
- clean, but not necessarily fully-qualified version of
- Path. The caller must free this memory when it is no
- longer needed.
-**/
-CHAR16 *
-EFIAPI
-FullyQualifyPath (
- IN CONST CHAR16 *Path
- );
-
-/**
- This function will retrieve the information about the file for the handle
- specified and store it in allocated pool memory.
-
- This function allocates a buffer to store the file's information. It is the
- caller's responsibility to free the buffer.
-
- @param[in] FileHandle The file handle of the file for which information is
- being requested.
-
- @retval NULL Information could not be retrieved.
-
- @return The information about the file.
-**/
-EFI_FILE_INFO *
-EFIAPI
-ShellGetFileInfo (
- IN SHELL_FILE_HANDLE FileHandle
- );
-
-/**
- This function sets the information about the file for the opened handle
- specified.
-
- @param[in] FileHandle The file handle of the file for which information
- is being set.
-
- @param[in] FileInfo The information to set.
-
- @retval EFI_SUCCESS The information was set.
- @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid.
- @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo.
- @retval EFI_NO_MEDIA The device has no medium.
- @retval EFI_DEVICE_ERROR The device reported an error.
- @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
- @retval EFI_WRITE_PROTECTED The file or medium is write protected.
- @retval EFI_ACCESS_DENIED The file was opened read only.
- @retval EFI_VOLUME_FULL The volume is full.
-**/
-EFI_STATUS
-EFIAPI
-ShellSetFileInfo (
- IN SHELL_FILE_HANDLE FileHandle,
- IN EFI_FILE_INFO *FileInfo
- );
-
-/**
- This function will open a file or directory referenced by DevicePath.
-
- This function opens a file with the open mode according to the file path. The
- Attributes is valid only for EFI_FILE_MODE_CREATE.
-
- @param[in, out] FilePath On input, the device path to the file. On output,
- the remaining device path.
- @param[out] FileHandle Pointer to the file handle.
- @param[in] OpenMode The mode to open the file with.
- @param[in] Attributes The file's file attributes.
-
- @retval EFI_SUCCESS The information was set.
- @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
- @retval EFI_UNSUPPORTED Could not open the file path.
- @retval EFI_NOT_FOUND The specified file could not be found on the
- device or the file system could not be found on
- the device.
- @retval EFI_NO_MEDIA The device has no medium.
- @retval EFI_MEDIA_CHANGED The device has a different medium in it or the
- medium is no longer supported.
- @retval EFI_DEVICE_ERROR The device reported an error.
- @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
- @retval EFI_WRITE_PROTECTED The file or medium is write protected.
- @retval EFI_ACCESS_DENIED The file was opened read only.
- @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the
- file.
- @retval EFI_VOLUME_FULL The volume is full.
-**/
-EFI_STATUS
-EFIAPI
-ShellOpenFileByDevicePath (
- IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath,
- OUT SHELL_FILE_HANDLE *FileHandle,
- IN UINT64 OpenMode,
- IN UINT64 Attributes
- );
-
-/**
- This function will open a file or directory referenced by filename.
-
- If return is EFI_SUCCESS, the Filehandle is the opened file's handle;
- otherwise, the Filehandle is NULL. Attributes is valid only for
- EFI_FILE_MODE_CREATE.
-
- @param[in] FileName The pointer to file name.
- @param[out] FileHandle The pointer to the file handle.
- @param[in] OpenMode The mode to open the file with.
- @param[in] Attributes The file's file attributes.
-
- @retval EFI_SUCCESS The information was set.
- @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
- @retval EFI_UNSUPPORTED Could not open the file path.
- @retval EFI_NOT_FOUND The specified file could not be found on the
- device or the file system could not be found
- on the device.
- @retval EFI_NO_MEDIA The device has no medium.
- @retval EFI_MEDIA_CHANGED The device has a different medium in it or the
- medium is no longer supported.
- @retval EFI_DEVICE_ERROR The device reported an error.
- @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
- @retval EFI_WRITE_PROTECTED The file or medium is write protected.
- @retval EFI_ACCESS_DENIED The file was opened read only.
- @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the
- file.
- @retval EFI_VOLUME_FULL The volume is full.
-**/
-EFI_STATUS
-EFIAPI
-ShellOpenFileByName (
- IN CONST CHAR16 *FileName,
- OUT SHELL_FILE_HANDLE *FileHandle,
- IN UINT64 OpenMode,
- IN UINT64 Attributes
- );
-
-/**
- This function creates a directory.
-
- If return is EFI_SUCCESS, the Filehandle is the opened directory's handle;
- otherwise, the Filehandle is NULL. If the directory already existed, this
- function opens the existing directory.
-
- @param[in] DirectoryName The pointer to Directory name.
- @param[out] FileHandle The pointer to the file handle.
-
- @retval EFI_SUCCESS The information was set.
- @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
- @retval EFI_UNSUPPORTED Could not open the file path.
- @retval EFI_NOT_FOUND The specified file could not be found on the
- device, or the file system could not be found
- on the device.
- @retval EFI_NO_MEDIA The device has no medium.
- @retval EFI_MEDIA_CHANGED The device has a different medium in it or the
- medium is no longer supported.
- @retval EFI_DEVICE_ERROR The device reported an error.
- @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
- @retval EFI_WRITE_PROTECTED The file or medium is write protected.
- @retval EFI_ACCESS_DENIED The file was opened read only.
- @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the
- file.
- @retval EFI_VOLUME_FULL The volume is full.
-**/
-EFI_STATUS
-EFIAPI
-ShellCreateDirectory (
- IN CONST CHAR16 *DirectoryName,
- OUT SHELL_FILE_HANDLE *FileHandle
- );
-
-/**
- This function reads information from an opened file.
-
- If FileHandle is not a directory, the function reads the requested number of
- bytes from the file at the file's current position and returns them in Buffer.
- If the read goes beyond the end of the file, the read length is truncated to the
- end of the file. The file's current position is increased by the number of bytes
- returned. If FileHandle is a directory, the function reads the directory entry
- at the file's current position and returns the entry in Buffer. If the Buffer
- is not large enough to hold the current directory entry, then
- EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated.
- BufferSize is set to be the size of the buffer needed to read the entry. On
- success, the current position is updated to the next directory entry. If there
- are no more directory entries, the read returns a zero-length buffer.
- EFI_FILE_INFO is the structure returned as the directory entry.
-
- @param[in] FileHandle The opened file handle.
- @param[in, out] ReadSize On input the size of buffer in bytes. On return
- the number of bytes written.
- @param[out] Buffer The buffer to put read data into.
-
- @retval EFI_SUCCESS Data was read.
- @retval EFI_NO_MEDIA The device has no media.
- @retval EFI_DEVICE_ERROR The device reported an error.
- @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
- @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required
- size.
-
-**/
-EFI_STATUS
-EFIAPI
-ShellReadFile (
- IN SHELL_FILE_HANDLE FileHandle,
- IN OUT UINTN *ReadSize,
- OUT VOID *Buffer
- );
-
-/**
- Write data to a file.
-
- This function writes the specified number of bytes to the file at the current
- file position. The current file position is advanced the actual number of bytes
- written, which is returned in BufferSize. Partial writes only occur when there
- has been a data error during the write attempt (such as "volume space full").
- The file is automatically grown to hold the data if required. Direct writes to
- opened directories are not supported.
-
- @param[in] FileHandle The opened file for writing.
-
- @param[in, out] BufferSize On input the number of bytes in Buffer. On output
- the number of bytes written.
-
- @param[in] Buffer The buffer containing data to write is stored.
-
- @retval EFI_SUCCESS Data was written.
- @retval EFI_UNSUPPORTED Writes to an open directory are not supported.
- @retval EFI_NO_MEDIA The device has no media.
- @retval EFI_DEVICE_ERROR The device reported an error.
- @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
- @retval EFI_WRITE_PROTECTED The device is write-protected.
- @retval EFI_ACCESS_DENIED The file was open for read only.
- @retval EFI_VOLUME_FULL The volume is full.
-**/
-EFI_STATUS
-EFIAPI
-ShellWriteFile (
- IN SHELL_FILE_HANDLE FileHandle,
- IN OUT UINTN *BufferSize,
- IN VOID *Buffer
- );
-
-/**
- Close an open file handle.
-
- This function closes a specified file handle. All "dirty" cached file data is
- flushed to the device, and the file is closed. In all cases the handle is
- closed.
-
- @param[in] FileHandle The file handle to close.
-
- @retval EFI_SUCCESS The file handle was closed successfully.
- @retval INVALID_PARAMETER One of the parameters has an invalid value.
-**/
-EFI_STATUS
-EFIAPI
-ShellCloseFile (
- IN SHELL_FILE_HANDLE *FileHandle
- );
-
-/**
- Delete a file and close the handle
-
- This function closes and deletes a file. In all cases the file handle is closed.
- If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is
- returned, but the handle is still closed.
-
- @param[in] FileHandle The file handle to delete.
-
- @retval EFI_SUCCESS The file was closed successfully.
- @retval EFI_WARN_DELETE_FAILURE The handle was closed, but the file was not
- deleted.
- @retval INVALID_PARAMETER One of the parameters has an invalid value.
-**/
-EFI_STATUS
-EFIAPI
-ShellDeleteFile (
- IN SHELL_FILE_HANDLE *FileHandle
- );
-
-/**
- Set the current position in a file.
-
- This function sets the current file position for the handle to the position
- supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only
- absolute positioning is supported, and moving past the end of the file is
- allowed (a subsequent write would grow the file). Moving to position
- 0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file.
- If FileHandle is a directory, the only position that may be set is zero. This
- has the effect of starting the read process of the directory entries over.
-
- @param[in] FileHandle The file handle on which the position is being set.
-
- @param[in] Position The byte position from the beginning of the file.
-
- @retval EFI_SUCCESS Operation completed successfully.
- @retval EFI_UNSUPPORTED The seek request for non-zero is not valid on
- directories.
- @retval INVALID_PARAMETER One of the parameters has an invalid value.
-**/
-EFI_STATUS
-EFIAPI
-ShellSetFilePosition (
- IN SHELL_FILE_HANDLE FileHandle,
- IN UINT64 Position
- );
-
-/**
- Gets a file's current position
-
- This function retrieves the current file position for the file handle. For
- directories, the current file position has no meaning outside of the file
- system driver and as such the operation is not supported. An error is returned
- if FileHandle is a directory.
-
- @param[in] FileHandle The open file handle on which to get the position.
- @param[out] Position The byte position from the beginning of the file.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval INVALID_PARAMETER One of the parameters has an invalid value.
- @retval EFI_UNSUPPORTED The request is not valid on directories.
-**/
-EFI_STATUS
-EFIAPI
-ShellGetFilePosition (
- IN SHELL_FILE_HANDLE FileHandle,
- OUT UINT64 *Position
- );
-
-/**
- Flushes data on a file
-
- This function flushes all modified data associated with a file to a device.
-
- @param[in] FileHandle The file handle on which to flush data.
-
- @retval EFI_SUCCESS The data was flushed.
- @retval EFI_NO_MEDIA The device has no media.
- @retval EFI_DEVICE_ERROR The device reported an error.
- @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
- @retval EFI_WRITE_PROTECTED The file or medium is write protected.
- @retval EFI_ACCESS_DENIED The file was opened for read only.
-**/
-EFI_STATUS
-EFIAPI
-ShellFlushFile (
- IN SHELL_FILE_HANDLE FileHandle
- );
-
-/** Retrieve first entry from a directory.
-
- This function takes an open directory handle and gets information from the
- first entry in the directory. A buffer is allocated to contain
- the information and a pointer to the buffer is returned in *Buffer. The
- caller can use ShellFindNextFile() to get subsequent directory entries.
-
- The buffer will be freed by ShellFindNextFile() when the last directory
- entry is read. Otherwise, the caller must free the buffer, using FreePool,
- when finished with it.
-
- @param[in] DirHandle The file handle of the directory to search.
- @param[out] Buffer The pointer to the buffer for the file's information.
-
- @retval EFI_SUCCESS Found the first file.
- @retval EFI_NOT_FOUND Cannot find the directory.
- @retval EFI_NO_MEDIA The device has no media.
- @retval EFI_DEVICE_ERROR The device reported an error.
- @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
- @return Others Status of ShellGetFileInfo, ShellSetFilePosition,
- or ShellReadFile.
-
- @sa ShellReadFile
-**/
-EFI_STATUS
-EFIAPI
-ShellFindFirstFile (
- IN SHELL_FILE_HANDLE DirHandle,
- OUT EFI_FILE_INFO **Buffer
- );
-
-/** Retrieve next entries from a directory.
-
- To use this function, the caller must first call the ShellFindFirstFile()
- function to get the first directory entry. Subsequent directory entries are
- retrieved by using the ShellFindNextFile() function. This function can
- be called several times to get each entry from the directory. If the call of
- ShellFindNextFile() retrieved the last directory entry, the next call of
- this function will set *NoFile to TRUE and free the buffer.
-
- @param[in] DirHandle The file handle of the directory.
- @param[in, out] Buffer The pointer to buffer for file's information.
- @param[in, out] NoFile The pointer to boolean when last file is found.
-
- @retval EFI_SUCCESS Found the next file.
- @retval EFI_NO_MEDIA The device has no media.
- @retval EFI_DEVICE_ERROR The device reported an error.
- @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
-
- @sa ShellReadFile
-**/
-EFI_STATUS
-EFIAPI
-ShellFindNextFile (
- IN SHELL_FILE_HANDLE DirHandle,
- IN OUT EFI_FILE_INFO *Buffer,
- IN OUT BOOLEAN *NoFile
- );
-
-/**
- Retrieve the size of a file.
-
- This function extracts the file size info from the FileHandle's EFI_FILE_INFO
- data.
-
- @param[in] FileHandle The file handle from which size is retrieved.
- @param[out] Size The pointer to size.
-
- @retval EFI_SUCCESS The operation was completed successfully.
- @retval EFI_DEVICE_ERROR Cannot access the file.
-**/
-EFI_STATUS
-EFIAPI
-ShellGetFileSize (
- IN SHELL_FILE_HANDLE FileHandle,
- OUT UINT64 *Size
- );
-
-/**
- Retrieves the status of the break execution flag
-
- This function is useful to check whether the application is being asked to halt by the shell.
-
- @retval TRUE The execution break is enabled.
- @retval FALSE The execution break is not enabled.
-**/
-BOOLEAN
-EFIAPI
-ShellGetExecutionBreakFlag (
- VOID
- );
-
-/**
- Return the value of an environment variable.
-
- This function gets the value of the environment variable set by the
- ShellSetEnvironmentVariable function.
-
- @param[in] EnvKey The key name of the environment variable.
-
- @retval NULL The named environment variable does not exist.
- @return != NULL The pointer to the value of the environment variable.
-**/
-CONST CHAR16 *
-EFIAPI
-ShellGetEnvironmentVariable (
- IN CONST CHAR16 *EnvKey
- );
-
-/**
- Set the value of an environment variable.
-
- This function changes the current value of the specified environment variable. If the
- environment variable exists and the Value is an empty string, then the environment
- variable is deleted. If the environment variable exists and the Value is not an empty
- string, then the value of the environment variable is changed. If the environment
- variable does not exist and the Value is an empty string, there is no action. If the
- environment variable does not exist and the Value is a non-empty string, then the
- environment variable is created and assigned the specified value.
-
- This is not supported pre-UEFI Shell 2.0.
-
- @param[in] EnvKey The key name of the environment variable.
- @param[in] EnvVal The Value of the environment variable
- @param[in] Volatile Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE).
-
- @retval EFI_SUCCESS The operation completed successfully
- @retval EFI_UNSUPPORTED This operation is not allowed in pre-UEFI 2.0 Shell environments.
-**/
-EFI_STATUS
-EFIAPI
-ShellSetEnvironmentVariable (
- IN CONST CHAR16 *EnvKey,
- IN CONST CHAR16 *EnvVal,
- IN BOOLEAN Volatile
- );
-
-/**
- Cause the shell to parse and execute a command line.
-
- This function creates a nested instance of the shell and executes the specified
- command (CommandLine) with the specified environment (Environment). Upon return,
- the status code returned by the specified command is placed in StatusCode.
- If Environment is NULL, then the current environment is used and all changes made
- by the commands executed will be reflected in the current environment. If the
- Environment is non-NULL, then the changes made will be discarded.
- The CommandLine is executed from the current working directory on the current
- device.
-
- The EnvironmentVariables and Status parameters are ignored in a pre-UEFI Shell 2.0
- environment. The values pointed to by the parameters will be unchanged by the
- ShellExecute() function. The Output parameter has no effect in a
- UEFI Shell 2.0 environment.
-
- @param[in] ParentHandle The parent image starting the operation.
- @param[in] CommandLine The pointer to a NULL terminated command line.
- @param[in] Output True to display debug output. False to hide it.
- @param[in] EnvironmentVariables Optional pointer to array of environment variables
- in the form "x=y". If NULL, the current set is used.
- @param[out] Status The status of the run command line.
-
- @retval EFI_SUCCESS The operation completed successfully. Status
- contains the status code returned.
- @retval EFI_INVALID_PARAMETER A parameter contains an invalid value.
- @retval EFI_OUT_OF_RESOURCES Out of resources.
- @retval EFI_UNSUPPORTED The operation is not allowed.
-**/
-EFI_STATUS
-EFIAPI
-ShellExecute (
- IN EFI_HANDLE *ParentHandle,
- IN CHAR16 *CommandLine,
- IN BOOLEAN Output,
- IN CHAR16 **EnvironmentVariables,
- OUT EFI_STATUS *Status
- );
-
-/**
- Retreives the current directory path.
-
- If the DeviceName is NULL, it returns the current device's current directory
- name. If the DeviceName is not NULL, it returns the current directory name
- on specified drive.
-
- Note that the current directory string should exclude the tailing backslash character.
-
- @param[in] DeviceName The name of the file system to get directory on.
-
- @retval NULL The directory does not exist.
- @retval != NULL The directory.
-**/
-CONST CHAR16 *
-EFIAPI
-ShellGetCurrentDir (
- IN CHAR16 *CONST DeviceName OPTIONAL
- );
-
-/**
- Sets (enabled or disabled) the page break mode.
-
- When page break mode is enabled the screen will stop scrolling
- and wait for operator input before scrolling a subsequent screen.
-
- @param[in] CurrentState TRUE to enable and FALSE to disable.
-**/
-VOID
-EFIAPI
-ShellSetPageBreakMode (
- IN BOOLEAN CurrentState
- );
-
-/**
- Opens a group of files based on a path.
-
- This function uses the Arg to open all the matching files. Each matched
- file has a SHELL_FILE_ARG structure to record the file information. These
- structures are placed on the list ListHead. Users can get the SHELL_FILE_ARG
- structures from ListHead to access each file. This function supports wildcards
- and will process '?' and '*' as such. The list must be freed with a call to
- ShellCloseFileMetaArg().
-
- If you are NOT appending to an existing list *ListHead must be NULL. If
- *ListHead is NULL then it must be callee freed.
-
- @param[in] Arg The pointer to path string.
- @param[in] OpenMode Mode to open files with.
- @param[in, out] ListHead Head of linked list of results.
-
- @retval EFI_SUCCESS The operation was successful and the list head
- contains the list of opened files.
- @retval != EFI_SUCCESS The operation failed.
-
- @sa InternalShellConvertFileListType
-**/
-EFI_STATUS
-EFIAPI
-ShellOpenFileMetaArg (
- IN CHAR16 *Arg,
- IN UINT64 OpenMode,
- IN OUT EFI_SHELL_FILE_INFO **ListHead
- );
-
-/**
- Free the linked list returned from ShellOpenFileMetaArg.
-
- @param[in, out] ListHead The pointer to free.
-
- @retval EFI_SUCCESS The operation was successful.
- @retval EFI_INVALID_PARAMETER A parameter was invalid.
-**/
-EFI_STATUS
-EFIAPI
-ShellCloseFileMetaArg (
- IN OUT EFI_SHELL_FILE_INFO **ListHead
- );
-
-/**
- Find a file by searching the CWD and then the path.
-
- If FileName is NULL, then ASSERT.
-
- If the return value is not NULL then the memory must be caller freed.
-
- @param[in] FileName Filename string.
-
- @retval NULL The file was not found.
- @retval !NULL The path to the file.
-**/
-CHAR16 *
-EFIAPI
-ShellFindFilePath (
- IN CONST CHAR16 *FileName
- );
-
-/**
- Find a file by searching the CWD and then the path with a variable set of file
- extensions. If the file is not found it will append each extension in the list
- in the order provided and return the first one that is successful.
-
- If FileName is NULL, then ASSERT.
- If FileExtension is NULL, then the behavior is identical to ShellFindFilePath.
-
- If the return value is not NULL then the memory must be caller freed.
-
- @param[in] FileName The filename string.
- @param[in] FileExtension Semicolon delimited list of possible extensions.
-
- @retval NULL The file was not found.
- @retval !NULL The path to the file.
-**/
-CHAR16 *
-EFIAPI
-ShellFindFilePathEx (
- IN CONST CHAR16 *FileName,
- IN CONST CHAR16 *FileExtension
- );
-
-typedef enum {
- TypeFlag = 0, ///< A flag that is present or not present only (IE "-a").
- TypeValue, ///< A flag that has some data following it with a space (IE "-a 1").
- TypePosition, ///< Some data that did not follow a parameter (IE "filename.txt").
- TypeStart, ///< A flag that has variable value appended to the end (IE "-ad", "-afd", "-adf", etc...).
- TypeDoubleValue, ///< A flag that has 2 space seperated value data following it (IE "-a 1 2").
- TypeMaxValue, ///< A flag followed by all the command line data before the next flag.
- TypeTimeValue, ///< A flag that has a time value following it (IE "-a -5:00").
- TypeMax,
-} SHELL_PARAM_TYPE;
-
-typedef struct {
- CHAR16 *Name;
- SHELL_PARAM_TYPE Type;
-} SHELL_PARAM_ITEM;
-
-/// Helper structure for no parameters (besides -? and -b)
-extern SHELL_PARAM_ITEM EmptyParamList[];
-
-/// Helper structure for -sfo only (besides -? and -b)
-extern SHELL_PARAM_ITEM SfoParamList[];
-
-/**
- Checks the command line arguments passed against the list of valid ones.
- Optionally removes NULL values first.
-
- If no initialization is required, then return RETURN_SUCCESS.
-
- @param[in] CheckList The pointer to list of parameters to check.
- @param[out] CheckPackage The package of checked values.
- @param[out] ProblemParam Optional pointer to pointer to unicode string for
- the paramater that caused failure.
- @param[in] AutoPageBreak Will automatically set PageBreakEnabled.
- @param[in] AlwaysAllowNumbers Will never fail for number based flags.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_OUT_OF_RESOURCES A memory allocation failed.
- @retval EFI_INVALID_PARAMETER A parameter was invalid.
- @retval EFI_VOLUME_CORRUPTED The command line was corrupt.
- @retval EFI_DEVICE_ERROR The commands contained 2 opposing arguments. One
- of the command line arguments was returned in
- ProblemParam if provided.
- @retval EFI_NOT_FOUND A argument required a value that was missing.
- The invalid command line argument was returned in
- ProblemParam if provided.
-**/
-EFI_STATUS
-EFIAPI
-ShellCommandLineParseEx (
- IN CONST SHELL_PARAM_ITEM *CheckList,
- OUT LIST_ENTRY **CheckPackage,
- OUT CHAR16 **ProblemParam OPTIONAL,
- IN BOOLEAN AutoPageBreak,
- IN BOOLEAN AlwaysAllowNumbers
- );
-
-/// Make it easy to upgrade from older versions of the shell library.
-#define ShellCommandLineParse(CheckList, CheckPackage, ProblemParam, AutoPageBreak) ShellCommandLineParseEx(CheckList,CheckPackage,ProblemParam,AutoPageBreak,FALSE)
-
-/**
- Frees shell variable list that was returned from ShellCommandLineParse.
-
- This function will free all the memory that was used for the CheckPackage
- list of postprocessed shell arguments.
-
- If CheckPackage is NULL, then return.
-
- @param[in] CheckPackage The list to de-allocate.
- **/
-VOID
-EFIAPI
-ShellCommandLineFreeVarList (
- IN LIST_ENTRY *CheckPackage
- );
-
-/**
- Checks for presence of a flag parameter.
-
- Flag arguments are in the form of "-<Key>" or "/<Key>", but do not have a value following the key.
-
- If CheckPackage is NULL then return FALSE.
- If KeyString is NULL then ASSERT().
-
- @param[in] CheckPackage The package of parsed command line arguments.
- @param[in] KeyString The Key of the command line argument to check for.
-
- @retval TRUE The flag is on the command line.
- @retval FALSE The flag is not on the command line.
-**/
-BOOLEAN
-EFIAPI
-ShellCommandLineGetFlag (
- IN CONST LIST_ENTRY *CONST CheckPackage,
- IN CONST CHAR16 *CONST KeyString
- );
-
-/**
- Returns value from command line argument.
-
- Value parameters are in the form of "-<Key> value" or "/<Key> value".
-
- If CheckPackage is NULL, then return NULL.
-
- @param[in] CheckPackage The package of parsed command line arguments.
- @param[in] KeyString The Key of the command line argument to check for.
-
- @retval NULL The flag is not on the command line.
- @retval !=NULL The pointer to unicode string of the value.
-**/
-CONST CHAR16 *
-EFIAPI
-ShellCommandLineGetValue (
- IN CONST LIST_ENTRY *CheckPackage,
- IN CHAR16 *KeyString
- );
-
-/**
- Returns raw value from command line argument.
-
- Raw value parameters are in the form of "value" in a specific position in the list.
-
- If CheckPackage is NULL, then return NULL.
-
- @param[in] CheckPackage The package of parsed command line arguments.
- @param[in] Position The position of the value.
-
- @retval NULL The flag is not on the command line.
- @retval !=NULL The pointer to unicode string of the value.
-**/
-CONST CHAR16 *
-EFIAPI
-ShellCommandLineGetRawValue (
- IN CONST LIST_ENTRY *CONST CheckPackage,
- IN UINTN Position
- );
-
-/**
- Returns the number of command line value parameters that were parsed.
-
- This will not include flags.
-
- @param[in] CheckPackage The package of parsed command line arguments.
-
- @retval (UINTN)-1 No parsing has occurred.
- @retval other The number of value parameters found.
-**/
-UINTN
-EFIAPI
-ShellCommandLineGetCount (
- IN CONST LIST_ENTRY *CheckPackage
- );
-
-/**
- Determines if a parameter is duplicated.
-
- If Param is not NULL, then it will point to a callee-allocated string buffer
- with the parameter value, if a duplicate is found.
-
- If CheckPackage is NULL, then ASSERT.
-
- @param[in] CheckPackage The package of parsed command line arguments.
- @param[out] Param Upon finding one, a pointer to the duplicated parameter.
-
- @retval EFI_SUCCESS No parameters were duplicated.
- @retval EFI_DEVICE_ERROR A duplicate was found.
- **/
-EFI_STATUS
-EFIAPI
-ShellCommandLineCheckDuplicate (
- IN CONST LIST_ENTRY *CheckPackage,
- OUT CHAR16 **Param
- );
-
-/**
- This function causes the shell library to initialize itself. If the shell library
- is already initialized it will de-initialize all the current protocol pointers and
- re-populate them again.
-
- When the library is used with PcdShellLibAutoInitialize set to true this function
- will return EFI_SUCCESS and perform no actions.
-
- This function is intended for internal access for shell commands only.
-
- @retval EFI_SUCCESS The initialization was complete successfully.
-
-**/
-EFI_STATUS
-EFIAPI
-ShellInitialize (
- VOID
- );
-
-/**
- Print at a specific location on the screen.
-
- This function will move the cursor to a given screen location and print the specified string.
-
- If -1 is specified for either the Row or Col the current screen location for BOTH
- will be used.
-
- If either Row or Col is out of range for the current console, then ASSERT.
- If Format is NULL, then ASSERT.
-
- In addition to the standard %-based flags as supported by UefiLib Print() this supports
- the following additional flags:
- %N - Set output attribute to normal
- %H - Set output attribute to highlight
- %E - Set output attribute to error
- %B - Set output attribute to blue color
- %V - Set output attribute to green color
-
- Note: The background color is controlled by the shell command cls.
-
- @param[in] Col The column to print at.
- @param[in] Row The row to print at.
- @param[in] Format The format string.
- @param[in] ... The variable argument list.
-
- @return EFI_SUCCESS The printing was successful.
- @return EFI_DEVICE_ERROR The console device reported an error.
-**/
-EFI_STATUS
-EFIAPI
-ShellPrintEx (
- IN INT32 Col OPTIONAL,
- IN INT32 Row OPTIONAL,
- IN CONST CHAR16 *Format,
- ...
- );
-
-/**
- Print at a specific location on the screen.
-
- This function will move the cursor to a given screen location and print the specified string.
-
- If -1 is specified for either the Row or Col the current screen location for BOTH
- will be used.
-
- If either Row or Col is out of range for the current console, then ASSERT.
- If Format is NULL, then ASSERT.
-
- In addition to the standard %-based flags as supported by UefiLib Print() this supports
- the following additional flags:
- %N - Set output attribute to normal.
- %H - Set output attribute to highlight.
- %E - Set output attribute to error.
- %B - Set output attribute to blue color.
- %V - Set output attribute to green color.
-
- Note: The background color is controlled by the shell command cls.
-
- @param[in] Col The column to print at.
- @param[in] Row The row to print at.
- @param[in] Language The language of the string to retrieve. If this parameter
- is NULL, then the current platform language is used.
- @param[in] HiiFormatStringId The format string Id for getting from Hii.
- @param[in] HiiFormatHandle The format string Handle for getting from Hii.
- @param[in] ... The variable argument list.
-
- @return EFI_SUCCESS The printing was successful.
- @return EFI_DEVICE_ERROR The console device reported an error.
-**/
-EFI_STATUS
-EFIAPI
-ShellPrintHiiEx (
- IN INT32 Col OPTIONAL,
- IN INT32 Row OPTIONAL,
- IN CONST CHAR8 *Language OPTIONAL,
- IN CONST EFI_STRING_ID HiiFormatStringId,
- IN CONST EFI_HII_HANDLE HiiFormatHandle,
- ...
- );
-
-/**
- Function to determine if a given filename represents a directory.
-
- If DirName is NULL, then ASSERT.
-
- @param[in] DirName Path to directory to test.
-
- @retval EFI_SUCCESS The Path represents a directory.
- @retval EFI_NOT_FOUND The Path does not represent a directory.
- @retval other The path failed to open.
-**/
-EFI_STATUS
-EFIAPI
-ShellIsDirectory (
- IN CONST CHAR16 *DirName
- );
-
-/**
- Function to determine if a given filename represents a file.
-
- This will search the CWD only.
-
- If Name is NULL, then ASSERT.
-
- @param[in] Name Path to file to test.
-
- @retval EFI_SUCCESS The Path represents a file.
- @retval EFI_NOT_FOUND The Path does not represent a file.
- @retval other The path failed to open.
-**/
-EFI_STATUS
-EFIAPI
-ShellIsFile (
- IN CONST CHAR16 *Name
- );
-
-/**
- Function to determine if a given filename represents a file.
-
- This will search the CWD and then the Path.
-
- If Name is NULL, then ASSERT.
-
- @param[in] Name Path to file to test.
-
- @retval EFI_SUCCESS The Path represents a file.
- @retval EFI_NOT_FOUND The Path does not represent a file.
- @retval other The path failed to open.
-**/
-EFI_STATUS
-EFIAPI
-ShellIsFileInPath (
- IN CONST CHAR16 *Name
- );
-
-/**
- Function to determine whether a string is decimal or hex representation of a number
- and return the number converted from the string.
-
- Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid
- result. Use ShellConvertStringToUint64 instead.
-
- @param[in] String String representation of a number.
-
- @return The unsigned integer result of the conversion.
- @retval (UINTN)(-1) An error occurred.
-**/
-UINTN
-EFIAPI
-ShellStrToUintn (
- IN CONST CHAR16 *String
- );
-
-/**
- Function return the number converted from a hex representation of a number.
-
- Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid
- result. Use ShellConvertStringToUint64 instead.
-
- @param[in] String String representation of a number.
-
- @return The unsigned integer result of the conversion.
- @retval (UINTN)(-1) An error occurred.
-**/
-UINTN
-EFIAPI
-ShellHexStrToUintn (
- IN CONST CHAR16 *String
- );
-
-/**
- Safely append with automatic string resizing given length of Destination and
- desired length of copy from Source.
-
- Append the first D characters of Source to the end of Destination, where D is
- the lesser of Count and the StrLen() of Source. If appending those D characters
- will fit within Destination (whose Size is given as CurrentSize) and
- still leave room for a NULL terminator, then those characters are appended,
- starting at the original terminating NULL of Destination, and a new terminating
- NULL is appended.
-
- If appending D characters onto Destination will result in a overflow of the size
- given in CurrentSize the string will be grown such that the copy can be performed
- and CurrentSize will be updated to the new size.
-
- If Source is NULL, there is nothing to append, so return the current buffer in
- Destination.
-
- If Destination is NULL, then ASSERT().
- If Destination's current length (including NULL terminator) is already more than
- CurrentSize, then ASSERT().
-
- @param[in, out] Destination The String to append onto.
- @param[in, out] CurrentSize On call, the number of bytes in Destination. On
- return, possibly the new size (still in bytes). If NULL,
- then allocate whatever is needed.
- @param[in] Source The String to append from.
- @param[in] Count The maximum number of characters to append. If 0, then
- all are appended.
-
- @return The Destination after appending the Source.
-**/
-CHAR16 *
-EFIAPI
-StrnCatGrow (
- IN OUT CHAR16 **Destination,
- IN OUT UINTN *CurrentSize,
- IN CONST CHAR16 *Source,
- IN UINTN Count
- );
-
-/**
- This is a find and replace function. Upon successful return the NewString is a copy of
- SourceString with each instance of FindTarget replaced with ReplaceWith.
-
- If SourceString and NewString overlap the behavior is undefined.
-
- If the string would grow bigger than NewSize it will halt and return error.
-
- @param[in] SourceString The string with source buffer.
- @param[in, out] NewString The string with resultant buffer.
- @param[in] NewSize The size in bytes of NewString.
- @param[in] FindTarget The string to look for.
- @param[in] ReplaceWith The string to replace FindTarget with.
- @param[in] SkipPreCarrot If TRUE will skip a FindTarget that has a '^'
- immediately before it.
- @param[in] ParameterReplacing If TRUE will add "" around items with spaces.
-
- @retval EFI_INVALID_PARAMETER SourceString was NULL.
- @retval EFI_INVALID_PARAMETER NewString was NULL.
- @retval EFI_INVALID_PARAMETER FindTarget was NULL.
- @retval EFI_INVALID_PARAMETER ReplaceWith was NULL.
- @retval EFI_INVALID_PARAMETER FindTarget had length < 1.
- @retval EFI_INVALID_PARAMETER SourceString had length < 1.
- @retval EFI_BUFFER_TOO_SMALL NewSize was less than the minimum size to hold
- the new string (truncation occurred).
- @retval EFI_SUCCESS The string was successfully copied with replacement.
-**/
-EFI_STATUS
-EFIAPI
-ShellCopySearchAndReplace (
- IN CHAR16 CONST *SourceString,
- IN OUT CHAR16 *NewString,
- IN UINTN NewSize,
- IN CONST CHAR16 *FindTarget,
- IN CONST CHAR16 *ReplaceWith,
- IN CONST BOOLEAN SkipPreCarrot,
- IN CONST BOOLEAN ParameterReplacing
- );
-
-/**
- Check if a Unicode character is a hexadecimal character.
-
- This internal function checks if a Unicode character is a
- numeric character. The valid hexadecimal characters are
- L'0' to L'9', L'a' to L'f', or L'A' to L'F'.
-
-
- @param Char The character to check against.
-
- @retval TRUE The Char is a hexadecmial character.
- @retval FALSE The Char is not a hexadecmial character.
-
-**/
-BOOLEAN
-EFIAPI
-ShellIsHexaDecimalDigitCharacter (
- IN CHAR16 Char
- );
-
-/**
- Check if a Unicode character is a decimal character.
-
- This internal function checks if a Unicode character is a
- decimal character. The valid characters are
- L'0' to L'9'.
-
-
- @param Char The character to check against.
-
- @retval TRUE The Char is a hexadecmial character.
- @retval FALSE The Char is not a hexadecmial character.
-
-**/
-BOOLEAN
-EFIAPI
-ShellIsDecimalDigitCharacter (
- IN CHAR16 Char
- );
-
-///
-/// What type of answer is requested.
-///
-typedef enum {
- ShellPromptResponseTypeYesNo,
- ShellPromptResponseTypeYesNoCancel,
- ShellPromptResponseTypeFreeform,
- ShellPromptResponseTypeQuitContinue,
- ShellPromptResponseTypeYesNoAllCancel,
- ShellPromptResponseTypeEnterContinue,
- ShellPromptResponseTypeAnyKeyContinue,
- ShellPromptResponseTypeMax
-} SHELL_PROMPT_REQUEST_TYPE;
-
-///
-/// What answer was given.
-///
-typedef enum {
- ShellPromptResponseYes,
- ShellPromptResponseNo,
- ShellPromptResponseCancel,
- ShellPromptResponseQuit,
- ShellPromptResponseContinue,
- ShellPromptResponseAll,
- ShellPromptResponseMax
-} SHELL_PROMPT_RESPONSE;
-
-/**
- Prompt the user and return the resultant answer to the requestor.
-
- This function will display the requested question on the shell prompt and then
- wait for an appropriate answer to be input from the console.
-
- If the SHELL_PROMPT_REQUEST_TYPE is SHELL_PROMPT_REQUEST_TYPE_YESNO, ShellPromptResponseTypeQuitContinue
- or SHELL_PROMPT_REQUEST_TYPE_YESNOCANCEL then *Response is of type SHELL_PROMPT_RESPONSE.
-
- If the SHELL_PROMPT_REQUEST_TYPE is ShellPromptResponseTypeFreeform then *Response is of type
- CHAR16*.
-
- In either case *Response must be callee freed if Response was not NULL;
-
- @param Type What type of question is asked. This is used to filter the input
- to prevent invalid answers to question.
- @param Prompt The pointer to a string prompt used to request input.
- @param Response The pointer to Response, which will be populated upon return.
-
- @retval EFI_SUCCESS The operation was successful.
- @retval EFI_UNSUPPORTED The operation is not supported as requested.
- @retval EFI_INVALID_PARAMETER A parameter was invalid.
- @return other The operation failed.
-**/
-EFI_STATUS
-EFIAPI
-ShellPromptForResponse (
- IN SHELL_PROMPT_REQUEST_TYPE Type,
- IN CHAR16 *Prompt OPTIONAL,
- IN OUT VOID **Response OPTIONAL
- );
-
-/**
- Prompt the user and return the resultant answer to the requestor.
-
- This function is the same as ShellPromptForResponse, except that the prompt is
- automatically pulled from HII.
-
- @param[in] Type What type of question is asked. This is used to filter the input
- to prevent invalid answers to question.
- @param[in] HiiFormatStringId The format string Id for getting from Hii.
- @param[in] HiiFormatHandle The format string Handle for getting from Hii.
- @param[in, out] Response The pointer to Response, which will be populated upon return.
-
- @retval EFI_SUCCESS The operation was successful.
- @return other The operation failed.
-
- @sa ShellPromptForResponse
-**/
-EFI_STATUS
-EFIAPI
-ShellPromptForResponseHii (
- IN SHELL_PROMPT_REQUEST_TYPE Type,
- IN CONST EFI_STRING_ID HiiFormatStringId,
- IN CONST EFI_HII_HANDLE HiiFormatHandle,
- IN OUT VOID **Response
- );
-
-/**
- Function to determin if an entire string is a valid number.
-
- If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.
-
- @param[in] String The string to evaluate.
- @param[in] ForceHex TRUE - always assume hex.
- @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to keep going.
-
- @retval TRUE It is all numeric (dec/hex) characters.
- @retval FALSE There is a non-numeric character.
-**/
-BOOLEAN
-EFIAPI
-ShellIsHexOrDecimalNumber (
- IN CONST CHAR16 *String,
- IN CONST BOOLEAN ForceHex,
- IN CONST BOOLEAN StopAtSpace
- );
-
-/**
- Function to verify and convert a string to its numerical 64 bit representation.
-
- If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE.
-
- @param[in] String The string to evaluate.
- @param[out] Value Upon a successful return the value of the conversion.
- @param[in] ForceHex TRUE - always assume hex.
- @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to
- process the entire String.
-
- @retval EFI_SUCCESS The conversion was successful.
- @retval EFI_INVALID_PARAMETER String contained an invalid character.
- @retval EFI_NOT_FOUND String was a number, but Value was NULL.
-**/
-EFI_STATUS
-EFIAPI
-ShellConvertStringToUint64 (
- IN CONST CHAR16 *String,
- OUT UINT64 *Value,
- IN CONST BOOLEAN ForceHex,
- IN CONST BOOLEAN StopAtSpace
- );
-
-/**
- Function to determine if a given filename exists.
-
- @param[in] Name Path to test.
-
- @retval EFI_SUCCESS The Path represents a file.
- @retval EFI_NOT_FOUND The Path does not represent a file.
- @retval other The path failed to open.
-**/
-EFI_STATUS
-EFIAPI
-ShellFileExists (
- IN CONST CHAR16 *Name
- );
-
-/**
- Function to read a single line from a SHELL_FILE_HANDLE. The \n is not included in the returned
- buffer. The returned buffer must be callee freed.
-
- If the position upon start is 0, then the Ascii Boolean will be set. This should be
- maintained and not changed for all operations with the same file.
-
- @param[in] Handle SHELL_FILE_HANDLE to read from.
- @param[in, out] Ascii Boolean value for indicating whether the file is
- Ascii (TRUE) or UCS2 (FALSE).
-
- @return The line of text from the file.
-
- @sa ShellFileHandleReadLine
-**/
-CHAR16 *
-EFIAPI
-ShellFileHandleReturnLine (
- IN SHELL_FILE_HANDLE Handle,
- IN OUT BOOLEAN *Ascii
- );
-
-/**
- Function to read a single line (up to but not including the \n) from a SHELL_FILE_HANDLE.
-
- If the position upon start is 0, then the Ascii Boolean will be set. This should be
- maintained and not changed for all operations with the same file.
-
- @param[in] Handle SHELL_FILE_HANDLE to read from.
- @param[in, out] Buffer The pointer to buffer to read into.
- @param[in, out] Size The pointer to number of bytes in Buffer.
- @param[in] Truncate If the buffer is large enough, this has no effect.
- If the buffer is is too small and Truncate is TRUE,
- the line will be truncated.
- If the buffer is is too small and Truncate is FALSE,
- then no read will occur.
-
- @param[in, out] Ascii Boolean value for indicating whether the file is
- Ascii (TRUE) or UCS2 (FALSE).
-
- @retval EFI_SUCCESS The operation was successful. The line is stored in
- Buffer.
- @retval EFI_END_OF_FILE There are no more lines in the file.
- @retval EFI_INVALID_PARAMETER Handle was NULL.
- @retval EFI_INVALID_PARAMETER Size was NULL.
- @retval EFI_BUFFER_TOO_SMALL Size was not large enough to store the line.
- Size was updated to the minimum space required.
-**/
-EFI_STATUS
-EFIAPI
-ShellFileHandleReadLine (
- IN SHELL_FILE_HANDLE Handle,
- IN OUT CHAR16 *Buffer,
- IN OUT UINTN *Size,
- IN BOOLEAN Truncate,
- IN OUT BOOLEAN *Ascii
- );
-
-/**
- Function to delete a file by name
-
- @param[in] FileName Pointer to file name to delete.
-
- @retval EFI_SUCCESS the file was deleted successfully
- @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not
- deleted
- @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
- @retval EFI_NOT_FOUND The specified file could not be found on the
- device or the file system could not be found
- on the device.
- @retval EFI_NO_MEDIA The device has no medium.
- @retval EFI_MEDIA_CHANGED The device has a different medium in it or the
- medium is no longer supported.
- @retval EFI_DEVICE_ERROR The device reported an error.
- @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.
- @retval EFI_WRITE_PROTECTED The file or medium is write protected.
- @retval EFI_ACCESS_DENIED The file was opened read only.
- @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the
- file.
- @retval other The file failed to open
-**/
-EFI_STATUS
-EFIAPI
-ShellDeleteFileByName (
- IN CONST CHAR16 *FileName
- );
-
-/**
- Function to print help file / man page content in the spec from the UEFI Shell protocol GetHelpText function.
-
- @param[in] CommandToGetHelpOn Pointer to a string containing the command name of help file to be printed.
- @param[in] SectionToGetHelpOn Pointer to the section specifier(s).
- @param[in] PrintCommandText If TRUE, prints the command followed by the help content, otherwise prints
- the help content only.
- @retval EFI_DEVICE_ERROR The help data format was incorrect.
- @retval EFI_NOT_FOUND The help data could not be found.
- @retval EFI_SUCCESS The operation was successful.
-**/
-EFI_STATUS
-EFIAPI
-ShellPrintHelp (
- IN CONST CHAR16 *CommandToGetHelpOn,
- IN CONST CHAR16 *SectionToGetHelpOn,
- IN BOOLEAN PrintCommandText
- );
-
-#endif // __SHELL_LIB__
+/** @file + Provides interface to shell functionality for shell commands and applications. + + Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> + Copyright 2018 Dell Technologies.<BR> + SPDX-License-Identifier: BSD-2-Clause-Patent + +**/ + +#ifndef __SHELL_LIB__ +#define __SHELL_LIB__ + +#include <Uefi.h> +#include <Guid/FileInfo.h> +#include <Protocol/SimpleFileSystem.h> +#include <Protocol/LoadedImage.h> +#include <Protocol/EfiShellInterface.h> +#include <Protocol/EfiShellEnvironment2.h> +#include <Protocol/Shell.h> +#include <Protocol/ShellParameters.h> + +#define SHELL_FREE_NON_NULL(Pointer) \ + do { \ + if ((Pointer) != NULL) { \ + FreePool((Pointer)); \ + (Pointer) = NULL; \ + } \ + } while(FALSE) + +extern EFI_SHELL_PARAMETERS_PROTOCOL *gEfiShellParametersProtocol; +extern EFI_SHELL_PROTOCOL *gEfiShellProtocol; + +/** + Return a clean, fully-qualified version of an input path. If the return value + is non-NULL the caller must free the memory when it is no longer needed. + + If asserts are disabled, and if the input parameter is NULL, NULL is returned. + + If there is not enough memory available to create the fully-qualified path or + a copy of the input path, NULL is returned. + + If there is no working directory, a clean copy of Path is returned. + + Otherwise, the current file system or working directory (as appropriate) is + prepended to Path and the resulting path is cleaned and returned. + + NOTE: If the input path is an empty string, then the current working directory + (if it exists) is returned. In other words, an empty input path is treated + exactly the same as ".". + + @param[in] Path A pointer to some file or directory path. + + @retval NULL The input path is NULL or out of memory. + + @retval non-NULL A pointer to a clean, fully-qualified version of Path. + If there is no working directory, then a pointer to a + clean, but not necessarily fully-qualified version of + Path. The caller must free this memory when it is no + longer needed. +**/ +CHAR16 * +EFIAPI +FullyQualifyPath ( + IN CONST CHAR16 *Path + ); + +/** + This function will retrieve the information about the file for the handle + specified and store it in allocated pool memory. + + This function allocates a buffer to store the file's information. It is the + caller's responsibility to free the buffer. + + @param[in] FileHandle The file handle of the file for which information is + being requested. + + @retval NULL Information could not be retrieved. + + @return The information about the file. +**/ +EFI_FILE_INFO * +EFIAPI +ShellGetFileInfo ( + IN SHELL_FILE_HANDLE FileHandle + ); + +/** + This function sets the information about the file for the opened handle + specified. + + @param[in] FileHandle The file handle of the file for which information + is being set. + + @param[in] FileInfo The information to set. + + @retval EFI_SUCCESS The information was set. + @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid. + @retval EFI_UNSUPPORTED The FileHandle does not support FileInfo. + @retval EFI_NO_MEDIA The device has no medium. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened read only. + @retval EFI_VOLUME_FULL The volume is full. +**/ +EFI_STATUS +EFIAPI +ShellSetFileInfo ( + IN SHELL_FILE_HANDLE FileHandle, + IN EFI_FILE_INFO *FileInfo + ); + +/** + This function will open a file or directory referenced by DevicePath. + + This function opens a file with the open mode according to the file path. The + Attributes is valid only for EFI_FILE_MODE_CREATE. + + @param[in, out] FilePath On input, the device path to the file. On output, + the remaining device path. + @param[out] FileHandle Pointer to the file handle. + @param[in] OpenMode The mode to open the file with. + @param[in] Attributes The file's file attributes. + + @retval EFI_SUCCESS The information was set. + @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. + @retval EFI_UNSUPPORTED Could not open the file path. + @retval EFI_NOT_FOUND The specified file could not be found on the + device or the file system could not be found on + the device. + @retval EFI_NO_MEDIA The device has no medium. + @retval EFI_MEDIA_CHANGED The device has a different medium in it or the + medium is no longer supported. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened read only. + @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the + file. + @retval EFI_VOLUME_FULL The volume is full. +**/ +EFI_STATUS +EFIAPI +ShellOpenFileByDevicePath ( + IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath, + OUT SHELL_FILE_HANDLE *FileHandle, + IN UINT64 OpenMode, + IN UINT64 Attributes + ); + +/** + This function will open a file or directory referenced by filename. + + If return is EFI_SUCCESS, the Filehandle is the opened file's handle; + otherwise, the Filehandle is NULL. Attributes is valid only for + EFI_FILE_MODE_CREATE. + + @param[in] FileName The pointer to file name. + @param[out] FileHandle The pointer to the file handle. + @param[in] OpenMode The mode to open the file with. + @param[in] Attributes The file's file attributes. + + @retval EFI_SUCCESS The information was set. + @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. + @retval EFI_UNSUPPORTED Could not open the file path. + @retval EFI_NOT_FOUND The specified file could not be found on the + device or the file system could not be found + on the device. + @retval EFI_NO_MEDIA The device has no medium. + @retval EFI_MEDIA_CHANGED The device has a different medium in it or the + medium is no longer supported. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened read only. + @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the + file. + @retval EFI_VOLUME_FULL The volume is full. +**/ +EFI_STATUS +EFIAPI +ShellOpenFileByName ( + IN CONST CHAR16 *FileName, + OUT SHELL_FILE_HANDLE *FileHandle, + IN UINT64 OpenMode, + IN UINT64 Attributes + ); + +/** + This function creates a directory. + + If return is EFI_SUCCESS, the Filehandle is the opened directory's handle; + otherwise, the Filehandle is NULL. If the directory already existed, this + function opens the existing directory. + + @param[in] DirectoryName The pointer to Directory name. + @param[out] FileHandle The pointer to the file handle. + + @retval EFI_SUCCESS The information was set. + @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. + @retval EFI_UNSUPPORTED Could not open the file path. + @retval EFI_NOT_FOUND The specified file could not be found on the + device, or the file system could not be found + on the device. + @retval EFI_NO_MEDIA The device has no medium. + @retval EFI_MEDIA_CHANGED The device has a different medium in it or the + medium is no longer supported. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened read only. + @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the + file. + @retval EFI_VOLUME_FULL The volume is full. +**/ +EFI_STATUS +EFIAPI +ShellCreateDirectory ( + IN CONST CHAR16 *DirectoryName, + OUT SHELL_FILE_HANDLE *FileHandle + ); + +/** + This function reads information from an opened file. + + If FileHandle is not a directory, the function reads the requested number of + bytes from the file at the file's current position and returns them in Buffer. + If the read goes beyond the end of the file, the read length is truncated to the + end of the file. The file's current position is increased by the number of bytes + returned. If FileHandle is a directory, the function reads the directory entry + at the file's current position and returns the entry in Buffer. If the Buffer + is not large enough to hold the current directory entry, then + EFI_BUFFER_TOO_SMALL is returned and the current file position is not updated. + BufferSize is set to be the size of the buffer needed to read the entry. On + success, the current position is updated to the next directory entry. If there + are no more directory entries, the read returns a zero-length buffer. + EFI_FILE_INFO is the structure returned as the directory entry. + + @param[in] FileHandle The opened file handle. + @param[in, out] ReadSize On input the size of buffer in bytes. On return + the number of bytes written. + @param[out] Buffer The buffer to put read data into. + + @retval EFI_SUCCESS Data was read. + @retval EFI_NO_MEDIA The device has no media. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required + size. + +**/ +EFI_STATUS +EFIAPI +ShellReadFile ( + IN SHELL_FILE_HANDLE FileHandle, + IN OUT UINTN *ReadSize, + OUT VOID *Buffer + ); + +/** + Write data to a file. + + This function writes the specified number of bytes to the file at the current + file position. The current file position is advanced the actual number of bytes + written, which is returned in BufferSize. Partial writes only occur when there + has been a data error during the write attempt (such as "volume space full"). + The file is automatically grown to hold the data if required. Direct writes to + opened directories are not supported. + + @param[in] FileHandle The opened file for writing. + + @param[in, out] BufferSize On input the number of bytes in Buffer. On output + the number of bytes written. + + @param[in] Buffer The buffer containing data to write is stored. + + @retval EFI_SUCCESS Data was written. + @retval EFI_UNSUPPORTED Writes to an open directory are not supported. + @retval EFI_NO_MEDIA The device has no media. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The device is write-protected. + @retval EFI_ACCESS_DENIED The file was open for read only. + @retval EFI_VOLUME_FULL The volume is full. +**/ +EFI_STATUS +EFIAPI +ShellWriteFile ( + IN SHELL_FILE_HANDLE FileHandle, + IN OUT UINTN *BufferSize, + IN VOID *Buffer + ); + +/** + Close an open file handle. + + This function closes a specified file handle. All "dirty" cached file data is + flushed to the device, and the file is closed. In all cases the handle is + closed. + + @param[in] FileHandle The file handle to close. + + @retval EFI_SUCCESS The file handle was closed successfully. + @retval INVALID_PARAMETER One of the parameters has an invalid value. +**/ +EFI_STATUS +EFIAPI +ShellCloseFile ( + IN SHELL_FILE_HANDLE *FileHandle + ); + +/** + Delete a file and close the handle + + This function closes and deletes a file. In all cases the file handle is closed. + If the file cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is + returned, but the handle is still closed. + + @param[in] FileHandle The file handle to delete. + + @retval EFI_SUCCESS The file was closed successfully. + @retval EFI_WARN_DELETE_FAILURE The handle was closed, but the file was not + deleted. + @retval INVALID_PARAMETER One of the parameters has an invalid value. +**/ +EFI_STATUS +EFIAPI +ShellDeleteFile ( + IN SHELL_FILE_HANDLE *FileHandle + ); + +/** + Set the current position in a file. + + This function sets the current file position for the handle to the position + supplied. With the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only + absolute positioning is supported, and moving past the end of the file is + allowed (a subsequent write would grow the file). Moving to position + 0xFFFFFFFFFFFFFFFF causes the current position to be set to the end of the file. + If FileHandle is a directory, the only position that may be set is zero. This + has the effect of starting the read process of the directory entries over. + + @param[in] FileHandle The file handle on which the position is being set. + + @param[in] Position The byte position from the beginning of the file. + + @retval EFI_SUCCESS Operation completed successfully. + @retval EFI_UNSUPPORTED The seek request for non-zero is not valid on + directories. + @retval INVALID_PARAMETER One of the parameters has an invalid value. +**/ +EFI_STATUS +EFIAPI +ShellSetFilePosition ( + IN SHELL_FILE_HANDLE FileHandle, + IN UINT64 Position + ); + +/** + Gets a file's current position + + This function retrieves the current file position for the file handle. For + directories, the current file position has no meaning outside of the file + system driver and as such the operation is not supported. An error is returned + if FileHandle is a directory. + + @param[in] FileHandle The open file handle on which to get the position. + @param[out] Position The byte position from the beginning of the file. + + @retval EFI_SUCCESS The operation completed successfully. + @retval INVALID_PARAMETER One of the parameters has an invalid value. + @retval EFI_UNSUPPORTED The request is not valid on directories. +**/ +EFI_STATUS +EFIAPI +ShellGetFilePosition ( + IN SHELL_FILE_HANDLE FileHandle, + OUT UINT64 *Position + ); + +/** + Flushes data on a file + + This function flushes all modified data associated with a file to a device. + + @param[in] FileHandle The file handle on which to flush data. + + @retval EFI_SUCCESS The data was flushed. + @retval EFI_NO_MEDIA The device has no media. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened for read only. +**/ +EFI_STATUS +EFIAPI +ShellFlushFile ( + IN SHELL_FILE_HANDLE FileHandle + ); + +/** Retrieve first entry from a directory. + + This function takes an open directory handle and gets information from the + first entry in the directory. A buffer is allocated to contain + the information and a pointer to the buffer is returned in *Buffer. The + caller can use ShellFindNextFile() to get subsequent directory entries. + + The buffer will be freed by ShellFindNextFile() when the last directory + entry is read. Otherwise, the caller must free the buffer, using FreePool, + when finished with it. + + @param[in] DirHandle The file handle of the directory to search. + @param[out] Buffer The pointer to the buffer for the file's information. + + @retval EFI_SUCCESS Found the first file. + @retval EFI_NOT_FOUND Cannot find the directory. + @retval EFI_NO_MEDIA The device has no media. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @return Others Status of ShellGetFileInfo, ShellSetFilePosition, + or ShellReadFile. + + @sa ShellReadFile +**/ +EFI_STATUS +EFIAPI +ShellFindFirstFile ( + IN SHELL_FILE_HANDLE DirHandle, + OUT EFI_FILE_INFO **Buffer + ); + +/** Retrieve next entries from a directory. + + To use this function, the caller must first call the ShellFindFirstFile() + function to get the first directory entry. Subsequent directory entries are + retrieved by using the ShellFindNextFile() function. This function can + be called several times to get each entry from the directory. If the call of + ShellFindNextFile() retrieved the last directory entry, the next call of + this function will set *NoFile to TRUE and free the buffer. + + @param[in] DirHandle The file handle of the directory. + @param[in, out] Buffer The pointer to buffer for file's information. + @param[in, out] NoFile The pointer to boolean when last file is found. + + @retval EFI_SUCCESS Found the next file. + @retval EFI_NO_MEDIA The device has no media. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + + @sa ShellReadFile +**/ +EFI_STATUS +EFIAPI +ShellFindNextFile ( + IN SHELL_FILE_HANDLE DirHandle, + IN OUT EFI_FILE_INFO *Buffer, + IN OUT BOOLEAN *NoFile + ); + +/** + Retrieve the size of a file. + + This function extracts the file size info from the FileHandle's EFI_FILE_INFO + data. + + @param[in] FileHandle The file handle from which size is retrieved. + @param[out] Size The pointer to size. + + @retval EFI_SUCCESS The operation was completed successfully. + @retval EFI_DEVICE_ERROR Cannot access the file. +**/ +EFI_STATUS +EFIAPI +ShellGetFileSize ( + IN SHELL_FILE_HANDLE FileHandle, + OUT UINT64 *Size + ); + +/** + Retrieves the status of the break execution flag + + This function is useful to check whether the application is being asked to halt by the shell. + + @retval TRUE The execution break is enabled. + @retval FALSE The execution break is not enabled. +**/ +BOOLEAN +EFIAPI +ShellGetExecutionBreakFlag ( + VOID + ); + +/** + Return the value of an environment variable. + + This function gets the value of the environment variable set by the + ShellSetEnvironmentVariable function. + + @param[in] EnvKey The key name of the environment variable. + + @retval NULL The named environment variable does not exist. + @return != NULL The pointer to the value of the environment variable. +**/ +CONST CHAR16 * +EFIAPI +ShellGetEnvironmentVariable ( + IN CONST CHAR16 *EnvKey + ); + +/** + Set the value of an environment variable. + + This function changes the current value of the specified environment variable. If the + environment variable exists and the Value is an empty string, then the environment + variable is deleted. If the environment variable exists and the Value is not an empty + string, then the value of the environment variable is changed. If the environment + variable does not exist and the Value is an empty string, there is no action. If the + environment variable does not exist and the Value is a non-empty string, then the + environment variable is created and assigned the specified value. + + This is not supported pre-UEFI Shell 2.0. + + @param[in] EnvKey The key name of the environment variable. + @param[in] EnvVal The Value of the environment variable + @param[in] Volatile Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE). + + @retval EFI_SUCCESS The operation completed successfully + @retval EFI_UNSUPPORTED This operation is not allowed in pre-UEFI 2.0 Shell environments. +**/ +EFI_STATUS +EFIAPI +ShellSetEnvironmentVariable ( + IN CONST CHAR16 *EnvKey, + IN CONST CHAR16 *EnvVal, + IN BOOLEAN Volatile + ); + +/** + Cause the shell to parse and execute a command line. + + This function creates a nested instance of the shell and executes the specified + command (CommandLine) with the specified environment (Environment). Upon return, + the status code returned by the specified command is placed in StatusCode. + If Environment is NULL, then the current environment is used and all changes made + by the commands executed will be reflected in the current environment. If the + Environment is non-NULL, then the changes made will be discarded. + The CommandLine is executed from the current working directory on the current + device. + + The EnvironmentVariables and Status parameters are ignored in a pre-UEFI Shell 2.0 + environment. The values pointed to by the parameters will be unchanged by the + ShellExecute() function. The Output parameter has no effect in a + UEFI Shell 2.0 environment. + + @param[in] ParentHandle The parent image starting the operation. + @param[in] CommandLine The pointer to a NULL terminated command line. + @param[in] Output True to display debug output. False to hide it. + @param[in] EnvironmentVariables Optional pointer to array of environment variables + in the form "x=y". If NULL, the current set is used. + @param[out] Status The status of the run command line. + + @retval EFI_SUCCESS The operation completed successfully. Status + contains the status code returned. + @retval EFI_INVALID_PARAMETER A parameter contains an invalid value. + @retval EFI_OUT_OF_RESOURCES Out of resources. + @retval EFI_UNSUPPORTED The operation is not allowed. +**/ +EFI_STATUS +EFIAPI +ShellExecute ( + IN EFI_HANDLE *ParentHandle, + IN CHAR16 *CommandLine, + IN BOOLEAN Output, + IN CHAR16 **EnvironmentVariables, + OUT EFI_STATUS *Status + ); + +/** + Retreives the current directory path. + + If the DeviceName is NULL, it returns the current device's current directory + name. If the DeviceName is not NULL, it returns the current directory name + on specified drive. + + Note that the current directory string should exclude the tailing backslash character. + + @param[in] DeviceName The name of the file system to get directory on. + + @retval NULL The directory does not exist. + @retval != NULL The directory. +**/ +CONST CHAR16 * +EFIAPI +ShellGetCurrentDir ( + IN CHAR16 *CONST DeviceName OPTIONAL + ); + +/** + Sets (enabled or disabled) the page break mode. + + When page break mode is enabled the screen will stop scrolling + and wait for operator input before scrolling a subsequent screen. + + @param[in] CurrentState TRUE to enable and FALSE to disable. +**/ +VOID +EFIAPI +ShellSetPageBreakMode ( + IN BOOLEAN CurrentState + ); + +/** + Opens a group of files based on a path. + + This function uses the Arg to open all the matching files. Each matched + file has a SHELL_FILE_ARG structure to record the file information. These + structures are placed on the list ListHead. Users can get the SHELL_FILE_ARG + structures from ListHead to access each file. This function supports wildcards + and will process '?' and '*' as such. The list must be freed with a call to + ShellCloseFileMetaArg(). + + If you are NOT appending to an existing list *ListHead must be NULL. If + *ListHead is NULL then it must be callee freed. + + @param[in] Arg The pointer to path string. + @param[in] OpenMode Mode to open files with. + @param[in, out] ListHead Head of linked list of results. + + @retval EFI_SUCCESS The operation was successful and the list head + contains the list of opened files. + @retval != EFI_SUCCESS The operation failed. + + @sa InternalShellConvertFileListType +**/ +EFI_STATUS +EFIAPI +ShellOpenFileMetaArg ( + IN CHAR16 *Arg, + IN UINT64 OpenMode, + IN OUT EFI_SHELL_FILE_INFO **ListHead + ); + +/** + Free the linked list returned from ShellOpenFileMetaArg. + + @param[in, out] ListHead The pointer to free. + + @retval EFI_SUCCESS The operation was successful. + @retval EFI_INVALID_PARAMETER A parameter was invalid. +**/ +EFI_STATUS +EFIAPI +ShellCloseFileMetaArg ( + IN OUT EFI_SHELL_FILE_INFO **ListHead + ); + +/** + Find a file by searching the CWD and then the path. + + If FileName is NULL, then ASSERT. + + If the return value is not NULL then the memory must be caller freed. + + @param[in] FileName Filename string. + + @retval NULL The file was not found. + @retval !NULL The path to the file. +**/ +CHAR16 * +EFIAPI +ShellFindFilePath ( + IN CONST CHAR16 *FileName + ); + +/** + Find a file by searching the CWD and then the path with a variable set of file + extensions. If the file is not found it will append each extension in the list + in the order provided and return the first one that is successful. + + If FileName is NULL, then ASSERT. + If FileExtension is NULL, then the behavior is identical to ShellFindFilePath. + + If the return value is not NULL then the memory must be caller freed. + + @param[in] FileName The filename string. + @param[in] FileExtension Semicolon delimited list of possible extensions. + + @retval NULL The file was not found. + @retval !NULL The path to the file. +**/ +CHAR16 * +EFIAPI +ShellFindFilePathEx ( + IN CONST CHAR16 *FileName, + IN CONST CHAR16 *FileExtension + ); + +typedef enum { + TypeFlag = 0, ///< A flag that is present or not present only (IE "-a"). + TypeValue, ///< A flag that has some data following it with a space (IE "-a 1"). + TypePosition, ///< Some data that did not follow a parameter (IE "filename.txt"). + TypeStart, ///< A flag that has variable value appended to the end (IE "-ad", "-afd", "-adf", etc...). + TypeDoubleValue, ///< A flag that has 2 space seperated value data following it (IE "-a 1 2"). + TypeMaxValue, ///< A flag followed by all the command line data before the next flag. + TypeTimeValue, ///< A flag that has a time value following it (IE "-a -5:00"). + TypeMax, +} SHELL_PARAM_TYPE; + +typedef struct { + CHAR16 *Name; + SHELL_PARAM_TYPE Type; +} SHELL_PARAM_ITEM; + +/// Helper structure for no parameters (besides -? and -b) +extern SHELL_PARAM_ITEM EmptyParamList[]; + +/// Helper structure for -sfo only (besides -? and -b) +extern SHELL_PARAM_ITEM SfoParamList[]; + +/** + Checks the command line arguments passed against the list of valid ones. + Optionally removes NULL values first. + + If no initialization is required, then return RETURN_SUCCESS. + + @param[in] CheckList The pointer to list of parameters to check. + @param[out] CheckPackage The package of checked values. + @param[out] ProblemParam Optional pointer to pointer to unicode string for + the paramater that caused failure. + @param[in] AutoPageBreak Will automatically set PageBreakEnabled. + @param[in] AlwaysAllowNumbers Will never fail for number based flags. + + @retval EFI_SUCCESS The operation completed successfully. + @retval EFI_OUT_OF_RESOURCES A memory allocation failed. + @retval EFI_INVALID_PARAMETER A parameter was invalid. + @retval EFI_VOLUME_CORRUPTED The command line was corrupt. + @retval EFI_DEVICE_ERROR The commands contained 2 opposing arguments. One + of the command line arguments was returned in + ProblemParam if provided. + @retval EFI_NOT_FOUND A argument required a value that was missing. + The invalid command line argument was returned in + ProblemParam if provided. +**/ +EFI_STATUS +EFIAPI +ShellCommandLineParseEx ( + IN CONST SHELL_PARAM_ITEM *CheckList, + OUT LIST_ENTRY **CheckPackage, + OUT CHAR16 **ProblemParam OPTIONAL, + IN BOOLEAN AutoPageBreak, + IN BOOLEAN AlwaysAllowNumbers + ); + +/// Make it easy to upgrade from older versions of the shell library. +#define ShellCommandLineParse(CheckList, CheckPackage, ProblemParam, AutoPageBreak) ShellCommandLineParseEx(CheckList,CheckPackage,ProblemParam,AutoPageBreak,FALSE) + +/** + Frees shell variable list that was returned from ShellCommandLineParse. + + This function will free all the memory that was used for the CheckPackage + list of postprocessed shell arguments. + + If CheckPackage is NULL, then return. + + @param[in] CheckPackage The list to de-allocate. + **/ +VOID +EFIAPI +ShellCommandLineFreeVarList ( + IN LIST_ENTRY *CheckPackage + ); + +/** + Checks for presence of a flag parameter. + + Flag arguments are in the form of "-<Key>" or "/<Key>", but do not have a value following the key. + + If CheckPackage is NULL then return FALSE. + If KeyString is NULL then ASSERT(). + + @param[in] CheckPackage The package of parsed command line arguments. + @param[in] KeyString The Key of the command line argument to check for. + + @retval TRUE The flag is on the command line. + @retval FALSE The flag is not on the command line. +**/ +BOOLEAN +EFIAPI +ShellCommandLineGetFlag ( + IN CONST LIST_ENTRY *CONST CheckPackage, + IN CONST CHAR16 *CONST KeyString + ); + +/** + Returns value from command line argument. + + Value parameters are in the form of "-<Key> value" or "/<Key> value". + + If CheckPackage is NULL, then return NULL. + + @param[in] CheckPackage The package of parsed command line arguments. + @param[in] KeyString The Key of the command line argument to check for. + + @retval NULL The flag is not on the command line. + @retval !=NULL The pointer to unicode string of the value. +**/ +CONST CHAR16 * +EFIAPI +ShellCommandLineGetValue ( + IN CONST LIST_ENTRY *CheckPackage, + IN CHAR16 *KeyString + ); + +/** + Returns raw value from command line argument. + + Raw value parameters are in the form of "value" in a specific position in the list. + + If CheckPackage is NULL, then return NULL. + + @param[in] CheckPackage The package of parsed command line arguments. + @param[in] Position The position of the value. + + @retval NULL The flag is not on the command line. + @retval !=NULL The pointer to unicode string of the value. +**/ +CONST CHAR16 * +EFIAPI +ShellCommandLineGetRawValue ( + IN CONST LIST_ENTRY *CONST CheckPackage, + IN UINTN Position + ); + +/** + Returns the number of command line value parameters that were parsed. + + This will not include flags. + + @param[in] CheckPackage The package of parsed command line arguments. + + @retval (UINTN)-1 No parsing has occurred. + @retval other The number of value parameters found. +**/ +UINTN +EFIAPI +ShellCommandLineGetCount ( + IN CONST LIST_ENTRY *CheckPackage + ); + +/** + Determines if a parameter is duplicated. + + If Param is not NULL, then it will point to a callee-allocated string buffer + with the parameter value, if a duplicate is found. + + If CheckPackage is NULL, then ASSERT. + + @param[in] CheckPackage The package of parsed command line arguments. + @param[out] Param Upon finding one, a pointer to the duplicated parameter. + + @retval EFI_SUCCESS No parameters were duplicated. + @retval EFI_DEVICE_ERROR A duplicate was found. + **/ +EFI_STATUS +EFIAPI +ShellCommandLineCheckDuplicate ( + IN CONST LIST_ENTRY *CheckPackage, + OUT CHAR16 **Param + ); + +/** + This function causes the shell library to initialize itself. If the shell library + is already initialized it will de-initialize all the current protocol pointers and + re-populate them again. + + When the library is used with PcdShellLibAutoInitialize set to true this function + will return EFI_SUCCESS and perform no actions. + + This function is intended for internal access for shell commands only. + + @retval EFI_SUCCESS The initialization was complete successfully. + +**/ +EFI_STATUS +EFIAPI +ShellInitialize ( + VOID + ); + +/** + Print at a specific location on the screen. + + This function will move the cursor to a given screen location and print the specified string. + + If -1 is specified for either the Row or Col the current screen location for BOTH + will be used. + + If either Row or Col is out of range for the current console, then ASSERT. + If Format is NULL, then ASSERT. + + In addition to the standard %-based flags as supported by UefiLib Print() this supports + the following additional flags: + %N - Set output attribute to normal + %H - Set output attribute to highlight + %E - Set output attribute to error + %B - Set output attribute to blue color + %V - Set output attribute to green color + + Note: The background color is controlled by the shell command cls. + + @param[in] Col The column to print at. + @param[in] Row The row to print at. + @param[in] Format The format string. + @param[in] ... The variable argument list. + + @return EFI_SUCCESS The printing was successful. + @return EFI_DEVICE_ERROR The console device reported an error. +**/ +EFI_STATUS +EFIAPI +ShellPrintEx ( + IN INT32 Col OPTIONAL, + IN INT32 Row OPTIONAL, + IN CONST CHAR16 *Format, + ... + ); + +/** + Print at a specific location on the screen. + + This function will move the cursor to a given screen location and print the specified string. + + If -1 is specified for either the Row or Col the current screen location for BOTH + will be used. + + If either Row or Col is out of range for the current console, then ASSERT. + If Format is NULL, then ASSERT. + + In addition to the standard %-based flags as supported by UefiLib Print() this supports + the following additional flags: + %N - Set output attribute to normal. + %H - Set output attribute to highlight. + %E - Set output attribute to error. + %B - Set output attribute to blue color. + %V - Set output attribute to green color. + + Note: The background color is controlled by the shell command cls. + + @param[in] Col The column to print at. + @param[in] Row The row to print at. + @param[in] Language The language of the string to retrieve. If this parameter + is NULL, then the current platform language is used. + @param[in] HiiFormatStringId The format string Id for getting from Hii. + @param[in] HiiFormatHandle The format string Handle for getting from Hii. + @param[in] ... The variable argument list. + + @return EFI_SUCCESS The printing was successful. + @return EFI_DEVICE_ERROR The console device reported an error. +**/ +EFI_STATUS +EFIAPI +ShellPrintHiiEx ( + IN INT32 Col OPTIONAL, + IN INT32 Row OPTIONAL, + IN CONST CHAR8 *Language OPTIONAL, + IN CONST EFI_STRING_ID HiiFormatStringId, + IN CONST EFI_HII_HANDLE HiiFormatHandle, + ... + ); + +/** + Function to determine if a given filename represents a directory. + + If DirName is NULL, then ASSERT. + + @param[in] DirName Path to directory to test. + + @retval EFI_SUCCESS The Path represents a directory. + @retval EFI_NOT_FOUND The Path does not represent a directory. + @retval other The path failed to open. +**/ +EFI_STATUS +EFIAPI +ShellIsDirectory ( + IN CONST CHAR16 *DirName + ); + +/** + Function to determine if a given filename represents a file. + + This will search the CWD only. + + If Name is NULL, then ASSERT. + + @param[in] Name Path to file to test. + + @retval EFI_SUCCESS The Path represents a file. + @retval EFI_NOT_FOUND The Path does not represent a file. + @retval other The path failed to open. +**/ +EFI_STATUS +EFIAPI +ShellIsFile ( + IN CONST CHAR16 *Name + ); + +/** + Function to determine if a given filename represents a file. + + This will search the CWD and then the Path. + + If Name is NULL, then ASSERT. + + @param[in] Name Path to file to test. + + @retval EFI_SUCCESS The Path represents a file. + @retval EFI_NOT_FOUND The Path does not represent a file. + @retval other The path failed to open. +**/ +EFI_STATUS +EFIAPI +ShellIsFileInPath ( + IN CONST CHAR16 *Name + ); + +/** + Function to determine whether a string is decimal or hex representation of a number + and return the number converted from the string. + + Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid + result. Use ShellConvertStringToUint64 instead. + + @param[in] String String representation of a number. + + @return The unsigned integer result of the conversion. + @retval (UINTN)(-1) An error occurred. +**/ +UINTN +EFIAPI +ShellStrToUintn ( + IN CONST CHAR16 *String + ); + +/** + Function return the number converted from a hex representation of a number. + + Note: this function cannot be used when (UINTN)(-1), (0xFFFFFFFF) may be a valid + result. Use ShellConvertStringToUint64 instead. + + @param[in] String String representation of a number. + + @return The unsigned integer result of the conversion. + @retval (UINTN)(-1) An error occurred. +**/ +UINTN +EFIAPI +ShellHexStrToUintn ( + IN CONST CHAR16 *String + ); + +/** + Safely append with automatic string resizing given length of Destination and + desired length of copy from Source. + + Append the first D characters of Source to the end of Destination, where D is + the lesser of Count and the StrLen() of Source. If appending those D characters + will fit within Destination (whose Size is given as CurrentSize) and + still leave room for a NULL terminator, then those characters are appended, + starting at the original terminating NULL of Destination, and a new terminating + NULL is appended. + + If appending D characters onto Destination will result in a overflow of the size + given in CurrentSize the string will be grown such that the copy can be performed + and CurrentSize will be updated to the new size. + + If Source is NULL, there is nothing to append, so return the current buffer in + Destination. + + If Destination is NULL, then ASSERT(). + If Destination's current length (including NULL terminator) is already more than + CurrentSize, then ASSERT(). + + @param[in, out] Destination The String to append onto. + @param[in, out] CurrentSize On call, the number of bytes in Destination. On + return, possibly the new size (still in bytes). If NULL, + then allocate whatever is needed. + @param[in] Source The String to append from. + @param[in] Count The maximum number of characters to append. If 0, then + all are appended. + + @return The Destination after appending the Source. +**/ +CHAR16 * +EFIAPI +StrnCatGrow ( + IN OUT CHAR16 **Destination, + IN OUT UINTN *CurrentSize, + IN CONST CHAR16 *Source, + IN UINTN Count + ); + +/** + This is a find and replace function. Upon successful return the NewString is a copy of + SourceString with each instance of FindTarget replaced with ReplaceWith. + + If SourceString and NewString overlap the behavior is undefined. + + If the string would grow bigger than NewSize it will halt and return error. + + @param[in] SourceString The string with source buffer. + @param[in, out] NewString The string with resultant buffer. + @param[in] NewSize The size in bytes of NewString. + @param[in] FindTarget The string to look for. + @param[in] ReplaceWith The string to replace FindTarget with. + @param[in] SkipPreCarrot If TRUE will skip a FindTarget that has a '^' + immediately before it. + @param[in] ParameterReplacing If TRUE will add "" around items with spaces. + + @retval EFI_INVALID_PARAMETER SourceString was NULL. + @retval EFI_INVALID_PARAMETER NewString was NULL. + @retval EFI_INVALID_PARAMETER FindTarget was NULL. + @retval EFI_INVALID_PARAMETER ReplaceWith was NULL. + @retval EFI_INVALID_PARAMETER FindTarget had length < 1. + @retval EFI_INVALID_PARAMETER SourceString had length < 1. + @retval EFI_BUFFER_TOO_SMALL NewSize was less than the minimum size to hold + the new string (truncation occurred). + @retval EFI_SUCCESS The string was successfully copied with replacement. +**/ +EFI_STATUS +EFIAPI +ShellCopySearchAndReplace ( + IN CHAR16 CONST *SourceString, + IN OUT CHAR16 *NewString, + IN UINTN NewSize, + IN CONST CHAR16 *FindTarget, + IN CONST CHAR16 *ReplaceWith, + IN CONST BOOLEAN SkipPreCarrot, + IN CONST BOOLEAN ParameterReplacing + ); + +/** + Check if a Unicode character is a hexadecimal character. + + This internal function checks if a Unicode character is a + numeric character. The valid hexadecimal characters are + L'0' to L'9', L'a' to L'f', or L'A' to L'F'. + + + @param Char The character to check against. + + @retval TRUE The Char is a hexadecmial character. + @retval FALSE The Char is not a hexadecmial character. + +**/ +BOOLEAN +EFIAPI +ShellIsHexaDecimalDigitCharacter ( + IN CHAR16 Char + ); + +/** + Check if a Unicode character is a decimal character. + + This internal function checks if a Unicode character is a + decimal character. The valid characters are + L'0' to L'9'. + + + @param Char The character to check against. + + @retval TRUE The Char is a hexadecmial character. + @retval FALSE The Char is not a hexadecmial character. + +**/ +BOOLEAN +EFIAPI +ShellIsDecimalDigitCharacter ( + IN CHAR16 Char + ); + +/// +/// What type of answer is requested. +/// +typedef enum { + ShellPromptResponseTypeYesNo, + ShellPromptResponseTypeYesNoCancel, + ShellPromptResponseTypeFreeform, + ShellPromptResponseTypeQuitContinue, + ShellPromptResponseTypeYesNoAllCancel, + ShellPromptResponseTypeEnterContinue, + ShellPromptResponseTypeAnyKeyContinue, + ShellPromptResponseTypeMax +} SHELL_PROMPT_REQUEST_TYPE; + +/// +/// What answer was given. +/// +typedef enum { + ShellPromptResponseYes, + ShellPromptResponseNo, + ShellPromptResponseCancel, + ShellPromptResponseQuit, + ShellPromptResponseContinue, + ShellPromptResponseAll, + ShellPromptResponseMax +} SHELL_PROMPT_RESPONSE; + +/** + Prompt the user and return the resultant answer to the requestor. + + This function will display the requested question on the shell prompt and then + wait for an appropriate answer to be input from the console. + + If the SHELL_PROMPT_REQUEST_TYPE is SHELL_PROMPT_REQUEST_TYPE_YESNO, ShellPromptResponseTypeQuitContinue + or SHELL_PROMPT_REQUEST_TYPE_YESNOCANCEL then *Response is of type SHELL_PROMPT_RESPONSE. + + If the SHELL_PROMPT_REQUEST_TYPE is ShellPromptResponseTypeFreeform then *Response is of type + CHAR16*. + + In either case *Response must be callee freed if Response was not NULL; + + @param Type What type of question is asked. This is used to filter the input + to prevent invalid answers to question. + @param Prompt The pointer to a string prompt used to request input. + @param Response The pointer to Response, which will be populated upon return. + + @retval EFI_SUCCESS The operation was successful. + @retval EFI_UNSUPPORTED The operation is not supported as requested. + @retval EFI_INVALID_PARAMETER A parameter was invalid. + @return other The operation failed. +**/ +EFI_STATUS +EFIAPI +ShellPromptForResponse ( + IN SHELL_PROMPT_REQUEST_TYPE Type, + IN CHAR16 *Prompt OPTIONAL, + IN OUT VOID **Response OPTIONAL + ); + +/** + Prompt the user and return the resultant answer to the requestor. + + This function is the same as ShellPromptForResponse, except that the prompt is + automatically pulled from HII. + + @param[in] Type What type of question is asked. This is used to filter the input + to prevent invalid answers to question. + @param[in] HiiFormatStringId The format string Id for getting from Hii. + @param[in] HiiFormatHandle The format string Handle for getting from Hii. + @param[in, out] Response The pointer to Response, which will be populated upon return. + + @retval EFI_SUCCESS The operation was successful. + @return other The operation failed. + + @sa ShellPromptForResponse +**/ +EFI_STATUS +EFIAPI +ShellPromptForResponseHii ( + IN SHELL_PROMPT_REQUEST_TYPE Type, + IN CONST EFI_STRING_ID HiiFormatStringId, + IN CONST EFI_HII_HANDLE HiiFormatHandle, + IN OUT VOID **Response + ); + +/** + Function to determin if an entire string is a valid number. + + If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE. + + @param[in] String The string to evaluate. + @param[in] ForceHex TRUE - always assume hex. + @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to keep going. + + @retval TRUE It is all numeric (dec/hex) characters. + @retval FALSE There is a non-numeric character. +**/ +BOOLEAN +EFIAPI +ShellIsHexOrDecimalNumber ( + IN CONST CHAR16 *String, + IN CONST BOOLEAN ForceHex, + IN CONST BOOLEAN StopAtSpace + ); + +/** + Function to verify and convert a string to its numerical 64 bit representation. + + If Hex it must be preceeded with a 0x, 0X, or has ForceHex set TRUE. + + @param[in] String The string to evaluate. + @param[out] Value Upon a successful return the value of the conversion. + @param[in] ForceHex TRUE - always assume hex. + @param[in] StopAtSpace TRUE to halt upon finding a space, FALSE to + process the entire String. + + @retval EFI_SUCCESS The conversion was successful. + @retval EFI_INVALID_PARAMETER String contained an invalid character. + @retval EFI_NOT_FOUND String was a number, but Value was NULL. +**/ +EFI_STATUS +EFIAPI +ShellConvertStringToUint64 ( + IN CONST CHAR16 *String, + OUT UINT64 *Value, + IN CONST BOOLEAN ForceHex, + IN CONST BOOLEAN StopAtSpace + ); + +/** + Function to determine if a given filename exists. + + @param[in] Name Path to test. + + @retval EFI_SUCCESS The Path represents a file. + @retval EFI_NOT_FOUND The Path does not represent a file. + @retval other The path failed to open. +**/ +EFI_STATUS +EFIAPI +ShellFileExists ( + IN CONST CHAR16 *Name + ); + +/** + Function to read a single line from a SHELL_FILE_HANDLE. The \n is not included in the returned + buffer. The returned buffer must be callee freed. + + If the position upon start is 0, then the Ascii Boolean will be set. This should be + maintained and not changed for all operations with the same file. + + @param[in] Handle SHELL_FILE_HANDLE to read from. + @param[in, out] Ascii Boolean value for indicating whether the file is + Ascii (TRUE) or UCS2 (FALSE). + + @return The line of text from the file. + + @sa ShellFileHandleReadLine +**/ +CHAR16 * +EFIAPI +ShellFileHandleReturnLine ( + IN SHELL_FILE_HANDLE Handle, + IN OUT BOOLEAN *Ascii + ); + +/** + Function to read a single line (up to but not including the \n) from a SHELL_FILE_HANDLE. + + If the position upon start is 0, then the Ascii Boolean will be set. This should be + maintained and not changed for all operations with the same file. + + @param[in] Handle SHELL_FILE_HANDLE to read from. + @param[in, out] Buffer The pointer to buffer to read into. + @param[in, out] Size The pointer to number of bytes in Buffer. + @param[in] Truncate If the buffer is large enough, this has no effect. + If the buffer is is too small and Truncate is TRUE, + the line will be truncated. + If the buffer is is too small and Truncate is FALSE, + then no read will occur. + + @param[in, out] Ascii Boolean value for indicating whether the file is + Ascii (TRUE) or UCS2 (FALSE). + + @retval EFI_SUCCESS The operation was successful. The line is stored in + Buffer. + @retval EFI_END_OF_FILE There are no more lines in the file. + @retval EFI_INVALID_PARAMETER Handle was NULL. + @retval EFI_INVALID_PARAMETER Size was NULL. + @retval EFI_BUFFER_TOO_SMALL Size was not large enough to store the line. + Size was updated to the minimum space required. +**/ +EFI_STATUS +EFIAPI +ShellFileHandleReadLine ( + IN SHELL_FILE_HANDLE Handle, + IN OUT CHAR16 *Buffer, + IN OUT UINTN *Size, + IN BOOLEAN Truncate, + IN OUT BOOLEAN *Ascii + ); + +/** + Function to delete a file by name + + @param[in] FileName Pointer to file name to delete. + + @retval EFI_SUCCESS the file was deleted successfully + @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not + deleted + @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. + @retval EFI_NOT_FOUND The specified file could not be found on the + device or the file system could not be found + on the device. + @retval EFI_NO_MEDIA The device has no medium. + @retval EFI_MEDIA_CHANGED The device has a different medium in it or the + medium is no longer supported. + @retval EFI_DEVICE_ERROR The device reported an error. + @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. + @retval EFI_WRITE_PROTECTED The file or medium is write protected. + @retval EFI_ACCESS_DENIED The file was opened read only. + @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the + file. + @retval other The file failed to open +**/ +EFI_STATUS +EFIAPI +ShellDeleteFileByName ( + IN CONST CHAR16 *FileName + ); + +/** + Function to print help file / man page content in the spec from the UEFI Shell protocol GetHelpText function. + + @param[in] CommandToGetHelpOn Pointer to a string containing the command name of help file to be printed. + @param[in] SectionToGetHelpOn Pointer to the section specifier(s). + @param[in] PrintCommandText If TRUE, prints the command followed by the help content, otherwise prints + the help content only. + @retval EFI_DEVICE_ERROR The help data format was incorrect. + @retval EFI_NOT_FOUND The help data could not be found. + @retval EFI_SUCCESS The operation was successful. +**/ +EFI_STATUS +EFIAPI +ShellPrintHelp ( + IN CONST CHAR16 *CommandToGetHelpOn, + IN CONST CHAR16 *SectionToGetHelpOn, + IN BOOLEAN PrintCommandText + ); + +#endif // __SHELL_LIB__ |