ShellCommandLib.h@ 61497

Last change on this file since 61497 was 58466, checked in by vboxsync, 9 years ago
EFI/Firmware: Merged in the svn:eol-style, svn:mime-type and trailing whitespace cleanup that was done after the initial UDK2014.SP1 import: svn merge ^{/vendor/edk2/UDK2014.SP1}/vendor/edk2/current .
Property svn:eol-style set to `native`
File size: 20.0 KB

Line
1	/** @file
2	Provides interface to shell internal functions for shell commands.
3
4	This library is for use ONLY by shell commands linked into the shell application.
5	This library will not funciton if it is used for UEFI Shell 2.0 Applications.
6
7	(C) Copyright 2013-2014, Hewlett-Packard Development Company, L.P.
8	Copyright (c) 2009 - 2014, Intel Corporation. All rights reserved.<BR>
9	This program and the accompanying materials
10	are licensed and made available under the terms and conditions of the BSD License
11	which accompanies this distribution. The full text of the license may be found at
12	http://opensource.org/licenses/bsd-license.php.
13
14	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16
17	**/
18
19	#ifndef _SHELL_COMMAND_LIB_
20	#define _SHELL_COMMAND_LIB_
21
22	#include <Uefi.h>
23	#include <ShellBase.h>
24
25	#include <Protocol/EfiShell.h>
26	#include <Protocol/EfiShellParameters.h>
27	#include <Protocol/UnicodeCollation.h>
28	#include <Protocol/SimpleFileSystem.h>
29
30	#include <Library/UefiBootServicesTableLib.h>
31
32	//
33	// The extern global protocol poionters.
34	//
35	extern EFI_UNICODE_COLLATION_PROTOCOL *gUnicodeCollation;
36	extern CONST CHAR16* SupportLevel[];
37
38	//
39	// The map list objects.
40	//
41	typedef struct {
42	LIST_ENTRY Link;
43	EFI_DEVICE_PATH_PROTOCOL *DevicePath;
44	CHAR16 *MapName;
45	CHAR16 *CurrentDirectoryPath;
46	UINT64 Flags;
47	} SHELL_MAP_LIST;
48	/// List of Mappings - DeviceName and Drive Letter(ism).
49	extern SHELL_MAP_LIST gShellMapList;
50	/// Pointer to node of current directory in the mMapList.
51	extern SHELL_MAP_LIST *gShellCurDir;
52
53	/**
54	Returns the help MAN fileName for a given shell command.
55
56	@retval !NULL The unicode string of the MAN filename.
57	@retval NULL An error ocurred.
58
59	**/
60	typedef
61	CONST CHAR16 *
62	(EFIAPI *SHELL_GET_MAN_FILENAME)(
63	VOID
64	);
65
66	/**
67	Runs a shell command on a given command line.
68
69	The specific operation of a given shell command is specified in the UEFI Shell
70	Specification 2.0, or in the source of the given command.
71
72	Upon completion of the command run the shell protocol and environment variables
73	may have been updated due to the operation.
74
75	@param[in] ImageHandle The ImageHandle to the app, or NULL if
76	the command built into shell.
77	@param[in] SystemTable The pointer to the system table.
78
79	@retval RETURN_SUCCESS The shell command was sucessful.
80	@retval RETURN_UNSUPPORTED The command is not supported.
81	**/
82	typedef
83	SHELL_STATUS
84	(EFIAPI *SHELL_RUN_COMMAND)(
85	IN EFI_HANDLE ImageHandle,
86	IN EFI_SYSTEM_TABLE *SystemTable
87	);
88
89	/**
90	Registers the handlers of type SHELL_RUN_COMMAND and
91	SHELL_GET_MAN_FILENAME for each shell command.
92
93	If the ShellSupportLevel is greater than the value of
94	PcdShellSupportLevel, then return RETURN_UNSUPPORTED.
95
96	Registers the the handlers specified by GetHelpInfoHandler and CommandHandler
97	with the command specified by CommandString. If the command named by
98	CommandString has already been registered, then return
99	RETURN_ALREADY_STARTED.
100
101	If there are not enough resources available to register the handlers, then
102	RETURN_OUT_OF_RESOURCES is returned.
103
104	If CommandString is NULL, then ASSERT().
105	If GetHelpInfoHandler is NULL, then ASSERT().
106	If CommandHandler is NULL, then ASSERT().
107	If ProfileName is NULL, then ASSERT().
108
109	@param[in] CommandString The pointer to the command name. This is the
110	name to look for on the command line in
111	the shell.
112	@param[in] CommandHandler The pointer to a function that runs the
113	specified command.
114	@param[in] GetManFileName The pointer to a function that provides man
115	filename.
116	@param[in] ShellMinSupportLevel The minimum Shell Support Level which has this
117	function.
118	@param[in] ProfileName The profile name to require for support of this
119	function.
120	@param[in] CanAffectLE Indicates whether this command's return value
121	can change the LASTERROR environment variable.
122	@param[in] HiiHandle The handle of this command's HII entry.
123	@param[in] ManFormatHelp The HII locator for the help text.
124
125	@retval RETURN_SUCCESS The handlers were registered.
126	@retval RETURN_OUT_OF_RESOURCES There are not enough resources available to
127	register the shell command.
128	@retval RETURN_UNSUPPORTED The ShellMinSupportLevel was higher than the
129	currently allowed support level.
130	@retval RETURN_ALREADY_STARTED The CommandString represents a command that
131	is already registered. Only one handler set for
132	a given command is allowed.
133	@sa SHELL_GET_MAN_FILENAME
134	@sa SHELL_RUN_COMMAND
135	**/
136	RETURN_STATUS
137	EFIAPI
138	ShellCommandRegisterCommandName (
139	IN CONST CHAR16 *CommandString,
140	IN SHELL_RUN_COMMAND CommandHandler,
141	IN SHELL_GET_MAN_FILENAME GetManFileName,
142	IN UINT32 ShellMinSupportLevel,
143	IN CONST CHAR16 *ProfileName,
144	IN CONST BOOLEAN CanAffectLE,
145	IN CONST EFI_HANDLE HiiHandle,
146	IN CONST EFI_STRING_ID ManFormatHelp
147	);
148
149	/**
150	Checks if a command string has been registered for CommandString, and if so, it runs
151	the previously registered handler for that command with the command line.
152
153	If CommandString is NULL, then ASSERT().
154
155	If Sections is specified, then each section name listed will be compared in a case sensitive
156	manner to the section names described in Appendix B UEFI Shell 2.0 Specification. If the section exists,
157	it is appended to the returned help text. If the section does not exist, no
158	information is returned. If Sections is NULL, then all help text information
159	available is returned.
160
161	@param[in] CommandString The pointer to the command name. This is the name
162	found on the command line in the shell.
163	@param[in, out] RetVal The pointer to the return value from the command handler.
164
165	@param[in, out] CanAffectLE Indicates whether this command's return value
166	needs to be placed into LASTERROR environment variable.
167
168	@retval RETURN_SUCCESS The handler was run.
169	@retval RETURN_NOT_FOUND The CommandString did not match a registered
170	command name.
171	@sa SHELL_RUN_COMMAND
172	**/
173	RETURN_STATUS
174	EFIAPI
175	ShellCommandRunCommandHandler (
176	IN CONST CHAR16 *CommandString,
177	IN OUT SHELL_STATUS *RetVal,
178	IN OUT BOOLEAN *CanAffectLE OPTIONAL
179	);
180
181	/**
182	Checks if a command string has been registered for CommandString, and if so, it
183	returns the MAN filename specified for that command.
184
185	If CommandString is NULL, then ASSERT().
186
187	@param[in] CommandString The pointer to the command name. This is the name
188	found on the command line in the shell.
189
190	@retval NULL The CommandString was not a registered command.
191	@retval other The name of the MAN file.
192	@sa SHELL_GET_MAN_FILENAME
193	**/
194	CONST CHAR16*
195	EFIAPI
196	ShellCommandGetManFileNameHandler (
197	IN CONST CHAR16 *CommandString
198	);
199
200
201	typedef struct {
202	LIST_ENTRY Link;
203	CHAR16 *CommandString;
204	} COMMAND_LIST;
205
206	/**
207	Get the list of all available shell internal commands. This is a linked list,
208	via the LIST_ENTRY structure. Enumerate through it using the BaseLib linked
209	list functions. Do not modify the values.
210
211	@param[in] Sort TRUE to alphabetically sort the values first. FALSE otherwise.
212
213	@return A linked list of all available shell commands.
214	**/
215	CONST COMMAND_LIST*
216	EFIAPI
217	ShellCommandGetCommandList (
218	IN CONST BOOLEAN Sort
219	);
220
221	typedef struct {
222	LIST_ENTRY Link;
223	CHAR16 *CommandString;
224	CHAR16 *Alias;
225	} ALIAS_LIST;
226
227	/**
228	Registers aliases to be set as part of the initialization of the shell application.
229
230	If Command is NULL, then ASSERT().
231	If Alias is NULL, then ASSERT().
232
233	@param[in] Command The pointer to the Command.
234	@param[in] Alias The pointer to Alias.
235
236	@retval RETURN_SUCCESS The handlers were registered.
237	@retval RETURN_OUT_OF_RESOURCES There are not enough resources available to
238	register the shell command.
239	**/
240	RETURN_STATUS
241	EFIAPI
242	ShellCommandRegisterAlias (
243	IN CONST CHAR16 *Command,
244	IN CONST CHAR16 *Alias
245	);
246
247	/**
248	Get the list of all shell alias commands. This is a linked list,
249	via LIST_ENTRY structure. Enumerate through it using the BaseLib linked
250	list functions. Do not modify the values.
251
252	@return A linked list of all requested shell aliases.
253	**/
254	CONST ALIAS_LIST*
255	EFIAPI
256	ShellCommandGetInitAliasList (
257	VOID
258	);
259
260	/**
261	Determine if a given alias is on the list of built in aliases.
262
263	@param[in] Alias The alias to test for.
264
265	@retval TRUE The alias is a built in alias.
266	@retval FALSE The alias is not a built in alias.
267	**/
268	BOOLEAN
269	EFIAPI
270	ShellCommandIsOnAliasList (
271	IN CONST CHAR16 *Alias
272	);
273
274	/**
275	Checks if a command is already on the list.
276
277	@param[in] CommandString The command string to check for on the list.
278
279	@retval TRUE CommandString represents a registered command.
280	@retval FALSE CommandString does not represent a registered command.
281	**/
282	BOOLEAN
283	EFIAPI
284	ShellCommandIsCommandOnList (
285	IN CONST CHAR16 *CommandString
286	);
287
288	/**
289	Get the help text for a command.
290
291	@param[in] CommandString The command name.
292
293	@retval NULL No help text was found.
294	@return The string of the help text. The caller required to free.
295	**/
296	CHAR16*
297	EFIAPI
298	ShellCommandGetCommandHelp (
299	IN CONST CHAR16 *CommandString
300	);
301
302	/**
303	Function to make sure that the above pointers are valid.
304	**/
305	EFI_STATUS
306	EFIAPI
307	CommandInit (
308	VOID
309	);
310
311	/**
312	Function to determine current state of ECHO. Echo determines if lines from scripts
313	and ECHO commands are enabled.
314
315	@retval TRUE Echo is currently enabled.
316	@retval FALSE Echo is currently disabled.
317	**/
318	BOOLEAN
319	EFIAPI
320	ShellCommandGetEchoState (
321	VOID
322	);
323
324	/**
325	Function to set current state of ECHO. Echo determines if lines from scripts
326	and ECHO commands are enabled.
327
328	@param[in] State TRUE to enable Echo, FALSE otherwise.
329	**/
330	VOID
331	EFIAPI
332	ShellCommandSetEchoState (
333	IN BOOLEAN State
334	);
335
336
337
338	/**
339	Indicate that the current shell or script should exit.
340
341	@param[in] ScriptOnly TRUE if exiting a script; FALSE otherwise.
342	@param[in] ErrorCode The 64 bit error code to return.
343	**/
344	VOID
345	EFIAPI
346	ShellCommandRegisterExit (
347	IN BOOLEAN ScriptOnly,
348	IN CONST UINT64 ErrorCode
349	);
350
351	/**
352	Retrieve the Exit code.
353
354	@return the value passed into RegisterExit.
355	**/
356	UINT64
357	EFIAPI
358	ShellCommandGetExitCode (
359	VOID
360	);
361
362	/**
363	Retrieve the Exit indicator.
364
365	@retval TRUE Exit was indicated.
366	@retval FALSE Exit was not indicated.
367	**/
368	BOOLEAN
369	EFIAPI
370	ShellCommandGetExit (
371	VOID
372	);
373
374	/**
375	Retrieve the Exit script indicator.
376
377	If ShellCommandGetExit returns FALSE, then the return from this is undefined.
378
379	@retval TRUE ScriptOnly was indicated.
380	@retval FALSE ScriptOnly was not indicated.
381	**/
382	BOOLEAN
383	EFIAPI
384	ShellCommandGetScriptExit (
385	VOID
386	);
387
388	typedef struct {
389	LIST_ENTRY Link; ///< List enumerator items.
390	UINTN Line; ///< What line of the script file this was on.
391	CHAR16 *Cl; ///< The original command line.
392	VOID *Data; ///< The data structure format dependant upon Command. (not always used)
393	BOOLEAN Reset; ///< Reset the command (it must be treated like a initial run (but it may have data already))
394	} SCRIPT_COMMAND_LIST;
395
396	typedef struct {
397	CHAR16 *ScriptName; ///< The filename of this script.
398	CHAR16 **Argv; ///< The parmameters to the script file.
399	UINTN Argc; ///< The count of parameters.
400	LIST_ENTRY CommandList; ///< The script converted to a list of commands (SCRIPT_COMMAND_LIST objects).
401	SCRIPT_COMMAND_LIST *CurrentCommand; ///< The command currently being operated. If !=NULL must be a member of CommandList.
402	LIST_ENTRY SubstList; ///< A list of current script loop alias' (ALIAS_LIST objects) (Used for the for %-based replacement).
403	} SCRIPT_FILE;
404
405	/**
406	Function to return a pointer to the currently running script file object.
407
408	@retval NULL A script file is not currently running.
409	@return A pointer to the current script file object.
410	**/
411	SCRIPT_FILE*
412	EFIAPI
413	ShellCommandGetCurrentScriptFile (
414	VOID
415	);
416
417	/**
418	Function to set a new script as the currently running one.
419
420	This function will correctly stack and unstack nested scripts.
421
422	@param[in] Script The pointer to new script information structure. If NULL,
423	it removes and de-allocates the topmost Script structure.
424
425	@return A pointer to the current running script file after this
426	change. It is NULL if removing the final script.
427	**/
428	SCRIPT_FILE*
429	EFIAPI
430	ShellCommandSetNewScript (
431	IN SCRIPT_FILE *Script OPTIONAL
432	);
433
434	/**
435	Function to cleanup all memory from a SCRIPT_FILE structure.
436
437	@param[in] Script The pointer to the structure to cleanup.
438	**/
439	VOID
440	EFIAPI
441	DeleteScriptFileStruct (
442	IN SCRIPT_FILE *Script
443	);
444
445	/**
446	Function to get the current Profile string.
447
448	This is used to retrieve what profiles were installed.
449
450	@retval NULL There are no installed profiles.
451	@return A semicolon-delimited list of profiles.
452	**/
453	CONST CHAR16 *
454	EFIAPI
455	ShellCommandGetProfileList (
456	VOID
457	);
458
459	typedef enum {
460	MappingTypeFileSystem,
461	MappingTypeBlockIo,
462	MappingTypeMax
463	} SHELL_MAPPING_TYPE;
464
465	/**
466	Function to generate the next default mapping name.
467
468	If the return value is not NULL then it must be callee freed.
469
470	@param Type What kind of mapping name to make.
471
472	@retval NULL a memory allocation failed.
473	@return a new map name string
474	**/
475	CHAR16*
476	EFIAPI
477	ShellCommandCreateNewMappingName(
478	IN CONST SHELL_MAPPING_TYPE Type
479	);
480
481	/**
482	Function to initialize the table for creating consistent map names.
483
484	@param[out] Table The pointer to pointer to pointer to DevicePathProtocol object.
485
486	@retval EFI_SUCCESS The table was created successfully.
487	**/
488	EFI_STATUS
489	EFIAPI
490	ShellCommandConsistMappingInitialize (
491	EFI_DEVICE_PATH_PROTOCOL ***Table
492	);
493
494	/**
495	Function to uninitialize the table for creating consistent map names.
496
497	The parameter must have been received from ShellCommandConsistMappingInitialize.
498
499	@param[out] Table The pointer to pointer to DevicePathProtocol object.
500
501	@retval EFI_SUCCESS The table was deleted successfully.
502	**/
503	EFI_STATUS
504	EFIAPI
505	ShellCommandConsistMappingUnInitialize (
506	EFI_DEVICE_PATH_PROTOCOL **Table
507	);
508
509	/**
510	Create a consistent mapped name for the device specified by DevicePath
511	based on the Table.
512
513	This must be called after ShellCommandConsistMappingInitialize() and
514	before ShellCommandConsistMappingUnInitialize() is called.
515
516	@param[in] DevicePath The pointer to the dev path for the device.
517	@param[in] Table The Table of mapping information.
518
519	@retval NULL A consistent mapped name could not be created.
520	@return A pointer to a string allocated from pool with the device name.
521	**/
522	CHAR16*
523	EFIAPI
524	ShellCommandConsistMappingGenMappingName (
525	IN EFI_DEVICE_PATH_PROTOCOL *DevicePath,
526	IN EFI_DEVICE_PATH_PROTOCOL **Table
527	);
528
529	/**
530	Function to search the list of mappings for the first matching node on the
531	list based on the MapKey.
532
533	@param[in] MapKey The pointer to the string key to search for in the map.
534
535	@return the node on the list.
536	**/
537	SHELL_MAP_LIST*
538	EFIAPI
539	ShellCommandFindMapItem (
540	IN CONST CHAR16 *MapKey
541	);
542
543	/**
544	Function to add a map node to the list of map items and update the "path" environment variable (optionally).
545
546	If Path is TRUE (during initialization only), the path environment variable will also be updated to include
547	default paths on the new map name...
548
549	Path should be FALSE when this function is called from the protocol SetMap function.
550
551	@param[in] Name The human readable mapped name.
552	@param[in] DevicePath The Device Path for this map.
553	@param[in] Flags The Flags attribute for this map item.
554	@param[in] Path TRUE to update path, FALSE to skip this step (should only be TRUE during initialization).
555
556	@retval EFI_SUCCESS The addition was sucessful.
557	@retval EFI_OUT_OF_RESOURCES A memory allocation failed.
558	@retval EFI_INVALID_PARAMETER A parameter was invalid.
559	**/
560	EFI_STATUS
561	EFIAPI
562	ShellCommandAddMapItemAndUpdatePath(
563	IN CONST CHAR16 *Name,
564	IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath,
565	IN CONST UINT64 Flags,
566	IN CONST BOOLEAN Path
567	);
568
569	/**
570	Creates the default map names for each device path in the system with
571	a protocol depending on the Type.
572
573	Also sets up the default path environment variable if Type is FileSystem.
574
575	@retval EFI_SUCCESS All map names were created sucessfully.
576	@retval EFI_NOT_FOUND No protocols were found in the system.
577	@return Error returned from gBS->LocateHandle().
578
579	@sa LocateHandle
580	**/
581	EFI_STATUS
582	EFIAPI
583	ShellCommandCreateInitialMappingsAndPaths(
584	VOID
585	);
586
587	/**
588	Add mappings for any devices without one. Do not change any existing maps.
589
590	@retval EFI_SUCCESS The operation was successful.
591	**/
592	EFI_STATUS
593	EFIAPI
594	ShellCommandUpdateMapping (
595	VOID
596	);
597
598	/**
599	Converts a SHELL_FILE_HANDLE to an EFI_FILE_PROTOCOL*.
600
601	@param[in] Handle The SHELL_FILE_HANDLE to convert.
602
603	@return a EFI_FILE_PROTOCOL* representing the same file.
604	**/
605	EFI_FILE_PROTOCOL*
606	EFIAPI
607	ConvertShellHandleToEfiFileProtocol(
608	IN CONST SHELL_FILE_HANDLE Handle
609	);
610
611	/**
612	Remove a SHELL_FILE_HANDLE frmo the list of SHELL_FILE_HANDLES.
613
614	@param[in] Handle The SHELL_FILE_HANDLE to remove.
615
616	@retval TRUE The item was removed.
617	@retval FALSE The item was not found.
618	**/
619	BOOLEAN
620	EFIAPI
621	ShellFileHandleRemove(
622	IN CONST SHELL_FILE_HANDLE Handle
623	);
624
625	/**
626	Converts a EFI_FILE_PROTOCOL* to an SHELL_FILE_HANDLE.
627
628	@param[in] Handle The pointer to EFI_FILE_PROTOCOL to convert.
629	@param[in] Path The path to the file for verification.
630
631	@return a SHELL_FILE_HANDLE representing the same file.
632	**/
633	SHELL_FILE_HANDLE
634	EFIAPI
635	ConvertEfiFileProtocolToShellHandle(
636	IN CONST EFI_FILE_PROTOCOL *Handle,
637	IN CONST CHAR16 *Path
638	);
639
640	/**
641	Find the path that was logged with the specified SHELL_FILE_HANDLE.
642
643	@param[in] Handle The SHELL_FILE_HANDLE to query on.
644
645	@return A pointer to the path for the file.
646	**/
647	CONST CHAR16*
648	EFIAPI
649	ShellFileHandleGetPath(
650	IN CONST SHELL_FILE_HANDLE Handle
651	);
652
653
654	/**
655	Function to determine if a SHELL_FILE_HANDLE is at the end of the file.
656
657	This will NOT work on directories.
658
659	If Handle is NULL, then ASSERT.
660
661	@param[in] Handle the file handle
662
663	@retval TRUE the position is at the end of the file
664	@retval FALSE the position is not at the end of the file
665	**/
666	BOOLEAN
667	EFIAPI
668	ShellFileHandleEof(
669	IN SHELL_FILE_HANDLE Handle
670	);
671
672	typedef struct {
673	LIST_ENTRY Link;
674	void *Buffer;
675	} BUFFER_LIST;
676
677	/**
678	Frees any BUFFER_LIST defined type.
679
680	@param[in] List The pointer to the list head.
681	**/
682	VOID
683	EFIAPI
684	FreeBufferList (
685	IN BUFFER_LIST *List
686	);
687
688	#endif //_SHELL_COMMAND_LIB_

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/ShellPkg/Include/Library/ShellCommandLib.h@ 61497

Download in other formats: