chrome/common/extensions/api/scripting.idl

// Copyright 2020 The Chromium Authors
// 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 <a href="https://developer.mozilla.org/en-US/docs/Glossary/Style_origin">style origins</a>
  // for more info.
  enum StyleOrigin {
    AUTHOR,
    USER
  };

  // The JavaScript world for a script to execute within.
  enum ExecutionWorld {
    // Specifies the isolated world, which is the execution environment unique
    // to this extension.
    ISOLATED,
    // Specifies the main world of the DOM, which is the execution environment
    // shared with the host page's JavaScript.
    MAIN
  };

  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</a>
    // of specific frames to inject into.
    long[]? frameIds;

    // The <a href="https://developer.chrome.com/extensions/webNavigation#document_ids">IDs</a>
    // of specific documentIds to inject into. This must not be set if
    // <code>frameIds</code> is set.
    DOMString[]? documentIds;

    // 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> or <code>func</code> must be
    // specified.
    [serializableFunction]InjectedFunction? func;

    // The arguments to pass to the provided function. This is only valid if
    // the <code>func</code> parameter is specified. These arguments must be
    // JSON-serializable.
    any[]? args;

    // We used to call the injected function `function`, but this is
    // incompatible with JavaScript's object declaration shorthand (see
    // https://crbug.com/1166438). We leave this silently in for backwards
    // compatibility.
    // TODO(devlin): Remove this in M95.
    [nodoc, serializableFunction]InjectedFunction? function;

    // The path of the JS or CSS files to inject, relative to the extension's
    // root directory.
    // Exactly one of <code>files</code> or <code>func</code> must be
    // specified.
    DOMString[]? files;

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

    // The JavaScript "world" to run the script in. Defaults to
    // <code>ISOLATED</code>.
    ExecutionWorld? world;

    // Whether the injection should be triggered in the target as soon as
    // possible. Note that this is not a guarantee that injection will occur
    // prior to page load, as the page may have already loaded by the time the
    // script reaches the target.
    boolean? injectImmediately;
  };

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

    // The frame associated with the injection.
    long frameId;

    // The document associated with the injection.
    DOMString documentId;
  };

  // Describes a content script to be injected into a web page registered
  // through this API.
  dictionary RegisteredContentScript {
    // The id of the content script, specified in the API call. Must not start
    // with a '_' as it's reserved as a prefix for generated script IDs.
    DOMString id;
    // Specifies which pages this content script will be injected into. See
    // <a href="develop/concepts/match-patterns">Match Patterns</a> for more
    // details on the syntax of these strings. Must be specified for
    // $(ref:registerContentScripts).
    DOMString[]? matches;
    // Excludes pages that this content script would otherwise be injected into.
    // See <a href="develop/concepts/match-patterns">Match Patterns</a> for
    // more details on the syntax of these strings.
    DOMString[]? excludeMatches;
    // The list of CSS files to be injected into matching pages. These are
    // injected in the order they appear in this array, before any DOM is
    // constructed or displayed for the page.
    DOMString[]? css;
    // The list of JavaScript files to be injected into matching pages. These
    // are injected in the order they appear in this array.
    DOMString[]? js;
    // If specified true, it will inject into all frames, even if the frame is
    // not the top-most frame in the tab. Each frame is checked independently
    // for URL requirements; it will not inject into child frames if the URL
    // requirements are not met. Defaults to false, meaning that only the top
    // frame is matched.
    boolean? allFrames;
    // Indicates whether the script can be injected into frames where the URL
    // contains an unsupported scheme; specifically: about:, data:, blob:, or
    // filesystem:. In these cases, the URL's origin is checked to determine if
    // the script should be injected. If the origin is `null` (as is the case
    // for data: URLs) then the used origin is either the frame that created
    // the current frame or the frame that initiated the navigation to this
    // frame. Note that this may not be the parent frame.
    boolean? matchOriginAsFallback;
    // Specifies when JavaScript files are injected into the web page. The
    // preferred and default value is <code>document_idle</code>.
    extensionTypes.RunAt? runAt;
    // Specifies if this content script will persist into future sessions. The
    // default is true.
    boolean? persistAcrossSessions;
    // The JavaScript "world" to run the script in. Defaults to
    // <code>ISOLATED</code>.
    ExecutionWorld? world;
  };

  // An object used to filter content scripts for
  // ${ref:getRegisteredContentScripts}.
  dictionary ContentScriptFilter {
    // If specified, $(ref:getRegisteredContentScripts) will only return scripts
    // with an id specified in this list.
    DOMString[]? ids;
  };

  callback ScriptInjectionCallback = void(InjectionResult[] results);

  callback CSSInjectionCallback = void();

  callback RegisterContentScriptsCallback = void();

  callback GetRegisteredContentScriptsCallback = void(
      RegisteredContentScript[] scripts);

  callback UnregisterContentScriptsCallback = void();

  callback UpdateContentScriptsCallback = void();

  interface Properties {
    // An object available for content scripts running in isolated worlds to use
    // and modify as a JS object. One instance exists per frame and is shared
    // between all content scripts for a given extension. This object is
    // initialized when the frame is created, before document_start.
    // TODO(crbug.com/40119604): Enable this once implementation is complete.
    [nodoc, nocompile] static long globalParams();
  };

  interface Functions {
    // Injects a script into a target context. By default, the script will be run
    // at <code>document_idle</code>, or immediately if the page has already
    // loaded. If the <code>injectImmediately</code> property is set, the script
    // will inject without waiting, even if the page has not finished loading. If
    // the script evaluates to a promise, the browser will wait for the promise to
    // settle and return the resulting value.
    // |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 where the
    // injection succeeded.
    static void executeScript(
        ScriptInjection injection,
        optional ScriptInjectionCallback callback);

    // Inserts a CSS stylesheet into a target context.
    // If multiple frames are specified, unsuccessful injections are ignored.
    // |injection|: The details of the styles to insert.
    // |callback|: Invoked upon completion of the insertion.
    static void insertCSS(
        CSSInjection injection,
        optional CSSInjectionCallback callback);

    // Removes a CSS stylesheet that was previously inserted by this extension
    // from a target context.
    // |injection|: The details of the styles to remove. Note that the
    // <code>css</code>, <code>files</code>, and <code>origin</code> properties
    // must exactly match the stylesheet inserted through $(ref:insertCSS).
    // Attempting to remove a non-existent stylesheet is a no-op.
    // |callback|: A callback to be invoked upon the completion of the removal.
    static void removeCSS(
        CSSInjection injection,
        optional CSSInjectionCallback callback);

    // Registers one or more content scripts for this extension.
    // |scripts|: Contains a list of scripts to be registered. If there are
    // errors during script parsing/file validation, or if the IDs specified
    // already exist, then no scripts are registered.
    // |callback|: A callback to be invoked once scripts have been fully
    // registered or if an error has occurred.
    static void registerContentScripts(
        RegisteredContentScript[] scripts,
        optional RegisterContentScriptsCallback callback);

    // Returns all dynamically registered content scripts for this extension
    // that match the given filter.
    // |filter|: An object to filter the extension's dynamically registered
    // scripts.
    static void getRegisteredContentScripts(
        optional ContentScriptFilter filter,
        GetRegisteredContentScriptsCallback callback);

    // Unregisters content scripts for this extension.
    // |filter|: If specified, only unregisters dynamic content scripts which
    // match the filter. Otherwise, all of the extension's dynamic content
    // scripts are unregistered.
    // |callback|: A callback to be invoked once scripts have been unregistered
    // or if an error has occurred.
    static void unregisterContentScripts(
        optional ContentScriptFilter filter,
        optional UnregisterContentScriptsCallback callback);

    // Updates one or more content scripts for this extension.
    // |scripts|: Contains a list of scripts to be updated. A property is only
    // updated for the existing script if it is specified in this object. If
    // there are errors during script parsing/file validation, or if the IDs
    // specified do not correspond to a fully registered script, then no scripts
    // are updated.
    // |callback|: A callback to be invoked once scripts have been updated or
    // if an error has occurred.
    static void updateContentScripts(
        RegisteredContentScript[] scripts,
        optional RegisterContentScriptsCallback callback);
  };
};