1 /*
2  * Copyright (C) 2016 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 
17 package android.service.autofill;
18 
19 import android.annotation.Nullable;
20 import android.app.Activity;
21 import android.os.RemoteException;
22 import android.util.Log;
23 
24 /**
25  * <p><code>FillCallback</code> handles autofill requests from the {@link AutofillService} into
26  * the {@link Activity} being autofilled.
27  *
28  * <p>To learn about using Autofill services in your app, read
29  * <a href="/guide/topics/text/autofill-services">Build autofill services</a>.
30  */
31 public final class FillCallback {
32 
33     private static final String TAG = "FillCallback";
34 
35     private final IFillCallback mCallback;
36     private final int mRequestId;
37     private boolean mCalled;
38 
39     /** @hide */
FillCallback(IFillCallback callback, int requestId)40     public FillCallback(IFillCallback callback, int requestId) {
41         mCallback = callback;
42         mRequestId = requestId;
43     }
44 
45     /**
46      * Notifies the Android System that a fill request
47      * ({@link AutofillService#onFillRequest(FillRequest, android.os.CancellationSignal,
48      * FillCallback)}) was successfully fulfilled by the service.
49      *
50      * <p>This method should always be called, even if the service doesn't have the heuristics to
51      * fulfill the request (in which case it should be called with {@code null}).
52      *
53      * <p>See the main {@link AutofillService} documentation for more details and examples.
54      *
55      * @param response autofill information for that activity, or {@code null} when the service
56      * cannot autofill the activity.
57      *
58      * @throws IllegalStateException if this method or {@link #onFailure(CharSequence)} was already
59      * called.
60      */
onSuccess(@ullable FillResponse response)61     public void onSuccess(@Nullable FillResponse response) {
62         assertNotCalled();
63         mCalled = true;
64 
65         if (response != null) {
66             response.setRequestId(mRequestId);
67         }
68 
69         try {
70             mCallback.onSuccess(response);
71         } catch (RemoteException e) {
72             e.rethrowAsRuntimeException();
73         }
74     }
75 
76     /**
77      * Notifies the Android System that a fill request (
78      * {@link AutofillService#onFillRequest(FillRequest, android.os.CancellationSignal,
79      * FillCallback)}) could not be fulfilled by the service (for example, because the user data was
80      * not available yet), so the request could be retried later.
81      *
82      * <p><b>Note: </b>this method should not be used when the service didn't have the heursitics to
83      * fulfill the request; in this case, the service should call {@link #onSuccess(FillResponse)
84      * onSuccess(null)} instead.
85      *
86      * <p><b>Note: </b>prior to {@link android.os.Build.VERSION_CODES#Q}, this
87      * method was not working as intended and the service should always call
88      * {@link #onSuccess(FillResponse) onSuccess(null)} instead.
89      *
90      * <p><b>Note: </b>for apps targeting {@link android.os.Build.VERSION_CODES#Q} or higher, this
91      * method just logs the message on {@code logcat}; for apps targetting older SDKs, it also
92      * displays the message to user using a {@link android.widget.Toast}. Generally speaking, you
93      * should not display an error to the user if the request failed, unless the request had the
94      * {@link FillRequest#FLAG_MANUAL_REQUEST} flag.
95      *
96      * @param message error message. <b>Note: </b> this message should <b>not</b> contain PII
97      * (Personally Identifiable Information, such as username or email address).
98      *
99      * @throws IllegalStateException if this method or {@link #onSuccess(FillResponse)} was already
100      * called.
101      */
onFailure(@ullable CharSequence message)102     public void onFailure(@Nullable CharSequence message) {
103         Log.w(TAG, "onFailure(): " + message);
104         assertNotCalled();
105         mCalled = true;
106         try {
107             mCallback.onFailure(mRequestId, message);
108         } catch (RemoteException e) {
109             e.rethrowAsRuntimeException();
110         }
111     }
112 
assertNotCalled()113     private void assertNotCalled() {
114         if (mCalled) {
115             throw new IllegalStateException("Already called");
116         }
117     }
118 }
119