android.os
public
final
class
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.
Summary
Constants
Public Methods
|
|
final |
|
|
void |
appendFrom(Parcel parcel, int offset, int length) |
|
|
final |
|
|
IBinder[] |
createBinderArray() |
|
|
final |
|
|
ArrayList<IBinder> |
createBinderArrayList() |
|
|
final |
|
|
boolean[] |
createBooleanArray() |
|
|
final |
|
|
byte[] |
createByteArray() |
|
|
final |
|
|
char[] |
createCharArray() |
|
|
final |
|
|
double[] |
createDoubleArray() |
|
|
final |
|
|
float[] |
createFloatArray() |
|
|
final |
|
|
int[] |
createIntArray() |
|
|
final |
|
|
long[] |
createLongArray() |
|
|
final |
|
|
String[] |
createStringArray() |
|
|
final |
|
|
ArrayList<String> |
createStringArrayList() |
|
|
final |
|
<T> |
T[] |
createTypedArray(Creator<T> c) |
|
|
final |
|
<T> |
ArrayList<T> |
createTypedArrayList(Creator<T> c) |
|
|
final |
|
|
int |
dataAvail() |
|
|
final |
|
|
int |
dataCapacity() |
|
|
final |
|
|
int |
dataPosition() |
|
|
final |
|
|
int |
dataSize() |
|
|
final |
|
|
void |
enforceInterface(String interfaceName) |
|
|
final |
|
|
boolean |
hasFileDescriptors() |
|
|
final |
|
|
byte[] |
marshall() |
|
|
|
static |
|
Parcel |
obtain() |
|
|
final |
|
|
Object[] |
readArray(ClassLoader loader) |
|
|
final |
|
|
ArrayList |
readArrayList(ClassLoader loader) |
|
|
final |
|
|
void |
readBinderArray(IBinder[] val) |
|
|
final |
|
|
void |
readBinderList(List<IBinder> list) |
|
|
final |
|
|
void |
readBooleanArray(boolean[] val) |
|
|
final |
|
|
Bundle |
readBundle() |
|
|
final |
|
|
Bundle |
readBundle(ClassLoader loader) |
|
|
final |
|
|
byte |
readByte() |
|
|
final |
|
|
void |
readByteArray(byte[] val) |
|
|
final |
|
|
void |
readCharArray(char[] val) |
|
|
final |
|
|
double |
readDouble() |
|
|
final |
|
|
void |
readDoubleArray(double[] val) |
|
|
final |
|
|
void |
readException() |
|
|
final |
|
|
void |
readException(int code, String msg) |
|
|
final |
|
|
ParcelFileDescriptor |
readFileDescriptor() |
|
|
final |
|
|
float |
readFloat() |
|
|
final |
|
|
void |
readFloatArray(float[] val) |
|
|
final |
|
|
HashMap |
readHashMap(ClassLoader loader) |
|
|
final |
|
|
int |
readInt() |
|
|
final |
|
|
void |
readIntArray(int[] val) |
|
|
final |
|
|
void |
readList(List outVal, ClassLoader loader) |
|
|
final |
|
|
long |
readLong() |
|
|
final |
|
|
void |
readLongArray(long[] val) |
|
|
final |
|
|
void |
readMap(Map outVal, ClassLoader loader) |
|
|
final |
|
<T extends Parcelable> |
T |
readParcelable(ClassLoader loader) |
|
|
final |
|
|
Parcelable[] |
readParcelableArray(ClassLoader loader) |
|
|
final |
|
|
Serializable |
readSerializable() |
|
|
final |
|
|
SparseArray |
readSparseArray(ClassLoader loader) |
|
|
final |
|
|
SparseBooleanArray |
readSparseBooleanArray() |
|
|
final |
|
|
String |
readString() |
|
|
final |
|
|
String[] |
readStringArray() |
|
|
final |
|
|
void |
readStringArray(String[] val) |
|
|
final |
|
|
void |
readStringList(List<String> list) |
|
|
final |
|
|
IBinder |
readStrongBinder() |
|
|
final |
|
<T> |
void |
readTypedArray(T[] val, Creator<T> c) |
|
|
final |
|
<T> |
T[] |
readTypedArray(Creator<T> c) |
|
|
final |
|
<T> |
void |
readTypedList(List<T> list, Creator<T> c) |
|
|
final |
|
|
Object |
readValue(ClassLoader loader) |
|
|
final |
|
|
void |
recycle() |
|
|
final |
|
|
void |
setDataCapacity(int size) |
|
|
final |
|
|
void |
setDataPosition(int pos) |
|
|
final |
|
|
void |
setDataSize(int size) |
|
|
final |
|
|
void |
unmarshall(byte[] data, int offest, int length) |
|
|
final |
|
|
void |
writeArray(Object[] val) |
|
|
final |
|
|
void |
writeBinderArray(IBinder[] val) |
|
|
final |
|
|
void |
writeBinderList(List<IBinder> val) |
|
|
final |
|
|
void |
writeBooleanArray(boolean[] val) |
|
|
final |
|
|
void |
writeBundle(Bundle val) |
|
|
final |
|
|
void |
writeByte(byte val) |
|
|
final |
|
|
void |
writeByteArray(byte[] b) |
|
|
final |
|
|
void |
writeByteArray(byte[] b, int offset, int len) |
|
|
final |
|
|
void |
writeCharArray(char[] val) |
|
|
final |
|
|
void |
writeDouble(double val) |
|
|
final |
|
|
void |
writeDoubleArray(double[] val) |
|
|
final |
|
|
void |
writeException(Exception e) |
|
|
final |
|
|
void |
writeFileDescriptor(FileDescriptor val) |
|
|
final |
|
|
void |
writeFloat(float val) |
|
|
final |
|
|
void |
writeFloatArray(float[] val) |
|
|
final |
|
|
void |
writeInt(int val) |
|
|
final |
|
|
void |
writeIntArray(int[] val) |
|
|
final |
|
|
void |
writeInterfaceToken(String interfaceName) |
|
|
final |
|
|
void |
writeList(List val) |
|
|
final |
|
|
void |
writeLong(long val) |
|
|
final |
|
|
void |
writeLongArray(long[] val) |
|
|
final |
|
|
void |
writeMap(Map val) |
|
|
final |
|
|
void |
writeNoException() |
|
|
final |
|
|
void |
writeParcelable(Parcelable p, int parcelableFlags) |
|
|
final |
|
<T extends Parcelable> |
void |
writeParcelableArray(T[] value, int parcelableFlags) |
|
|
final |
|
|
void |
writeSerializable(Serializable s) |
|
|
final |
|
|
void |
writeSparseArray(SparseArray<Object> val) |
|
|
final |
|
|
void |
writeSparseBooleanArray(SparseBooleanArray val) |
|
|
final |
|
|
void |
writeString(String val) |
|
|
final |
|
|
void |
writeStringArray(String[] val) |
|
|
final |
|
|
void |
writeStringList(List<String> val) |
|
|
final |
|
|
void |
writeStrongBinder(IBinder val) |
|
|
final |
|
|
void |
writeStrongInterface(IInterface val) |
|
|
final |
|
<T extends Parcelable> |
void |
writeTypedArray(T[] val, int parcelableFlags) |
|
|
final |
|
<T extends Parcelable> |
void |
writeTypedList(List<T> val) |
|
|
final |
|
|
void |
writeValue(Object v) |
Protected Methods
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
Details
Constants
Public Methods
public
final
void
appendFrom(Parcel parcel, int offset, int length)
public
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(). Returns null if the
previously written list object was null.
Returns
- A newly created ArrayList containing strings with the same data
as those that were previously written.
public
final
boolean[]
createBooleanArray()
public
final
byte[]
createByteArray()
Read and return a byte[] object from the parcel.
public
final
char[]
createCharArray()
public
final
double[]
createDoubleArray()
public
final
float[]
createFloatArray()
public
final
int[]
createIntArray()
public
final
long[]
createLongArray()
public
final
String[]
createStringArray()
public
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(). Returns null if the
previously written list object was null.
Returns
- A newly created ArrayList containing strings with the same data
as those that were previously written.
public
final
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.
Returns
- A newly created array containing objects with the same data
as those that were previously written.
public
final
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.
Returns
- A newly created ArrayList containing objects with the same data
as those that were previously written.
public
final
int
dataAvail()
public
final
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.
public
final
int
dataPosition()
Returns the current position in the parcel data. Never
more than
dataSize().
public
final
int
dataSize()
Returns the total amount of data contained in the parcel.
public
final
void
enforceInterface(String interfaceName)
public
final
boolean
hasFileDescriptors()
Report whether the parcel contains any marshalled file descriptors.
public
final
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 Java 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.
public
static
Parcel
obtain()
Retrieve a new Parcel object from the pool.
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.
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.
public
final
void
readBinderArray(IBinder[] val)
public
final
void
readBinderList(List<IBinder> list)
Read into the given List items IBinder objects that were written with
writeBinderList(List) at the current dataPosition().
Returns
- A newly created ArrayList containing strings with the same data
as those that were previously written.
public
final
void
readBooleanArray(boolean[] val)
public
final
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.
Read and return a new Bundle object from the parcel at the current
dataPosition(). Returns null if the previously written Bundle object was
null.
public
final
byte
readByte()
Read a byte value from the parcel at the current dataPosition().
public
final
void
readByteArray(byte[] val)
Read a byte[] object from the parcel and copy it into the
given byte array.
public
final
void
readCharArray(char[] val)
public
final
double
readDouble()
Read a double precision floating point value from the parcel at the
current dataPosition().
public
final
void
readDoubleArray(double[] val)
public
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. 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.
public
final
void
readException(int code, String msg)
Use this function for customized exception handling.
customized method call this method for all unknown case
Parameters
code
| exception code |
msg
| exception message
|
Read a FileDescriptor from the parcel at the current dataPosition().
public
final
float
readFloat()
Read a floating point value from the parcel at the current
dataPosition().
public
final
void
readFloatArray(float[] val)
Read and return a new HashMap object from the parcel at the current
dataPosition(). Returns null if the previously written map object was
null.
public
final
int
readInt()
Read an integer value from the parcel at the current dataPosition().
public
final
void
readIntArray(int[] val)
public
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. If it is null, the default class loader is used.
public
final
long
readLong()
Read a long integer value from the parcel at the current dataPosition().
public
final
void
readLongArray(long[] val)
public
final
void
readMap(Map outVal, ClassLoader loader)
Read into an existing Map object from the parcel at the current
dataPosition().
public
final
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
| a ClassLoader, or null |
Returns
- 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.
|
Read and return a new Parcelable array from the parcel.
The given class loader will be used to load any enclosed
Parcelables.
Returns
- the Parcelable array, or null if the array is null
public
final
Serializable
readSerializable()
Read and return a new Serializable object from the parcel.
Returns
- the Serializable object, or null if the Serializable name
wasn't found in the parcel.
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.
public
final
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.
public
final
String
readString()
Read a string value from the parcel at the current dataPosition().
public
final
String[]
readStringArray()
Read and return a byte[] object from the parcel.
public
final
void
readStringArray(String[] val)
public
final
void
readStringList(List<String> list)
Read into the given List items String objects that were written with
writeStringList(List) at the current dataPosition().
Returns
- A newly created ArrayList containing strings with the same data
as those that were previously written.
public
final
IBinder
readStrongBinder()
Read an object from the parcel at the current dataPosition().
public
final
void
readTypedArray(T[] val, Creator<T> c)
public
final
T[]
readTypedArray(Creator<T> c)
public
final
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.
Returns
- A newly created ArrayList containing objects with the same data
as those that were previously written.
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.
public
final
void
recycle()
Put a Parcel object back into the pool. You must not touch
the object after this call.
public
final
void
setDataCapacity(int size)
Change the capacity (current available space) of the parcel.
Parameters
size
| 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.
|
public
final
void
setDataPosition(int pos)
Move the current read/write position in the parcel.
Parameters
pos
| New offset in the parcel; must be between 0 and
dataSize().
|
public
final
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
| The new number of bytes in the Parcel.
|
public
final
void
unmarshall(byte[] data, int offest, int length)
Set the bytes in data to be the raw bytes of this Parcel.
public
final
void
writeArray(Object[] val)
Flatten an Object array into the parcel at the current dataPosition(),
growing dataCapacity() if needed.
public
final
void
writeBinderArray(IBinder[] val)
public
final
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
| The list of strings to be written. |
public
final
void
writeBooleanArray(boolean[] val)
public
final
void
writeBundle(Bundle val)
Flatten a Bundle into the parcel at the current dataPosition(),
growing dataCapacity() if needed.
public
final
void
writeByte(byte val)
Write an byte value into the parcel at the current dataPosition(),
growing dataCapacity() if needed.
public
final
void
writeByteArray(byte[] b)
Write a byte array into the parcel at the current {#link #dataPosition},
growing
dataCapacity() if needed.
Parameters
b
| Bytes to place into the parcel.
|
public
final
void
writeByteArray(byte[] b, int offset, int len)
Write an byte array into the parcel at the current {#link #dataPosition},
growing
dataCapacity() if needed.
Parameters
b
| Bytes to place into the parcel. |
offset
| Index of first byte to be written. |
len
| Number of bytes to write.
|
public
final
void
writeCharArray(char[] val)
public
final
void
writeDouble(double val)
Write a double precision floating point value into the parcel at the
current dataPosition(), growing dataCapacity() if needed.
public
final
void
writeDoubleArray(double[] val)
public
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.
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
| The Exception to be written. |
public
final
void
writeFileDescriptor(FileDescriptor val)
Write a FileDescriptor into the parcel at the current dataPosition(),
growing dataCapacity() if needed.
public
final
void
writeFloat(float val)
Write a floating point value into the parcel at the current
dataPosition(), growing dataCapacity() if needed.
public
final
void
writeFloatArray(float[] val)
public
final
void
writeInt(int val)
Write an integer value into the parcel at the current dataPosition(),
growing dataCapacity() if needed.
public
final
void
writeIntArray(int[] val)
public
final
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.
public
final
void
writeList(List val)
Flatten a List into the parcel at the current dataPosition(), growing
dataCapacity() if needed.
public
final
void
writeLong(long val)
Write a long integer value into the parcel at the current dataPosition(),
growing dataCapacity() if needed.
public
final
void
writeLongArray(long[] val)
public
final
void
writeMap(Map val)
Flatten a Map into the parcel at the current dataPosition(),
growing dataCapacity() if needed. The Map keys must be String objects.
public
final
void
writeNoException()
Special function for writing information at the front of the Parcel
indicating that no exception occurred.
public
final
void
writeParcelable(Parcelable p, int parcelableFlags)
Flatten the name of the class of the Parcelable and its contents
into the parcel.
public
final
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.
public
final
void
writeSparseArray(SparseArray<Object> val)
Flatten a generic SparseArray into the parcel at the current
dataPosition(), growing dataCapacity() if needed.
public
final
void
writeString(String val)
Write a string value into the parcel at the current dataPosition(),
growing dataCapacity() if needed.
public
final
void
writeStringArray(String[] val)
public
final
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
| The list of strings to be written. |
public
final
void
writeStrongBinder(IBinder val)
Write an object into the parcel at the current dataPosition(),
growing dataCapacity() if needed.
public
final
void
writeStrongInterface(IInterface val)
Write an object into the parcel at the current dataPosition(),
growing dataCapacity() if needed.
public
final
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.
public
final
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
| The list of objects to be written. |
public
final
void
writeValue(Object v)
Flatten an arbitrary object in to a parcel.
Protected Methods
protected
void
finalize()
Called by the virtual machine when there are no longer any (non-weak)
references to the receiver. Subclasses can use this facility to guarantee
that any associated resources are cleaned up before the receiver is
garbage collected. Uncaught exceptions which are thrown during the
running of the method cause it to terminate immediately, but are
otherwise ignored.
Note: The virtual machine assumes that the implementation in class Object
is empty.
protected
static
final
Parcel
obtain(int obj)