diff --git a/core/api/system-current.txt b/core/api/system-current.txt index 33ea8e1e09911..07d739a098586 100644 --- a/core/api/system-current.txt +++ b/core/api/system-current.txt @@ -12584,6 +12584,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 { diff --git a/core/java/android/service/voice/VisualQueryDetectionService.java b/core/java/android/service/voice/VisualQueryDetectionService.java index d8266f3f7a0f1..7926901601597 100644 --- a/core/java/android/service/voice/VisualQueryDetectionService.java +++ b/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. + *
+ * On user attention is lost, developers should call {@link Callback#onAttentionLost()} to + * disable the streaming of the query. + *
+ * On query is detected and ready to stream, developers should call + * {@link Callback#onQueryDetected(String)} to return detected query to the + * {@link VisualQueryDetector}. + *
+ * On streamed query should be rejected, clients should call {@link Callback#onQueryRejected()} + * to abandon query streamed to the {@link VisualQueryDetector}. + *
+ * On streamed query is finished, clients should call {@link Callback#onQueryFinished()} to + * complete query streamed to {@link VisualQueryDetector}. + *
+ * 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. + } } }