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.viewsv1token;

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

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

interface 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.
  CreateView2(handle<eventpair> view_token,
                 request<fuchsia.sys.ServiceProvider>? incoming_services,
                 fuchsia.sys.ServiceProvider? outgoing_services);

  // Deprecated.
  // TODO(crbug.com/899348): Update all code to use CreateView2()
  // and remove CreateView().
  CreateView(request<fuchsia.ui.viewsv1token.ViewOwner> view_owner,
                request<fuchsia.sys.ServiceProvider>? 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.
  //
  // 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.
  // TODO(crbug.com/900391): Investigate if we can run the scripts in isolated
  // JS worlds.
  //
  // 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.
  ExecuteJavaScript(
     vector<string> origins, fuchsia.mem.Buffer script, ExecuteMode mode) ->
     (bool success);

  // 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);
};

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.
interface 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);
};