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 file system—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 shows the requested completion filters (grouped by the number of inode reads required to support them), the changes they watch for, and the actions that correspond 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 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]

Re-Enumerating Changes after the STATUS_ENUM_DIR Error

If the SMB client can’t keep up with the notification stream from the server, the server returns the STATUS_ENUM_DIR error code to the client and stops sending notifications.

In this scenario, the client must re-enumerate any changes that concern it directly, by opening and inspecting files, rather than relying on notifications. This scenario can happen because the request is too broad, for example, a recursive watch on the file system root.

Configuring Full Recursion for the WATCH_TREE Flag

By default, when a client supplies the WATCH_TREE flag, the server sends an error to the client immediately. In this scenario, you can configure your Qumulo cluster to support full recursion.