Most visited

Recently visited

Added in API level 1

Parcel

public final class Parcel
extends Object

java.lang.Object
   ↳ android.os.Parcel


Container for a message (data and object references) that can be sent through an IBinder. A Parcel can contain both flattened data that will be unflattened on the other side of the IPC (using the various methods here for writing specific types, or the general Parcelable interface), and references to live IBinder objects that will result in the other side receiving a proxy IBinder connected with the original IBinder in the Parcel.

Parcel is not a general-purpose serialization mechanism. This class (and the corresponding Parcelable API for placing arbitrary objects into a Parcel) is designed as a high-performance IPC transport. As such, it is not appropriate to place any Parcel data in to persistent storage: changes in the underlying implementation of any of the data in the Parcel can render older data unreadable.

The bulk of the Parcel API revolves around reading and writing data of various types. There are six major classes of such functions available.

Primitives

The most basic data functions are for writing and reading primitive data types: writeByte(byte), readByte(), writeDouble(double), readDouble(), writeFloat(float), readFloat(), writeInt(int), readInt(), writeLong(long), readLong(), writeString(String), readString(). Most other data operations are built on top of these. The given data is written and read using the endianess of the host CPU.

Primitive Arrays

There are a variety of methods for reading and writing raw arrays of primitive objects, which generally result in writing a 4-byte length followed by the primitive data items. The methods for reading can either read the data into an existing array, or create and return a new array. These available types are:

Parcelables

The Parcelable protocol provides an extremely efficient (but low-level) protocol for objects to write and read themselves from Parcels. You can use the direct methods writeParcelable(Parcelable, int) and readParcelable(ClassLoader) or writeParcelableArray(T[], int) and readParcelableArray(ClassLoader) to write or read. These methods write both the class type and its data to the Parcel, allowing that class to be reconstructed from the appropriate class loader when later reading.

There are also some methods that provide a more efficient way to work with Parcelables: writeTypedObject(T, int), writeTypedArray(T[], int), writeTypedList(List), readTypedObject(Parcelable.Creator), createTypedArray(Parcelable.Creator) and createTypedArrayList(Parcelable.Creator). These methods do not write the class information of the original object: instead, the caller of the read function must know what type to expect and pass in the appropriate Parcelable.Creator instead to properly construct the new object and read its data. (To more efficient write and read a single Parceable object that is not null, you can directly call Parcelable.writeToParcel and Parcelable.Creator.createFromParcel yourself.)

Bundles

A special type-safe container, called Bundle, is available for key/value maps of heterogeneous values. This has many optimizations for improved performance when reading and writing data, and its type-safe API avoids difficult to debug type errors when finally marshalling the data contents into a Parcel. The methods to use are writeBundle(Bundle), readBundle(), and readBundle(ClassLoader).

Active Objects

An unusual feature of Parcel is the ability to read and write active objects. For these objects the actual contents of the object is not written, rather a special token referencing the object is written. When reading the object back from the Parcel, you do not get a new instance of the object, but rather a handle that operates on the exact same object that was originally written. There are two forms of active objects available.

Binder objects are a core facility of Android's general cross-process communication system. The IBinder interface describes an abstract protocol with a Binder object. Any such interface can be written in to a Parcel, and upon reading you will receive either the original object implementing that interface or a special proxy implementation that communicates calls back to the original object. The methods to use are writeStrongBinder(IBinder), writeStrongInterface(IInterface), readStrongBinder(), writeBinderArray(IBinder[]), readBinderArray(IBinder[]), createBinderArray(), writeBinderList(List), readBinderList(List), createBinderArrayList().

FileDescriptor objects, representing raw Linux file descriptor identifiers, can be written and ParcelFileDescriptor objects returned to operate on the original file descriptor. The returned file descriptor is a dup of the original file descriptor: the object and fd is different, but operating on the same underlying file stream, with the same position, etc. The methods to use are writeFileDescriptor(FileDescriptor), readFileDescriptor().

Untyped Containers

A final class of methods are for writing and reading standard Java containers of arbitrary types. These all revolve around the writeValue(Object) and readValue(ClassLoader) methods which define the types of objects allowed. The container methods are writeArray(Object[]), readArray(ClassLoader), writeList(List), readList(List, ClassLoader), readArrayList(ClassLoader), writeMap(Map), readMap(Map, ClassLoader), writeSparseArray(SparseArray), readSparseArray(ClassLoader).

Summary

Fields

public static final Creator<String> STRING_CREATOR

Public methods

final void appendFrom(Parcel parcel, int offset, int length)
final IBinder[] createBinderArray()
final ArrayList<IBinder> createBinderArrayList()

Read and return a new ArrayList containing IBinder objects from the parcel that was written with writeBinderList(List) at the current dataPosition().

final boolean[] createBooleanArray()
final byte[] createByteArray()

Read and return a byte[] object from the parcel.

final char[] createCharArray()
final double[] createDoubleArray()
final float[] createFloatArray()
final int[] createIntArray()
final long[] createLongArray()
final String[] createStringArray()
final ArrayList<String> createStringArrayList()

Read and return a new ArrayList containing String objects from the parcel that was written with writeStringList(List) at the current dataPosition().

final <T> T[] createTypedArray(Creator<T> c)

Read and return a new array containing a particular object type from the parcel at the current dataPosition().

final <T> ArrayList<T> createTypedArrayList(Creator<T> c)

Read and return a new ArrayList containing a particular object type from the parcel that was written with writeTypedList(List) at the current dataPosition().

final int dataAvail()

Returns the amount of data remaining to be read from the parcel.

final int dataCapacity()

Returns the total amount of space in the parcel.

final int dataPosition()

Returns the current position in the parcel data.

final int dataSize()

Returns the total amount of data contained in the parcel.

final void enforceInterface(String interfaceName)
final boolean hasFileDescriptors()

Report whether the parcel contains any marshalled file descriptors.

final byte[] marshall()

Returns the raw bytes of the parcel.

static Parcel obtain()

Retrieve a new Parcel object from the pool.

final Object[] readArray(ClassLoader loader)

Read and return a new Object array from the parcel at the current dataPosition().

final ArrayList readArrayList(ClassLoader loader)

Read and return a new ArrayList object from the parcel at the current dataPosition().

final void readBinderArray(IBinder[] val)
final void readBinderList(List<IBinder> list)

Read into the given List items IBinder objects that were written with writeBinderList(List) at the current dataPosition().

final void readBooleanArray(boolean[] val)
final Bundle readBundle()

Read and return a new Bundle object from the parcel at the current dataPosition().

final Bundle readBundle(ClassLoader loader)

Read and return a new Bundle object from the parcel at the current dataPosition(), using the given class loader to initialize the class loader of the Bundle for later retrieval of Parcelable objects.

final byte readByte()

Read a byte value from the parcel at the current dataPosition().

final void readByteArray(byte[] val)

Read a byte[] object from the parcel and copy it into the given byte array.

final void readCharArray(char[] val)
final double readDouble()

Read a double precision floating point value from the parcel at the current dataPosition().

final void readDoubleArray(double[] val)
final void readException()

Special function for reading an exception result from the header of a parcel, to be used after receiving the result of a transaction.

final void readException(int code, String msg)

Throw an exception with the given message.

final ParcelFileDescriptor readFileDescriptor()

Read a FileDescriptor from the parcel at the current dataPosition().

final float readFloat()

Read a floating point value from the parcel at the current dataPosition().

final void readFloatArray(float[] val)
final HashMap readHashMap(ClassLoader loader)

Please use readBundle(ClassLoader) instead (whose data must have been written with writeBundle(Bundle).

final int readInt()

Read an integer value from the parcel at the current dataPosition().

final void readIntArray(int[] val)
final void readList(List outVal, ClassLoader loader)

Read into an existing List object from the parcel at the current dataPosition(), using the given class loader to load any enclosed Parcelables.

final long readLong()

Read a long integer value from the parcel at the current dataPosition().

final void readLongArray(long[] val)
final void readMap(Map outVal, ClassLoader loader)

Please use readBundle(ClassLoader) instead (whose data must have been written with writeBundle(Bundle).

final <T extends Parcelable> T readParcelable(ClassLoader loader)

Read and return a new Parcelable from the parcel.

final Parcelable[] readParcelableArray(ClassLoader loader)

Read and return a new Parcelable array from the parcel.

final PersistableBundle readPersistableBundle()

Read and return a new Bundle object from the parcel at the current dataPosition().

final PersistableBundle readPersistableBundle(ClassLoader loader)

Read and return a new Bundle object from the parcel at the current dataPosition(), using the given class loader to initialize the class loader of the Bundle for later retrieval of Parcelable objects.

final Serializable readSerializable()

Read and return a new Serializable object from the parcel.

final Size readSize()

Read a Size from the parcel at the current dataPosition().

final SizeF readSizeF()

Read a SizeF from the parcel at the current dataPosition().

final SparseArray readSparseArray(ClassLoader loader)

Read and return a new SparseArray object from the parcel at the current dataPosition().

final SparseBooleanArray readSparseBooleanArray()

Read and return a new SparseBooleanArray object from the parcel at the current dataPosition().

final String readString()

Read a string value from the parcel at the current dataPosition().

final void readStringArray(String[] val)
final void readStringList(List<String> list)

Read into the given List items String objects that were written with writeStringList(List) at the current dataPosition().

final IBinder readStrongBinder()

Read an object from the parcel at the current dataPosition().

final <T> void readTypedArray(T[] val, Creator<T> c)
final <T> void readTypedList(List<T> list, Creator<T> c)

Read into the given List items containing a particular object type that were written with writeTypedList(List) at the current dataPosition().

final <T> T readTypedObject(Creator<T> c)

Read and return a typed Parcelable object from a parcel.

final Object readValue(ClassLoader loader)

Read a typed object from a parcel.

final void recycle()

Put a Parcel object back into the pool.

final void setDataCapacity(int size)

Change the capacity (current available space) of the parcel.

final void setDataPosition(int pos)

Move the current read/write position in the parcel.

final void setDataSize(int size)

Change the amount of data in the parcel.

final void unmarshall(byte[] data, int offset, int length)

Set the bytes in data to be the raw bytes of this Parcel.

final void writeArray(Object[] val)

Flatten an Object array into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeBinderArray(IBinder[] val)
final void writeBinderList(List<IBinder> val)

Flatten a List containing IBinder objects into the parcel, at the current dataPosition() and growing dataCapacity() if needed.

final void writeBooleanArray(boolean[] val)
final void writeBundle(Bundle val)

Flatten a Bundle into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeByte(byte val)

Write a byte value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeByteArray(byte[] b)

Write a byte array into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeByteArray(byte[] b, int offset, int len)

Write a byte array into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeCharArray(char[] val)
final void writeDouble(double val)

Write a double precision floating point value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeDoubleArray(double[] val)
final void writeException(Exception e)

Special function for writing an exception result at the header of a parcel, to be used when returning an exception from a transaction.

final void writeFileDescriptor(FileDescriptor val)

Write a FileDescriptor into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeFloat(float val)

Write a floating point value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeFloatArray(float[] val)
final void writeInt(int val)

Write an integer value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeIntArray(int[] val)
final void writeInterfaceToken(String interfaceName)

Store or read an IBinder interface token in the parcel at the current dataPosition().

final void writeList(List val)

Flatten a List into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeLong(long val)

Write a long integer value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeLongArray(long[] val)
final void writeMap(Map val)

Please use writeBundle(Bundle) instead.

final void writeNoException()

Special function for writing information at the front of the Parcel indicating that no exception occurred.

final void writeParcelable(Parcelable p, int parcelableFlags)

Flatten the name of the class of the Parcelable and its contents into the parcel.

final <T extends Parcelable> void writeParcelableArray(T[] value, int parcelableFlags)

Write a heterogeneous array of Parcelable objects into the Parcel.

final void writePersistableBundle(PersistableBundle val)

Flatten a PersistableBundle into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeSerializable(Serializable s)

Write a generic serializable object in to a Parcel.

final void writeSize(Size val)

Flatten a Size into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeSizeF(SizeF val)

Flatten a SizeF into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeSparseArray(SparseArray<Object> val)

Flatten a generic SparseArray into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeSparseBooleanArray(SparseBooleanArray val)
final void writeString(String val)

Write a string value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeStringArray(String[] val)
final void writeStringList(List<String> val)

Flatten a List containing String objects into the parcel, at the current dataPosition() and growing dataCapacity() if needed.

final void writeStrongBinder(IBinder val)

Write an object into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final void writeStrongInterface(IInterface val)

Write an object into the parcel at the current dataPosition(), growing dataCapacity() if needed.

final <T extends Parcelable> void writeTypedArray(T[] val, int parcelableFlags)

Flatten a heterogeneous array containing a particular object type into the parcel, at the current dataPosition() and growing dataCapacity() if needed.

final <T extends Parcelable> void writeTypedList(List<T> val)

Flatten a List containing a particular object type into the parcel, at the current dataPosition() and growing dataCapacity() if needed.

final <T extends Parcelable> void writeTypedObject(T val, int parcelableFlags)

Flatten the Parcelable object into the parcel.

final void writeValue(Object v)

Flatten a generic object in to a parcel.

Protected methods

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Inherited methods

From class java.lang.Object

Fields

STRING_CREATOR

Added in API level 1
Creator<String> STRING_CREATOR

Public methods

appendFrom

Added in API level 1
void appendFrom (Parcel parcel, 
                int offset, 
                int length)

Parameters
parcel Parcel
offset int
length int

createBinderArray

Added in API level 1
IBinder[] createBinderArray ()

Returns
IBinder[]

createBinderArrayList

Added in API level 1
ArrayList<IBinder> createBinderArrayList ()

Read and return a new ArrayList containing IBinder objects from the parcel that was written with writeBinderList(List) at the current dataPosition(). Returns null if the previously written list object was null.

Returns
ArrayList<IBinder> A newly created ArrayList containing strings with the same data as those that were previously written.

See also:

createBooleanArray

Added in API level 1
boolean[] createBooleanArray ()

Returns
boolean[]

createByteArray

Added in API level 1
byte[] createByteArray ()

Read and return a byte[] object from the parcel.

Returns
byte[]

createCharArray

Added in API level 1
char[] createCharArray ()

Returns
char[]

createDoubleArray

Added in API level 1
double[] createDoubleArray ()

Returns
double[]

createFloatArray

Added in API level 1
float[] createFloatArray ()

Returns
float[]

createIntArray

Added in API level 1
int[] createIntArray ()

Returns
int[]

createLongArray

Added in API level 1
long[] createLongArray ()

Returns
long[]

createStringArray

Added in API level 1
String[] createStringArray ()

Returns
String[]

createStringArrayList

Added in API level 1
ArrayList<String> createStringArrayList ()

Read and return a new ArrayList containing String objects from the parcel that was written with writeStringList(List) at the current dataPosition(). Returns null if the previously written list object was null.

Returns
ArrayList<String> A newly created ArrayList containing strings with the same data as those that were previously written.

See also:

createTypedArray

Added in API level 1
T[] createTypedArray (Creator<T> c)

Read and return a new array containing a particular object type from the parcel at the current dataPosition(). Returns null if the previously written array was null. The array must have previously been written via writeTypedArray(T[], int) with the same object type.

Parameters
c Creator
Returns
T[] A newly created array containing objects with the same data as those that were previously written.

See also:

createTypedArrayList

Added in API level 1
ArrayList<T> createTypedArrayList (Creator<T> c)

Read and return a new ArrayList containing a particular object type from the parcel that was written with writeTypedList(List) at the current dataPosition(). Returns null if the previously written list object was null. The list must have previously been written via writeTypedList(List) with the same object type.

Parameters
c Creator
Returns
ArrayList<T> A newly created ArrayList containing objects with the same data as those that were previously written.

See also:

dataAvail

Added in API level 1
int dataAvail ()

Returns the amount of data remaining to be read from the parcel. That is, dataSize()-dataPosition().

Returns
int

dataCapacity

Added in API level 1
int dataCapacity ()

Returns the total amount of space in the parcel. This is always >= dataSize(). The difference between it and dataSize() is the amount of room left until the parcel needs to re-allocate its data buffer.

Returns
int

dataPosition

Added in API level 1
int dataPosition ()

Returns the current position in the parcel data. Never more than dataSize().

Returns
int

dataSize

Added in API level 1
int dataSize ()

Returns the total amount of data contained in the parcel.

Returns
int

enforceInterface

Added in API level 1
void enforceInterface (String interfaceName)

Parameters
interfaceName String

hasFileDescriptors

Added in API level 1
boolean hasFileDescriptors ()

Report whether the parcel contains any marshalled file descriptors.

Returns
boolean

marshall

Added in API level 1
byte[] marshall ()

Returns the raw bytes of the parcel.

The data you retrieve here must not be placed in any kind of persistent storage (on local disk, across a network, etc). For that, you should use standard serialization or another kind of general serialization mechanism. The Parcel marshalled representation is highly optimized for local IPC, and as such does not attempt to maintain compatibility with data created in different versions of the platform.

Returns
byte[]

obtain

Added in API level 1
Parcel obtain ()

Retrieve a new Parcel object from the pool.

Returns
Parcel

readArray

Added in API level 1
Object[] readArray (ClassLoader loader)

Read and return a new Object array from the parcel at the current dataPosition(). Returns null if the previously written array was null. The given class loader will be used to load any enclosed Parcelables.

Parameters
loader ClassLoader
Returns
Object[]

readArrayList

Added in API level 1
ArrayList readArrayList (ClassLoader loader)

Read and return a new ArrayList object from the parcel at the current dataPosition(). Returns null if the previously written list object was null. The given class loader will be used to load any enclosed Parcelables.

Parameters
loader ClassLoader
Returns
ArrayList

readBinderArray

Added in API level 1
void readBinderArray (IBinder[] val)

Parameters
val IBinder

readBinderList

Added in API level 1
void readBinderList (List<IBinder> list)

Read into the given List items IBinder objects that were written with writeBinderList(List) at the current dataPosition().

Parameters
list List
Returns
void A newly created ArrayList containing strings with the same data as those that were previously written.

See also:

readBooleanArray

Added in API level 1
void readBooleanArray (boolean[] val)

Parameters
val boolean

readBundle

Added in API level 1
Bundle readBundle ()

Read and return a new Bundle object from the parcel at the current dataPosition(). Returns null if the previously written Bundle object was null.

Returns
Bundle

readBundle

Added in API level 1
Bundle readBundle (ClassLoader loader)

Read and return a new Bundle object from the parcel at the current dataPosition(), using the given class loader to initialize the class loader of the Bundle for later retrieval of Parcelable objects. Returns null if the previously written Bundle object was null.

Parameters
loader ClassLoader
Returns
Bundle

readByte

Added in API level 1
byte readByte ()

Read a byte value from the parcel at the current dataPosition().

Returns
byte

readByteArray

Added in API level 1
void readByteArray (byte[] val)

Read a byte[] object from the parcel and copy it into the given byte array.

Parameters
val byte

readCharArray

Added in API level 1
void readCharArray (char[] val)

Parameters
val char

readDouble

Added in API level 1
double readDouble ()

Read a double precision floating point value from the parcel at the current dataPosition().

Returns
double

readDoubleArray

Added in API level 1
void readDoubleArray (double[] val)

Parameters
val double

readException

Added in API level 1
void readException ()

Special function for reading an exception result from the header of a parcel, to be used after receiving the result of a transaction. This will throw the exception for you if it had been written to the Parcel, otherwise return and let you read the normal result data from the Parcel.

See also:

readException

Added in API level 1
void readException (int code, 
                String msg)

Throw an exception with the given message. Not intended for use outside the Parcel class.

Parameters
code int: Used to determine which exception class to throw.
msg String: The exception message.

readFileDescriptor

Added in API level 1
ParcelFileDescriptor readFileDescriptor ()

Read a FileDescriptor from the parcel at the current dataPosition().

Returns
ParcelFileDescriptor

readFloat

Added in API level 1
float readFloat ()

Read a floating point value from the parcel at the current dataPosition().

Returns
float

readFloatArray

Added in API level 1
void readFloatArray (float[] val)

Parameters
val float

readHashMap

Added in API level 1
HashMap readHashMap (ClassLoader loader)

Please use readBundle(ClassLoader) instead (whose data must have been written with writeBundle(Bundle). Read and return a new HashMap object from the parcel at the current dataPosition(), using the given class loader to load any enclosed Parcelables. Returns null if the previously written map object was null.

Parameters
loader ClassLoader
Returns
HashMap

readInt

Added in API level 1
int readInt ()

Read an integer value from the parcel at the current dataPosition().

Returns
int

readIntArray

Added in API level 1
void readIntArray (int[] val)

Parameters
val int

readList

Added in API level 1
void readList (List outVal, 
                ClassLoader loader)

Read into an existing List object from the parcel at the current dataPosition(), using the given class loader to load any enclosed Parcelables. If it is null, the default class loader is used.

Parameters
outVal List
loader ClassLoader

readLong

Added in API level 1
long readLong ()

Read a long integer value from the parcel at the current dataPosition().

Returns
long

readLongArray

Added in API level 1
void readLongArray (long[] val)

Parameters
val long

readMap

Added in API level 1
void readMap (Map outVal, 
                ClassLoader loader)

Please use readBundle(ClassLoader) instead (whose data must have been written with writeBundle(Bundle). Read into an existing Map object from the parcel at the current dataPosition().

Parameters
outVal Map
loader ClassLoader

readParcelable

Added in API level 1
T readParcelable (ClassLoader loader)

Read and return a new Parcelable from the parcel. The given class loader will be used to load any enclosed Parcelables. If it is null, the default class loader will be used.

Parameters
loader ClassLoader: A ClassLoader from which to instantiate the Parcelable object, or null for the default class loader.
Returns
T Returns the newly created Parcelable, or null if a null object has been written.
Throws
BadParcelableException Throws BadParcelableException if there was an error trying to instantiate the Parcelable.

readParcelableArray

Added in API level 1
Parcelable[] readParcelableArray (ClassLoader loader)

Read and return a new Parcelable array from the parcel. The given class loader will be used to load any enclosed Parcelables.

Parameters
loader ClassLoader
Returns
Parcelable[] the Parcelable array, or null if the array is null

readPersistableBundle

Added in API level 21
PersistableBundle readPersistableBundle ()

Read and return a new Bundle object from the parcel at the current dataPosition(). Returns null if the previously written Bundle object was null.

Returns
PersistableBundle

readPersistableBundle

Added in API level 21
PersistableBundle readPersistableBundle (ClassLoader loader)

Read and return a new Bundle object from the parcel at the current dataPosition(), using the given class loader to initialize the class loader of the Bundle for later retrieval of Parcelable objects. Returns null if the previously written Bundle object was null.

Parameters
loader ClassLoader
Returns
PersistableBundle

readSerializable

Added in API level 1
Serializable readSerializable ()

Read and return a new Serializable object from the parcel.

Returns
Serializable the Serializable object, or null if the Serializable name wasn't found in the parcel.

readSize

Added in API level 21
Size readSize ()

Read a Size from the parcel at the current dataPosition().

Returns
Size

readSizeF

Added in API level 21
SizeF readSizeF ()

Read a SizeF from the parcel at the current dataPosition().

Returns
SizeF

readSparseArray

Added in API level 1
SparseArray readSparseArray (ClassLoader loader)

Read and return a new SparseArray object from the parcel at the current dataPosition(). Returns null if the previously written list object was null. The given class loader will be used to load any enclosed Parcelables.

Parameters
loader ClassLoader
Returns
SparseArray

readSparseBooleanArray

Added in API level 1
SparseBooleanArray readSparseBooleanArray ()

Read and return a new SparseBooleanArray object from the parcel at the current dataPosition(). Returns null if the previously written list object was null.

Returns
SparseBooleanArray

readString

Added in API level 1
String readString ()

Read a string value from the parcel at the current dataPosition().

Returns
String

readStringArray

Added in API level 1
void readStringArray (String[] val)

Parameters
val String

readStringList

Added in API level 1
void readStringList (List<String> list)

Read into the given List items String objects that were written with writeStringList(List) at the current dataPosition().

Parameters
list List
Returns
void A newly created ArrayList containing strings with the same data as those that were previously written.

See also:

readStrongBinder

Added in API level 1
IBinder readStrongBinder ()

Read an object from the parcel at the current dataPosition().

Returns
IBinder

readTypedArray

Added in API level 1
void readTypedArray (T[] val, 
                Creator<T> c)

Parameters
val T
c Creator

readTypedList

Added in API level 1
void readTypedList (List<T> list, 
                Creator<T> c)

Read into the given List items containing a particular object type that were written with writeTypedList(List) at the current dataPosition(). The list must have previously been written via writeTypedList(List) with the same object type.

Parameters
list List
c Creator
Returns
void A newly created ArrayList containing objects with the same data as those that were previously written.

See also:

readTypedObject

Added in API level 23
T readTypedObject (Creator<T> c)

Read and return a typed Parcelable object from a parcel. Returns null if the previous written object was null. The object must have previous been written via writeTypedObject(T, int) with the same object type.

Parameters
c Creator
Returns
T A newly created object of the type that was previously written.

See also:

readValue

Added in API level 1
Object readValue (ClassLoader loader)

Read a typed object from a parcel. The given class loader will be used to load any enclosed Parcelables. If it is null, the default class loader will be used.

Parameters
loader ClassLoader
Returns
Object

recycle

Added in API level 1
void recycle ()

Put a Parcel object back into the pool. You must not touch the object after this call.

setDataCapacity

Added in API level 1
void setDataCapacity (int size)

Change the capacity (current available space) of the parcel.

Parameters
size int: The new capacity of the parcel, in bytes. Can not be less than dataSize() -- that is, you can not drop existing data with this method.

setDataPosition

Added in API level 1
void setDataPosition (int pos)

Move the current read/write position in the parcel.

Parameters
pos int: New offset in the parcel; must be between 0 and dataSize().

setDataSize

Added in API level 1
void setDataSize (int size)

Change the amount of data in the parcel. Can be either smaller or larger than the current size. If larger than the current capacity, more memory will be allocated.

Parameters
size int: The new number of bytes in the Parcel.

unmarshall

Added in API level 1
void unmarshall (byte[] data, 
                int offset, 
                int length)

Set the bytes in data to be the raw bytes of this Parcel.

Parameters
data byte
offset int
length int

writeArray

Added in API level 1
void writeArray (Object[] val)

Flatten an Object array into the parcel at the current dataPosition(), growing dataCapacity() if needed. The array values are written using writeValue(Object) and must follow the specification there.

Parameters
val Object

writeBinderArray

Added in API level 1
void writeBinderArray (IBinder[] val)

Parameters
val IBinder

writeBinderList

Added in API level 1
void writeBinderList (List<IBinder> val)

Flatten a List containing IBinder objects into the parcel, at the current dataPosition() and growing dataCapacity() if needed. They can later be retrieved with createBinderArrayList() or readBinderList(List).

Parameters
val List: The list of strings to be written.

See also:

writeBooleanArray

Added in API level 1
void writeBooleanArray (boolean[] val)

Parameters
val boolean

writeBundle

Added in API level 1
void writeBundle (Bundle val)

Flatten a Bundle into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val Bundle

writeByte

Added in API level 1
void writeByte (byte val)

Write a byte value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val byte

writeByteArray

Added in API level 1
void writeByteArray (byte[] b)

Write a byte array into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
b byte: Bytes to place into the parcel.

writeByteArray

Added in API level 1
void writeByteArray (byte[] b, 
                int offset, 
                int len)

Write a byte array into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
b byte: Bytes to place into the parcel.
offset int: Index of first byte to be written.
len int: Number of bytes to write.

writeCharArray

Added in API level 1
void writeCharArray (char[] val)

Parameters
val char

writeDouble

Added in API level 1
void writeDouble (double val)

Write a double precision floating point value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val double

writeDoubleArray

Added in API level 1
void writeDoubleArray (double[] val)

Parameters
val double

writeException

Added in API level 1
void writeException (Exception e)

Special function for writing an exception result at the header of a parcel, to be used when returning an exception from a transaction. Note that this currently only supports a few exception types; any other exception will be re-thrown by this function as a RuntimeException (to be caught by the system's last-resort exception handling when dispatching a transaction).

The supported exception types are:

Parameters
e Exception: The Exception to be written.

See also:

writeFileDescriptor

Added in API level 1
void writeFileDescriptor (FileDescriptor val)

Write a FileDescriptor into the parcel at the current dataPosition(), growing dataCapacity() if needed.

The file descriptor will not be closed, which may result in file descriptor leaks when objects are returned from Binder calls. Use writeToParcel(Parcel, int) instead, which accepts contextual flags and will close the original file descriptor if PARCELABLE_WRITE_RETURN_VALUE is set.

Parameters
val FileDescriptor

writeFloat

Added in API level 1
void writeFloat (float val)

Write a floating point value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val float

writeFloatArray

Added in API level 1
void writeFloatArray (float[] val)

Parameters
val float

writeInt

Added in API level 1
void writeInt (int val)

Write an integer value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val int

writeIntArray

Added in API level 1
void writeIntArray (int[] val)

Parameters
val int

writeInterfaceToken

Added in API level 1
void writeInterfaceToken (String interfaceName)

Store or read an IBinder interface token in the parcel at the current dataPosition(). This is used to validate that the marshalled transaction is intended for the target interface.

Parameters
interfaceName String

writeList

Added in API level 1
void writeList (List val)

Flatten a List into the parcel at the current dataPosition(), growing dataCapacity() if needed. The List values are written using writeValue(Object) and must follow the specification there.

Parameters
val List

writeLong

Added in API level 1
void writeLong (long val)

Write a long integer value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val long

writeLongArray

Added in API level 1
void writeLongArray (long[] val)

Parameters
val long

writeMap

Added in API level 1
void writeMap (Map val)

Please use writeBundle(Bundle) instead. Flattens a Map into the parcel at the current dataPosition(), growing dataCapacity() if needed. The Map keys must be String objects. The Map values are written using writeValue(Object) and must follow the specification there.

It is strongly recommended to use writeBundle(Bundle) instead of this method, since the Bundle class provides a type-safe API that allows you to avoid mysterious type errors at the point of marshalling.

Parameters
val Map

writeNoException

Added in API level 1
void writeNoException ()

Special function for writing information at the front of the Parcel indicating that no exception occurred.

See also:

writeParcelable

Added in API level 1
void writeParcelable (Parcelable p, 
                int parcelableFlags)

Flatten the name of the class of the Parcelable and its contents into the parcel.

Parameters
p Parcelable: The Parcelable object to be written.
parcelableFlags int: Contextual flags as per Parcelable.writeToParcel().

writeParcelableArray

Added in API level 1
void writeParcelableArray (T[] value, 
                int parcelableFlags)

Write a heterogeneous array of Parcelable objects into the Parcel. Each object in the array is written along with its class name, so that the correct class can later be instantiated. As a result, this has significantly more overhead than writeTypedArray(T[], int), but will correctly handle an array containing more than one type of object.

Parameters
value T: The array of objects to be written.
parcelableFlags int: Contextual flags as per Parcelable.writeToParcel().

See also:

writePersistableBundle

Added in API level 21
void writePersistableBundle (PersistableBundle val)

Flatten a PersistableBundle into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val PersistableBundle

writeSerializable

Added in API level 1
void writeSerializable (Serializable s)

Write a generic serializable object in to a Parcel. It is strongly recommended that this method be avoided, since the serialization overhead is extremely large, and this approach will be much slower than using the other approaches to writing data in to a Parcel.

Parameters
s Serializable

writeSize

Added in API level 21
void writeSize (Size val)

Flatten a Size into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val Size

writeSizeF

Added in API level 21
void writeSizeF (SizeF val)

Flatten a SizeF into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val SizeF

writeSparseArray

Added in API level 1
void writeSparseArray (SparseArray<Object> val)

Flatten a generic SparseArray into the parcel at the current dataPosition(), growing dataCapacity() if needed. The SparseArray values are written using writeValue(Object) and must follow the specification there.

Parameters
val SparseArray

writeSparseBooleanArray

Added in API level 1
void writeSparseBooleanArray (SparseBooleanArray val)

Parameters
val SparseBooleanArray

writeString

Added in API level 1
void writeString (String val)

Write a string value into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val String

writeStringArray

Added in API level 1
void writeStringArray (String[] val)

Parameters
val String

writeStringList

Added in API level 1
void writeStringList (List<String> val)

Flatten a List containing String objects into the parcel, at the current dataPosition() and growing dataCapacity() if needed. They can later be retrieved with createStringArrayList() or readStringList(List).

Parameters
val List: The list of strings to be written.

See also:

writeStrongBinder

Added in API level 1
void writeStrongBinder (IBinder val)

Write an object into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val IBinder

writeStrongInterface

Added in API level 1
void writeStrongInterface (IInterface val)

Write an object into the parcel at the current dataPosition(), growing dataCapacity() if needed.

Parameters
val IInterface

writeTypedArray

Added in API level 1
void writeTypedArray (T[] val, 
                int parcelableFlags)

Flatten a heterogeneous array containing a particular object type into the parcel, at the current dataPosition() and growing dataCapacity() if needed. The type of the objects in the array must be one that implements Parcelable. Unlike the writeParcelableArray(T[], int) method, however, only the raw data of the objects is written and not their type, so you must use readTypedArray(T[], Parcelable.Creator) with the correct corresponding Parcelable.Creator implementation to unmarshall them.

Parameters
val T: The array of objects to be written.
parcelableFlags int: Contextual flags as per Parcelable.writeToParcel().

See also:

writeTypedList

Added in API level 1
void writeTypedList (List<T> val)

Flatten a List containing a particular object type into the parcel, at the current dataPosition() and growing dataCapacity() if needed. The type of the objects in the list must be one that implements Parcelable. Unlike the generic writeList() method, however, only the raw data of the objects is written and not their type, so you must use the corresponding readTypedList() to unmarshall them.

Parameters
val List: The list of objects to be written.

See also:

writeTypedObject

Added in API level 23
void writeTypedObject (T val, 
                int parcelableFlags)

Flatten the Parcelable object into the parcel.

Parameters
val T: The Parcelable object to be written.
parcelableFlags int: Contextual flags as per Parcelable.writeToParcel().

See also:

writeValue

Added in API level 1
void writeValue (Object v)

Flatten a generic object in to a parcel. The given Object value may currently be one of the following types:

Parcelable objects are written with writeToParcel(Parcel, int) using contextual flags of 0. When serializing objects containing ParcelFileDescriptors, this may result in file descriptor leaks when they are returned from Binder calls (where PARCELABLE_WRITE_RETURN_VALUE should be used).

Parameters
v Object

Protected methods

finalize

Added in API level 1
void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the JavaTM virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Throws
Throwable

Hooray!