blob: 631cdff6d63cef6e19aaf8705f21d9f327a6bef3 [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.element;
using fuchsia.mem;
/// Maximum length of `AnnotationKey.namespace`.
/// Maximum length of `AnnotationKey.value`.
/// Maximum number of annotations for a single element or view.
const MAX_ANNOTATIONS_PER_ELEMENT uint32 = 1024;
/// The key of an [`fuchsia.element/Annotation`].
type AnnotationKey = struct {
/// A namespace that disambiguates groups of keys across clients.
/// This is intended to group related keys together under the same
/// identifier, and avoid naming collisions. For example, a session may
/// use a custom namespace to define annotations that are specific
/// to its implementation.
/// The namespace is required and must be non-empty.
/// The namespace "global" is represents the global namespace, reserved for
/// annotations common across many products and session components.
/// To ensure compatibility, clients should use a unique namespace,
/// like a UUID or the client's component URL, when introducing new keys.
/// An identifier for this annotation, uniquely identifying the annotation
/// within `namespace`.
/// The value of an [`fuchsia.element/Annotation`].
/// The actual field used depends on the type of annotation.
type AnnotationValue = strict resource union {
1: text string:MAX;
2: buffer fuchsia.mem.Buffer;
/// An annotation defined dynamically by key/value pair.
/// The Session Framework does not constrain the contents of `key` and `value`
/// in any way. Cooperating components that exchange annotations must define
/// and validate annotation entries based on their own conventions.
type Annotation = resource struct {
/// An identfier for this annotation.
key AnnotationKey;
/// The content of this annotation.
value AnnotationValue;
/// A list of annotations on an element.
alias Annotations = vector<Annotation>:MAX_ANNOTATIONS_PER_ELEMENT;
/// A list of annotation keys.
alias AnnotationKeys = vector<AnnotationKey>:MAX_ANNOTATIONS_PER_ELEMENT;
/// An interface to create, read, update, and delete annotations,
/// typically on an element or its view.
protocol AnnotationController {
/// Adds, updates, and removes annotations.
/// The server is expected to adhere to the following conventions:
/// * If a key in `annotations_to_set` is new, a new annotation is added
/// * If a key in `annotations_to_set` already exists, the annotation value is updated
/// * If a key in `annotations_to_delete` does not exist, it is ignored
/// The same key cannot appear twice in a call to UpdateAnnotations(). In other words,
/// to set two Annotations with matching keys is illegal, as is an attempt to set an
/// Annotation and also delete it.
/// If the operation results in an error, the annotations remain unchanged,
/// and will not be partially updated.
/// * error `UpdateAnnotationsError.INVALID_ARGS` if the same key exists in
/// both `annotations_to_set` and `annotations_to_delete`.
/// * error `UpdateAnnotationsError.INVALID_ARGS` if a key in `annotations_to_set` or
/// `annotations_to_delete` has an empty namespace.
/// * error `UpdateAnnotationsError.INVALID_ARGS` if an `AnnotationValue.buffer` in
/// `annotations_to_set` could not be read.
/// * error `UpdateAnnotationsError.TOO_MANY_ANNOTATIONS` if the operation results
/// in more than `MAX_ANNOTATIONS_PER_ELEMENT` annotations existing.
UpdateAnnotations(resource struct {
annotations_to_set Annotations;
annotations_to_delete AnnotationKeys;
}) -> (struct {}) error UpdateAnnotationsError;
/// Returns the current `Annotations` for the element.
/// * error `GetAnnotationsError` if the annotations could not be returned.
GetAnnotations() -> (resource struct {
annotations Annotations;
}) error GetAnnotationsError;
/// Returns annotations when they have changed, or when this method is
/// called by the client for the first time.
/// This operation does not block other requests from the client, but only one
/// `WatchAnnotations` request at a time can be made on a connection. If the
/// client makes a second `WatchAnnotations` request before waiting for the
/// previous request to complete, the connection will be closed.
/// * error `WatchAnnotationsError` if the annotations could not be returned.
WatchAnnotations() -> (resource struct {
annotations Annotations;
}) error WatchAnnotationsError;
/// An error returned from `AnnotationController/UpdateAnnotations`
type UpdateAnnotationsError = strict enum {
/// The arguments passed to `UpdateAnnotations` are malformed.
/// The total number of annotations will exceed [`MAX_ANNOTATIONS_PER_ELEMENT`]
/// as a result of updating the annotations.
/// An error returned from `ElementController/GetAnnotations`.
type GetAnnotationsError = strict enum {
/// The `AnnotationValue.buffer` of an annotation could not be read.
/// An error returned from `AnnotationController/WatchAnnotations` and
/// `ElementController/WatchAnnotations`.
type WatchAnnotationsError = flexible enum {
/// The `AnnotationValue.buffer` of an annotation could not be read.