Android - An Open Handset Alliance Project

android.os
public final class

android.os.Parcel

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.

Summary

Constants

			Value
Creator	STRING_CREATOR

Public Methods

final		void	appendFrom(Parcel parcel, int offset, int length)
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	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[]	createTypedArray(Creator c)
			Read and return a new array containing a particular object type from the parcel at the current dataPosition().
final		ArrayList	createTypedArrayList(Creator 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		byte[]	marshall()
			Returns the raw bytes of the parcel.
final	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	readBooleanArray(boolean[] val)
final		Bundle	readBundle()
			Read and return a new Bundle object from the parcel at the current dataPosition().
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		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)
			Read and return a new HashMap object from the parcel at the current dataPosition().
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)
			Read into an existing Map object from the parcel at the current dataPosition().
final		Object	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		Serializable	readSerializable()
			Read and return a new Serializable object from the parcel.
final		SparseArray	readSparseArray(ClassLoader loader)
			Read and return a new SparseArray object from the parcel at the current dataPosition().
final		String	readString()
			Read a string value from the parcel at the current dataPosition().
final		String[]	readStringArray()
			Read and return a byte[[]] object from the parcel.
final		void	readStringArray(String[] val)
final		void	readStringList(List 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		void	readTypedArray(T[] val, Creator c)
final		T[]	readTypedArray(Creator c)
final		void	readTypedList(List list, Creator c)
			Read into the given List items containing a particular object type that were written with writeTypedList(List) at the current dataPosition().
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 offest, 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	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 an byte value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
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.
final		void	writeByteArray(byte[] b)
			Write a byte array into the parcel at the current {#link #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	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)
			Flatten a Map into the parcel at the current dataPosition(), growing dataCapacity() if needed.
final		void	writeNoException()
			Special function for writing information at the front of the Parcel indicating that no exception occurred.
final		void	writeParcelable(Parcelable p)
			Flatten the name of the class of the Parcelable and its contents into the parcel.
final		void	writeParcelableArray(T[] value)
			Write a heterogeneous array of Parcelable objects into the Parcel.
final		void	writeSerializable(Serializable s)
final		void	writeSparseArray(SparseArray val)
			Flatten a generic SparseArray into the parcel at the current dataPosition(), growing dataCapacity() if needed.
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 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		void	writeTypedArray(T[] val)
			Flatten a heterogeneous array containing a particular object type into the parcel, at the current dataPosition() and growing dataCapacity() if needed.
final		void	writeTypedList(List val)
			Flatten a List containing a particular object type into the parcel, at the current dataPosition() and growing dataCapacity() if needed.
final		void	writeValue(Object v)
			Flatten an arbitrary object in to a parcel.

Protected Methods

		void	finalize()
			Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
final	static	Parcel	obtain(int obj)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

	Object	clone()
		Answers a new instance of the same class as the receiver, whose slots have been filled in with the values in the slots of the receiver.
	boolean	equals(Object o)
		Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
	void	finalize()
		Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
final	Class	getClass()
		Answers the unique instance of java.lang.Class which represents the class of the receiver.
	int	hashCode()
		Answers an integer hash code for the receiver.
final	void	notify()
		Causes one thread which is `wait` ing on the receiver to be made ready to run.
final	void	notifyAll()
		Causes all threads which are `wait` ing on the receiver to be made ready to run.
	String	toString()
		Answers a string containing a concise, human-readable description of the receiver.
final	void	wait(long time, int frac)
		Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by `notify` or `notifyAll`) or the expiration of the timeout.
final	void	wait(long time)
		Causes the thread which sent this message to be made not ready to run either pending some change in the receiver (as indicated by `notify` or `notifyAll`) or the expiration of the timeout.
final	void	wait()
		Causes the thread which sent this message to be made not ready to run pending some change in the receiver (as indicated by `notify` or `notifyAll`).

Details

Constants

public static final Creator STRING_CREATOR

Public Methods

public final void appendFrom(Parcel parcel, int offset, int length)

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 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 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[]) 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 createTypedArrayList(Creator 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()

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

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 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 final Parcel obtain()

Retrieve a new Parcel object from the pool.

public final 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.

public final 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.

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.

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 ParcelFileDescriptor readFileDescriptor()

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)

public final HashMap readHashMap(ClassLoader loader)

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 Object 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.

public final 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.

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.

public final 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.

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 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 c)

public final T[] readTypedArray(Creator c)

public final void readTypedList(List list, Creator 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.

public final 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.

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 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, 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 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 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 SecurityException; any other exception will be re-thrown by the function (to be caught by the systems last-resort exception handling when dispatching a transaction).

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 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)

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

public final void writeParcelableArray(T[] value)

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[]), but will correctly handle an array containing more than one type of object.

Parameters

value	The array of objects to be written.

public final void writeSerializable(Serializable s)

public final void writeSparseArray(SparseArray 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 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)

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[]) 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	The array of objects to be written.

public final void writeTypedList(List 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.

Throws

Throwable


e.g. "intent" or "activity"

Android - An Open Handset Alliance Project

Documentation

Goodies

android.os.Parcel

Summary

Constants

Public Methods

Protected Methods

Methods inherited from class java.lang.Object

Details

Constants

public static final Creator STRING_CREATOR

Public Methods

public final void appendFrom(Parcel parcel, int offset, int length)

public final boolean[] createBooleanArray()

public final byte[] createByteArray()

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 createStringArrayList()

Returns

See Also

public final T[] createTypedArray(Creator c)

Returns

See Also

public final ArrayList createTypedArrayList(Creator c)

Returns

See Also

public final int dataAvail()

public final int dataCapacity()

public final int dataPosition()

public final int dataSize()

public final byte[] marshall()

public static final Parcel obtain()

public final Object[] readArray(ClassLoader loader)

public final ArrayList readArrayList(ClassLoader loader)

public final void readBooleanArray(boolean[] val)

public final Bundle readBundle()

public final byte readByte()

public final void readByteArray(byte[] val)

public final void readCharArray(char[] val)

public final double readDouble()

public final void readDoubleArray(double[] val)

public final void readException()

See Also

public final ParcelFileDescriptor readFileDescriptor()

public final float readFloat()

public final void readFloatArray(float[] val)

public final HashMap readHashMap(ClassLoader loader)

public final int readInt()

public final void readIntArray(int[] val)

public final void readList(List outVal, ClassLoader loader)

public final long readLong()

public final void readLongArray(long[] val)

public final void readMap(Map outVal, ClassLoader loader)

public final Object readParcelable(ClassLoader loader)

Parameters

Returns

Throws

public final Parcelable[] readParcelableArray(ClassLoader loader)

Returns

public final Serializable readSerializable()

Returns

public final SparseArray readSparseArray(ClassLoader loader)

public final String readString()

public final String[] readStringArray()

public final void readStringArray(String[] val)

public final void readStringList(List list)

Returns

See Also

public final IBinder readStrongBinder()

public final void readTypedArray(T[] val, Creator c)

public final T[] readTypedArray(Creator c)

public final void readTypedList(List list, Creator c)

Returns

See Also

public final Object readValue(ClassLoader loader)