// Copyright 2015 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.searchEnginesPrivate</code> API to get or set
// preferences from the settings UI.
namespace searchEnginesPrivate {

  // Types of hotword features that are available.
  enum HotwordFeature {
    SEARCH, ALWAYS_ON, RETRAIN_LINK, AUDIO_HISTORY
  };

  // Types of search engines.
  enum SearchEngineType {
    DEFAULT, OTHER
  };

  dictionary HotwordState {
    // Availability of hotword features.
    HotwordFeature[] availability;

    // State of the audio history; present if the availability includes
    // audio history.
    DOMString? audioHistoryState;

    // Error message when fetching hotword state if an error occurred.
    DOMString? errorMsg;
  };

  dictionary SearchEngine {
    // The unique ID of the engine in the list.
    DOMString guid;

    // The name of the engine.
    DOMString name;

    // The keyword for the engine.
    DOMString keyword;

    // The URL of the engine.
    DOMString url;

    // The type of the engine.
    SearchEngineType type;

    // Whether the engine is the selected a.k.a. "default" search engine.
    boolean? isSelected;
  };

  callback HotwordStateCallback = void (HotwordState state);
  callback SearchEnginesCallback = void (SearchEngine[] engines);

  interface Functions {
    // Gets a list of the search engines.
    // Exactly one of the values should have default == true.
    static void getSearchEngines(SearchEnginesCallback callback);

    // Sets the search engine with the given GUID as the selected default.
    static void setSelectedSearchEngine(DOMString guid);

    // Adds a new "other" (non-default) search engine with the given name,
    // keyword, and URL.
    static void addOtherSearchEngine(
        DOMString name, DOMString keyword, DOMString url);

    // Updates the search engine that has the given GUID, with the given name,
    // keyword, and URL.
    static void updateSearchEngine(
        DOMString guid, DOMString name, DOMString keyword, DOMString url);

    // Removes the search engine with the given GUID.
    static void removeSearchEngine(DOMString guid);

    // Gets the hotword state.
    static void getHotwordState(HotwordStateCallback callback);

    // Opts in to hotwording; |retrain| indicates whether the user wants to
    // retrain the hotword system with their voice by launching the audio
    // verification app.
    static void optIntoHotwording(boolean retrain);
  };

  interface Events {
    // Fires when the list of search engines changes or when the user selects a
    // preferred default search engine. The new list of engines is passed along.
    static void onSearchEnginesChanged(SearchEngine[] engines);
  };
};