1 page.title=Carrier Configuration 2 @jd:body 3 4 <!-- 5 Copyright 2015 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 20 <div id="qv-wrapper"> 21 <div id="qv"> 22 <h2>In this document</h2> 23 <ol id="auto-toc"> 24 </ol> 25 </div> 26 </div> 27 28 <p>The Android 6.0 Marshmallow release introduces a capability for privileged 29 applications to provide carrier-specific configuration to the platform. This 30 functionality, based on the <a href="uicc.html">UICC carrier privilege 31 functionality</a> introduced in Android 5.1 (Lollipop MR1), will allow carrier 32 configuration to be moved away from the static configuration overlays and give 33 carriers and OEMs the ability to dynamically provide carrier configuration to 34 the platform through a defined interface.</p> 35 36 <p>A properly signed carrier app can either be preloaded in the system image, 37 installed automatically, or manually installed through an app store. The app 38 will be queried by the platform to provide configuration for settings 39 including:</p> 40 41 <ul> 42 <li>Roaming/Non-roaming networks 43 <li>Visual Voicemail 44 <li>SMS/MMS network settings 45 <li>VoLTE/IMS configurations 46 </ul> 47 48 <p class="note"><strong>Note</strong>: This app must be signed with the 49 certificate that has a matching signature to one on the SIM. See the <a 50 href="#how_privilege_is_granted_to_a_carrier_app">How is privilege granted to a 51 Carrier App</a> section for details.</p> 52 53 <p>The determination of what values to return is entirely up to the Carrier App 54 and can be dynamic based on detailed information passed to the app via the 55 platform. </p> 56 57 <p>The key benefits of this approach are:</p> 58 59 <ul> 60 <li><strong>Dynamic configuration</strong> - Support for concepts like 61 non-MCCMNC derived configuration, for example 62 mobile virtual network operators (MVNOs) or customer opt in to extra services 63 <li><strong>Support for devices sold through any channel</strong> - e.g. an 64 open market phone can be automatically configured with the right 65 settings by downloading an app from an app store. 66 <li><strong>Security</strong> - Privilege to provide this configuration is 67 given only to applications signed by the carrier 68 <li><strong>Defined API</strong> - Previously this configuration was stored 69 mostly in internal XML overlays within the framework and not through a public 70 API. The carrier config API in Android 6.0 is public and well defined. 71 </ul> 72 73 <h2 id=how_it_works>How it works</h2> 74 75 <h3 id=loading_the_config>Loading the config</h3> 76 77 <p>The carrier configuration supplied by this feature is a set of key-value pairs 78 that change various telephony-related behaviors in the platform.</p> 79 80 <p>The set of values for a particular device is determined by querying the 81 following components in order:</p> 82 83 <ol> 84 <li>The Carrier App (although this is technically optional, it is the recommended 85 location for additional configuration beyond what exists in the Android Open 86 Source Project - AOSP) 87 <li>The Platform Config App bundled with the system image 88 <li>Default values, hardcoded into the framework (equivalent to the behavior prior 89 to M) 90 </ol> 91 92 <p class="caution"><strong>Important</strong>: If a value for a particular key 93 is returned at any stage, the first value found takes precedence over the 94 further stages.</p> 95 96 <h4 id=the_platform_config_app>The Platform Config App</h4> 97 98 <p>A generic Platform Config App is bundled with the system image that can supply 99 values for any variables the regular Carrier App does not. The platform config 100 app can be found (in M) in: <code>packages/apps/CarrierConfig</code></p> 101 102 <p>This apps purpose is to provide some per-network configuration when a Carrier 103 App is not installed, and carriers/OEMs should make only minimal changes to it 104 in their own images. Instead carriers should provide the separate Carrier App 105 for carrier customization, allowing updates to be distributed via avenues such 106 as app stores.</p> 107 108 <h4 id=how_privilege_is_granted_to_a_carrier_app>How privilege is granted to a Carrier App</h4> 109 110 <p>The Carrier App in question must be signed with the same certificate found on 111 the SIM card, as documented in <a href="uicc.html">UICC Carrier Privileges</a>.</p> 112 113 <h4 id=what_information_is_passed_to_the_carrier_app>What information is passed to the Carrier App</h4> 114 115 <p>The Carrier App is supplied with the following values, enabling it to make a 116 dynamic decision as to what values to return:</p> 117 118 <ul> 119 <li>MCC 120 <li>MNC 121 <li>SPN 122 <li>IMSI 123 <li>GID1 124 <li>GID2 125 </ul> 126 127 <h4 id=when_loading_the_carrier_config_occurs>When loading the carrier config occurs</h4> 128 129 <p>The building of the list of key value pairs occurs:</p> 130 131 <ul> 132 <li>When the SIM is loaded (boot, or SIM hot swap) 133 <li>When the Carrier app manually triggers a reload 134 <li>When the Carrier app gets updated 135 </ul> 136 137 <p>See the <a 138 href="http://developer.android.com/reference/android/service/carrier/CarrierService.html#onLoadConfig(android.service.carrier.CarrierIdentifier)">android.service.carrier.CarrierService#onLoadConfig()</a> 139 reference for more details.</p> 140 141 <p class="note"><strong>Note</strong>: The platform caches carrier 142 configuration bundles and loads from the cache for SIM state changes. This is 143 to speed up boot and SIM hot swap. It is assumed that without a package update 144 or an explicit <code>notifyConfigChangedForSubId</code>, the config bundle has 145 not been modified.</p> 146 147 <h3 id=using_the_config>Using the config</h3> 148 149 <p>Once the configuration has been built, the values contained within it are used 150 to set various values of system configuration, including:</p> 151 152 <ul> 153 <li>Internal framework telephony settings 154 <li>SDK-returned configuration values, e.g. in SmsManager 155 <li>App settings like VVM connection values in the Dialer 156 </ul> 157 158 <h3 id=configuration_keys>Configuration keys</h3> 159 160 <p>The list of keys is defined as part of the public SDK in <code><a 161 href="http://developer.android.com/reference/android/telephony/CarrierConfigManager.html">android.telephony.CarrierConfigManager</a></code> 162 and cannot change within the same API level. See the table below for a summary of keys.</p> 163 164 <h2 id=how_to_build_your_application>How to build your application</h2> 165 166 <h3 id=create_your_application>Create your application</h3> 167 168 <p>Your application must target the Android 6.0 API level (23).</p> 169 170 <h3 id=declare_a_class_that_overrides_android_service_carrier_carrierservice>Declare a class that overrides android.service.carrier.CarrierService</h3> 171 172 <ol> 173 <li>Override <code>onLoadConfig</code> to return the values you wish to 174 supply based on the <code>service.carrier.CarrierIdentifier</code> object 175 passed. 176 <li>Add logic to call <code>notifyConfigChangedForSubId</code> in scenarios 177 where carrier configuration may change over time (e.g. when the 178 user adds extra services to their account) 179 </ol> 180 181 <p>An example is below:</p> 182 183 <pre> 184 public class SampleCarrierConfigService extends CarrierService { 185 186 private static final String TAG = "SampleCarrierConfigService"; 187 188 public SampleCarrierConfigService() { 189 Log.d(TAG, "Service created"); 190 } 191 192 @Override 193 public PersistableBundle onLoadConfig(CarrierIdentifier id) { 194 Log.d(TAG, "Config being fetched"); 195 PersistableBundle config = new PersistableBundle(); 196 config.putBoolean( 197 CarrierConfigManager.KEY_CARRIER_VOLTE_AVAILABLE_BOOL, true); 198 config.putBoolean( 199 CarrierConfigManager.KEY_CARRIER_VOLTE_TTY_SUPPORTED_BOOL, false); 200 config.putInt(CarrierConfigManager.KEY_VOLTE_REPLACEMENT_RAT_INT, 6); 201 // Check CarrierIdentifier and add more config if needed 202 return config; 203 } 204 } 205 </pre> 206 207 208 <p>Please see the <a 209 href="https://developer.android.com/reference/android/service/carrier/CarrierService.html">android.service.carrier.CarrierService</a> reference on developer.android.com for more details.</p> 210 211 <h3 id=name_the_class_in_your_manifest>Name the class in your manifest</h3> 212 213 <p>An example is below:</p> 214 215 <pre> 216 <service android:name=".SampleCarrierConfigService" 217 android:label="@string/service_name" 218 android:permission="android.permission.BIND_CARRIER_SERVICES"> 219 <intent-filter> 220 <action android:name="android.service.carrier.ConfigService"/></intent-filter> 221 </service> 222 </pre> 223 224 <h3 id=sign_app_with_same_certificate_on_sim>Sign app with same certificate on SIM</h3> 225 226 <p>See <a href="uicc.html">UICC Carrier Privileges</a> for the requirements.</p> 227 228 <h2 id=testing_your_application>Testing your application</h2> 229 230 <p>Once you have built your configuration application, you can test your code 231 with:</p> 232 233 <ul> 234 <li>A SIM containing a valid certificate signature 235 <li>A device running Android 6.0 and later, for example a Nexus device 236 </ul> 237
