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
15namespace KIO
16{
17class 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 */
31class KIOCORE_EXPORT ListJob : public SimpleJob
32{
33 Q_OBJECT
34
35public:
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
57Q_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
106protected Q_SLOTS:
107 void slotFinished() override;
108 void slotResult(KJob *job) override;
109
110protected:
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 */
132KIOCORE_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 */
151KIOCORE_EXPORT ListJob *listRecursive(const QUrl &url, JobFlags flags = DefaultFlags, ListJob::ListFlags listFlags = ListJob::ListFlag::IncludeHidden);
152
153Q_DECLARE_OPERATORS_FOR_FLAGS(KIO::ListJob::ListFlags)
154}
155
156#endif
157

source code of kio/src/core/listjob.h