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   // DEPRECATED: Prefer ExtensionType.
  11   enum ItemType {
  12     hosted_app,
  13     packaged_app,
  14     legacy_packaged_app,
  15     extension,
  16     theme
  17   };
  18
  19   // DEPRECATED: Prefer ExtensionView.
  20   dictionary ItemInspectView {
  21     // path to the inspect page.
  22     DOMString path;
  23
  24     // For lazy background pages, the value is -1.
  25     long render_process_id;
  26
  27     long render_view_id;
  28     boolean incognito;
  29     boolean generatedBackgroundPage;
  30   };
  31
  32   // DEPRECATED: Use OpenDevTools.
  33   dictionary InspectOptions {
  34     DOMString extension_id;
  35     (DOMString or long) render_process_id;
  36     (DOMString or long) render_view_id;
  37     boolean incognito;
  38   };
  39
  40   dictionary InstallWarning {
  41     DOMString message;
  42   };
  43
  44   enum ExtensionType {
  45     HOSTED_APP,
  46     PLATFORM_APP,
  47     LEGACY_PACKAGED_APP,
  48     EXTENSION,
  49     THEME,
  50     SHARED_MODULE
  51   };
  52
  53   enum Location {
  54     FROM_STORE,
  55     UNPACKED,
  56     THIRD_PARTY,
  57     // "Unknown" includes crx's installed from chrome://extensions.
  58     UNKNOWN
  59   };
  60
  61   enum ViewType {
  62     APP_WINDOW,
  63     BACKGROUND_CONTENTS,
  64     EXTENSION_BACKGROUND_PAGE,
  65     EXTENSION_DIALOG,
  66     EXTENSION_POPUP,
  67     LAUNCHER_PAGE,
  68     PANEL,
  69     TAB_CONTENTS,
  70     VIRTUAL_KEYBOARD
  71   };
  72
  73   enum ErrorType {
  74     MANIFEST,
  75     RUNTIME
  76   };
  77
  78   enum ErrorLevel {
  79     LOG,
  80     WARN,
  81     ERROR
  82   };
  83
  84   enum ExtensionState {
  85     ENABLED,
  86     DISABLED,
  87     TERMINATED
  88   };
  89
  90   dictionary AccessModifier {
  91     boolean isEnabled;
  92     boolean isActive;
  93   };
  94
  95   dictionary StackFrame {
  96     long lineNumber;
  97     long columnNumber;
  98     DOMString url;
  99     DOMString functionName;
 100   };
 101
 102   dictionary ManifestError {
 103     ErrorType type;
 104     DOMString extensionId;
 105     boolean fromIncognito;
 106     DOMString source;
 107     DOMString message;
 108     long id;
 109     DOMString manifestKey;
 110     DOMString? manifestSpecific;
 111   };
 112
 113   dictionary RuntimeError {
 114     ErrorType type;
 115     DOMString extensionId;
 116     boolean fromIncognito;
 117     DOMString source;
 118     DOMString message;
 119     long id;
 120     ErrorLevel severity;
 121     DOMString contextUrl;
 122     long occurrences;
 123     long renderViewId;
 124     long renderProcessId;
 125     boolean canInspect;
 126     StackFrame[] stackTrace;
 127   };
 128
 129   dictionary DisableReasons {
 130     boolean suspiciousInstall;
 131     boolean corruptInstall;
 132     boolean updateRequired;
 133   };
 134
 135   dictionary OptionsPage {
 136     boolean openInTab;
 137     DOMString url;
 138   };
 139
 140   dictionary HomePage {
 141     DOMString url;
 142     boolean specified;
 143   };
 144
 145   dictionary ExtensionView {
 146     DOMString url;
 147     long renderProcessId;
 148     long renderViewId;
 149     boolean incognito;
 150     ViewType type;
 151   };
 152
 153   dictionary ExtensionInfo {
 154     boolean actionButtonHidden;
 155     DOMString? blacklistText;
 156     DOMString[] dependentExtensions;
 157     DOMString description;
 158     DisableReasons disableReasons;
 159     AccessModifier errorCollection;
 160     AccessModifier fileAccess;
 161     HomePage homePage;
 162     DOMString iconUrl;
 163     DOMString id;
 164     AccessModifier incognitoAccess;
 165     boolean installedByCustodian;
 166     DOMString[] installWarnings;
 167     DOMString? launchUrl;
 168     Location location;
 169     DOMString? locationText;
 170     ManifestError[] manifestErrors;
 171     boolean mustRemainInstalled;
 172     DOMString name;
 173     boolean offlineEnabled;
 174     OptionsPage? optionsPage;
 175     DOMString? path;
 176     DOMString? policyText;
 177     DOMString? prettifiedPath;
 178     AccessModifier runOnAllUrls;
 179     RuntimeError[] runtimeErrors;
 180     DOMString[] runtimeWarnings;
 181     ExtensionState state;
 182     ExtensionType type;
 183     DOMString updateUrl;
 184     boolean userMayModify;
 185     DOMString version;
 186     ExtensionView[] views;
 187   };
 188
 189   dictionary ProfileInfo {
 190     boolean appInfoDialogEnabled;
 191     boolean canLoadUnpacked;
 192     boolean inDeveloperMode;
 193     boolean isIncognitoAvailable;
 194     boolean isSupervised;
 195   };
 196
 197   // DEPRECATED: Prefer ExtensionInfo.
 198   dictionary ItemInfo {
 199     DOMString id;
 200     DOMString name;
 201     DOMString version;
 202     DOMString description;
 203     boolean may_disable;
 204     boolean enabled;
 205     boolean isApp;
 206     ItemType type;
 207     boolean allow_activity;
 208     boolean allow_file_access;
 209     boolean wants_file_access;
 210     boolean incognito_enabled;
 211     boolean is_unpacked;
 212     boolean allow_reload;
 213     boolean terminated;
 214     boolean allow_incognito;
 215     DOMString icon_url;
 216
 217     // Path of an unpacked extension.
 218     DOMString? path;
 219
 220     // Options settings page for the item.
 221     DOMString? options_url;
 222     DOMString? app_launch_url;
 223     DOMString? homepage_url;
 224     DOMString? update_url;
 225     InstallWarning[] install_warnings;
 226     any[] manifest_errors;
 227     any[] runtime_errors;
 228     boolean offline_enabled;
 229
 230     // All views of the current extension.
 231     ItemInspectView[] views;
 232   };
 233
 234   dictionary GetExtensionsInfoOptions {
 235     boolean? includeDisabled;
 236     boolean? includeTerminated;
 237   };
 238
 239   dictionary ExtensionConfigurationUpdate {
 240     DOMString extensionId;
 241     boolean? fileAccess;
 242     boolean? incognitoAccess;
 243     boolean? errorCollection;
 244     boolean? runOnAllUrls;
 245     boolean? showActionButton;
 246   };
 247
 248   dictionary ProfileConfigurationUpdate {
 249     boolean? inDeveloperMode;
 250   };
 251
 252   dictionary ReloadOptions {
 253     // If false, an alert dialog will show in the event of a reload error.
 254     // Defaults to false.
 255     boolean? failQuietly;
 256   };
 257
 258   dictionary LoadUnpackedOptions {
 259     // If false, an alert dialog will show in the event of a reload error.
 260     // Defaults to false.
 261     boolean? failQuietly;
 262   };
 263
 264   enum PackStatus {
 265     SUCCESS,
 266     ERROR,
 267     WARNING
 268   };
 269
 270   enum FileType {
 271     LOAD,
 272     PEM
 273   };
 274
 275   enum SelectType {
 276     FILE,
 277     FOLDER
 278   };
 279
 280   enum EventType {
 281     INSTALLED,
 282     UNINSTALLED,
 283     LOADED,
 284     UNLOADED,
 285     // New window / view opened.
 286     VIEW_REGISTERED,
 287     // window / view closed.
 288     VIEW_UNREGISTERED,
 289     ERROR_ADDED,
 290     ERRORS_REMOVED,
 291     PREFS_CHANGED
 292   };
 293
 294   dictionary PackDirectoryResponse {
 295     // The response message of success or error.
 296     DOMString message;
 297
 298     // Unpacked items's path.
 299     DOMString item_path;
 300
 301     // Permanent key path.
 302     DOMString pem_path;
 303
 304     long override_flags;
 305     PackStatus status;
 306   };
 307
 308   dictionary ProjectInfo {
 309     DOMString name;
 310   };
 311
 312   dictionary EventData {
 313     EventType event_type;
 314     DOMString item_id;
 315     ExtensionInfo? extensionInfo;
 316   };
 317
 318   dictionary RequestFileSourceProperties {
 319     // The ID of the extension owning the file.
 320     DOMString extensionId;
 321
 322     // The path of the file, relative to the extension; e.g., manifest.json,
 323     // script.js, or main.html.
 324     DOMString pathSuffix;
 325
 326     // The error message which was thrown as a result of the error in the file.
 327     DOMString message;
 328
 329     // The key in the manifest which caused the error (e.g., "permissions").
 330     // (Required for "manifest.json" files)
 331     DOMString? manifestKey;
 332
 333     // The specific portion of the manifest key which caused the error (e.g.,
 334     // "foo" in the "permissions" key). (Optional for "manifest.json" file).
 335     DOMString? manifestSpecific;
 336
 337     // The line number which caused the error (optional for non-manifest files).
 338     long? lineNumber;
 339   };
 340
 341   dictionary RequestFileSourceResponse {
 342     // The region of the code which threw the error, and should be highlighted.
 343     DOMString highlight;
 344
 345     // The region before the "highlight" portion.
 346     // If the region which threw the error was not found, the full contents of
 347     // the file will be in the "beforeHighlight" section.
 348     DOMString beforeHighlight;
 349
 350     // The region after the "highlight" portion.
 351     DOMString afterHighlight;
 352
 353     // A title for the file in the form '<extension name>: <file name>'.
 354     DOMString title;
 355
 356     // The error message.
 357     DOMString message;
 358   };
 359
 360   dictionary OpenDevToolsProperties {
 361     // The ID of the extension. This is only needed if opening the background
 362     // page (where renderViewId and renderProcessId are -1).
 363     DOMString? extensionId;
 364
 365     // The ID of the render view in which the error occurred.
 366     long renderViewId;
 367
 368     // The ID of the process in which the error occurred.
 369     long renderProcessId;
 370
 371     boolean? incognito;
 372
 373     // The URL in which the error occurred.
 374     DOMString? url;
 375
 376     // The line to focus the devtools at.
 377     long? lineNumber;
 378
 379     // The column to focus the devtools at.
 380     long? columnNumber;
 381   };
 382
 383   dictionary DeleteExtensionErrorsProperties {
 384     DOMString extensionId;
 385     long[]? errorIds;
 386     ErrorType? type;
 387   };
 388
 389   callback VoidCallback = void ();
 390   callback BooleanCallback = void (boolean result);
 391   callback ExtensionInfosCallback = void (ExtensionInfo[] result);
 392   callback ExtensionInfoCallback = void (ExtensionInfo result);
 393   callback ItemsInfoCallback = void (ItemInfo[] result);
 394   callback ProfileInfoCallback = void (ProfileInfo info);
 395   callback GetProjectsInfoCallback = void (ProjectInfo[] result);
 396   callback PathCallback = void (DOMString path);
 397   callback PackCallback = void (PackDirectoryResponse response);
 398   callback VoidCallback = void();
 399   callback RequestFileSourceCallback =
 400       void (RequestFileSourceResponse response);
 401
 402   interface Functions {
 403     // Runs auto update for extensions and apps immediately.
 404     // |callback| : Called with the boolean result, true if autoUpdate is
 405     // successful.
 406     static void autoUpdate(optional BooleanCallback callback);
 407
 408     // Returns information of all the extensions and apps installed.
 409     // |options| : Options to restrict the items returned.
 410     // |callback| : Called with extensions info.
 411     static void getExtensionsInfo(optional GetExtensionsInfoOptions options,
 412                                   optional ExtensionInfosCallback callback);
 413
 414     // Returns information of a particular extension.
 415     // |id| : The id of the extension.
 416     // |callback| : Called with the result.
 417     static void getExtensionInfo(DOMString id,
 418                                  optional ExtensionInfoCallback callback);
 419
 420     // Returns information of all the extensions and apps installed.
 421     // |includeDisabled| : include disabled items.
 422     // |includeTerminated| : include terminated items.
 423     // |callback| : Called with items info.
 424     [deprecated="Use getExtensionsInfo"] static void getItemsInfo(
 425         boolean includeDisabled,
 426         boolean includeTerminated,
 427         ItemsInfoCallback callback);
 428
 429     // Returns the current profile's configuration.
 430     static void getProfileConfiguration(ProfileInfoCallback callback);
 431
 432     // Updates the active profile.
 433     // |update| : The parameters for updating the profile's configuration.  Any
 434     //     properties omitted from |update| will not be changed.
 435     static void updateProfileConfiguration(ProfileConfigurationUpdate update,
 436                                            optional VoidCallback callback);
 437
 438     // Opens a permissions dialog.
 439     // |extensionId| : The id of the extension to show permissions for.
 440     static void showPermissionsDialog(DOMString extensionId,
 441                                       optional VoidCallback callback);
 442
 443     // Reloads a given extension.
 444     // |extensionId| : The id of the extension to reload.
 445     // |options| : Additional configuration parameters.
 446     static void reload(DOMString extensionId,
 447                        optional ReloadOptions options,
 448                        optional VoidCallback callback);
 449
 450     // Modifies an extension's current configuration.
 451     // |update| : The parameters for updating the extension's configuration.
 452     //     Any properties omitted from |update| will not be changed.
 453     static void updateExtensionConfiguration(
 454         ExtensionConfigurationUpdate update,
 455         optional VoidCallback callback);
 456
 457     // Loads a user-selected unpacked item.
 458     // |options| : Additional configuration parameters.
 459     static void loadUnpacked(optional LoadUnpackedOptions options,
 460                              optional VoidCallback callback);
 461
 462     // Loads an extension / app.
 463     // |directory| : The directory to load the extension from.
 464     static void loadDirectory(
 465         [instanceOf=DirectoryEntry] object directory,
 466         PathCallback callback);
 467
 468     // Open Dialog to browse to an entry.
 469     // |selectType| : Select a file or a folder.
 470     // |fileType| : Required file type. For example, pem type is for private
 471     // key and load type is for an unpacked item.
 472     // |callback| : called with selected item's path.
 473     static void choosePath(SelectType selectType,
 474                            FileType fileType,
 475                            PathCallback callback);
 476
 477     // Pack an extension.
 478     // |rootPath| : The path of the extension.
 479     // |privateKeyPath| : The path of the private key, if one is given.
 480     // |flags| : Special flags to apply to the loading process, if any.
 481     // |callback| : called with the success result string.
 482     static void packDirectory(DOMString path,
 483                               optional DOMString privateKeyPath,
 484                               optional long flags,
 485                               optional PackCallback callback);
 486
 487     // Returns true if the profile is managed.
 488     static void isProfileManaged(BooleanCallback callback);
 489
 490     // Reads and returns the contents of a file related to an extension which
 491     // caused an error.
 492     static void requestFileSource(RequestFileSourceProperties properties,
 493                                   RequestFileSourceCallback callback);
 494
 495     // Open the developer tools to focus on a particular error.
 496     static void openDevTools(OpenDevToolsProperties properties,
 497                              optional VoidCallback callback);
 498
 499     // Delete reported extension erors.
 500     // |properties| : The properties specifying the errors to remove.
 501     static void deleteExtensionErrors(
 502         DeleteExtensionErrorsProperties properties,
 503         optional VoidCallback callback);
 504
 505     // Repairs the extension specified.
 506     // |extensionId| : The id of the extension to repair.
 507     static void repairExtension(DOMString extensionId,
 508                                 optional VoidCallback callback);
 509
 510     // Shows the options page for the extension specified.
 511     // |extensionId| : The id of the extension to show the options page for.
 512     static void showOptions(DOMString extensionId,
 513                             optional VoidCallback callback);
 514
 515     // Shows the path of the extension specified.
 516     // |extensionId| : The id of the extension to show the path for.
 517     static void showPath(DOMString extensionId, optional VoidCallback callback);
 518
 519     [nocompile, deprecated="Use management.setEnabled"]
 520         static void enable(DOMString id,
 521                            boolean enabled,
 522                            optional VoidCallback callback);
 523     [nocompile, deprecated="Use updateExtensionConfiguration"]
 524         static void allowIncognito(DOMString extensionId,
 525                                    boolean allow,
 526                                    optional VoidCallback callback);
 527     [nocompile, deprecated="Use updateExtensionConfiguration"]
 528         static void allowFileAccess(DOMString extensionId,
 529                                     boolean allow,
 530                                     optional VoidCallback callback);
 531     [nocompile, deprecated="Use openDevTools"]
 532         static void inspect(InspectOptions options,
 533                             optional VoidCallback callback);
 534   };
 535
 536   interface Events {
 537     // Fired when a item state is changed.
 538     static void onItemStateChanged(EventData response);
 539   };
 540
 541 };