| /* |
| * Copyright (C) 2016 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except |
| * in compliance with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software distributed under the License |
| * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express |
| * or implied. See the License for the specific language governing permissions and limitations under |
| * the License. |
| */ |
| |
| package com.android.dialer.p13n.inference.protocol; |
| |
| import android.database.Cursor; |
| import android.support.annotation.MainThread; |
| import android.support.annotation.NonNull; |
| import android.support.annotation.Nullable; |
| import java.util.List; |
| |
| /** Provides personalized ranking of outgoing call targets. */ |
| public interface P13nRanker { |
| |
| /** |
| * Re-orders a list of phone numbers according to likelihood they will be the next outgoing call. |
| * |
| * @param phoneNumbers the list of candidate numbers to call (may be in contacts list or not) |
| */ |
| @NonNull |
| @MainThread |
| List<String> rankList(@NonNull List<String> phoneNumbers); |
| |
| /** |
| * Re-orders a retrieved contact list according to likelihood they will be the next outgoing call. |
| * |
| * <p>A new cursor with reordered data is returned; the input cursor is unmodified except for its |
| * position. If the order is unchanged, this method may return a reference to the unmodified input |
| * cursor directly. The order would be unchanged if the ranking cache is not yet ready, or if the |
| * input cursor is closed or invalid, or if any other error occurs in the ranking process. |
| * |
| * @param phoneQueryResults cursor of results of a Dialer search query |
| * @param queryLength length of the search query that resulted in the cursor data, if below 0, |
| * assumes no length is specified, thus applies the default behavior which is same as when |
| * queryLength is greater than zero. |
| * @return new cursor of data reordered by ranking (or reference to input cursor if order |
| * unchanged) |
| */ |
| @NonNull |
| @MainThread |
| Cursor rankCursor(@NonNull Cursor phoneQueryResults, int queryLength); |
| |
| /** |
| * Refreshes ranking cache (pulls fresh contextual features, pre-caches inference results, etc.). |
| * |
| * <p>Asynchronously runs in background as the process might take a few seconds, notifying a |
| * listener upon completion; meanwhile, any calls to {@link #rankList} will simply return the |
| * input in same order. |
| * |
| * @param listener callback for when ranking refresh has completed; null value skips notification. |
| */ |
| @MainThread |
| void refresh(@Nullable P13nRefreshCompleteListener listener); |
| |
| /** Decides if results should be displayed for no-query search. */ |
| @MainThread |
| boolean shouldShowEmptyListForNullQuery(); |
| |
| /** |
| * Callback class for when ranking refresh has completed. |
| * |
| * <p>Primary use is to notify {@link com.android.dialer.app.DialtactsActivity} that the ranking |
| * functions {@link #rankList} and {@link #rankCursor(Cursor, int)} will now give useful results. |
| */ |
| interface P13nRefreshCompleteListener { |
| |
| /** Callback for when ranking refresh has completed. */ |
| void onP13nRefreshComplete(); |
| } |
| } |