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 com.android.dialer.spam; 18 19 import android.preference.Preference; 20 import android.preference.Preference.OnPreferenceChangeListener; 21 import android.provider.CallLog.Calls; 22 import android.support.annotation.Nullable; 23 import com.android.dialer.DialerPhoneNumber; 24 import com.android.dialer.logging.ContactLookupResult; 25 import com.android.dialer.logging.ContactSource; 26 import com.android.dialer.logging.ReportingLocation; 27 import com.android.dialer.spam.status.SpamStatus; 28 import com.google.common.collect.ImmutableMap; 29 import com.google.common.collect.ImmutableSet; 30 import com.google.common.util.concurrent.ListenableFuture; 31 32 /** Allows the container application to mark calls as spam. */ 33 public interface Spam { 34 35 /** 36 * Checks if each of numbers in the given list is suspected of being a spam. 37 * 38 * @param dialerPhoneNumbers A set of {@link DialerPhoneNumber}. 39 * @return A {@link ListenableFuture} of a map that maps each number to its {@link SpamStatus}. 40 */ batchCheckSpamStatus( ImmutableSet<DialerPhoneNumber> dialerPhoneNumbers)41 ListenableFuture<ImmutableMap<DialerPhoneNumber, SpamStatus>> batchCheckSpamStatus( 42 ImmutableSet<DialerPhoneNumber> dialerPhoneNumbers); 43 44 /** 45 * Checks if the given number is suspected of being spam. 46 * 47 * @param dialerPhoneNumber the phone number. 48 * @return the {@link SpamStatus} for the given number. 49 */ checkSpamStatus(DialerPhoneNumber dialerPhoneNumber)50 ListenableFuture<SpamStatus> checkSpamStatus(DialerPhoneNumber dialerPhoneNumber); 51 52 /** 53 * Checks if the given number is suspected of being spam. 54 * 55 * <p>See {@link #checkSpamStatus(DialerPhoneNumber)}. 56 * 57 * @param number the phone number. 58 * @param defaultCountryIso the default country to use if it's not part of the number. 59 * @return the {@link SpamStatus} for the given number. 60 */ checkSpamStatus(String number, @Nullable String defaultCountryIso)61 ListenableFuture<SpamStatus> checkSpamStatus(String number, @Nullable String defaultCountryIso); 62 63 /** 64 * Called as an indication that the Spam implementation should check whether downloading a spam 65 * list needs to occur or not. 66 * 67 * @param isEnabledByUser true if spam is enabled by the user. Generally, this value should be 68 * passed as {@link SpamSettings#isSpamEnabled()}. In the scenario where the user toggles the 69 * spam setting isSpamEnabled returns stale data: the SharedPreferences will not have updated 70 * prior to executing {@link OnPreferenceChangeListener#onPreferenceChange(Preference, 71 * Object)}. For that case, use the new value provided in the onPreferenceChange callback. 72 * @return a future containing no value. It is only an indication of success or failure of the 73 * operation. 74 */ updateSpamListDownload(boolean isEnabledByUser)75 ListenableFuture<Void> updateSpamListDownload(boolean isEnabledByUser); 76 77 /** 78 * Synchronously checks if the given number is suspected of being a spamer. 79 * 80 * @param number The phone number of the call. 81 * @param countryIso The country ISO of the call. 82 * @return True if the number is spam. 83 */ checkSpamStatusSynchronous(String number, String countryIso)84 boolean checkSpamStatusSynchronous(String number, String countryIso); 85 86 /** 87 * Returns a {@link ListenableFuture} indicating whether the spam data have been updated since 88 * {@code timestampMillis}. 89 * 90 * <p>It is the caller's responsibility to ensure the timestamp is in milliseconds. Failure to do 91 * so will result in undefined behavior. 92 */ dataUpdatedSince(long timestampMillis)93 ListenableFuture<Boolean> dataUpdatedSince(long timestampMillis); 94 95 /** 96 * Reports number as spam. 97 * 98 * @param number The number to be reported. 99 * @param countryIso The country ISO of the number. 100 * @param callType Whether the type of call is missed, voicemail, etc. Example of this is {@link 101 * android.provider.CallLog.Calls#VOICEMAIL_TYPE}. 102 * @param from Where in the dialer this was reported from. Must be one of {@link 103 * com.android.dialer.logging.ReportingLocation}. 104 * @param contactLookupResultType The result of the contact lookup for this phone number. Must be 105 * one of {@link com.android.dialer.logging.ContactLookupResult}. 106 */ reportSpamFromAfterCallNotification( String number, String countryIso, int callType, ReportingLocation.Type from, ContactLookupResult.Type contactLookupResultType)107 void reportSpamFromAfterCallNotification( 108 String number, 109 String countryIso, 110 int callType, 111 ReportingLocation.Type from, 112 ContactLookupResult.Type contactLookupResultType); 113 114 /** 115 * Reports number as spam. 116 * 117 * @param number The number to be reported. 118 * @param countryIso The country ISO of the number. 119 * @param callType Whether the type of call is missed, voicemail, etc. Example of this is {@link 120 * android.provider.CallLog.Calls#VOICEMAIL_TYPE}. 121 * @param from Where in the dialer this was reported from. Must be one of {@link 122 * com.android.dialer.logging.ReportingLocation}. 123 * @param contactSourceType If we have cached contact information for the phone number, this 124 * indicates its source. Must be one of {@link com.android.dialer.logging.ContactSource}. 125 */ reportSpamFromCallHistory( String number, String countryIso, int callType, ReportingLocation.Type from, ContactSource.Type contactSourceType)126 void reportSpamFromCallHistory( 127 String number, 128 String countryIso, 129 int callType, 130 ReportingLocation.Type from, 131 ContactSource.Type contactSourceType); 132 133 /** 134 * Reports number as not spam. 135 * 136 * @param number The number to be reported. 137 * @param countryIso The country ISO of the number. 138 * @param callType Whether the type of call is missed, voicemail, etc. Example of this is {@link 139 * android.provider.CallLog.Calls#VOICEMAIL_TYPE}. 140 * @param from Where in the dialer this was reported from. Must be one of {@link 141 * com.android.dialer.logging.ReportingLocation}. 142 * @param contactLookupResultType The result of the contact lookup for this phone number. Must be 143 * one of {@link com.android.dialer.logging.ContactLookupResult}. 144 */ reportNotSpamFromAfterCallNotification( String number, String countryIso, int callType, ReportingLocation.Type from, ContactLookupResult.Type contactLookupResultType)145 void reportNotSpamFromAfterCallNotification( 146 String number, 147 String countryIso, 148 int callType, 149 ReportingLocation.Type from, 150 ContactLookupResult.Type contactLookupResultType); 151 152 /** 153 * Reports number as not spam. 154 * 155 * @param number The number to be reported. 156 * @param countryIso The country ISO of the number. 157 * @param callType Whether the type of call is missed, voicemail, etc. Example of this is {@link 158 * android.provider.CallLog.Calls#VOICEMAIL_TYPE}. 159 * @param from Where in the dialer this was reported from. Must be one of {@link 160 * com.android.dialer.logging.ReportingLocation}. 161 * @param contactSourceType If we have cached contact information for the phone number, this 162 * indicates its source. Must be one of {@link com.android.dialer.logging.ContactSource}. 163 */ reportNotSpamFromCallHistory( String number, String countryIso, int callType, ReportingLocation.Type from, ContactSource.Type contactSourceType)164 void reportNotSpamFromCallHistory( 165 String number, 166 String countryIso, 167 int callType, 168 ReportingLocation.Type from, 169 ContactSource.Type contactSourceType); 170 171 /** 172 * Given a number's spam status and a call type, determine if the call should be shown as spam. 173 * 174 * <p>We show a call as spam if 175 * 176 * <ul> 177 * <li>the number is marked as spam, and 178 * <li>the call is not an outgoing call. 179 * </ul> 180 * 181 * <p>This is because spammers can hide behind a legit number (e.g., a customer service number). 182 * We don't want to show a spam icon when users call it. 183 * 184 * @param isNumberSpam Whether the number is spam. 185 * @param callType One of the types in {@link android.provider.CallLog.Calls#TYPE}. 186 * @return true if the number is spam *and* the call is not an outgoing call. 187 */ shouldShowAsSpam(boolean isNumberSpam, int callType)188 static boolean shouldShowAsSpam(boolean isNumberSpam, int callType) { 189 return isNumberSpam && (callType != Calls.OUTGOING_TYPE); 190 } 191 } 192