ShellPkg/ShellCommandLib: add ShellSortFileList()

[mirror_edk2.git] / ShellPkg / Include / Library / ShellCommandLib.h

diff --git a/ShellPkg/Include/Library/ShellCommandLib.h b/ShellPkg/Include/Library/ShellCommandLib.h
index 63fcac82a2de2a387acdeee92db5188ccff6d056..bc1afed5e7f53e9a1cb985611818ee932645dbb1 100644 (file)
--- a/ShellPkg/Include/Library/ShellCommandLib.h
+++ b/ShellPkg/Include/Library/ShellCommandLib.h
@@ -714,4 +714,85 @@ CatSDumpHex (
   IN UINTN   DataSize,\r
   IN VOID    *UserData\r
   );\r
+\r
+//\r
+// Determines the ordering operation for ShellSortFileList().\r
+//\r
+typedef enum {\r
+  //\r
+  // Sort the EFI_SHELL_FILE_INFO objects by the FileName field, in increasing\r
+  // order, using gUnicodeCollation->StriColl().\r
+  //\r
+  ShellSortFileListByFileName,\r
+  //\r
+  // Sort the EFI_SHELL_FILE_INFO objects by the FullName field, in increasing\r
+  // order, using gUnicodeCollation->StriColl().\r
+  //\r
+  ShellSortFileListByFullName,\r
+  ShellSortFileListMax\r
+} SHELL_SORT_FILE_LIST;\r
+\r
+/**\r
+  Sort an EFI_SHELL_FILE_INFO list, optionally moving duplicates to a separate\r
+  list.\r
+\r
+  @param[in,out] FileList  The list of EFI_SHELL_FILE_INFO objects to sort.\r
+\r
+                           If FileList is NULL on input, then FileList is\r
+                           considered an empty, hence already sorted, list.\r
+\r
+                           Otherwise, if (*FileList) is NULL on input, then\r
+                           EFI_INVALID_PARAMETER is returned.\r
+\r
+                           Otherwise, the caller is responsible for having\r
+                           initialized (*FileList)->Link with\r
+                           InitializeListHead(). No other fields in the\r
+                           (**FileList) head element are accessed by this\r
+                           function.\r
+\r
+                           On output, (*FileList) is sorted according to Order.\r
+                           If Duplicates is NULL on input, then duplicate\r
+                           elements are preserved, sorted stably, on\r
+                           (*FileList). If Duplicates is not NULL on input,\r
+                           then duplicates are moved (stably sorted) to the\r
+                           new, dynamically allocated (*Duplicates) list.\r
+\r
+  @param[out] Duplicates   If Duplicates is NULL on input, (*FileList) will be\r
+                           a monotonically ordered list on output, with\r
+                           duplicates stably sorted.\r
+\r
+                           If Duplicates is not NULL on input, (*FileList) will\r
+                           be a strictly monotonically oredered list on output,\r
+                           with duplicates separated (stably sorted) to\r
+                           (*Duplicates). All fields except Link will be\r
+                           zero-initialized in the (**Duplicates) head element.\r
+                           If no duplicates exist, then (*Duplicates) is set to\r
+                           NULL on output.\r
+\r
+  @param[in] Order         Determines the comparison operation between\r
+                           EFI_SHELL_FILE_INFO objects.\r
+\r
+  @retval EFI_INVALID_PARAMETER  (UINTN)Order is greater than or equal to\r
+                                 (UINTN)ShellSortFileListMax. Neither the\r
+                                 (*FileList) nor the (*Duplicates) list has\r
+                                 been modified.\r
+\r
+  @retval EFI_INVALID_PARAMETER  (*FileList) was NULL on input. Neither the\r
+                                 (*FileList) nor the (*Duplicates) list has\r
+                                 been modified.\r
+\r
+  @retval EFI_OUT_OF_RESOURCES   Memory allocation failed. Neither the\r
+                                 (*FileList) nor the (*Duplicates) list has\r
+                                 been modified.\r
+\r
+  @retval EFI_SUCCESS            Sorting successful, including the case when\r
+                                 FileList is NULL on input.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+ShellSortFileList (\r
+  IN OUT EFI_SHELL_FILE_INFO  **FileList,\r
+     OUT EFI_SHELL_FILE_INFO  **Duplicates OPTIONAL,\r
+  IN     SHELL_SORT_FILE_LIST Order\r
+  );\r
 #endif //_SHELL_COMMAND_LIB_\r