Components All New MacOS Windows Linux iOS
Examples Mac & Win Server Client Guides Statistic FMM Blog Deprecated Old

FSEvents.Create

Creates a new FSEvents monitor.

Component Version macOS Windows Linux Server iOS SDK
FSEvents 5.4 ✅ Yes ❌ No ❌ No ✅ Yes, on macOS ❌ No
MBS( "FSEvents.Create"; PathList { ; sinceWhen; Flags; latency } )   More

Parameters

Parameter Description Example Flags
PathList List of folders to watch.
(or just one path)		 $path
sinceWhen The event ID from where to start. Can be the latest ID you saw last time or you pass "now" to start with now. "now" Optional
Flags The flags. Can be a combination of NoDefer, WatchRoot, IgnoreSelf, FileEvents or MarkSelf. "IgnoreSelf,FileEvents" Optional
latency The latency. 2 Optional

Result

Returns reference number or error.

Description

Creates a new FSEvents monitor.
Works on server and client.
May not work for network shared disks as most drivers don't pass through change events.

Flag values:

NoDefer = 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.

WatchRoot = 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.

IgnoreSelf = 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. Also, this does not apply to RootChanged events because the WatchRoot feature uses a separate mechanism that is unable to provide information about the responsible process.

FileEvents = 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.

MarkSel = 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.

This function requires a native path. Use Path.FileMakerPathToNativePath to convert a FileMaker path to a native path if required. If you like to have the user choose the path, you can use FileDialog functions.
For Server be aware that server has limited permissions and may not be able to access all files on a computer.

Examples

Initializes FSEvents:

Delete All Records [No dialog]
Set Variable [$path; Value:MBS( "Folders.UserDesktop" )]
Set Variable [$sinceWhen; Value:"now"]
If [not IsEmpty(FSEvents::LastID)]
    Set Variable [$sinceWhen; Value:FSEvents::LastID]
End If
Set Variable [$fstream; Value:MBS("FSEvents.Create"; $path; $sinceWhen; "IgnoreSelf, FileEvents, WatchRoot"; 2)]
If [MBS("IsError")]
    Show Custom Dialog ["Error"; "Failed to create file system event monitor."]
Else
    Set Variable [$r; Value:MBS("FSEvents.SetFileName"; $fstream; Get(FileName))]
    Set Variable [$r; Value:MBS("FSEvents.SetScriptName"; $fstream; "FSEventsNotification")]
    Set Variable [$r; Value:MBS("FSEvents.Start"; $fstream)]
    If [$r = 1]
        Set Field [FSEvents::StreamRef; $fstream]
    Else
        Show Custom Dialog ["Error"; "Failed to start file system event monitor."]
        Set Variable [$r; Value:MBS("FSEvents.Release"; $fstream)]
    End If
End If

See also

Example Databases

This function checks for a license.

Created 18th November 2015, last changed 13th January 2020


FM.VariableSet - FSEvents.CreateRelativeToDevice