fixed to build under IPF.
[mirror_edk2.git] / ShellPkg / Include / Protocol / EfiShell.h
CommitLineData
94b17fa1 1/** @file\r
2 EFI Shell protocol as defined in the UEFI Shell 2.0 specification.\r
3 \r
4 Copyright (c) 2006 - 2009, Intel Corporation \r
5 All rights reserved. This program and the accompanying materials \r
6 are licensed and made available under the terms and conditions of the BSD License \r
7 which accompanies this distribution. The full text of the license may be found at \r
8 http://opensource.org/licenses/bsd-license.php \r
9\r
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
12\r
13**/\r
14\r
15#ifndef __EFI_SHELL_PROTOCOL__\r
16#define __EFI_SHELL_PROTOCOL__\r
17\r
18#include <Protocol/SimpleFileSystem.h>\r
19#include <Guid/FileInfo.h>\r
20\r
21#define EFI_SHELL_PROTOCOL_GUID \\r
22 { \\r
23 0x6302d008, 0x7f9b, 0x4f30, { 0x87, 0xac, 0x60, 0xc9, 0xfe, 0xf5, 0xda, 0x4e } \\r
24 }\r
25\r
d2b4564b 26// replaced EFI_LIST_ENTRY with LIST_ENTRY for simplicity.\r
27// they are identical outside of the name.\r
94b17fa1 28typedef struct {\r
d2b4564b 29 LIST_ENTRY Link;\r
94b17fa1 30 EFI_STATUS Status;\r
31 CONST CHAR16 *FullName;\r
32 CONST CHAR16 *FileName;\r
33 EFI_FILE_HANDLE Handle;\r
34 EFI_FILE_INFO *Info;\r
35} EFI_SHELL_FILE_INFO;\r
36/**\r
37 Returns whether any script files are currently being processed.\r
38\r
39 @retval TRUE There is at least one script file active.\r
40 @retval FALSE No script files are active now.\r
41\r
42**/\r
43typedef\r
44BOOLEAN\r
45(EFIAPI *EFI_SHELL_BATCH_IS_ACTIVE) (\r
46 VOID\r
47 );\r
48\r
49/**\r
50 Closes the file handle.\r
51\r
52 This function closes a specified file handle. All 'dirty' cached file data is \r
53 flushed to the device, and the file is closed. In all cases, the handle is \r
54 closed.\r
55\r
56 @param FileHandle The file handle to be closed\r
57\r
58 @retval EFI_SUCCESS the file closed sucessfully\r
59**/\r
60typedef\r
61EFI_STATUS\r
62(EFIAPI *EFI_SHELL_CLOSE_FILE)(\r
63 IN EFI_FILE_HANDLE FileHandle\r
64 );\r
65\r
66/**\r
67 Creates a file or directory by name.\r
68\r
69 This function creates an empty new file or directory with the specified attributes and\r
70 returns the new file's handle. If the file already exists and is read-only, then\r
71 EFI_INVALID_PARAMETER will be returned.\r
72 \r
73 If the file already existed, it is truncated and its attributes updated. If the file is\r
74 created successfully, the FileHandle is the file's handle, else, the FileHandle is NULL.\r
75 \r
76 If the file name begins with >v, then the file handle which is returned refers to the\r
77 shell environment variable with the specified name. If the shell environment variable\r
78 already exists and is non-volatile then EFI_INVALID_PARAMETER is returned.\r
79\r
80 @param FileName Pointer to null-terminated file path\r
81 @param FileAttribs The new file's attrbiutes. the different attributes are\r
82 described in EFI_FILE_PROTOCOL.Open().\r
83 @param FileHandle On return, points to the created file handle or directory's handle\r
84\r
85 @retval EFI_SUCCESS The file was opened. FileHandle points to the new file's handle.\r
86 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.\r
87 @retval EFI_UNSUPPORTED could not open the file path\r
88 @retval EFI_NOT_FOUND the specified file could not be found on the devide, or could not\r
89 file the file system on the device.\r
90 @retval EFI_NO_MEDIA the device has no medium.\r
91 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the medium is no\r
92 longer supported.\r
93 @retval EFI_DEVICE_ERROR The device reported an error or can't get the file path according\r
94 the DirName.\r
95 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.\r
96 @retval EFI_WRITE_PROTECTED An attempt was made to create a file, or open a file for write\r
97 when the media is write-protected.\r
98 @retval EFI_ACCESS_DENIED The service denied access to the file.\r
99 @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the file.\r
100 @retval EFI_VOLUME_FULL The volume is full.\r
101**/\r
102typedef\r
103EFI_STATUS\r
104(EFIAPI *EFI_SHELL_CREATE_FILE)(\r
105 IN CONST CHAR16 *FileName,\r
106 IN UINT64 FileAttribs,\r
107 OUT EFI_FILE_HANDLE *FileHandle\r
108 );\r
109\r
110/**\r
111 Deletes the file specified by the file handle.\r
112\r
113 This function closes and deletes a file. In all cases, the file handle is closed. If the file\r
114 cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is returned, but the\r
115 handle is still closed.\r
116\r
117 @param FileHandle The file handle to delete.\r
118\r
119 @retval EFI_SUCCESS The file was closed and deleted, and the handle was closed.\r
120 @retval EFI_WARN_DELETE_FAILURE The handle was closed but the file was not deleted.\r
121**/\r
122typedef\r
123EFI_STATUS\r
124(EFIAPI *EFI_SHELL_DELETE_FILE)(\r
125 IN EFI_FILE_HANDLE FileHandle\r
126 );\r
127\r
128/**\r
129 Deletes the file specified by the file name.\r
130\r
131 This function deletes a file.\r
132\r
133 @param FileName Points to the null-terminated file name.\r
134\r
135 @retval EFI_SUCCESS The file was closed and deleted, and the handle was closed.\r
136 @retval EFI_WARN_DELETE_FAILURE The handle was closed but the file was not deleted.\r
137**/\r
138typedef\r
139EFI_STATUS\r
140(EFIAPI *EFI_SHELL_DELETE_FILE_BY_NAME)(\r
141 IN CONST CHAR16 *FileName\r
142 );\r
143\r
144/**\r
145 Disables the page break output mode.\r
146**/\r
147typedef\r
148VOID\r
149(EFIAPI *EFI_SHELL_DISABLE_PAGE_BREAK) (\r
150VOID\r
151);\r
152\r
153/**\r
154 Enables the page break output mode.\r
155**/\r
156typedef\r
157VOID\r
158(EFIAPI *EFI_SHELL_ENABLE_PAGE_BREAK) (\r
159VOID\r
160);\r
161\r
162/**\r
163 Execute the command line.\r
164\r
165 This function creates a nested instance of the shell and executes the specified\r
166 command (CommandLine) with the specified environment (Environment). Upon return,\r
167 the status code returned by the specified command is placed in StatusCode.\r
168 \r
169 If Environment is NULL, then the current environment is used and all changes made\r
170 by the commands executed will be reflected in the current environment. If the\r
171 Environment is non-NULL, then the changes made will be discarded.\r
172 \r
173 The CommandLine is executed from the current working directory on the current\r
174 device.\r
175\r
176 @param ParentImageHandle A handle of the image that is executing the specified \r
177 command line. \r
178 @param CommandLine Points to the null-terminated UCS-2 encoded string \r
179 containing the command line. If NULL then the command-\r
180 line will be empty.\r
181 @param Environment Points to a null-terminated array of environment \r
182 variables with the format 'x=y', where x is the \r
183 environment variable name and y is the value. If this\r
184 is NULL, then the current shell environment is used.\r
185 @param ErrorCode Points to the status code returned by the command.\r
186\r
187 @retval EFI_SUCCESS The command executed successfully. The status code \r
188 returned by the command is pointed to by StatusCode.\r
189 @retval EFI_INVALID_PARAMETER The parameters are invalid.\r
190 @retval EFI_OUT_OF_RESOURCES Out of resources.\r
191 @retval EFI_UNSUPPORTED Nested shell invocations are not allowed.\r
192**/\r
193typedef\r
194EFI_STATUS\r
195(EFIAPI *EFI_SHELL_EXECUTE) (\r
196 IN EFI_HANDLE *ParentImageHandle,\r
197 IN CHAR16 *CommandLine OPTIONAL,\r
198 IN CHAR16 **Environment OPTIONAL,\r
199 OUT EFI_STATUS *StatusCode OPTIONAL\r
200 );\r
201\r
202/**\r
203 Find files that match a specified pattern.\r
204\r
205 This function searches for all files and directories that match the specified\r
206 FilePattern. The FilePattern can contain wild-card characters. The resulting file\r
207 information is placed in the file list FileList.\r
208\r
209 The files in the file list are not opened. The OpenMode field is set to 0 and the FileInfo\r
210 field is set to NULL.\r
211\r
212 @param FilePattern Points to a null-terminated shell file path, including wildcards.\r
213 @param FileList On return, points to the start of a file list containing the names \r
214 of all matching files or else points to NULL if no matching files \r
215 were found.\r
216\r
217 @retval EFI_SUCCESS Files found.\r
218 @retval EFI_NOT_FOUND No files found.\r
219 @retval EFI_NO_MEDIA The device has no media\r
220 @retval EFI_DEVICE_ERROR The device reported an error\r
221 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted\r
222**/\r
223typedef\r
224EFI_STATUS\r
225(EFIAPI *EFI_SHELL_FIND_FILES)(\r
226 IN CONST CHAR16 *FilePattern,\r
227 OUT EFI_SHELL_FILE_INFO **FileList\r
228 );\r
229\r
230/**\r
231 Find all files in a specified directory.\r
232\r
233 @param FileDirHandle Handle of the directory to search.\r
234 @param FileList On return, points to the list of files in the directory \r
235 or NULL if there are no files in the directory.\r
236\r
237 @retval EFI_SUCCESS File information was returned successfully.\r
238 @retval EFI_VOLUME_CORRUPTED The file system structures have been corrupted.\r
239 @retval EFI_DEVICE_ERROR The device reported an error.\r
240 @retval EFI_NO_MEDIA The device media is not present.\r
241**/\r
242typedef\r
243EFI_STATUS\r
244(EFIAPI *EFI_SHELL_FIND_FILES_IN_DIR)(\r
245IN EFI_FILE_HANDLE FileDirHandle,\r
246OUT EFI_SHELL_FILE_INFO **FileList\r
247);\r
248\r
249/**\r
250 Flushes data back to a device\r
251 \r
252 This function flushes all modified data associated with a file to a device.\r
253\r
254 @param FileHandle The handle of the file to flush\r
255\r
256 @retval EFI_SUCCESS The data was flushed.\r
257 @retval EFI_NO_MEDIA The device has no medium.\r
258 @retval EFI_DEVICE_ERROR The device reported an error.\r
259 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.\r
260 @retval EFI_WRITE_PROTECTED The file or medium is write-protected.\r
261 @retval EFI_ACCESS_DENIED The file was opened read-only.\r
262 @retval EFI_VOLUME_FULL The volume is full.\r
263**/\r
264typedef\r
265EFI_STATUS\r
266(EFIAPI *EFI_SHELL_FLUSH_FILE)(\r
267 IN EFI_FILE_HANDLE FileHandle\r
268 );\r
269\r
270/**\r
271 Frees the file list.\r
272 \r
273 This function cleans up the file list and any related data structures. It has no\r
274 impact on the files themselves.\r
275\r
276 @param FileList The file list to free. Type EFI_SHELL_FILE_INFO is \r
277 defined in OpenFileList()\r
278\r
279 @retval EFI_SUCCESS Free the file list successfully.\r
280**/\r
281typedef\r
282EFI_STATUS\r
283(EFIAPI *EFI_SHELL_FREE_FILE_LIST) (\r
284 IN EFI_SHELL_FILE_INFO **FileList\r
285 );\r
286\r
287/**\r
288 Returns the current directory on the specified device.\r
289\r
290 If FileSystemMapping is NULL, it returns the current working directory. If the\r
291 FileSystemMapping is not NULL, it returns the current directory associated with the\r
292 FileSystemMapping. In both cases, the returned name includes the file system\r
293 mapping (i.e. fs0:\current-dir).\r
294\r
295 @param FileSystemMapping A pointer to the file system mapping. If NULL, \r
296 then the current working directory is returned.\r
297 \r
298 @retval !=NULL The current directory.\r
299 @retval NULL Current directory does not exist.\r
300**/\r
301typedef\r
302CONST CHAR16 *\r
303(EFIAPI *EFI_SHELL_GET_CUR_DIR) (\r
304 IN CONST CHAR16 *FileSystemMapping OPTIONAL\r
305 );\r
306\r
307typedef UINT32 EFI_SHELL_DEVICE_NAME_FLAGS;\r
308#define EFI_DEVICE_NAME_USE_COMPONENT_NAME 0x00000001\r
309#define EFI_DEVICE_NAME_USE_DEVICE_PATH 0x00000002\r
310/**\r
311 Gets the name of the device specified by the device handle.\r
312\r
313 This function gets the user-readable name of the device specified by the device\r
314 handle. If no user-readable name could be generated, then *BestDeviceName will be\r
315 NULL and EFI_NOT_FOUND will be returned.\r
316\r
d2b4564b 317 If EFI_DEVICE_NAME_USE_COMPONENT_NAME is set, then the function will return the\r
318