// Copyright 2013 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.feedbackPrivate</code> API to provide Chrome [OS]
// feedback to the Google Feedback servers.
namespace feedbackPrivate {

  dictionary AttachedFile {
    DOMString name;
    [instanceOf=Blob] object? data;
  };

  dictionary SystemInformation {
    DOMString key;
    DOMString value;
  };

  // Supported feedback flows.
  enum FeedbackFlow {
    // Flow for regular user. This is the default.
    regular,

    // Flow on the ChromeOS login screen. URL entry, file attaching and landing
    // page is disabled for this flow.
    login,

    // Flow where a prompt to download the Chrome Cleanup Tool is displayed
    // prior to showing the feedback form.
    showSrtPrompt,

    // Flow when the feedback is requested from the sad tab ("Aw, Snap!") page
    // when the renderer crashes.
    sadTabCrash
  };

  dictionary FeedbackInfo {
    // File to attach to the feedback report.
    AttachedFile? attachedFile;

    // An optional tag to label what type this feedback is.
    DOMString? categoryTag;

    // The feedback text describing the user issue.
    DOMString description;

    // The placeholder text that will be shown in the description field when
    // it's empty.
    DOMString? descriptionPlaceholder;

    // The e-mail of the user that initiated this feedback.
    DOMString? email;

    // The URL of the page that this issue was being experienced on.
    DOMString? pageUrl;

    // Optional product ID to override the Chrome [OS] product id that is
    // usually passed to the feedback server.
    long? productId;

    // Screenshot to send with this feedback.
    [instanceOf=Blob] object? screenshot;

    // Optional id for performance trace data that can be included in this
    // report.
    long? traceId;

    // An array of key/value pairs providing system information for this
    // feedback report.
    SystemInformation[]? systemInformation;

    // True if we have permission to add histograms to this feedback report.
    boolean sendHistograms;

    // Optional feedback UI flow. Default is the regular user flow.
    FeedbackFlow? flow;

    // TODO(rkc): Remove these once we have bindings to send blobs to Chrome.
    // Used internally to store the blob uuid after parameter customization.
    DOMString? attachedFileBlobUuid;
    DOMString? screenshotBlobUuid;

    // Whether to use the system-provided window frame or custom frame controls.
    boolean? useSystemWindowFrame;
  };

  // Status of the sending of a feedback report.
  enum Status {success, delayed};

  // The type of the landing page shown to the user when the feedback report is
  // successfully sent.
  enum LandingPageType {normal, techstop};

  // Result of presenting the user with a prompt to download SRT.
  enum SrtPromptResult {
    // User clicked the "Learn More" button.
    accepted,

    // User declined the prompt and proceeded to the feedback page.
    declined,

    // User closed the window altogether.
    closed
  };

  // Allowed log sources on Chrome OS.
  enum LogSource {
    // Chrome OS system messages.
    messages,

    // Latest Chrome OS UI logs.
    uiLatest,

    // Info about display connectors and connected displays from DRM subsystem.
    drmModetest,

    // USB device list and connectivity graph.
    lsusb,

    // Logs from daemon for Atrus device.
    atrusLog,

    // Network log.
    netLog,

    // Log of system events.
    eventLog,

    // Update engine log.
    updateEngineLog,

    // Log of the current power manager session.
    powerdLatest,

    // Log of the previous power manager session.
    powerdPrevious,

    // Info about system PCI buses devices.
    lspci,

    // Info about system network interface.
    ifconfig,

    // Info about system uptime.
    uptime
  };

  // Input parameters for a readLogSource() call.
  dictionary ReadLogSourceParams {
    // The log source from which to read.
    LogSource source;

    // For file-based log sources, read from source without closing the file
    // handle. The next time $(ref:readLogSource) is called, the file read will
    // continue where it left off. $(ref:readLogSource) can be called with
    // <code>incremental=true</code> repeatedly. To subsequently close the file
    // handle, pass in <code>incremental=false</code>.
    boolean incremental;

    // To read from an existing file handle, set this to a valid
    // <code>readerId</code> value that was returned from a previous
    // $(ref:readLogSource) call. The reader must previously have been created
    // for the same value of <code>source</code>. If no <code>readerId</code> is
    // provided, $(ref:readLogSource) will attempt to open a new log source
    // reader handle.
    long? readerId;
  };

  // Result returned from a $(ref:readLogSource) call.
  dictionary ReadLogSourceResult {
    // The ID of the log source reader that was created to read from the log
    // source. If the reader was destroyed at the end of a read by passing in
    // <code>incremental=false</code>, this is always set to 0. If the call was
    // to use an existing reader with an existing ID, this will be set to the
    // same <code>readerId</code> that was passed into $(ref:readLogSource).
    long readerId;

    // Each DOMString in this array represents one line of logging that was
    // fetched from the log source.
    DOMString[] logLines;
  };

  callback GetUserEmailCallback = void(DOMString email);
  callback GetSystemInformationCallback =
      void(SystemInformation[] systemInformation);
  callback SendFeedbackCallback = void(Status status, LandingPageType type);
  callback GetStringsCallback = void(object result);
  callback ReadLogSourceCallback = void (ReadLogSourceResult result);

  interface Functions {
    // Returns the email of the currently active or logged in user.
    static void getUserEmail(GetUserEmailCallback callback);

    // Returns the system information dictionary.
    static void getSystemInformation(GetSystemInformationCallback callback);

    // Sends a feedback report.
    static void sendFeedback(FeedbackInfo feedback,
                             SendFeedbackCallback callback);

    // Gets localized translated strings for feedback. It returns the
    // strings as a dictionary mapping from string identifier to the
    // translated string to use in the feedback app UI.
    static void getStrings(FeedbackFlow flow, GetStringsCallback callback);

    // Logs whether the user accepted a prompt to try the Software Removal
    // Tool.
    static void logSrtPromptResult(SrtPromptResult result);

    // Reads from a log source indicated by <code>source</code>.
    // <p>If <code>incremental</code> is false:
    // <ul>
    //   <li>Returns the entire contents of the log file.</li>
    //   <li>Returns <code>readerId</code> value of 0 to callback.</li>
    // </ul>
    // If <code>incremental</code> is true, and no <code>readerId</code> is
    // provided:
    // <ul>
    //   <li>Returns the entire contents of the log file.</li>
    //   <li>Starts tracking the file read handle, which is returned as a
    //       nonzero <code>readerId</code> value in the callback.
    //       </li>
    //   <li>If can't create a new file handle, returns <code>readerId</code>
    //       value of 0 in the callback.
    //       </li>
    // </ul>
    // If <code>incremental</code> is true, and a valid non-zero
    // <code>readerId</code> is provided:
    // <ul>
    //   <li>Returns new lines written to the file since the last time this
    //       function was called for the same file and <code>readerId</code>.
    //       </li>
    //   <li>Returns the same <code>readerId</code> value to the callback.</li>
    // </ul>
    static void readLogSource(ReadLogSourceParams params,
                              ReadLogSourceCallback callback);
  };

  interface Events {
    // Fired when the a user requests the launch of the feedback UI. We're
    // using an event for this versus using the override API since we want
    // to be invoked, but not showing a UI, so the feedback extension can
    // take a screenshot of the user's desktop.
    static void onFeedbackRequested(FeedbackInfo feedback);
  };
};