Deprecate unused and implementation-specific parts of TTS API

TTS Voice-data related API was originally written with
one engine in mind (pico sVox TTS). It exposes some implementation
details that should be private to the engine implementation.

- Deprecating fields of ACTION_CHECK_TTS_DATA results that were
used by sVox language packs to find out location of voice data.
Those fields are TTS engine implementation details and should be
private:
EXTRA_VOICE_DATA_ROOT_DIRECTORY
EXTRA_VOICE_DATA_FILES
EXTRA_VOICE_DATA_FILES_INFO

- Deprecating fields of ACTION_CHECK_TTS_DATA request that are
providing unnescesary functionality (it can be easily done on client
side):
EXTRA_CHECK_VOICE_DATA_FOR

- Deprecating some of the return codes of ACTION_CHECK_TTS_DATA - they
are specific to sVox pico voice data and in all cases can be replaced
by CHECK_VOICE_DATA_FAIL result code.
CHECK_VOICE_DATA_BAD_DATA
CHECK_VOICE_DATA_MISSING_DATA
CHECK_VOICE_DATA_MISSING_VOLUME

- Changing semantics of ACTION_TTS_DATA_INSTALLED intent. It's now
more generic and covers any change of available voice data set (so, not only
adding languages, but also removing them should trigger broadcast. Adding and
removing features to existing locale (like embedded synthesis) should be marked
by broadcast as well).

- Deprecating its EXTRA_TTS_DATA_INSTALLED result field - client should discover
the change by running ACTION_CHECK_TTS_DATA intent.

- Making GetSampleText intent public again - it's used by most TTS engines to
provide unique demonstation data.

- Deprecating TextToSpeech.OnUtteranceCompletedListener - it was replaced
by UtteranceProgressListener in API level 15, but no one put deprecation tag
on it.

Change-Id: I6609cde5c50236457f14955e2e7c0481b2b217ec

1 files changed, 84 insertions, 36 deletions

diff --git a/core/java/android/speech/tts/TextToSpeech.java b/core/java/android/speech/tts/TextToSpeech.java
index 30a8626..06b4a3b 100644
--- a/core/java/android/speech/tts/TextToSpeech.java
+++ b/core/java/android/speech/tts/TextToSpeech.java
@@ -140,7 +140,10 @@ public class TextToSpeech {
      * Listener that will be called when the TTS service has
      * completed synthesizing an utterance. This is only called if the utterance
      * has an utterance ID (see {@link TextToSpeech.Engine#KEY_PARAM_UTTERANCE_ID}).
+     *
+     * @deprecated Use {@link UtteranceProgressListener} instead.
      */
+    @Deprecated
     public interface OnUtteranceCompletedListener {
         /**
          * Called when an utterance has been synthesized.
@@ -236,19 +239,28 @@ public class TextToSpeech {
         /**
          * Indicates erroneous data when checking the installation status of the resources used by
          * the TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
+         *
+         * @deprecated Use CHECK_VOICE_DATA_FAIL instead.
          */
+        @Deprecated
         public static final int CHECK_VOICE_DATA_BAD_DATA = -1;
 
         /**
          * Indicates missing resources when checking the installation status of the resources used
          * by the TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
+         *
+         * @deprecated Use CHECK_VOICE_DATA_FAIL instead.
          */
+        @Deprecated
         public static final int CHECK_VOICE_DATA_MISSING_DATA = -2;
 
         /**
          * Indicates missing storage volume when checking the installation status of the resources
          * used by the TextToSpeech engine with the {@link #ACTION_CHECK_TTS_DATA} intent.
+         *
+         * @deprecated Use CHECK_VOICE_DATA_FAIL instead.
          */
+        @Deprecated
         public static final int CHECK_VOICE_DATA_MISSING_VOLUME = -3;
 
         /**
@@ -284,9 +296,8 @@ public class TextToSpeech {
                 "android.speech.tts.engine.INSTALL_TTS_DATA";
 
         /**
-         * Broadcast Action: broadcast to signal the completion of the installation of
-         * the data files used by the synthesis engine. Success or failure is indicated in the
-         * {@link #EXTRA_TTS_DATA_INSTALLED} extra.
+         * Broadcast Action: broadcast to signal the change in the list of available
+         * languages or/and their features.
          */
         @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
         public static final String ACTION_TTS_DATA_INSTALLED =
@@ -299,20 +310,16 @@ public class TextToSpeech {
          * return one of the following codes:
          * {@link #CHECK_VOICE_DATA_PASS},
          * {@link #CHECK_VOICE_DATA_FAIL},
-         * {@link #CHECK_VOICE_DATA_BAD_DATA},
-         * {@link #CHECK_VOICE_DATA_MISSING_DATA}, or
-         * {@link #CHECK_VOICE_DATA_MISSING_VOLUME}.
          * <p> Moreover, the data received in the activity result will contain the following
          * fields:
          * <ul>
-         *   <li>{@link #EXTRA_VOICE_DATA_ROOT_DIRECTORY} which
-         *       indicates the path to the location of the resource files,</li>
-         *   <li>{@link #EXTRA_VOICE_DATA_FILES} which contains
-         *       the list of all the resource files,</li>
-         *   <li>and {@link #EXTRA_VOICE_DATA_FILES_INFO} which
-         *       contains, for each resource file, the description of the language covered by
-         *       the file in the xxx-YYY format, where xxx is the 3-letter ISO language code,
-         *       and YYY is the 3-letter ISO country code.</li>
+         *   <li>{@link #EXTRA_AVAILABLE_VOICES} which contains an ArrayList<String> of all the
+         *   available voices. The format of each voice is: lang-COUNTRY-variant where COUNTRY and
+         *   variant are optional (ie, "eng" or "eng-USA" or "eng-USA-FEMALE").</li>
+         *   <li>{@link #EXTRA_UNAVAILABLE_VOICES} which contains an ArrayList<String> of all the
+         *   unavailable voices (ones that user can install). The format of each voice is:
+         *   lang-COUNTRY-variant where COUNTRY and variant are optional (ie, "eng" or
+         *   "eng-USA" or "eng-USA-FEMALE").</li>
          * </ul>
          */
         @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
@@ -320,37 +327,33 @@ public class TextToSpeech {
                 "android.speech.tts.engine.CHECK_TTS_DATA";
 
         /**
-         * Activity intent for getting some sample text to use for demonstrating TTS.
+         * Activity intent for getting some sample text to use for demonstrating TTS. Specific
+         * locale have to be requested by passing following extra parameters:
+         * <ul>
+         *   <li>language</li>
+         *   <li>country</li>
+         *   <li>variant</li>
+         * </ul>
          *
-         * @hide This intent was used by engines written against the old API.
-         * Not sure if it should be exposed.
+         * Upon completion, the activity result may contain the following fields:
+         * <ul>
+         *   <li>{@link #EXTRA_SAMPLE_TEXT} which contains an String with sample text.</li>
+         * </ul>
          */
         @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
         public static final String ACTION_GET_SAMPLE_TEXT =
                 "android.speech.tts.engine.GET_SAMPLE_TEXT";
 
-        // extras for a TTS engine's check data activity
         /**
-         * Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent where
-         * the TextToSpeech engine specifies the path to its resources.
+         * Extra information received with the {@link #ACTION_GET_SAMPLE_TEXT} intent result where
+         * the TextToSpeech engine returns an String with sample text for requested voice
          */
-        public static final String EXTRA_VOICE_DATA_ROOT_DIRECTORY = "dataRoot";
+        public static final String EXTRA_SAMPLE_TEXT = "sampleText";
 
-        /**
-         * Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent where
-         * the TextToSpeech engine specifies the file names of its resources under the
-         * resource path.
-         */
-        public static final String EXTRA_VOICE_DATA_FILES = "dataFiles";
-
-        /**
-         * Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent where
-         * the TextToSpeech engine specifies the locale associated with each resource file.
-         */
-        public static final String EXTRA_VOICE_DATA_FILES_INFO = "dataFilesInfo";
 
+        // extras for a TTS engine's check data activity
         /**
-         * Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent where
+         * Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent result where
          * the TextToSpeech engine returns an ArrayList<String> of all the available voices.
          * The format of each voice is: lang-COUNTRY-variant where COUNTRY and variant are
          * optional (ie, "eng" or "eng-USA" or "eng-USA-FEMALE").
@@ -358,7 +361,7 @@ public class TextToSpeech {
         public static final String EXTRA_AVAILABLE_VOICES = "availableVoices";
 
         /**
-         * Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent where
+         * Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent result where
          * the TextToSpeech engine returns an ArrayList<String> of all the unavailable voices.
          * The format of each voice is: lang-COUNTRY-variant where COUNTRY and variant are
          * optional (ie, "eng" or "eng-USA" or "eng-USA-FEMALE").
@@ -366,22 +369,63 @@ public class TextToSpeech {
         public static final String EXTRA_UNAVAILABLE_VOICES = "unavailableVoices";
 
         /**
+         * Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent result where
+         * the TextToSpeech engine specifies the path to its resources.
+         *
+         * It may be used by language packages to find out where to put their data.
+         *
+         * @deprecated TTS engine implementation detail, this information has no use for
+         * text-to-speech API client.
+         */
+        @Deprecated
+        public static final String EXTRA_VOICE_DATA_ROOT_DIRECTORY = "dataRoot";
+
+        /**
+         * Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent result where
+         * the TextToSpeech engine specifies the file names of its resources under the
+         * resource path.
+         *
+         * @deprecated TTS engine implementation detail, this information has no use for
+         * text-to-speech API client.
+         */
+        @Deprecated
+        public static final String EXTRA_VOICE_DATA_FILES = "dataFiles";
+
+        /**
+         * Extra information received with the {@link #ACTION_CHECK_TTS_DATA} intent result where
+         * the TextToSpeech engine specifies the locale associated with each resource file.
+         *
+         * @deprecated TTS engine implementation detail, this information has no use for
+         * text-to-speech API client.
+         */
+        @Deprecated
+        public static final String EXTRA_VOICE_DATA_FILES_INFO = "dataFilesInfo";
+
+        /**
          * Extra information sent with the {@link #ACTION_CHECK_TTS_DATA} intent where the
          * caller indicates to the TextToSpeech engine which specific sets of voice data to
          * check for by sending an ArrayList<String> of the voices that are of interest.
          * The format of each voice is: lang-COUNTRY-variant where COUNTRY and variant are
          * optional (ie, "eng" or "eng-USA" or "eng-USA-FEMALE").
+         *
+         * @deprecated Redundant functionality, checking for existence of specific sets of voice
+         * data can be done on client side.
          */
+        @Deprecated
         public static final String EXTRA_CHECK_VOICE_DATA_FOR = "checkVoiceDataFor";
 
         // extras for a TTS engine's data installation
         /**
-         * Extra information received with the {@link #ACTION_TTS_DATA_INSTALLED} intent.
+         * Extra information received with the {@link #ACTION_TTS_DATA_INSTALLED} intent result.
          * It indicates whether the data files for the synthesis engine were successfully
          * installed. The installation was initiated with the  {@link #ACTION_INSTALL_TTS_DATA}
          * intent. The possible values for this extra are
          * {@link TextToSpeech#SUCCESS} and {@link TextToSpeech#ERROR}.
+         *
+         * @deprecated No longer in use. If client ise interested in information about what
+         * changed, is should send ACTION_CHECK_TTS_DATA intent to discover available voices.
          */
+        @Deprecated
         public static final String EXTRA_TTS_DATA_INSTALLED = "dataInstalled";
 
         // keys for the parameters passed with speak commands. Hidden keys are used internally
@@ -474,6 +518,10 @@ public class TextToSpeech {
          * for a description of how feature keys work. If set and supported by the engine
          * as per {@link TextToSpeech#getFeatures(Locale)}, the engine must synthesize
          * text on-device (without making network requests).
+         *
+         * @see TextToSpeech#speak(String, int, java.util.HashMap)
+         * @see TextToSpeech#synthesizeToFile(String, java.util.HashMap, String)
+         * @see TextToSpeech#getFeatures(java.util.Locale)
          */
         public static final String KEY_FEATURE_EMBEDDED_SYNTHESIS = "embeddedTts";
     }