This section lists the completion filters that an SMB client can request and the corresponding actions that Qumulo Core returns for a matched change.
Qumulo Core can watch for changes in file attributes and directory entries with a combination of SMB2 CHANGE_NOTIFY
filters. Depending on the requested filter—and activity in the filesystem—an SMB client or an application remains current by receiving a variety of notifications.
Commonly, these requests help limit the amount of traffic required to keep a current cache of entries for an open directory. The requests also help operating system applications such as Windows Explorer and macOS Finder update automatically when changes take place. It is also possible to make requests programmatically. For more information about language bindings, see the Windows Protocol documentation, such as ReadDirectoryChangesW function (winbase.h) for Win32 and FileSystemWatcher Class for .NET.
- Certain events, such as
rename
anddelete
trigger multipleNOTIFY_CHANGE
events. - For certain events, such as
setattr
andwrite
, Qumulo Core aggregates changes into a singleMODIFIED
event. - Currently, Qumulo Core doesn’t support watching
STREAM
attributes or theWATCH_TREE
flag.
Completion Filter Types
Each request uses a completion filter to specify the events to watch for. When events occur, the system batches them into a NOTIFY
response that contains a list of FILE_ACTION
items, each tagged with the names of changed entries. As long as the handle for the watched directory remains open, events queue up on the server, so that no events are lost between NOTIFY
requests.
- Watching for Name Changes: A name change can include four event types.
- Renaming
- Deleting
- Moving into watched directory
- Moving out of watched directory
The returned action specifies to your application whether an entry has been added, renamed, or removed.
- Watching for Metadata Changes: A metadata change can include six supported attribute types.
- File attributes
- File size
- Last-write time
- Last-access time
- Creation time
- Security (the permissions or access control list for the file or directory)
Note
Qumulo doesn’t support mutating extended attributes (EA). If only theFILE_NOTIFY_CHANGE_EA
filter is requested, no events propagate.
Completion Filters and Corresponding Actions
The following table show the requested completion filters (grouped by the number of inode reads required to support them), the changes they watch for, and the actions corresponding to them.
Completion Filters | Actions | Description |
---|---|---|
The following filters watch for name changes ( • • |
• • • • • |
When Qumulo Core watches names, it notifies the client when there is an added, removed, or renamed file or directory in the watched directory.
|
The following filters watch for metadata changes ( • • • • • • Note
Qumulo doesn’t support mutating extended attributes (EA). If only the FILE_NOTIFY_CHANGE_EA filter is requested, no events propagate. |
FILE_ACTION_MODIFIED
|
When one of the watched attributes changes for an entry of the watched directory and the filter is requested, the client receives a Note
In Microsoft terminology, attributes are flags. For more information, see File Attributes in the Open Specification documentation. |
The following filters watch for alternative data stream (ADS) changes ( • • • Note
Qumulo Core doesn't support watching ADS changes. The following explanation is only informational. For more information, see Known CHANGE_NOTIFY Limitations for Qumulo Core. |
• • • |
Consider the following example command. echo "data" > watched_dir/file0:stream This command generates the following event. [ADDED_STREAM, file0:stream] When a name change takes place, Qumulo Core returns the |
Known CHANGE_NOTIFY Limitations for Qumulo Core
Qumulo Core doesn’t support the following workflows.
You must ensure that your application can handle the
STATUS_ENUM_DIR
response status that indicates to the SMB client that it needs to re-enumerate a directory manually. Depending on the library you use, this response might propagate as an error or an empty response.-
A
NOTIFY_CHANGE_STREAM
ADS completion filter is requested. -
The
SMB2_WATCH_TREE
flag is requested. Rather than watch a directory tree recursively, Qumulo Core handles theSMB2_WATCH_TREE
flag the same way it handles theCHANGE_STREAM
filters. -
The watched directory contains more than 5,000 entries.
-
The response buffer size is exceeded. Most third-party libraries limit this size to 64 Kb. At the maximum SMB file name length of 255 UTF-16 characters, this limit corresponds to roughly 200 simultaneous file renames.
-
The system reaches the heap usage quota for
CHANGE_NOTIFY
. In the worst scenario, this can correspond to more than 500 unique handles across all clients connected to a single Qumulo node.