// Copyright 2018 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.accessibility;

using koid = uint64;

// A semantics root is an interface implemented by an accessibility manager. It stores semantic
// information on a per-view basis as supplied by front-ends. Each frontend pushes its semantic tree
// to the manager, which stores this data. In future, the manager will also forward this data to
// relevant client services. It also acts as a place for the manager to call actions on front-ends.
//
// This is a stub implementation and is currently a work in progress.
[Discoverable]
interface SemanticsRoot {
    // Registers a frontend with a view id to the root. To correlate views with their associated
    // clients, the semantic root uses view KOIDs as unique identifiers. All future updates that a
    // frontend makes need to include the view id. The frontend is required to pass a
    // SemanticsProvider interface on registration for the manager to call front-end accessibility
    // actions. Providers need to re-register on connection error.
    RegisterSemanticsProvider(
        koid view_id,
        SemanticsProvider provider);

    // Commits changes to node tree associated with the view_id using
    // UpdateSemanticNodes and DeleteSemanticNodes. This function must
    // always be called at the end of a full update push to signal the end of an update.
    // No-op if the client did not register that ID.

    // This commit system is used to allow for atomic changes of the tree that
    // exceed the FIDL transfer limit and allows both updates and deletes as part
    // of one commit. We give front-ends the responsibility of splitting a full update
    // into multiple update and delete calls that do not exceed FIDL transfer data limits.
    Commit(koid view_id);

    // Sends new/updated nodes to the root to add to the cache on the next commit.
    // No-op if the client did not register that ID.
    UpdateSemanticNodes(koid view_id, vector<Node> nodes);

    // Tells the root to remove nodes with node_ids from the frontend referenced by
    // view_id on the next commit. No-op if the client did not register that ID.
    DeleteSemanticNodes(koid view_id, vector<int32> node_ids);
};

// A semantic provider is the client-side interface that the manager can use to
// ask clients to perform accessibility actions.
interface SemanticsProvider {
    // Asks the semantics provider to perform an accessibility action on the
    // node with node id in the front-end.
    PerformAccessibilityAction(int32 node_id, Action action);
};