1 /** @file 2 EFI Shell protocol as defined in the UEFI Shell 2.0 specification including errata. 3 4 (C) Copyright 2014 Hewlett-Packard Development Company, L.P.<BR> 5 Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR> 6 This program and the accompanying materials 7 are licensed and made available under the terms and conditions of the BSD License 8 which accompanies this distribution. The full text of the license may be found at 9 http://opensource.org/licenses/bsd-license.php 10 11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 13 14 **/ 15 16 #ifndef __EFI_SHELL_PROTOCOL__ 17 #define __EFI_SHELL_PROTOCOL__ 18 19 #include <ShellBase.h> 20 #include <Guid/FileInfo.h> 21 22 #define EFI_SHELL_PROTOCOL_GUID \ 23 { \ 24 0x6302d008, 0x7f9b, 0x4f30, { 0x87, 0xac, 0x60, 0xc9, 0xfe, 0xf5, 0xda, 0x4e } \ 25 } 26 27 // replaced EFI_LIST_ENTRY with LIST_ENTRY for simplicity. 28 // they are identical outside of the name. 29 typedef struct { 30 LIST_ENTRY Link; ///< Linked list members. 31 EFI_STATUS Status; ///< Status of opening the file. Valid only if Handle != NULL. 32 CONST CHAR16 *FullName; ///< Fully qualified filename. 33 CONST CHAR16 *FileName; ///< name of this file. 34 SHELL_FILE_HANDLE Handle; ///< Handle for interacting with the opened file or NULL if closed. 35 EFI_FILE_INFO *Info; ///< Pointer to the FileInfo struct for this file or NULL. 36 } EFI_SHELL_FILE_INFO; 37 38 /** 39 Returns whether any script files are currently being processed. 40 41 @retval TRUE There is at least one script file active. 42 @retval FALSE No script files are active now. 43 44 **/ 45 typedef 46 BOOLEAN 47 (EFIAPI *EFI_SHELL_BATCH_IS_ACTIVE) ( 48 VOID 49 ); 50 51 /** 52 Closes the file handle. 53 54 This function closes a specified file handle. All 'dirty' cached file data is 55 flushed to the device, and the file is closed. In all cases, the handle is 56 closed. 57 58 @param[in] FileHandle The file handle to be closed. 59 60 @retval EFI_SUCCESS The file closed sucessfully. 61 **/ 62 typedef 63 EFI_STATUS 64 (EFIAPI *EFI_SHELL_CLOSE_FILE)( 65 IN SHELL_FILE_HANDLE FileHandle 66 ); 67 68 /** 69 Creates a file or directory by name. 70 71 This function creates an empty new file or directory with the specified attributes and 72 returns the new file's handle. If the file already exists and is read-only, then 73 EFI_INVALID_PARAMETER will be returned. 74 75 If the file already existed, it is truncated and its attributes updated. If the file is 76 created successfully, the FileHandle is the file's handle, else, the FileHandle is NULL. 77 78 If the file name begins with >v, then the file handle which is returned refers to the 79 shell environment variable with the specified name. If the shell environment variable 80 already exists and is non-volatile then EFI_INVALID_PARAMETER is returned. 81 82 @param[in] FileName Pointer to NULL-terminated file path. 83 @param[in] FileAttribs The new file's attrbiutes. The different attributes are 84 described in EFI_FILE_PROTOCOL.Open(). 85 @param[out] FileHandle On return, points to the created file handle or directory's handle. 86 87 @retval EFI_SUCCESS The file was opened. FileHandle points to the new file's handle. 88 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. 89 @retval EFI_UNSUPPORTED The file path could not be opened. 90 @retval EFI_NOT_FOUND The specified file could not be found on the device, or could not 91 file the file system on the device. 92 @retval EFI_NO_MEDIA The device has no medium. 93 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the medium is no 94 longer supported. 95 @retval EFI_DEVICE_ERROR The device reported an error or can't get the file path according 96 the DirName. 97 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 98 @retval EFI_WRITE_PROTECTED An attempt was made to create a file, or open a file for write 99 when the media is write-protected. 100 @retval EFI_ACCESS_DENIED The service denied access to the file. 101 @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the file. 102 @retval EFI_VOLUME_FULL The volume is full. 103 **/ 104 typedef 105 EFI_STATUS 106 (EFIAPI *EFI_SHELL_CREATE_FILE)( 107 IN CONST CHAR16 *FileName, 108 IN UINT64 FileAttribs, 109 OUT SHELL_FILE_HANDLE *FileHandle 110 ); 111 112 /** 113 Deletes the file specified by the file handle. 114 115 This function closes and deletes a file. In all cases, the file handle is closed. If the file 116 cannot be deleted, the warning code EFI_WARN_DELETE_FAILURE is returned, but the 117 handle is still closed. 118 119 @param[in] FileHandle The file handle to delete. 120 121 @retval EFI_SUCCESS The file was closed and deleted and the handle was closed. 122 @retval EFI_WARN_DELETE_FAILURE The handle was closed but the file was not deleted. 123 **/ 124 typedef 125 EFI_STATUS 126 (EFIAPI *EFI_SHELL_DELETE_FILE)( 127 IN SHELL_FILE_HANDLE FileHandle 128 ); 129 130 /** 131 Deletes the file specified by the file name. 132 133 This function deletes a file. 134 135 @param[in] FileName Points to the NULL-terminated file name. 136 137 @retval EFI_SUCCESS The file was deleted. 138 @retval EFI_WARN_DELETE_FAILURE The handle was closed but the file was not deleted. 139 **/ 140 typedef 141 EFI_STATUS 142 (EFIAPI *EFI_SHELL_DELETE_FILE_BY_NAME)( 143 IN CONST CHAR16 *FileName 144 ); 145 146 /** 147 Disables the page break output mode. 148 **/ 149 typedef 150 VOID 151 (EFIAPI *EFI_SHELL_DISABLE_PAGE_BREAK) ( 152 VOID 153 ); 154 155 /** 156 Enables the page break output mode. 157 **/ 158 typedef 159 VOID 160 (EFIAPI *EFI_SHELL_ENABLE_PAGE_BREAK) ( 161 VOID 162 ); 163 164 /** 165 Execute the command line. 166 167 This function creates a nested instance of the shell and executes the specified 168 command (CommandLine) with the specified environment (Environment). Upon return, 169 the status code returned by the specified command is placed in StatusCode. 170 171 If Environment is NULL, then the current environment is used and all changes made 172 by the commands executed will be reflected in the current environment. If the 173 Environment is non-NULL, then the changes made will be discarded. 174 175 The CommandLine is executed from the current working directory on the current 176 device. 177 178 @param[in] ParentImageHandle A handle of the image that is executing the specified 179 command line. 180 @param[in] CommandLine Points to the NULL-terminated UCS-2 encoded string 181 containing the command line. If NULL then the command- 182 line will be empty. 183 @param[in] Environment Points to a NULL-terminated array of environment 184 variables with the format 'x=y', where x is the 185 environment variable name and y is the value. If this 186 is NULL, then the current shell environment is used. 187 @param[out] ErrorCode Points to the status code returned by the command. 188 189 @retval EFI_SUCCESS The command executed successfully. The status code 190 returned by the command is pointed to by StatusCode. 191 @retval EFI_INVALID_PARAMETER The parameters are invalid. 192 @retval EFI_OUT_OF_RESOURCES Out of resources. 193 @retval EFI_UNSUPPORTED Nested shell invocations are not allowed. 194 **/ 195 typedef 196 EFI_STATUS 197 (EFIAPI *EFI_SHELL_EXECUTE) ( 198 IN EFI_HANDLE *ParentImageHandle, 199 IN CHAR16 *CommandLine OPTIONAL, 200 IN CHAR16 **Environment OPTIONAL, 201 OUT EFI_STATUS *StatusCode OPTIONAL 202 ); 203 204 /** 205 Find files that match a specified pattern. 206 207 This function searches for all files and directories that match the specified 208 FilePattern. The FilePattern can contain wild-card characters. The resulting file 209 information is placed in the file list FileList. 210 211 The files in the file list are not opened. The OpenMode field is set to 0 and the FileInfo 212 field is set to NULL. 213 214 @param[in] FilePattern Points to a NULL-terminated shell file path, including wildcards. 215 @param[out] FileList On return, points to the start of a file list containing the names 216 of all matching files or else points to NULL if no matching files 217 were found. 218 219 @retval EFI_SUCCESS Files found. 220 @retval EFI_NOT_FOUND No files found. 221 @retval EFI_NO_MEDIA The device has no media. 222 @retval EFI_DEVICE_ERROR The device reported an error. 223 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 224 **/ 225 typedef 226 EFI_STATUS 227 (EFIAPI *EFI_SHELL_FIND_FILES)( 228 IN CONST CHAR16 *FilePattern, 229 OUT EFI_SHELL_FILE_INFO **FileList 230 ); 231 232 /** 233 Find all files in a specified directory. 234 235 @param[in] FileDirHandle Handle of the directory to search. 236 @param[out] FileList On return, points to the list of files in the directory 237 or NULL if there are no files in the directory. 238 239 @retval EFI_SUCCESS File information was returned successfully. 240 @retval EFI_VOLUME_CORRUPTED The file system structures have been corrupted. 241 @retval EFI_DEVICE_ERROR The device reported an error. 242 @retval EFI_NO_MEDIA The device media is not present. 243 **/ 244 typedef 245 EFI_STATUS 246 (EFIAPI *EFI_SHELL_FIND_FILES_IN_DIR)( 247 IN SHELL_FILE_HANDLE FileDirHandle, 248 OUT EFI_SHELL_FILE_INFO **FileList 249 ); 250 251 /** 252 Flushes data back to a device. 253 254 This function flushes all modified data associated with a file to a device. 255 256 @param[in] FileHandle The handle of the file to flush. 257 258 @retval EFI_SUCCESS The data was flushed. 259 @retval EFI_NO_MEDIA The device has no medium. 260 @retval EFI_DEVICE_ERROR The device reported an error. 261 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 262 @retval EFI_WRITE_PROTECTED The file or medium is write-protected. 263 @retval EFI_ACCESS_DENIED The file was opened read-only. 264 @retval EFI_VOLUME_FULL The volume is full. 265 **/ 266 typedef 267 EFI_STATUS 268 (EFIAPI *EFI_SHELL_FLUSH_FILE)( 269 IN SHELL_FILE_HANDLE FileHandle 270 ); 271 272 /** 273 Frees the file list. 274 275 This function cleans up the file list and any related data structures. It has no 276 impact on the files themselves. 277 278 @param[in] FileList The file list to free. Type EFI_SHELL_FILE_INFO is 279 defined in OpenFileList(). 280 281 @retval EFI_SUCCESS Free the file list successfully. 282 **/ 283 typedef 284 EFI_STATUS 285 (EFIAPI *EFI_SHELL_FREE_FILE_LIST) ( 286 IN EFI_SHELL_FILE_INFO **FileList 287 ); 288 289 /** 290 Returns the current directory on the specified device. 291 292 If FileSystemMapping is NULL, it returns the current working directory. If the 293 FileSystemMapping is not NULL, it returns the current directory associated with the 294 FileSystemMapping. In both cases, the returned name includes the file system 295 mapping (i.e. fs0:\current-dir). 296 297 Note that the current directory string should exclude the tailing backslash character. 298 299 @param[in] FileSystemMapping A pointer to the file system mapping. If NULL, 300 then the current working directory is returned. 301 302 @retval !=NULL The current directory. 303 @retval NULL Current directory does not exist. 304 **/ 305 typedef 306 CONST CHAR16 * 307 (EFIAPI *EFI_SHELL_GET_CUR_DIR) ( 308 IN CONST CHAR16 *FileSystemMapping OPTIONAL 309 ); 310 311 typedef UINT32 EFI_SHELL_DEVICE_NAME_FLAGS; 312 #define EFI_DEVICE_NAME_USE_COMPONENT_NAME 0x00000001 313 #define EFI_DEVICE_NAME_USE_DEVICE_PATH 0x00000002 314 315 /** 316 Gets the name of the device specified by the device handle. 317 318 This function gets the user-readable name of the device specified by the device 319 handle. If no user-readable name could be generated, then *BestDeviceName will be 320 NULL and EFI_NOT_FOUND will be returned. 321 322 If EFI_DEVICE_NAME_USE_COMPONENT_NAME is set, then the function will return the 323 device's name using the EFI_COMPONENT_NAME2_PROTOCOL, if present on 324 DeviceHandle. 325 326 If EFI_DEVICE_NAME_USE_DEVICE_PATH is set, then the function will return the 327 device's name using the EFI_DEVICE_PATH_PROTOCOL, if present on DeviceHandle. 328 If both EFI_DEVICE_NAME_USE_COMPONENT_NAME and 329 EFI_DEVICE_NAME_USE_DEVICE_PATH are set, then 330 EFI_DEVICE_NAME_USE_COMPONENT_NAME will have higher priority. 331 332 @param[in] DeviceHandle The handle of the device. 333 @param[in] Flags Determines the possible sources of component names. 334 @param[in] Language A pointer to the language specified for the device 335 name, in the same format as described in the UEFI 336 specification, Appendix M. 337 @param[out] BestDeviceName On return, points to the callee-allocated NULL- 338 terminated name of the device. If no device name 339 could be found, points to NULL. The name must be 340 freed by the caller... 341 342 @retval EFI_SUCCESS Get the name successfully. 343 @retval EFI_NOT_FOUND Fail to get the device name. 344 **/ 345 typedef 346 EFI_STATUS 347 (EFIAPI *EFI_SHELL_GET_DEVICE_NAME) ( 348 IN EFI_HANDLE DeviceHandle, 349 IN EFI_SHELL_DEVICE_NAME_FLAGS Flags, 350 IN CHAR8 *Language, 351 OUT CHAR16 **BestDeviceName 352 ); 353 354 /** 355 Gets the device path from the mapping. 356 357 This function gets the device path associated with a mapping. 358 359 @param[in] Mapping A pointer to the mapping 360 361 @retval !=NULL Pointer to the device path that corresponds to the 362 device mapping. The returned pointer does not need 363 to be freed. 364 @retval NULL There is no device path associated with the 365 specified mapping. 366 **/ 367 typedef 368 CONST EFI_DEVICE_PATH_PROTOCOL * 369 (EFIAPI *EFI_SHELL_GET_DEVICE_PATH_FROM_MAP) ( 370 IN CONST CHAR16 *Mapping 371 ); 372 373 /** 374 Converts a file system style name to a device path. 375 376 This function converts a file system style name to a device path, by replacing any 377 mapping references to the associated device path. 378 379 @param[in] Path The pointer to the path. 380 381 @return The pointer of the file path. The file path is callee 382 allocated and should be freed by the caller. 383 **/ 384 typedef 385 EFI_DEVICE_PATH_PROTOCOL * 386 (EFIAPI *EFI_SHELL_GET_DEVICE_PATH_FROM_FILE_PATH) ( 387 IN CONST CHAR16 *Path 388 ); 389 390 /** 391 Gets either a single or list of environment variables. 392 393 If name is not NULL then this function returns the current value of the specified 394 environment variable. 395 396 If Name is NULL than a list of all environment variable names is returned. Each a 397 NULL terminated string with a double NULL terminating the list. 398 399 @param[in] Name A pointer to the environment variable name. If 400 Name is NULL, then the function will return all 401 of the defined shell environment variables. In 402 the case where multiple environment variables are 403 being returned, each variable will be terminated by 404 a NULL, and the list will be terminated by a double 405 NULL. 406 407 @return A pointer to the returned string. 408 The returned pointer does not need to be freed by the caller. 409 410 @retval NULL The environment variable doesn't exist or there are 411 no environment variables. 412 **/ 413 typedef 414 CONST CHAR16 * 415 (EFIAPI *EFI_SHELL_GET_ENV) ( 416 IN CONST CHAR16 *Name OPTIONAL 417 ); 418 419 /** 420 Gets the environment variable and Attributes, or list of environment variables. Can be 421 used instead of GetEnv(). 422 423 This function returns the current value of the specified environment variable and 424 the Attributes. If no variable name was specified, then all of the known 425 variables will be returned. 426 427 @param[in] Name A pointer to the environment variable name. If Name is NULL, 428 then the function will return all of the defined shell 429 environment variables. In the case where multiple environment 430 variables are being returned, each variable will be terminated 431 by a NULL, and the list will be terminated by a double NULL. 432 @param[out] Attributes If not NULL, a pointer to the returned attributes bitmask for 433 the environment variable. In the case where Name is NULL, and 434 multiple environment variables are being returned, Attributes 435 is undefined. 436 437 @retval NULL The environment variable doesn't exist. 438 @return The environment variable's value. The returned pointer does not 439 need to be freed by the caller. 440 **/ 441 typedef 442 CONST CHAR16 * 443 (EFIAPI *EFI_SHELL_GET_ENV_EX) ( 444 IN CONST CHAR16 *Name, 445 OUT UINT32 *Attributes OPTIONAL 446 ); 447 448 /** 449 Gets the file information from an open file handle. 450 451 This function allocates a buffer to store the file's information. It's the caller's 452 responsibility to free the buffer. 453 454 @param[in] FileHandle A File Handle. 455 456 @retval NULL Cannot get the file info. 457 @return A pointer to a buffer with file information. 458 **/ 459 typedef 460 EFI_FILE_INFO * 461 (EFIAPI *EFI_SHELL_GET_FILE_INFO)( 462 IN SHELL_FILE_HANDLE FileHandle 463 ); 464 465 /** 466 Converts a device path to a file system-style path. 467 468 This function converts a device path to a file system path by replacing part, or all, of 469 the device path with the file-system mapping. If there are more than one application 470 file system mappings, the one that most closely matches Path will be used. 471 472 @param[in] Path The pointer to the device path. 473 474 @return The pointer of the NULL-terminated file path. The path 475 is callee-allocated and should be freed by the caller. 476 **/ 477 typedef 478 CHAR16 * 479 (EFIAPI *EFI_SHELL_GET_FILE_PATH_FROM_DEVICE_PATH) ( 480 IN CONST EFI_DEVICE_PATH_PROTOCOL *Path 481 ); 482 483 /** 484 Gets a file's current position. 485 486 This function returns the current file position for the file handle. For directories, the 487 current file position has no meaning outside of the file system driver and as such, the 488 operation is not supported. 489 490 @param[in] FileHandle The file handle on which to get the current position. 491 @param[out] Position Byte position from the start of the file. 492 493 @retval EFI_SUCCESS Data was accessed. 494 @retval EFI_UNSUPPORTED The request is not valid on open directories. 495 **/ 496 typedef 497 EFI_STATUS 498 (EFIAPI *EFI_SHELL_GET_FILE_POSITION)( 499 IN SHELL_FILE_HANDLE FileHandle, 500 OUT UINT64 *Position 501 ); 502 503 /** 504 Gets the size of a file. 505 506 This function returns the size of the file specified by FileHandle. 507 508 @param[in] FileHandle The handle of the file. 509 @param[out] Size The size of this file. 510 511 @retval EFI_SUCCESS Get the file's size. 512 @retval EFI_DEVICE_ERROR Can't access the file. 513 **/ 514 typedef 515 EFI_STATUS 516 (EFIAPI *EFI_SHELL_GET_FILE_SIZE)( 517 IN SHELL_FILE_HANDLE FileHandle, 518 OUT UINT64 *Size 519 ); 520 521 /** 522 Get the GUID value from a human readable name. 523 524 If GuidName is a known GUID name, then update Guid to have the correct value for 525 that GUID. 526 527 This function is only available when the major and minor versions in the 528 EfiShellProtocol are greater than or equal to 2 and 1, respectively. 529 530 @param[in] GuidName A pointer to the localized name for the GUID being queried. 531 @param[out] Guid A pointer to the GUID structure to be filled in. 532 533 @retval EFI_SUCCESS The operation was successful. 534 @retval EFI_INVALID_PARAMETER Guid was NULL. 535 @retval EFI_INVALID_PARAMETER GuidName was NULL. 536 @retval EFI_NOT_FOUND GuidName is not a known GUID Name. 537 **/ 538 typedef 539 EFI_STATUS 540 (EFIAPI *EFI_SHELL_GET_GUID_FROM_NAME)( 541 IN CONST CHAR16 *GuidName, 542 OUT EFI_GUID *Guid 543 ); 544 545 /** 546 Get the human readable name for a GUID from the value. 547 548 If Guid is assigned a name, then update *GuidName to point to the name. The callee 549 should not modify the value. 550 551 This function is only available when the major and minor versions in the 552 EfiShellProtocol are greater than or equal to 2 and 1, respectively. 553 554 @param[in] Guid A pointer to the GUID being queried. 555 @param[out] GuidName A pointer to a pointer the localized to name for the GUID being requested 556 557 @retval EFI_SUCCESS The operation was successful. 558 @retval EFI_INVALID_PARAMETER Guid was NULL. 559 @retval EFI_INVALID_PARAMETER GuidName was NULL. 560 @retval EFI_NOT_FOUND Guid is not assigned a name. 561 **/ 562 typedef 563 EFI_STATUS 564 (EFIAPI *EFI_SHELL_GET_GUID_NAME)( 565 IN CONST EFI_GUID *Guid, 566 OUT CONST CHAR16 **GuidName 567 ); 568 569 /** 570 Return help information about a specific command. 571 572 This function returns the help information for the specified command. The help text 573 can be internal to the shell or can be from a UEFI Shell manual page. 574 575 If Sections is specified, then each section name listed will be compared in a casesensitive 576 manner, to the section names described in Appendix B. If the section exists, 577 it will be appended to the returned help text. If the section does not exist, no 578 information will be returned. If Sections is NULL, then all help text information 579 available will be returned. 580 581 @param[in] Command Points to the NULL-terminated UEFI Shell command name. 582 @param[in] Sections Points to the NULL-terminated comma-delimited 583 section names to return. If NULL, then all 584 sections will be returned. 585 @param[out] HelpText On return, points to a callee-allocated buffer 586 containing all specified help text. 587 588 @retval EFI_SUCCESS The help text was returned. 589 @retval EFI_OUT_OF_RESOURCES The necessary buffer could not be allocated to hold the 590 returned help text. 591 @retval EFI_INVALID_PARAMETER HelpText is NULL. 592 @retval EFI_NOT_FOUND There is no help text available for Command. 593 **/ 594 typedef 595 EFI_STATUS 596 (EFIAPI *EFI_SHELL_GET_HELP_TEXT) ( 597 IN CONST CHAR16 *Command, 598 IN CONST CHAR16 *Sections OPTIONAL, 599 OUT CHAR16 **HelpText 600 ); 601 602 /** 603 Gets the mapping(s) that most closely matches the device path. 604 605 This function gets the mapping which corresponds to the device path *DevicePath. If 606 there is no exact match, then the mapping which most closely matches *DevicePath 607 is returned, and *DevicePath is updated to point to the remaining portion of the 608 device path. If there is an exact match, the mapping is returned and *DevicePath 609 points to the end-of-device-path node. 610 611 If there are multiple map names they will be semi-colon seperated in the 612 NULL-terminated string. 613 614 @param[in, out] DevicePath On entry, points to a device path pointer. On 615 exit, updates the pointer to point to the 616 portion of the device path after the mapping. 617 618 @retval NULL No mapping was found. 619 @retval !=NULL Pointer to NULL-terminated mapping. The buffer 620 is callee allocated and should be freed by the caller. 621 **/ 622 typedef 623 CONST CHAR16 * 624 (EFIAPI *EFI_SHELL_GET_MAP_FROM_DEVICE_PATH) ( 625 IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath 626 ); 627 628 /** 629 Gets the enable status of the page break output mode. 630 631 User can use this function to determine current page break mode. 632 633 @retval TRUE The page break output mode is enabled. 634 @retval FALSE The page break output mode is disabled. 635 **/ 636 typedef 637 BOOLEAN 638 (EFIAPI *EFI_SHELL_GET_PAGE_BREAK) ( 639 VOID 640 ); 641 642 /** 643 Judges whether the active shell is the root shell. 644 645 This function makes the user to know that whether the active Shell is the root shell. 646 647 @retval TRUE The active Shell is the root Shell. 648 @retval FALSE The active Shell is NOT the root Shell. 649 **/ 650 typedef 651 BOOLEAN 652 (EFIAPI *EFI_SHELL_IS_ROOT_SHELL) ( 653 VOID 654 ); 655 656 /** 657 Opens a file or a directory by file name. 658 659 This function opens the specified file in the specified OpenMode and returns a file 660 handle. 661 If the file name begins with '>v', then the file handle which is returned refers to the 662 shell environment variable with the specified name. If the shell environment variable 663 exists, is non-volatile and the OpenMode indicates EFI_FILE_MODE_WRITE, then 664 EFI_INVALID_PARAMETER is returned. 665 666 If the file name is '>i', then the file handle which is returned refers to the standard 667 input. If the OpenMode indicates EFI_FILE_MODE_WRITE, then EFI_INVALID_PARAMETER 668 is returned. 669 670 If the file name is '>o', then the file handle which is returned refers to the standard 671 output. If the OpenMode indicates EFI_FILE_MODE_READ, then EFI_INVALID_PARAMETER 672 is returned. 673 674 If the file name is '>e', then the file handle which is returned refers to the standard 675 error. If the OpenMode indicates EFI_FILE_MODE_READ, then EFI_INVALID_PARAMETER 676 is returned. 677 678 If the file name is 'NUL', then the file handle that is returned refers to the standard NUL 679 file. If the OpenMode indicates EFI_FILE_MODE_READ, then EFI_INVALID_PARAMETER is 680 returned. 681 682 If return EFI_SUCCESS, the FileHandle is the opened file's handle, else, the 683 FileHandle is NULL. 684 685 @param[in] FileName Points to the NULL-terminated UCS-2 encoded file name. 686 @param[out] FileHandle On return, points to the file handle. 687 @param[in] OpenMode File open mode. Either EFI_FILE_MODE_READ or 688 EFI_FILE_MODE_WRITE from section 12.4 of the UEFI 689 Specification. 690 @retval EFI_SUCCESS The file was opened. FileHandle has the opened file's handle. 691 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value. FileHandle is NULL. 692 @retval EFI_UNSUPPORTED Could not open the file path. FileHandle is NULL. 693 @retval EFI_NOT_FOUND The specified file could not be found on the device or the file 694 system could not be found on the device. FileHandle is NULL. 695 @retval EFI_NO_MEDIA The device has no medium. FileHandle is NULL. 696 @retval EFI_MEDIA_CHANGED The device has a different medium in it or the medium is no 697 longer supported. FileHandle is NULL. 698 @retval EFI_DEVICE_ERROR The device reported an error or can't get the file path according 699 the FileName. FileHandle is NULL. 700 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. FileHandle is NULL. 701 @retval EFI_WRITE_PROTECTED An attempt was made to create a file, or open a file for write 702 when the media is write-protected. FileHandle is NULL. 703 @retval EFI_ACCESS_DENIED The service denied access to the file. FileHandle is NULL. 704 @retval EFI_OUT_OF_RESOURCES Not enough resources were available to open the file. FileHandle 705 is NULL. 706 @retval EFI_VOLUME_FULL The volume is full. FileHandle is NULL. 707 **/ 708 typedef 709 EFI_STATUS 710 (EFIAPI *EFI_SHELL_OPEN_FILE_BY_NAME) ( 711 IN CONST CHAR16 *FileName, 712 OUT SHELL_FILE_HANDLE *FileHandle, 713 IN UINT64 OpenMode 714 ); 715 716 /** 717 Opens the files that match the path specified. 718 719 This function opens all of the files specified by Path. Wildcards are processed 720 according to the rules specified in UEFI Shell 2.0 spec section 3.7.1. Each 721 matching file has an EFI_SHELL_FILE_INFO structure created in a linked list. 722 723 @param[in] Path A pointer to the path string. 724 @param[in] OpenMode Specifies the mode used to open each file, EFI_FILE_MODE_READ or 725 EFI_FILE_MODE_WRITE. 726 @param[in, out] FileList Points to the start of a list of files opened. 727 728 @retval EFI_SUCCESS Create the file list successfully. 729 @return Can't create the file list. 730 **/ 731 typedef 732 EFI_STATUS 733 (EFIAPI *EFI_SHELL_OPEN_FILE_LIST) ( 734 IN CHAR16 *Path, 735 IN UINT64 OpenMode, 736 IN OUT EFI_SHELL_FILE_INFO **FileList 737 ); 738 739 /** 740 Opens the root directory of a device. 741 742 This function opens the root directory of a device and returns a file handle to it. 743 744 @param[in] DevicePath Points to the device path corresponding to the device where the 745 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL is installed. 746 @param[out] FileHandle On exit, points to the file handle corresponding to the root directory on the 747 device. 748 749 @retval EFI_SUCCESS Root opened successfully. 750 @retval EFI_NOT_FOUND EFI_SIMPLE_FILE_SYSTEM could not be found or the root directory 751 could not be opened. 752 @retval EFI_VOLUME_CORRUPTED The data structures in the volume were corrupted. 753 @retval EFI_DEVICE_ERROR The device had an error. 754 **/ 755 typedef 756 EFI_STATUS 757 (EFIAPI *EFI_SHELL_OPEN_ROOT)( 758 IN EFI_DEVICE_PATH_PROTOCOL *DevicePath, 759 OUT SHELL_FILE_HANDLE *FileHandle 760 ); 761 762 /** 763 Opens the root directory of a device on a handle. 764 765 This function opens the root directory of a device and returns a file handle to it. 766 767 @param[in] DeviceHandle The handle of the device that contains the volume. 768 @param[out] FileHandle On exit, points to the file handle corresponding to the root directory on the 769 device. 770 771 @retval EFI_SUCCESS Root opened successfully. 772 @retval EFI_NOT_FOUND EFI_SIMPLE_FILE_SYSTEM could not be found or the root directory 773 could not be opened. 774 @retval EFI_VOLUME_CORRUPTED The data structures in the volume were corrupted. 775 @retval EFI_DEVICE_ERROR The device had an error. 776 **/ 777 typedef 778 EFI_STATUS 779 (EFIAPI *EFI_SHELL_OPEN_ROOT_BY_HANDLE)( 780 IN EFI_HANDLE DeviceHandle, 781 OUT SHELL_FILE_HANDLE *FileHandle 782 ); 783 784 /** 785 Reads data from the file. 786 787 If FileHandle is not a directory, the function reads the requested number of bytes 788 from the file at the file's current position and returns them in Buffer. If the read goes 789 beyond the end of the file, the read length is truncated to the end of the file. The file's 790 current position is increased by the number of bytes returned. 791 If FileHandle is a directory, then an error is returned. 792 793 @param[in] FileHandle The opened file handle for read. 794 @param[in] ReadSize On input, the size of Buffer, in bytes. On output, the amount of data read. 795 @param[in, out] Buffer The buffer in which data is read. 796 797 @retval EFI_SUCCESS Data was read. 798 @retval EFI_NO_MEDIA The device has no media. 799 @retval EFI_DEVICE_ERROR The device reported an error. 800 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 801 @retval EFI_BUFFER_TO_SMALL Buffer is too small. ReadSize contains required size. 802 **/ 803 typedef 804 EFI_STATUS 805 (EFIAPI *EFI_SHELL_READ_FILE) ( 806 IN SHELL_FILE_HANDLE FileHandle, 807 IN OUT UINTN *ReadSize, 808 IN OUT VOID *Buffer 809 ); 810 811 /** 812 Register a GUID and a localized human readable name for it. 813 814 If Guid is not assigned a name, then assign GuidName to Guid. This list of GUID 815 names must be used whenever a shell command outputs GUID information. 816 817 This function is only available when the major and minor versions in the 818 EfiShellProtocol are greater than or equal to 2 and 1, respectively. 819 820 @param[in] Guid A pointer to the GUID being registered. 821 @param[in] GuidName A pointer to the localized name for the GUID being registered. 822 823 @retval EFI_SUCCESS The operation was successful. 824 @retval EFI_INVALID_PARAMETER Guid was NULL. 825 @retval EFI_INVALID_PARAMETER GuidName was NULL. 826 @retval EFI_ACCESS_DENIED Guid already is assigned a name. 827 **/ 828 typedef 829 EFI_STATUS 830 (EFIAPI *EFI_SHELL_REGISTER_GUID_NAME)( 831 IN CONST EFI_GUID *Guid, 832 IN CONST CHAR16 *GuidName 833 ); 834 835 /** 836 Deletes the duplicate file names files in the given file list. 837 838 @param[in] FileList A pointer to the first entry in the file list. 839 840 @retval EFI_SUCCESS Always success. 841 **/ 842 typedef 843 EFI_STATUS 844 (EFIAPI *EFI_SHELL_REMOVE_DUP_IN_FILE_LIST) ( 845 IN EFI_SHELL_FILE_INFO **FileList 846 ); 847 848 /** 849 Changes a shell command alias. 850 851 This function creates an alias for a shell command. 852 853 @param[in] Command Points to the NULL-terminated shell command or existing alias. 854 @param[in] Alias Points to the NULL-terminated alias for the shell command. If this is NULL, and 855 Command refers to an alias, that alias will be deleted. 856 @param[in] Replace If TRUE and the alias already exists, then the existing alias will be replaced. If 857 FALSE and the alias already exists, then the existing alias is unchanged and 858 EFI_ACCESS_DENIED is returned. 859 @param[in] Volatile if TRUE the Alias being set will be stored in a volatile fashion. if FALSE the 860 Alias being set will be stored in a non-volatile fashion. 861 862 @retval EFI_SUCCESS Alias created or deleted successfully. 863 @retval EFI_ACCESS_DENIED The alias is a built-in alias or already existed and Replace was set to 864 FALSE. 865 **/ 866 typedef 867 EFI_STATUS 868 (EFIAPI *EFI_SHELL_SET_ALIAS)( 869 IN CONST CHAR16 *Command, 870 IN CONST CHAR16 *Alias, 871 IN BOOLEAN Replace, 872 IN BOOLEAN Volatile 873 ); 874 875 /** 876 This function returns the command associated with a alias or a list of all 877 alias'. 878 879 @param[in] Alias Points to the NULL-terminated shell alias. 880 If this parameter is NULL, then all 881 aliases will be returned in ReturnedData. 882 @param[out] Volatile Upon return of a single command if TRUE indicates 883 this is stored in a volatile fashion. FALSE otherwise. 884 @return If Alias is not NULL, it will return a pointer to 885 the NULL-terminated command for that alias. 886 If Alias is NULL, ReturnedData points to a ';' 887 delimited list of alias (e.g. 888 ReturnedData = "dir;del;copy;mfp") that is NULL-terminated. 889 @retval NULL An error ocurred. 890 @retval NULL Alias was not a valid Alias. 891 **/ 892 typedef 893 CONST CHAR16 * 894 (EFIAPI *EFI_SHELL_GET_ALIAS)( 895 IN CONST CHAR16 *Alias, 896 OUT BOOLEAN *Volatile OPTIONAL 897 ); 898 899 /** 900 Changes the current directory on the specified device. 901 902 If the FileSystem is NULL, and the directory Dir does not contain a file system's 903 mapped name, this function changes the current working directory. If FileSystem is 904 NULL and the directory Dir contains a mapped name, then the current file system and 905 the current directory on that file system are changed. 906 907 If FileSystem is not NULL, and Dir is NULL, then this changes the current working file 908 system. 909 910 If FileSystem is not NULL and Dir is not NULL, then this function changes the current 911 directory on the specified file system. 912 913 If the current working directory or the current working file system is changed then the 914 %cwd% environment variable will be updated. 915 916 @param[in] FileSystem A pointer to the file system's mapped name. If NULL, then the current working 917 directory is changed. 918 @param[in] Dir Points to the NULL-terminated directory on the device specified by FileSystem. 919 920 @retval NULL Current directory does not exist. 921 @return The current directory. 922 **/ 923 typedef 924 EFI_STATUS 925 (EFIAPI *EFI_SHELL_SET_CUR_DIR) ( 926 IN CONST CHAR16 *FileSystem OPTIONAL, 927 IN CONST CHAR16 *Dir 928 ); 929 930 /** 931 Sets the environment variable. 932 933 This function changes the current value of the specified environment variable. If the 934 environment variable exists and the Value is an empty string, then the environment 935 variable is deleted. If the environment variable exists and the Value is not an empty 936 string, then the value of the environment variable is changed. If the environment 937 variable does not exist and the Value is an empty string, there is no action. If the 938 environment variable does not exist and the Value is a non-empty string, then the 939 environment variable is created and assigned the specified value. 940 941 For a description of volatile and non-volatile environment variables, see UEFI Shell 942 2.0 specification section 3.6.1. 943 944 @param[in] Name Points to the NULL-terminated environment variable name. 945 @param[in] Value Points to the NULL-terminated environment variable value. If the value is an 946 empty string then the environment variable is deleted. 947 @param[in] Volatile Indicates whether the variable is non-volatile (FALSE) or volatile (TRUE). 948 949 @retval EFI_SUCCESS The environment variable was successfully updated. 950 **/ 951 typedef 952 EFI_STATUS 953 (EFIAPI *EFI_SHELL_SET_ENV) ( 954 IN CONST CHAR16 *Name, 955 IN CONST CHAR16 *Value, 956 IN BOOLEAN Volatile 957 ); 958 959 /** 960 Sets the file information to an opened file handle. 961 962 This function changes file information. All file information in the EFI_FILE_INFO 963 struct will be updated to the passed in data. 964 965 @param[in] FileHandle A file handle. 966 @param[in] FileInfo Points to new file information. 967 968 @retval EFI_SUCCESS The information was set. 969 @retval EFI_NO_MEDIA The device has no medium. 970 @retval EFI_DEVICE_ERROR The device reported an error. 971 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 972 @retval EFI_WRITE_PROTECTED The file or medium is write-protected. 973 @retval EFI_ACCESS_DENIED The file was opened read-only. 974 @retval EFI_VOLUME_FULL The volume is full. 975 @retval EFI_BAD_BUFFER_SIZE BufferSize is smaller than the size of EFI_FILE_INFO. 976 **/ 977 typedef 978 EFI_STATUS 979 (EFIAPI *EFI_SHELL_SET_FILE_INFO)( 980 IN SHELL_FILE_HANDLE FileHandle, 981 IN CONST EFI_FILE_INFO *FileInfo 982 ); 983 984 /** 985 Sets a file's current position. 986 987 This function sets the current file position for the handle to the position supplied. With 988 the exception of seeking to position 0xFFFFFFFFFFFFFFFF, only absolute positioning is 989 supported, and seeking past the end of the file is allowed (a subsequent write would 990 grow the file). Seeking to position 0xFFFFFFFFFFFFFFFF causes the current position 991 to be set to the end of the file. 992 993 @param[in] FileHandle The file handle on which requested position will be set. 994 @param[in] Position Byte position from the start of the file. 995 996 @retval EFI_SUCCESS Data was written. 997 @retval EFI_UNSUPPORTED The seek request for nonzero is not valid on open directories. 998 **/ 999 typedef 1000 EFI_STATUS 1001 (EFIAPI *EFI_SHELL_SET_FILE_POSITION)( 1002 IN SHELL_FILE_HANDLE FileHandle, 1003 IN UINT64 Position 1004 ); 1005 1006 /** 1007 This function creates a mapping for a device path. 1008 1009 @param[in] DevicePath Points to the device path. If this is NULL and Mapping points to a valid mapping, 1010 then the mapping will be deleted. 1011 @param[in] Mapping Points to the NULL-terminated mapping for the device path. 1012 1013 @retval EFI_SUCCESS Mapping created or deleted successfully. 1014 @retval EFI_NO_MAPPING There is no handle that corresponds exactly to DevicePath. See the 1015 boot service function LocateDevicePath(). 1016 @retval EFI_ACCESS_DENIED The mapping is a built-in alias. 1017 **/ 1018 typedef 1019 EFI_STATUS 1020 (EFIAPI *EFI_SHELL_SET_MAP)( 1021 IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, 1022 IN CONST CHAR16 *Mapping 1023 ); 1024 1025 /** 1026 Writes data to the file. 1027 1028 This function writes the specified number of bytes to the file at the current file position. 1029 The current file position is advanced the actual number of bytes written, which is 1030 returned in BufferSize. Partial writes only occur when there has been a data error 1031 during the write attempt (such as "volume space full"). The file automatically grows to 1032 hold the data, if required. 1033 1034 Direct writes to opened directories are not supported. 1035 1036 @param[in] FileHandle The opened file handle for writing. 1037 @param[in, out] BufferSize On input, size of Buffer. 1038 @param[in] Buffer The buffer in which data to write. 1039 1040 @retval EFI_SUCCESS Data was written. 1041 @retval EFI_UNSUPPORTED Writes to open directory are not supported. 1042 @retval EFI_NO_MEDIA The device has no media. 1043 @retval EFI_DEVICE_ERROR The device reported an error. 1044 @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted. 1045 @retval EFI_WRITE_PROTECTED The device is write-protected. 1046 @retval EFI_ACCESS_DENIED The file was open for read only. 1047 @retval EFI_VOLUME_FULL The volume is full. 1048 **/ 1049 typedef 1050 EFI_STATUS 1051 (EFIAPI *EFI_SHELL_WRITE_FILE)( 1052 IN SHELL_FILE_HANDLE FileHandle, 1053 IN OUT UINTN *BufferSize, 1054 IN VOID *Buffer 1055 ); 1056 1057 // 1058 // EFI_SHELL_PROTOCOL has been updated since UEFI Shell Spec 2.0 1059 // Usage of this protocol will require version checking before attempting 1060 // to use any new members. There is no need to check the version for 1061 // members that existed in UEFI Shell Spec 2.0. 1062 // 1063 // Update below for any future UEFI Shell spec changes to this protocol. 1064 // 1065 // Check EFI_SHELL_PROTOCOL MajorVersion and MinorVersion: 1066 // if ((2 == gEfiShellProtocol->MajorVersion) && 1067 // (0 == gEfiShellProtocol->MinorVersion)) { 1068 // // 1069 // // Cannot call: 1070 // // RegisterGuidName - UEFI Shell 2.1 1071 // // GetGuidName - UEFI Shell 2.1 1072 // // GetGuidFromName - UEFI Shell 2.1 1073 // // GetEnvEx - UEFI Shell 2.1 1074 // // 1075 // } else { 1076 // // 1077 // // Can use all members 1078 // // 1079 // } 1080 // 1081 typedef struct _EFI_SHELL_PROTOCOL { 1082 EFI_SHELL_EXECUTE Execute; 1083 EFI_SHELL_GET_ENV GetEnv; 1084 EFI_SHELL_SET_ENV SetEnv; 1085 EFI_SHELL_GET_ALIAS GetAlias; 1086 EFI_SHELL_SET_ALIAS SetAlias; 1087 EFI_SHELL_GET_HELP_TEXT GetHelpText; 1088 EFI_SHELL_GET_DEVICE_PATH_FROM_MAP GetDevicePathFromMap; 1089 EFI_SHELL_GET_MAP_FROM_DEVICE_PATH GetMapFromDevicePath; 1090 EFI_SHELL_GET_DEVICE_PATH_FROM_FILE_PATH GetDevicePathFromFilePath; 1091 EFI_SHELL_GET_FILE_PATH_FROM_DEVICE_PATH GetFilePathFromDevicePath; 1092 EFI_SHELL_SET_MAP SetMap; 1093 EFI_SHELL_GET_CUR_DIR GetCurDir; 1094 EFI_SHELL_SET_CUR_DIR SetCurDir; 1095 EFI_SHELL_OPEN_FILE_LIST OpenFileList; 1096 EFI_SHELL_FREE_FILE_LIST FreeFileList; 1097 EFI_SHELL_REMOVE_DUP_IN_FILE_LIST RemoveDupInFileList; 1098 EFI_SHELL_BATCH_IS_ACTIVE BatchIsActive; 1099 EFI_SHELL_IS_ROOT_SHELL IsRootShell; 1100 EFI_SHELL_ENABLE_PAGE_BREAK EnablePageBreak; 1101 EFI_SHELL_DISABLE_PAGE_BREAK DisablePageBreak; 1102 EFI_SHELL_GET_PAGE_BREAK GetPageBreak; 1103 EFI_SHELL_GET_DEVICE_NAME GetDeviceName; 1104 EFI_SHELL_GET_FILE_INFO GetFileInfo; 1105 EFI_SHELL_SET_FILE_INFO SetFileInfo; 1106 EFI_SHELL_OPEN_FILE_BY_NAME OpenFileByName; 1107 EFI_SHELL_CLOSE_FILE CloseFile; 1108 EFI_SHELL_CREATE_FILE CreateFile; 1109 EFI_SHELL_READ_FILE ReadFile; 1110 EFI_SHELL_WRITE_FILE WriteFile; 1111 EFI_SHELL_DELETE_FILE DeleteFile; 1112 EFI_SHELL_DELETE_FILE_BY_NAME DeleteFileByName; 1113 EFI_SHELL_GET_FILE_POSITION GetFilePosition; 1114 EFI_SHELL_SET_FILE_POSITION SetFilePosition; 1115 EFI_SHELL_FLUSH_FILE FlushFile; 1116 EFI_SHELL_FIND_FILES FindFiles; 1117 EFI_SHELL_FIND_FILES_IN_DIR FindFilesInDir; 1118 EFI_SHELL_GET_FILE_SIZE GetFileSize; 1119 EFI_SHELL_OPEN_ROOT OpenRoot; 1120 EFI_SHELL_OPEN_ROOT_BY_HANDLE OpenRootByHandle; 1121 EFI_EVENT ExecutionBreak; 1122 UINT32 MajorVersion; 1123 UINT32 MinorVersion; 1124 // Added for Shell 2.1 1125 EFI_SHELL_REGISTER_GUID_NAME RegisterGuidName; 1126 EFI_SHELL_GET_GUID_NAME GetGuidName; 1127 EFI_SHELL_GET_GUID_FROM_NAME GetGuidFromName; 1128 EFI_SHELL_GET_ENV_EX GetEnvEx; 1129 } EFI_SHELL_PROTOCOL; 1130 1131 extern EFI_GUID gEfiShellProtocolGuid; 1132 1133 enum ShellVersion { 1134 SHELL_MAJOR_VERSION = 2, 1135 SHELL_MINOR_VERSION = 1 1136 }; 1137 1138 #endif 1139
