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

// The <code>chrome.hotwordPrivate</code> API allows extensions to access and
// mutate the preference for enabling hotword search. It also provides
// information on whether the hotword search is available. This API provides an
// event interface to transmit to the extension a signal that the preference fo
// hotword search has change.
//
// For an FYI, visit http://goo.gl/AyHbkH

namespace hotwordPrivate {

  dictionary StatusDetails {
    // Whether the hotword preference has been set.
    boolean enabledSet;

    // If the hotword extension is enabled. Will always be false if |available|
    // is false.
    boolean enabled;

    // Whether the hotword extension is available to be enabled
    // Optional field, only valid when getStatus() is called with
    // |getOptionalFields| = true. Otherwise, set to false.
    boolean available;

    // Whether always-on is available to be enabled
    // Optional field, only valid when getStatus() is called with
    // |getOptionalFields| = true. Otherwise, set to false.
    boolean alwaysOnAvailable;

    // Whether the sound of "Ok, Google" plus a few seconds before is sent
    // back to Google.
    boolean audioLoggingEnabled;

    // Whether always-on hotwording is enabled.
    boolean alwaysOnEnabled;

    // Whether training mode is enabled.
    boolean trainingEnabled;

    // Whether the user corresponding to this profile is the active user.
    boolean userIsActive;

    // Whether hotword hardware is available if requested.
    boolean hotwordHardwareAvailable;
  };

  dictionary LaunchState {
    // TODO(kcarattini): Consider adding more variables here,
    // such as the available state of the hotword service.

    // The mode that the Hotword Audio Verification app was launched in.
    long launchMode;
  };

  dictionary LogDetails {
    // Number of audio channels. i.e. 1 = mono, 2 = stereo
    long channels;

    // Bytes per sample per channel.
    long bytes_per_sample;

    // Sample rate. Usually 32000 or 44100, but may be any integer.
    long sample_rate;

    // Array containing audio data. Length is
    // (channels * bytes_per_sample * sample_rate * <seconds of log>).
    ArrayBuffer buffer;
  };

  dictionary AudioHistoryState {
    // Whether the call to set or get this state was successful.
    boolean success;

    // The current value of the audio history opt-in state after this
    // call.
    boolean enabled;
  };

  // The type of the recognized hotword. Right now it only has 'search' but
  // could be expanded to other types of actions in the future.
  enum HotwordType { search };

  callback GenericDoneCallback = void ();
  callback LaunchStateCallback = void(LaunchState result);
  callback LocalizeStringsCallback = void(object result);
  callback StatusDetailsCallback = void(StatusDetails result);
  callback AudioHistoryCallback = void(AudioHistoryState result);

  interface Functions {
    // Sets the current enabled state of hotword search.
    // True: enable hotword search. False: disable hotword search.
    static void setEnabled(boolean state,
                           optional GenericDoneCallback callback);

    // Retrieves the current state of hotword search.
    // The result is put into a StatusDetails object.
    // |getOptionalFields|: If true, fills in fields tagged as optional in
    // StatusDetails with valid values. These fields are not valid by default
    // since their current implementations may cause blocking operations.
    static void getStatus(optional boolean getOptionalFields,
                          StatusDetailsCallback callback);

    // Retrieves a dictionary mapping names to localized resource strings.
    static void getLocalizedStrings(LocalizeStringsCallback callback);

    // Sets the current enabled state of audio logging in the extension.
    // True: logging enabled. False: no logging.
    static void setAudioLoggingEnabled(boolean state,
                                       optional GenericDoneCallback callback);

    // Sets the current enabled state of hotword-always-on-search pref.
    // True: enable hotword always on search.
    // False: disable hotword always on search.
    static void setHotwordAlwaysOnSearchEnabled(boolean state,
        optional GenericDoneCallback callback);

    // Sets the current state of the browser-requested hotword session.
    static void setHotwordSessionState(boolean started,
                                       optional GenericDoneCallback callback);

    // Notifies that a hotword has been recognized in the browser-requested
    // hotword session.
    static void notifyHotwordRecognition(HotwordType type,
                                         optional LogDetails log,
                                         optional GenericDoneCallback callback);

    // Retrieves the state that the Hotword Audio Verification app was
    // launched in. The result is put into a LaunchState object.
    static void getLaunchState(LaunchStateCallback callback);

    // Starts the speaker model training.
    static void startTraining(optional GenericDoneCallback callback);

    // Finalizess the speaker model.
    static void finalizeSpeakerModel(optional GenericDoneCallback callback);

    // Notifies that the speaker model has been saved.
    static void notifySpeakerModelSaved(optional GenericDoneCallback callback);

    // Stops the speaker model training.
    static void stopTraining(optional GenericDoneCallback callback);

    // Sets the audio history opt-in state.
    static void setAudioHistoryEnabled(boolean enabled,
                                       optional AudioHistoryCallback callback);

    // Gets the audio history opt-in state.
    static void getAudioHistoryEnabled(optional AudioHistoryCallback callback);

    // Sends the result of whether a speaker model exists to the browser.
    static void speakerModelExistsResult(boolean exists,
                                         optional GenericDoneCallback callback);
  };

  interface Events {
    // Fired when the hotword detector enabled state should be changed.
    // This can be from various sources, e.g. a pref change or training
    // a speaker model.
    static void onEnabledChanged();

    // Fired when the browser wants to start a hotword session.
    static void onHotwordSessionRequested();

    // Fired when the browser wants to stop the requested hotword session.
    static void onHotwordSessionStopped();

    // Fired when the speaker model should be finalized.
    static void onFinalizeSpeakerModel();

    // Fired when the speaker model has been saved.
    static void onSpeakerModelSaved();

    // Fired when a hotword has triggered.
    static void onHotwordTriggered();

    // Fired when the speaker model should be deleted.
    static void onDeleteSpeakerModel();

    // Fired when the browser wants to find out whether the speaker model
    // exists.
    static void onSpeakerModelExists();

    // Fired when the microphone state changes.
    static void onMicrophoneStateChanged(boolean enabled);
  };
};