// 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() -> (struct {
        events vector<DirectoryWatchedEvent>:MAX_DIRECTORY_BATCH_SIZE;
    });
};

type DirectoryWatchOptions = table {};

/// Events returned from [`DirectoryWatcher.GetNext`].
type DirectoryWatchedEvent = flexible union {
    /// Indicates a node already existed in the directory when watching started.
    1: existing DirectoryEntry;

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

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

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

/// Used by [`fuchsia.io2/Directory.Watch`] to indicate the types of events
/// interested by a watcher.
type DirectoryWatchMask = strict bits : 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;
};

type IdleEvent = struct {};