1 /* 2 * Copyright (C) 2022 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 android.adservices.common; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.os.LimitExceededException; 22 23 import java.io.IOException; 24 import java.lang.annotation.Retention; 25 import java.lang.annotation.RetentionPolicy; 26 import java.util.concurrent.TimeoutException; 27 28 /** 29 * Utility class containing status codes and functions used by various response objects. 30 * 31 * <p>Those status codes are internal only. 32 * 33 * @hide 34 */ 35 public class AdServicesStatusUtils { 36 /** 37 * The status code has not been set. Keep unset status code the lowest value of the status 38 * codes. 39 */ 40 public static final int STATUS_UNSET = -1; 41 /** The call was successful. */ 42 public static final int STATUS_SUCCESS = 0; 43 /** 44 * An internal error occurred within the API, which the caller cannot address. 45 * 46 * <p>This error may be considered similar to {@link IllegalStateException}. 47 */ 48 public static final int STATUS_INTERNAL_ERROR = 1; 49 /** 50 * The caller supplied invalid arguments to the call. 51 * 52 * <p>This error may be considered similar to {@link IllegalArgumentException}. 53 */ 54 public static final int STATUS_INVALID_ARGUMENT = 2; 55 /** There was an unknown error. */ 56 public static final int STATUS_UNKNOWN_ERROR = 3; 57 /** 58 * There was an I/O error. 59 * 60 * <p>This error may be considered similar to {@link IOException}. 61 */ 62 public static final int STATUS_IO_ERROR = 4; 63 /** 64 * Result code for Rate Limit Reached. 65 * 66 * <p>This error may be considered similar to {@link LimitExceededException}. 67 */ 68 public static final int STATUS_RATE_LIMIT_REACHED = 5; 69 /** 70 * Killswitch was enabled. AdServices is not available. 71 * 72 * <p>This error may be considered similar to {@link IllegalStateException}. 73 */ 74 public static final int STATUS_KILLSWITCH_ENABLED = 6; 75 /** 76 * User consent was revoked. AdServices is not available. 77 * 78 * <p>This error may be considered similar to {@link IllegalStateException}. 79 */ 80 public static final int STATUS_USER_CONSENT_REVOKED = 7; 81 /** 82 * AdServices were disabled. AdServices is not available. 83 * 84 * <p>This error may be considered similar to {@link IllegalStateException}. 85 */ 86 public static final int STATUS_ADSERVICES_DISABLED = 8; 87 /** 88 * The caller is not authorized to make this call. Permission was not requested. 89 * 90 * <p>This error may be considered similar to {@link SecurityException}. 91 */ 92 public static final int STATUS_PERMISSION_NOT_REQUESTED = 9; 93 /** 94 * The caller is not authorized to make this call. Caller is not allowed (not present in the 95 * allowed list). 96 * 97 * <p>This error may be considered similar to {@link SecurityException}. 98 */ 99 public static final int STATUS_CALLER_NOT_ALLOWED = 10; 100 /** 101 * The caller is not authorized to make this call. Call was executed from background thread. 102 * 103 * <p>This error may be considered similar to {@link IllegalStateException}. 104 */ 105 public static final int STATUS_BACKGROUND_CALLER = 11; 106 /** 107 * The caller is not authorized to make this call. 108 * 109 * <p>This error may be considered similar to {@link SecurityException}. 110 */ 111 public static final int STATUS_UNAUTHORIZED = 12; 112 /** 113 * There was an internal Timeout within the API, which is non-recoverable by the caller 114 * 115 * <p>This error may be considered similar to {@link java.util.concurrent.TimeoutException} 116 */ 117 public static final int STATUS_TIMEOUT = 13; 118 /** 119 * The device is not running a version of WebView that supports JSSandbox, required for FLEDGE 120 * Ad Selection. 121 * 122 * <p>This error may be considered similar to {@link IllegalStateException}. 123 */ 124 public static final int STATUS_JS_SANDBOX_UNAVAILABLE = 14; 125 126 /** The error message to be returned along with {@link IllegalStateException}. */ 127 public static final String ILLEGAL_STATE_EXCEPTION_ERROR_MESSAGE = "Service is not available."; 128 /** The error message to be returned along with {@link LimitExceededException}. */ 129 public static final String RATE_LIMIT_REACHED_ERROR_MESSAGE = "API rate limit exceeded."; 130 /** 131 * The error message to be returned along with {@link SecurityException} when permission was not 132 * requested in the manifest. 133 */ 134 public static final String SECURITY_EXCEPTION_PERMISSION_NOT_REQUESTED_ERROR_MESSAGE = 135 "Caller is not authorized to call this API. Permission was not requested."; 136 /** 137 * The error message to be returned along with {@link SecurityException} when caller is not 138 * allowed to call AdServices (not present in the allowed list). 139 */ 140 public static final String SECURITY_EXCEPTION_CALLER_NOT_ALLOWED_ERROR_MESSAGE = 141 "Caller is not authorized to call this API. Caller is not allowed."; 142 /** 143 * The error message to be returned along with {@link SecurityException} when call was executed 144 * from the background thread. 145 */ 146 public static final String ILLEGAL_STATE_BACKGROUND_CALLER_ERROR_MESSAGE = 147 "Background thread is not allowed to call this service."; 148 149 /** 150 * The error message to be returned along with {@link SecurityException} when caller not allowed 151 * to perform this operation on behalf of the given package. 152 */ 153 public static final String SECURITY_EXCEPTION_CALLER_NOT_ALLOWED_ON_BEHALF_ERROR_MESSAGE = 154 "Caller is not allowed to perform this operation on behalf of the given package."; 155 156 /** The error message to be returned along with {@link TimeoutException}. */ 157 public static final String TIMED_OUT_ERROR_MESSAGE = "API timed out."; 158 159 /** Returns true for a successful status. */ isSuccess(@tatusCode int statusCode)160 public static boolean isSuccess(@StatusCode int statusCode) { 161 return statusCode == STATUS_SUCCESS; 162 } 163 164 /** Converts the input {@code statusCode} to an exception to be used in the callback. */ 165 @NonNull asException(@tatusCode int statusCode)166 public static Exception asException(@StatusCode int statusCode) { 167 switch (statusCode) { 168 case STATUS_INVALID_ARGUMENT: 169 return new IllegalArgumentException(); 170 case STATUS_IO_ERROR: 171 return new IOException(); 172 case STATUS_KILLSWITCH_ENABLED: // Intentional fallthrough 173 case STATUS_USER_CONSENT_REVOKED: // Intentional fallthrough 174 case STATUS_JS_SANDBOX_UNAVAILABLE: 175 return new IllegalStateException(ILLEGAL_STATE_EXCEPTION_ERROR_MESSAGE); 176 case STATUS_PERMISSION_NOT_REQUESTED: 177 return new SecurityException( 178 SECURITY_EXCEPTION_PERMISSION_NOT_REQUESTED_ERROR_MESSAGE); 179 case STATUS_CALLER_NOT_ALLOWED: 180 return new SecurityException(SECURITY_EXCEPTION_CALLER_NOT_ALLOWED_ERROR_MESSAGE); 181 case STATUS_BACKGROUND_CALLER: 182 return new IllegalStateException(ILLEGAL_STATE_BACKGROUND_CALLER_ERROR_MESSAGE); 183 case STATUS_UNAUTHORIZED: 184 return new SecurityException( 185 SECURITY_EXCEPTION_CALLER_NOT_ALLOWED_ON_BEHALF_ERROR_MESSAGE); 186 case STATUS_TIMEOUT: 187 return new TimeoutException(TIMED_OUT_ERROR_MESSAGE); 188 case STATUS_RATE_LIMIT_REACHED: 189 return new LimitExceededException(RATE_LIMIT_REACHED_ERROR_MESSAGE); 190 default: 191 return new IllegalStateException(); 192 } 193 } 194 195 /** Converts the {@link AdServicesResponse} to an exception to be used in the callback. */ 196 @NonNull asException(@onNull AdServicesResponse adServicesResponse)197 public static Exception asException(@NonNull AdServicesResponse adServicesResponse) { 198 return asException(adServicesResponse.getStatusCode()); 199 } 200 201 /** 202 * Result codes that are common across various APIs. 203 * 204 * @hide 205 */ 206 @IntDef( 207 prefix = {"STATUS_"}, 208 value = { 209 STATUS_UNSET, 210 STATUS_SUCCESS, 211 STATUS_INTERNAL_ERROR, 212 STATUS_INVALID_ARGUMENT, 213 STATUS_RATE_LIMIT_REACHED, 214 STATUS_UNKNOWN_ERROR, 215 STATUS_IO_ERROR, 216 STATUS_KILLSWITCH_ENABLED, 217 STATUS_USER_CONSENT_REVOKED, 218 STATUS_ADSERVICES_DISABLED, 219 STATUS_PERMISSION_NOT_REQUESTED, 220 STATUS_CALLER_NOT_ALLOWED, 221 STATUS_BACKGROUND_CALLER, 222 STATUS_UNAUTHORIZED, 223 STATUS_TIMEOUT, 224 STATUS_JS_SANDBOX_UNAVAILABLE 225 }) 226 @Retention(RetentionPolicy.SOURCE) 227 public @interface StatusCode {} 228 } 229