// 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.diagnostics.inspect;

using fuchsia.mem;

struct JsonSettings {
    // Sets the indentation for the JSON output.
    // A value of 0 means to not include newlines or indent.
    int32 indent;
};

struct TextSettings {
    // Sets the indentation for the text output.
    int32 indent;
};

/// Criteria for how to format
/// the selected Inspect data.
flexible union DisplaySettings {
    1: JsonSettings json;
    2: TextSettings text;
};

// Specify settings for printing Inspect data.
table FormatSettings {
    1: DisplaySettings format;
};

/// Enums describing the potential fail states
/// of the reader service.
enum ReaderError {
    // An unimplemented ReaderSelector format was used.
    UNIMPLEMENTED_FORMAT = 1;
    // A provided selector did not adhere to the selector format.
    INVALID_SELECTOR = 2;
    // An error occured parsing the inspect data.
    IO = 3;
};

/// Selection criteria for data returned by the Reader service.
flexible union ReaderSelector {
    /// The reader applies the selection defined
    /// by structured_selector to all possible inspect data that it
    /// has access to, returning a potential subset, but not superset,
    /// of what would be returned by selection using only the system
    /// configuration.
    1: Selector structured_selector;

    /// The reader parses the string-based selector
    /// string_selector into a structured selector and then will apply
    /// the selection defined by structured_selector to all possible inspect
    /// data that it has access to, returning a potential subset, but
    /// not a superset of what would be returned by selection using only the
    /// system configuration.
    2: string:1024 string_selector;
};

[Discoverable]
protocol Reader {
    /// Adds a [fuchsia.diagnostics.inspect/ReaderSelector] to the Inspect instance,
    /// which will be used when determining which Inspect data to parse and return.
    /// + request `selector` a [fuchsia.diagnostics.inspect/ReaderSelector]
    ///   defining a specific component-hierarchy and inspect-tree pattern
    ///   of interest to the client.
    /// * error a [fuchsia.diagnostics.inspect/ReaderError]
    ///   value indicating how the call failed.
    ///   - `UNIMPLEMENTED_FORMAT` means that a selector whose format is
    ///     not yet supported was provided.
    ///
    ///   - `INVALID_SELECTOR` means that a selector which had an invalid
    ///     structure was passed in and failed verficiation.
    AddSelector(ReaderSelector selector) -> () error ReaderError;

    /// Removes all previously added ReaderSelectors from the Inspect instance.
    ClearSelectors();

    /// Parses the inspect data of the component hierarchy into a format
    /// specified by the [fuchsia.diagnostics.inspect/FormatSettings] struct,
    /// dump that formatted string to a VMO, and return a buffer to the VMO.
    ///
    /// The inspect data which is parsed is defined both by the static
    /// configuration of the service and the ReaderSelectors which are
    /// currently added to the instance. If no added ReaderSelectors
    /// have been added to the current instance, the default behavior
    /// is to parse all Inspect data that the instance has access to.
    ///
    /// + request `settings` the `fuchsia.diagnostics.inspect/FormatSettings` that
    ///   specifies the format of the read Inspect data.
    /// - response `inspect_data_result` the `fuchsia.mem/Buffer` which contains
    ///   the formatted inspect data.
    /// * error a [fuchsia.diagnostics.inspect/ReaderError]
    ///   value indicating how the call failed.
    ///   - `IO` means that parsing the Inspect VMO or writing the formatted data
    ///      failed.
    Format(FormatSettings settings) -> (fuchsia.mem.Buffer inspect_data_result) error ReaderError;
};