blob: b9ba70441cdf6a7ea4760f92ef51809e318ed6d8 [file] [log] [blame]
// 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 {
};