| // 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 augmentation 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 protocols. Some |
| /// commonalities: |
| /// - Theory of operation. These augmentation protocols accept a standard |
| /// protocol endpoint and return an augmented protocol endpoint. In case of |
| /// error, the original endpoint is returned. |
| /// - View hierarchy scope. The reach of the augmented protocols are inherently |
| /// bound to the original protocols they augment. That is, if the original |
| /// protocol has power over only one view, the augmented protocol gives access |
| /// to only that 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 augmentation protocols to the intended view's |
| /// 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 augmentation provides augmentation-specific data to |
| /// the protocol's regular event, but otherwise is not intended to modify the |
| /// original protocol's basic functionality. |
| /// - Synchronicity. The augmentation-specific data is synchronous with the |
| /// original protocol's data. |
| /// - API evolution. Server-side can introduce new methods to these protocols, |
| /// and new fields to these tables, without breaking existing clients of the |
| /// original or augmented protocol. |
| /// - API evolution. When clients require substantially different augmentation, |
| /// new augmentation protocols representing those capabilities can (and |
| /// should) be introduced. |
| @available(added=7) |
| library fuchsia.ui.pointer.augment; |
| |
| using fuchsia.ui.pointer as pointer; |
| using zx; |
| |
| /// Abnormal conditions for augmentation protocols. |
| type ErrorReason = strict enum { |
| /// The augmentation attempt was denied. |
| DENIED = 1; |
| }; |
| |
| // LOCAL HIT AUGMENTATION |
| |
| // Abnormal return for local hit. |
| type ErrorForLocalHit = resource struct { |
| /// Abnormal reason for return. |
| error_reason ErrorReason; |
| |
| /// Original protocol endpoint for client use. |
| original client_end:pointer.TouchSource; |
| }; |
| |
| /// A method for a client to upgrade its touch event protocol to additionally |
| /// receive local-hit data for touch events. |
| @discoverable |
| closed protocol LocalHit { |
| /// An exchange from an `original` touch protocol endpoint to an `augmented` |
| /// touch protocol endpoint. If successful, `error` is empty, `original` is |
| /// consumed, and `augmented` is returned for the client's use. Otherwise, |
| /// the `error` carries back `original` for the client's use, and |
| /// `augmented` is null. |
| strict Upgrade(resource struct { |
| original client_end:pointer.TouchSource; |
| }) -> (resource struct { |
| augmented client_end:<TouchSourceWithLocalHit, optional>; |
| error box<ErrorForLocalHit>; |
| }); |
| }; |
| |
| /// Like [`fuchsia.ui.pointer.TouchSource`], but with additional information |
| /// about the local-hit position of touch events, and otherwise identical in |
| /// operation. See [`fuchsia.ui.pointer.TouchSource`] for regular usage |
| /// information. |
| closed protocol TouchSourceWithLocalHit { |
| /// Identical usage to [`fuchsia.ui.pointer.TouchSource.Watch`], but with |
| /// augmented data. |
| strict Watch(struct { |
| responses vector<pointer.TouchResponse>:pointer.TOUCH_MAX_EVENT; |
| }) -> (struct { |
| events vector<TouchEventWithLocalHit>:pointer.TOUCH_MAX_EVENT; |
| }); |
| /// Identical usage to [`fuchsia.ui.pointer.TouchSource.UpdateResponse`]. |
| strict UpdateResponse(struct { |
| interaction pointer.TouchInteractionId; |
| response pointer.TouchResponse; |
| }) -> (); |
| }; |
| |
| /// A floating point two-dimensional point. |
| /// - The values are placed in (x, y) order. |
| alias Point2 = array<float32, 2>; |
| |
| /// An augmentation of [`fuchsia.ui.pointer.TouchEvent`] to provide local-hit |
| /// data for a touch event. |
| /// |
| /// For a given touch event `e`, consider the ordered list of intersections with |
| /// graphical content: its "hits" from top to bottom. The "local hit" of `e` is |
| /// the location of `e` in the coordinate system of the view in which `e` has |
| /// the top-most intersection. |
| type TouchEventWithLocalHit = struct { |
| /// Identical usage to [`fuchsia.ui.pointer.TouchEvent`]. |
| touch_event pointer.TouchEvent; |
| |
| /// Augmented data for `touch_event` that describes the top-most client |
| /// KOID that it hits. |
| local_viewref_koid zx.Koid; |
| |
| /// Augmented data for `touch_event` that describes its local coordinates in |
| /// the coordinate space for `local_viewref_koid`. |
| local_point Point2; |
| }; |