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

module content.mojom;

import "content/public/common/speech_recognition_grammar.mojom";
import "content/public/common/speech_recognition_result.mojom";
import "content/public/common/speech_recognition_error.mojom";
import "url/mojom/origin.mojom";

// Created by the renderer and sent to the browser to start a speech recognition
// session.
struct StartSpeechRecognitionRequestParams {
  // Used to create a connection with a SpeechRecognitionSession implementation
  // that will be created when the session is created.
  SpeechRecognitionSession& session_request;

  // Used by the browser to communicate with a SpeechRecognitionSessionClient
  // implementation created for the new session.
  SpeechRecognitionSessionClient client;

  // Language to use for speech recognition.
  string language;

  // Speech grammars to use.
  array<content.mojom.SpeechRecognitionGrammar> grammars;

  // URL of the page (or iframe if applicable).
  url.mojom.Origin origin;

  // Maximum number of hypotheses allowed for each results.
  uint32 max_hypotheses;

  // Whether the user requested continuous recognition.
  bool continuous;

  // Whether the user requested interim results.
  bool interim_results;
};

// API for the renderer process to start a speech recognition session in the
// browser process.
interface SpeechRecognizer {
  // Requests the speech recognition service to start speech recognition.
  Start(StartSpeechRecognitionRequestParams params);
};

// API for the renderer process to stop or abort an existing speech recognition
// session. An InterfaceRequest is sent to the browser process via
// SpeechRecognizer::Start, and is bound to an implementation there.
// SpeechRecognitionSession and SpeechRecognitionSessionClient are 1:1 with each
// other and with WebSpeechRecognitionHandle.
interface SpeechRecognitionSession {
  // Requests the speech recognition service to abort speech recognition for the
  // associated session.
  Abort();

  // Requests the speech recognition service to stop audio capture for the
  // associated session.
  StopCapture();
};

// API for the browser process to communicate speech recognition related updates
// with renderer and cause events to be dispatched to the appropriate speech
// recognition handle. An InterfacePtr for each handle is sent to the browser
// process via SpeechRecognizer::Start. SpeechRecognitionSession and
// SpeechRecognitionSessionClient are 1:1 with each other and with
// WebSpeechRecognitionHandle.
interface SpeechRecognitionSessionClient {
  // Called to dispatch the "result" event.
  ResultRetrieved(array<content.mojom.SpeechRecognitionResult> results);

  // Called to dispatch the "nomatch" event if the error code passed is of types
  // kNoMatch, otherwise dispatchers an "error" event.
  ErrorOccurred(content.mojom.SpeechRecognitionError error);

  // Called to dispatch the "start" event.
  Started();

  // Called to dispatch the "audiostart" event.
  AudioStarted();

  // Called to  dispatch the "soundstart" and "speechstart" events.
  SoundStarted();

  // Called to dispatch "soundend" and "speechend" events.
  SoundEnded();

  // Called to dispatch the "audioend" event.
  AudioEnded();

  // Called to dispatch the "end" event.
  Ended();
};