MdePkg/UefiLib: introduce EfiOpenFileByDevicePath()

[mirror_edk2.git] / MdePkg / Include / Library / UefiLib.h

diff --git a/MdePkg/Include/Library/UefiLib.h b/MdePkg/Include/Library/UefiLib.h
index 7c6fde620c742b178fa5bb89147baf49a5e7356b..f950f1c9c6485d9e53681e81e19a4b9e44254721 100644 (file)
--- a/MdePkg/Include/Library/UefiLib.h
+++ b/MdePkg/Include/Library/UefiLib.h
@@ -33,6 +33,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include <Protocol/DriverDiagnostics.h>\r
 #include <Protocol/DriverDiagnostics2.h>\r
 #include <Protocol/GraphicsOutput.h>\r
+#include <Protocol/DevicePath.h>\r
+#include <Protocol/SimpleFileSystem.h>\r
 \r
 #include <Library/BaseLib.h>\r
 \r
@@ -1520,4 +1522,90 @@ EfiLocateProtocolBuffer (
   OUT UINTN     *NoProtocols,\r
   OUT VOID      ***Buffer\r
   );\r
+\r
+/**\r
+  Open or create a file or directory, possibly creating the chain of\r
+  directories leading up to the directory.\r
+\r
+  EfiOpenFileByDevicePath() first locates EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on\r
+  FilePath, and opens the root directory of that filesystem with\r
+  EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume().\r
+\r
+  On the remaining device path, the longest initial sequence of\r
+  FILEPATH_DEVICE_PATH nodes is node-wise traversed with\r
+  EFI_FILE_PROTOCOL.Open(). For the pathname fragment specified by each\r
+  traversed FILEPATH_DEVICE_PATH node, EfiOpenFileByDevicePath() first masks\r
+  EFI_FILE_MODE_CREATE out of OpenMode, and passes 0 for Attributes. If\r
+  EFI_FILE_PROTOCOL.Open() fails, and OpenMode includes EFI_FILE_MODE_CREATE,\r
+  then the operation is retried with the caller's OpenMode and Attributes\r
+  unmodified.\r
+\r
+  (As a consequence, if OpenMode includes EFI_FILE_MODE_CREATE, and Attributes\r
+  includes EFI_FILE_DIRECTORY, and each FILEPATH_DEVICE_PATH specifies a single\r
+  pathname component, then EfiOpenFileByDevicePath() ensures that the specified\r
+  series of subdirectories exist on return.)\r
+\r
+  The EFI_FILE_PROTOCOL identified by the last FILEPATH_DEVICE_PATH node is\r
+  output to the caller; intermediate EFI_FILE_PROTOCOL instances are closed. If\r
+  there are no FILEPATH_DEVICE_PATH nodes past the node that identifies the\r
+  filesystem, then the EFI_FILE_PROTOCOL of the root directory of the\r
+  filesystem is output to the caller. If a device path node that is different\r
+  from FILEPATH_DEVICE_PATH is encountered relative to the filesystem, the\r
+  traversal is stopped with an error, and a NULL EFI_FILE_PROTOCOL is output.\r
+\r
+  @param[in,out] FilePath  On input, the device path to the file or directory\r
+                           to open or create. The caller is responsible for\r
+                           ensuring that the device path pointed-to by FilePath\r
+                           is well-formed. On output, FilePath points one past\r
+                           the last node in the original device path that has\r
+                           been successfully processed. FilePath is set on\r
+                           output even if EfiOpenFileByDevicePath() returns an\r
+                           error.\r
+\r
+  @param[out] File         On error, File is set to NULL. On success, File is\r
+                           set to the EFI_FILE_PROTOCOL of the root directory\r
+                           of the filesystem, if there are no\r
+                           FILEPATH_DEVICE_PATH nodes in FilePath; otherwise,\r
+                           File is set to the EFI_FILE_PROTOCOL identified by\r
+                           the last node in FilePath.\r
+\r
+  @param[in] OpenMode      The OpenMode parameter to pass to\r
+                           EFI_FILE_PROTOCOL.Open(). For each\r
+                           FILEPATH_DEVICE_PATH node in FilePath,\r
+                           EfiOpenFileByDevicePath() first opens the specified\r
+                           pathname fragment with EFI_FILE_MODE_CREATE masked\r
+                           out of OpenMode and with Attributes set to 0, and\r
+                           only retries the operation with EFI_FILE_MODE_CREATE\r
+                           unmasked and Attributes propagated if the first open\r
+                           attempt fails.\r
+\r
+  @param[in] Attributes    The Attributes parameter to pass to\r
+                           EFI_FILE_PROTOCOL.Open(), when EFI_FILE_MODE_CREATE\r
+                           is propagated unmasked in OpenMode.\r
+\r
+  @retval EFI_SUCCESS            The file or directory has been opened or\r
+                                 created.\r
+\r
+  @retval EFI_INVALID_PARAMETER  FilePath is NULL; or File is NULL; or FilePath\r
+                                 contains a device path node, past the node\r
+                                 that identifies\r
+                                 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL, that is not a\r
+                                 FILEPATH_DEVICE_PATH node.\r
+\r
+  @retval EFI_OUT_OF_RESOURCES   Memory allocation failed.\r
+\r
+  @return                        Error codes propagated from the\r
+                                 LocateDevicePath() and OpenProtocol() boot\r
+                                 services, and from the\r
+                                 EFI_SIMPLE_FILE_SYSTEM_PROTOCOL.OpenVolume()\r
+                                 and EFI_FILE_PROTOCOL.Open() member functions.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+EfiOpenFileByDevicePath (\r
+  IN OUT EFI_DEVICE_PATH_PROTOCOL  **FilePath,\r
+  OUT    EFI_FILE_PROTOCOL         **File,\r
+  IN     UINT64                    OpenMode,\r
+  IN     UINT64                    Attributes\r
+  );\r
 #endif\r