.TH "KDirWatch" kde3 "11 Jun 2005" "Version Version 3.4.1" "kio Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
KDirWatch \- Watch directories and files for changes. Class for watching directory and file changes.  

.PP
.SH SYNOPSIS
.br
.PP
\fC#include <kdirwatch.h>\fP
.PP
Inherits \fBQObject\fP.
.PP
.SS "Public Types"

.in +1c
.ti -1c
.RI "enum \fBMethod\fP { \fBFAM\fP, \fBDNotify\fP, \fBStat\fP }"
.br
.in -1c
.SS "Signals"

.in +1c
.ti -1c
.RI "void \fBdirty\fP (const \fBQString\fP &path)"
.br
.ti -1c
.RI "void \fBcreated\fP (const \fBQString\fP &path)"
.br
.ti -1c
.RI "void \fBdeleted\fP (const \fBQString\fP &path)"
.br
.in -1c
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fBKDirWatch\fP (\fBQObject\fP *\fBparent\fP=0, const char *\fBname\fP=0)"
.br
.ti -1c
.RI "\fB~KDirWatch\fP ()"
.br
.ti -1c
.RI "void \fBaddDir\fP (const \fBQString\fP &path, bool watchFiles=false, bool recursive=false)"
.br
.ti -1c
.RI "void \fBaddFile\fP (const \fBQString\fP &file)"
.br
.ti -1c
.RI "\fBQDateTime\fP \fBctime\fP (const \fBQString\fP &path)"
.br
.ti -1c
.RI "void \fBremoveDir\fP (const \fBQString\fP &path)"
.br
.ti -1c
.RI "void \fBremoveFile\fP (const \fBQString\fP &file)"
.br
.ti -1c
.RI "bool \fBstopDirScan\fP (const \fBQString\fP &path)"
.br
.ti -1c
.RI "bool \fBrestartDirScan\fP (const \fBQString\fP &path)"
.br
.ti -1c
.RI "void \fBstartScan\fP (bool notify=false, bool skippedToo=false)"
.br
.ti -1c
.RI "void \fBstopScan\fP ()"
.br
.ti -1c
.RI "bool \fBisStopped\fP ()"
.br
.ti -1c
.RI "bool \fBcontains\fP (const \fBQString\fP &path) const "
.br
.ti -1c
.RI "void \fBsetCreated\fP (const \fBQString\fP &path)"
.br
.ti -1c
.RI "void \fBsetDirty\fP (const \fBQString\fP &path)"
.br
.ti -1c
.RI "void \fBsetDeleted\fP (const \fBQString\fP &path)"
.br
.ti -1c
.RI "Method \fBinternalMethod\fP ()"
.br
.in -1c
.SS "Static Public Member Functions"

.in +1c
.ti -1c
.RI "static void \fBstatistics\fP ()"
.br
.ti -1c
.RI "static \fBKDirWatch\fP * \fBself\fP ()"
.br
.ti -1c
.RI "static bool \fBexists\fP ()"
.br
.in -1c
.SH "Detailed Description"
.PP 
Watch directories and files for changes. Class for watching directory and file changes. 

The watched directories or files don't have to exist yet.
.PP
When a watched directory is changed, i.e. when files therein are created or deleted, KDirWatch will emit the signal \fBdirty()\fP.
.PP
When a watched, but previously not existing directory gets created, KDirWatch will emit the signal \fBcreated()\fP.
.PP
When a watched directory gets deleted, KDirWatch will emit the signal \fBdeleted()\fP. The directory is still watched for new creation.
.PP
When a watched file is changed, i.e. attributes changed or written to, KDirWatch will emit the signal \fBdirty()\fP.
.PP
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.
.PP
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.
.PP
\fBSee also:\fP
.RS 4
\fBself()\fP 
.RE
.PP
\fBAuthor:\fP
.RS 4
Sven Radej <sven@lisa.exp.univie.ac.at> 
.RE
.PP

.PP
Definition at line 63 of file kdirwatch.h.
.SH "Constructor & Destructor Documentation"
.PP 
.SS "KDirWatch::KDirWatch (\fBQObject\fP * parent = \fC0\fP, const char * name = \fC0\fP)"
.PP
Constructor. 
.PP
Scanning begins immediately when a dir/file watch is added. 
.PP
\fBParameters:\fP
.RS 4
\fIparent\fP the parent of the \fBQObject\fP (or 0 for parent-less KDataTools) 
.br
\fIname\fP the name of the \fBQObject\fP, can be 0 
.RE
.PP

.PP
Definition at line 1312 of file kdirwatch.cpp.
.PP
References QObject::setName().
.SS "KDirWatch::~\fBKDirWatch\fP ()"
.PP
Destructor. 
.PP
Stops scanning and cleans up. 
.PP
Definition at line 1330 of file kdirwatch.cpp.
.SH "Member Function Documentation"
.PP 
.SS "void KDirWatch::addDir (const \fBQString\fP & path, bool watchFiles = \fCfalse\fP, bool recursive = \fCfalse\fP)"
.PP
Adds a directory to be watched. 
.PP
The directory does not have to exist. When \fCwatchFiles\fP is false (the default), the signals \fBdirty()\fP, \fBcreated()\fP, \fBdeleted()\fP can be emitted, all for the watched directory. When \fCwatchFiles\fP is true, all files in the watched directory are watched for changes, too. Thus, the signals \fBdirty()\fP, \fBcreated()\fP, \fBdeleted()\fP can be emitted.
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path to watch 
.br
\fIwatchFiles\fP if true, the KDirWatch will also watch files - NOT IMPLEMENTED YET 
.br
\fIrecursive\fP if true, all sub directories are also watched - NOT IMPLEMENTED YET 
.RE
.PP

.PP
Definition at line 1343 of file kdirwatch.cpp.
.PP
References endl(), and kdDebug().
.SS "void KDirWatch::addFile (const \fBQString\fP & file)"
.PP
Adds a file to be watched. 
.PP
\fBParameters:\fP
.RS 4
\fIfile\fP the file to watch 
.RE
.PP

.PP
Definition at line 1352 of file kdirwatch.cpp.
.SS "\fBQDateTime\fP KDirWatch::ctime (const \fBQString\fP & path)"
.PP
Returns the time the directory/file was last changed. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the file to check 
.RE
.PP
\fBReturns:\fP
.RS 4
the date of the last modification 
.RE
.PP

.PP
Definition at line 1357 of file kdirwatch.cpp.
.PP
References QDateTime::setTime_t().
.SS "void KDirWatch::removeDir (const \fBQString\fP & path)"
.PP
Removes a directory from the list of scanned directories. 
.PP
If specified path is not in the list this does nothing. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path of the dir to be removed from the list 
.RE
.PP

.PP
Definition at line 1369 of file kdirwatch.cpp.
.SS "void KDirWatch::removeFile (const \fBQString\fP & file)"
.PP
Removes a file from the list of watched files. 
.PP
If specified path is not in the list this does nothing. 
.PP
\fBParameters:\fP
.RS 4
\fIfile\fP the file to be removed from the list 
.RE
.PP

.PP
Definition at line 1374 of file kdirwatch.cpp.
.SS "bool KDirWatch::stopDirScan (const \fBQString\fP & path)"
.PP
Stops scanning the specified path. 
.PP
The \fCpath\fP 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).
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path to skip 
.RE
.PP
\fBReturns:\fP
.RS 4
true if the \fCpath\fP is being watched, otherwise false 
.RE
.PP
\fBSee also:\fP
.RS 4
restartDirScanning() 
.RE
.PP

.PP
Definition at line 1379 of file kdirwatch.cpp.
.SS "bool KDirWatch::restartDirScan (const \fBQString\fP & path)"
.PP
Restarts scanning for specified path. 
.PP
Resets ctime. It doesn't notify the change (by emitted a signal), since the ctime value is reset.
.PP
Call it when you are finished with big operations on that path, \fIand\fP when \fIyou\fP have refreshed that path.
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path to restart scanning 
.RE
.PP
\fBReturns:\fP
.RS 4
true if the \fCpath\fP is being watched, otherwise false 
.RE
.PP
\fBSee also:\fP
.RS 4
stopDirScanning() 
.RE
.PP

.PP
Definition at line 1388 of file kdirwatch.cpp.
.SS "void KDirWatch::startScan (bool notify = \fCfalse\fP, bool skippedToo = \fCfalse\fP)"
.PP
Starts scanning of all dirs in list. 
.PP
\fBParameters:\fP
.RS 4
\fInotify\fP If true, all changed directories (since \fBstopScan()\fP call) will be notified for refresh. If notify is false, all ctimes will be reset (except those who are stopped, but only if \fCskippedToo\fP 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 \fCfalse\fP or else all directories in list will be notified. 
.br
\fIskippedToo\fP if true, the skipped directoris (scanning of which was stopped with \fBstopDirScan()\fP ) will be reset and notified for change. Otherwise, stopped directories will continue to be unnotified. 
.RE
.PP

.PP
Definition at line 1405 of file kdirwatch.cpp.
.SS "void KDirWatch::stopScan ()"
.PP
Stops scanning of all directories in internal list. 
.PP
The timer is stopped, but the list is not cleared. 
.PP
Definition at line 1399 of file kdirwatch.cpp.
.SS "bool KDirWatch::isStopped ()\fC [inline]\fP"
.PP
Is scanning stopped? After creation of a KDirWatch instance, this is false. 
.PP
\fBReturns:\fP
.RS 4
true when scanning stopped 
.RE
.PP

.PP
Definition at line 190 of file kdirwatch.h.
.SS "bool KDirWatch::contains (const \fBQString\fP & path) const"
.PP
Check if a directory is being watched by this KDirWatch instance. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the directory to check 
.RE
.PP
\fBReturns:\fP
.RS 4
true if the directory is being watched 
.RE
.PP

.PP
Definition at line 1412 of file kdirwatch.cpp.
.SS "void KDirWatch::statistics ()\fC [static]\fP"
.PP
Dump statistic information about all KDirWatch instances. 
.PP
This checks for consistency, too. 
.PP
Definition at line 1425 of file kdirwatch.cpp.
.PP
References endl(), and kdDebug().
.SS "void KDirWatch::setCreated (const \fBQString\fP & path)"
.PP
Emits \fBcreated()\fP. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path of the file or directory 
.RE
.PP

.PP
Definition at line 1435 of file kdirwatch.cpp.
.PP
References created(), endl(), kdDebug(), and QObject::name().
.SS "void KDirWatch::setDirty (const \fBQString\fP & path)"
.PP
Emits \fBdirty()\fP. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path of the file or directory 
.RE
.PP

.PP
Definition at line 1441 of file kdirwatch.cpp.
.PP
References dirty(), endl(), kdDebug(), and QObject::name().
.SS "void KDirWatch::setDeleted (const \fBQString\fP & path)"
.PP
Emits \fBdeleted()\fP. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path of the file or directory 
.RE
.PP

.PP
Definition at line 1447 of file kdirwatch.cpp.
.PP
References deleted(), endl(), kdDebug(), and QObject::name().
.SS "KDirWatch::Method KDirWatch::internalMethod ()"
.PP
Returns the preferred internal method to watch for changes. 
.PP
\fBSince:\fP
.RS 4
3.2 
.RE
.PP

.PP
Definition at line 1453 of file kdirwatch.cpp.
.SS "\fBKDirWatch\fP * KDirWatch::self ()\fC [static]\fP"
.PP
The KDirWatch instance usually globally used in an application. 
.PP
It is automatically deleted when the application exits.
.PP
However, you can create an arbitrary number of KDirWatch instances aside from this one - for those you have to take care of memory management.
.PP
This function returns an instance of KDirWatch. If there is none, it will be created.
.PP
\fBReturns:\fP
.RS 4
a KDirWatch instance 
.RE
.PP

.PP
Definition at line 1298 of file kdirwatch.cpp.
.PP
References KStaticDeleter< type >::setObject().
.SS "bool KDirWatch::exists ()\fC [static]\fP"
.PP
Returns true if there is an instance of KDirWatch. 
.PP
\fBReturns:\fP
.RS 4
true if there is an instance of KDirWatch. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBKDirWatch::self()\fP 
.RE
.PP
\fBSince:\fP
.RS 4
3.1 
.RE
.PP

.PP
Definition at line 1307 of file kdirwatch.cpp.
.SS "void KDirWatch::dirty (const \fBQString\fP & path)\fC [signal]\fP"
.PP
Emitted when a watched object is changed. 
.PP
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.
.PP
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.
.PP
The new ctime is set before the signal is emitted. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path of the file or directory 
.RE
.PP

.PP
Referenced by setDirty().
.SS "void KDirWatch::created (const \fBQString\fP & path)\fC [signal]\fP"
.PP
Emitted when a file or directory is created. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path of the file or directory 
.RE
.PP

.PP
Referenced by setCreated().
.SS "void KDirWatch::deleted (const \fBQString\fP & path)\fC [signal]\fP"
.PP
Emitted when a file or directory is deleted. 
.PP
The object is still watched for new creation. 
.PP
\fBParameters:\fP
.RS 4
\fIpath\fP the path of the file or directory 
.RE
.PP

.PP
Referenced by setDeleted().

.SH "Author"
.PP 
Generated automatically by Doxygen for kio Library from the source code.
