Awesome
lfwatch - A LightFileWatcher
A lightweight file watcher for Windows, Linux and OS X. Monitors a directory for file changes and calls the callback set for the directory with information about the event.
Building
The library uses CMake to build and compiles to a static linked library.
CMake options
LFWATCH_BUILD_DEMO
: Build the demo(default ON)
Example
To watch for file modification changes in "some_directory" and print out the name of the modified file we will create a watcher, set a watch on the directory with the filters and callback we want and then call update in our update loop.
lfw::Watcher watcher;
//Watch for file writes in 'some_directory' and call our lambda when one happens
watcher.watch("some_directory", lfw::Notify::FILE_MODIFIED,
[](const lfw::EventData &e){
std::cout << "File " << e.fname << " was written to\n";
});
//In your update loop notify the watcher to update itself
watcher.update();
There's a runnable example in demo which shows usage of the various filters available and demonstrates adding/removing/updating watches.
Documentation
Callback
The callback set for each watched directory should be a std::function<void(const lfw::EventData&)>
. This is
also typedef'd as lfw::Callback
.
EventData
The lfw::EventData
struct passed to your callback contains information about the watched directory and
event filters along with the file name and event that was caught.
struct EventData {
//dir: the directory being watched
//fname: the file the event occured on
std::string dir, fname;
//filter: the filters you set that matched the event
//event: the specific event that occured to match your filters
uint32_t filter, event;
};
Notify Filters and Events
There are five types of events you can watch a directory for and receive events about. To watch for multiple event types you can or the desired flags together.
lfw::Notify::FILE_MODIFIED
: A file was modified. This could be an attribute change or file write.lfw::Notify::FILE_CREATED
: A file was created.lfw::Notify::FILE_REMOVED
: A file was removed.lfw::Notify::FILE_RENAMED_OLD_NAME
: A file was renamed and this is its old namelfw::Notify::FILE_RENAMED_NEW_NAME
: A file was renamed and this is its new name
Note: For rename events there isn't information to absolutely associate the old name with the new name event. Although on Linux inotify gives you an associated number with the rename event it doesn't seem like Windows or OS X do that. Keep this in mind if you might be watching a lot of rename events.
Watcher
The lfw::Watcher
is what manages the watched directories and is responsible for adding, removing and updating existing
watches along with cleaning them up when it's destroyed.
To add a new directory to be watched or to update an existing watch with new filters and/or callback call watch
.
The function takes the directory name, your lfw::Notify
filters or'd together and the callback to call.
void watch(const std::string &dir, uint32_t filters, const Callback &callback);
To remove a directory from the watch list call remove
and pass the directory name to be removed.
void remove(const std::string &dir);
To update the watched directories and receive new events that have occured you must call update
.
void update();