EfiShellEnvironment2.h@ 99396

Last change on this file since 99396 was 80721, checked in by vboxsync, 6 years ago
Devices/EFI/FirmwareNew: Start upgrade process to edk2-stable201908 (compiles on Windows and works to some extent), bugref:4643
Property svn:eol-style set to `native`
File size: 32.1 KB

Line
1	/** @file
2	Defines for EFI shell environment 2 ported to EDK II build environment. (no spec)
3
4	Copyright (c) 2005 - 2010, Intel Corporation. All rights reserved.<BR>
5	SPDX-License-Identifier: BSD-2-Clause-Patent
6
7	**/
8
9
10	#ifndef _SHELL_ENVIRONMENT_2_PROTOCOL_H_
11	#define _SHELL_ENVIRONMENT_2_PROTOCOL_H_
12
13	#define DEFAULT_INIT_ROW 1
14	#define DEFAULT_AUTO_LF FALSE
15
16	/**
17	This function is a prototype for a function that dumps information on a protocol
18	to a given location. The location is dependant on the implementation. This is
19	used when programatically adding shell commands.
20
21	@param[in] Handle The handle the protocol is on.
22	@param[in] Interface The interface to the protocol.
23
24	**/
25	typedef
26	VOID
27	(EFIAPI *SHELLENV_DUMP_PROTOCOL_INFO) (
28	IN EFI_HANDLE Handle,
29	IN VOID *Interface
30	);
31
32	/**
33	This function is a prototype for each command internal to the EFI shell
34	implementation. The specific command depends on the implementation. This is
35	used when programatically adding shell commands.
36
37	@param[in] ImageHandle The handle to the binary shell.
38	@param[in] SystemTable The pointer to the system table.
39
40	@retval EFI_SUCCESS The command completed.
41	@retval other An error occurred. Any error is possible
42	depending on the implementation of the shell
43	command.
44
45	**/
46	typedef
47	EFI_STATUS
48	(EFIAPI *SHELLENV_INTERNAL_COMMAND) (
49	IN EFI_HANDLE ImageHandle,
50	IN EFI_SYSTEM_TABLE *SystemTable
51	);
52
53	/**
54	This function is a prototype for one that gets a help string for a given command.
55	This is used when programatically adding shell commands. Upon successful return
56	the memory allocated is up to the caller to free.
57
58	@param[in, out] Str Pointer to pointer to string to display for help.
59
60	@retval EFI_SUCCESS The help string is in the parameter Str.
61
62	**/
63	typedef
64	EFI_STATUS
65	(EFIAPI *SHELLCMD_GET_LINE_HELP) (
66	IN OUT CHAR16 **Str
67	);
68
69	/**
70	Structure returned from functions that open multiple files.
71	**/
72	typedef struct {
73	UINT32 Signature; ///< SHELL_FILE_ARG_SIGNATURE.
74	LIST_ENTRY Link; ///< Linked list helper.
75	EFI_STATUS Status; ///< File's status.
76
77	EFI_FILE_HANDLE Parent; ///< What is the Parent file of this file.
78	UINT64 OpenMode; ///< How was the file opened.
79	CHAR16 *ParentName; ///< String representation of parent.
80	EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath; ///< DevicePath for Parent.
81
82	CHAR16 *FullName; ///< Path and file name for this file.
83	CHAR16 *FileName; ///< File name for this file.
84
85	EFI_FILE_HANDLE Handle; ///< Handle to this file.
86	EFI_FILE_INFO *Info; ///< Pointer to file info for this file.
87	} SHELL_FILE_ARG;
88
89	/// Signature for SHELL_FILE_ARG.
90	#define SHELL_FILE_ARG_SIGNATURE SIGNATURE_32 ('g', 'r', 'a', 'f')
91
92	/**
93	GUID for the shell environment2 and shell environment.
94	**/
95	#define SHELL_ENVIRONMENT_PROTOCOL_GUID \
96	{ \
97	0x47c7b221, 0xc42a, 0x11d2, {0x8e, 0x57, 0x0, 0xa0, 0xc9, 0x69, 0x72, 0x3b} \
98	}
99
100	/**
101	GUID for the shell environment2 extension (main GUID above).
102	**/
103	#define EFI_SE_EXT_SIGNATURE_GUID \
104	{ \
105	0xd2c18636, 0x40e5, 0x4eb5, {0xa3, 0x1b, 0x36, 0x69, 0x5f, 0xd4, 0x2c, 0x87} \
106	}
107
108	#define EFI_SHELL_MAJOR_VER 0x00000001 ///< Major version of the EFI_SHELL_ENVIRONMENT2.
109	#define EFI_SHELL_MINOR_VER 0x00000000 ///< Minor version of the EFI_SHELL_ENVIRONMENT2.
110
111	/**
112	Execute a command line.
113
114	This function will run the CommandLine. This includes loading any required images,
115	parsing any requires scripts, and if DebugOutput is TRUE printing errors
116	encountered directly to the screen.
117
118	@param[in] ParentImageHandle Handle of the image executing this operation.
119	@param[in] CommandLine The string command line to execute.
120	@param[in] DebugOutput TRUE indicates that errors should be printed directly.
121	FALSE suppresses error messages.
122
123	@retval EFI_SUCCESS The command line executed and completed.
124	@retval EFI_ABORTED The operation aborted.
125	@retval EFI_INVALID_PARAMETER A parameter did not have a valid value.
126	@retval EFI_OUT_OF_RESOURCES A required memory allocation failed.
127
128	@sa HandleProtocol
129	**/
130	typedef
131	EFI_STATUS
132	(EFIAPI *SHELLENV_EXECUTE) (
133	IN EFI_HANDLE *ParentImageHandle,
134	IN CHAR16 *CommandLine,
135	IN BOOLEAN DebugOutput
136	);
137
138	/**
139	This function returns a shell environment variable value.
140
141	@param[in] Name The pointer to the string with the shell environment
142	variable name.
143
144	@retval NULL The shell environment variable's value could not be found.
145	@retval !=NULL The value of the shell environment variable Name.
146
147	**/
148	typedef
149	CHAR16 *
150	(EFIAPI *SHELLENV_GET_ENV) (
151	IN CHAR16 *Name
152	);
153
154	/**
155	This function returns a shell environment map value.
156
157	@param[in] Name The pointer to the string with the shell environment
158	map name.
159
160	@retval NULL The shell environment map's value could not be found.
161	@retval !=NULL The value of the shell environment map Name.
162
163	**/
164	typedef
165	CHAR16 *
166	(EFIAPI *SHELLENV_GET_MAP) (
167	IN CHAR16 *Name
168	);
169
170	/**
171	This function will add an internal command to the shell interface.
172
173	This will allocate all required memory, put the new command on the command
174	list in the correct location.
175
176	@param[in] Handler The handler function to call when the command gets called.
177	@param[in] Cmd The command name.
178	@param[in] GetLineHelp The function to call of type "get help" for this command.
179
180	@retval EFI_SUCCESS The command is now part of the command list.
181	@retval EFI_OUT_OF_RESOURCES A memory allocation failed.
182	@sa SHELLENV_INTERNAL_COMMAND
183	@sa SHELLCMD_GET_LINE_HELP
184	**/
185	typedef
186	EFI_STATUS
187	(EFIAPI *SHELLENV_ADD_CMD) (
188	IN SHELLENV_INTERNAL_COMMAND Handler,
189	IN CHAR16 *Cmd,
190	IN SHELLCMD_GET_LINE_HELP GetLineHelp
191	);
192
193	/**
194	Internal interface to add protocol handlers.
195
196	This function is for internal shell use only. This is how protocol handlers are added.
197	This will get the current protocol info and add the new info or update existing info
198	and then resave the info.
199
200	@param[in] Protocol The pointer to the protocol's GUID.
201	@param[in] DumpToken The function pointer to dump token function or
202	NULL.
203	@param[in] DumpInfo The function pointer to dump infomation function
204	or NULL.
205	@param[in] IdString The English name of the protocol.
206	**/
207	typedef
208	VOID
209	(EFIAPI *SHELLENV_ADD_PROT) (
210	IN EFI_GUID *Protocol,
211	IN SHELLENV_DUMP_PROTOCOL_INFO DumpToken OPTIONAL,
212	IN SHELLENV_DUMP_PROTOCOL_INFO DumpInfo OPTIONAL,
213	IN CHAR16 *IdString
214	);
215
216	/**
217	This function finds a protocol handle by a GUID.
218
219	This function will check for already known protocols by GUID and if one is
220	found it will return the name of that protocol. If no name is found and
221	GenId is TRUE it will generate ths string.
222
223	@param[in] Protocol The GUID of the protocol to look for.
224	@param[in] GenId Whether to generate a name string if it is not found.
225
226	@return !NULL The Name of the protocol.
227	@retval NULL The Name was not found, and GenId was not TRUE.
228	**/
229	typedef
230	CHAR16*
231	(EFIAPI *SHELLENV_GET_PROT) (
232	IN EFI_GUID *Protocol,
233	IN BOOLEAN GenId
234	);
235
236	/**
237	This function returns a string array containing the current directory on
238	a given device.
239
240	If DeviceName is specified, then return the current shell directory on that
241	device. If DeviceName is NULL, then return the current directory on the
242	current device. The caller us responsible to free the returned string when
243	no longer required.
244
245	@param[in] DeviceName The name of the device to get the current
246	directory on, or NULL for current device.
247
248	@return String array with the current directory on the current or specified device.
249
250	**/
251	typedef
252	CHAR16*
253	(EFIAPI *SHELLENV_CUR_DIR) (
254	IN CHAR16 *DeviceName OPTIONAL
255	);
256
257	/**
258	This function will open a group of files that match the Arg path, including
259	support for wildcard characters ('?' and '*') in the Arg path. If there are
260	any wildcard characters in the path this function will find any and all files
261	that match the wildcards. It returns a double linked list based on the
262	LIST_ENTRY linked list structure. Use this in conjunction with the
263	SHELL_FILE_ARG_SIGNATURE to get the SHELL_FILE_ARG structures that are returned.
264	The memory allocated by the callee for this list is freed by making a call to
265	SHELLENV_FREE_FILE_LIST.
266
267	@param[in] Arg The pointer Path to files to open.
268	@param[in, out] ListHead The pointer to the allocated and initialized list head
269	upon which to append all opened file structures.
270
271	@retval EFI_SUCCESS One or more files was opened and a struct of each file's
272	information was appended to ListHead.
273	@retval EFI_OUT_OF_RESOURCES A memory allocation failed.
274	@retval EFI_NOT_FOUND No matching files could be found.
275	@sa SHELLENV_FREE_FILE_LIST
276	**/typedef
277	EFI_STATUS
278	(EFIAPI *SHELLENV_FILE_META_ARG) (
279	IN CHAR16 *Arg,
280	IN OUT LIST_ENTRY *ListHead
281	);
282
283	/**
284	This frees all of the nodes under the ListHead, but not ListHead itself.
285
286	@param[in, out] ListHead Pointer to list to free all nodes of.
287
288	@retval EFI_SUCCESS This function always returns EFI_SUCCESS.
289	**/
290	typedef
291	EFI_STATUS
292	(EFIAPI *SHELLENV_FREE_FILE_LIST) (
293	IN OUT LIST_ENTRY *ListHead
294	);
295
296	/**
297	This function creates a new instance of the ShellInterface protocol for use on
298	the ImageHandle.
299
300	This function is for internal shell usage. This will allocate and then populate
301	EFI_SHELL_INTERFACE protocol. It is the caller's responsibility to free the
302	memory.
303
304	@param[in] ImageHandle The handle which will use the new ShellInterface
305	protocol.
306
307	@return The newly allocated shell interface protocol.
308
309	**/
310	typedef
311	EFI_SHELL_INTERFACE*
312	(EFIAPI *SHELLENV_NEW_SHELL) (
313	IN EFI_HANDLE ImageHandle
314	);
315
316	/**
317	This function determines whether a script file is currently being processed.
318
319	A script file (.nsh file) can contain a series of commands and this is useful to
320	know for some shell commands whether they are being run manually or as part of a
321	script.
322
323	@retval TRUE A script file is being processed.
324	@retval FALSE A script file is not being processed.
325	**/
326	typedef
327	BOOLEAN
328	(EFIAPI *SHELLENV_BATCH_IS_ACTIVE) (
329	VOID
330	);
331
332	/**
333	This is an internal shell function to free any and all allocated resources.
334	This should be called immediately prior to closing the shell.
335	**/
336	typedef
337	VOID
338	(EFIAPI *SHELLENV_FREE_RESOURCES) (
339	VOID
340	);
341
342	/**
343	This function enables the page break mode.
344
345	This mode causes the output to pause after each complete screen to enable a
346	user to more easily read it. If AutoWrap is TRUE, then rows with too many
347	characters will be chopped and divided into 2 rows. If FALSE, then rows with
348	too many characters may not be fully visible to the user on the screen.
349
350	@param[in] StartRow The row number to start this on.
351	@param[in] AutoWrap Whether to auto wrap rows that are too long.
352	**/
353	typedef
354	VOID
355	(EFIAPI *SHELLENV_ENABLE_PAGE_BREAK) (
356	IN INT32 StartRow,
357	IN BOOLEAN AutoWrap
358	);
359
360	/**
361	This function disables the page break mode.
362
363	Disabling this causes the output to print out exactly as coded, with no breaks
364	for readability.
365	**/
366	typedef
367	VOID
368	(EFIAPI *SHELLENV_DISABLE_PAGE_BREAK) (
369	VOID
370	);
371
372	/**
373	Get the status of the page break output mode.
374
375	@retval FALSE Page break output mode is not enabled.
376	@retval TRUE Page break output mode is enabled.
377	**/
378	typedef
379	BOOLEAN
380	(EFIAPI *SHELLENV_GET_PAGE_BREAK) (
381	VOID
382	);
383
384	/**
385	This function sets the keys to filter for for the console in. The valid
386	values to set are:
387
388	#define EFI_OUTPUT_SCROLL 0x00000001
389	#define EFI_OUTPUT_PAUSE 0x00000002
390	#define EFI_EXECUTION_BREAK 0x00000004
391
392	@param[in] KeyFilter The new key filter to use.
393	**/
394	typedef
395	VOID
396	(EFIAPI *SHELLENV_SET_KEY_FILTER) (
397	IN UINT32 KeyFilter
398	);
399
400	/**
401	This function gets the keys to filter for for the console in.
402
403	The valid values to get are:
404	#define EFI_OUTPUT_SCROLL 0x00000001
405	#define EFI_OUTPUT_PAUSE 0x00000002
406	#define EFI_EXECUTION_BREAK 0x00000004
407
408	@retval The current filter mask.
409	**/
410	typedef
411	UINT32
412	(EFIAPI *SHELLENV_GET_KEY_FILTER) (
413	VOID
414	);
415
416	/**
417	This function determines if the shell application should break.
418
419	This is used to inform a shell application that a break condition has been
420	initiated. Long loops should check this to prevent delays to the break.
421
422	@retval TRUE A break has been signaled. The application
423	should exit with EFI_ABORTED as soon as possible.
424	@retval FALSE Continue as normal.
425	**/
426	typedef
427	BOOLEAN
428	(EFIAPI *SHELLENV_GET_EXECUTION_BREAK) (
429	VOID
430	);
431
432	/**
433	This is an internal shell function used to increment the shell nesting level.
434
435	**/
436	typedef
437	VOID
438	(EFIAPI *SHELLENV_INCREMENT_SHELL_NESTING_LEVEL) (
439	VOID
440	);
441
442	/**
443	This is an internal shell function used to decrement the shell nesting level.
444	**/
445	typedef
446	VOID
447	(EFIAPI *SHELLENV_DECREMENT_SHELL_NESTING_LEVEL) (
448	VOID
449	);
450
451	/**
452	This function determines if the caller is running under the root shell.
453
454	@retval TRUE The caller is running under the root shell.
455	@retval FALSE The caller is not running under the root shell.
456
457	**/
458	typedef
459	BOOLEAN
460	(EFIAPI *SHELLENV_IS_ROOT_SHELL) (
461	VOID
462	);
463
464	/**
465	Close the console proxy to restore the original console.
466
467	This is an internal shell function to handle shell cascading. It restores the
468	original set of console protocols.
469
470	@param[in] ConInHandle The handle of ConIn.
471	@param[in, out] ConIn The pointer to the location to return the pointer to
472	the original console input.
473	@param[in] ConOutHandle The handle of ConOut
474	@param[in, out] ConOut The pointer to the location to return the pointer to
475	the original console output.
476	**/
477	typedef
478	VOID
479	(EFIAPI *SHELLENV_CLOSE_CONSOLE_PROXY) (
480	IN EFI_HANDLE ConInHandle,
481	IN OUT EFI_SIMPLE_TEXT_INPUT_PROTOCOL **ConIn,
482	IN EFI_HANDLE ConOutHandle,
483	IN OUT EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL **ConOut
484	);
485
486	//
487	// declarations of handle enumerator
488	//
489	/**
490	For ease of use the shell maps handle #'s to short numbers.
491	This is only done on request for various internal commands and the references
492	are immediately freed when the internal command completes.
493	**/
494	typedef
495	VOID
496	(EFIAPI *INIT_HANDLE_ENUMERATOR) (
497	VOID
498	);
499
500	/**
501	This is an internal shell function to enumerate the handle database.
502
503	This function gets the next handle in the handle database. If no handles are
504	found, EFI_NOT_FOUND is returned. If the previous Handle was the last handle,
505	it is set to NULL before returning.
506
507	This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR.
508
509	@param[in, out] Handle The pointer to pointer to Handle. It is set
510	on a sucessful return.
511
512	@retval EFI_SUCCESS The next handle in the handle database is *Handle.
513	@retval EFI_NOT_FOUND There is not another handle.
514	**/
515	typedef
516	EFI_STATUS
517	(EFIAPI *NEXT_HANDLE) (
518	IN OUT EFI_HANDLE **Handle
519	);
520
521	/**
522	This is an internal shell function to enumerate the handle database.
523
524	This function skips the next SkipNum handles in the handle database. If there
525	are not enough handles left to skip that many EFI_ACCESS_DENIED is returned and
526	no skip is performed.
527
528	This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR.
529
530	@param[in] SkipNum How many handles to skip
531
532	@retval EFI_SUCCESS The next handle in the handle database is *Handle
533	@retval EFI_ACCESS_DENIED There are not SkipNum handles left in the database
534	**/
535	typedef
536	EFI_STATUS
537	(EFIAPI *SKIP_HANDLE) (
538	IN UINTN SkipNum
539	);
540
541	/**
542	This is an internal shell function to enumerate the handle database.
543
544	This function resets the the handle database so that NEXT_HANDLE and SKIP_HANDLE
545	will start from EnumIndex on the next call.
546
547	This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR.
548
549	@param[in] EnumIndex Where to start.
550
551	@return The number of handles either read out or skipped before this reset.
552	**/
553	typedef
554	UINTN
555	(EFIAPI *RESET_HANDLE_ENUMERATOR) (
556	IN UINTN EnumIndex
557	);
558
559	/**
560	This is an internal shell function to enumerate the handle database.
561
562	This must be called after INIT_HANDLE_ENUMERATOR.
563
564	This function releases all memory and resources associated with the handle database.
565	After this no other handle enumerator functions except INIT_HANDLE_ENUMERATOR will
566	function properly.
567	**/
568	typedef
569	VOID
570	(EFIAPI *CLOSE_HANDLE_ENUMERATOR) (
571	VOID
572	);
573
574	/**
575	This is an internal shell function to enumerate the handle database.
576
577	This function returns the number of handles in the handle database.
578
579	This must be called after INIT_HANDLE_ENUMERATOR and before CLOSE_HANDLE_ENUMERATOR.
580
581	@return The number of handles in the handle database.
582	**/
583	typedef
584	UINTN
585	(EFIAPI *GET_NUM) (
586	VOID
587	);
588
589	/**
590	Handle Enumerator structure.
591	**/
592	typedef struct {
593	INIT_HANDLE_ENUMERATOR Init; ///< The pointer to INIT_HANDLE_ENUMERATOR function.
594	NEXT_HANDLE Next; ///< The pointer to NEXT_HANDLE function.
595	SKIP_HANDLE Skip; ///< The pointer to SKIP_HANDLE function.
596	RESET_HANDLE_ENUMERATOR Reset; ///< The pointer to RESET_HANDLE_ENUMERATOR function.
597	CLOSE_HANDLE_ENUMERATOR Close; ///< The pointer to CLOSE_HANDLE_ENUMERATOR function.
598	GET_NUM GetNum; ///< The pointer to GET_NUM function.
599	} HANDLE_ENUMERATOR;
600
601	/**
602	Signature for the PROTOCOL_INFO structure.
603	**/
604	#define PROTOCOL_INFO_SIGNATURE SIGNATURE_32 ('s', 'p', 'i', 'n')
605
606	/**
607	PROTOCOL_INFO structure for protocol enumerator functions.
608	**/
609	typedef struct {
610	UINTN Signature; ///< PROTOCOL_INFO_SIGNATURE.
611	LIST_ENTRY Link; ///< Standard linked list helper member.
612	//
613	// The parsing info for the protocol.
614	//
615	EFI_GUID ProtocolId; ///< The GUID for the protocol.
616	CHAR16 *IdString; ///< The name of the protocol.
617	SHELLENV_DUMP_PROTOCOL_INFO DumpToken; ///< The pointer to DumpToken function for the protocol.
618	SHELLENV_DUMP_PROTOCOL_INFO DumpInfo; ///< The pointer to DumpInfo function for the protocol.
619	//
620	// Patabase info on which handles are supporting this protocol.
621	//
622	UINTN NoHandles; ///< The number of handles producing this protocol.
623	EFI_HANDLE *Handles; ///< The array of handles.
624
625	} PROTOCOL_INFO;
626
627	//
628	// Declarations of protocol info enumerator.
629	//
630	/**
631	This is an internal shell function to initialize the protocol enumerator.
632
633	This must be called before NEXT_PROTOCOL_INFO, SKIP_PROTOCOL_INFO,
634	RESET_PROTOCOL_INFO_ENUMERATOR, and CLOSE_PROTOCOL_INFO_ENUMERATOR are
635	called.
636	**/
637	typedef
638	VOID
639	(EFIAPI *INIT_PROTOCOL_INFO_ENUMERATOR) (
640	VOID
641	);
642
643	/**
644	This function is an internal shell function for enumeration of protocols.
645
646	This function returns the next protocol on the list. If this is called
647	immediately after initialization, it will return the first protocol on the list.
648	If this is called immediately after reset, it will return the first protocol again.
649
650	This cannot be called after CLOSE_PROTOCOL_INFO_ENUMERATOR, but it must be
651	called after INIT_PROTOCOL_INFO_ENUMERATOR.
652
653	@param[in, out] ProtocolInfo The pointer to pointer to protocol information structure.
654
655	@retval EFI_SUCCESS The next protocol's information was sucessfully returned.
656	@retval NULL There are no more protocols.
657	**/
658	typedef
659	EFI_STATUS
660	(EFIAPI *NEXT_PROTOCOL_INFO) (
661	IN OUT PROTOCOL_INFO **ProtocolInfo
662	);
663
664	/**
665	This function is an internal shell function for enumeration of protocols.
666
667	This cannot be called after CLOSE_PROTOCOL_INFO_ENUMERATOR, but it must be
668	called after INIT_PROTOCOL_INFO_ENUMERATOR.
669
670	This function does nothing and always returns EFI_SUCCESS.
671
672	@retval EFI_SUCCESS Always returned (see above).
673	**/
674	typedef
675	EFI_STATUS
676	(EFIAPI *SKIP_PROTOCOL_INFO) (
677	IN UINTN SkipNum
678	);
679
680	/**
681	This function is an internal shell function for enumeration of protocols.
682
683	This cannot be called after CLOSE_PROTOCOL_INFO_ENUMERATOR, but it must be
684	called after INIT_PROTOCOL_INFO_ENUMERATOR.
685
686	This function resets the list of protocols such that the next one in the
687	list is the begining of the list.
688	**/
689	typedef
690	VOID
691	(EFIAPI *RESET_PROTOCOL_INFO_ENUMERATOR) (
692	VOID
693	);
694
695
696	/**
697	This function is an internal shell function for enumeration of protocols.
698
699	This must be called after INIT_PROTOCOL_INFO_ENUMERATOR. After this call
700	no protocol enumerator calls except INIT_PROTOCOL_INFO_ENUMERATOR may be made.
701
702	This function frees any memory or resources associated with the protocol
703	enumerator.
704	**/
705	typedef
706	VOID
707	(EFIAPI *CLOSE_PROTOCOL_INFO_ENUMERATOR) (
708	VOID
709	);
710
711	/**
712	Protocol enumerator structure of function pointers.
713	**/
714	typedef struct {
715	INIT_PROTOCOL_INFO_ENUMERATOR Init; ///< The pointer to INIT_PROTOCOL_INFO_ENUMERATOR function.
716	NEXT_PROTOCOL_INFO Next; ///< The pointer to NEXT_PROTOCOL_INFO function.
717	SKIP_PROTOCOL_INFO Skip; ///< The pointer to SKIP_PROTOCOL_INFO function.
718	RESET_PROTOCOL_INFO_ENUMERATOR Reset; ///< The pointer to RESET_PROTOCOL_INFO_ENUMERATOR function.
719	CLOSE_PROTOCOL_INFO_ENUMERATOR Close; ///< The pointer to CLOSE_PROTOCOL_INFO_ENUMERATOR function.
720	} PROTOCOL_INFO_ENUMERATOR;
721
722	/**
723	This function is used to retrieve a user-friendly display name for a handle.
724
725	If UseComponentName is TRUE then the component name protocol for this device
726	or it's parent device (if required) will be used to obtain the name of the
727	device. If UseDevicePath is TRUE it will get the human readable device path
728	and return that. If both are TRUE it will try to use component name first
729	and device path if that fails.
730
731	It will use either ComponentName or ComponentName2 protocol, depending on
732	what is present.
733
734	This function will furthur verify whether the handle in question produced either
735	EFI_DRIVER_CONFIGRATION_PROTOCOL or EFI_DRIVER_CONFIGURATION2_PROTOCOL and also
736	whether the handle in question produced either EFI_DRIVER_DIAGNOSTICS_PROTOCOL or
737	EFI_DRIVER_DIAGNOSTICS2_PROTOCOL.
738
739	Upon successful return, the memory for *BestDeviceName is up to the caller to free.
740
741	@param[in] DeviceHandle The device handle whose name is desired.
742	@param[in] UseComponentName Whether to use the ComponentName protocol at all.
743	@param[in] UseDevicePath Whether to use the DevicePath protocol at all.
744	@param[in] Language The pointer to the language string to use.
745	@param[in, out] BestDeviceName The pointer to pointer to string allocated with the name.
746	@param[out] ConfigurationStatus The pointer to status for opening a Configuration protocol.
747	@param[out] DiagnosticsStatus The pointer to status for opening a Diagnostics protocol.
748	@param[in] Display Whether to Print this out to default Print location.
749	@param[in] Indent How many characters to indent the printing.
750
751	@retval EFI_SUCCESS This function always returns EFI_SUCCESS.
752	**/
753	typedef
754	EFI_STATUS
755	(EFIAPI *GET_DEVICE_NAME) (
756	IN EFI_HANDLE DeviceHandle,
757	IN BOOLEAN UseComponentName,
758	IN BOOLEAN UseDevicePath,
759	IN CHAR8 *Language,
760	IN OUT CHAR16 **BestDeviceName,
761	OUT EFI_STATUS *ConfigurationStatus,
762	OUT EFI_STATUS *DiagnosticsStatus,
763	IN BOOLEAN Display,
764	IN UINTN Indent
765	);
766
767	#define EFI_SHELL_COMPATIBLE_MODE_VER L"1.1.1" ///< The string for lowest version this shell supports.
768	#define EFI_SHELL_ENHANCED_MODE_VER L"1.1.2" ///< The string for highest version this shell supports.
769
770	/**
771	This function gets the shell mode as stored in the shell environment
772	"efishellmode". It will not fail.
773
774	@param[out] Mode Returns a string representing one of the
775	2 supported modes of the shell.
776
777	@retval EFI_SUCCESS This function always returns success.
778	**/
779	typedef
780	EFI_STATUS
781	(EFIAPI *GET_SHELL_MODE) (
782	OUT CHAR16 **Mode
783	);
784
785	/**
786	Convert a file system style name to a device path.
787
788	This function will convert a shell path name to a Device Path Protocol path.
789	This function will allocate any required memory for this operation and it
790	is the responsibility of the caller to free that memory when no longer required.
791
792	If anything prevents the complete conversion free any allocated memory and
793	return NULL.
794
795	@param[in] Path The path to convert.
796
797	@retval !NULL A pointer to the callee allocated Device Path.
798	@retval NULL The operation could not be completed.
799	**/
800	typedef
801	EFI_DEVICE_PATH_PROTOCOL*
802	(EFIAPI *SHELLENV_NAME_TO_PATH) (
803	IN CHAR16 *Path
804	);
805
806	/**
807	Converts a device path into a file system map name.
808
809	If DevPath is NULL, then ASSERT.
810
811	This function looks through the shell environment map for a map whose device
812	path matches the DevPath parameter. If one is found the Name is returned via
813	Name parameter. If sucessful the caller must free the memory allocated for
814	Name.
815
816	This function will use the internal lock to prevent changes to the map during
817	the lookup operation.
818
819	@param[in] DevPath The device path to search for a name for.
820	@param[in] ConsistMapping What state to verify map flag VAR_ID_CONSIST.
821	@param[out] Name On sucessful return the name of that device path.
822
823	@retval EFI_SUCCESS The DevPath was found and the name returned
824	in Name.
825	@retval EFI_OUT_OF_RESOURCES A required memory allocation failed.
826	@retval EFI_UNSUPPORTED The DevPath was not found in the map.
827	**/
828	typedef
829	EFI_STATUS
830	(EFIAPI *SHELLENV_GET_FS_NAME) (
831	IN EFI_DEVICE_PATH_PROTOCOL * DevPath,
832	IN BOOLEAN ConsistMapping,
833	OUT CHAR16 **Name
834	);
835
836	/**
837	This function will open a group of files that match the Arg path, but will not
838	support the wildcard characters ('?' and '*') in the Arg path. If there are
839	any wildcard characters in the path this function will return
840	EFI_INVALID_PARAMETER. The return is a double linked list based on the
841	LIST_ENTRY linked list structure. Use this in conjunction with the
842	SHELL_FILE_ARG_SIGNATURE to get the SHELL_FILE_ARG structures that are returned.
843	The memory allocated by the callee for this list is freed by making a call to
844	SHELLENV_FREE_FILE_LIST.
845
846	@param[in] Arg The pointer to the path of the files to be opened.
847	@param[in, out] ListHead The pointer to allocated and initialized list head
848	upon which to append all the opened file structures.
849
850	@retval EFI_SUCCESS One or more files was opened and a struct of each file's
851	information was appended to ListHead.
852	@retval EFI_OUT_OF_RESOURCES A memory allocation failed.
853	@retval EFI_NOT_FOUND No matching files could be found.
854	@sa SHELLENV_FREE_FILE_LIST
855	**/
856	typedef
857	EFI_STATUS
858	(EFIAPI *SHELLENV_FILE_META_ARG_NO_WILDCARD) (
859	IN CHAR16 *Arg,
860	IN OUT LIST_ENTRY *ListHead
861	);
862
863	/**
864	This function removes duplicate file listings from lists.
865
866	This is a function for use with SHELLENV_FILE_META_ARG_NO_WILDCARD and
867	SHELLENV_FILE_META_ARG. This function will verify that there are no duplicate
868	files in the list of returned files. Any file listed twice will have one of its
869	instances removed.
870
871	@param[in] ListHead The pointer to linked list head that was returned from
872	SHELLENV_FILE_META_ARG_NO_WILDCARD or
873	SHELLENV_FILE_META_ARG.
874
875	@retval EFI_SUCCESS This function always returns success.
876
877	**/
878	typedef
879	EFI_STATUS
880	(EFIAPI *SHELLENV_DEL_DUP_FILE) (
881	IN LIST_ENTRY * ListHead
882	);
883
884	/**
885	Converts a File System map name to a device path.
886
887	If DevPath is NULL, then ASSERT().
888
889	This function looks through the shell environment map for a map whose Name
890	matches the Name parameter. If one is found, the device path pointer is
891	updated to point to that file systems device path. The caller should not
892	free the memory from that device path.
893
894	This function will use the internal lock to prevent changes to the map during
895	the lookup operation.
896
897	@param[in] Name The pointer to the NULL terminated UNICODE string of the
898	file system name.
899	@param[out] DevPath The pointer to pointer to DevicePath. Only valid on
900	successful return.
901
902	@retval EFI_SUCCESS The conversion was successful, and the device
903	path was returned.
904	@retval EFI_NOT_FOUND The file system could not be found in the map.
905	**/
906	typedef
907	EFI_STATUS
908	(EFIAPI *SHELLENV_GET_FS_DEVICE_PATH) (
909	IN CHAR16 *Name,
910	OUT EFI_DEVICE_PATH_PROTOCOL **DevPath
911	);
912
913	/// EFI_SHELL_ENVIRONMENT2 protocol structure.
914	typedef struct {
915	SHELLENV_EXECUTE Execute;
916	SHELLENV_GET_ENV GetEnv;
917	SHELLENV_GET_MAP GetMap;
918	SHELLENV_ADD_CMD AddCmd;
919	SHELLENV_ADD_PROT AddProt;
920	SHELLENV_GET_PROT GetProt;
921	SHELLENV_CUR_DIR CurDir;
922	SHELLENV_FILE_META_ARG FileMetaArg;
923	SHELLENV_FREE_FILE_LIST FreeFileList;
924
925	//
926	// The following services are only used by the shell itself.
927	//
928	SHELLENV_NEW_SHELL NewShell;
929	SHELLENV_BATCH_IS_ACTIVE BatchIsActive;
930
931	SHELLENV_FREE_RESOURCES FreeResources;
932
933	//
934	// GUID to differentiate ShellEnvironment2 from ShellEnvironment.
935	//
936	EFI_GUID SESGuid;
937	//
938	// Major Version grows if shell environment interface has been changes.
939	//
940	UINT32 MajorVersion;
941	UINT32 MinorVersion;
942	SHELLENV_ENABLE_PAGE_BREAK EnablePageBreak;
943	SHELLENV_DISABLE_PAGE_BREAK DisablePageBreak;
944	SHELLENV_GET_PAGE_BREAK GetPageBreak;
945
946	SHELLENV_SET_KEY_FILTER SetKeyFilter;
947	SHELLENV_GET_KEY_FILTER GetKeyFilter;
948
949	SHELLENV_GET_EXECUTION_BREAK GetExecutionBreak;
950	SHELLENV_INCREMENT_SHELL_NESTING_LEVEL IncrementShellNestingLevel;
951	SHELLENV_DECREMENT_SHELL_NESTING_LEVEL DecrementShellNestingLevel;
952	SHELLENV_IS_ROOT_SHELL IsRootShell;
953
954	SHELLENV_CLOSE_CONSOLE_PROXY CloseConsoleProxy;
955	HANDLE_ENUMERATOR HandleEnumerator;
956	PROTOCOL_INFO_ENUMERATOR ProtocolInfoEnumerator;
957	GET_DEVICE_NAME GetDeviceName;
958	GET_SHELL_MODE GetShellMode;
959	SHELLENV_NAME_TO_PATH NameToPath;
960	SHELLENV_GET_FS_NAME GetFsName;
961	SHELLENV_FILE_META_ARG_NO_WILDCARD FileMetaArgNoWildCard;
962	SHELLENV_DEL_DUP_FILE DelDupFileArg;
963	SHELLENV_GET_FS_DEVICE_PATH GetFsDevicePath;
964	} EFI_SHELL_ENVIRONMENT2;
965
966	extern EFI_GUID gEfiShellEnvironment2Guid;
967	extern EFI_GUID gEfiShellEnvironment2ExtGuid;
968
969	#endif // _SHELL_ENVIRONMENT_2_PROTOCOL_H_

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

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/ShellPkg/Include/Protocol/EfiShellEnvironment2.h@ 99396

Download in other formats: