// 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.session;

using fuchsia.mem;

/// The value of a [`fuchsia.session/Entry`].
///
/// The actual field used depends on the type of annotation.
union Value {
    1: string:MAX text;
    2: fuchsia.mem.Buffer buffer;
};

/// An annotation defined dynamically by key/value pair.
///
/// The `Key`, `Value` type, and legal values are not enforced by the Session Framework. Cooperating
/// components that exchange annotations must define and validate annotation entries based on their
/// own conventions.
struct Annotation {
    /// An identfier for this annotation.
    string:MAX key;

    /// The content of this annotation.
    Value? value;
};

/// Error returned from calls to SetAnnotations() or GetAnnotations().
enum AnnotationError {
    /// The session rejected the annotations to add to the controlled element.
    /// Reasons for rejection may be due to annotations that violate defined
    /// type constraints, such as:
    ///   * The `Value` size exceeds the maximum length.
    ///   * The total number of annotations on an element exceeds `MAX`
    REJECTED = 1;

    /// The element failed to return the annotations from a call to get_annotations()/
    /// Reasons for the failure may be due to inability to read buffer bytes.
    NOT_FOUND = 2;
};

// NOTE: `Annotations` is a table (and not a type alias) to anticipate the possibility that
// `Annotations` may be extended with additional well-known annotations, using hard-coded
// table fields of any legal type.
/// Contains the annotations applied to an Element.
table Annotations {
    /// A list of dynamically-defined annotations.
    1: vector<Annotation>:MAX custom_annotations;
};