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 listjob.h <KIO/ListJob>
20 *
21 * A ListJob is allows you to get the get the content of a directory.
22 * Don't create the job directly, but use KIO::listRecursive() or
23 * KIO::listDir() instead.
24 * @see KIO::listRecursive()
25 * @see KIO::listDir()
26 */
27class KIOCORE_EXPORT ListJob : public SimpleJob
28{
29 Q_OBJECT
30
31public:
32 ~ListJob() override;
33
34 enum class ListFlag {
35 IncludeHidden = 1 << 0, ///< Include hidden files in the listing.
36 };
37 Q_DECLARE_FLAGS(ListFlags, ListFlag)
38
39 /**
40 * Returns the ListJob's redirection URL. This will be invalid if there
41 * was no redirection.
42 * @return the redirection url
43 */
44 const QUrl &redirectionUrl() const;
45
46 /**
47 * Do not apply any KIOSK restrictions to this job.
48 */
49 void setUnrestricted(bool unrestricted);
50
51Q_SIGNALS:
52 /**
53 * This signal emits the entry found by the job while listing.
54 * The progress signals aren't specific to ListJob. It simply
55 * uses SimpleJob's processedSize (number of entries listed) and
56 * totalSize (total number of entries, if known),
57 * as well as percent.
58 * @param job the job that emitted this signal
59 * @param list the list of UDSEntries
60 */
61 void entries(KIO::Job *job, const KIO::UDSEntryList &list); // TODO KDE5: use KIO::ListJob* argument to avoid casting
62
63 /**
64 * This signal is emitted when a sub-directory could not be listed.
65 * The job keeps going, thus doesn't result in an overall error.
66 * @param job the job that emitted the signal
67 * @param subJob the job listing a sub-directory, which failed. Use
68 * url(), error() and errorText() on that job to find
69 * out more.
70 */
71 void subError(KIO::ListJob *job, KIO::ListJob *subJob);
72
73 /**
74 * Signals a redirection.
75 * Use to update the URL shown to the user.
76 * The redirection itself is handled internally.
77 * @param job the job that is redirected
78 * @param url the new url
79 */
80 void redirection(KIO::Job *job, const QUrl &url);
81
82 /**
83 * Signals a permanent redirection.
84 * The redirection itself is handled internally.
85 * @param job the job that emitted this signal
86 * @param fromUrl the original URL
87 * @param toUrl the new URL
88 */
89 void permanentRedirection(KIO::Job *job, const QUrl &fromUrl, const QUrl &toUrl);
90
91protected Q_SLOTS:
92 void slotFinished() override;
93 void slotResult(KJob *job) override;
94
95protected:
96 KIOCORE_NO_EXPORT explicit ListJob(ListJobPrivate &dd);
97
98 Q_DECLARE_PRIVATE(ListJob)
99 friend class ListJobPrivate;
100};
101
102/**
103 * List the contents of @p url, which is assumed to be a directory.
104 *
105 * "." and ".." are returned, filter them out if you don't want them.
106 *
107 *
108 * @param url the url of the directory
109 * @param flags Can be HideProgressInfo here
110 * @param includeHidden true for all files, false to cull out UNIX hidden
111 * files/dirs (whose names start with dot)
112 * @return the job handling the operation.
113 */
114KIOCORE_EXPORT ListJob *listDir(const QUrl &url, JobFlags flags = DefaultFlags, ListJob::ListFlags listFlags = ListJob::ListFlag::IncludeHidden);
115
116/**
117 * The same as the previous method, but recurses subdirectories.
118 * Directory links are not followed.
119 *
120 * "." and ".." are returned but only for the toplevel directory.
121 * Filter them out if you don't want them.
122 *
123 * @param url the url of the directory
124 * @param flags Can be HideProgressInfo here
125 * @param includeHidden true for all files, false to cull out UNIX hidden
126 * files/dirs (whose names start with dot)
127 * @return the job handling the operation.
128 */
129KIOCORE_EXPORT ListJob *listRecursive(const QUrl &url, JobFlags flags = DefaultFlags, ListJob::ListFlags listFlags = ListJob::ListFlag::IncludeHidden);
130
131Q_DECLARE_OPERATORS_FOR_FLAGS(KIO::ListJob::ListFlags)
132}
133
134#endif
135

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