zircon/system/fidl/fuchsia-inspect/tree.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.inspect;
using fuchsia.mem;

/// Maximum length of an Inspect Tree, specified by the format.
const uint64 MAX_TREE_NAME_LENGTH = 2040;

/// Maximum number of children returned by a single read of the tree name iterator.
const uint64 MAX_TREE_NAME_LIST_SIZE = 64;

using TreeName = string:MAX_TREE_NAME_LENGTH;

/// The content of a specific Inspect Tree.
table TreeContent {
    /// Buffer containing the bytes of a tree in Inspect format.
    1: fuchsia.mem.Buffer buffer;

    /// Describes the current state of the buffer, which informs the
    /// reader how to interpet it (see below).
    2: TreeState state;
};

/// The state of the buffer returned in a TreeContent.
enum TreeState {
    /// The VMO backing the buffer is still in use. Clients must interpret
    /// the whole buffer accoring to the Inspect format reading algorithm.
    IN_USE = 1;

    /// The VMO backing the buffer is complete, and will not be modified further.
    /// Clients may read the buffer without performing the whole
    /// consistency algorithm, but they should still be wary of the input.
    COMPLETE = 2;
};

/// Iterator protocol for listing the names of children of a particular Tree.
protocol TreeNameIterator {
    /// Get the next batch of names.
    ///
    /// Returns an empty vector and closes the channel when no more names are present.
    /// Implementors may eagerly close the channel after sending the last batch.
    GetNext() -> (vector<TreeName>:MAX_TREE_NAME_LIST_SIZE name);
};

/// The Tree protocol represents a hierarchy of Inspect VMOs.
[Discoverable]
protocol Tree {
    /// Get the content for the Inspect VMO backing this tree.
    GetContent() -> (TreeContent content);

    /// Iterate over the names of Trees that are children of this Tree.
    ListChildrenNames(request<TreeNameIterator> tree_iterator);

    /// Open a child Tree by name.
    ///
    /// If the child cannot be opened, the given request is closed.
    OpenChild(TreeName child_name, request<Tree> tree);
};