extensions/api/developer_private.idl

// Copyright (c) 2012 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.

// developerPrivate API.
// This is a private API exposing developing and debugging functionalities for
// apps and extensions.
namespace developerPrivate {

  enum ItemType {
    hosted_app,
    packaged_app,
    legacy_packaged_app,
    extension,
    theme
  };

  dictionary ItemInspectView {
    // path to the inspect page.
    DOMString path;

    // For lazy background pages, the value is -1.
    long render_process_id;

    long render_view_id;
    boolean incognito;
    boolean generatedBackgroundPage;
  };

  dictionary InstallWarning {
    DOMString message;
  };

  dictionary ItemInfo {
    DOMString id;
    DOMString name;
    DOMString version;
    DOMString description;
    boolean may_disable;
    boolean enabled;
    DOMString? disabled_reason;
    boolean isApp;
    ItemType type;
    boolean allow_activity;
    boolean allow_file_access;
    boolean wants_file_access;
    boolean incognito_enabled;
    boolean is_unpacked;
    boolean allow_reload;
    boolean terminated;
    boolean allow_incognito;
    DOMString icon_url;

    // Path of an unpacked extension.
    DOMString? path;

    // Options settings page for the item.
    DOMString? options_url;
    DOMString? app_launch_url;
    DOMString? homepage_url;
    DOMString? update_url;
    InstallWarning[] install_warnings;
    any[] manifest_errors;
    any[] runtime_errors;
    boolean offline_enabled;

    // All views of the current extension.
    ItemInspectView[] views;
  };

  dictionary InspectOptions {
    DOMString extension_id;
    DOMString render_process_id;
    DOMString render_view_id;
    boolean incognito;
  };

  enum PackStatus {
    SUCCESS,
    ERROR,
    WARNING
  };

  enum FileType {
    LOAD,
    PEM
  };

  enum SelectType {
    FILE,
    FOLDER
  };

  enum EventType {
    INSTALLED,
    UNINSTALLED,
    LOADED,
    UNLOADED,
    // New window / view opened.
    VIEW_REGISTERED,
    // window / view closed.
    VIEW_UNREGISTERED,
    ERROR_ADDED
  };

  dictionary PackDirectoryResponse {
    // The response message of success or error.
    DOMString message;

    // Unpacked items's path.
    DOMString item_path;

    // Permanent key path.
    DOMString pem_path;

    long override_flags;
    PackStatus status;
  };

  dictionary ProjectInfo {
    DOMString name;
  };

  dictionary EventData {
    EventType event_type;
    DOMString item_id;
  };

  callback VoidCallback = void ();
  callback BooleanCallback = void (boolean result);
  callback ItemsInfoCallback = void (ItemInfo[] result);
  callback GetProjectsInfoCallback = void (ProjectInfo[] result);
  callback PathCallback = void (DOMString path);
  callback PackCallback = void (PackDirectoryResponse response);
  callback VoidCallback = void();
  callback AnyCallback = void (any result);

  interface Functions {
    // Runs auto update for extensions and apps immediately.
    // |callback| : Called with the boolean result, true if autoUpdate is
    // successful.
    static void autoUpdate(BooleanCallback callback);

    // Returns information of all the extensions and apps installed.
    // |include_disabled| : include disabled items.
    // |include_terminated| : include terminated items.
    // |callback| : Called with items info.
    static void getItemsInfo(boolean include_disabled,
                             boolean include_terminated,
                             ItemsInfoCallback callback);

    // Opens a permissions dialog for given |itemId|.
    static void showPermissionsDialog(DOMString itemId,
                                      optional VoidCallback callback);

    // Opens an inspect window for given |options|
    static void inspect(InspectOptions options,
                        optional VoidCallback callback);

    // Enable / Disable file access for a given |item_id|
    static void allowFileAccess(DOMString item_id,
                                boolean allow,
                                optional VoidCallback callback);

    // Reloads a given item with |itemId|.
    static void reload(DOMString itemId, optional VoidCallback callback);

    // Enable / Disable a given item with id |itemId|.
    static void enable(DOMString itemId,
                       boolean enable,
                       optional VoidCallback callback);

    // Allow / Disallow item with |item_id| in incognito mode.
    static void allowIncognito(DOMString item_id,
                               boolean allow,
                               VoidCallback callback);

    // Load a user selected unpacked item
    static void loadUnpacked(optional VoidCallback callback);

    // Loads an extension / app from a given |directory|
    static void loadDirectory([instanceOf=DirectoryEntry] object directory,
                        PathCallback callback);

    // Open Dialog to browse to an entry.
    // |select_type| : Select a file or a folder.
    // |file_type| : Required file type. For Example pem type is for private
    // key and load type is for an unpacked item.
    // |callback| : called with selected item's path.
    static void choosePath(SelectType select_type,
                           FileType file_type,
                           PathCallback callback);

    // Pack an item with given |path| and |private_key_path|
    // |callback| : called with the success result string.
    static void packDirectory(DOMString path,
                              DOMString private_key_path,
                              long flags,
                              PackCallback callback);

    // Returns true if the profile is managed.
    static void isProfileManaged(BooleanCallback callback);

    // Reads and returns the contents of a file related to an extension which
    // caused an error. The expected argument is a dictionary with the
    // following entries:
    // - pathSuffix: The path of the file, relative to the extension; e.g.,
    //       manifest.json, script.js, or main.html.
    // - extensionId: The ID of the extension owning the file.
    // - errorMessage: The error message which was thrown as a result of the
    //       error in the file.
    // - manifestKey (required for "manifest.json" file): The key
    //       in the manifest which caused the error (e.g., "permissions").
    // - manifestSpecific (optional for "manifest.json" file): The specific
    //       portion of the manifest key which caused the error (e.g., "foo" in
    //       the "permissions" key).
    // - lineNumber (optional for non-manifest files): The line number which
    //       caused the error.
    // The callback is called with a dictionary with three keys:
    // - highlight: The region of the code which threw the error, and should
    //       be highlighted.
    // - beforeHighlight: The region before the "highlight" portion.
    // - afterHighlight: The region after the "highlight" portion.
    // - highlight: The region of the code which threw the error.
    // If the region which threw the error was not found, the full contents of
    // the file will be in the "beforeHighlight" section.
    static void requestFileSource(any dict, AnyCallback callback);

    // Open the developer tools to focus on a particular error. The expected
    // argument is a dictionary with the following entries:
    // - renderViewId: The ID of the render view in which the error occurred.
    // - renderProcessId: The ID of the process in which the error occurred.
    // - url (optional): The URL in which the error occurred.
    // - lineNumber (optional): The line to focus the devtools at.
    // - columnNumber (optional): The column to focus the devtools at.
    static void openDevTools(any dict);
  };

  interface Events {
    // Fired when a item state is changed.
    static void onItemStateChanged(EventData response);
  };

};