diff options
Diffstat (limited to 'tdeio/tdeio/kdirwatch.h')
| -rw-r--r-- | tdeio/tdeio/kdirwatch.h | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/tdeio/tdeio/kdirwatch.h b/tdeio/tdeio/kdirwatch.h new file mode 100644 index 000000000..4abaa302e --- /dev/null +++ b/tdeio/tdeio/kdirwatch.h @@ -0,0 +1,290 @@ +/* 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 _KDIRWATCH_H +#define _KDIRWATCH_H + +#include <tqtimer.h> +#include <tqdatetime.h> +#include <tqmap.h> + +#include <tdelibs_export.h> + +#define kdirwatch KDirWatch::self() + +class KDirWatchPrivate; + + /** + * 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, KDirWatch will emit the signal dirty(). + * + * When a watched, but previously not existing directory gets created, + * KDirWatch will emit the signal created(). + * + * When a watched directory gets deleted, KDirWatch 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, KDirWatch 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 KDirWatch : 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 + */ + KDirWatch (TQObject* parent = 0, const char* name = 0); + + /** + * Destructor. + * + * Stops scanning and cleans up. + */ + ~KDirWatch(); + + /** + * 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 KDirWatch 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 KDirWatch instance, this is false. + * @return true when scanning stopped + */ + bool isStopped() { return _isStopped; } + + /** + * Check if a directory is being watched by this KDirWatch 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 KDirWatch 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 KDirWatch instance usually globally used in an application. + * It is automatically deleted when the application exits. + * + * However, you can create an arbitrary number of KDirWatch instances + * aside from this one - for those you have to take care of memory management. + * + * This function returns an instance of KDirWatch. If there is none, it + * will be created. + * + * @return a KDirWatch instance + */ + static KDirWatch* self(); + /** + * Returns true if there is an instance of KDirWatch. + * @return true if there is an instance of KDirWatch. + * @see KDirWatch::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 KDirWatch. + * + * 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; + + KDirWatchPrivate *d; + static KDirWatch* s_pSelf; +}; + +#endif + +// vim: sw=3 et |