RecognizerResultsIntent.java revision f9271c8b7dfafecef6747c81aa1c9038ab51d274 
1/*
2 * Copyright (C) 2010 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.speech;
18
19import java.util.ArrayList;
20
21/**
22 * Constants for intents related to showing speech recognition results.
23 *
24 * These constants should not be needed for normal utilization of speech recognition. They
25 * would only be called if you wanted to trigger a view of voice search results in your
26 * application, or implemented if you wanted to offer a different view for voice search results
27 * with your application.
28 *
29 * The standard behavior here for someone receiving an {@link #ACTION_VOICE_SEARCH_RESULTS} is to
30 * first retrieve the list of {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS}, and use any provided
31 * HTML for that result in {@link #EXTRA_VOICE_SEARCH_RESULT_HTML}, if available, to display
32 * the search results. If that is not available, then the corresponding url for that result in
33 * {@link #EXTRA_VOICE_SEARCH_RESULT_URLS} should be used. And if even that is not available,
34 * then a search url should be constructed from the actual recognition result string.
35 *
36 * @hide for making public in a later release
37 */
38public class RecognizerResultsIntent {
39    private RecognizerResultsIntent() {
40        // Not for instantiating.
41    }
42
43    /**
44     * Intent that can be sent by implementations of voice search to display the results of
45     * a search in, for example, a web browser.
46     *
47     * This intent should always be accompanied by at least
48     * {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS}, and optionally but recommended,
49     * {@link #EXTRA_VOICE_SEARCH_RESULT_URLS}, and sometimes
50     * {@link #EXTRA_VOICE_SEARCH_RESULT_HTML} and
51     * {@link #EXTRA_VOICE_SEARCH_RESULT_HTML_BASE_URLS}.
52     *
53     * These are parallel arrays, where a recognition result string at index N of
54     * {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS} should be accompanied by a url to use for
55     * searching based on that string at index N of {@link #EXTRA_VOICE_SEARCH_RESULT_URLS},
56     * and, possibly, the full html to display for that result at index N of
57     * {@link #EXTRA_VOICE_SEARCH_RESULT_HTML}. If full html is provided, a base url (or
58     * list of base urls) should be provided with {@link #EXTRA_VOICE_SEARCH_RESULT_HTML_BASE_URLS}.
59     *
60     * @hide for making public in a later release
61     */
62    public static final String ACTION_VOICE_SEARCH_RESULTS =
63            "android.speech.action.VOICE_SEARCH_RESULTS";
64
65    /**
66     * The key to an extra {@link ArrayList} of {@link String}s that contains the list of
67     * recognition alternates from voice search, in order from highest to lowest confidence.
68     *
69     * @hide for making public in a later release
70     */
71    public static final String EXTRA_VOICE_SEARCH_RESULT_STRINGS =
72            "android.speech.extras.VOICE_SEARCH_RESULT_STRINGS";
73
74    /**
75     * The key to an extra {@link ArrayList} of {@link String}s that contains the search urls
76     * to use, if available, for the recognition alternates provided in
77     * {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS}. This list should always be the same size as the
78     * one provided in {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS} - if a result cannot provide a
79     * search url, that entry in this ArrayList should be <code>null</code>, and the implementor of
80     * {@link #ACTION_VOICE_SEARCH_RESULTS} should execute a search of its own choosing,
81     * based on the recognition result string.
82     *
83     * @hide for making public in a later release
84     */
85    public static final String EXTRA_VOICE_SEARCH_RESULT_URLS =
86            "android.speech.extras.VOICE_SEARCH_RESULT_URLS";
87
88    /**
89     * The key to an extra {@link ArrayList} of {@link String}s that contains the html content to
90     * use, if available, for the recognition alternates provided in
91     * {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS}. This list should always be the same size as the
92     * one provided in {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS} - if a result cannot provide
93     * html, that entry in this list should be <code>null</code>, and the implementor of
94     * {@link #ACTION_VOICE_SEARCH_RESULTS} should back off to the corresponding url provided in
95     * {@link #EXTRA_VOICE_SEARCH_RESULT_URLS}, if available, or else should execute a search of
96     * its own choosing, based on the recognition result string.
97     *
98     * Currently this html content should be expected in the form of an "inline:" uri for the
99     * Browser. In the future this may change to a "content://" uri or some other identifier.
100     * Anyone who reads this extra should confirm that a result is in fact an "inline:" uri and
101     * back off to the urls or strings gracefully if it is not, thus maintaining future backwards
102     * compatibility if this changes.
103     *
104     * @hide not to be exposed immediately as the implementation details may change
105     */
106    public static final String EXTRA_VOICE_SEARCH_RESULT_HTML =
107            "android.speech.extras.VOICE_SEARCH_RESULT_HTML";
108
109    /**
110     * The key to an extra {@link ArrayList} of {@link String}s that contains the base url to
111     * assume when interpreting html provided in {@link #EXTRA_VOICE_SEARCH_RESULT_HTML}.
112     *
113     * A list of size 1 may be provided to apply the same base url to all html results.
114     * A list of the same size as {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS} may be provided
115     * to apply different base urls to each different html result in the
116     * {@link #EXTRA_VOICE_SEARCH_RESULT_HTML} list.
117     *
118     * @hide not to be exposed immediately as the implementation details may change
119     */
120    public static final String EXTRA_VOICE_SEARCH_RESULT_HTML_BASE_URLS =
121            "android.speech.extras.VOICE_SEARCH_RESULT_HTML_BASE_URLS";
122}
123