BackupManager.java revision 3de55bcd34afd5871816526294f9514d1adf3fe5
1/* 2 * Copyright (C) 2009 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.app.backup; 18 19import android.app.backup.RestoreSession; 20import android.app.backup.IBackupManager; 21import android.app.backup.IRestoreSession; 22import android.content.Context; 23import android.os.RemoteException; 24import android.os.ServiceManager; 25import android.util.Log; 26 27/** 28 * BackupManager is the interface to the system's backup service. Applications 29 * simply instantiate one, and then use that instance to communicate with the 30 * backup infrastructure. 31 * <p> 32 * When an application has made changes to data which should be backed up, a 33 * call to {@link #dataChanged()} will notify the backup service. The system 34 * will then schedule a backup operation to occur in the near future. Repeated 35 * calls to {@link #dataChanged()} have no further effect until the backup 36 * operation actually occurs. 37 * <p> 38 * The backup operation itself begins with the system launching the 39 * {@link android.app.backup.BackupAgent} subclass declared in your manifest. See the 40 * documentation for {@link android.app.backup.BackupAgent} for a detailed description 41 * of how the backup then proceeds. 42 * <p> 43 * A simple implementation of a BackupAgent useful for backing up Preferences 44 * and files is available by using {@link android.app.backup.BackupHelperAgent}. 45 * <p> 46 * STOPSHIP: more documentation! 47 * <p> 48 * <b>XML attributes</b> 49 * <p> 50 * See {@link android.R.styleable#AndroidManifestApplication 51 * AndroidManifest.xml's application attributes} 52 * 53 * @attr ref android.R.styleable#AndroidManifestApplication_allowBackup 54 * @attr ref android.R.styleable#AndroidManifestApplication_backupAgent 55 * @attr ref android.R.styleable#AndroidManifestApplication_killAfterRestore 56 */ 57public class BackupManager { 58 private static final String TAG = "BackupManager"; 59 60 private Context mContext; 61 private static IBackupManager sService; 62 63 private static void checkServiceBinder() { 64 if (sService == null) { 65 sService = IBackupManager.Stub.asInterface( 66 ServiceManager.getService(Context.BACKUP_SERVICE)); 67 } 68 } 69 70 /** 71 * Constructs a BackupManager object through which the application can 72 * communicate with the Android backup system. 73 * 74 * @param context The {@link android.content.Context} that was provided when 75 * one of your application's {@link android.app.Activity Activities} 76 * was created. 77 */ 78 public BackupManager(Context context) { 79 mContext = context; 80 } 81 82 /** 83 * Notifies the Android backup system that your application wishes to back up 84 * new changes to its data. A backup operation using your application's 85 * {@link android.app.backup.BackupAgent} subclass will be scheduled when you call this method. 86 */ 87 public void dataChanged() { 88 checkServiceBinder(); 89 if (sService != null) { 90 try { 91 sService.dataChanged(mContext.getPackageName()); 92 } catch (RemoteException e) { 93 Log.d(TAG, "dataChanged() couldn't connect"); 94 } 95 } 96 } 97 98 /** 99 * Convenience method for callers who need to indicate that some other package 100 * needs a backup pass. This can be relevant in the case of groups of packages 101 * that share a uid, for example. 102 * 103 * This method requires that the application hold the "android.permission.BACKUP" 104 * permission if the package named in the argument is not the caller's own. 105 */ 106 public static void dataChanged(String packageName) { 107 checkServiceBinder(); 108 if (sService != null) { 109 try { 110 sService.dataChanged(packageName); 111 } catch (RemoteException e) { 112 Log.d(TAG, "dataChanged(pkg) couldn't connect"); 113 } 114 } 115 } 116 117 /** 118 * Begin the process of restoring data from backup. See the 119 * {@link android.app.backup.RestoreSession} class for documentation on that process. 120 */ 121 public RestoreSession beginRestoreSession() { 122 RestoreSession session = null; 123 checkServiceBinder(); 124 if (sService != null) { 125 try { 126 String transport = sService.getCurrentTransport(); 127 IRestoreSession binder = sService.beginRestoreSession(transport); 128 session = new RestoreSession(mContext, binder); 129 } catch (RemoteException e) { 130 Log.w(TAG, "beginRestoreSession() couldn't connect"); 131 } 132 } 133 return session; 134 } 135} 136