fuchsia/fidl/web/frame.fidl

// Copyright 2018 The Chromium 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 chromium.web;

using fuchsia.mem;
using fuchsia.sys;
using fuchsia.ui.views;

enum ExecuteMode {
  /// Evaluate the script immediately.
  IMMEDIATE_ONCE = 1;
  /// Evaluate the script on all subsequent page loads.
  ON_PAGE_LOAD = 2;
};

enum LogLevel : int32 {
  /// No logging.
  NONE = 100;
  /// Outputs messages from console.debug().
  DEBUG = -1;
  /// Outputs messages from console.log().
  INFO = 0;
  /// Outputs messages from console.warn().
  WARN = 1;
  /// Outputs messages from console.error().
  ERROR = 2;
};

protocol Frame {
  /// Creates a new view using the specified |view_token|. Caller should pass
  /// the other end of the token to CreateViewHolderCmd() to attach the new view
  /// to a the view tree.
  ///
  /// |view_token|: Token for the new view.
  CreateView(fuchsia.ui.views.ViewToken view_token);

  // Deprecated.
  // TODO(crbug.com/899348): Update all code to use CreateView()
  // and remove CreateView2().
  CreateView2(handle<eventpair> view_token,
              request<fuchsia.sys.ServiceProvider>? incoming_services,
              fuchsia.sys.ServiceProvider? outgoing_services);

  /// Returns an interface through which the frame may be navigated to
  /// a desired URL, reloaded, etc.
  ///
  /// |view_provider|: An interface request for the Frame's
  /// NavigationController.
  GetNavigationController(request<NavigationController> controller);

  /// Executes |script| in the frame if the frame's URL has an origin which
  /// matches entries in |origins|.
  /// At least one |origins| entry must be specified.
  /// If a wildcard "*" is specified in |origins|, then the script will be
  /// evaluated for all documents.
  /// If |mode| is NOW, then the script is evaluated immediately.
  /// If |mode| is ON_PAGE_LOAD, then the script is evaluated on every future
  /// document load prior to the page's script's execution.
  //  Note: ON_PAGE_LOAD is deprecated, please use AddJavaScriptBindings()
  //  instead.
  ///
  /// Multiple scripts can be registered by calling ExecuteJavascript()
  /// repeatedly.
  ///
  /// Note that scripts share the same execution context as the document,
  /// meaning that document may modify variables, classes, or objects set by the
  /// script in arbitrary or unpredictable ways.
  ///
  /// Returns |true| if the script was executed, |false| if the script was
  /// rejected due to injection being blocked by the parent Context, or because
  /// the script's text encoding was invalid.
  //
  // TODO(crbug.com/900391): Investigate if we can run the scripts in isolated
  // JS worlds.
  // TODO(crbug.com/939064): Replace this with a method focused exclusively on
  // immediate JS execution.
  ExecuteJavaScript(
     vector<string> origins, fuchsia.mem.Buffer script, ExecuteMode mode) ->
     (bool success);

  /// Executes |script| for every subsequent page load where the frame's
  /// URL has an origin reflected in |origins|. The script is executed early,
  /// prior to the execution of the document's scripts.
  ///
  /// Scripts are identified by a the client-managed identifier |id|. Any
  /// script previously injected using the same |id| will be replaced.
  ///
  /// The order in which multiple bindings are executed is the same as the
  /// order in which the bindings were Added. If a script is added which
  /// clobbers an existing script of the same |id|, the previous script's
  /// precedence in the injection order will be preserved.
  ///
  /// At least one |origins| entry must be specified.
  /// If a wildcard "*" is specified in |origins|, then the script will be
  /// evaluated for all documents.
  AddJavaScriptBindings(uint64 id, vector<string> origins,
                        fuchsia.mem.Buffer script) -> (bool success);

  /// Removes a previously added JavaScript snippet identified by |id|.
  /// Always returns |true|, it is safe to ignore the return value.
  RemoveJavaScriptBindings(uint64 id) -> (bool removed);

  /// Posts a message to the frame's onMessage handler.
  ///
  /// |targetOrigin| restricts message delivery to the specified origin.
  /// If |targetOrigin| is "*", then the message will be sent to the document
  /// regardless of its origin.
  /// See html.spec.whatwg.org/multipage/web-messaging.html sect. 9.4.3
  /// for more details on how the target origin policy is applied.
  ///
  /// Returns |false| if |message| is invalid or |targetOrigin| is missing.
  PostMessage(WebMessage message, string targetOrigin) -> (bool success);

  /// Sets the observer for handling page navigation events.
  ///
  /// |observer|: The observer to use. Unregisters any existing observers
  ///             if null.
  SetNavigationEventObserver(NavigationEventObserver? observer);

  /// If set to a value other than NONE, allows web content to log messages
  /// to the system logger using console.log(), console.info(), console.warn(),
  /// and console.error().
  SetJavaScriptLogLevel(LogLevel level);

  /// Used at runtime to enables or disables user input processing
  /// (e.g. keyboard, mouse, touch) on a Frame.
  /// Input is enabled by default.
  SetEnableInput(bool enable_input);
};

struct WebMessage {
  /// The message payload, encoded as an UTF-8 string.
  fuchsia.mem.Buffer data;

  /// List of objects transferred into the MessagePort from the FIDL client.
  // TODO(crbug.com/893236): make this a vector when FIDL-354 is fixed.
  IncomingTransferable? incoming_transfer;

  /// List of objects transferred out of the MessagePort to the FIDL client.
  OutgoingTransferable? outgoing_transfer;
};

union OutgoingTransferable {
  request<MessagePort> message_port;
};

union IncomingTransferable {
  MessagePort message_port;
};

/// Represents one end of an HTML5 MessageChannel. Can be used to send
/// and exchange Messages with the peered MessagePort in the Frame's script
/// context. The port is destroyed when either end of the MessagePort channel
/// is torn down.
protocol MessagePort {
  /// Sends a WebMessage to the peer.
  PostMessage(WebMessage message) -> (bool success);

  /// Asynchronously reads the next message from the channel.
  /// The client should invoke the callback when it is ready to process
  /// another message.
  /// Unreceived messages are buffered on the sender's side and bounded
  /// by its available resources.
  ReceiveMessage() -> (WebMessage message);
};