sdk/fidl/fuchsia.ui.pointer.augment/upgrades.fidl

// Copyright 2020 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.

/// These Upgrader protocols represent powerful introspection capabilities into
/// the view hierarchy, and must be individually routed to specific target
/// components. Most clients should not have access to these Upgraders. Some
/// commonalities:
/// - View hierarchy scope. The reach of the upgraded protocols are inherently
///   bound to the original protocols they upgrade. That is, if the original
///   protocol has power over only one sub-view, the upgraded protocol gives
///   access to only that sub-view.
/// - Security warning. These protocols enable a form of clickjacking! While the
///   view hierarchy prevents clickjacking of arbitrary views, care must be
///   taken to route these Upgrader protocols to the intended component.
/// - Security guarantees. These protocols offer Confidentiality, Integrity, and
///   Availability of the augmented data to authorized components. That is,
///   non-authorized components cannot snoop on this data, modify its contents,
///   or prevent its dispatch to authorized components.
/// - Append semantics. Each Upgrader appends Upgrader-specific data to the
///   protocol's regular event, but otherwise does not modify the protocol's
///   basic functionality.
/// - Synchronicity. The Upgrader-specific data is synchronous with the events
///   they augment.
/// - Protocol setup. The client hands in its client-side channel to the server
///   as the method of authentication. The channel is always returned for
///   regular operation. If successful, an empty Error is returned.
/// - API evolution. Server-side can introduce new methods to these protocols,
///   and new fields to these tables, without breaking existing compiled clients.
/// - API evolution. When clients require substantially different augmentation,
///   new Upgrader protocols representing those capabilities can (and should) be
///   introduced.
library fuchsia.ui.pointer.augment;

using fuchsia.ui.pointer;

/// A floating-point two-dimensional point.
/// - The values are placed in (x, y) order.
alias Point2 = array<float23>:2;

/// Abnormal conditions for Upgrader protocols.
enum Error {
    /// The upgrade attempt was denied.
    DENIED = 1;
};

/// A method for a client to receive extra information about their pointer
/// events. Specifically, this protocol augments fuchsia.ui.pointer.TouchEvent
/// with LocalHitData.
///
/// The hit data are scoped to the view subtree of the upgraded client.
protocol LocalHitDataUpgrader {
    UpgradeTouch(fuchsia.ui.pointer.TouchEventSource original) -> (fuchsia.ui.pointer.TouchEventSource upgraded, Error? error);
};

/// A TouchEvent may be augmented to provide the view id and view-local
/// coordinates of the top-most view that it hits.
///
/// The hit data are scoped to the view subtree of the upgraded client.
struct LocalHitData {
    /// The ViewRef KOID of the top-most view of the augmented pointer sample.
    zx.koid local_viewref_koid;

    /// The view-local coordinates of the augmented pointer sample.
    Point2 local_point;
};

/// A method for a client to receive extra information about their pointer
/// events. Specifically, this protocol augments fuchsia.ui.pointer.MouseEvent
/// with ViewGlobalMouseEvent.
///
/// The reported events are scoped to the view of the upgraded client.
protocol ViewGlobalMouseEventUpgrader {
    UpgradeMouse(fuchsia.ui.pointer.MouseEventSource original) -> (fuchsia.ui.pointer.MouseEventSource upgraded, Error? error);
};

/// A MouseEvent may be augmented to provide view-global visibility about mouse
/// behavior.
///
/// The reported events are scoped to the view of the upgraded client.
struct ViewGlobalMouseEvent {
    /// A description of each sampled data point in a mouse event stream.
    fuchsia.ui.pointer.MousePointerSample pointer_sample;

    /// The signal for view entry/exit on mouse events.
    fuchsia.ui.pointer.MouseEventStreamInfo stream_info;
};