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