CarrierService.java revision 2b5348b41329b42f5b0929455a9b616a5e1f685e
1/* 2 * Copyright (C) 2015 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 15package android.service.carrier; 16 17import android.app.Service; 18import android.content.Intent; 19import android.os.IBinder; 20import android.os.PersistableBundle; 21 22/** 23 * A service that exposes carrier-specific functionality to the system. 24 * <p> 25 * To extend this class, you must declare the service in your manifest file to require the 26 * {@link android.Manifest.permission#BIND_CARRIER_SERVICES} permission and include an intent 27 * filter with the {@link #CONFIG_SERVICE_INTERFACE} action if the service exposes carrier config 28 * and the {@link #BIND_SERVICE_INTERFACE} action if the service should have a long-lived binding. 29 * For example: 30 * </p> 31 * 32 * <pre>{@code 33 * <service android:name=".MyCarrierService" 34 * android:label="@string/service_name" 35 * android:permission="android.permission.BIND_CARRIER_SERVICES"> 36 * <intent-filter> 37 * <action android:name="android.service.carrier.ConfigService" /> 38 * <action android:name="android.service.carrier.BindService" /> 39 * </intent-filter> 40 * </service> 41 * }</pre> 42 */ 43public abstract class CarrierService extends Service { 44 45 public static final String CONFIG_SERVICE_INTERFACE = "android.service.carrier.ConfigService"; 46 public static final String BIND_SERVICE_INTERFACE = "android.service.carrier.BindService"; 47 48 private final ICarrierService.Stub mStubWrapper; 49 50 public CarrierService() { 51 mStubWrapper = new ICarrierServiceWrapper(); 52 } 53 54 /** 55 * Override this method to set carrier configuration. 56 * <p> 57 * This method will be called by telephony services to get carrier-specific configuration 58 * values. The returned config will be saved by the system until, 59 * <ol> 60 * <li>The carrier app package is updated, or</li> 61 * <li>The carrier app requests a reload with 62 * {@link android.telephony.CarrierConfigManager#reloadCarrierConfigForSubId 63 * reloadCarrierConfigForSubId}.</li> 64 * </ol> 65 * This method can be called after a SIM card loads, which may be before or after boot. 66 * </p> 67 * <p> 68 * This method should not block for a long time. If expensive operations (e.g. network access) 69 * are required, this method can schedule the work and return null. Then, use 70 * {@link android.telephony.CarrierConfigManager#reloadCarrierConfigForSubId 71 * reloadCarrierConfigForSubId} to trigger a reload when the config is ready. 72 * </p> 73 * <p> 74 * Implementations should use the keys defined in {@link android.telephony.CarrierConfigManager 75 * CarrierConfigManager}. Any configuration values not set in the returned {@link 76 * PersistableBundle} may be overridden by the system's default configuration service. 77 * </p> 78 * 79 * @param id contains details about the current carrier that can be used do decide what 80 * configuration values to return. 81 * @return a {@link PersistableBundle} object containing the configuration or null if default 82 * values should be used. 83 */ 84 public abstract PersistableBundle onLoadConfig(CarrierIdentifier id); 85 86 /** @hide */ 87 @Override 88 public final IBinder onBind(Intent intent) { 89 switch (intent.getAction()) { 90 case CONFIG_SERVICE_INTERFACE: 91 case BIND_SERVICE_INTERFACE: 92 return mStubWrapper; 93 default: 94 return null; 95 } 96 } 97 98 /** 99 * A wrapper around ICarrierService that forwards calls to implementations of 100 * {@link CarrierService}. 101 * 102 * @hide 103 */ 104 private class ICarrierServiceWrapper extends ICarrierService.Stub { 105 106 @Override 107 public PersistableBundle getCarrierConfig(CarrierIdentifier id) { 108 return CarrierService.this.onLoadConfig(id); 109 } 110 } 111} 112