// Copyright 2014 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.

// Use the <code>chrome.app.runtime</code> API to manage the app lifecycle.
// The app runtime manages app installation, controls the event page, and can
// shut down the app at anytime.
namespace app.runtime {

  [inline_doc] dictionary LaunchItem {
    // Entry for the item.
    [instanceOf=Entry] object entry;

    // The MIME type of the file.
    DOMString? type;
  };

  // Enumeration of app launch sources.
  // This should be kept in sync with AppLaunchSource in
  // extensions/common/constants.h, and GetLaunchSourceEnum() in
  // extensions/browser/api/app_runtime/app_runtime_api.cc.
  // Note the enumeration is used in UMA histogram so entries
  // should not be re-ordered or removed.
  enum LaunchSource {
    untracked,
    app_launcher,
    new_tab_page,
    reload,
    restart,
    load_and_launch,
    command_line,
    file_handler,
    url_handler,
    system_tray,
    about_page,
    keyboard,
    extensions_page,
    management_api,
    ephemeral_app,
    background,
    kiosk,
    chrome_internal,
    test,
    installed_notification,
    context_menu
  };

  // An app can be launched with a specific action in mind, for example, to
  // create a new note. The type of action the app was launched
  // with is available inside of the |actionData| field from the LaunchData
  // instance.
  enum ActionType {
    // The user wants to quickly take a new note.
    new_note
  };

  // Status of the play store.
  [nodoc] enum PlayStoreStatus {
    // Indicates that the play store is enabled. It also implies available.
    enabled,
    // Indicates that the play store is available but not enabled.
    available,
    // Indicates that the play store status is unknown.
    unknown
  };

  // Optional data that includes action-specific launch information.
  dictionary ActionData {
    ActionType actionType;

    // <p>Whether the action was requested on Chrome OS lock screen.</p>
    // <p>
    //   Launch events with this valued set to <code>true</code> are fired
    //   in lock screen context, where apps have reduced access to extension
    //   APIs, but are able to create windows on lock screen.
    // </p>
    // <p>
    //   Note that this value will be set to <code>true</code> only if the app
    //   is set as the lock screen enabled action handler by the user.
    // </p>
    [nodoc] boolean? isLockScreenAction;

    // Currently, used only with lock screen actions. If set, indicates whether
    // the app should attempt to restore state from when the action was last
    // handled.
    [nodoc] boolean? restoreLastActionState;
  };

  // Optional data for the launch. Either <code>items</code>, or
  // the pair (<code>url, referrerUrl</code>) can be present for any given
  // launch.
  [inline_doc] dictionary LaunchData {
    // The ID of the file or URL handler that the app is being invoked with.
    // Handler IDs are the top-level keys in the <code>file_handlers</code>
    // and/or <code>url_handlers</code> dictionaries in the manifest.
    DOMString? id;

    // The file entries for the <code>onLaunched</code> event triggered by a
    // matching file handler in the <code>file_handlers</code> manifest key.
    LaunchItem[]? items;

    // The URL for the <code>onLaunched</code> event triggered by a matching
    // URL handler in the <code>url_handlers</code> manifest key.
    DOMString? url;

    // The referrer URL for the <code>onLaunched</code> event triggered by a
    // matching URL handler in the <code>url_handlers</code> manifest key.
    DOMString? referrerUrl;

    // Whether the app is being launched in a <a
    // href="https://support.google.com/chromebook/answer/3134673">Chrome OS
    // kiosk session</a>.
    boolean? isKioskSession;

    // Whether the app is being launched in a <a
    // href="https://support.google.com/chrome/a/answer/3017014">Chrome OS
    // public session</a>.
    boolean? isPublicSession;

    // Where the app is launched from.
    LaunchSource? source;

    // Contains data that specifies the <code>ActionType</code> this app was
    // launched with. This is null if the app was not launched with a specific
    // action intent.
    ActionData? actionData;

    // Internal fields used to indicate ARC status on the device.
    [nodoc] PlayStoreStatus? playStoreStatus;
  };

  // This object specifies details and operations to perform on the embedding
  // request. The app to be embedded can make a decision on whether or not to
  // allow the embedding and what to embed based on the embedder making the
  // request.
  dictionary EmbedRequest {
    DOMString embedderId;

    // Optional developer specified data that the app to be embedded can use
    // when making an embedding decision.
    any? data;

    // Allows <code>embedderId</code> to embed this app in an &lt;appview&gt;
    // element. The <code>url</code> specifies the content to embed.
    [nocompile] static void allow(DOMString url);

    // Prevents <code> embedderId</code> from embedding this app in an
    // &lt;appview&gt; element.
    [nocompile] static void deny();
  };

  interface Events {
    // Fired when an embedding app requests to embed this app. This event is
    // only available on dev channel with the flag --enable-app-view.
    static void onEmbedRequested(EmbedRequest request);

    // Fired when an app is launched from the launcher.
    static void onLaunched(optional LaunchData launchData);

    // Fired at Chrome startup to apps that were running when Chrome last shut
    // down, or when apps have been requested to restart from their previous
    // state for other reasons (e.g. when the user revokes access to an app's
    // retained files the runtime will restart the app). In these situations if
    // apps do not have an <code>onRestarted</code> handler they will be sent
    // an <code>onLaunched </code> event instead.
    static void onRestarted();
  };
};