Mercurial > foo_out_sdl

comparison foosdk/sdk/foobar2000/SDK/fsitem.h @ 1:20d02a178406 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
*: check in everything else yay
author Paper <paper@tflc.us>
date Mon, 05 Jan 2026 02:15:46 -0500
parents
children
comparison
equal deleted inserted replaced
0:e9bb126753e7 1:20d02a178406
1 #pragma once
2
3 // fsItem API
4 // Alternate, object-based way of accessing the local filesystem.
5 // It is recommended to use fsItem methods to operate on user-specified media folders.
6 // In some cases, notably Android and WinPhone/UWP, accessing user's documents/media over paths requires expensive resolving of objects representing them.
7 // fsItem can cache platform specific resources necessary to manipulate the files, allowing efficient opening of files returned by directory enumeration.
8 //
9 // Note that as of 2023, fsItem is just a convenience API.
10 // WinPhone/UWP has been dropped; slow and buggy Android DocumentFile (*) wrapper is being abandoned. On neither of these platforms foobar2000 supports loading components.
11 // Nothing in current-generation foobar2000 gains performance from using fsItem methods over plain filesystem with paths.
12 //
13 // (*) Android DocumentFile is slow and buggy, not the wrapper. Google sucks.
14
15 #include "file.h"
16 #include "commonObjects.h"
17
18 namespace foobar2000_io {
19
20 namespace createMode {
21 enum {
22 failIfExists = 0,
23 allowExisting,
24 generateUniqueName
25 };
26 }
27 namespace listMode {
28 enum {
29 //! Return files
30 files = 1,
31 //! Return folders
32 folders = 2,
33 //! Return both files and flders
34 filesAndFolders = files | folders,
35 //! Return hidden files
36 hidden = 4,
37 //! Do not hand over filestats unless they come for free with folder enumeration
38 suppressStats = 8,
39 };
40 }
41
42 class fsItemBase; class fsItemFile; class fsItemFolder;
43 typedef service_ptr_t<fsItemBase> fsItemPtr;
44 typedef service_ptr_t<fsItemFile> fsItemFilePtr;
45 typedef service_ptr_t<fsItemFolder> fsItemFolderPtr;
46 class filesystem;
47
48 //! Base class for filesystem items, files or folders. All fsItemBase objects actually belong to one of the main subclasses fsItemFile or fsItemFolder.
49 class fsItemBase : public service_base {
50 FB2K_MAKE_SERVICE_INTERFACE(fsItemBase, service_base);
51 public:
52 //! Returns possibly incomplete or outdated stats that are readily available without blocking. \n
53 //! The stats may have been fetched at the the object is created (as a part of directory enumeration).
54 virtual t_filestats2 getStatsOpportunist();
55
56 //! Returns this item's canonical path.
57 virtual fb2k::stringRef canonicalPath() = 0;
58
59 //! Returns filename+extension / last path component
60 virtual fb2k::stringRef nameWithExt() = 0;
61
62
63 //! Shortened display name. By default same as nameWithExt().
64 virtual fb2k::stringRef shortName();
65
66 //! Copies this item to the specified folder. \n
67 //! If this is a folder, it will be copied recursively. \n
68 //! This may be overridden for a specific filesystem to provide an optimized version; the default implementation walks and copies files using regular file APIs.
69 virtual fsItemPtr copyTo(fsItemFolderPtr folder, const char* desiredName, unsigned createMode, abort_callback& aborter);
70 //! See copyTo(4) above. \n
71 //! Uses source item's name (last path component, filename+ext or foldername).
72 fsItemPtr copyTo(fsItemFolderPtr folder, unsigned createMode, abort_callback& aborter);
73
74 //! Moves this item to the specified folder. \n
75 //! If this is a folder, it will be moved recursively. \n
76 //! This may be overridden for a specific filesystem to provide an optimized version; the default implementation walks and moves files using regular file APIs.
77 virtual fsItemPtr moveTo(fsItemFolderPtr folder, const char* desiredName, unsigned createMode, abort_callback& aborter);
78 //! See moveTo(4) above. \n
79 //! Uses source item's name (last path component, filename+ext or foldername).
80 fsItemPtr moveTo(fsItemFolderPtr folder, unsigned createMode, abort_callback& aborter);
81
82 //! Removes this item.
83 virtual void remove(abort_callback& aborter);
84
85 //! Does represent remote object or local?
86 virtual bool isRemote() = 0;
87
88 virtual t_filestats2 getStats2(uint32_t s2flags, abort_callback& aborter) = 0;
89
90 virtual service_ptr_t<filesystem> getFS() = 0;
91
92 static fsItemBase::ptr fromPath(const char* path, abort_callback& aborter);
93
94 t_filestats getStats(abort_callback& a);
95 };
96
97 class fsItemFile : public fsItemBase {
98 FB2K_MAKE_SERVICE_INTERFACE(fsItemFile, fsItemBase);
99 public:
100 virtual file::ptr open(uint32_t openMode, abort_callback& aborter) = 0;
101
102 file::ptr openRead(abort_callback& aborter);
103 file::ptr openWriteExisting(abort_callback& aborter);
104 file::ptr openWriteNew(abort_callback& aborter);
105
106 //! Transfer this file's content and properties to another file.
107 virtual void copyToOther(fsItemFilePtr other, abort_callback& aborter);
108
109 //! Returns the file's content type, if provided by the filesystem. \n
110 //! Null if not provided by the filesystem.
111 virtual fb2k::stringRef getContentType(abort_callback&) { return nullptr; }
112
113 static fsItemFile::ptr fromPath(const char* path, abort_callback& aborter);
114
115 virtual fb2k::memBlockRef readWhole(size_t sizeSanity, abort_callback& aborter);
116 };
117
118 class fsItemFolder : public fsItemBase {
119 FB2K_MAKE_SERVICE_INTERFACE(fsItemFolder, fsItemBase);
120 public:
121 virtual fb2k::arrayRef listContents(unsigned listMode, abort_callback& aborter) = 0;
122 virtual fsItemBase::ptr findChild(const char* fileName, abort_callback& aborter) = 0;
123 virtual fsItemFile::ptr findChildFile(const char* fileName, abort_callback& aborter) = 0;
124 virtual fsItemFolder::ptr findChildFolder(const char* fileName, abort_callback& aborter) = 0;
125 virtual fsItemFile::ptr createFile(const char* fileName, unsigned createMode, abort_callback& aborter) = 0;
126 virtual fsItemFolder::ptr createFolder(const char* fileName, unsigned createMode, abort_callback& aborter) = 0;
127
128 //! Removes this folder recursively.
129 virtual void removeRecur(abort_callback& aborter);
130
131 static fsItemFolder::ptr fromPath(const char* path, abort_callback& aborter);
132 };
133
134 }