Add VisualQueryDetectionService Callbacks

Provides callback interface for VisualQueryDetectionService to send
attnetion/detection signals to upstream consumer like assistant and
SysUI.

Bug: 261783496
Test: atest CtsVoiceInteractionTestCases
API-Coverage-Bug: 264039061
Change-Id: Ia46875d67a4f038bb1f47ba407167020c06e8159

core/api/system-current.txt

@@ -12557,6 +12557,11 @@ package android.service.voice {
 
   public static final class VisualQueryDetectionService.Callback {
     ctor public VisualQueryDetectionService.Callback();
+    method public void onAttentionGained();
+    method public void onAttentionLost();
+    method public void onQueryDetected(@NonNull String) throws java.lang.IllegalStateException;
+    method public void onQueryFinished() throws java.lang.IllegalStateException;
+    method public void onQueryRejected() throws java.lang.IllegalStateException;
   }
 
   public class VoiceInteractionService extends android.app.Service {

core/java/android/service/voice/VisualQueryDetectionService.java

@@ -190,9 +190,86 @@ public abstract class VisualQueryDetectionService extends Service
 
     /**
      * Callback for sending out signals and returning query results.
+     *
+     * On successful user attention, developers should call {@link Callback#onAttentionGained()}
+     * to enable the streaming of the query.
+     * <p>
+     * On user attention is lost, developers should call {@link Callback#onAttentionLost()} to
+     * disable the streaming of the query.
+     * <p>
+     * On query is detected and ready to stream, developers should call
+     * {@link Callback#onQueryDetected(String)} to return detected query to the
+     * {@link VisualQueryDetector}.
+     * <p>
+     * On streamed query should be rejected, clients should call {@link Callback#onQueryRejected()}
+     * to abandon query streamed to the {@link VisualQueryDetector}.
+     * <p>
+     * On streamed query is finished, clients should call {@link Callback#onQueryFinished()} to
+     * complete query streamed to {@link VisualQueryDetector}.
+     * <p>
+     * Before a call for {@link Callback#onQueryDetected(String)} is triggered,
+     * {@link Callback#onAttentionGained()} MUST be called to enable the streaming of query. A query
+     * streaming is also expected to be finished by calling either
+     * {@link Callback#onQueryFinished()} or {@link Callback#onQueryRejected()} before a new query
+     * should start streaming. When the service enters the state where query streaming should be
+     * disabled, {@link Callback#onAttentionLost()} MUST be called to block unnecessary streaming.
      */
     public static final class Callback {
-        //TODO: Add callback to send signals to VIS and SysUI.
+
+        /**
+         * Informs attention listener that the user attention is gained.
+         */
+        public void onAttentionGained() {
+            //TODO(b/265345361): call internal callbacks to send signal to the interactor
+        }
+
+        /**
+         * Informs attention listener that the user attention is lost.
+         */
+        public void onAttentionLost() {
+            //TODO(b/265345361): call internal callbacks to send signal to the interactor
+        }
+
+        /**
+         * Informs the {@link VisualQueryDetector} with the text content being captured about the
+         * query from the audio source. {@code partialQuery} is provided to the
+         * {@link VisualQueryDetector}. This method is expected to be only triggered if
+         * {@link Callback#onAttentionGained()} is called to put the service into the attention
+         * gained state.
+         *
+         * @param partialQuery Partially detected query in string.
+         * @throws IllegalStateException if method called without attention gained.
+         */
+        public void onQueryDetected(@NonNull String partialQuery) throws IllegalStateException {
+            //TODO(b/265345361): call internal callbacks to send signal to the interactor
+            //TODO(b/265381651): convert callback exceptions and throw IllegalStateException.
+        }
+
+        /**
+         * Informs the {@link VisualQueryDetector} to abandon the streamed partial query that has
+         * been sent to {@link VisualQueryDetector}.This method is expected to be only triggered if
+         * {@link Callback#onQueryDetected()} is called to put the service into the query streaming
+         * state.
+         *
+         * @throws IllegalStateException if method called without query streamed.
+         */
+        public void onQueryRejected() throws IllegalStateException {
+            //TODO(b/265345361): call internal callbacks to send signal to the interactor
+            //TODO(b/265381651): convert callback exceptions and throw IllegalStateException.
+        }
+
+        /**
+         * Informs {@link VisualQueryDetector} with the metadata to complete the streamed partial
+         * query that has been sent to {@link VisualQueryDetector}. This method is expected to be
+         * only triggered if {@link Callback#onQueryDetected()} is called to put the service into
+         * the query streaming state.
+         *
+         * @throws IllegalStateException if method called without query streamed.
+         */
+        public void onQueryFinished() throws IllegalStateException {
+            //TODO(b/265345361): call internal callbacks to send signal to the interactor
+            //TODO(b/265381651): convert callback exceptions and throw IllegalStateException.
+        }
     }
 
 }