zircon/system/fidl/fuchsia-io2/directory-watcher.fidl

// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.io2;

/// DirectoryWatcher transmits messages from a filesystem server about
/// events happening in the filesystem. Clients can register new watchers
/// using the [`fuchsia.io2/Directory.Watch`] method, where they can
/// filter which events they want to receive notifications for.
protocol DirectoryWatcher {
    /// A hanging get to obtain the next batch of events.
    ///
    /// The caller should always use a receiving buffer size as large as the
    /// maximum channel limit.
    ///
    /// Clients should attempt to maintain one in-flight `GetNext` call as much
    /// as possible. If `GetNext` is not constantly polled, the filesystem
    /// server might hit an upper limit on the number of buffered events,
    /// resulting in dropping. Should this happen, the connection will be closed
    /// with a `ZX_ERR_IO_OVERRUN` epitaph.
    ///
    /// When the watched directory is deleted, this connection will be closed
    /// with a `ZX_ERR_UNAVAILABLE` epitaph.
    /// When the filesystem server is dying, this connection will be closed
    /// with a `ZX_ERR_PEER_CLOSED` epitaph.
    GetNext()
        -> (vector<DirectoryWatchedEvent>:MAX_DIRECTORY_BATCH_SIZE events);
};

table DirectoryWatchOptions {
};

/// Events returned from [`DirectoryWatcher.GetNext`].
xunion DirectoryWatchedEvent {
    /// Indicates a node already existed in the directory when watching started.
    DirectoryEntry existing;

    /// Indicates that no more `existing` events will be sent.
    IdleEvent idle;

    /// Indicates a node has been created (either new or moved) into a
    /// directory.
    DirectoryEntry added;

    /// Indicates a node has been removed (either deleted or moved) from the
    /// directory.
    Name removed;
};

/// Used by [`fuchsia.io2/Directory.Watch`] to indicate the types of events
/// interested by a watcher.
bits DirectoryWatchMask : uint64 {
    /// Requests transmission of `existing` events.
    EXISTING = 0x01;

    /// Requests transmission of `idle` events.
    IDLE = 0x02;

    /// Requests transmission of `added` events.
    ADDED = 0x04;

    /// Requests transmission of `removed` events.
    REMOVED = 0x08;
};

struct IdleEvent {
};