class Poco::DirectoryWatcher

Overview

This class is used to get notifications about changes to the filesystem, more specifically, to a specific directory. More…

#include <DirectoryWatcher.h>

class DirectoryWatcher: protected Poco::Runnable
{
public:
    // enums

    enum
    {
        DW_DEFAULT_SCAN_INTERVAL = 5,
    };

    enum DirectoryEventMask;
    enum DirectoryEventType;

    // structs

    struct DirectoryEvent;

    // fields

    BasicEvent<const DirectoryEvent> itemAdded;
    BasicEvent<const DirectoryEvent> itemRemoved;
    BasicEvent<const DirectoryEvent> itemModified;
    BasicEvent<const DirectoryEvent> itemMovedFrom;
    BasicEvent<const DirectoryEvent> itemMovedTo;
    BasicEvent<const Exception> scanError;

    // construction

    DirectoryWatcher(
        const std::string& path,
        int eventMask = DW_FILTER_ENABLE_ALL,
        int scanInterval = DW_DEFAULT_SCAN_INTERVAL
        );

    DirectoryWatcher(
        const File& directory,
        int eventMask = DW_FILTER_ENABLE_ALL,
        int scanInterval = DW_DEFAULT_SCAN_INTERVAL
        );

    // methods

    void
    suspendEvents();

    void
    resumeEvents();

    bool
    eventsSuspended() const;

    int
    eventMask() const;

    int
    scanInterval() const;

    const File&
    directory() const;

    bool
    supportsMoveEvents() const;

protected:
    // methods

    void
    init();

    void
    stop();

    virtual
    void
    run();
};

Inherited Members

public:
    // methods

    virtual
    void
    run() = 0;

Detailed Documentation

This class is used to get notifications about changes to the filesystem, more specifically, to a specific directory.

Changes to a directory are reported via events.

A thread will be created that watches the specified directory for changes. Events are reported in the context of this thread.

Note that changes to files in subdirectories of the watched directory are not reported. Separate DirectoryWatcher objects must be created for these directories if they should be watched.

Changes to file attributes are not reported.

On Windows, this class is implemented using FindFirstChangeNotification()/FindNextChangeNotification(). On Linux, this class is implemented using inotify. On FreeBSD and Darwin (Mac OS X, iOS), this class uses kevent/kqueue. On all other platforms, the watched directory is periodically scanned for changes. This can negatively affect performance if done too often. Therefore, the interval in which scans are done can be specified in the constructor. Note that periodic scanning will also be done on FreeBSD and Darwin if events for changes to files (DW_ITEM_MODIFIED) are enabled.

DW_ITEM_MOVED_FROM and DW_ITEM_MOVED_TO events will only be reported on Linux. On other platforms, a file rename or move operation will be reported via a DW_ITEM_REMOVED and a DW_ITEM_ADDED event. The order of these two events is not defined.

An event mask can be specified to enable only certain events.

Enum Values

DW_DEFAULT_SCAN_INTERVAL

Default scan interval for platforms that don’t provide a native notification mechanism.

Fields

BasicEvent<const DirectoryEvent> itemAdded

Fired when a file or directory has been created or added to the directory.

BasicEvent<const DirectoryEvent> itemRemoved

Fired when a file or directory has been removed from the directory.

BasicEvent<const DirectoryEvent> itemModified

Fired when a file or directory has been modified.

BasicEvent<const DirectoryEvent> itemMovedFrom

Fired when a file or directory has been renamed. This event delivers the old name.

BasicEvent<const DirectoryEvent> itemMovedTo

Fired when a file or directory has been moved. This event delivers the new name.

BasicEvent<const Exception> scanError

Fired when an error occurs while scanning for changes.

Construction

DirectoryWatcher(
    const std::string& path,
    int eventMask = DW_FILTER_ENABLE_ALL,
    int scanInterval = DW_DEFAULT_SCAN_INTERVAL
    )

Creates a DirectoryWatcher for the directory given in path.

To enable only specific events, an eventMask can be specified by OR-ing the desired event IDs (e.g., DW_ITEM_ADDED | DW_ITEM_MODIFIED). On platforms where no native filesystem notifications are available, scanInterval specifies the interval in seconds between scans of the directory.

DirectoryWatcher(
    const File& directory,
    int eventMask = DW_FILTER_ENABLE_ALL,
    int scanInterval = DW_DEFAULT_SCAN_INTERVAL
    )

Creates a DirectoryWatcher for the specified directory To enable only specific events, an eventMask can be specified by OR-ing the desired event IDs (e.g., DW_ITEM_ADDED | DW_ITEM_MODIFIED).

On platforms where no native filesystem notifications are available, scanInterval specifies the interval in seconds between scans of the directory.

Methods

void
suspendEvents()

Suspends sending of events.

Can be called multiple times, but every call to suspendEvent() must be matched by a call to resumeEvents().

void
resumeEvents()

Resumes events, after they have been suspended with a call to suspendEvents().

bool
eventsSuspended() const

Returns true iff events are suspended.

int
eventMask() const

Returns the value of the eventMask passed to the constructor.

int
scanInterval() const

Returns the scan interval in seconds.

const File&
directory() const

Returns the directory being watched.

bool
supportsMoveEvents() const

Returns true iff the platform supports DW_ITEM_MOVED_FROM/itemMovedFrom and DW_ITEM_MOVED_TO/itemMovedTo events.

virtual
void
run()

Do whatever the thread needs to do.

Must be overridden by subclasses.