RecognizerResultsIntent.java revision 2ffa625a2ad57614e0a963899669ee542d1ca988 
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 android.os.Bundle;
20
21import java.util.ArrayList;
22
23/**
24 * Constants for intents related to showing speech recognition results.
25 *
26 * These constants should not be needed for normal utilization of speech recognition. They
27 * would only be called if you wanted to trigger a view of voice search results in your
28 * application, or implemented if you wanted to offer a different view for voice search results
29 * with your application.
30 *
31 * The standard behavior here for someone receiving an {@link #ACTION_VOICE_SEARCH_RESULTS} is to
32 * first retrieve the list of {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS}, and use any provided
33 * HTML for that result in {@link #EXTRA_VOICE_SEARCH_RESULT_HTML}, if available, to display
34 * the search results. If that is not available, then the corresponding url for that result in
35 * {@link #EXTRA_VOICE_SEARCH_RESULT_URLS} should be used. And if even that is not available,
36 * then a search url should be constructed from the actual recognition result string.
37 *
38 * @hide for making public in a later release
39 */
40public class RecognizerResultsIntent {
41    private RecognizerResultsIntent() {
42        // Not for instantiating.
43    }
44
45    /**
46     * Intent that can be sent by implementations of voice search to display the results of
47     * a search in, for example, a web browser.
48     *
49     * This intent should always be accompanied by at least
50     * {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS}, and optionally but recommended,
51     * {@link #EXTRA_VOICE_SEARCH_RESULT_URLS}, and sometimes
52     * {@link #EXTRA_VOICE_SEARCH_RESULT_HTML} and
53     * {@link #EXTRA_VOICE_SEARCH_RESULT_HTML_BASE_URLS}.
54     *
55     * These are parallel arrays, where a recognition result string at index N of
56     * {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS} should be accompanied by a url to use for
57     * searching based on that string at index N of {@link #EXTRA_VOICE_SEARCH_RESULT_URLS},
58     * and, possibly, the full html to display for that result at index N of
59     * {@link #EXTRA_VOICE_SEARCH_RESULT_HTML}. If full html is provided, a base url (or
60     * list of base urls) should be provided with {@link #EXTRA_VOICE_SEARCH_RESULT_HTML_BASE_URLS}.
61     *
62     * @hide for making public in a later release
63     */
64    public static final String ACTION_VOICE_SEARCH_RESULTS =
65            "android.speech.action.VOICE_SEARCH_RESULTS";
66
67    /**
68     * The key to an extra {@link ArrayList} of {@link String}s that contains the list of
69     * recognition alternates from voice search, in order from highest to lowest confidence.
70     *
71     * @hide for making public in a later release
72     */
73    public static final String EXTRA_VOICE_SEARCH_RESULT_STRINGS =
74            "android.speech.extras.VOICE_SEARCH_RESULT_STRINGS";
75
76    /**
77     * The key to an extra {@link ArrayList} of {@link String}s that contains the search urls
78     * to use, if available, for the recognition alternates provided in
79     * {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS}. This list should always be the same size as the
80     * one provided in {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS} - if a result cannot provide a
81     * search url, that entry in this ArrayList should be <code>null</code>, and the implementor of
82     * {@link #ACTION_VOICE_SEARCH_RESULTS} should execute a search of its own choosing,
83     * based on the recognition result string.
84     *
85     * @hide for making public in a later release
86     */
87    public static final String EXTRA_VOICE_SEARCH_RESULT_URLS =
88            "android.speech.extras.VOICE_SEARCH_RESULT_URLS";
89
90    /**
91     * The key to an extra {@link ArrayList} of {@link String}s that contains the html content to
92     * use, if available, for the recognition alternates provided in
93     * {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS}. This list should always be the same size as the
94     * one provided in {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS} - if a result cannot provide
95     * html, that entry in this list should be <code>null</code>, and the implementor of
96     * {@link #ACTION_VOICE_SEARCH_RESULTS} should back off to the corresponding url provided in
97     * {@link #EXTRA_VOICE_SEARCH_RESULT_URLS}, if available, or else should execute a search of
98     * its own choosing, based on the recognition result string.
99     *
100     * Currently this html content should be expected in the form of a uri with scheme
101     * {@link #URI_SCHEME_INLINE} for the Browser. In the future this may change to a "content://"
102     * uri or some other identifier. Anyone who reads this extra should confirm that a result is
103     * in fact an "inline:" uri and back off to the urls or strings gracefully if it is not, thus
104     * maintaining future backwards compatibility if this changes.
105     *
106     * @hide not to be exposed immediately as the implementation details may change
107     */
108    public static final String EXTRA_VOICE_SEARCH_RESULT_HTML =
109            "android.speech.extras.VOICE_SEARCH_RESULT_HTML";
110
111    /**
112     * The key to an extra {@link ArrayList} of {@link String}s that contains the base url to
113     * assume when interpreting html provided in {@link #EXTRA_VOICE_SEARCH_RESULT_HTML}.
114     *
115     * A list of size 1 may be provided to apply the same base url to all html results.
116     * A list of the same size as {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS} may be provided
117     * to apply different base urls to each different html result in the
118     * {@link #EXTRA_VOICE_SEARCH_RESULT_HTML} list.
119     *
120     * @hide not to be exposed immediately as the implementation details may change
121     */
122    public static final String EXTRA_VOICE_SEARCH_RESULT_HTML_BASE_URLS =
123            "android.speech.extras.VOICE_SEARCH_RESULT_HTML_BASE_URLS";
124
125    /**
126     * The key to an extra {@link ArrayList} of {@link Bundle}s that contains key/value pairs.
127     * All the values and the keys are {@link String}s. Each key/value pair represents an extra HTTP
128     * header. The keys can't be the standard HTTP headers as they are set by the WebView.
129     *
130     * A list of size 1 may be provided to apply the same HTTP headers to all html results. A list
131     * of the same size as {@link #EXTRA_VOICE_SEARCH_RESULT_STRINGS} may be provided to apply
132     * different HTTP headers to each different html result in the
133     * {@link #EXTRA_VOICE_SEARCH_RESULT_HTML} list.
134     *
135     * @hide not to be exposed immediately as the implementation details may change
136     */
137    public static final String EXTRA_VOICE_SEARCH_RESULT_HTTP_HEADERS =
138            "android.speech.extras.EXTRA_VOICE_SEARCH_RESULT_HTTP_HEADERS";
139
140    /**
141     * The scheme used currently for html content in {@link #EXTRA_VOICE_SEARCH_RESULT_HTML}.
142     *
143     * @hide not to be exposed immediately as the implementation details may change
144     */
145    public static final String URI_SCHEME_INLINE = "inline";
146}
147