home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kdirwatch.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-01-19  |  9.0 KB  |  291 lines
  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., 51 Franklin Street, Fifth Floor,
  16.    Boston, MA 02110-1301, USA.
  17. */
  18. #ifndef _KDIRWATCH_H
  19. #define _KDIRWATCH_H
  20.  
  21. #include <qtimer.h>
  22. #include <qdatetime.h>
  23. #include <qmap.h>
  24.  
  25. #include <kdelibs_export.h>
  26.  
  27. #define kdirwatch KDirWatch::self()
  28.  
  29. class KDirWatchPrivate;
  30.  
  31.  /**
  32.   * Watch directories and files for changes.
  33.   * The watched directories or files don't have to exist yet.
  34.   *
  35.   * When a watched directory is changed, i.e. when files therein are
  36.   * created or deleted, KDirWatch will emit the signal dirty().
  37.   *
  38.   * When a watched, but previously not existing directory gets created,
  39.   * KDirWatch will emit the signal created().
  40.   *
  41.   * When a watched directory gets deleted, KDirWatch will emit the
  42.   * signal deleted(). The directory is still watched for new
  43.   * creation.
  44.   *
  45.   * When a watched file is changed, i.e. attributes changed or written
  46.   * to, KDirWatch will emit the signal dirty().
  47.   *
  48.   * Scanning of particular directories or files can be stopped temporarily
  49.   * and restarted. The whole class can be stopped and restarted.
  50.   * Directories and files can be added/removed from the list in any state.
  51.   *
  52.   * The implementation uses the FAM service when available;
  53.   * if FAM is not available, the DNOTIFY functionality is used on LINUX.
  54.   * As a last resort, a regular polling for change of modification times
  55.   * is done; the polling interval is a global config option:
  56.   * DirWatch/PollInterval and DirWatch/NFSPollInterval for NFS mounted
  57.   * directories.
  58.   *
  59.   * @see self()
  60.   * @short Class for watching directory and file changes.
  61.   * @author Sven Radej <sven@lisa.exp.univie.ac.at>
  62.   */
  63. class KIO_EXPORT KDirWatch : public QObject
  64. {
  65.   Q_OBJECT
  66.     
  67.   public:
  68.    /**
  69.     * Constructor.
  70.     *
  71.     * Scanning begins immediately when a dir/file watch
  72.     * is added.
  73.     * @param parent the parent of the QObject (or 0 for parent-less KDataTools)
  74.     * @param name the name of the QObject, can be 0
  75.     */
  76.    KDirWatch (QObject* parent = 0, const char* name = 0);
  77.  
  78.    /**
  79.     * Destructor.
  80.     *
  81.     * Stops scanning and cleans up.
  82.     */
  83.    ~KDirWatch();
  84.  
  85.    /**
  86.     * Adds a directory to be watched.
  87.     *
  88.     * The directory does not have to exist. When @p watchFiles is
  89.     * false (the default), the signals dirty(), created(), deleted()
  90.     * can be emitted, all for the watched directory.
  91.     * When @p watchFiles is true, all files in the watched directory
  92.     * are watched for changes, too. Thus, the signals dirty(),
  93.     * created(), deleted() can be emitted.
  94.     *
  95.     * @param path the path to watch
  96.     * @param watchFiles if true, the KDirWatch will also watch files - NOT IMPLEMENTED YET
  97.     * @param recursive if true, all sub directories are also watched - NOT IMPLEMENTED YET
  98.     */
  99.    void addDir(const QString& path, 
  100.            bool watchFiles = false, bool recursive = false);
  101.  
  102.    /**
  103.     * Adds a file to be watched.
  104.     * @param file the file to watch
  105.     */
  106.    void addFile(const QString& file);
  107.  
  108.    /**
  109.     * Returns the time the directory/file was last changed.
  110.     * @param path the file to check
  111.     * @return the date of the last modification
  112.     */
  113.    QDateTime ctime(const QString& path);
  114.  
  115.    /**
  116.     * Removes a directory from the list of scanned directories.
  117.     *
  118.     * If specified path is not in the list this does nothing.
  119.     * @param path the path of the dir to be removed from the list
  120.     */
  121.    void removeDir(const QString& path);
  122.  
  123.    /**
  124.     * Removes a file from the list of watched files.
  125.     *
  126.     * If specified path is not in the list this does nothing.
  127.     * @param file the file to be removed from the list
  128.     */
  129.    void removeFile(const QString& file);
  130.  
  131.    /**
  132.     * Stops scanning the specified path.
  133.     *
  134.     * The @p path is not deleted from the interal just, it is just skipped.
  135.     * Call this function when you perform an huge operation
  136.     * on this directory (copy/move big files or many files). When finished,
  137.     * call restartDirScan(path).
  138.     *
  139.     * @param path the path to skip
  140.     * @return true if the @p path is being watched, otherwise false
  141.     * @see restartDirScanning()
  142.     */
  143.    bool stopDirScan(const QString& path);
  144.  
  145.    /**
  146.     * Restarts scanning for specified path.
  147.     *
  148.     * Resets ctime. It doesn't notify
  149.     * the change (by emitted a signal), since the ctime value is reset.
  150.     *
  151.     * Call it when you are finished with big operations on that path,
  152.     * @em and when @em you have refreshed that path. 
  153.     *
  154.     * @param path the path to restart scanning
  155.     * @return true if the @p path is being watched, otherwise false
  156.     * @see stopDirScanning()
  157.     */
  158.    bool restartDirScan(const QString& path);
  159.  
  160.    /**
  161.     * Starts scanning of all dirs in list.
  162.     *
  163.     * @param notify If true, all changed directories (since 
  164.     * stopScan() call) will be notified for refresh. If notify is
  165.     * false, all ctimes will be reset (except those who are stopped,
  166.     * but only if @p skippedToo is false) and changed dirs won't be
  167.     * notified. You can start scanning even if the list is
  168.     * empty. First call should be called with @p false or else all 
  169.     * directories 
  170.     * in list will be notified.  
  171.     * @param skippedToo if true, the skipped directoris (scanning of which was
  172.     * stopped with stopDirScan() ) will be reset and notified
  173.     * for change. Otherwise, stopped directories will continue to be
  174.     * unnotified.
  175.     */
  176.    void startScan( bool notify=false, bool skippedToo=false );
  177.  
  178.    /**
  179.     * Stops scanning of all directories in internal list.
  180.     *
  181.     * The timer is stopped, but the list is not cleared.
  182.     */
  183.    void stopScan();
  184.  
  185.    /**
  186.     * Is scanning stopped?
  187.     * After creation of a KDirWatch instance, this is false.
  188.     * @return true when scanning stopped
  189.     */
  190.    bool isStopped() { return _isStopped; }
  191.  
  192.    /**
  193.     * Check if a directory is being watched by this KDirWatch instance
  194.     * @param path the directory to check
  195.     * @return true if the directory is being watched
  196.     */
  197.    bool contains( const QString& path ) const;
  198.  
  199.    /**
  200.     * Dump statistic information about all KDirWatch instances.
  201.     * This checks for consistency, too.
  202.     */
  203.    static void statistics();
  204.  
  205.    /** 
  206.     * Emits created().
  207.     * @param path the path of the file or directory
  208.     */
  209.    void setCreated( const QString &path );
  210.    /** 
  211.     * Emits dirty().
  212.     * @param path the path of the file or directory
  213.     */
  214.    void setDirty( const QString &path );
  215.    /** 
  216.     * Emits deleted().
  217.     * @param path the path of the file or directory
  218.     */
  219.    void setDeleted( const QString &path );
  220.  
  221.    enum Method { FAM, DNotify, Stat, INotify };
  222.    /**
  223.     * Returns the preferred internal method to
  224.     * watch for changes.
  225.     * @since 3.2
  226.     */
  227.    Method internalMethod();
  228.  
  229.    /**
  230.     * The KDirWatch instance usually globally used in an application.
  231.     * It is automatically deleted when the application exits.
  232.     *
  233.     * However, you can create an arbitrary number of KDirWatch instances
  234.     * aside from this one - for those you have to take care of memory management.
  235.     *
  236.     * This function returns an instance of KDirWatch. If there is none, it
  237.     * will be created.
  238.     * 
  239.     * @return a KDirWatch instance
  240.     */
  241.    static KDirWatch* self();
  242.    /**
  243.     * Returns true if there is an instance of KDirWatch.
  244.     * @return true if there is an instance of KDirWatch.
  245.     * @see KDirWatch::self()
  246.     * @since 3.1
  247.     */
  248.    static bool exists();
  249.  
  250.  signals:
  251.  
  252.    /**
  253.     * Emitted when a watched object is changed.
  254.     * For a directory this signal is emitted when files
  255.     * therein are created or deleted.
  256.     * For a file this signal is emitted when its size or attributes change.
  257.     *
  258.     * When you watch a directory, changes in the size or attributes of
  259.     * contained files may or may not trigger this signal to be emitted
  260.     * depending on which backend is used by KDirWatch.
  261.     *
  262.     * The new ctime is set before the signal is emitted.
  263.     * @param path the path of the file or directory
  264.     */
  265.    void dirty (const QString &path);
  266.  
  267.    /**
  268.     * Emitted when a file or directory is created.
  269.     * @param path the path of the file or directory
  270.     */
  271.    void created (const QString &path );
  272.      
  273.    /**
  274.     * Emitted when a file or directory is deleted.
  275.     *
  276.     * The object is still watched for new creation.
  277.     * @param path the path of the file or directory
  278.     */
  279.    void deleted (const QString &path );
  280.      
  281.  private:
  282.    bool _isStopped;
  283.    
  284.    KDirWatchPrivate *d;
  285.    static KDirWatch* s_pSelf;
  286. };
  287.  
  288. #endif
  289.  
  290. // vim: sw=3 et
  291.