This class listens for changes to or operations on a certain file, and receives callbacks to be notified when changes occur. More...

#include <lfilesystem_FileWatcher.h>

Inheritance diagram for limes::files::FileWatcher:

Public Member Functions
	FileWatcher () noexcept
	Creates an inactive FileWatcher that does nothing. More...

	FileWatcher (const FilesystemEntry &fileToWatch)
	Creates a FileWatcher to watch the given file or directory. More...

	FileWatcher (const FileWatcher &)=delete

	FileWatcher (FileWatcher &&)=delete

virtual	~FileWatcher ()
	Destructor. More...

virtual void	fileAccessed (const FilesystemEntry &)
	Called when a file's content is accessed. More...

virtual void	fileCreated (const FilesystemEntry &)
	Called when a file or subdirectory is created in a watched directory. More...

virtual void	fileDeleted (const FilesystemEntry &)
	Called when a file is deleted. More...

virtual void	fileHandleClosed (const FilesystemEntry &)
	Called when a file handle is closed (from either reading or writing). More...

virtual void	fileMetadataChanged (const FilesystemEntry &)
	Called when a file's metadata is changed, such as permissions, owner, etc. More...

virtual void	fileModified (const FilesystemEntry &)
	Called when a file's content is modified. More...

virtual void	fileMoved (const FilesystemEntry &)
	Called when a file is moved or renamed. More...

virtual void	fileOpened (const FilesystemEntry &)
	Called when a file handle is created (for either reading or writing). More...

FilesystemEntry	getWatchedPath () const noexcept
	Returns the path that is currently being watched. More...

bool	isRunning ()
	Returns true if the FilesystemWatcher is currently monitoring events. More...

FileWatcher &	operator= (const FileWatcher &)=delete

FileWatcher &	operator= (FileWatcher &&)=delete

virtual void	otherEventType (const FilesystemEntry &)
	Called when an unspecified event has occurred, such as one of the watched file's parent directories being renamed or deleted. More...

bool	start ()
	Restarts watching the path specified at construction. More...

bool	start (const FilesystemEntry &newPathToWatch)
	Begins watching the new specified path. More...

void	stop ()
	Stops the FilesystemWatcher's event callbacks. More...

Static Public Member Functions
static bool	supportedBySystem () noexcept
	Returns true if the current system supports file event watching. More...

Detailed Description

This class listens for changes to or operations on a certain file, and receives callbacks to be notified when changes occur.

You can create a FileWatcher to listen for events to any kind of FilesystemEntry .

The callbacks are asynchronous, and have no guarantee of granularity or regularity. Note that the callbacks may be called from a background thread!

Each of the callbacks receives a FilesystemEntry argument with the path to which the current event applies. If a directory is being watched, this path may be a child of the watched directory. In some cases, this path may be a parent directory of the watched path, even if the watched path is a file.

See also: SimpleFileWatcher

Todo:: iOS, Android and Emscripten implementations. This class requires platform-specific code, probably JNI for Android and Swift/ObjC for iOS. Is this class possible to implement for Emscripten?

Todo:: how to test this class? A test would basically need to check that the proper callbacks are indeed called when a watched file is mutated. Is this even possible?

Examples: files_dir_listen.cpp.

Definition at line 67 of file lfilesystem_FileWatcher.h.

Constructor & Destructor Documentation

◆ FileWatcher() [1/2]

limes::files::FileWatcher::FileWatcher ( const FilesystemEntry & fileToWatch )

explicit

Creates a FileWatcher to watch the given file or directory.

Exceptions

std::runtime_error Throws an exception if the file watcher fails to initialize for any reason. An exception will always be thrown if the file you request to watch does not exist at the time of the object's construction.

◆ FileWatcher() [2/2]

limes::files::FileWatcher::FileWatcher ( )

noexcept

Creates an inactive FileWatcher that does nothing.

Call start() and provide a new path to watch in order to use this object.

◆ ~FileWatcher()

virtual limes::files::FileWatcher::~FileWatcher ( )

virtual

Destructor.

Member Function Documentation

◆ fileAccessed()

virtual void limes::files::FileWatcher::fileAccessed ( const FilesystemEntry & )

inlinevirtual

Called when a file's content is accessed.

This is never called on Windows.

Definition at line 96 of file lfilesystem_FileWatcher.h.

◆ fileCreated()

virtual void limes::files::FileWatcher::fileCreated ( const FilesystemEntry & )

inlinevirtual

Called when a file or subdirectory is created in a watched directory.

Reimplemented in JSONWatcher.

Definition at line 110 of file lfilesystem_FileWatcher.h.

◆ fileDeleted()

virtual void limes::files::FileWatcher::fileDeleted ( const FilesystemEntry & )

inlinevirtual

Called when a file is deleted.

Reimplemented in JSONWatcher.

Definition at line 113 of file lfilesystem_FileWatcher.h.

◆ fileHandleClosed()

virtual void limes::files::FileWatcher::fileHandleClosed ( const FilesystemEntry & )

inlinevirtual

Called when a file handle is closed (from either reading or writing).

This is only called on Linux.

Definition at line 107 of file lfilesystem_FileWatcher.h.

◆ fileMetadataChanged()

virtual void limes::files::FileWatcher::fileMetadataChanged ( const FilesystemEntry & )

inlinevirtual

Called when a file's metadata is changed, such as permissions, owner, etc.

This is never called on Windows.

See also: fileModified()

Definition at line 102 of file lfilesystem_FileWatcher.h.

◆ fileModified()

virtual void limes::files::FileWatcher::fileModified ( const FilesystemEntry & )

inlinevirtual

Called when a file's content is modified.

On Windows, there is no distinction between events for a file's content being modified and its metadata being modified. This function will always be called in both cases, and fileMetadataChanged() will never be called on Windows.

Definition at line 122 of file lfilesystem_FileWatcher.h.

◆ fileMoved()

virtual void limes::files::FileWatcher::fileMoved ( const FilesystemEntry & )

inlinevirtual

Called when a file is moved or renamed.

For directories, this will be called if the watched directory contained the file that was moved from or the file that was moved to.

Reimplemented in JSONWatcher.

Definition at line 128 of file lfilesystem_FileWatcher.h.

◆ fileOpened()

virtual void limes::files::FileWatcher::fileOpened ( const FilesystemEntry & )

inlinevirtual

Called when a file handle is created (for either reading or writing).

This is only called on Linux.

Definition at line 133 of file lfilesystem_FileWatcher.h.

◆ getWatchedPath()

FilesystemEntry limes::files::FileWatcher::getWatchedPath ( ) const

noexcept

Returns the path that is currently being watched.

◆ isRunning()

bool limes::files::FileWatcher::isRunning ( )

Returns true if the FilesystemWatcher is currently monitoring events.

◆ otherEventType()

virtual void limes::files::FileWatcher::otherEventType ( const FilesystemEntry & )

inlinevirtual

Called when an unspecified event has occurred, such as one of the watched file's parent directories being renamed or deleted.

This is currently only called on Mac when the kFSEventStreamEventFlagRootChanged event flag is received.

Definition at line 139 of file lfilesystem_FileWatcher.h.

◆ start() [1/2]

bool limes::files::FileWatcher::start ( )

Restarts watching the path specified at construction.

Returns: True if the FilesystemWatcher is running after this function returns. This will return true if the watcher was already running before this function call.

◆ start() [2/2]

bool limes::files::FileWatcher::start ( const FilesystemEntry & newPathToWatch )

Begins watching the new specified path.

If the new path is not the same as the previously watched path, this will first call stop() to cease monitoring events from the old path, then attempt to start watching events for the new path, and return true if this initialization is successful.

◆ stop()

void limes::files::FileWatcher::stop ( )

Stops the FilesystemWatcher's event callbacks.

This does not cancel any pending callbacks that may have been registered with the OS.

◆ supportedBySystem()

static bool limes::files::FileWatcher::supportedBySystem ( )

staticnoexcept

Returns true if the current system supports file event watching.

Currently returns false on iOS and Android.

The documentation for this class was generated from the following file:

lfilesystem_FileWatcher.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ FileWatcher() [1/2]

◆ FileWatcher() [2/2]

◆ ~FileWatcher()

Member Function Documentation

◆ fileAccessed()

◆ fileCreated()

◆ fileDeleted()

◆ fileHandleClosed()

◆ fileMetadataChanged()

◆ fileModified()

◆ fileMoved()

◆ fileOpened()

◆ getWatchedPath()

◆ isRunning()

◆ otherEventType()

◆ start() [1/2]

◆ start() [2/2]

◆ stop()

◆ supportedBySystem()