1ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian/* 2ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * Copyright (C) 2016 The Android Open Source Project 3ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * 4ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 5ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * in compliance with the License. You may obtain a copy of the License at 6ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * 7ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * http://www.apache.org/licenses/LICENSE-2.0 8ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * 9ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * Unless required by applicable law or agreed to in writing, software distributed under the License 10ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 11ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * or implied. See the License for the specific language governing permissions and limitations under 12ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * the License. 13ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian */ 14ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian 15ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanianpackage com.android.dialer.p13n.inference.protocol; 16ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian 17ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanianimport android.database.Cursor; 18ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanianimport android.support.annotation.MainThread; 19ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanianimport android.support.annotation.NonNull; 20ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanianimport android.support.annotation.Nullable; 21ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanianimport java.util.List; 22ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian 23ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian/** Provides personalized ranking of outgoing call targets. */ 24ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanianpublic interface P13nRanker { 25ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian 26ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian /** 27ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * Re-orders a list of phone numbers according to likelihood they will be the next outgoing call. 28ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * 29ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * @param phoneNumbers the list of candidate numbers to call (may be in contacts list or not) 30ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian */ 31ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian @NonNull 32ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian @MainThread 33ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian List<String> rankList(@NonNull List<String> phoneNumbers); 34ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian 35ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian /** 36ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * Re-orders a retrieved contact list according to likelihood they will be the next outgoing call. 37ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * 38ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * <p>A new cursor with reordered data is returned; the input cursor is unmodified except for its 39ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * position. If the order is unchanged, this method may return a reference to the unmodified input 40ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * cursor directly. The order would be unchanged if the ranking cache is not yet ready, or if the 41ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * input cursor is closed or invalid, or if any other error occurs in the ranking process. 42ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * 43ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * @param phoneQueryResults cursor of results of a Dialer search query 44d5e47f6da5b08b13ecdfa7f1edc7e12aeb83fab9Eric Erfanian * @param queryLength length of the search query that resulted in the cursor data, if below 0, 45d5e47f6da5b08b13ecdfa7f1edc7e12aeb83fab9Eric Erfanian * assumes no length is specified, thus applies the default behavior which is same as when 46d5e47f6da5b08b13ecdfa7f1edc7e12aeb83fab9Eric Erfanian * queryLength is greater than zero. 47ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * @return new cursor of data reordered by ranking (or reference to input cursor if order 48ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * unchanged) 49ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian */ 50ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian @NonNull 51ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian @MainThread 52d5e47f6da5b08b13ecdfa7f1edc7e12aeb83fab9Eric Erfanian Cursor rankCursor(@NonNull Cursor phoneQueryResults, int queryLength); 53ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian 54ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian /** 55ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * Refreshes ranking cache (pulls fresh contextual features, pre-caches inference results, etc.). 56ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * 57ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * <p>Asynchronously runs in background as the process might take a few seconds, notifying a 58ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * listener upon completion; meanwhile, any calls to {@link #rankList} will simply return the 59ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * input in same order. 60ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * 61ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * @param listener callback for when ranking refresh has completed; null value skips notification. 62ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian */ 63ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian @MainThread 64ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian void refresh(@Nullable P13nRefreshCompleteListener listener); 65ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian 66d5e47f6da5b08b13ecdfa7f1edc7e12aeb83fab9Eric Erfanian /** Decides if results should be displayed for no-query search. */ 67d5e47f6da5b08b13ecdfa7f1edc7e12aeb83fab9Eric Erfanian @MainThread 68d5e47f6da5b08b13ecdfa7f1edc7e12aeb83fab9Eric Erfanian boolean shouldShowEmptyListForNullQuery(); 69d5e47f6da5b08b13ecdfa7f1edc7e12aeb83fab9Eric Erfanian 70ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian /** 71ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * Callback class for when ranking refresh has completed. 72ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * 73ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * <p>Primary use is to notify {@link com.android.dialer.app.DialtactsActivity} that the ranking 74ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian * functions {@link #rankList} and {@link #rankCursor(Cursor, int)} will now give useful results. 75ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian */ 76ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian interface P13nRefreshCompleteListener { 77ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian 78ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian /** Callback for when ranking refresh has completed. */ 79ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian void onP13nRefreshComplete(); 80ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian } 81ccca31529c07970e89419fb85a9e8153a5396838Eric Erfanian} 82