Carrier Configuration in Android 6.0 文档翻译

Carrier Configuration in Android 6.0（主要就是carrier app）
Introduction

□介绍

The Android 6.0 Marshmallow release introduces a capability for privileged applications to provide carrier-specific configuration to the platform. This functionality, based on the UICC carrier privilege functionality ​introduced in Android 5.1 (Lollipop MR1), will allow carrier configuration to be moved away from the static configuration overlays and give carriers and OEMs the ability to dynamically provide carrier configuration to the platform through a defined interface.
Android 6.0版本为平台提供了一种授权的应用，该应用可以为android系统提供运营商定制配置文件的能力（配置文件指各个应用res/value下的xml文件，用于记录手机一些应用的数据，比如短信大小限制，数据漫游开关状态，默认小区广播，是否允许群发彩信等等）。该功能基于5.1的UICC carrier privilege功能，该功能将允许OEM和运营商移除静态配置文件的属性值，并使其通过一个定义好的接口，有能力动态修改配置文件。

A properly signed carrier app can either be preloaded in the system image, provided through Play Auto Installs, or manually installed through avenues such as Google Play.
一个正确签名的carrier app既可以预编译到系统镜像来安装到系统，也可以通过Google Play等应用手动下载安装。

The app will be queried by the platform to provide configuration for settings including:
● Roaming/Non-roaming networks
● Visual Voicemail
● SMS/MMS network settings
该App可以提供以下设置的配置文件：
●漫游/非漫游网络
●可视语音信箱
●短信/彩信网络设置
Note :
This app must be signed with the certificate that has a matching signature to one on the SIM - see the ​How is privilege granted to a Carrier App ​section for details.
注意：此应用程序必须与具有匹配签名的证书签名。详情请看How is privilege granted to a Carrier App章节

The determination of what values to return is entirely up to the Carrier App and can be dynamic based on detailed information passed to the app via the platform.
The key benefits of this approach are:
● Dynamic configuration ​
- Support for concepts like non-MCCMNC derived configuration, for example mobile virtual network operators (MVNOs) or customer opt in to extra services
● Support for devices sold through any channel ​
- e.g. an open market phone can
be automatically configured with the right settings by downloading an app from Google Play.
● Security
- ​Privilege to provide this configuration is given only to applications signed by the carrier
● Defined API ​
- Previously this configuration was stored mostly in internal XML overlays within the framework and not through a public API. The carrier config API in the M release is public and well defined.
最终的返回值完全取决于Carrier App，并且App还可以是动态的值，基于传给app的详细信息
该方式的好处有：

● 动态配置
- 支持这样的想法比如无法从MCCMNC中获取的配置, 比如说手机虚拟运营商(MVNOs) 或者客户的其他服务
● 支持通过任何渠道销售的设备 ​
-比如，一个开放市场的手机通过从Google Play下载一个App就可以自动正确配置
● 安全
- ​提供此配置的权限仅用于由carrier签名的应用程序。
●定义的API ​
-之前这个配置大多数存储在framework的XML中，没有通过一个公共的API。在Android M版本中carrier配置API是public的而且完好的定义了。

How it works
Loading the config
The carrier configuration supplied by this feature is a set of key-value pairs that change various telephony-related behaviors in the platform.
The set of values for a particular device is determined by querying the following components in order:
1. The Carrier App (although this is technically optional, it is the recommended location for additional configuration beyond what exists in the Android Open
Source Project - AOSP)
2. The Platform Config App bundled with the system image
3. Default values, hardcoded into the framework (equivalent to the behavior prior to M)
Important ​:
If a value for a particular key is returned at any stage, the first value found takes precedence over the further stages.

□它如何工作

加载配置文件
该功能提供的carrier配置是一系列键值对的集合，它们改变了平台中与电话相关的各种行为
这一系列特殊设备的值最终通过按顺序查询以下组件决定：
1.从carrier App读取（虽然这个app是可选的，但是相对从Android源码AOSP中读取，我们推荐从carrier app读取附加配置）
2.从与平台镜像绑定的配置App读取
3.默认值，android framework中的硬编码（跟M之前的行为一样）
重要：如果在任意一个阶段读取到一个特殊的值，它相对与后面读取到相同key的值是优先的（使用最先读到的值）

The Platform Config App
平台的配置App
A generic Platform Config App is bundled with the system image that can supply values for any variables the regular Carrier App does not. The platform config app can be found (in M) in: ​
packages/apps/CarrierConfig
一个普通的平台配置App会和系统镜像捆绑在一起，该app可以支持任何变量的值而Carrier App无法做到。平台配置app是可以在下面的位置找到的
packages/apps/CarrierConfig

This app’s purpose is to provide some per-network configuration when a Carrier App is not installed, and carriers/OEMs should make only minimal changes to it in their own images. Instead carriers should provide the separate Carrier App for carrier customization, allowing updates to be distributed via avenues such as Google Play.
该app的目的是当Carrier App没有安装时提供一些网络配置，OEM公司/运营商需要在自己的镜像中对其进行最小的更改。相反的运营商需要为运营商客制化提供独立的Carrier App，这样做才能允许通过google play等渠道发布更新

How privilege is granted to a Carrier App
The Carrier App in question must be signed with the same certificate found on the SIM card, as documented in the ​UICC carrier privileges for partners document.
Carrier App如何授权
讨论中的Carrier App必须和SIM卡中的签名一致，正如记录在“UICC carrier privileges for partners”文档中一样

What information is passed to the Carrier App
哪些信息传递给Carrier应用程序
The Carrier App is supplied with the following values, enabling it to make a dynamic decision as to what values to return:
● MCC
● MNC
● SPN
● IMSI
● GID1
● GID2
Carrier App提供了以下值，使其能够动态地决定返回什么值：
● MCC
● MNC
● SPN
● IMSI
● GID1
● GID2

When loading the carrier config occurs
The building of the list of key value pairs occurs:
● When the SIM is loaded (boot, or SIM hot swap)
● When the Carrier app manually triggers a reload
● When the Carrier app gets updated
See ​the Javadoc for android.service.carrier.CarrierService#onLoadConfig() ​for more details.

何时加载运营商配置
一系列键值对的匹配发生在：
● 加载SIM卡（开机，或者换卡）
● Carrier app被手动触发重新加载
●Carrier app更新了
详情请查看“android.service.carrier.CarrierService#onLoadConfig()”java文件中的对应函数

（在源码中摘抄CarrierService注释如下：

 /**
     * Override this method to set carrier configuration.
     * 

     * This method will be called by telephony services to get carrier-specific configuration
     * values. The returned config will be saved by the system until,
     * 

     * 
The carrier app package is updated, or
     * 
The carrier app requests a reload with
     * {@link android.telephony.CarrierConfigManager#notifyConfigChangedForSubId
     * notifyConfigChangedForSubId}.
     * 
     * This method can be called after a SIM card loads, which may be before or after boot.
     * 

     * 

     * This method should not block for a long time. If expensive operations (e.g. network access)
     * are required, this method can schedule the work and return null. Then, use
     * {@link android.telephony.CarrierConfigManager#notifyConfigChangedForSubId
     * notifyConfigChangedForSubId} to trigger a reload when the config is ready.
     * 
     * 

     * Implementations should use the keys defined in {@link android.telephony.CarrierConfigManager
     * CarrierConfigManager}. Any configuration values not set in the returned {@link
     * PersistableBundle} may be overridden by the system's default configuration service.
     * 
     *
     * @param id contains details about the current carrier that can be used do decide what
     *            configuration values to return.
     * @return a {@link PersistableBundle} object containing the configuration or null if default
     *         values should be used.
     */
    public abstract PersistableBundle onLoadConfig(CarrierIdentifier id);

）

Note ​:
The platform caches carrier configuration bundles and loads from the cache for SIM state changes. This is to speed up boot and SIM hot swap. It is assumed that without a package update or an explicit notifyCarrierNetworkChange, the config bundle has not been modified.
注意：平台会缓存运营商配置数据并从缓存中加载SIM卡状态的变化。这是为了加快开机和支持SIM卡的热插拔。假定没有包更新或一个明确的notifycarriernetworkchange，配置就不会被修改。

（摘录notifyCarrierNetworkChange的注释如下：）

/**
     * Informs the system of an intentional upcoming carrier network change by
     * a carrier app. This call is optional and is only used to allow the
     * system to provide alternative UI while telephony is performing an action
     * that may result in intentional, temporary network lack of connectivity.
     * 

     * Based on the active parameter passed in, this method will either show or
     * hide the alternative UI. There is no timeout associated with showing
     * this UX, so a carrier app must be sure to call with active set to false
     * sometime after calling with it set to true.
     * 

     * Requires Permission:
     *   {@link android.Manifest.permission#MODIFY_PHONE_STATE MODIFY_PHONE_STATE}
     * Or the calling app has carrier privileges.
     *   @see {@link android.telephony.TelephonyManager#hasCarrierPrivileges}
     *
     * @param active Whether the carrier network change is or shortly will be
     *               active. Set this value to true to begin showing
     *               alternative UI and false to stop.
     */
    public final void notifyCarrierNetworkChange(boolean active) {
        try {
            if (sRegistry != null) sRegistry.notifyCarrierNetworkChange(active);
        } catch (RemoteException | NullPointerException ex) {}
    }

Using the config
Once the configuration has been built, the values contained within it are used to set various values of system configuration, including:
● Internal framework telephony settings
● SDK-returned configuration values, e.g. in SmsManager
● App settings like VVM connection values in the Dialer

使用配置
一旦配置完成后，其中包含的值用于设置各种系统配置值，包括：
●框架内部电话设置
●SDK返回的配置值，例如SmsManager
●应用程序设置如在VVM拨号连接的值时

Configuration keys
The list of keys is defined as part of the public SDK in android.telephony.CarrierConfigManager and cannot change within the same API level. The Javadoc for the keys in M is appended to the end of this document, but the canonical source will be the SDK documentation on developer.android.com.

配置Keys
keys的列表在公共SDK中的android.telephony.CarrierConfigManage定义了，且在同一API级别中keys列表无法更改。M版本中Keys的java文件附在了文档末尾，但是更规范的还是developer.android.com.的SDK文档

□How to build your application

如何构建你的应用程序
Your application must target the Android 6.0 API level (23).
你的应用程目标版本必须是Android6.0（API level 23）
Declare a class that overrides android.service.carrier.CarrierService
声明一个类重写android.service.carrier.CarrierService

1. Override onLoadConfig to return the values you wish to supply based on the service.carrier.CarrierIdentifier object passed.
2. Add logic to call ​notifyCarrierNetworkChange in scenarios where carrier configuration may change over time (e.g. when the user adds extra services to their account)
   An example is below:

1.重写onLoadConfig方法来返回你希望支持的基于service.carrier.CarrierIdentifier对象传输的值
2.在运营商配置会变化的环节增加调用notifyCarrierNetworkChange的逻辑（比如当用户增加额外的服务到账户时）
下面是一个范例：

public class SampleCarrierConfigService extends CarrierService {

    private static final String TAG = "SampleCarrierConfigService";

    public SampleCarrierConfigService() {
        Log.d(TAG, "Service created");
    }

    @Override
    public PersistableBundle onLoadConfig(CarrierIdentifier id) {
        Log.d(TAG, "Config being fetched");
        PersistableBundle config = new PersistableBundle();
        config.putBoolean(CarrierConfigManager.KEY_CARRIER_VOLTE_AVAILABLE_BOOL, true);
        config.putBoolean(CarrierConfigManager.KEY_CARRIER_VOLTE_TTY_SUPPORTED_BOOL, false);
        config.putInt(CarrierConfigManager.KEY_VOLTE_REPLACEMENT_RAT_INT, 6);
        // Check CarrierIdentifier and add more config if needed... 
        return config;
    }
} 

Please see the associated javadoc of ​android.service.carrier.CarrierService for more details
更多细节请看相关的java文件android.service.carrier.CarrierService

Name the class in your manifest
在清单文件命名你的类

        <service
            android:name=".SampleCarrierConfigService"
            android:label="@string/service_name"
            android:permission="android.permission.BIND_CARRIER_SERVICES">
            <intent-filter>
                <action android:name="android.service.carrier.ConfigService" />
            intent-filter>
        service>

Sign app with same certificate on SIM
See the ​UICC carrier privileges for partners document for the requirements.
给app赋予sim卡上相同的权限
查看​UICC carrier privileges for partners以获取更多信息

Testing your application

□测试你的程序

Once you have built your configuration application, you can test your code with:
● A SIM containing a valid certificate signature
● A device running the M release, for example a Nexus device
一旦你编译你配置应用程序，你可以用以下方法测试：
● 一个包含有效证书签名的sim卡
● 一台运行着M版本的android机器, 比如一台Nexus设备

Appendix - CarrierConfigManager key fields

□附录-CarrierConfigManager的键值

CarrierConfigManager defines the set of keys that the platform will examine and use to configure its behavior. The following table is an extract of the Javadoc for the
CarrierConfigManager class.
Please note, the Javadoc for M does not explain the MMS-related keys currently. The keys map directly to the existing parameters defined by SmsManager. The public SDK docs will be updated to reflect these additions.
CarrierConfigManager定义了一系列键，android系统会检查并用这些键来控制android设备的行为。以下的表格是CarrierConfigManager java类的一个提取
请注意，M版本的java文件目前没有解释MMS相关的键。键值对直接映射到SmsManager定义的一些已存在的参数。public SDK文档将更新，以反映这些补充。

ACTION_CARRIER_CONFIG_CHANGED
This intent is broadcast by the system when carrier config changes.

KEY_ADDITIONAL_CALL_SETTING_BOOL
Does not display additional call setting for IMS phone based on GSM Phone.

KEY_ALLOW_EMERGENCY_NUMBERS_IN_CALL_LOG_BOOL 
Determines if the current device should allow emergency numbers to be logged in the Call Log.

KEY_ALLOW_LOCAL_DTMF_TONES_BOOL
Determine whether we want to play local DTMF tones in a call, or just let the radio/BP handle playing of the tones.

KEY_APN_EXPAND_BOOL
Control whether users can edit APNs in Settings.

KEY_AUTO_RETRY_ENABLED_BOOL Flag 
indicating if auto retry is enabled.

KEY_CARRIER_SETTINGS_ENABLE_BOOL 
Display carrier settings menu if true.

KEY_CARRIER_VOLTE_AVAILABLE_BOOL
Flag specifying whether VoLTE should be available for carrier, independent of carrier provisioning.

KEY_CARRIER_VOLTE_PROVISIONED_BOOL 
Flag specifying whether VoLTE availability is based on provisioning.

KEY_CARRIER_VOLTE_TTY_SUPPORTED_BOOL 
Flag specifying whether VoLTE TTY is supported.

KEY_CARRIER_WFC_IMS_AVAILABLE_BOOL 
Flag specifying whether WFC over IMS should be available for carrier:independent of carrier provisioning.

KEY_CDMA_NONROAMING_NETWORKS_STRING_ARRAY
Override the platform's notion of a network operator being considered non roaming.

KEY_CDMA_ROAMING_NETWORKS_STRING_ARRAY 
Override the platform's notion of a network operator being considered roaming.

KEY_DEFAULT_SIM_CALL_MANAGER_STRI 
The default sim call manager to use NG when the default dialer doesn't implement one.

KEY_DISABLE_CDMA_ACTIVATION_CODE_BOOL 
Disables dialing "*228" (OTASP provisioning) on CDMA carriers where it is not supported or is potentially harmful by locking the SIM to 3G.

KEY_DTMF_TYPE_ENABLED_BOOL
Flag indicating if dtmf tone type is enabled.

KEY_ENABLE_DIALER_KEY_VIBRATION_BOOL 
If true, enable vibration (haptic feedback) for key presses in the EmergencyDialer activity.

KEY_GSM_NONROAMING_NETWORKS_STRING_ARRAY 
Override the platform's notion of a network operator being considered not roaming.

KEY_GSM_ROAMING_NETWORKS_STRING_ARRAY 
Override the platform's notion of a network operator being considered roaming.

KEY_HAS_IN_CALL_NOISE_SUPPRESSION_BOOL 
Determines if device implements a noise suppression device for in call audio.

KEY_HIDE_CARRIER_NETWORK_SETTINGS_BOOL 
Control whether users can reach the carrier portions of Cellular Network Settings.

KEY_HIDE_SIM_LOCK_SETTINGS_BOOL
Control whether users can reach the SIM lock settings.

KEY_IGNORE_SIM_NETWORK_LOCKED_EVENTS_BOOL 
Flag indicating whether the Phone app should ignore EVENT_SIM_NETWORK_LOCKED events from the Sim.

如前文所述MMS相关的Key没有解释
KEY_MMS_ALIAS_ENABLED_BOOL
KEY_MMS_ALIAS_MAX_CHARS_INT
KEY_MMS_ALIAS_MIN_CHARS_INT
KEY_MMS_ALLOW_ATTACH_AUDIO_BOOL
KEY_MMS_APPEND_TRANSACTION_ID_BOOL
KEY_MMS_EMAIL_GATEWAY_NUMBER_STRING
KEY_MMS_GROUP_MMS_ENABLED_BOOL
KEY_MMS_HTTP_PARAMS_STRING
KEY_MMS_HTTP_SOCKET_TIMEOUT_INT
KEY_MMS_MAX_IMAGE_HEIGHT_INT
KEY_MMS_MAX_IMAGE_WIDTH_INT
KEY_MMS_MAX_MESSAGE_SIZE_INT
KEY_MMS_MESSAGE_TEXT_MAX_SIZE_INT
KEY_MMS_MMS_DELIVERY_REPORT_ENABLED_BOOL
KEY_MMS_MMS_ENABLED_BOOL
KEY_MMS_MMS_READ_REPORT_ENABLED_BOOL
KEY_MMS_MULTIPART_SMS_ENABLED_BOOL
KEY_MMS_NAI_SUFFIX_STRING
KEY_MMS_NOTIFY_WAP_MMSC_ENABLED_BOOL
KEY_MMS_RECIPIENT_LIMIT_INT
KEY_MMS_SEND_MULTIPART_SMS_AS_SEPARATE_MESSAGES_BOOL
KEY_MMS_SHOW_CELL_BROADCAST_APP_LINKS_BOOL
KEY_MMS_SMS_DELIVERY_REPORT_ENABLED_BOOL
KEY_MMS_SMS_TO_MMS_TEXT_LENGTH_THRESHOLD_INT
KEY_MMS_SMS_TO_MMS_TEXT_THRESHOLD_INT
KEY_MMS_SUBJECT_MAX_LENGTH_INT
KEY_MMS_SUPPORT_HTTP_CHARSET_HEADER_BOOL
KEY_MMS_SUPPORT_MMS_CONTENT_DISPOSITION_BOOL
KEY_MMS_UA_PROF_TAG_NAME_STRING
KEY_MMS_UA_PROF_URL_STRING
KEY_MMS_USER_AGENT_STRING


KEY_OPERATOR_SELECTION_EXPAND_BOOL  
Control whether users can choose anetwork operator.

KEY_PREFER_2G_BOOL 
Used in Cellular Network Settings for preferred network type.

KEY_SHOW_APN_SETTING_CDMA_BOOL
Show APN Settings for some CDMA carriers.

KEY_SHOW_CDMA_CHOICES_BOOL
Show cdma network mode choices 1x,3G, global etc.

KEY_SHOW_ONSCREEN_DIAL_BUTTON_BOOL 
If true, show an onscreen "Dial" button in the dialer.

KEY_SIM_NETWORK_UNLOCK_ALLOW_DISMISS_BOOL 
Flag indicating whether the Phone app should provide a "Dismiss" button on the SIM network unlock screen.

KEY_SUPPORT_PAUSE_IMS_VIDEO_CALLS_BOOL 
For IMS video over LTE calls, determines whether video pause signalling is supported.

KEY_SUPPORT_SWAP_AFTER_MERGE_BOOL 
After a CDMA conference call is merged,the swap button should be displayed.

KEY_USE_HFA_FOR_PROVISIONING_BOOL 
CDMA activation goes through HFA.

KEY_USE_OTASP_FOR_PROVISIONING_BOOL 
CDMA activation goes through OTASP.

KEY_VOICEMAIL_NOTIFICATION_PERSISTENT_BOOL 
Determine whether the voicemail notification is persistent in the notification bar.

KEY_VOICE_PRIVACY_DISABLE_UI_BOOL
If true, removes the Voice Privacy option from Call Settings.

KEY_VOLTE_REPLACEMENT_RAT_INT
If Voice Radio Technology is RIL_RADIO_TECHNOLOGY_LTE:14 or RIL_RADIO_TECHNOLOGY_UNKNOWN:0, this is the value that should be used instead.

KEY_WORLD_PHONE_BOOL
Flag indicating if the phone is a world phone.