Merge change 2692 into donut

* changes:
  * Chagned RecognitionService interface to use more complex RecognitionResult instead of String.

core/java/android/speech/IRecognitionListener.aidl

@@ -17,6 +17,7 @@
 package android.speech;
 
 import android.os.Bundle;
+import android.speech.RecognitionResult;
 
 /**
  * Listener for speech recognition events, used with RecognitionService.
@@ -43,13 +44,19 @@ interface IRecognitionListener {
     /** Called after the user stops speaking. */
     void onEndOfSpeech();
 
-    /** A network or recognition error occurred. */
+    /**
-    void onError(in String error);
+     * A network or recognition error occurred.
+     * TODO: right now, the error code is given in voice search package
+     * (vendor/google/apps/src/com/google/android/voicesearch/speechservice/SpeechServiceListener.java)
+     * we need to find a place to define common error code.
+     */
+    void onError(in int error);
 
     /** 
-     * Called when recognition transcripts are ready.
+     * Called when recognition results are ready.
-     * results: an ordered list of the most likely transcripts (N-best list).
+     * @param results: an ordered list of the most likely results (N-best list).
-     * @hide
+     * @param key: a key associated with the results. The same results can
+     * be retrieved asynchronously later using the key, if available. 
      */
-    void onResults(in List<String> results);
+    void onResults(in List<RecognitionResult> results, long key);
 }

core/java/android/speech/IRecognitionService.aidl

@@ -18,6 +18,7 @@ package android.speech;
 
 import android.content.Intent;
 import android.speech.IRecognitionListener;
+import android.speech.RecognitionResult;
 
 // A Service interface to speech recognition. Call startListening when
 // you want to begin capturing audio; RecognitionService will automatically
@@ -30,5 +31,7 @@ interface IRecognitionService {
     void startListening(in Intent recognizerIntent,
         in IRecognitionListener listener);
         
+    List<RecognitionResult> getRecognitionResults(in long key);
+
     void cancel();
 }

core/java/android/speech/RecognitionResult.aidl

@@ -0,0 +1,19 @@
+/*
+ * Copyright (C) 2009 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.speech;
+
+parcelable RecognitionResult;

core/java/android/speech/RecognitionResult.java

@@ -0,0 +1,151 @@
+/*
+ * Copyright (C) 2008 Google Inc.
+ * 
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ * 
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package android.speech;
+
+import android.os.Parcel;
+import android.os.Parcelable;
+
+/**
+ * RecognitionResult is a passive object that stores a single recognized
+ * query and its search result.
+ * TODO: revisit and improve. May be we should have a separate result
+ * object for each type, and put them (type/value) in bundle?
+ * 
+ * {@hide}
+ */
+public class RecognitionResult implements Parcelable {
+
+    /**
+     * Type of the recognition results. 
+     */
+    public static final int RAW_RECOGNITION_RESULT  = 0;
+    public static final int WEB_SEARCH_RESULT  = 1;
+    public static final int CONTACT_RESULT = 2;
+
+    /**
+     * A factory method to create a raw RecognitionResult
+     * 
+     * @param sentence the recognized text.
+     */
+    public static RecognitionResult newRawRecognitionResult(String sentence) {
+        return new RecognitionResult(RAW_RECOGNITION_RESULT, sentence, null, null);
+    }
+
+    /**
+     * A factory method to create RecognitionResult for contacts.
+     * 
+     * @param contact the contact name.
+     * @param phoneType the phone type.
+     */
+    public static RecognitionResult newContactResult(String contact, int phoneType) {
+        return new RecognitionResult(CONTACT_RESULT, contact, phoneType);
+    }
+
+    /**
+     * A factory method to create a RecognitionResult for Web Search Query.
+     * 
+     * @param query the query string. 
+     * @param html the html page of the search result.
+     * @param url  the url that performs the search with the query.
+     */
+    public static RecognitionResult newWebResult(String query, String html, String url) {
+        return new RecognitionResult(WEB_SEARCH_RESULT, query, html, url);
+    }
+    
+    public static final Parcelable.Creator<RecognitionResult> CREATOR
+            = new Parcelable.Creator<RecognitionResult>() {
+
+        public RecognitionResult createFromParcel(Parcel in) {
+            return new RecognitionResult(in);
+        }
+        
+        public RecognitionResult[] newArray(int size) {
+            return new RecognitionResult[size];
+        }
+    };
+
+    /**
+     * Result type.
+     */
+    public final int mResultType;
+
+     /**
+     * The recognized string when mResultType is WEB_SEARCH_RESULT.
+     * The name of the contact when mResultType is CONTACT_RESULT.
+     */
+    public final String mText;
+
+    /**
+     * The HTML result page for the query. If this is null, then the
+     * application must use the url field to get the HTML result page.
+     */
+    public final String mHtml;
+
+    /**
+     * The url to get the result page for the query string.  The
+     * application must use this url instead of performing the search
+     * with the query.
+     */
+    public final String mUrl;
+
+    /** Phone number type. This is valid only when mResultType == CONTACT_RESULT */
+    public final int mPhoneType;
+
+    private RecognitionResult(int type, String query, String html, String url) {
+        mResultType = type;
+        mText = query;
+        mHtml = html;
+        mUrl = url;
+        mPhoneType = -1;
+    }
+
+    private RecognitionResult(int type, String query, int at) {
+        mResultType = type;
+        mText = query;
+        mPhoneType = at;
+        mHtml = null;
+        mUrl = null;
+    }
+    
+    private RecognitionResult(Parcel in) {
+        mResultType = in.readInt();
+        mText = in.readString();
+        mHtml= in.readString();
+        mUrl= in.readString();
+        mPhoneType = in.readInt();
+    }
+
+    public void writeToParcel(Parcel out, int flags) {
+        out.writeInt(mResultType);
+        out.writeString(mText);
+        out.writeString(mHtml);
+        out.writeString(mUrl);
+        out.writeInt(mPhoneType);
+    }
+    
+    
+    @Override
+    public String toString() {
+        String resultType[] = { "RAW", "WEB", "CONTACT" };
+        return "[type=" +  resultType[mResultType] +
+                ", text=" + mText+ ", mUrl=" + mUrl + ", html=" + mHtml + "]";
+    }
+
+    public int describeContents() {
+        // no special description
+        return 0;
+    }
+}

core/java/android/speech/RecognitionServiceUtil.java

@@ -21,6 +21,9 @@ import android.content.Intent;
 import android.content.ServiceConnection;
 import android.os.Bundle;
 import android.os.IBinder;
+import android.os.RemoteException;
+import android.speech.RecognitionResult;
+import android.util.Log;
 
 import java.util.List;
 
@@ -56,6 +59,11 @@ public class RecognitionServiceUtil {
     public static final Intent sDefaultIntent = new Intent(
             RecognizerIntent.ACTION_RECOGNIZE_SPEECH);
 
+    // Recognize request parameters
+    public static final String USE_LOCATION = "useLocation";
+    public static final String CONTACT_AUTH_TOKEN = "contactAuthToken";
+    
+    // Bundles
     public static final String NOISE_LEVEL = "NoiseLevel";
     public static final String SIGNAL_NOISE_RATIO = "SignalNoiseRatio";
 
@@ -72,8 +80,8 @@ public class RecognitionServiceUtil {
         public void onRmsChanged(float rmsdB) {}
         public void onBufferReceived(byte[] buf) {}
         public void onEndOfSpeech() {}
-        public void onError(String error) {}
+        public void onError(int error) {}
-        public void onResults(List<String> results) {}
+        public void onResults(List<RecognitionResult> results, long key) {}
     }
 
     /**