1 /*
2  * Copyright (C) 2020 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 package android.app.search;
17 
18 import android.annotation.NonNull;
19 import android.annotation.SystemApi;
20 import android.os.Bundle;
21 import android.os.Parcel;
22 import android.os.Parcelable;
23 
24 /**
25  * Query object is sent over from client to the service.
26  *
27  * Inside the query object, there is a timestamp that trackes when the query string was typed.
28  *
29  * If this object was created for the {@link SearchSession#query},
30  * the client expects first consumer to be returned
31  * within {@link #getTimestampMillis()} + {@link SearchContext#getTimeoutMillis()}
32  * Base of the timestamp should be SystemClock.elasedRealTime()
33  *
34  * @hide
35  */
36 @SystemApi
37 public final class Query implements Parcelable {
38 
39     /**
40      * The lookup key for a integer that indicates what the height of the soft keyboard
41      * (e.g., IME, also known as Input Method Editor) was on the client window
42      * in dp (density-independent pixels). This information is to be used by the consumer
43      * of the API in estimating how many search results will be visible above the keyboard.
44      */
45     public static final String EXTRA_IME_HEIGHT = "android.app.search.extra.IME_HEIGHT";
46 
47     /**
48      * string typed from the client.
49      */
50     @NonNull
51     private final String mInput;
52 
53     private final long mTimestampMillis;
54 
55     /**
56      * Contains other client UI constraints related data (e.g., {@link #EXTRA_IME_HEIGHT}.
57      */
58     @NonNull
59     private final Bundle mExtras;
60 
61     /**
62      * Query object used to pass search box input from client to service.
63      *
64      * @param input string typed from the client
65      * @param timestampMillis timestamp that query string was typed.
66      * @param extras bundle that contains other client UI constraints data
67      */
Query(@onNull String input, long timestampMillis, @NonNull Bundle extras)68     public Query(@NonNull String input,
69             long timestampMillis,
70             @NonNull Bundle extras) {
71         mInput = input;
72         mTimestampMillis = timestampMillis;
73         mExtras = extras != null ? extras : new Bundle();
74     }
75 
76     /**
77      * Query object used to pass search box input from client to service.
78      *
79      * @param input string typed from the client
80      * @param timestampMillis timestamp that query string was typed
81      */
Query(@onNull String input, long timestampMillis)82     public Query(@NonNull String input, long timestampMillis) {
83         this(input, timestampMillis, new Bundle());
84     }
85 
Query(Parcel parcel)86     private Query(Parcel parcel) {
87         mInput = parcel.readString();
88         mTimestampMillis = parcel.readLong();
89         mExtras = parcel.readBundle();
90     }
91 
92     /**
93      * @return string typed from the client
94      */
95     @NonNull
getInput()96     public String getInput() {
97         return mInput;
98     }
99 
100     /**
101      * @deprecated Will be replaced by {@link #getTimestampMillis()} as soon as
102      * new SDK is adopted.
103      *
104      * @removed
105      */
106     @Deprecated
107     @NonNull
getTimestamp()108     public long getTimestamp() {
109         return mTimestampMillis;
110     }
111 
112     /**
113      * Base of the timestamp should be SystemClock.elasedRealTime()
114      *
115      * @return timestamp that query string was typed
116      */
getTimestampMillis()117     public long getTimestampMillis() {
118         return mTimestampMillis;
119     }
120 
121     /**
122      * @return bundle that contains other client constraints related to the query
123      */
124     @NonNull
getExtras()125     public Bundle getExtras() {
126         if (mExtras == null) {
127             return new Bundle();
128         }
129         return mExtras;
130     }
131 
132     @Override
describeContents()133     public int describeContents() {
134         return 0;
135     }
136 
137     @Override
writeToParcel(@onNull Parcel dest, int flags)138     public void writeToParcel(@NonNull Parcel dest, int flags) {
139         dest.writeString(mInput);
140         dest.writeLong(mTimestampMillis);
141         dest.writeBundle(mExtras);
142     }
143 
144     /**
145      * @see Creator
146      */
147     @NonNull
148     public static final Creator<Query> CREATOR =
149             new Creator<Query>() {
150                 public Query createFromParcel(Parcel parcel) {
151                     return new Query(parcel);
152                 }
153 
154                 public Query[] newArray(int size) {
155                     return new Query[size];
156                 }
157             };
158 }
159