Xojo Conferences
XDCMay2019MiamiUSA

Platforms to show: All Mac Windows Linux Cross-Platform

FSEventsMBS class

Type Topic Plugin Version macOS Windows Linux Console & Web iOS
class Folder Change Watching MBS MacFrameworks Plugin 8.1 Yes No No Yes, macOS only No
Function: A class for the Mac OS X 10.5 feature called FSEvents which can be used to monitor a folder hierarchie for changes.
Notes:
The text below is from the Apple documentation (With some plugin related modifications). The plugin does currently not support the device related functions, but that can be added later if you need it.

This class provides a mechanism to notify clients about directories they ought to re-scan in order to keep their internal data structures up-to-date with respect to the true state of the file system. (For example, when files or directories are created, modified, or removed.) It sends these notifications "in bulk", possibly notifying the client of changes to several directories in a single callback. By using the API, clients can notice such changes quickly, without needing to resort to recursive polling/scanning of the file system.

Much like kqueues, the FSEvents API allows an application to find near-immediately when the contents of a particular directory has changed. However, unlike kqueues, the FSEvents API allows the application to monitor the whole file system hierarchy rooted at a specified directory (and still get precise per-directory notifications) -- to do this with the kqueues API would require the client to monitor each directory individually.

Clients can register interest in a chunk of the filesystem hierarchy and will receive callbacks from their runloop whenever an event occurs that modifies the filesystem therein. The callback will indicate the exact directory in which the event occurred, so the client only has to scan that directory for updated info, not all its children. Clients can supply a "latency" parameter that tells how long to wait after an event occurs before forwarding it; this reduces the volume of events and reduces the chance that the client will see an "intermediate" state, like those that arise when doing a "safe save" of a file, creating a package, or downloading a file via Safari.

The lifecycle of an FSEventStream consists of these stages:

1. new FSEventsMBS(...) -> Creates an FSEventStream.

2. Start() -> Starts receiving events and servicing them from the client's runloop(s) using the callback supplied by the client when the stream was created. If a value was supplied for the sinceWhen parameter then "historical" events will be sent via your callback first, then a HistoryDone event, then "contemporary" events will be sent on an ongoing basis (as though you had supplied kFSEventStreamEventIdSinceNow for sinceWhen).

3. Stop() -> Stops the stream, ensuring the client's callback will not be called again for this stream. After stopping the stream, it can be restarted seamlessly via Start() without missing any events.

Once the event stream has been started, the following calls can be used:

GetLatestEventId() -> Initially, this returns the sinceWhen value supplied when the stream was created; thereafter, it is updated with the highest-numbered event ID mentioned in the current batch of events just before invoking the client's callback. Clients can store this value persistently as long as they also store the UUID for the device (obtained via CopyUUIDForDevice()). Clients can then later supply this event ID as the sinceWhen parameter to CreateRelativeToDevice(), as long as its UUID matches what you stored. This works because the FSEvents service stores events in a persistent, per-volume database. In this regard,the stream of event IDs acts like a global, system-wide clock, but bears no relation to any particular timebase.

FlushAsync() -> Requests that the fseventsd daemon send any events it has already buffered (via the latency parameter to one of the constructors). This occurs asynchronously; clients will not have received all the callbacks by the time this call returns to them.

FlushSync() -> Requests that the fseventsd daemon send any events it has already buffered (via the latency parameter to one of the constructors). Then runs the runloop in its private mode till all events that have occurred have been reported (via the clients callback). This occurs synchronously; clients will have received all the callbacks by the time this call returns to them.

GetDeviceBeingWatched() -> Gets the dev_t value supplied when the stream was created with CreateRelativeToDevice(), otherwise 0.

CopyPathsBeingWatched() -> Gets the paths supplied when the stream was created with one of the constructors.

Calls that can be made without a stream:

CopyUUIDForDevice() -> Gets a UUID that uniquely identifies the FSEvents database for that volume. If the database gets discarded then its replacement will have a different UUID so that clients will be able to detect this situation and avoid trying to use event IDs that they stored as the sinceWhen parameter to the FSEventStreamCreate...() functions.

GetCurrentEventId() -> Gets the most recently generated event ID, system-wide (not just for one stream).

GetLastEventIdForDeviceBeforeTime() -> Gets the last event ID for the given device that was returned before the given time. This is conservative in the sense that if you then use the returned event ID as the sinceWhen parameter of CreateRelativeToDevice() that you will not miss any events that happened since that time. On the other hand, you might receive some (harmless) extra events.

PurgeEventsForDeviceUpToEventId() -> Purges old events from the persistent per-volume database maintained by the service. You can combine this with GetLastEventIdForDeviceBeforeTime(). Can only be called by the root user.

For Windows, you can use WindowsDirectoryWatcherMBS class.

Feedback, Comments & Corrections

Creation Flags

Constant Value Description
kFSEventStreamCreateFlagFileEvents 16 Request file-level notifications. Your stream will receive events about individual files in the hierarchy you're watching instead of only receiving directory level notifications. Use this flag with care as it will generate significantly more events than without it.

Available in Mac OS X 10.7 or newer.
kFSEventStreamCreateFlagIgnoreSelf 8 Don't send events that were triggered by the current process. This is useful for reducing the volume of events that are sent. It is only useful if your process might modify the file system hierarchy beneath the path(s) being monitored. Note: this has no effect on historical events, i.e., those delivered before the HistoryDone sentinel event.

Available in Mac OS X 10.7 or newer.
kFSEventStreamCreateFlagMarkSelf 32 Tag events that were triggered by the current process with the "OwnEvent" flag. This is only useful if your process might modify the file system hierarchy beneath the path(s) being monitored and you wish to know which events were triggered by your process. Note: this has no effect on historical events, i.e., those delivered before the HistoryDone sentinel event.
kFSEventStreamCreateFlagNoDefer 2 Affects the meaning of the latency parameter. If you specify this flag and more than latency seconds have elapsed since the last event, your app will receive the event immediately. The delivery of the event resets the latency timer and any further events will be delivered after latency seconds have elapsed. This flag is useful for apps that are interactive and want to react immediately to changes but avoid getting swamped by notifications when changes are occurringin rapid succession. If you do not specify this flag, then when an event occurs after a period of no events, the latency timer is started. Any events that occur during the next latency seconds will be delivered as one group (including that first event). The delivery of the group of events resets the latency timer and any further events will be delivered after latency seconds. This is the default behavior and is more appropriate for background, daemon or batch processing apps.
kFSEventStreamCreateFlagNone 0
kFSEventStreamCreateFlagUseCFTypes 1 The plugin uses this one internally.
kFSEventStreamCreateFlagUseExtendedData 64 Requires kFSEventStreamCreateFlagUseCFTypes and instructs the framework to invoke your callback function with CF types but, instead of passing it a CFArrayMBS of CFStringMBSs, a CFArrayMBS of CFDictionaryMBSs is passed. Each dictionary will contain the event path and possibly other "extended data" about the event. See the kFSEventStreamEventExtendedData*Key definitions for the set of keys that may be set in the dictionary.
For macOS 10.13 or newer.
kFSEventStreamCreateFlagWatchRoot 4 Request notifications of changes along the path to the path(s) you're watching. For example, with this flag, if you watch "/foo/bar" and it is renamed to "/foo/bar.old", you would receive a RootChanged event. The same is true if the directory "/foo" were renamed. The event you receive is a special event: the path for the event is the original path you specified, the flag kFSEventStreamEventFlagRootChanged is set and event ID is zero. RootChanged events are useful to indicate that you should rescan a particular hierarchy because it changed completely (as opposed to the things inside of it changing). If you want to track the current location of a directory, it is best to open the directory before creating the stream so that you have a file descriptor for it and can issue an F_GETPATH fcntl() to find the current path.

Event flags.

Constant Value Description
kFSEventStreamEventFlagEventIdsWrapped 8 If kFSEventStreamEventFlagEventIdsWrapped is set, it means the 64-bit event ID counter wrapped around. As a result, previously-issued event ID's are no longer valid arguments for the sinceWhen parameter of the constructors.
kFSEventStreamEventFlagHistoryDone 16 Denotes a sentinel event sent to mark the end of the "historical" events sent as a result of specifying a sinceWhen value in the constructor call that created this event stream. (It will not be sent if kFSEventStreamEventIdSinceNow was passed for sinceWhen.) After invoking the client's callback with all the "historical" events that occurred before now, the client's callback will be invoked with an event where the kFSEventStreamEventFlagHistoryDone flag is set. The client should ignore the path supplied in this callback.
kFSEventStreamEventFlagKernelDropped 4 The kFSEventStreamEventFlagUserDropped or kFSEventStreamEventFlagKernelDropped flags may be set in addition to the kFSEventStreamEventFlagMustScanSubDirs flag to indicate that a problem occurred in buffering the events (the particular flag set indicates where the problem occurred) and that the client must do a full scan of any directories (and their subdirectories, recursively) being monitored by this stream. If you asked to monitor multiple paths with this stream then you will be notified about all of them. Your code need only check for the kFSEventStreamEventFlagMustScanSubDirs flag; these flags (if present) only provide information to help you diagnose the problem.
kFSEventStreamEventFlagMount 64 Denotes a special event sent when a volume is mounted. The path in the event is the path to the newly-mounted volume. You will receive one of these notifications for every volume mount event inside the kernel (independent of DiskArbitration). Beware that a newly-mounted volume could contain an arbitrarily large directory hierarchy. Avoid pitfalls like triggering a recursive scan of a non-local filesystem, which you can detect by checking for the absence of the MNT_LOCAL flag in the f_flags returned by statfs(). Also be aware of the MNT_DONTBROWSE flag that is set for volumes which should not be displayed by user interface elements.
kFSEventStreamEventFlagMustScanSubDirs 1 Your application must rescan not just the directory given in the event, but all its children, recursively. This can happen if there was a problem whereby events were coalesced hierarchically. For example, an event in /Users/jsmith/Music and an event in /Users/jsmith/Pictures might be coalesced into an event with this flag set and path=/Users/jsmith. If this flag is set you may be able to get an idea of whether the bottleneck happened in the kernel (less likely) or in your client (more likely) by checking for the presence of the informational flags kFSEventStreamEventFlagUserDropped or kFSEventStreamEventFlagKernelDropped.
kFSEventStreamEventFlagNone 0
kFSEventStreamEventFlagRootChanged 32 Denotes a special event sent when there is a change to one of the directories along the path to one of the directories you asked to watch. When this flag is set, the event ID is zero and the path corresponds to one of the paths you asked to watch (specifically, the one that changed). The path may no longer exist because it or one of its parents was deleted or renamed. Events with this flag set will only be sent if you passed the flag kFSEventStreamCreateFlagWatchRoot to the constructor when you created the stream.
kFSEventStreamEventFlagUnmount 128 Denotes a special event sent when a volume is unmounted. The path in the event is the path to the directory from which the volume was unmounted. You will receive one of these notifications for every volume unmount event inside the kernel. This is not a substitute for the notifications provided by the DiskArbitration framework; you only get notified after the unmount has occurred. Beware that unmounting a volume could uncover an arbitrarily large directory hierarchy, although Mac OS X never does that.
kFSEventStreamEventFlagUserDropped 2 The kFSEventStreamEventFlagUserDropped or kFSEventStreamEventFlagKernelDropped flags may be set in addition to the kFSEventStreamEventFlagMustScanSubDirs flag to indicate that a problem occurred in buffering the events (the particular flag set indicates where the problem occurred) and that the client must do a full scan of any directories (and their subdirectories, recursively) being monitored by this stream. If you asked to monitor multiple paths with this stream then you will be notified about all of them. Your code need only check for the kFSEventStreamEventFlagMustScanSubDirs flag; these flags (if present) only provide information to help you diagnose the problem.

File Event Flags

Constant Value Description
kFSEventStreamEventFlagItemChangeOwner &h00004000 File changed owner.
kFSEventStreamEventFlagItemCloned &h00400000 The file system object at the specific path supplied in this event is a clone or was cloned.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
kFSEventStreamEventFlagItemCreated &h00000100 File created.
kFSEventStreamEventFlagItemFinderInfoMod &h00002000 File meta data in Finder info have changed.
kFSEventStreamEventFlagItemInodeMetaMod &h00000400 File meta data in inode have changed.
kFSEventStreamEventFlagItemIsDir &h00020000 File is a folder.
kFSEventStreamEventFlagItemIsFile &h00010000 File is a regular file.
kFSEventStreamEventFlagItemIsHardlink &h00100000 Indicates the object at the specified path supplied in this event is a hard link.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
kFSEventStreamEventFlagItemIsLastHardlink &h00200000 Indicates the object at the specific path supplied in this event was the last hard link.
(This flag is only ever set if you specified the FileEvents flag when creating the stream.)
kFSEventStreamEventFlagItemIsSymlink &h00040000 File is a symlink.
kFSEventStreamEventFlagItemModified &h00001000 File modified.
kFSEventStreamEventFlagItemRemoved &h00000200 File deleted.
kFSEventStreamEventFlagItemRenamed &h00000800 File renamed.
kFSEventStreamEventFlagItemXattrMod &h00008000 Extended attributes changed.
kFSEventStreamEventFlagOwnEvent &h00080000 Indicates the event was triggered by the current process.
(This flag is only ever set if you specified the MarkSelf flag when creating the stream.)

This class has no sub classes.

Some examples which use this class:


The items on this page are in the following plugins: MBS MacFrameworks Plugin.


FontMBS   -   GameKitMBS




Links
MBS FileMaker blog