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

// Use the <code>chrome.scripting</code> API to execute script in different
// contexts.
namespace scripting {
  callback InjectedFunction = void();

  // The origin for a style change.
  // See <href="https://developer.mozilla.org/en-US/docs/Glossary/Style_origin">style origins</href>
  // for more info.
  enum StyleOrigin {
    AUTHOR,
    USER
  };

  dictionary InjectionTarget {
    // The ID of the tab into which to inject.
    long tabId;

    // The <a href="https://developer.chrome.com/extensions/webNavigation#frame_ids">IDs</href>
    // of specific frames to inject into.
    long[]? frameIds;

    // Whether the script should inject into all frames within the tab. Defaults
    // to false.
    // This must not be true if <code>frameIds</code> is specified.
    boolean? allFrames;
  };

  dictionary ScriptInjection {
    // A JavaScript function to inject. This function will be serialized, and
    // then deserialized for injection. This means that any bound parameters
    // and execution context will be lost.
    // Exactly one of <code>files</code> and <code>function</code> must be
    // specified.
    [serializableFunction]InjectedFunction? function;

    // The path of the JS files to inject, relative to the extension's root
    // directory.
    // NOTE: Currently a maximum of one file is supported.
    // Exactly one of <code>files</code> and <code>function</code> must be
    // specified.
    DOMString[]? files;

    // Details specifying the target into which to inject the script.
    InjectionTarget target;
  };

  dictionary CSSInjection {
    // Details specifying the target into which to insert the CSS.
    InjectionTarget target;

    // A string containing the CSS to inject.
    // Exactly one of <code>files</code> and <code>css</code> must be
    // specified.
    DOMString? css;

    // The path of the CSS files to inject, relative to the extension's root
    // directory.
    // NOTE: Currently a maximum of one file is supported.
    // Exactly one of <code>files</code> and <code>css</code> must be
    // specified.
    DOMString[]? files;

    // The style origin for the injection. Defaults to <code>'AUTHOR'</code>.
    StyleOrigin? origin;
  };

  dictionary InjectionResult {
    // The result of the script execution.
    any? result;
  };

  callback ScriptInjectionCallback = void(InjectionResult[] results);

  callback CSSInjectionCallback = void();

  interface Functions {
    // Injects a script into a target context. The script will be run at
    // <code>document_end</code>.
    // |injection|: The details of the script which to inject.
    // |callback|: Invoked upon completion of the injection. The resulting
    // array contains the result of execution for each frame.
    static void executeScript(ScriptInjection injection,
                              optional ScriptInjectionCallback callback);

    // Inserts a CSS stylesheet into a target context.
    // |injection|: The details of the styles to insert.
    // |callback|: Invoked upon completion of the insertion.
    static void insertCSS(CSSInjection injection,
                          optional CSSInjectionCallback callback);
  };
};