kio Library API Documentation

KDirWatch Class Reference

Watch directories and files for changes. Class for watching directory and file changes. More...

#include <kdirwatch.h>

Inheritance diagram for KDirWatch:

QObject List of all members.

Signals

void dirty (const QString &path)
void created (const QString &path)
void deleted (const QString &path)

Public Methods

 KDirWatch (QObject *parent=0, const char *name=0)
 ~KDirWatch ()
void addDir (const QString &path, bool watchFiles=false, bool recursive=false)
void addFile (const QString &file)
QDateTime ctime (const QString &path)
void removeDir (const QString &path)
void removeFile (const QString &file)
bool stopDirScan (const QString &path)
bool restartDirScan (const QString &path)
void startScan (bool notify=false, bool skippedToo=false)
void stopScan ()
bool isStopped ()
bool contains (const QString &path) const
void setCreated (const QString &path)
void setDirty (const QString &path)
void setDeleted (const QString &path)
Method internalMethod ()

Static Public Methods

void statistics ()
KDirWatch * self ()
bool exists ()

Detailed Description

Watch directories and files for changes. Class for watching directory and file 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 also:
self()
Author:
Sven Radej <sven@lisa.exp.univie.ac.at>

Definition at line 61 of file kdirwatch.h.


Constructor & Destructor Documentation

KDirWatch::KDirWatch QObject   parent = 0,
const char *    name = 0
 

Constructor.

Scanning begins immediately when a dir/file watch is added.

Parameters:
parent  the parent of the QObject (or 0 for parent-less KDataTools)
name  the name of the QObject, can be 0

Definition at line 1296 of file kdirwatch.cpp.

References QObject::name(), and QObject::setName().

KDirWatch::~KDirWatch  
 

Destructor.

Stops scanning and cleans up.

Definition at line 1314 of file kdirwatch.cpp.


Member Function Documentation

void KDirWatch::addDir const QString   path,
bool    watchFiles = false,
bool    recursive = false
 

Adds a directory to be watched.

The directory does not have to exist. When watchFiles is false (the default), the signals dirty(), created(), deleted() can be emitted, all for the watched directory. When watchFiles is true, all files in the watched directory are watched for changes, too. Thus, the signals dirty(), created(), deleted() can be emitted.

Parameters:
path  the path to watch
watchFiles  if true, the KDirWatch will also watch files
recursive  if true, all sub directories are also watched

Definition at line 1327 of file kdirwatch.cpp.

void KDirWatch::addFile const QString   file
 

Adds a file to be watched.

Parameters:
file  the file to watch

Definition at line 1337 of file kdirwatch.cpp.

QDateTime KDirWatch::ctime const QString   path
 

Returns the time the directory/file was last changed.

Parameters:
path  the file to check
Returns:
the date of the last modification

Definition at line 1342 of file kdirwatch.cpp.

References QDateTime::setTime_t().

void KDirWatch::removeDir const QString   path
 

Removes a directory from the list of scanned directories.

If specified path is not in the list this does nothing.

Parameters:
path  the path of the dir to be removed from the list

Definition at line 1354 of file kdirwatch.cpp.

void KDirWatch::removeFile const QString   file
 

Removes a file from the list of watched files.

If specified path is not in the list this does nothing.

Parameters:
file  the file to be removed from the list

Definition at line 1359 of file kdirwatch.cpp.

bool KDirWatch::stopDirScan const QString   path
 

Stops scanning the specified path.

The 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).

Parameters:
path  the path to skip
Returns:
true if the path is being watched, otherwise false
See also:
restartDirScanning()

Definition at line 1364 of file kdirwatch.cpp.

bool KDirWatch::restartDirScan const QString   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, and when you have refreshed that path.

Parameters:
path  the path to restart scanning
Returns:
true if the path is being watched, otherwise false
See also:
stopDirScanning()

Definition at line 1373 of file kdirwatch.cpp.

void KDirWatch::startScan bool    notify = false,
bool    skippedToo = false
 

Starts scanning of all dirs in list.

Parameters:
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 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 false or else all directories in list will be notified.
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.

Definition at line 1390 of file kdirwatch.cpp.

void KDirWatch::stopScan  
 

Stops scanning of all directories in internal list.

The timer is stopped, but the list is not cleared.

Definition at line 1384 of file kdirwatch.cpp.

bool KDirWatch::isStopped   [inline]
 

Is scanning stopped? After creation of a KDirWatch instance, this is false.

Returns:
true when scanning stopped

Definition at line 188 of file kdirwatch.h.

bool KDirWatch::contains const QString   path const
 

Check if a directory is being watched by this KDirWatch instance.

Parameters:
path  the directory to check
Returns:
true if the directory is being watched

Definition at line 1397 of file kdirwatch.cpp.

void KDirWatch::statistics   [static]
 

Dump statistic information about all KDirWatch instances.

This checks for consistency, too.

Definition at line 1410 of file kdirwatch.cpp.

void KDirWatch::setCreated const QString   path
 

Emits created().

Parameters:
path  the path of the file or directory

Definition at line 1420 of file kdirwatch.cpp.

References created(), and QObject::name().

void KDirWatch::setDirty const QString   path
 

Emits dirty().

Parameters:
path  the path of the file or directory

Definition at line 1426 of file kdirwatch.cpp.

References dirty(), and QObject::name().

void KDirWatch::setDeleted const QString   path
 

Emits deleted().

Parameters:
path  the path of the file or directory

Definition at line 1432 of file kdirwatch.cpp.

References deleted(), and QObject::name().

KDirWatch::Method KDirWatch::internalMethod  
 

Returns the preferred internal method to watch for changes.

Since:
3.2

Definition at line 1438 of file kdirwatch.cpp.

KDirWatch * KDirWatch::self   [static]
 

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.

Returns:
a KDirWatch instance

Definition at line 1282 of file kdirwatch.cpp.

References KStaticDeleter< type >::setObject().

bool KDirWatch::exists   [static]
 

Returns true if there is an instance of KDirWatch.

Returns:
true if there is an instance of KDirWatch.
See also:
KDirWatch::self()
Since:
3.1

Definition at line 1291 of file kdirwatch.cpp.

void KDirWatch::dirty const QString   path [signal]
 

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.

Parameters:
path  the path of the file or directory

Referenced by setDirty().

void KDirWatch::created const QString   path [signal]
 

Emitted when a file or directory is created.

Parameters:
path  the path of the file or directory

Referenced by setCreated().

void KDirWatch::deleted const QString   path [signal]
 

Emitted when a file or directory is deleted.

The object is still watched for new creation.

Parameters:
path  the path of the file or directory

Referenced by setDeleted().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kio Library Version 3.2.0.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Feb 4 12:35:12 2004 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2003