Speech refactoring: Reimplemented SpeechRecognitionManagerImpl as a FSM. (CL1.7)

content/public/browser/speech_recognition_manager.h

 // Copyright (c) 2012 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.
 
 #ifndef CONTENT_PUBLIC_BROWSER_SPEECH_RECOGNITION_MANAGER_H_
 #define CONTENT_PUBLIC_BROWSER_SPEECH_RECOGNITION_MANAGER_H_
 
 #include "base/string16.h"
+#include "base/callback.h"
 #include "content/common/content_export.h"
+#include "content/public/common/speech_recognition_result.h"
 
 namespace content {
 
-// This is the gatekeeper for speech recognition in the browser process. It
-// handles requests received from various render views and makes sure only one
-// of them can use speech recognition at a time. It also sends recognition
-// results and status events to the render views when required.
-class SpeechRecognitionManager {
+class SpeechRecognitionEventListener;
+struct SpeechRecognitionSessionConfig;
+struct SpeechRecognitionSessionContext;
+
+// The SpeechRecognitionManager (SRM) is a singleton class that handles SR

[Satish, 2012/04/19 13:03:19]

I like this comment block :) but feels verbose. Can it be written more
succinctly?

[Primiano Tucci (use gerrit), 2012/04/20 16:06:43]

Done.

+// functionalities within Chrome. Everyone that needs to perform SR should
+// interface exclusively with the SRM. Usually SR requires the operation and
+// coordination of several objects (an audio controller, a SR engine...). The
+// aim of the SRM is to make all this activities transparent to end users,
+// which will perceive only the SRM methods and the callback interface
+// SpeechRecognitionEventListener.
+// Since many different sources can use SR in different times (some overlapping
+// is allowed while waiting for results), the SRM has the further responsibility
+// of handling separately and reliably these different sessions, distinguishing
+// them by means of a session_id.
+// The rationale behind the word "reliably" is that while most of the classes,
+// that are (should be) NOT directly accessible to the end-user are designed to
+// work in an ideal flow (the SpeechRecognizer will get extremely offended if
+// asked to start recognition while it is already in progress), the SRM is
+// designed to interface with an evil world (the user interface / JS APIs) in
+// which very bad people that will try any possible sequence of commands, often
+// without a particular logic.
+// In this sense a session, within the SRM, models the ongoing evolution of a
+// SR request from the viewpoint of the end-user (abstracting all the concrete
+// operations that must be carried out, that will be handled by inner classes).
+// SR session requires for most of the time (i.e. audio capture) exclusive
+// interaction with the user (popup/notifications/consensus). For this reason,
+// while many SR sessions can be alive during the lifetime of the browser,
+// only one, the interactive session, is allowed to capture audio and interact
+// with the user. After the audio capture is terminated the session may
+// eventually be detached (will continue processing recorded audio and gathering
+// the results without interacting with the user). A SR session finally dies
+// either when it retrieves a valid result or when, after reporting a visible
+class CONTENT_EXPORT SpeechRecognitionManager {
  public:
+  static const int kSessionIDInvalid;
+
   // Returns the singleton instance.
-  CONTENT_EXPORT static SpeechRecognitionManager* GetInstance();
+  static SpeechRecognitionManager* GetInstance();
 
-  // Starts/restarts recognition for an existing request.
-  virtual void StartRecognitionForRequest(int session_id) = 0;
+  // Creates a new recognition session.
+  virtual int CreateSession(SpeechRecognitionSessionConfig& config,
+                            SpeechRecognitionEventListener* listener) = 0;
 
-  // Cancels recognition for an existing request.
-  virtual void CancelRecognitionForRequest(int session_id) = 0;
+  // Starts/restarts recognition for an existing session.
+  virtual void StartSession(int session_id) = 0;
 
-  // Called when the user clicks outside the speech input UI causing it to close
-  // and possibly have speech input go to another element.
-  virtual void FocusLostForRequest(int session_id) = 0;
+  // Aborts recognition for an existing session, without providing any result.
+  virtual void AbortSession(int session_id) = 0;
+
+  // Aborts all sessions for a given listener, without providing any result.
+  virtual void AbortAllSessionsForListener(
+      SpeechRecognitionEventListener* listener) = 0;
+
+  // Stops audio capture for an existing session. The audio captured before the
+  // call will be processed, possibly ending up with a result.
+  virtual void StopAudioCaptureForSession(int session_id) = 0;
+
+  // Detaches the session preventing it from interacting further with the
+  // browser (typically invoked when the user clicks outside the speech UI).
+  // The session will be silently continued in background if possible (in the
+  // case it already finished capturing audio and was just waiting for the
+  // result) or will be aborted if user interaction (e.g., audio recording) was
+  // involved at the time DetachSession was called.
+  virtual void DetachSession(int session_id) = 0;
+
+  // Retrieves the context associated to a session.
+  virtual SpeechRecognitionSessionContext& GetSessionContext(
+      int session_id) const = 0;
+
+  // Looks-up an existing session using a caller-provided matcher function.
+  virtual int LookupSessionByContext(
+      base::Callback<bool(
+          const content::SpeechRecognitionSessionContext&)> matcher)
+            const = 0;
 
   // Returns true if the OS reports existence of audio recording devices.
   virtual bool HasAudioInputDevices() = 0;
 
   // Used to determine if something else is currently making use of audio input.
   virtual bool IsCapturingAudio() = 0;
 
   // Returns a human readable string for the model/make of the active audio
   // input device for this computer.
   virtual string16 GetAudioInputDeviceModel() = 0;
 
   // Invokes the platform provided microphone settings UI in a non-blocking way,
   // via the BrowserThread::FILE thread.
   virtual void ShowAudioInputSettings() = 0;
 
  protected:
    virtual ~SpeechRecognitionManager() {}
 };
 
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_BROWSER_SPEECH_RECOGNITION_MANAGER_H_