-rw-r--r-- | microkde/kio/kio/kdirwatch.h | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/microkde/kio/kio/kdirwatch.h b/microkde/kio/kio/kdirwatch.h new file mode 100644 index 0000000..bee30c2 --- a/dev/null +++ b/microkde/kio/kio/kdirwatch.h | |||
@@ -0,0 +1,288 @@ | |||
1 | /* This file is part of the KDE libraries | ||
2 | Copyright (C) 1998 Sven Radej <sven@lisa.exp.univie.ac.at> | ||
3 | |||
4 | This library is free software; you can redistribute it and/or | ||
5 | modify it under the terms of the GNU Library General Public | ||
6 | License version 2 as published by the Free Software Foundation. | ||
7 | |||
8 | This library is distributed in the hope that it will be useful, | ||
9 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
10 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
11 | Library General Public License for more details. | ||
12 | |||
13 | You should have received a copy of the GNU Library General Public License | ||
14 | along with this library; see the file COPYING.LIB. If not, write to | ||
15 | the Free Software Foundation, Inc., 59 Temple Place - Suite 330, | ||
16 | Boston, MA 02111-1307, USA. | ||
17 | */ | ||
18 | |||
19 | /* | ||
20 | Enhanced Version of the file for platform independent KDE tools. | ||
21 | Copyright (c) 2004 Ulf Schenk | ||
22 | |||
23 | $Id$ | ||
24 | */ | ||
25 | |||
26 | #ifndef _KDIRWATCH_H | ||
27 | #define _KDIRWATCH_H | ||
28 | |||
29 | #include <qtimer.h> | ||
30 | #include <qdatetime.h> | ||
31 | #include <qmap.h> | ||
32 | |||
33 | #define kdirwatch KDirWatch::self() | ||
34 | |||
35 | class KDirWatchPrivate; | ||
36 | |||
37 | /** | ||
38 | * Watch directories and files for changes. | ||
39 | * The watched directories or files don't have to exist yet. | ||
40 | * | ||
41 | * When a watched directory is changed, i.e. when files therein are | ||
42 | * created or deleted, KDirWatch will emit the signal @ref dirty(). | ||
43 | * | ||
44 | * When a watched, but previously not existing directory gets created, | ||
45 | * KDirWatch will emit the signal @ref created(). | ||
46 | * | ||
47 | * When a watched directory gets deleted, KDirWatch will emit the | ||
48 | * signal @ref deleted(). The directory is still watched for new | ||
49 | * creation. | ||
50 | * | ||
51 | * When a watched file is changed, i.e. attributes changed or written | ||
52 | * to, KDirWatch will emit the signal @ref dirty(). | ||
53 | * | ||
54 | * Scanning of particular directories or files can be stopped temporarily | ||
55 | * and restarted. The whole class can be stopped and restarted. | ||
56 | * Directories and files can be added/removed from the list in any state. | ||
57 | * | ||
58 | * The implementation uses the FAM service when available; | ||
59 | * if FAM is not available, the DNOTIFY functionality is used on LINUX. | ||
60 | * As a last resort, a regular polling for change of modification times | ||
61 | * is done; the polling interval is a global config option: | ||
62 | * DirWatch/PollInterval and DirWatch/NFSPollInterval for NFS mounted | ||
63 | * directories. | ||
64 | * | ||
65 | * @see self() | ||
66 | * @short Class for watching directory and file changes. | ||
67 | * @author Sven Radej <sven@lisa.exp.univie.ac.at> | ||
68 | */ | ||
69 | class KDirWatch : public QObject | ||
70 | { | ||
71 | Q_OBJECT | ||
72 | |||
73 | public: | ||
74 | /** | ||
75 | * Constructor. | ||
76 | * | ||
77 | * Scanning begins immediatly when a dir/file watch | ||
78 | * is added. | ||
79 | * @param parent the parent of the QObject (or 0 for parent-less KDataTools) | ||
80 | * @param name the name of the QObject, can be 0 | ||
81 | */ | ||
82 | KDirWatch (QObject* parent = 0, const char* name = 0); | ||
83 | |||
84 | /** | ||
85 | * Destructor. | ||
86 | * | ||
87 | * Stops scanning and cleans up. | ||
88 | */ | ||
89 | ~KDirWatch(); | ||
90 | |||
91 | /** | ||
92 | * Adds a directory to be watched. | ||
93 | * | ||
94 | * The directory does not have to exist. When @p watchFiles is | ||
95 | * false (the default), the signals dirty(), created(), deleted() | ||
96 | * can be emitted, all for the watched directory. | ||
97 | * When @p watchFiles is true, all files in the watched directory | ||
98 | * are watched for changes, too. Thus, the signals dirty(), | ||
99 | * created(), deleted() can be emitted. | ||
100 | * | ||
101 | * @param path the path to watch | ||
102 | * @param watchFiles if true, the KDirWatch will also watch files | ||
103 | * @param recursive if true, all sub directories are also watched | ||
104 | */ | ||
105 | void addDir(const QString& path, | ||
106 | bool watchFiles = false, bool recursive = false); | ||
107 | |||
108 | /** | ||
109 | * Adds a file to be watched. | ||
110 | * @param file the file to watch | ||
111 | */ | ||
112 | void addFile(const QString& file); | ||
113 | |||
114 | /** | ||
115 | * Returns the time the directory/file was last changed. | ||
116 | * @param file the file to check | ||
117 | * @return the date of the last modification | ||
118 | */ | ||
119 | QDateTime ctime(const QString& path); | ||
120 | |||
121 | /** | ||
122 | * Removes a directory from the list of scanned directories. | ||
123 | * | ||
124 | * If specified path is not in the list this does nothing. | ||
125 | * @param dir the path of the dir to be removed from the list | ||
126 | */ | ||
127 | void removeDir(const QString& path); | ||
128 | |||
129 | /** | ||
130 | * Removes a file from the list of watched files. | ||
131 | * | ||
132 | * If specified path is not in the list this does nothing. | ||
133 | * @param file the file to be removed from the list | ||
134 | */ | ||
135 | void removeFile(const QString& file); | ||
136 | |||
137 | /** | ||
138 | * Stops scanning the specified path. | ||
139 | * | ||
140 | * The @p path is not deleted from the interal just, it is just skipped. | ||
141 | * Call this function when you perform an huge operation | ||
142 | * on this directory (copy/move big files or many files). When finished, | ||
143 | * call @ref restartDirScan(path). | ||
144 | * | ||
145 | * @param path the path to skip | ||
146 | * @return true if the @p path is being watched, otherwise false | ||
147 | * @see restartDirScanning() | ||
148 | */ | ||
149 | bool stopDirScan(const QString& path); | ||
150 | |||
151 | /** | ||
152 | * Restarts scanning for specified path. | ||
153 | * | ||
154 | * Resets ctime. It doesn't notify | ||
155 | * the change (by emitted a signal), since the ctime value is reset. | ||
156 | * | ||
157 | * Call it when you are finished with big operations on that path, | ||
158 | * @em and when @em you have refreshed that path. | ||
159 | * | ||
160 | * @param path the path to restart scanning | ||
161 | * @return true if the @p path is being watched, otherwise false | ||
162 | * @see stopDirScanning() | ||
163 | */ | ||
164 | bool restartDirScan(const QString& path); | ||
165 | |||
166 | /** | ||
167 | * Starts scanning of all dirs in list. | ||
168 | * | ||
169 | * @param notify If true, all changed directories (since @ref | ||
170 | * stopScan() call) will be notified for refresh. If notify is | ||
171 | * false, all ctimes will be reset (except those who are stopped, | ||
172 | * but only if @p skippedToo is false) and changed dirs won't be | ||
173 | * notified. You can start scanning even if the list is | ||
174 | * empty. First call should be called with @p false or else all | ||
175 | * directories | ||
176 | * in list will be notified. | ||
177 | * @param skippedToo if true, the skipped directoris (scanning of which was | ||
178 | * stopped with @ref stopDirScan() ) will be reset and notified | ||
179 | * for change. Otherwise, stopped directories will continue to be | ||
180 | * unnotified. | ||
181 | */ | ||
182 | void startScan( bool notify=false, bool skippedToo=false ); | ||
183 | |||
184 | /** | ||
185 | * Stops scanning of all directories in internal list. | ||
186 | * | ||
187 | * The timer is stopped, but the list is not cleared. | ||
188 | */ | ||
189 | void stopScan(); | ||
190 | |||
191 | /** | ||
192 | * Is scanning stopped? | ||
193 | * After creation of a KDirWatch instance, this is false. | ||
194 | * @return true when scanning stopped | ||
195 | */ | ||
196 | bool isStopped() { return _isStopped; } | ||
197 | |||
198 | /** | ||
199 | * Check if a directory is being watched by this KDirWatch instance | ||
200 | * @param path the directory to check | ||
201 | * @return true if the directory is being watched | ||
202 | */ | ||
203 | bool contains( const QString& path ) const; | ||
204 | |||
205 | /** | ||
206 | * Dump statistic information about all KDirWatch instances. | ||
207 | * This checks for consistency, too. | ||
208 | */ | ||
209 | static void statistics(); | ||
210 | |||
211 | /** | ||
212 | * Emits @ref created(). | ||
213 | * @param path the path of the file or directory | ||
214 | */ | ||
215 | void setCreated( const QString &path ); | ||
216 | /** | ||
217 | * Emits @ref dirty(). | ||
218 | * @param path the path of the file or directory | ||
219 | */ | ||
220 | void setDirty( const QString &path ); | ||
221 | /** | ||
222 | * Emits @ref deleted(). | ||
223 | * @param path the path of the file or directory | ||
224 | */ | ||
225 | void setDeleted( const QString &path ); | ||
226 | |||
227 | /** | ||
228 | * The KDirWatch instance usually globally used in an application. | ||
229 | * It is automatically deleted when the application exits. | ||
230 | * | ||
231 | * However, you can create an arbitrary number of KDirWatch instances | ||
232 | * aside from this one - for those you have to take care of memory management. | ||
233 | * | ||
234 | * This function returns an instance of KDirWatch. If there is none, it | ||
235 | * will be created. | ||
236 | * | ||
237 | * @return a KDirWatch instance | ||
238 | */ | ||
239 | static KDirWatch* self(); | ||
240 | /** | ||
241 | * Returns true if there is an instance of KDirWatch. | ||
242 | * @return true if there is an instance of KDirWatch. | ||
243 | * @see KDirWatch::self() | ||
244 | * @since 3.1 | ||
245 | */ | ||
246 | static bool exists(); | ||
247 | |||
248 | signals: | ||
249 | |||
250 | /** | ||
251 | * Emitted when a watched object is changed. | ||
252 | * For a directory this signal is emitted when files | ||
253 | * therein are created or deleted. | ||
254 | * For a file this signal is emitted when its size or attributes change. | ||
255 | * | ||
256 | * When you watch a directory, changes in the size or attributes of | ||
257 | * contained files may or may not trigger this signal to be emitted | ||
258 | * depending on which backend is used by KDirWatch. | ||
259 | * | ||
260 | * The new ctime is set before the signal is emitted. | ||
261 | * @param path the path of the file or directory | ||
262 | */ | ||
263 | void dirty (const QString &path); | ||
264 | |||
265 | /** | ||
266 | * Emitted when a file or directory is created. | ||
267 | * @param path the path of the file or directory | ||
268 | */ | ||
269 | void created (const QString &path ); | ||
270 | |||
271 | /** | ||
272 | * Emitted when a file or directory is deleted. | ||
273 | * | ||
274 | * The object is still watched for new creation. | ||
275 | * @param path the path of the file or directory | ||
276 | */ | ||
277 | void deleted (const QString &path ); | ||
278 | |||
279 | private: | ||
280 | bool _isStopped; | ||
281 | |||
282 | KDirWatchPrivate *d; | ||
283 | static KDirWatch* s_pSelf; | ||
284 | }; | ||
285 | |||
286 | #endif | ||
287 | |||
288 | // vim: sw=3 et | ||