FileDocCategorySizeDatePackage
BackupDataOutput.javaAPI DocAndroid 5.1 API5665Thu Mar 12 22:22:10 GMT 2015android.app.backup

BackupDataOutput

public class BackupDataOutput extends Object
Provides the structured interface through which a {@link BackupAgent} commits information to the backup data set, via its {@link BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) onBackup()} method. Data written for backup is presented as a set of "entities," key/value pairs in which each binary data record "value" is named with a string "key."

To commit a data record to the backup transport, the agent's {@link BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) onBackup()} method first writes an "entity header" that supplies the key string for the record and the total size of the binary value for the record. After the header has been written, the agent then writes the binary entity value itself. The entity value can be written in multiple chunks if desired, as long as the total count of bytes written matches what was supplied to {@link #writeEntityHeader(String, int) writeEntityHeader()}.

Entity key strings are considered to be unique within a given application's backup data set. If a backup agent writes a new entity under an existing key string, its value will replace any previous value in the transport's remote data store. You can remove a record entirely from the remote data set by writing a new entity header using the existing record's key, but supplying a negative dataSize parameter. When you do so, the agent does not need to call {@link #writeEntityData(byte[], int)}.

Example

Here is an example illustrating a way to back up the value of a String variable called mStringToBackUp: 

static final String MY_STRING_KEY = "storedstring";

public void {@link BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) onBackup(ParcelFileDescriptor oldState, BackupDataOutput data, ParcelFileDescriptor newState)}
throws IOException {
...
byte[] stringBytes = mStringToBackUp.getBytes();
data.writeEntityHeader(MY_STRING_KEY, stringBytes.length);
data.writeEntityData(stringBytes, stringBytes.length);
...
}
see
BackupAgent

Fields Summary
long
mBackupWriter
Constructors Summary
public BackupDataOutput(FileDescriptor fd)

hide

        if (fd == null) throw new NullPointerException();
        mBackupWriter = ctor(fd);
        if (mBackupWriter == 0) {
            throw new RuntimeException("Native initialization failed with fd=" + fd);
        }
Methods Summary
private static native longctor(java.io.FileDescriptor fd)

private static native voiddtor(long mBackupWriter)
protected voidfinalize()
hide
        try {
            dtor(mBackupWriter);
        } finally {
            super.finalize();
        }
    
public voidsetKeyPrefix(java.lang.String keyPrefix)
hide
        setKeyPrefix_native(mBackupWriter, keyPrefix);
    
private static native voidsetKeyPrefix_native(long mBackupWriter, java.lang.String keyPrefix)
public intwriteEntityData(byte[] data, int size)
Write a chunk of data under the current entity to the backup transport.
param
data A raw data buffer to send
param
size The number of bytes to be sent in this chunk
return
the number of bytes written
throws
IOException if the write failed
        int result = writeEntityData_native(mBackupWriter, data, size);
        if (result >= 0) {
            return result;
        } else {
            throw new IOException("result=0x" + Integer.toHexString(result));
        }
    
private static native intwriteEntityData_native(long mBackupWriter, byte[] data, int size)
public intwriteEntityHeader(java.lang.String key, int dataSize)
Mark the beginning of one record in the backup data stream. This must be called before
{@link #writeEntityData}.
param
key A string key that uniquely identifies the data record within the application.
Keys whose first character is \uFF00 or higher are not valid.
param
dataSize The size in bytes of this record's data. Passing a dataSize
of -1 indicates that the record under this key should be deleted.
return
The number of bytes written to the backup stream
throws
IOException if the write failed
        int result = writeEntityHeader_native(mBackupWriter, key, dataSize);
        if (result >= 0) {
            return result;
        } else {
            throw new IOException("result=0x" + Integer.toHexString(result));
        }
    
private static native intwriteEntityHeader_native(long mBackupWriter, java.lang.String key, int dataSize)