summaryrefslogtreecommitdiffstats
path: root/tdecore/ksimpledirwatch.h
blob: 4dcae30b7c41c06e2dab88cb20bae8f8c4d71998 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
/* This file is part of the KDE libraries
   Copyright (C) 1998 Sven Radej <sven@lisa.exp.univie.ac.at>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License version 2 as published by the Free Software Foundation.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
   Boston, MA 02110-1301, USA.
*/
#ifndef _KSIMPLEDIRWATCH_H
#define _KSIMPLEDIRWATCH_H

#include <tqtimer.h>
#include <tqdatetime.h>
#include <tqmap.h>

#include <tdelibs_export.h>

#define kdirwatch KSimpleDirWatch::self()

class KSimpleDirWatchPrivate;

 /**
  * KSimpleDirWatch is a basic copy of KDirWatch
  * but with the KIO linking requirement removed
  *
  * Watch directories and files for changes.
  * The watched directories or files don't have to exist yet.
  *
  * When a watched directory is changed, i.e. when files therein are
  * created or deleted, KSimpleDirWatch will emit the signal dirty().
  *
  * When a watched, but previously not existing directory gets created,
  * KSimpleDirWatch will emit the signal created().
  *
  * When a watched directory gets deleted, KSimpleDirWatch will emit the
  * signal deleted(). The directory is still watched for new
  * creation.
  *
  * When a watched file is changed, i.e. attributes changed or written
  * to, KSimpleDirWatch will emit the signal dirty().
  *
  * Scanning of particular directories or files can be stopped temporarily
  * and restarted. The whole class can be stopped and restarted.
  * Directories and files can be added/removed from the list in any state.
  *
  * The implementation uses the FAM service when available;
  * if FAM is not available, the DNOTIFY functionality is used on LINUX.
  * As a last resort, a regular polling for change of modification times
  * is done; the polling interval is a global config option:
  * DirWatch/PollInterval and DirWatch/NFSPollInterval for NFS mounted
  * directories.
  *
  * @see self()
  * @short Class for watching directory and file changes.
  * @author Sven Radej <sven@lisa.exp.univie.ac.at>
  */
class TDEIO_EXPORT KSimpleDirWatch : public TQObject
{
  Q_OBJECT
    
  public:
   /**
    * Constructor.
    *
    * Scanning begins immediately when a dir/file watch
    * is added.
    * @param parent the parent of the TQObject (or 0 for parent-less KDataTools)
    * @param name the name of the TQObject, can be 0
    */
   KSimpleDirWatch (TQObject* parent = 0, const char* name = 0);

   /**
    * Destructor.
    *
    * Stops scanning and cleans up.
    */
   ~KSimpleDirWatch();

   /**
    * Adds a directory to be watched.
    *
    * The directory does not have to exist. When @p watchFiles is
    * false (the default), the signals dirty(), created(), deleted()
    * can be emitted, all for the watched directory.
    * When @p watchFiles is true, all files in the watched directory
    * are watched for changes, too. Thus, the signals dirty(),
    * created(), deleted() can be emitted.
    *
    * @param path the path to watch
    * @param watchFiles if true, the KSimpleDirWatch will also watch files - NOT IMPLEMENTED YET
    * @param recursive if true, all sub directories are also watched - NOT IMPLEMENTED YET
    */
   void addDir(const TQString& path, 
	       bool watchFiles = false, bool recursive = false);

   /**
    * Adds a file to be watched.
    * @param file the file to watch
    */
   void addFile(const TQString& file);

   /**
    * Returns the time the directory/file was last changed.
    * @param path the file to check
    * @return the date of the last modification
    */
   TQDateTime ctime(const TQString& path);

   /**
    * Removes a directory from the list of scanned directories.
    *
    * If specified path is not in the list this does nothing.
    * @param path the path of the dir to be removed from the list
    */
   void removeDir(const TQString& path);

   /**
    * Removes a file from the list of watched files.
    *
    * If specified path is not in the list this does nothing.
    * @param file the file to be removed from the list
    */
   void removeFile(const TQString& file);

   /**
    * Stops scanning the specified path.
    *
    * The @p path is not deleted from the interal just, it is just skipped.
    * Call this function when you perform an huge operation
    * on this directory (copy/move big files or many files). When finished,
    * call restartDirScan(path).
    *
    * @param path the path to skip
    * @return true if the @p path is being watched, otherwise false
    * @see restartDirScanning()
    */
   bool stopDirScan(const TQString& path);

   /**
    * Restarts scanning for specified path.
    *
    * Resets ctime. It doesn't notify
    * the change (by emitted a signal), since the ctime value is reset.
    *
    * Call it when you are finished with big operations on that path,
    * @em and when @em you have refreshed that path. 
    *
    * @param path the path to restart scanning
    * @return true if the @p path is being watched, otherwise false
    * @see stopDirScanning()
    */
   bool restartDirScan(const TQString& path);

   /**
    * Starts scanning of all dirs in list.
    *
    * @param notify If true, all changed directories (since 
    * stopScan() call) will be notified for refresh. If notify is
    * false, all ctimes will be reset (except those who are stopped,
    * but only if @p skippedToo is false) and changed dirs won't be
    * notified. You can start scanning even if the list is
    * empty. First call should be called with @p false or else all 
    * directories 
    * in list will be notified.  
    * @param skippedToo if true, the skipped directoris (scanning of which was
    * stopped with stopDirScan() ) will be reset and notified
    * for change. Otherwise, stopped directories will continue to be
    * unnotified.
    */
   void startScan( bool notify=false, bool skippedToo=false );

   /**
    * Stops scanning of all directories in internal list.
    *
    * The timer is stopped, but the list is not cleared.
    */
   void stopScan();

   /**
    * Is scanning stopped?
    * After creation of a KSimpleDirWatch instance, this is false.
    * @return true when scanning stopped
    */
   bool isStopped() { return _isStopped; }

   /**
    * Check if a directory is being watched by this KSimpleDirWatch instance
    * @param path the directory to check
    * @return true if the directory is being watched
    */
   bool contains( const TQString& path ) const;

   /**
    * Dump statistic information about all KSimpleDirWatch instances.
    * This checks for consistency, too.
    */
   static void statistics();

   /** 
    * Emits created().
    * @param path the path of the file or directory
    */
   void setCreated( const TQString &path );
   /** 
    * Emits dirty().
    * @param path the path of the file or directory
    */
   void setDirty( const TQString &path );
   /** 
    * Emits deleted().
    * @param path the path of the file or directory
    */
   void setDeleted( const TQString &path );

   enum Method { FAM, DNotify, Stat, INotify };
   /**
    * Returns the preferred internal method to
    * watch for changes.
    * @since 3.2
    */
   Method internalMethod();

   /**
    * The KSimpleDirWatch instance usually globally used in an application.
    * It is automatically deleted when the application exits.
    *
    * However, you can create an arbitrary number of KSimpleDirWatch instances
    * aside from this one - for those you have to take care of memory management.
    *
    * This function returns an instance of KSimpleDirWatch. If there is none, it
    * will be created.
    * 
    * @return a KSimpleDirWatch instance
    */
   static KSimpleDirWatch* self();
   /**
    * Returns true if there is an instance of KSimpleDirWatch.
    * @return true if there is an instance of KSimpleDirWatch.
    * @see KSimpleDirWatch::self()
    * @since 3.1
    */
   static bool exists();

 signals:

   /**
    * Emitted when a watched object is changed.
    * For a directory this signal is emitted when files
    * therein are created or deleted.
    * For a file this signal is emitted when its size or attributes change.
    *
    * When you watch a directory, changes in the size or attributes of
    * contained files may or may not trigger this signal to be emitted
    * depending on which backend is used by KSimpleDirWatch.
    *
    * The new ctime is set before the signal is emitted.
    * @param path the path of the file or directory
    */
   void dirty (const TQString &path);

   /**
    * Emitted when a file or directory is created.
    * @param path the path of the file or directory
    */
   void created (const TQString &path );
     
   /**
    * Emitted when a file or directory is deleted.
    *
    * The object is still watched for new creation.
    * @param path the path of the file or directory
    */
   void deleted (const TQString &path );
     
 private:
   bool _isStopped;
   
   KSimpleDirWatchPrivate *d;
   static KSimpleDirWatch* s_pSelf;
};

#endif

// vim: sw=3 et