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.
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.
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:
writeBooleanArray(boolean[])
,
readBooleanArray(boolean[])
, createBooleanArray()
writeByteArray(byte[])
,
writeByteArray(byte[], int, int)
, readByteArray(byte[])
,
createByteArray()
writeCharArray(char[])
, readCharArray(char[])
,
createCharArray()
writeDoubleArray(double[])
, readDoubleArray(double[])
,
createDoubleArray()
writeFloatArray(float[])
, readFloatArray(float[])
,
createFloatArray()
writeIntArray(int[])
, readIntArray(int[])
,
createIntArray()
writeLongArray(long[])
, readLongArray(long[])
,
createLongArray()
writeStringArray(String[])
, readStringArray(String[])
,
createStringArray()
.
writeSparseBooleanArray(SparseBooleanArray)
,
readSparseBooleanArray()
.
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.)
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)
.
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()
.
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)
.
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 |
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 |
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 |
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
|
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 |
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 |
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
|
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 |
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 |
final
void
|
writeByteArray(byte[] b, int offset, int len)
Write a byte array into the parcel at the current |
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
|
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 |
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
|
void appendFrom (Parcel parcel, int offset, int length)
Parameters | |
---|---|
parcel |
Parcel
|
offset |
int
|
length |
int
|
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:
byte[] createByteArray ()
Read and return a byte[] object from the parcel.
Returns | |
---|---|
byte[] |
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:
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:
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:
int dataAvail ()
Returns the amount of data remaining to be read from the
parcel. That is, dataSize()
-dataPosition()
.
Returns | |
---|---|
int |
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 |
int dataPosition ()
Returns the current position in the parcel data. Never
more than dataSize()
.
Returns | |
---|---|
int |
int dataSize ()
Returns the total amount of data contained in the parcel.
Returns | |
---|---|
int |
void enforceInterface (String interfaceName)
Parameters | |
---|---|
interfaceName |
String
|
boolean hasFileDescriptors ()
Report whether the parcel contains any marshalled file descriptors.
Returns | |
---|---|
boolean |
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[] |
Parcel obtain ()
Retrieve a new Parcel object from the pool.
Returns | |
---|---|
Parcel |
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[] |
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 |
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:
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 |
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 |
byte readByte ()
Read a byte value from the parcel at the current dataPosition().
Returns | |
---|---|
byte |
void readByteArray (byte[] val)
Read a byte[] object from the parcel and copy it into the given byte array.
Parameters | |
---|---|
val |
byte
|
double readDouble ()
Read a double precision floating point value from the parcel at the current dataPosition().
Returns | |
---|---|
double |
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.
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.
|
ParcelFileDescriptor readFileDescriptor ()
Read a FileDescriptor from the parcel at the current dataPosition().
Returns | |
---|---|
ParcelFileDescriptor |
float readFloat ()
Read a floating point value from the parcel at the current dataPosition().
Returns | |
---|---|
float |
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 |
int readInt ()
Read an integer value from the parcel at the current dataPosition().
Returns | |
---|---|
int |
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
|
long readLong ()
Read a long integer value from the parcel at the current dataPosition().
Returns | |
---|---|
long |
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
|
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. |
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 |
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 |
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 |
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. |
Size readSize ()
Read a Size from the parcel at the current dataPosition().
Returns | |
---|---|
Size |
SizeF readSizeF ()
Read a SizeF from the parcel at the current dataPosition().
Returns | |
---|---|
SizeF |
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 |
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 |
String readString ()
Read a string value from the parcel at the current dataPosition().
Returns | |
---|---|
String |
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:
IBinder readStrongBinder ()
Read an object from the parcel at the current dataPosition().
Returns | |
---|---|
IBinder |
void readTypedArray (T[] val, Creator<T> c)
Parameters | |
---|---|
val |
T
|
c |
Creator
|
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:
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:
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 |
void recycle ()
Put a Parcel object back into the pool. You must not touch the object after this call.
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.
|
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() .
|
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.
|
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
|
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
|
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. |
void writeBooleanArray (boolean[] val)
Parameters | |
---|---|
val |
boolean
|
void writeBundle (Bundle val)
Flatten a Bundle into the parcel at the current dataPosition(), growing dataCapacity() if needed.
Parameters | |
---|---|
val |
Bundle
|
void writeByte (byte val)
Write a byte value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
Parameters | |
---|---|
val |
byte
|
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.
|
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.
|
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
|
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:
BadParcelableException
IllegalArgumentException
IllegalStateException
NullPointerException
SecurityException
NetworkOnMainThreadException
Parameters | |
---|---|
e |
Exception :
The Exception to be written. |
See also:
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
|
void writeFloat (float val)
Write a floating point value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
Parameters | |
---|---|
val |
float
|
void writeInt (int val)
Write an integer value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
Parameters | |
---|---|
val |
int
|
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
|
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
|
void writeLong (long val)
Write a long integer value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
Parameters | |
---|---|
val |
long
|
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
|
void writeNoException ()
Special function for writing information at the front of the Parcel indicating that no exception occurred.
See also:
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() .
|
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:
void writePersistableBundle (PersistableBundle val)
Flatten a PersistableBundle into the parcel at the current dataPosition(), growing dataCapacity() if needed.
Parameters | |
---|---|
val |
PersistableBundle
|
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
|
void writeSize (Size val)
Flatten a Size into the parcel at the current dataPosition(), growing dataCapacity() if needed.
Parameters | |
---|---|
val |
Size
|
void writeSizeF (SizeF val)
Flatten a SizeF into the parcel at the current dataPosition(), growing dataCapacity() if needed.
Parameters | |
---|---|
val |
SizeF
|
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
|
void writeSparseBooleanArray (SparseBooleanArray val)
Parameters | |
---|---|
val |
SparseBooleanArray
|
void writeString (String val)
Write a string value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
Parameters | |
---|---|
val |
String
|
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. |
void writeStrongBinder (IBinder val)
Write an object into the parcel at the current dataPosition(), growing dataCapacity() if needed.
Parameters | |
---|---|
val |
IBinder
|
void writeStrongInterface (IInterface val)
Write an object into the parcel at the current dataPosition(), growing dataCapacity() if needed.
Parameters | |
---|---|
val |
IInterface
|
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() . |
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. |
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:
void writeValue (Object v)
Flatten a generic object in to a parcel. The given Object value may currently be one of the following types:
Bundle
writeMap(Map)
).
Parcelable
protocol.
writeToParcel(CharSequence, Parcel, int)
).
writeList(List)
).
SparseArray
(as supported by writeSparseArray(SparseArray)
).
IBinder
writeSerializable(Serializable)
for caveats). Note that all of the
previous types have relatively efficient implementations for
writing to a Parcel; having to rely on the generic serialization
approach is much less efficient and should be avoided whenever
possible.
Parcelable
objects are written with
writeToParcel(Parcel, int)
using contextual flags of 0. When
serializing objects containing ParcelFileDescriptor
s,
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
|
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 |