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.

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)

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 (readdir-without-attrs).

• FILE_NOTIFY_CHANGE_DIR_NAME

• FILE_NOTIFY_CHANGE_FILE_NAME

• FILE_ACTION_ADDED

• FILE_ACTION_MODIFIED

• FILE_ACTION_REMOVED

• FILE_ACTION_RENAMED_NEW_NAME

• FILE_ACTION_RENAMED_OLD_NAME

When Qumulo Core watches names, it notifies the client when there is an added, removed, or renamed file or directory in the watched directory.

  • A delete event sends both REMOVED and MODIFIED notifications.
  • A rename event sends separate, consecutive events for OLD and NEW names, for example:
    [REMOVED, file_old_name],
    [ADDED, file_new_name]

The following filters watch for metadata changes (readdir-with-attrs).

• FILE_NOTIFY_CHANGE_ATTRIBUTES

• FILE_NOTIFY_CHANGE_CREATION

• FILE_NOTIFY_CHANGE_SECURITY

• FILE_NOTIFY_CHANGE_SIZE

• FILE_NOTIFY_CHANGE_LAST_ACCESS

• FILE_NOTIFY_CHANGE_LAST_WRITE

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 MODIFIED event.

The following filters watch for alternative data stream (ADS) changes (readdir-attrs-and-stream-names).

• FILE_NOTIFY_CHANGE_STREAM_NAME

• FILE_NOTIFY_CHANGE_STREAM_SIZE

• FILE_NOTIFY_CHANGE_STREAM_WRITE

• FILE_ACTION_ADDED_STREAM

• FILE_ACTION_REMOVED_STREAM

• FILE_ACTION_MODIFIED_STREAM

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 STATUS_ENUM_DIR message that indicates that the client should perform its own directory read.

Known CHANGE_NOTIFY Limitations for Qumulo Core

Qumulo Core doesn’t support the following workflows.

  • 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 the SMB2_WATCH_TREE flag the same way it handles the CHANGE_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.