chrome/common/extensions/api/developer_private.idl

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // developerPrivate API.
   6 // This is a private API exposing developing and debugging functionalities for
   7 // apps and extensions.
   8 namespace developerPrivate {
   9
  10   enum ItemType {
  11     hosted_app,
  12     packaged_app,
  13     legacy_packaged_app,
  14     extension,
  15     theme
  16   };
  17
  18   dictionary ItemInspectView {
  19     // path to the inspect page.
  20     DOMString path;
  21
  22     // For lazy background pages, the value is -1.
  23     long render_process_id;
  24
  25     long render_view_id;
  26     boolean incognito;
  27     boolean generatedBackgroundPage;
  28   };
  29
  30   dictionary InstallWarning {
  31     DOMString message;
  32   };
  33
  34   dictionary ItemInfo {
  35     DOMString id;
  36     DOMString name;
  37     DOMString version;
  38     DOMString description;
  39     boolean may_disable;
  40     boolean enabled;
  41     DOMString? disabled_reason;
  42     boolean isApp;
  43     ItemType type;
  44     boolean allow_activity;
  45     boolean allow_file_access;
  46     boolean wants_file_access;
  47     boolean incognito_enabled;
  48     boolean is_unpacked;
  49     boolean allow_reload;
  50     boolean terminated;
  51     boolean allow_incognito;
  52     DOMString icon_url;
  53
  54     // Path of an unpacked extension.
  55     DOMString? path;
  56
  57     // Options settings page for the item.
  58     DOMString? options_url;
  59     DOMString? app_launch_url;
  60     DOMString? homepage_url;
  61     DOMString? update_url;
  62     InstallWarning[] install_warnings;
  63     any[] manifest_errors;
  64     any[] runtime_errors;
  65     boolean offline_enabled;
  66
  67     // All views of the current extension.
  68     ItemInspectView[] views;
  69   };
  70
  71   dictionary InspectOptions {
  72     DOMString extension_id;
  73     DOMString render_process_id;
  74     DOMString render_view_id;
  75     boolean incognito;
  76   };
  77
  78   dictionary ReloadOptions {
  79     // If false, an alert dialog will show in the event of a reload error.
  80     // Defaults to false.
  81     boolean? failQuietly;
  82   };
  83
  84   dictionary LoadUnpackedOptions {
  85     // If false, an alert dialog will show in the event of a reload error.
  86     // Defaults to false.
  87     boolean? failQuietly;
  88   };
  89
  90   enum PackStatus {
  91     SUCCESS,
  92     ERROR,
  93     WARNING
  94   };
  95
  96   enum FileType {
  97     LOAD,
  98     PEM
  99   };
 100
 101   enum SelectType {
 102     FILE,
 103     FOLDER
 104   };
 105
 106   enum EventType {
 107     INSTALLED,
 108     UNINSTALLED,
 109     LOADED,
 110     UNLOADED,
 111     // New window / view opened.
 112     VIEW_REGISTERED,
 113     // window / view closed.
 114     VIEW_UNREGISTERED,
 115     ERROR_ADDED
 116   };
 117
 118   dictionary PackDirectoryResponse {
 119     // The response message of success or error.
 120     DOMString message;
 121
 122     // Unpacked items's path.
 123     DOMString item_path;
 124
 125     // Permanent key path.
 126     DOMString pem_path;
 127
 128     long override_flags;
 129     PackStatus status;
 130   };
 131
 132   dictionary ProjectInfo {
 133     DOMString name;
 134   };
 135
 136   dictionary EventData {
 137     EventType event_type;
 138     DOMString item_id;
 139   };
 140
 141   dictionary RequestFileSourceProperties {
 142     // The ID of the extension owning the file.
 143     DOMString extensionId;
 144
 145     // The path of the file, relative to the extension; e.g., manifest.json,
 146     // script.js, or main.html.
 147     DOMString pathSuffix;
 148
 149     // The error message which was thrown as a result of the error in the file.
 150     DOMString message;
 151
 152     // The key in the manifest which caused the error (e.g., "permissions").
 153     // (Required for "manifest.json" files)
 154     DOMString? manifestKey;
 155
 156     // The specific portion of the manifest key which caused the error (e.g.,
 157     // "foo" in the "permissions" key). (Optional for "manifest.json" file).
 158     DOMString? manifestSpecific;
 159
 160     // The line number which caused the error (optional for non-manifest files).
 161     long? lineNumber;
 162   };
 163
 164   dictionary RequestFileSourceResponse {
 165     // The region of the code which threw the error, and should be highlighted.
 166     DOMString highlight;
 167
 168     // The region before the "highlight" portion.
 169     // If the region which threw the error was not found, the full contents of
 170     // the file will be in the "beforeHighlight" section.
 171     DOMString beforeHighlight;
 172
 173     // The region after the "highlight" portion.
 174     DOMString afterHighlight;
 175
 176     // A title for the file in the form '<extension name>: <file name>'.
 177     DOMString title;
 178
 179     // The error message.
 180     DOMString message;
 181   };
 182
 183   dictionary OpenDevToolsProperties {
 184     // The ID of the render view in which the error occurred.
 185     long renderViewId;
 186
 187     // The ID of the process in which the error occurred.
 188     long renderProcessId;
 189
 190     // The URL in which the error occurred.
 191     DOMString? url;
 192
 193     // The line to focus the devtools at.
 194     long? lineNumber;
 195
 196     // The column to focus the devtools at.
 197     long? columnNumber;
 198   };
 199
 200   callback VoidCallback = void ();
 201   callback BooleanCallback = void (boolean result);
 202   callback ItemsInfoCallback = void (ItemInfo[] result);
 203   callback GetProjectsInfoCallback = void (ProjectInfo[] result);
 204   callback PathCallback = void (DOMString path);
 205   callback PackCallback = void (PackDirectoryResponse response);
 206   callback VoidCallback = void();
 207   callback RequestFileSourceCallback =
 208       void (RequestFileSourceResponse response);
 209
 210   interface Functions {
 211     // Runs auto update for extensions and apps immediately.
 212     // |callback| : Called with the boolean result, true if autoUpdate is
 213     // successful.
 214     static void autoUpdate(optional BooleanCallback callback);
 215
 216     // Returns information of all the extensions and apps installed.
 217     // |includeDisabled| : include disabled items.
 218     // |includeTerminated| : include terminated items.
 219     // |callback| : Called with items info.
 220     static void getItemsInfo(boolean includeDisabled,
 221                              boolean includeTerminated,
 222                              ItemsInfoCallback callback);
 223
 224     // Opens a permissions dialog.
 225     // |extensionId| : The id of the extension to show permissions for.
 226     static void showPermissionsDialog(DOMString extensionId,
 227                                       optional VoidCallback callback);
 228
 229     // Opens a developer tools inspection window.
 230     // |options| : The details about the inspection.
 231     static void inspect(InspectOptions options,
 232                         optional VoidCallback callback);
 233
 234     // Enables / Disables file access for an extension.
 235     // |extensionId| : The id of the extension to set file access for.
 236     // |allow| : Whether or not to allow file access for the extension.
 237     static void allowFileAccess(DOMString extensionId,
 238                                 boolean allow,
 239                                 optional VoidCallback callback);
 240
 241     // Reloads a given extension.
 242     // |extensionId| : The id of the extension to reload.
 243     // |options| : Additional configuration parameters.
 244     static void reload(DOMString extensionId,
 245                        optional ReloadOptions options,
 246                        optional VoidCallback callback);
 247
 248     // Allows / Disallows an extension to run in incognito mode.
 249     // |extensionId| : The id of the extension.
 250     // |allow| : Whether or not the extension should be allowed incognito.
 251     static void allowIncognito(DOMString extensionId,
 252                                boolean allow,
 253                                optional VoidCallback callback);
 254
 255     // Loads a user-selected unpacked item.
 256     // |options| : Additional configuration parameters.
 257     static void loadUnpacked(optional LoadUnpackedOptions options,
 258                              optional VoidCallback callback);
 259
 260     // Loads an extension / app.
 261     // |directory| : The directory to load the extension from.
 262     static void loadDirectory(
 263         [instanceOf=DirectoryEntry] object directory,
 264         PathCallback callback);
 265
 266     // Open Dialog to browse to an entry.
 267     // |selectType| : Select a file or a folder.
 268     // |fileType| : Required file type. For example, pem type is for private
 269     // key and load type is for an unpacked item.
 270     // |callback| : called with selected item's path.
 271     static void choosePath(SelectType selectType,
 272                            FileType fileType,
 273                            PathCallback callback);
 274
 275     // Pack an extension.
 276     // |rootPath| : The path of the extension.
 277     // |privateKeyPath| : The path of the private key, if one is given.
 278     // |flags| : Special flags to apply to the loading process, if any.
 279     // |callback| : called with the success result string.
 280     static void packDirectory(DOMString path,
 281                               optional DOMString privateKeyPath,
 282                               optional long flags,
 283                               optional PackCallback callback);
 284
 285     // Returns true if the profile is managed.
 286     static void isProfileManaged(BooleanCallback callback);
 287
 288     // Reads and returns the contents of a file related to an extension which
 289     // caused an error.
 290     static void requestFileSource(RequestFileSourceProperties properties,
 291                                   RequestFileSourceCallback callback);
 292
 293     // Open the developer tools to focus on a particular error.
 294     static void openDevTools(OpenDevToolsProperties properties);
 295   };
 296
 297   interface Events {
 298     // Fired when a item state is changed.
 299     static void onItemStateChanged(EventData response);
 300   };
 301
 302 };