/* * Copyright (C) 2009 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.app; import android.app.IBackupAgent; import android.backup.BackupDataInput; import android.backup.BackupDataOutput; import android.backup.IBackupManager; import android.content.Context; import android.content.ContextWrapper; import android.os.Binder; import android.os.IBinder; import android.os.ParcelFileDescriptor; import android.os.RemoteException; import android.util.Log; import java.io.IOException; /** * This is the central interface between an application and Android's settings * backup mechanism. Any implementation of a backup agent should perform backup * and restore actions in * {@link #onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)} * and {@link #onRestore(BackupDataInput, int, ParcelFileDescriptor)} * respectively. *

* A backup agent based on convenient helper classes is available in * {@link android.backup.BackupHelperAgent} for less complex implementation * requirements. *

* STOPSHIP write more documentation about the backup process here. */ public abstract class BackupAgent extends ContextWrapper { private static final String TAG = "BackupAgent"; private static final boolean DEBUG = false; public BackupAgent() { super(null); } public void onCreate() { } public void onDestroy() { } /** * The application is being asked to write any data changed since the last * time it performed a backup operation. The state data recorded during the * last backup pass is provided in the oldState file * descriptor. If oldState is null, no old state * is available and the application should perform a full backup. In both * cases, a representation of the final backup state after this pass should * be written to the file pointed to by the file descriptor wrapped in * newState. * * @param oldState An open, read-only ParcelFileDescriptor pointing to the * last backup state provided by the application. May be * null, in which case no prior state is being * provided and the application should perform a full backup. * @param data A structured wrapper around an open, read/write * ParcelFileDescriptor pointing to the backup data destination. * Typically the application will use backup helper classes to * write to this file. * @param newState An open, read/write ParcelFileDescriptor pointing to an * empty file. The application should record the final backup * state here after writing the requested data to dataFd. */ public abstract void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data, ParcelFileDescriptor newState) throws IOException; /** * The application is being restored from backup and should replace any * existing data with the contents of the backup. The backup data is * provided in the file descriptor pointed to by the * {@link android.backup.BackupDataInput} instance data. Once * the restore is finished, the application should write a representation of * the final state to the newState file descriptor. *

* The application is responsible for properly erasing its old data and * replacing it with the data supplied to this method. No "clear user data" * operation will be performed automatically by the operating system. The * exception to this is in the case of a failed restore attempt: if * onRestore() throws an exception, the OS will assume that the * application's data may now be in an incoherent state, and will clear it * before proceeding. * * @param data A structured wrapper around an open, read-only * ParcelFileDescriptor pointing to a full snapshot of the * application's data. Typically the application will use helper * classes to read this data. * @param appVersionCode The android:versionCode value of the application * that backed up this particular data set. This makes it easier * for an application's agent to distinguish among several * possible older data versions when asked to perform the restore * operation. * @param newState An open, read/write ParcelFileDescriptor pointing to an * empty file. The application should record the final backup * state here after restoring its data from dataFd. */ public abstract void onRestore(BackupDataInput data, int appVersionCode, ParcelFileDescriptor newState) throws IOException; // ----- Core implementation ----- /** @hide */ public final IBinder onBind() { return mBinder; } private final IBinder mBinder = new BackupServiceBinder().asBinder(); /** @hide */ public void attach(Context context) { attachBaseContext(context); } // ----- IBackupService binder interface ----- private class BackupServiceBinder extends IBackupAgent.Stub { private static final String TAG = "BackupServiceBinder"; public void doBackup(ParcelFileDescriptor oldState, ParcelFileDescriptor data, ParcelFileDescriptor newState, int token, IBackupManager callbackBinder) throws RemoteException { // Ensure that we're running with the app's normal permission level long ident = Binder.clearCallingIdentity(); if (DEBUG) Log.v(TAG, "doBackup() invoked"); BackupDataOutput output = new BackupDataOutput(data.getFileDescriptor()); try { BackupAgent.this.onBackup(oldState, output, newState); } catch (IOException ex) { Log.d(TAG, "onBackup (" + BackupAgent.this.getClass().getName() + ") threw", ex); throw new RuntimeException(ex); } catch (RuntimeException ex) { Log.d(TAG, "onBackup (" + BackupAgent.this.getClass().getName() + ") threw", ex); throw ex; } finally { Binder.restoreCallingIdentity(ident); try { callbackBinder.opComplete(token); } catch (RemoteException e) { // we'll time out anyway, so we're safe } } } public void doRestore(ParcelFileDescriptor data, int appVersionCode, ParcelFileDescriptor newState, int token, IBackupManager callbackBinder) throws RemoteException { // Ensure that we're running with the app's normal permission level long ident = Binder.clearCallingIdentity(); if (DEBUG) Log.v(TAG, "doRestore() invoked"); BackupDataInput input = new BackupDataInput(data.getFileDescriptor()); try { BackupAgent.this.onRestore(input, appVersionCode, newState); } catch (IOException ex) { Log.d(TAG, "onRestore (" + BackupAgent.this.getClass().getName() + ") threw", ex); throw new RuntimeException(ex); } catch (RuntimeException ex) { Log.d(TAG, "onRestore (" + BackupAgent.this.getClass().getName() + ") threw", ex); throw ex; } finally { Binder.restoreCallingIdentity(ident); try { callbackBinder.opComplete(token); } catch (RemoteException e) { // we'll time out anyway, so we're safe } } } } }