Joe Onorato | b1a7ffe | 2009-05-06 18:06:21 -0700 | [diff] [blame] | 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 | |
Christopher Tate | 4528186 | 2010-03-05 15:46:30 -0800 | [diff] [blame] | 17 | package android.app.backup; |
Joe Onorato | b1a7ffe | 2009-05-06 18:06:21 -0700 | [diff] [blame] | 18 | |
arete | ff31add | 2014-08-18 11:50:51 -0700 | [diff] [blame] | 19 | import android.annotation.SystemApi; |
Christopher Tate | 4e14a82 | 2010-04-08 12:54:23 -0700 | [diff] [blame] | 20 | import android.os.ParcelFileDescriptor; |
Joe Onorato | b1a7ffe | 2009-05-06 18:06:21 -0700 | [diff] [blame] | 21 | import java.io.FileDescriptor; |
Joe Onorato | 1cf5874 | 2009-06-12 11:06:24 -0700 | [diff] [blame] | 22 | import java.io.IOException; |
Joe Onorato | b1a7ffe | 2009-05-06 18:06:21 -0700 | [diff] [blame] | 23 | |
Christopher Tate | e28290e | 2010-02-16 15:22:26 -0800 | [diff] [blame] | 24 | /** |
Scott Main | d17da43 | 2010-04-29 21:42:58 -0700 | [diff] [blame] | 25 | * Provides the structured interface through which a {@link BackupAgent} commits |
| 26 | * information to the backup data set, via its {@link |
| 27 | * BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) |
| 28 | * onBackup()} method. Data written for backup is presented |
Christopher Tate | 4e14a82 | 2010-04-08 12:54:23 -0700 | [diff] [blame] | 29 | * as a set of "entities," key/value pairs in which each binary data record "value" is |
| 30 | * named with a string "key." |
| 31 | * <p> |
| 32 | * To commit a data record to the backup transport, the agent's |
Scott Main | d17da43 | 2010-04-29 21:42:58 -0700 | [diff] [blame] | 33 | * {@link BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) |
| 34 | * onBackup()} method first writes an "entity header" that supplies the key string for the record |
Christopher Tate | 4e14a82 | 2010-04-08 12:54:23 -0700 | [diff] [blame] | 35 | * and the total size of the binary value for the record. After the header has been |
Scott Main | d17da43 | 2010-04-29 21:42:58 -0700 | [diff] [blame] | 36 | * written, the agent then writes the binary entity value itself. The entity value can |
Christopher Tate | 4e14a82 | 2010-04-08 12:54:23 -0700 | [diff] [blame] | 37 | * be written in multiple chunks if desired, as long as the total count of bytes written |
Scott Main | d17da43 | 2010-04-29 21:42:58 -0700 | [diff] [blame] | 38 | * matches what was supplied to {@link #writeEntityHeader(String, int) writeEntityHeader()}. |
Christopher Tate | 4e14a82 | 2010-04-08 12:54:23 -0700 | [diff] [blame] | 39 | * <p> |
| 40 | * Entity key strings are considered to be unique within a given application's backup |
Scott Main | d17da43 | 2010-04-29 21:42:58 -0700 | [diff] [blame] | 41 | * data set. If a backup agent writes a new entity under an existing key string, its value will |
| 42 | * replace any previous value in the transport's remote data store. You can remove a record |
| 43 | * entirely from the remote data set by writing a new entity header using the |
Christopher Tate | 4e14a82 | 2010-04-08 12:54:23 -0700 | [diff] [blame] | 44 | * existing record's key, but supplying a negative <code>dataSize</code> parameter. |
Scott Main | d17da43 | 2010-04-29 21:42:58 -0700 | [diff] [blame] | 45 | * When you do so, the agent does not need to call {@link #writeEntityData(byte[], int)}. |
| 46 | * <h3>Example</h3> |
Christopher Tate | 4e14a82 | 2010-04-08 12:54:23 -0700 | [diff] [blame] | 47 | * <p> |
| 48 | * Here is an example illustrating a way to back up the value of a String variable |
| 49 | * called <code>mStringToBackUp</code>: |
| 50 | * <pre> |
| 51 | * static final String MY_STRING_KEY = "storedstring"; |
| 52 | * |
| 53 | * public void {@link BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) onBackup(ParcelFileDescriptor oldState, BackupDataOutput data, ParcelFileDescriptor newState)} |
| 54 | * throws IOException { |
| 55 | * ... |
| 56 | * byte[] stringBytes = mStringToBackUp.getBytes(); |
| 57 | * data.writeEntityHeader(MY_STRING_KEY, stringBytes.length); |
| 58 | * data.writeEntityData(stringBytes, stringBytes.length); |
| 59 | * ... |
| 60 | * }</pre> |
| 61 | * |
| 62 | * @see BackupAgent |
Christopher Tate | e28290e | 2010-02-16 15:22:26 -0800 | [diff] [blame] | 63 | */ |
Joe Onorato | b1a7ffe | 2009-05-06 18:06:21 -0700 | [diff] [blame] | 64 | public class BackupDataOutput { |
Christopher Tate | ee87b96 | 2017-04-26 17:07:27 -0700 | [diff] [blame] | 65 | final long mQuota; |
Ashok Bhat | 58b8b24 | 2014-01-02 16:52:41 +0000 | [diff] [blame] | 66 | long mBackupWriter; |
Joe Onorato | b1a7ffe | 2009-05-06 18:06:21 -0700 | [diff] [blame] | 67 | |
Christopher Tate | ee87b96 | 2017-04-26 17:07:27 -0700 | [diff] [blame] | 68 | /** |
| 69 | * Construct a BackupDataOutput purely for data-stream manipulation. This instance will |
| 70 | * not report usable quota information. |
| 71 | * @hide */ |
| 72 | @SystemApi |
| 73 | public BackupDataOutput(FileDescriptor fd) { |
| 74 | this(fd, -1); |
| 75 | } |
| 76 | |
Christopher Tate | e28290e | 2010-02-16 15:22:26 -0800 | [diff] [blame] | 77 | /** @hide */ |
arete | ff31add | 2014-08-18 11:50:51 -0700 | [diff] [blame] | 78 | @SystemApi |
Christopher Tate | ee87b96 | 2017-04-26 17:07:27 -0700 | [diff] [blame] | 79 | public BackupDataOutput(FileDescriptor fd, long quota) { |
Joe Onorato | d2110db | 2009-05-19 13:41:21 -0700 | [diff] [blame] | 80 | if (fd == null) throw new NullPointerException(); |
Christopher Tate | ee87b96 | 2017-04-26 17:07:27 -0700 | [diff] [blame] | 81 | mQuota = quota; |
Joe Onorato | d2110db | 2009-05-19 13:41:21 -0700 | [diff] [blame] | 82 | mBackupWriter = ctor(fd); |
| 83 | if (mBackupWriter == 0) { |
| 84 | throw new RuntimeException("Native initialization failed with fd=" + fd); |
| 85 | } |
Joe Onorato | b1a7ffe | 2009-05-06 18:06:21 -0700 | [diff] [blame] | 86 | } |
| 87 | |
Christopher Tate | e28290e | 2010-02-16 15:22:26 -0800 | [diff] [blame] | 88 | /** |
Christopher Tate | ee87b96 | 2017-04-26 17:07:27 -0700 | [diff] [blame] | 89 | * Returns the quota in bytes for the application's current backup operation. The |
| 90 | * value can vary for each operation. |
| 91 | * |
| 92 | * @see FullBackupDataOutput#getQuota() |
| 93 | */ |
| 94 | public long getQuota() { |
| 95 | return mQuota; |
| 96 | } |
| 97 | |
| 98 | /** |
Scott Main | d17da43 | 2010-04-29 21:42:58 -0700 | [diff] [blame] | 99 | * Mark the beginning of one record in the backup data stream. This must be called before |
| 100 | * {@link #writeEntityData}. |
Christopher Tate | adfe8b8 | 2014-02-04 16:23:32 -0800 | [diff] [blame] | 101 | * @param key A string key that uniquely identifies the data record within the application. |
| 102 | * Keys whose first character is \uFF00 or higher are not valid. |
Christopher Tate | e28290e | 2010-02-16 15:22:26 -0800 | [diff] [blame] | 103 | * @param dataSize The size in bytes of this record's data. Passing a dataSize |
| 104 | * of -1 indicates that the record under this key should be deleted. |
| 105 | * @return The number of bytes written to the backup stream |
| 106 | * @throws IOException if the write failed |
| 107 | */ |
Joe Onorato | 1cf5874 | 2009-06-12 11:06:24 -0700 | [diff] [blame] | 108 | public int writeEntityHeader(String key, int dataSize) throws IOException { |
| 109 | int result = writeEntityHeader_native(mBackupWriter, key, dataSize); |
| 110 | if (result >= 0) { |
| 111 | return result; |
| 112 | } else { |
| 113 | throw new IOException("result=0x" + Integer.toHexString(result)); |
| 114 | } |
| 115 | } |
| 116 | |
Christopher Tate | e28290e | 2010-02-16 15:22:26 -0800 | [diff] [blame] | 117 | /** |
| 118 | * Write a chunk of data under the current entity to the backup transport. |
| 119 | * @param data A raw data buffer to send |
| 120 | * @param size The number of bytes to be sent in this chunk |
| 121 | * @return the number of bytes written |
| 122 | * @throws IOException if the write failed |
| 123 | */ |
Joe Onorato | 1cf5874 | 2009-06-12 11:06:24 -0700 | [diff] [blame] | 124 | public int writeEntityData(byte[] data, int size) throws IOException { |
| 125 | int result = writeEntityData_native(mBackupWriter, data, size); |
| 126 | if (result >= 0) { |
| 127 | return result; |
| 128 | } else { |
| 129 | throw new IOException("result=0x" + Integer.toHexString(result)); |
| 130 | } |
| 131 | } |
| 132 | |
Christopher Tate | fc922f11 | 2010-04-09 13:05:16 -0700 | [diff] [blame] | 133 | /** @hide */ |
Joe Onorato | 06290a4 | 2009-06-18 20:10:37 -0700 | [diff] [blame] | 134 | public void setKeyPrefix(String keyPrefix) { |
| 135 | setKeyPrefix_native(mBackupWriter, keyPrefix); |
| 136 | } |
| 137 | |
Christopher Tate | e28290e | 2010-02-16 15:22:26 -0800 | [diff] [blame] | 138 | /** @hide */ |
arete | ff31add | 2014-08-18 11:50:51 -0700 | [diff] [blame] | 139 | @Override |
Joe Onorato | d2110db | 2009-05-19 13:41:21 -0700 | [diff] [blame] | 140 | protected void finalize() throws Throwable { |
| 141 | try { |
| 142 | dtor(mBackupWriter); |
| 143 | } finally { |
| 144 | super.finalize(); |
| 145 | } |
Joe Onorato | b1a7ffe | 2009-05-06 18:06:21 -0700 | [diff] [blame] | 146 | } |
Joe Onorato | 06290a4 | 2009-06-18 20:10:37 -0700 | [diff] [blame] | 147 | |
Ashok Bhat | 58b8b24 | 2014-01-02 16:52:41 +0000 | [diff] [blame] | 148 | private native static long ctor(FileDescriptor fd); |
| 149 | private native static void dtor(long mBackupWriter); |
Joe Onorato | 1cf5874 | 2009-06-12 11:06:24 -0700 | [diff] [blame] | 150 | |
Ashok Bhat | 58b8b24 | 2014-01-02 16:52:41 +0000 | [diff] [blame] | 151 | private native static int writeEntityHeader_native(long mBackupWriter, String key, int dataSize); |
| 152 | private native static int writeEntityData_native(long mBackupWriter, byte[] data, int size); |
| 153 | private native static void setKeyPrefix_native(long mBackupWriter, String keyPrefix); |
Joe Onorato | b1a7ffe | 2009-05-06 18:06:21 -0700 | [diff] [blame] | 154 | } |
| 155 | |