1 | /* |
2 | This file is part of the KDE libraries |
3 | SPDX-FileCopyrightText: 2000 Stephan Kulow <coolo@kde.org> |
4 | SPDX-FileCopyrightText: 2000-2009 David Faure <faure@kde.org> |
5 | |
6 | SPDX-License-Identifier: LGPL-2.0-or-later |
7 | */ |
8 | |
9 | #ifndef KIO_LISTJOB_H |
10 | #define KIO_LISTJOB_H |
11 | |
12 | #include "simplejob.h" |
13 | #include <kio/udsentry.h> |
14 | |
15 | namespace KIO |
16 | { |
17 | class ListJobPrivate; |
18 | /*! |
19 | * \class KIO::ListJob |
20 | * \inmodule KIOCore |
21 | * \inheaderfile KIO/ListJob |
22 | * |
23 | * \brief A ListJob is allows you to get the get the content of a directory. |
24 | * |
25 | * Don't create the job directly, but use KIO::listRecursive() or |
26 | * KIO::listDir() instead. |
27 | * |
28 | * \sa KIO::listRecursive() |
29 | * \sa KIO::listDir() |
30 | */ |
31 | class KIOCORE_EXPORT ListJob : public SimpleJob |
32 | { |
33 | Q_OBJECT |
34 | |
35 | public: |
36 | ~ListJob() override; |
37 | |
38 | /*! |
39 | * \value IncludeHidden Include hidden files in the listing. |
40 | */ |
41 | enum class ListFlag { |
42 | IncludeHidden = 1 << 0, |
43 | }; |
44 | Q_DECLARE_FLAGS(ListFlags, ListFlag) |
45 | |
46 | /*! |
47 | * Returns the ListJob's redirection URL. This will be invalid if there |
48 | * was no redirection. |
49 | */ |
50 | const QUrl &redirectionUrl() const; |
51 | |
52 | /*! |
53 | * Do not apply any KIOSK restrictions to this job. |
54 | */ |
55 | void setUnrestricted(bool unrestricted); |
56 | |
57 | Q_SIGNALS: |
58 | /*! |
59 | * This signal emits the entry found by the job while listing. |
60 | * The progress signals aren't specific to ListJob. It simply |
61 | * uses SimpleJob's processedSize (number of entries listed) and |
62 | * totalSize (total number of entries, if known), |
63 | * as well as percent. |
64 | * |
65 | * \a job the job that emitted this signal |
66 | * |
67 | * \a list the list of UDSEntries |
68 | */ |
69 | void entries(KIO::Job *job, const KIO::UDSEntryList &list); // TODO KDE5: use KIO::ListJob* argument to avoid casting |
70 | |
71 | /*! |
72 | * This signal is emitted when a sub-directory could not be listed. |
73 | * The job keeps going, thus doesn't result in an overall error. |
74 | * |
75 | * \a job the job that emitted the signal |
76 | * |
77 | * \a subJob the job listing a sub-directory, which failed. Use |
78 | * url(), error() and errorText() on that job to find |
79 | * out more. |
80 | */ |
81 | void subError(KIO::ListJob *job, KIO::ListJob *subJob); |
82 | |
83 | /*! |
84 | * Signals a redirection. |
85 | * Use to update the URL shown to the user. |
86 | * The redirection itself is handled internally. |
87 | * |
88 | * \a job the job that is redirected |
89 | * |
90 | * \a url the new url |
91 | */ |
92 | void redirection(KIO::Job *job, const QUrl &url); |
93 | |
94 | /*! |
95 | * Signals a permanent redirection. |
96 | * The redirection itself is handled internally. |
97 | * |
98 | * \a job the job that emitted this signal |
99 | * |
100 | * \a fromUrl the original URL |
101 | * |
102 | * \a toUrl the new URL |
103 | */ |
104 | void permanentRedirection(KIO::Job *job, const QUrl &fromUrl, const QUrl &toUrl); |
105 | |
106 | protected Q_SLOTS: |
107 | void slotFinished() override; |
108 | void slotResult(KJob *job) override; |
109 | |
110 | protected: |
111 | KIOCORE_NO_EXPORT explicit ListJob(ListJobPrivate &dd); |
112 | |
113 | Q_DECLARE_PRIVATE(ListJob) |
114 | friend class ListJobPrivate; |
115 | }; |
116 | |
117 | /*! |
118 | * \relates KIO::ListJob |
119 | * |
120 | * List the contents of \a url, which is assumed to be a directory. |
121 | * |
122 | * "." and ".." are returned, filter them out if you don't want them. |
123 | * |
124 | * \a url the url of the directory |
125 | * |
126 | * \a flags Can be HideProgressInfo here |
127 | * |
128 | * \a listFlags Can be used to control whether hidden files are included |
129 | * |
130 | * Returns the job handling the operation. |
131 | */ |
132 | KIOCORE_EXPORT ListJob *listDir(const QUrl &url, JobFlags flags = DefaultFlags, ListJob::ListFlags listFlags = ListJob::ListFlag::IncludeHidden); |
133 | |
134 | /*! |
135 | * \relates KIO::ListJob |
136 | * |
137 | * The same as the previous method, but recurses subdirectories. |
138 | * Directory links are not followed. |
139 | * |
140 | * "." and ".." are returned but only for the toplevel directory. |
141 | * Filter them out if you don't want them. |
142 | * |
143 | * \a url the url of the directory |
144 | * |
145 | * \a flags Can be HideProgressInfo here |
146 | * |
147 | * \a listFlags Can be used to control whether hidden files are included |
148 | * |
149 | * Returns the job handling the operation. |
150 | */ |
151 | KIOCORE_EXPORT ListJob *listRecursive(const QUrl &url, JobFlags flags = DefaultFlags, ListJob::ListFlags listFlags = ListJob::ListFlag::IncludeHidden); |
152 | |
153 | Q_DECLARE_OPERATORS_FOR_FLAGS(KIO::ListJob::ListFlags) |
154 | } |
155 | |
156 | #endif |
157 | |