blob: 58648d32aecf703562e4c294beb61b56a0d8b2ac [file] [log] [blame]
// 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.
/// Evaluate the script on all subsequent page loads.
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( 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( Investigate if we can run the scripts in isolated
// JS worlds.
// TODO( Replace this with a method focused exclusively on
// immediate JS execution.
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 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.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( 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);