/*布局文件<RadioGroup><RadioButton/><RadioButton/></RadioGroup><RadioGroup></RadioGroup>
*/
/* java 类*/
RadioGroup rg....;RadioButton rb....;CheckBox cb...;
rg.setOnCheckedChangeListener(new RadioGroup.onCheckedChangeListener(){
public void onCheckedChanged(RadioGroup rg,int checkedId){
if(rb.getId()==checkedId){
Toast.makeText(RadioTest.this,"famale",Toast.LENGTH_SHORT).show();// 桌面提示信息
}
}
})
cb.setOnCheckedChangeListener(new CompoundButton.OnCheckedChangeListener(){
public void onCheckedChanged(CompoundButton buttonView,boolean isChecked){
if(isChecked){
// ......
}
}
}
【翻译】(42)数据备份
see
http://developer.android.com/guide/topics/data/backup.html
原文见
http://developer.android.com/guide/topics/data/backup.html
-------------------------------
Data Backup
数据备份
-------------------------------
Quickview
快速概览
* Back up the user's data to the cloud in case the user loses it
* 备份用户数据到云（注：这里的云是指云存储，即数据保存到第三方代理的多台虚拟服务器中，这里可能特指Google Cloud Storage），以防用户丢失它
* If the user upgrades to a new Android-powered device, your app can restore the user's data onto the new device
* 如果用户更新到新的基于Android的设备，你的应用可以还原用户数据到新的设备上
* Easily back up SharedPreferences and private files with BackupAgentHelper
* 用BackupAgentHelper简单地备份SharedPreferences和私有文件
* Requires API Level 8
* 需要API级别8
In this document
本文目录
* The Basics 基础
* Declaring the Backup Agent in Your Manifest 在你的清单中声明备份代理
* Registering for Android Backup Service 注册Android备份服务
* Extending BackupAgent 扩展BackupAgent
* Required Methods 必需的方法
* Performing backup 执行备份
* Performing restore 执行还原
* Extending BackupAgentHelper 扩展BackupAgentHelper
* Backing up SharedPreferences 备份SharedPreferences
* Backing up Private Files 备份私有文件
* Checking the Restore Data Version 检查还原数据版本
* Requesting Backup 请求备份
* Requesting Restore 请求还原
* Testing Your Backup Agent 测试你的备份代理
Key classes
关键类
BackupManager
BackupAgent
BackupAgentHelper
See also
另见
bmgr tool bmgr工具
-------------------------------
Android's backup service allows you to copy your persistent application data to remote "cloud" storage, in order to provide a restore point for the application data and settings. If a user performs a factory reset or converts to a new Android-powered device, the system automatically restores your backup data when the application is re-installed. This way, your users don't need to reproduce their previous data or application settings. This process is completely transparent to the user and does not affect the functionality or user experience in your application.
Android的备份服务允许你复制你的持久应用程序数据到远程的“云”存储，以为应用程序数据和设置提供一个还原点。如果一个用户执行一次出厂重置或转换到一台新的基于Android的设备，那么当应用程序被重新安装时系统自动地还原你的备份数据。这样，你的用户不需要再生成他们之前的数据或应用程序设置。这个处理对于用户来说是完全透明的，并且不影响你的应用程序中的功能或用户体验。
During a backup operation (which your application can request), Android's Backup Manager (BackupManager) queries your application for backup data, then hands it to a backup transport, which then delivers the data to the cloud storage. During a restore operation, the Backup Manager retrieves the backup data from the backup transport and returns it to your application so your application can restore the data to the device. It's possible for your application to request a restore, but that shouldn't be necessary—Android automatically performs a restore operation when your application is installed and there exists backup data associated with the user. The primary scenario in which backup data is restored is when a user resets their device or upgrades to a new device and their previously installed applications are re-installed.
在一次备份操作期间（你的应用程序可以请求它），Android的备份管理器（BackupManager）查询你的应用程序以获得备份数据，然后把它传给一次备份传输，再然后它可以传递数据给云存储。在一次还原操作期间，备份管理器从备份传输中取出备份数据并返回它到你的应用程序，使你的应用程序可以还原数据到设备。你的应用程序可以请求一次还原，但不是必需的——当应用程序被安装而且存在关联到用户的备份数据时，Android自动地执行一次还原操作。备份数据被还原的主要场景是在一个用户重置他们的设备或更新到一台新的设备而他们之前安装的应用程序被重新安装的时候。
-------------------------------
Note: The backup service is not designed for synchronizing application data with other clients or saving data that you'd like to access during the normal application lifecycle. You cannot read or write backup data on demand and cannot access it in any way other than through the APIs provided by the Backup Manager.
注意：备份服务不是设计成和其它客户端同步应用程序的数据或保存你希望在正常应用程序生命周期期间访问的数据。你无法读或写需要的备份数据，并且无法用不同于备份管理器提供的API的任意方式来访问它。
-------------------------------
The backup transport is the client-side component of Android's backup framework, which is customizable by the device manufacturer and service provider. The backup transport may differ from device to device and which backup transport is available on any given device is transparent to your application. The Backup Manager APIs isolate your application from the actual backup transport available on a given device—your application communicates with the Backup Manager through a fixed set of APIs, regardless of the underlying transport.
备份传输是Android的备份框架的客户端组件，它可以被设备生产商和服务提供者定制。备份传输可能因设备而不同，并且哪个备份传输在任意给定的设备可用对于你的应用程序是透明的。备份管理器API隔离你的应用程序和所给设备上可用的实际备份传输——你的应用程序和备份管理通过一个API的固定集合来通信，不管底层的传输是什么。
Data backup is not guaranteed to be available on all Android-powered devices. However, your application is not adversely affected in the event that a device does not provide a backup transport. If you believe that users will benefit from data backup in your application, then you can implement it as described in this document, test it, then publish your application without any concern about which devices actually perform backup. When your application runs on a device that does not provide a backup transport, your application operates normally, but will not receive callbacks from the Backup Manager to backup data.
数据备份不保证在所有基于Android的设备上可用。然而，你的应用程序不会在设备不提供备份传输的事件中受到不好的影响。如果你相信用户将在你的应用程序中从数据备份里获益，那么你可以实现它如同本文描述的那样，测试它，然后发布你的应用程序而不关心那种设备实际上会执行备份。当你的应用程序运行在一个不提供备份传输的设备上时，你的应用程序正常地操作，但将不会接收来自备份管理器的回调以备份数据。
Although you cannot know what the current transport is, you are always assured that your backup data cannot be read by other applications on the device. Only the Backup Manager and backup transport have access to the data you provide during a backup operation.
虽然你无法知道当前传输是什么，但你总是肯定你的备份数据无法被设备上的其它应用程序读取。只有备份管理器和备份传输拥有你在备份操作期间提供的数据的访问权。
-------------------------------
Caution: Because the cloud storage and transport service can differ from device to device, Android makes no guarantees about the security of your data while using backup. You should always be cautious about using backup to store sensitive data, such as usernames and passwords.
警告：因为云存储和传输服务可能因设备而不同，所以Android不保证正在使用备份时你的数据的安全。你应该总是谨慎地使用备份来存储敏感数据，诸如用户名和密码。
-------------------------------
The Basics
基础
To backup your application data, you need to implement a backup agent. Your backup agent is called by the Backup Manager to provide the data you want to back up. It is also called to restore your backup data when the application is re-installed. The Backup Manager handles all your data transactions with the cloud storage (using the backup transport) and your backup agent handles all your data transactions on the device.
为了备份你的应用程序数据，你需要实现一个备份代理。你的备份代理被备份管理器调用以提供你希望备份的数据。它还被调用以还原你的备份数据，当应用程序被重新安装时。备份管理器处理你使用云存储的所有数据事务（使用备份传输）而你的备份代理处理你在设备上的所有数据事务。
To implement a backup agent, you must:
为了实现一个备份代理，你必须：
1. Declare your backup agent in your manifest file with the android:backupAgent attribute.
1. 在你的清单文件中用android:backupAgent属性声明你的备份代理。
2. Register your application with a backup service. Google offers Android Backup Service as a backup service for most Android-powered devices, which requires that you register your application in order for it to work. Any other backup services available might also require you to register in order to store your data on their servers.
2. 用一个备份服务注册你的应用程序。Google提供Android备份服务作为用于基于Android的设备的备份服务，它需要你注册你的应用程序以使它能工作。其它任何可用的备份服务还可能需要你注册以存储你的数据到它们的服务器上。
3. Define a backup agent by either:
3. 定义一个备份代理，用以下其中一种方法：
a. Extending BackupAgent
a. 扩展BackupAgent
The BackupAgent class provides the central interface with which your application communicates with the Backup Manager. If you extend this class directly, you must override onBackup() and onRestore() to handle the backup and restore operations for your data.
BackupAgent类提供中心接口，你的应用程序用它与备份管理器通信。如果你直接扩展这个类，那么你必须覆盖onBackup()和onRestore()以为你的数据处理备份和还原操作。
Or
或者
b. Extending BackupAgentHelper
b. 扩展BackupAgentHelper
The BackupAgentHelper class provides a convenient wrapper around the BackupAgent class, which minimizes the amount of code you need to write. In your BackupAgentHelper, you must use one or more "helper" objects, which automatically backup and restore certain types of data, so that you do not need to implement onBackup() and onRestore().
BackupAgentHelper类提供一个封装BackupAgent类的便利封装器，它最小化你需要编写的代码量。在你的BackupAgentHelper中，你必须使用一个或多个“辅助器”对象，它自动地备份和还原某种数据类型，致使你不需要实现onBackup()和onRestore()。
Android currently provides backup helpers that will backup and restore complete files from SharedPreferences and internal storage.
Android当前提供备份辅助器，它将从SharedPreferences和内部存储中备份和还原完整的文件。
-------------------------------
Declaring the Backup Agent in Your Manifest
在你的清单中声明备份代理
This is the easiest step, so once you've decided on the class name for your backup agent, declare it in your manifest with the android:backupAgent attribute in the <application> tag.
这是最简单的步骤，所以一旦你已经为你的备份代理决定好类名，就在你的清单中用<application>标签里的android:backupAgent属性声明它。
For example:
例如：
-------------------------------
<manifest ... >
...
<application android:label="MyApplication"
android:backupAgent="MyBackupAgent">
<activity ... >
...
</activity>
</application>
</manifest>
-------------------------------
Another attribute you might want to use is android:restoreAnyVersion. This attribute takes a boolean value to indicate whether you want to restore the application data regardless of the current application version compared to the version that produced the backup data. (The default value is "false".) See Checking the Restore Data Version for more information.
另一个你可能希望使用的属性是android:restoreAnyVersion。这个属性持有一个布尔型值以指示你是否希望还原应用程序的数据，不管当前的应用程序版本比较生成备份数据的版本的结果。（默认值是"false"。）参见检查还原数据版本以获取更多信息。
-------------------------------
Note: The backup service and the APIs you must use are available only on devices running API Level 8 (Android 2.2) or greater, so you should also set your android:minSdkVersion attribute to "8". However, if you implement proper backward compatibility in your application, you can support this feature for devices running API Level 8 or greater, while remaining compatible with older devices.
注意：备份服务和你必须使用的API仅在运行API级别8（Android 2.2）或更高的设备上可用，所以你还应该设置你的android:minSdkVersion属性为"8"。然而，如果你在你的应用程序中实现正确的向后兼容性，那么你可以对运行API级别8或以上的设备支持这个特性，同时保留较旧设备的兼容性。
-------------------------------
-------------------------------
Registering for Android Backup Service
注册Android备份服务
Google provides a backup transport with Android Backup Service for most Android-powered devices running Android 2.2 or greater.
Google用Android备份服务为大多数运行Android 2.2或更高的基于Android的设备提供备份传输。
In order for you application to perform backup using Android Backup Service, you must register your application with the service to receive a Backup Service Key, then declare the Backup Service Key in your Android manifest.
为了让你的应用程序使用Android备份服务执行备份，你必须用该服务注册你的应用程序以接收一个备份服务键，然后在你的Android清单中声明该备份服务键。
To get your Backup Service Key, register for Android Backup Service. When you register, you will be provided a Backup Service Key and the appropriate <meta-data> XML code for your Android manifest file, which you must include as a child of the <application> element. For example:
为了获得你的备份服务键，请注册Android备份服务。当你注册时，它将向你提供一个备份服务键和用于你的Android清单文件的合适的<meta-data>的XML代码，你必须包含它作为<application>元素的子节点。例如：
-------------------------------
<application android:label="MyApplication"
android:backupAgent="MyBackupAgent">
...
<meta-data android:name="com.google.android.backup.api_key"
android:value="AEdPqrEAAAAIDaYEVgU6DJnyJdBmU7KLH3kszDXLv_4DIsEIyQ" />
</application>
-------------------------------
The android:name must be "com.google.android.backup.api_key" and the android:value must be the Backup Service Key received from the Android Backup Service registration.
android:name必须是"com.google.android.backup.api_key"，而android:value必须是从Android备份服务注册中接收的备份服务键。
If you have multiple applications, you must register each one, using the respective package name.
如果你有多个应用程序，你必须注册每一个，使用相应的包名。
-------------------------------
Note: The backup transport provided by Android Backup Service is not guaranteed to be available on all Android-powered devices that support backup. Some devices might support backup using a different transport, some devices might not support backup at all, and there is no way for your application to know what transport is used on the device. However, if you implement backup for your application, you should always include a Backup Service Key for Android Backup Service so your application can perform backup when the device uses the Android Backup Service transport. If the device does not use Android Backup Service, then the <meta-data> element with the Backup Service Key is ignored.
注意：Android备份服务提供的备份传输不保证在支持备份的所有基于Android的设备上可用。一些设备可能支持使用不同的传输来备份，一些设备可能完全不支持备份，而且你的应用程序没有办法知道在设备上使用什么传输。然而，如果你为你的应用程序实现备份，那么你应该总是包含一个用于Android备份服务的备份服务键，使你的应用程序可以在设备使用Android备份服务传输时执行备份（注：这句话的意思也可能是：在执行备份时使用Android备份服务传输）。如果设备不使用Android备份服务，那么带备份服务键的<meta-data>元素被忽略。
-------------------------------
-------------------------------
Extending BackupAgent
扩展BackupAgent
Most applications shouldn't need to extend the BackupAgent class directly, but should instead extend BackupAgentHelper to take advantage of the built-in helper classes that automatically backup and restore your files. However, you might want to extend BackupAgent directly if you need to:
大多数应用程序不需要直接扩展BackupAgent类，而应该改为扩展BackupAgentHelper以利用自动备份和还原你的文件的内建辅助类。然而，你可能希望直接扩展BackupAgent，如果你需要：
* Version your data format. For instance, if you anticipate the need to revise the format in which you write your application data, you can build a backup agent to cross-check your application version during a restore operation and perform any necessary compatibility work if the version on the device is different than that of the backup data. For more information, see Checking the Restore Data Version.
* 版本化你的数据格式。例如，如果你预计需要修订你写入你的应用程序数据的格式，那么你可以构建一个备份代理以在还原操作期间再次复核你的应用程序版本，并且执行任意必需的兼容性工作如果设备上的版本不同于备份数据的版本。想获取更多信息，请参见检查还原数据版本。
* Instead of backing up an entire file, you can specify the portions of data the should be backed up and how each portion is then restored to the device. (This can also help you manage different versions, because you read and write your data as unique entities, rather than complete files.)
* 不是备份整个文件，你可以指定应该备份的数据局部（注：the可能是that的笔误）以及然后每个局部如何被还原到设备。（它还可以帮助你管理不同的版本，因为你读写你的数据作为唯一的实体，而非整个文件。）
* Back up data in a database. If you have an SQLite database that you want to restore when the user re-installs your application, you need to build a custom BackupAgent that reads the appropriate data during a backup operation, then create your table and insert the data during a restore operation.
* 备份数据库中的数据。如果当用户重新安装你的应用程序时你有一个你希望还原的SQLite数据库，你必须构建一个自定义BackupAgent，它在备份操作期间读取合适的数据，然后在还原操作期间创建你的表和插入数据。
If you don't need to perform any of the tasks above and want to back up complete files from SharedPreferences or internal storage, you should skip to Extending BackupAgentHelper.
如果你不需要执行上述的任何任务并且希望从SharedPreferences中备份整个文件或内部存储，那么你应该跳到扩展BackupAgentHelper。
Required Methods
必需的方法
When you create a backup agent by extending BackupAgent, you must implement the following callback methods:
当你用扩展的BackupAgent创建一个备份代理时，你必须实现以下回调方法：
* onBackup()
The Backup Manager calls this method after you request a backup. In this method, you read your application data from the device and pass the data you want to back up to the Backup Manager, as described below in Performing backup.
备份代理在你请求一个备份时调用此方法。在这个方法中，你从设备中读取你的应用程序数据并且传递你想备份的数据到备份管理器，正如下面执行备份中所描述的那样。
* onRestore()
The Backup Manager calls this method during a restore operation (you can request a restore, but the system automatically performs restore when the user re-installs your application). When it calls this method, the Backup Manager delivers your backup data, which you then restore to the device, as described below in Performing restore.
备份管理器在一次还原操作期间调用此方法（你可以请求一次还原，但系统在用户重新安装你的应用程序时自动执行还原）。当它调用此方法时，备份管理器传递你的备份数据，然后你恢复它到设备，正如下面执行还原中所描述的那样。
Performing backup
执行备份
When it's time to back up your application data, the Backup Manager calls your onBackup() method. This is where you must provide your application data to the Backup Manager so it can be saved to cloud storage.
当是时候备份你的应用程序数据时，备份管理器调用你的onBackup()方法。在这里你必须提供你的应用程序数据给备份管理器，使它可以被保存到云存储。
Only the Backup Manager can call your backup agent's onBackup() method. Each time that your application data changes and you want to perform a backup, you must request a backup operation by calling dataChanged() (see Requesting Backup for more information). A backup request does not result in an immediate call to your onBackup() method. Instead, the Backup Manager waits for an appropriate time, then performs backup for all applications that have requested a backup since the last backup was performed.
只有备份管理器可以调用你的备份代理的onBackup()方法。每次你的应用程序数据改变而你希望执行备份，你必须通过调用dataChanged()请求备份操作（参见请求备份以获取更多信息）。备份请求不会导致对你的onBackup()方法的即时调用。取而代之，备份管理器等待一个合适的时机，然后为从上次执行备份开始请求备份的所有应用程序执行备份。
-------------------------------
Tip: While developing your application, you can initiate an immediate backup operation from the Backup Manager with the bmgr tool.
提示：当开发你的应用程序时，你可以用bmgr工具从备份管理器中初始化一次即时备份操作。
-------------------------------
When the Backup Manager calls your onBackup() method, it passes three parameters:
当备份管理器调用你的onBackup()方法时，它传进三个参数：
* oldState
An open, read-only ParcelFileDescriptor pointing to the last backup state provided by your application. This is not the backup data from cloud storage, but a local representation of the data that was backed up the last time onBackup() was called (as defined by newState, below, or from onRestore()—more about this in the next section). Because onBackup() does not allow you to read existing backup data in the cloud storage, you can use this local representation to determine whether your data has changed since the last backup.
一个打开的、只读的ParcelFileDescriptor，它指向你的应用程序提供的最后备份状态。它不是来自云存储的备份数据，而是上次onBackup()被调用时被备份的数据的本地表现（正如下面newState所定义的，或来自onRestore()——下一节中有关于它的更多内容）。因为onBackup()不允许你在云存储中读取现存备份数据，所以你可以使用这个本地表现来决定你的数据从上次备份开始是否已经被改变。
* data
A BackupDataOutput object, which you use to deliver your backup data to the Backup Manager.
一个BackupDataOutput对象，你可以使用它传递你的备份数据到备份管理器。
* newState
An open, read/write ParcelFileDescriptor pointing to a file in which you must write a representation of the data that you delivered to data (a representation can be as simple as the last-modified timestamp for your file). This object is returned as oldState the next time the Backup Manager calls your onBackup() method. If you do not write your backup data to newState, then oldState will point to an empty file next time Backup Manager calls onBackup().
一个打开的、可读写的ParcelFileDescriptor，它指向你必须把你传递给data的数据表现写到的文件（表现可以简单到是你的文件的最近修改的时间戳）。下次备份管理器调用你的onBackup()方法时这个对象被返回作为oldState。如果你不写你的备份数据到newState，那么下次备份管理器调用onBackup()时oldState将指向一个空文件。
Using these parameters, you should implement your onBackup() method to do the following:
使用这些参数，你应该实现你的onBackup()方法以做如下事情：
1. Check whether your data has changed since the last backup by comparing oldState to your current data. How you read data in oldState depends on how you originally wrote it to newState (see step 3). The easiest way to record the state of a file is with its last-modified timestamp. For example, here's how you can read and compare a timestamp from oldState:
1. 检查你的数据从上次备份开始是否已经改变，通过比较oldState和你的当前数据。你如何读取oldState里的数据依赖于你最初如何写它到newState（见步骤3）。记录一个文件的状态的最简单方法是使用它的最近修改时间戳。例如，这里是你如何可以从oldState中读取和比较时间戳。
-------------------------------
// Get the oldState input stream
// 获取oldState输入流
FileInputStream instream = new FileInputStream(oldState.getFileDescriptor());
DataInputStream in = new DataInputStream(instream);
try {
// Get the last modified timestamp from the state file and data file
// 从状态文件和数据文件中获取最后修改时间戳
long stateModified = in.readLong();
long fileModified = mDataFile.lastModified();
if (stateModified != fileModified) {
// The file has been modified, so do a backup
// Or the time on the device changed, so be safe and do a backup
// 文件已经被修改过，所以执行备份
// 或者设备上的时间改变，所以会安全并执行一次备份
} else {
// Don't back up because the file hasn't changed
// 不要备份，因为文件还未改变
return;
}
} catch (IOException e) {
// Unable to read state file... be safe and do a backup
// 无法读取状态文件... 安全并执行一次备份
}
-------------------------------
If nothing has changed and you don't need to back up, skip to step 3.
如果没有东西改变而且你不需要备份，请跳到步骤3。
2. If your data has changed, compared to oldState, write the current data to data to back it up to the cloud storage.
2. 如果你的数据已经改变，请比较oldState，写当前数据到data以备份它到云存储。
You must write each chunk of data as an "entity" in the BackupDataOutput. An entity is a flattened binary data record that is identified by a unique key string. Thus, the data set that you back up is conceptually a set of key-value pairs.
你必须写入每个数据块作为BackupDataOutput中的一个“实体”。一个实体是平的二进制数据记录，它被一个唯一的键字符串标识。因此，你备份的数据集概念上是键值对的集合。
To add an entity to your backup data set, you must:
为了添加一个实体到你的备份数据集，你必须：
1. Call writeEntityHeader(), passing a unique string key for the data you're about to write and the data size.
1. 调用writeEntityHeader()，传进你打算写的数据的唯一字符串键和数据大小。
2. Call writeEntityData(), passing a byte buffer that contains your data and the number of bytes to write from the buffer (which should match the size passed to writeEntityHeader()).
2. 调用writeEntityData()，传进一个包含你的数据的字节缓冲和要从缓冲区中写的字节数（它应该匹配传给writeEntityHeader()的大小）。
For example, the following code flattens some data into a byte stream and writes it into a single entity:
例如，以下代码把一些数据变平放进一个字节流并把它写进一个单一的实体：
-------------------------------
// Create buffer stream and data output stream for our data
// 为我们的数据创建缓冲流和数据输出流
ByteArrayOutputStream bufStream = new ByteArrayOutputStream();
DataOutputStream outWriter = new DataOutputStream(bufStream);
// Write structured data
// 写入结构化数据
outWriter.writeUTF(mPlayerName);
outWriter.writeInt(mPlayerScore);
// Send the data to the Backup Manager via the BackupDataOutput
// 通过BackupDataOutput发送数据给备份管理器
byte[] buffer = bufStream.toByteArray();
int len = buffer.length;
data.writeEntityHeader(TOPSCORE_BACKUP_KEY, len);
data.writeEntityData(buffer, len);
-------------------------------
Perform this for each piece of data that you want to back up. How you divide your data into entities is up to you (and you might use just one entity).
为每一块你希望备份的数据执行它。你如何划分你的数据为实体取决于你（而且你可能只使用一个实体）。
3. Whether or not you perform a backup (in step 2), write a representation of the current data to the newState ParcelFileDescriptor. The Backup Manager retains this object locally as a representation of the data that is currently backed up. It passes this back to you as oldState the next time it calls onBackup() so you can determine whether another backup is necessary (as handled in step 1). If you do not write the current data state to this file, then oldState will be empty during the next callback.
3. 不管你是否执行备份（在步骤2），都要写当前数据的表现到newState这个ParcelFileDescriptor对象。备份管理器局部地保留这个对象作为当前备份的数据的表现。下次它调用onBackup()时把它传回给你作为oldState，使你可以决定是否需要另一次备份（正如步骤1中处理的）。如果你不写当前数据状态到这个文件，那么下一次回调期间oldState将是空的。
The following example saves a representation of the current data into newState using the file's last-modified timestamp:
以下示例使用文件的最后修改时间戳来保存当前数据的表现进newState。
-------------------------------
FileOutputStream outstream = new FileOutputStream(newState.getFileDescriptor());
DataOutputStream out = new DataOutputStream(outstream);
long modified = mDataFile.lastModified();
out.writeLong(modified);
-------------------------------
-------------------------------
Caution: If your application data is saved to a file, make sure that you use synchronized statements while accessing the file so that your backup agent does not read the file while an Activity in your application is also writing the file.
警告：如果你的应用程序数据被保存到一个文件，那么确保你正在访问文件时使用synchronized语句，使你的应用程序的一个Activity也在写文件时你的备份代理不读取文件。
-------------------------------
Performing restore
执行还原
When it's time to restore your application data, the Backup Manager calls your backup agent's onRestore() method. When it calls this method, the Backup Manager delivers your backup data so you can restore it onto the device.
当到了还原你的应用程序数据的时候，备份管理器调用你的备份代理的onRestore()方法。当它调用这个方法时，备份管理器传递你的备份数据，使你可以还原它到设备上。
Only the Backup Manager can call onRestore(), which happens automatically when the system installs your application and finds existing backup data. However, you can request a restore operation for your application by calling requestRestore() (see Requesting restore for more information).
只有备份管理器可以调用onRestore()，这自动地发生在系统安装你的应用程序并找到现存备份数据的时候。然而，你可以通过调用requestRestore()为你的应用程序请求还原操作（参见请求还原以获取更多信息）。
-------------------------------
Note: While developing your application, you can also request a restore operation with the bmgr tool.
注意：当正在开发你的应用程序时，你还可以用bmgr工具请求还原操作。
-------------------------------
When the Backup Manager calls your onRestore() method, it passes three parameters:
当备份管理器调用你的onRestore()方法时，它传进三个参数：
* data
A BackupDataInput, which allows you to read your backup data.
一个BackupDataInput，它允许你读取你的备份数据。
* appVersionCode
An integer representing the value of your application's android:versionCode manifest attribute, as it was when this data was backed up. You can use this to cross-check the current application version and determine if the data format is compatible. For more information about using this to handle different versions of restore data, see the section below about Checking the Restore Data Version.
一个整数，代表你的应用程序的android:versionCode清单属性的值，正如当这个数据被备份时那样。你可以使用它再次复核当前应用程序版本并决定数据格式是否兼容。想获取关于使用它来处理还原数据的不同版本的更多信息，请参见下面关于检查还原数据版本的章节。
* newState
An open, read/write ParcelFileDescriptor pointing to a file in which you must write the final backup state that was provided with data. This object is returned as oldState the next time onBackup() is called. Recall that you must also write the same newState object in the onBackup() callback—also doing it here ensures that the oldState object given to onBackup() is valid even the first time onBackup() is called after the device is restored.
一个打开的、可读写的ParcelFileDescriptor，它指向一个你必须把数据（注：data？）提供的最终备份状态写入的文件。下次onBackup()被调用时这个对象被返回作为oldState。记得你还必须在onBackup()回调中写相同的newState对象——这里还要做它，确保传给onBackup()的oldState对象是可用的，甚至是在设备被还原后onBackup()第一次被调用的时候。
In your implementation of onRestore(), you should call readNextHeader() on the data to iterate through all entities in the data set. For each entity found, do the following:
在你的onRestore()实现里，你应该在数据上调用readNextHeader()以迭代遍历数据集中的所有实体。对于每个找到的实体，做以下事情：
1. Get the entity key with getKey().
1. 用getKey()获得实体键。
2. Compare the entity key to a list of known key values that you should have declared as static final strings inside your BackupAgent class. When the key matches one of your known key strings, enter into a statement to extract the entity data and save it to the device:
2. 比较实体键和你已经在你的BackupAgent类中声明为static final字符串的已知键值的列表。当键匹配你已知键字符串的其中一个时，进入一个语句以提取实体数据并保存它到设备：
1. Get the entity data size with getDataSize() and create a byte array of that size.
1. 用getDataSize()获得实体数据大小并且创建那个大小的字节数组。
2. Call readEntityData() and pass it the byte array, which is where the data will go, and specify the start offset and the size to read.
2. 调用readEntityData()并传给它数据将跑到的字节数组，并且指定开始偏移和要读取的大小。
3. Your byte array is now full and you can read the data and write it to the device however you like.
3. 你的字节数组现在是填满的，你可以用你喜欢的任意方法读取数据和把它写到设备上。
3. After you read and write your data back to the device, write the state of your data to the newState parameter the same as you do during onBackup().
3. 你读写你的数据回设备后，写你的数据的状态到newState参数，和你在onBackup()期间做的相同。
For example, here's how you can restore the data backed up by the example in the previous section:
例如，这里是你如何可以还原被前面章节中的示例备份的数据。
-------------------------------
@Override
public void onRestore(BackupDataInput data, int appVersionCode,
ParcelFileDescriptor newState) throws IOException {
// There should be only one entity, but the safest
// way to consume it is using a while loop
// 应该只有一个实体，但消耗它的最安全方法
// 是使用while循环
while (data.readNextHeader()) {
String key = data.getKey();
int dataSize = data.getDataSize();
// If the key is ours (for saving top score). Note this key was used when
// we wrote the backup entity header
// 如果键是我们的（用于保存最高分数）。注意这个键被使用，
// 当我们写入备份的实体头时
if (TOPSCORE_BACKUP_KEY.equals(key)) {
// Create an input stream for the BackupDataInput
// 为BackupDataInput创建一个输入流
byte[] dataBuf = new byte[dataSize];
data.readEntityData(dataBuf, 0, dataSize);
ByteArrayInputStream baStream = new ByteArrayInputStream(dataBuf);
DataInputStream in = new DataInputStream(baStream);
// Read the player name and score from the backup data
// 从备份数据中读取播放器名称和分数
mPlayerName = in.readUTF();
mPlayerScore = in.readInt();
// Record the score on the device (to a file or something)
// 记录分数在设备上（到一个文件或一些东西）
recordScore(mPlayerName, mPlayerScore);
} else {
// We don't know this entity key. Skip it. (Shouldn't happen.)
// 我们不知道这个实体键。跳过它。（不应该发生。）
data.skipEntityData();
}
}
// Finally, write to the state blob (newState) that describes the restored data
// 最后，写入到描述还原数据的状态二进制大对象（注：blob是Binary large object的缩写，即二进制大对象）（newState）
FileOutputStream outstream = new FileOutputStream(newState.getFileDescriptor());
DataOutputStream out = new DataOutputStream(outstream);
out.writeUTF(mPlayerName);
out.writeInt(mPlayerScore);
}
-------------------------------
In this example, the appVersionCode parameter passed to onRestore() is not used. However, you might want to use it if you've chosen to perform backup when the user's version of the application has actually moved backward (for example, the user went from version 1.5 of your app to 1.0). For more information, see the section about Checking the Restore Data Version.
在这个示例中，传给onRestore()的appVersionCode参数没有被使用。然而，你可能希望使用它，如果你已经选择在用户的应用程序版本实际上已经向后移动的时候执行备份（例如，用户从你的应用的版本1.5移到1.0）。想获取更多信息，请参见关于检查还原数据版本的章节。
-------------------------------
For an example implementation of BackupAgent, see the ExampleAgent class in the Backup and Restore sample application.
想获取BackupAgent的示例实现，请参见备份和还原示例应用程序中的ExampleAgent类。
-------------------------------
-------------------------------
Extending BackupAgentHelper
扩展BackupAgentHelper
You should build your backup agent using BackupAgentHelper if you want to back up complete files (from either SharedPreferences or internal storage). Building your backup agent with BackupAgentHelper requires far less code than extending BackupAgent, because you don't have to implement onBackup() and onRestore().
你应该使用BackupAgentHelper构建你的备份代理，如果你希望备份整个文件（来自SharedPreferences或内部存储）。用BackupAgentHelper构建你的备份代理需要远少于扩展BackupAgent的代码，因为你不必实现onBackup()和onRestore()。
Your implementation of BackupAgentHelper must use one or more backup helpers. A backup helper is a specialized component that BackupAgentHelper summons to perform backup and restore operations for a particular type of data. The Android framework currently provides two different helpers:
你的BackupAgentHelper的实现必须使用一个或多个备份辅助器。一个备份辅助器是一个专门的组件，BackupAgentHelper召唤它来为一种特殊类型的数据执行备份和还原操作。Android框架当前提供两种不同的辅助器：
* SharedPreferencesBackupHelper to backup SharedPreferences files.
* SharedPreferencesBackupHelper以备份SharedPreferences文件。
* FileBackupHelper to backup files from internal storage.
* FileBackupHelper以备份来自内部存储的文件。
You can include multiple helpers in your BackupAgentHelper, but only one helper is needed for each data type. That is, if you have multiple SharedPreferences files, then you need only one SharedPreferencesBackupHelper.
你可以在你的BackupAgentHelper中包含多个辅助器，但对于每个数据类型只有一个辅助器是需要的。就是说，如果你有多个SharedPreferences文件，那么你只需要一个SharedPreferencesBackupHelper。
For each helper you want to add to your BackupAgentHelper, you must do the following during your onCreate() method:
对于你希望添加到你的BackupAgentHelper的每个辅助器，你必须在你的onCreate()方法期间做以下事情：
1. Instantiate in instance of the desired helper class. In the class constructor, you must specify the appropriate file(s) you want to backup.
1. 在期望的辅助器类的实例中实例化。在类的构造函数中，你必须指定你希望备份的合适文件。
2. Call addHelper() to add the helper to your BackupAgentHelper.
2. 调用addHelper()以添加辅助器到你的BackupAgentHelper。
The following sections describe how to create a backup agent using each of the available helpers.
以下章节描述如何使用每种可用的辅助器来创建备份代理。
Backing up SharedPreferences
备份SharedPreferences
When you instantiate a SharedPreferencesBackupHelper, you must include the name of one or more SharedPreferences files.
当你实例化一个SharedPreferencesBackupHelper时，你必须包含一个或多个SharedPreferences文件的名称。
For example, to back up a SharedPreferences file named "user_preferences", a complete backup agent using BackupAgentHelper looks like this:
例如，为了备份一个名为"user_preferences"的SharedPreferences，一个使用BackupAgentHelper的完整备份代理看起来像这样：
-------------------------------
public class MyPrefsBackupAgent extends BackupAgentHelper {
// The name of the SharedPreferences file
// SharedPreferences文件的名称
static final String PREFS = "user_preferences";
// A key to uniquely identify the set of backup data
// 一个键以唯一地标识备份数据的集合
static final String PREFS_BACKUP_KEY = "prefs";
// Allocate a helper and add it to the backup agent
// 分配一个辅助器并添加它到备份代理
@Override
public void onCreate() {
SharedPreferencesBackupHelper helper = new SharedPreferencesBackupHelper(this, PREFS);
addHelper(PREFS_BACKUP_KEY, helper);
}
}
-------------------------------
That's it! That's your entire backup agent. The SharedPreferencesBackupHelper includes all the code needed to backup and restore a SharedPreferences file.
这样就行了！那是你的整个备份代理。SharedPreferencesBackupHelper包含备份和还原一个SharedPreferences文件所需的所有代码。
When the Backup Manager calls onBackup() and onRestore(), BackupAgentHelper calls your backup helpers to perform backup and restore for your specified files.
当备份管理器调用onBackup()和onRestore()时，BackupAgentHelper调用你的备份辅助器以为你的指定文件执行备份和还原。
-------------------------------
Note: SharedPreferences are threadsafe, so you can safely read and write the shared preferences file from your backup agent and other activities.
注意：SharedPreferences是线程安全的，所以你可以安全地从你的备份代理和其它活动中读写共享预设文件。
-------------------------------
Backing up other files
备份其它文件
When you instantiate a FileBackupHelper, you must include the name of one or more files that are saved to your application's internal storage (as specified by getFilesDir(), which is the same location where openFileOutput() writes files).
当你实例化一个FileBackupHelper时，你必须包含被保存到你的应用程序的内部存储的一个或多个文件的名称（正如getFilesDir()所指定的，它和openFileOutput()写文件的位置是相同的）。
For example, to backup two files named "scores" and "stats," a backup agent using BackupAgentHelper looks like this:
例如，为了备份两个名为"scores"和"stats"的文件，一个使用BackupAgentHelper的备份代理看起来像这样：
-------------------------------
public class MyFileBackupAgent extends BackupAgentHelper {
// The name of the SharedPreferences file
// SharedPreferences文件的名称
static final String TOP_SCORES = "scores";
static final String PLAYER_STATS = "stats";
// A key to uniquely identify the set of backup data
// 一个键以唯一地标识备份数据的集合
static final String FILES_BACKUP_KEY = "myfiles";
// Allocate a helper and add it to the backup agent
// 分配一个辅助器并添加它到备份代理
void onCreate() {
FileBackupHelper helper = new FileBackupHelper(this, TOP_SCORES, PLAYER_STATS);
addHelper(FILES_BACKUP_KEY, helper);
}
}
-------------------------------
The FileBackupHelper includes all the code necessary to backup and restore files that are saved to your application's internal storage..
FileBackupHelper包含备份和还原保存到你的应用程序的内部存储的文件所需的所有代码。
However, reading and writing to files on internal storage is not threadsafe. To ensure that your backup agent does not read or write your files at the same time as your activities, you must use synchronized statements each time you perform a read or write. For example, in any Activity where you read and write the file, you need an object to use as the intrinsic lock for the synchronized statements:
然而，内部存储上的文件的读写不是线程安全的。为了确保你的备份代理不和你的活动同时读写你的文件，你必须在每次你执行读或写的时候使用synchronized语句。例如，在任意Activity中你读写文件的地方，你需要一个对象以用作synchronized语句的内在锁：
-------------------------------
Interesting Fact:
有趣的事实：
A zero-length array is lighter-weight than a normal Object, so it's great for an intrinsic lock.
一个零长度的数组比一个正常Object较轻量级，所以最好用它做内在锁。
-------------------------------
-------------------------------
// Object for intrinsic lock
// 用于内在锁（注：即Java中使用synchronized的锁）的对象
static final Object[] sDataLock = new Object[0];
-------------------------------
Then create a synchronized statement with this lock each time you read or write the files. For example, here's a synchronized statement for writing the latest score in a game to a file:
然后每次你读或写文件时用这个锁创建一个synchronized语句。例如，这里有一个synchronized语句用于写游戏中最近的分数到一个文件：
-------------------------------
try {
synchronized (MyActivity.sDataLock) {
File dataFile = new File(getFilesDir(), TOP_SCORES);
RandomAccessFile raFile = new RandomAccessFile(dataFile, "rw");
raFile.writeInt(score);
}
} catch (IOException e) {
Log.e(TAG, "Unable to write to file");
}
-------------------------------
You should synchronize your read statements with the same lock.
你应该用相同的锁同步你的读语句。
Then, in your BackupAgentHelper, you must override onBackup() and onRestore() to synchronize the backup and restore operations with the same intrinsic lock. For example, the MyFileBackupAgent example from above needs the following methods:
然后，在你的BackupAgentHelper中，你必须覆盖onBackup()和onRestore()以用相同的内在锁同步备份和还原操作。例如，来自上文的MyFileBackupAgent示例需要以下方法：
-------------------------------
@Override
public void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
ParcelFileDescriptor newState) throws IOException {
// Hold the lock while the FileBackupHelper performs backup
// 当FileBackupHelper执行备份时持有锁
synchronized (MyActivity.sDataLock) {
super.onBackup(oldState, data, newState);
}
}
@Override
public void onRestore(BackupDataInput data, int appVersionCode,
ParcelFileDescriptor newState) throws IOException {
// Hold the lock while the FileBackupHelper restores the file
// 当FileBackupHelper还原文件时持有锁
synchronized (MyActivity.sDataLock) {
super.onRestore(data, appVersionCode, newState);
}
}
-------------------------------
That's it. All you need to do is add your FileBackupHelper in the onCreate() method and override onBackup() and onRestore() to synchronize read and write operations.
这样就行了。你需要做的所有事情是在onCreate()方法中添加你的FileBackupHelper，并且覆盖onBackup()和onRestore()以同步读写操作。
-------------------------------
For an example implementation of BackupAgentHelper with FileBackupHelper, see the FileHelperExampleAgent class in the Backup and Restore sample application.
想获取带FileBackupHelper的BackupAgentHelper的示例实现，请参见备份和还原示例应用程序中的FileHelperExampleAgent类。
-------------------------------
-------------------------------
Checking the Restore Data Version
检查还原数据版本
When the Backup Manager saves your data to cloud storage, it automatically includes the version of your application, as defined by your manifest file's android:versionCode attribute. Before the Backup Manager calls your backup agent to restore your data, it looks at the android:versionCode of the installed application and compares it to the value recorded in the restore data set. If the version recorded in the restore data set is newer than the application version on the device, then the user has downgraded their application. In this case, the Backup Manager will abort the restore operation for your application and not call your onRestore() method, because the restore set is considered meaningless to an older version.
当备份管理器保存你的数据到云存储时，它自动地包含你的应用程序的版本，正如你的清单文件的android:versionCode属性中定义的那样。在备份管理器调用你的备份代理以还原你的数据之前，它查看被安装应用程序的android:versionCode以及比较它和还原数据集中记录的值。如果记录在还原数据集的版本比设备上的应用程序版本新，那么用户降级了他们的应用程序。在这种情况下，备份管理器将中止你的应用程序的还原操作，并且不调用你的onRestore()方法，因为还原集合被认为对于旧版本来说是没有意义的。
You can override this behavior with the android:restoreAnyVersion attribute. This attribute is either "true" or "false" to indicate whether you want to restore the application regardless of the restore set version. The default value is "false". If you define this to be "true" then the Backup Manager will ignore the android:versionCode and call your onRestore() method in all cases. In doing so, you can manually check for the version difference in your onRestore() method and take any steps necessary to make the data compatible if the versions conflict.
你可以用android:restoreAnyVersion属性覆盖这个行为。这个属性是"true"或者是"false"以指示你是否希望还原应用程序，不管还原集合的版本是什么。默认值为"false"。如果你定义它为"true"，那么备份管理器将忽略android:versionCode并在所有情况下调用你的onRestore()方法。这样做的情况下，你可以在你的onRestore()方法中手动检查版本区别并且采取任何必需的步骤以使数据兼容，如果版本有冲突。
To help you handle different versions during a restore operation, the onRestore() method passes you the version code included with the restore data set as the appVersionCode parameter. You can then query the current application's version code with the PackageInfo.versionCode field. For example:
为了帮助你在还原操作期间处理不同版本，onRestore()方法传给你还原数据集所包含的版本代码作为appVersionCode参数。然后你可以用PackageInfo.versionCode查询当前应用程序的版本代码。例如：
-------------------------------
PackageInfo info;
try {
String name = getPackageName();
info = getPackageManager().getPackageInfo(name,0);
} catch (NameNotFoundException nnfe) {
info = null;
}
int version;
if (info != null) {
version = info.versionCode;
}
-------------------------------
Then simply compare the version acquired from PackageInfo to the appVersionCode passed into onRestore().
然后简单地比较从PackageInfo中获得的版本和传递进onRestore()的appVersionCode。
-------------------------------
Caution: Be certain you understand the consequences of setting android:restoreAnyVersion to "true" for your application. If each version of your application that supports backup does not properly account for variations in your data format during onRestore(), then the data on the device could be saved in a format incompatible with the version currently installed on the device.
警告：请确信你理解为你的应用程序设置android:restoreAnyVersion为"true"的后果。如果你的应用程序的支持备份的每个版本在onRestore()期间没有正确地负责在你的数据格式中的变化，那么设备上的数据可以以一种不兼容当前已经安装在设备上的版本的格式来保存。
-------------------------------
-------------------------------
Requesting Backup
请求备份
You can request a backup operation at any time by calling dataChanged(). This method notifies the Backup Manager that you'd like to backup your data using your backup agent. The Backup Manager then calls your backup agent's onBackup() method at an opportune time in the future. Typically, you should request a backup each time your data changes (such as when the user changes an application preference that you'd like to back up). If you call dataChanged() several times consecutively, before the Backup Manager requests a backup from your agent, your agent still receives just one call to onBackup().
你可以在任何时候通过调用dataChanged()请求备份操作。这个方法使用你的备份代理通知你想备份你的数据的备份管理器。然后备份管理器在未来的一个合适时候调用你的备份代理的onBackup()方法。通常，每次你的数据改变你都应该请求备份（诸如当用户改变你想备份的应用程序预设时）。如果在备份管理器从你的代理中请求备份前，你连续调用dataChanged()几次，那么你的代理仍然只会接收一次对onBackup()的调用。
-------------------------------
Note: While developing your application, you can request a backup and initiate an immediate backup operation with the bmgr tool.
注意：当正在开发你的应用程序时，你可以用bmgr工具请求一次备份和初始化一次即时备份操作。
-------------------------------
-------------------------------
Requesting Restore
请求还原
During the normal life of your application, you shouldn't need to request a restore operation. They system automatically checks for backup data and performs a restore when your application is installed. However, you can manually request a restore operation by calling requestRestore(), if necessary. In which case, the Backup Manager calls your onRestore() implementation, passing the data from the current set of backup data.
在你的应用程序的正常生命期期间，你不需要请求还原操作。当你的应用程序被安装时，系统（注：they可能是the的笔误）自动地检查备份数据和执行还原。然而，你可以通过调用requestRestore()手动地请求还原操作，如果需要的话。在这种情况下，备份管理器调用你的onRestore()实现，传进来自备份数据的当前集合的数据。
-------------------------------
Note: While developing your application, you can request a restore operation with the bmgr tool.
注意：当正在开发你的应用程序时，你可以用bmgr工具请求还原操作。
-------------------------------
-------------------------------
Testing Your Backup Agent
测试你的备份代理
Once you've implemented your backup agent, you can test the backup and restore functionality with the following procedure, using bmgr.
一旦你已经实现好你的备份代理，你可以使用bmgr用以下步骤来测试备份和还原功能。
1. Install your application on a suitable Android system image
1. 安装你的应用程序在一个合适的Android系统镜像上
* If using the emulator, create and use an AVD with Android 2.2 (API Level 8).
* 如果使用模拟器，创建和使用一个带Android 2.2（API级别8）的AVD（注：AVD是Android虚拟设备的缩写）。
* If using a device, the device must be running Android 2.2 or greater and have Android Market built in.
* 如果使用设备，那么设备必须正在运行Android 2.2或更高并且有内建的Android市场。
2. Ensure that backup is enabled
2. 确保备份是被使能的
* If using the emulator, you can enable backup with the following command from your SDK tools/ path:
* 如果使用模拟器，那么你可以在你的SDK的tools/目录下用以下命令使能备份：
-------------------------------
adb shell bmgr enable true
-------------------------------
* If using a device, open the system Settings, select Privacy, then enable Back up my data and Automatic restore.
* 如果使用设备，那么打开系统设置，选择隐私，然后使能备份我的数据和自动还原。
3. Open your application and initialize some data
3. 打开你的应用程序和初始化一些数据
If you've properly implemented backup in your application, then it should request a backup each time the data changes. For example, each time the user changes some data, your app should call dataChanged(), which adds a backup request to the Backup Manager queue. For testing purposes, you can also make a request with the following bmgr command:
如果你已经在你的应用程序中正确地实现备份，那么每次数据改变它应该请求一次备份。例如，每次用户改变一些数据，你的应用应该调用dataChanged()，它添加一个备份请求到备份管理队列。出于测试的目的，你还可以用以下bmgr命令作出请求：
-------------------------------
adb shell bmgr backup your.package.name
adb shell bmgr backup <你的包名>
-------------------------------
4. Initiate a backup operation:
4. 初始化一个备份操作：
-------------------------------
adb shell bmgr run
-------------------------------
This forces the Backup Manager to perform all backup requests that are in its queue.
它强制备份管理器执行它的队列中的所有备份请求。
5. Uninstall your application:
5. 卸载你的应用程序：
-------------------------------
adb uninstall your.package.name
adb uninstall <你的包名>
-------------------------------
6. Re-install your application.
6. 重装你的用于程序。
If your backup agent is successful, all the data you initialized in step 4 is restored.
如果你的备份代理是成功的，那么你在步骤4中初始化的所有数据被还原。
Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.
除特别说明外，本文在Apache 2.0下许可。细节和限制请参考内容许可证。
Android 4.0 r1 - 20 Jan 2012 22:25
-------------------------------
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
（此页部分内容基于Android开源项目，以及使用根据创作公共2.5来源许可证描述的条款进行修改）
（本人翻译质量欠佳，请以官方最新内容为准，或者参考其它翻译版本：
* ソフトウェア技術ドキュメントを勝手に翻訳
http://www.techdoctranslator.com/android
* Ley's Blog
http://leybreeze.com/blog/
* 农民伯伯
http://www.cnblogs.com/over140/
* Android中文翻译组
http://androidbox.sinaapp.com/
）
xCode 4.2 是目前最新的iOS开发工具，苹果的东西总是更新的非常快，所以看在线文档是最好的。但是有些人没有开发者账号，或者上网有限制，如何像Java api或者MSDN一样安装离线文档呢，其实很简单，只要你记得你机器的管理员密码就可以了。
1.下载所需要的docset
打开xCode-》Preferences-》Downloads-》Documentation，点击Check and Install 会从服务器上更新最新的文档，你也可以根据你的需要选择要更新具体哪一个。
如果你的下载速度非常慢, 点击查看详细信息的按钮，你会看到
Feed: http://developer.apple.com/rss/com.apple.adc.documentation.AppleiPhone5_0.atom 这样的地址
用Safari浏览器访问，可以查看到列出的资源，选择你要下载的版本，通过迅雷或者其他下载工具下载。得到你需要的xar文件
2. 解压缩xar得到docset
下载下来的xar文件解压缩得到docset，拷贝到/Developer/Documentation/DocSets/ 目录下，这里你会用到你的管理员密码，如果文件名已经存在你可以删除旧的。
3. 重新启动xCode, 好了，你所有的文档都可以离线浏览了！