1 /* 2 * Copyright (C) 2023 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.libraries.entitlement.odsa; 18 19 import androidx.annotation.IntDef; 20 import androidx.annotation.NonNull; 21 import androidx.annotation.Nullable; 22 23 import com.android.libraries.entitlement.EsimOdsaOperation.CompanionService; 24 import com.android.libraries.entitlement.utils.HttpConstants; 25 import com.android.libraries.entitlement.utils.HttpConstants.ContentType; 26 import com.android.libraries.entitlement.utils.Ts43Constants; 27 import com.android.libraries.entitlement.utils.Ts43Constants.AppId; 28 import com.android.libraries.entitlement.utils.Ts43Constants.NotificationAction; 29 30 import com.google.auto.value.AutoValue; 31 import com.google.common.collect.ImmutableList; 32 33 import java.lang.annotation.Retention; 34 import java.lang.annotation.RetentionPolicy; 35 import java.net.URL; 36 37 /** Check eligibility operation described in GSMA Service Entitlement Configuration section 6. */ 38 public final class CheckEligibilityOperation { 39 /** ODSA app check eligibility result unknown. */ 40 public static final int ELIGIBILITY_RESULT_UNKNOWN = -1; 41 42 /** ODSA app cannot be offered and invoked by the end-user. */ 43 public static final int ELIGIBILITY_RESULT_DISABLED = 0; 44 45 /** ODSA app can be invoked by end-user or to activate a new subscription. */ 46 public static final int ELIGIBILITY_RESULT_ENABLED = 1; 47 48 /** ODSA app is not compatible with the device or server. */ 49 public static final int ELIGIBILITY_RESULT_INCOMPATIBLE = 2; 50 51 @Retention(RetentionPolicy.SOURCE) 52 @IntDef({ 53 ELIGIBILITY_RESULT_UNKNOWN, 54 ELIGIBILITY_RESULT_DISABLED, 55 ELIGIBILITY_RESULT_ENABLED, 56 ELIGIBILITY_RESULT_INCOMPATIBLE 57 }) 58 public @interface EligibilityResult { 59 } 60 61 /** 62 * HTTP request parameters specific to on device service activation (ODSA). 63 * See GSMA spec TS.43 section 6.2. 64 */ 65 @AutoValue 66 public abstract static class CheckEligibilityRequest { 67 /** 68 * Returns the application id. Can only be {@link Ts43Constants#APP_ODSA_COMPANION}, 69 * {@link Ts43Constants#APP_ODSA_PRIMARY}, or 70 * {@link Ts43Constants#APP_ODSA_SERVER_INITIATED_REQUESTS}. 71 */ 72 @AppId appId()73 public abstract String appId(); 74 75 /** 76 * Returns the unique identifier of the companion device, like IMEI. Used by HTTP parameter 77 * {@code companion_terminal_id}. 78 */ 79 @NonNull companionTerminalId()80 public abstract String companionTerminalId(); 81 82 /** 83 * Returns the OEM of the companion device. Used by HTTP parameter 84 * {@code companion_terminal_vendor}. 85 */ 86 @NonNull companionTerminalVendor()87 public abstract String companionTerminalVendor(); 88 89 /** 90 * Returns the model of the companion device. Used by HTTP parameter 91 * {@code companion_terminal_model}. 92 */ 93 @NonNull companionTerminalModel()94 public abstract String companionTerminalModel(); 95 96 /** 97 * Returns the software version of the companion device. Used by HTTP parameter 98 * {@code companion_terminal_sw_version}. 99 */ 100 @NonNull companionTerminalSoftwareVersion()101 public abstract String companionTerminalSoftwareVersion(); 102 103 /** 104 * Returns the user-friendly version of the companion device. Used by HTTP parameter 105 * {@code companion_terminal_friendly_name}. 106 */ 107 @NonNull companionTerminalFriendlyName()108 public abstract String companionTerminalFriendlyName(); 109 110 /** 111 * Returns the notification token used to register for entitlement configuration request 112 * from network. Used by HTTP parameter {@code notif_token}. 113 */ 114 @NonNull notificationToken()115 public abstract String notificationToken(); 116 117 /** 118 * Returns the action associated with the notification token. Used by HTTP parameter 119 * {@code notif_action}. 120 */ 121 @NotificationAction notificationAction()122 public abstract int notificationAction(); 123 124 /** Returns a new {@link Builder} object. */ 125 @NonNull builder()126 public static Builder builder() { 127 return new AutoValue_CheckEligibilityOperation_CheckEligibilityRequest.Builder() 128 .setAppId(Ts43Constants.APP_UNKNOWN) 129 .setCompanionTerminalId("") 130 .setCompanionTerminalVendor("") 131 .setCompanionTerminalModel("") 132 .setCompanionTerminalSoftwareVersion("") 133 .setCompanionTerminalFriendlyName("") 134 .setNotificationToken("") 135 .setNotificationAction(Ts43Constants.NOTIFICATION_ACTION_ENABLE_FCM); 136 } 137 138 /** Builder */ 139 @AutoValue.Builder 140 public abstract static class Builder { 141 /** 142 * Sets the application id. 143 * 144 * @param appId The application id. Can only be 145 * {@link Ts43Constants#APP_ODSA_COMPANION}, 146 * {@link Ts43Constants#APP_ODSA_PRIMARY}, or {@link 147 * Ts43Constants#APP_ODSA_SERVER_INITIATED_REQUESTS}. 148 * @return The builder. 149 */ 150 @NonNull setAppId(@onNull @ppId String appId)151 public abstract Builder setAppId(@NonNull @AppId String appId); 152 153 /** 154 * Sets the unique identifier of the companion device, like IMEI. Used by HTTP parameter 155 * {@code companion_terminal_id} if set. 156 * 157 * <p>Used by companion device ODSA operation. 158 * 159 * @param companionTerminalId The unique identifier of the companion device. 160 * @return The builder. 161 */ 162 @NonNull setCompanionTerminalId(@onNull String companionTerminalId)163 public abstract Builder setCompanionTerminalId(@NonNull String companionTerminalId); 164 165 /** 166 * Sets the OEM of the companion device. Used by HTTP parameter 167 * {@code companion_terminal_vendor} if set. 168 * 169 * <p>Used by companion device ODSA operation. 170 * 171 * @param companionTerminalVendor The OEM of the companion device. 172 * @return The builder. 173 */ 174 @NonNull setCompanionTerminalVendor( @onNull String companionTerminalVendor)175 public abstract Builder setCompanionTerminalVendor( 176 @NonNull String companionTerminalVendor); 177 178 /** 179 * Sets the model of the companion device. Used by HTTP parameter 180 * {@code companion_terminal_model} if set. 181 * 182 * <p>Used by companion device ODSA operation. 183 * 184 * @param companionTerminalModel The model of the companion device. 185 * @return The builder. 186 */ 187 @NonNull setCompanionTerminalModel( @onNull String companionTerminalModel)188 public abstract Builder setCompanionTerminalModel( 189 @NonNull String companionTerminalModel); 190 191 /** 192 * Sets the software version of the companion device. Used by HTTP parameter 193 * {@code companion_terminal_sw_version} if set. 194 * 195 * <p>Used by companion device ODSA operation. 196 * 197 * @param companionTerminalSoftwareVersion The software version of the companion device. 198 * @return The builder. 199 */ 200 @NonNull setCompanionTerminalSoftwareVersion( @onNull String companionTerminalSoftwareVersion)201 public abstract Builder setCompanionTerminalSoftwareVersion( 202 @NonNull String companionTerminalSoftwareVersion); 203 204 /** 205 * Sets the user-friendly version of the companion device. Used by HTTP parameter 206 * {@code companion_terminal_friendly_name} if set. 207 * 208 * <p>Used by companion device ODSA operation. 209 * 210 * @param companionTerminalFriendlyName The user-friendly version of the companion 211 * device. 212 * @return The builder. 213 */ 214 @NonNull setCompanionTerminalFriendlyName( @onNull String companionTerminalFriendlyName)215 public abstract Builder setCompanionTerminalFriendlyName( 216 @NonNull String companionTerminalFriendlyName); 217 218 /** 219 * Sets the notification token used to register for entitlement configuration request 220 * from network. Used by HTTP parameter {@code notif_token} if set. 221 * 222 * <p>Used by primary device ODSA operation. 223 * 224 * @param notificationToken The notification token used to register for entitlement 225 * configuration request from network. 226 * @return The builder. 227 */ 228 @NonNull setNotificationToken(@onNull String notificationToken)229 public abstract Builder setNotificationToken(@NonNull String notificationToken); 230 231 /** 232 * Sets the action associated with the notification token. Used by HTTP parameter 233 * {@code notif_action} if set. 234 * 235 * <p>Used by primary device ODSA operation. 236 * 237 * @param notificationAction The action associated with the notification token. 238 * @return The builder. 239 */ 240 @NonNull setNotificationAction( @otificationAction int notificationAction)241 public abstract Builder setNotificationAction( 242 @NotificationAction int notificationAction); 243 244 /** Returns the {@link CheckEligibilityRequest} object. */ 245 @NonNull build()246 public abstract CheckEligibilityRequest build(); 247 } 248 } 249 250 /** 251 * Check eligibility response described in GSMA Service Entitlement Configuration section 6.5.2. 252 */ 253 @AutoValue 254 public abstract static class CheckEligibilityResponse extends OdsaResponse { 255 /** Returns the result of check eligibility request. */ 256 @EligibilityResult appEligibility()257 public abstract int appEligibility(); 258 259 /** Indicates the applicable companion device services. */ 260 @NonNull 261 @CompanionService companionDeviceServices()262 public abstract ImmutableList<String> companionDeviceServices(); 263 264 /** 265 * The provided URL shall present a web view to user on the reason(s) why the ODSA app 266 * cannot be used/invoked. 267 */ 268 @Nullable notEnabledUrl()269 public abstract URL notEnabledUrl(); 270 271 /** 272 * User data sent to the Service Provider when requesting the {@link #notEnabledUrl()} web 273 * view. It should contain user-specific attributes to improve user experience. The format 274 * must follow the {@link #notEnabledContentsType()} parameter. For content types of 275 * {@code JSON} and {@code XML}, it is possible to provide the base64 encoding of the value 276 * by preceding it with {@code encodedValue=}. 277 */ 278 @NonNull notEnabledUserData()279 public abstract String notEnabledUserData(); 280 281 /** 282 * Specifies content and HTTP method to use when reaching out to the web server specified in 283 * {@link #notEnabledUrl()}. 284 */ 285 @ContentType notEnabledContentsType()286 public abstract int notEnabledContentsType(); 287 288 /** Returns the builder. */ builder()289 public static Builder builder() { 290 return new AutoValue_CheckEligibilityOperation_CheckEligibilityResponse.Builder() 291 .setAppEligibility(ELIGIBILITY_RESULT_UNKNOWN) 292 .setCompanionDeviceServices(ImmutableList.of()) 293 .setNotEnabledUserData("") 294 .setNotEnabledContentsType(HttpConstants.UNKNOWN); 295 } 296 297 /** The builder. */ 298 @AutoValue.Builder 299 public abstract static class Builder extends OdsaResponse.Builder { 300 /** 301 * Set the eligibility. 302 * 303 * @param eligibility The result of check eligibility request. 304 * @return The builder. 305 */ 306 @NonNull setAppEligibility(@ligibilityResult int eligibility)307 public abstract Builder setAppEligibility(@EligibilityResult int eligibility); 308 309 /** 310 * Set the companion device services. 311 * 312 * @param companionDeviceServices The applicable companion device services. 313 * @return The builder. 314 */ 315 @NonNull setCompanionDeviceServices( @onNull @ompanionService ImmutableList<String> companionDeviceServices)316 public abstract Builder setCompanionDeviceServices( 317 @NonNull @CompanionService ImmutableList<String> companionDeviceServices); 318 319 /** 320 * Set the URL presenting a web view to user on the reason(s) why the ODSA app cannot be 321 * used/invoked. 322 * 323 * @param url The provided URL shall present a web view to user on the reason(s) why the 324 * ODSA app cannot be used/invoked. 325 * @return The builder. 326 */ 327 @NonNull setNotEnabledUrl(@onNull URL url)328 public abstract Builder setNotEnabledUrl(@NonNull URL url); 329 330 /** 331 * Set the user data sent to the Service Provider when requesting the 332 * {@link #notEnabledUrl()} web view. 333 * 334 * @param notEnabledUserData User data sent to the Service Provider when requesting the 335 * {@link #notEnabledUrl()} web view. It should contain 336 * user-specific attributes to improve user experience. The 337 * format must follow the {@link #notEnabledContentsType()} 338 * parameter. For content types of {@link HttpConstants#JSON} 339 * and {@link HttpConstants#XML}, it is possible to provide 340 * the base64 encoding of the value by preceding it with 341 * {@code encodedValue=}. 342 * @return The builder. 343 */ 344 @NonNull setNotEnabledUserData(@onNull String notEnabledUserData)345 public abstract Builder setNotEnabledUserData(@NonNull String notEnabledUserData); 346 347 /** 348 * Set the content and HTTP method to use when reaching out to the web server specified 349 * in {@link #notEnabledUrl()}. 350 * 351 * @param notEnabledContentsType Specifies content and HTTP method to use when reaching 352 * out to the web server specified in 353 * {@link #notEnabledUrl()}. 354 * @return The builder. 355 */ 356 @NonNull setNotEnabledContentsType( @ontentType int notEnabledContentsType)357 public abstract Builder setNotEnabledContentsType( 358 @ContentType int notEnabledContentsType); 359 360 /** Build the {@link CheckEligibilityResponse} object. */ build()361 public abstract CheckEligibilityResponse build(); 362 } 363 } 364 CheckEligibilityOperation()365 private CheckEligibilityOperation() { 366 } 367 } 368