extensions/common/api/app_runtime.idl

   1 // Copyright 2014 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 // Use the <code>chrome.app.runtime</code> API to manage the app lifecycle.
   6 // The app runtime manages app installation, controls the event page, and can
   7 // shut down the app at anytime.
   8 namespace app.runtime {
   9
  10   [inline_doc] dictionary LaunchItem {
  11     // FileEntry for the file.
  12     [instanceOf=FileEntry] object entry;
  13
  14     // The MIME type of the file.
  15     DOMString type;
  16   };
  17
  18   // Enumeration of app launch sources.
  19   enum LaunchSource {
  20     app_launcher,
  21     new_tab_page,
  22     reload,
  23     restart,
  24     load_and_launch,
  25     command_line,
  26     file_handler,
  27     url_handler,
  28     system_tray,
  29     about_page,
  30     keyboard,
  31     extensions_page,
  32     management_api,
  33     ephemeral_app,
  34     background,
  35     kiosk,
  36     chrome_internal,
  37     test
  38   };
  39
  40   // Optional data for the launch. Either <code>items</code>, or
  41   // the pair (<code>url, referrerUrl</code>) can be present for any given
  42   // launch.
  43   [inline_doc] dictionary LaunchData {
  44     // The ID of the file or URL handler that the app is being invoked with.
  45     // Handler IDs are the top-level keys in the <code>file_handlers</code>
  46     // and/or <code>url_handlers</code> dictionaries in the manifest.
  47     DOMString? id;
  48
  49     // The file entries for the <code>onLaunched</code> event triggered by a
  50     // matching file handler in the <code>file_handlers</code> manifest key.
  51     LaunchItem[]? items;
  52
  53     // The URL for the <code>onLaunched</code> event triggered by a matching
  54     // URL handler in the <code>url_handlers</code> manifest key.
  55     DOMString? url;
  56
  57     // The referrer URL for the <code>onLaunched</code> event triggered by a
  58     // matching URL handler in the <code>url_handlers</code> manifest key.
  59     DOMString? referrerUrl;
  60
  61     // Whether the app is being launched in a <a
  62     // href="https://support.google.com/chromebook/answer/3134673">Chrome OS
  63     // kiosk session</a>.
  64     boolean? isKioskSession;
  65
  66     // Where the app is launched from.
  67     LaunchSource? source;
  68   };
  69
  70   // This object specifies details and operations to perform on the embedding
  71   // request. The app to be embedded can make a decision on whether or not to
  72   // allow the embedding and what to embed based on the embedder making the
  73   // request.
  74   dictionary EmbedRequest {
  75     DOMString embedderId;
  76
  77     // Optional developer specified data that the app to be embedded can use
  78     // when making an embedding decision.
  79     any? data;
  80
  81     // Allows <code>embedderId</code> to embed this app in an &lt;appview&gt;
  82     // element. The <code>url</code> specifies the content to embed.
  83     [nocompile] static void allow(DOMString url);
  84
  85     // Prevents <code> embedderId</code> from embedding this app in an
  86     // &lt;appview&gt; element.
  87     [nocompile] static void deny();
  88   };
  89
  90   interface Events {
  91     // Fired when an embedding app requests to embed this app. This event is
  92     // only available on dev channel with the flag --enable-app-view.
  93     static void onEmbedRequested(EmbedRequest request);
  94
  95     // Fired when an app is launched from the launcher.
  96     static void onLaunched(optional LaunchData launchData);
  97
  98     // Fired at Chrome startup to apps that were running when Chrome last shut
  99     // down, or when apps have been requested to restart from their previous
 100     // state for other reasons (e.g. when the user revokes access to an app's
 101     // retained files the runtime will restart the app). In these situations if
 102     // apps do not have an <code>onRestarted</code> handler they will be sent
 103     // an <code>onLaunched </code> event instead.
 104     static void onRestarted();
 105   };
 106 };