Parcel Class

Definition

Namespace:

Android.OS

Assembly:

Mono.Android.dll

Container for a message (data and object references) that can be sent through an IBinder.

[Android.Runtime.Register("android/os/Parcel", DoNotGenerateAcw=true)]
public sealed class Parcel : Java.Lang.Object

[<Android.Runtime.Register("android/os/Parcel", DoNotGenerateAcw=true)>]
type Parcel = class
    inherit Object

Inheritance

Object

Object

Parcel

Attributes

RegisterAttribute

Remarks

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.

<p class="note">Parcel is <strong>not</strong> 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.</p>

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

<h3>Primitives</h3>

The most basic data functions are for writing and reading primitive data types: #writeByte, #readByte, #writeDouble, #readDouble, #writeFloat, #readFloat, #writeInt, #readInt, #writeLong, #readLong, #writeString, #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.

<h3>Primitive Arrays</h3>

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:

<ul> <li> #writeBooleanArray(boolean[]), #readBooleanArray(boolean[]), #createBooleanArray()<li> #writeByteArray(byte[]), #writeByteArray(byte[], int, int), #readByteArray(byte[]), #createByteArray()<li> #writeCharArray(char[]), #readCharArray(char[]), #createCharArray()<li> #writeDoubleArray(double[]), #readDoubleArray(double[]), #createDoubleArray()<li> #writeFloatArray(float[]), #readFloatArray(float[]), #createFloatArray()<li> #writeIntArray(int[]), #readIntArray(int[]), #createIntArray()<li> #writeLongArray(long[]), #readLongArray(long[]), #createLongArray()<li> #writeStringArray(String[]), #readStringArray(String[]), #createStringArray(). <li> #writeSparseBooleanArray(SparseBooleanArray), #readSparseBooleanArray(). </ul>

<h3>Parcelables</h3>

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 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, #writeTypedArray, #writeTypedList, #readTypedObject, #createTypedArray and #createTypedArrayList. 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 Parcelable.Creator instead to properly construct the new object and read its data. (To more efficient write and read a single Parcelable object that is not null, you can directly call Parcelable#writeToParcel Parcelable.writeToParcel and Parcelable.Creator#createFromParcel Parcelable.Creator.createFromParcel yourself.)

<h3>Bundles</h3>

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

<h3>Active Objects</h3>

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(), #writeInterfaceArray(T[]), #readInterfaceArray(T[], Function), #createInterfaceArray(IntFunction, Function), #writeBinderList(List), #readBinderList(List), #createBinderArrayList(), #writeInterfaceList(List), #readInterfaceList(List, Function), #createInterfaceArrayList(Function).

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

<h3>Parcelable Containers</h3>

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

<h3>Restricted Parcelable Containers</h3>

A final class of methods are for reading standard Java containers of restricted types. These methods replace methods for reading containers of arbitrary types from previous section starting from Android Build.VERSION_CODES#TIRAMISU. The pairing writing methods are still the same from previous section. These methods accepts additional clazz parameters as the required types. The Restricted Parcelable container methods are #readArray(ClassLoader, Class), #readList(List, ClassLoader, Class), #readArrayList(ClassLoader, Class), #readMap(Map, ClassLoader, Class, Class), #readSparseArray(ClassLoader, Class).

Java documentation for android.os.Parcel.

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Properties

Class	Returns the runtime class of this Object. (Inherited from Object)
Handle	The handle to the underlying Android instance. (Inherited from Object)
HasFileDescriptors	Report whether the parcel contains any marshalled file descriptors.
JniIdentityHashCode	(Inherited from Object)
JniPeerMembers
PeerReference	(Inherited from Object)
StringCreator
ThresholdClass	This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. (Inherited from Object)
ThresholdType	This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. (Inherited from Object)

Methods

AppendFrom(Parcel, Int32, Int32)
Clone()	Creates and returns a copy of this object. (Inherited from Object)
CreateBinderArray()
CreateBinderArrayList()	Read and return a new ArrayList containing IBinder objects from the parcel that was written with #writeBinderList at the current dataPosition().
CreateBooleanArray()
CreateByteArray()	Read and return a byte[] object from the parcel.
CreateCharArray()
CreateDoubleArray()
CreateFixedArray(Class, IFunction, Int32[])	Read and return a new multi-dimensional array of typed interfaces from a parcel.
CreateFixedArray(Class, Int32[])	Read and return a new multi-dimensional array from a parcel.
CreateFixedArray(Class, IParcelableCreator, Int32[])
CreateFloatArray()
CreateIntArray()
CreateInterfaceArray(IIntFunction, IFunction)	Read and return a new array of T (IInterface) from the parcel.
CreateInterfaceArrayList(IFunction)	Read and return a new ArrayList containing T (IInterface) objects from the parcel that was written with #writeInterfaceList at the current dataPosition().
CreateLongArray()
CreateStringArray()
CreateStringArrayList()	Read and return a new ArrayList containing String objects from the parcel that was written with #writeStringList at the current dataPosition().
CreateTypedArray(IParcelableCreator)	Read and return a new array containing a particular object type from the parcel at the current dataPosition().
CreateTypedArrayList(IParcelableCreator)	Read and return a new ArrayList containing a particular object type from the parcel that was written with #writeTypedList at the current dataPosition().
CreateTypedArrayMap(IParcelableCreator)	Read into a new ArrayMap with string keys items containing a particular object type that were written with #writeTypedArrayMap(ArrayMap, int) at the current dataPosition().
CreateTypedSparseArray(IParcelableCreator)	Read into a new SparseArray items containing a particular object type that were written with #writeTypedSparseArray(SparseArray, int) at the current dataPosition().
DataAvail()	Returns the amount of data remaining to be read from the parcel.
DataCapacity()	Returns the total amount of space in the parcel.
DataPosition()	Returns the current position in the parcel data.
DataSize()	Returns the total amount of data contained in the parcel.
Dispose()	(Inherited from Object)
Dispose(Boolean)	(Inherited from Object)
EnforceInterface(String)	Read the header written by writeInterfaceToken and verify it matches the interface name in question.
EnforceNoDataAvail()	Verify there are no bytes left to be read on the Parcel.
Equals(Object)	Indicates whether some other object is "equal to" this one. (Inherited from Object)
GetHashCode()	Returns a hash code value for the object. (Inherited from Object)
InvokeHasFileDescriptors(Int32, Int32)	Report whether the parcel contains any marshalled file descriptors in the range defined by offset and length.
JavaFinalize()	Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. (Inherited from Object)
Marshall()	Returns the raw bytes of the parcel.
Notify()	Wakes up a single thread that is waiting on this object's monitor. (Inherited from Object)
NotifyAll()	Wakes up all threads that are waiting on this object's monitor. (Inherited from Object)
Obtain()	Retrieve a new Parcel object from the pool.
Obtain(IBinder)	Retrieve a new Parcel object from the pool for use with a specific binder.
ReadArray(ClassLoader, Class)	Same as #readArray(ClassLoader) but accepts clazz parameter as the type required for each item.
ReadArray(ClassLoader)	Read and return a new Object array from the parcel at the current dataPosition().
ReadArrayList(ClassLoader, Class)	Same as #readArrayList(ClassLoader) but accepts clazz parameter as the type required for each item.
ReadArrayList(ClassLoader)	Read and return a new ArrayList object from the parcel at the current dataPosition().
ReadBinderArray(IBinder[])
ReadBinderList(IList<IBinder>)	Read into the given List items IBinder objects that were written with #writeBinderList at the current dataPosition().
ReadBlob()	Read a blob of data from the parcel and return it as a byte array.
ReadBoolean()	Read a boolean value from the parcel at the current dataPosition().
ReadBooleanArray(Boolean[])
ReadBundle()	Read and return a new Bundle object from the parcel at the current dataPosition().
ReadBundle(ClassLoader)	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.
ReadByte()	Read a byte value from the parcel at the current dataPosition().
ReadByteArray(Byte[])	Read a byte[] object from the parcel and copy it into the given byte array.
ReadCharArray(Char[])
ReadDouble()	Read a double precision floating point value from the parcel at the current dataPosition().
ReadDoubleArray(Double[])
ReadException()	Special function for reading an exception result from the header of a parcel, to be used after receiving the result of a transaction.
ReadException(Int32, String)	Throw an exception with the given message.
ReadFileDescriptor()	Read a FileDescriptor from the parcel at the current dataPosition().
ReadFixedArray(Object, IFunction)	Read a new multi-dimensional array of typed interfaces from a parcel.
ReadFixedArray(Object, IParcelableCreator)
ReadFixedArray(Object)	Read a new multi-dimensional array from a parcel.
ReadFloat()	Read a floating point value from the parcel at the current dataPosition().
ReadFloatArray(Single[])
ReadHashMap(ClassLoader, Class, Class)	Same as #readHashMap(ClassLoader) but accepts clazzKey and clazzValue parameter as the types required for each key and value pair.
ReadHashMap(ClassLoader)	Please use #readBundle(ClassLoader) instead (whose data must have been written with #writeBundle.
ReadInt()	Read an integer value from the parcel at the current dataPosition().
ReadIntArray(Int32[])
ReadInterfaceArray(Object[], IFunction)	Read an array of T (IInterface) from a parcel.
ReadInterfaceList(IList, IFunction)	Read into the given List items IInterface objects that were written with #writeInterfaceList at the current dataPosition().
ReadList(IList, ClassLoader, Class)	Same as #readList(List, ClassLoader) but accepts clazz parameter as the type required for each item.
ReadList(IList, ClassLoader)	Read into an existing List object from the parcel at the current dataPosition(), using the given class loader to load any enclosed Parcelables.
ReadLong()	Read a long integer value from the parcel at the current dataPosition().
ReadLongArray(Int64[])
ReadMap(IDictionary, ClassLoader, Class, Class)	Same as #readMap(Map, ClassLoader) but accepts clazzKey and clazzValue parameter as the types required for each key and value pair.
ReadMap(IDictionary, ClassLoader)	Please use #readBundle(ClassLoader) instead (whose data must have been written with #writeBundle.
ReadParcelable(ClassLoader, Class)	Same as #readParcelable(ClassLoader) but accepts clazz parameter as the type required for each item.
ReadParcelable(ClassLoader)	Read and return a new Parcelable from the parcel.
ReadParcelableArray(ClassLoader, Class)	Same as #readParcelableArray(ClassLoader) but accepts clazz parameter as the type required for each item.
ReadParcelableArray(ClassLoader)	Read and return a new Parcelable array from the parcel.
ReadParcelableCreator(ClassLoader, Class)
ReadParcelableCreator(ClassLoader)	Read and return a Parcelable.
ReadParcelableList(IList, ClassLoader, Class)	Same as #readParcelableList(List, ClassLoader) but accepts clazz parameter as the type required for each item.
ReadParcelableList(IList, ClassLoader)	Read the list of Parcelable objects at the current data position into the given list.
ReadPersistableBundle()	Read and return a new Bundle object from the parcel at the current dataPosition().
ReadPersistableBundle(ClassLoader)	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.
ReadSerializable()	Read and return a new Serializable object from the parcel.
ReadSerializable(ClassLoader, Class)	Same as #readSerializable() but accepts loader and clazz parameters.
ReadSize()	Read a Size from the parcel at the current dataPosition().
ReadSizeF()	Read a SizeF from the parcel at the current dataPosition().
ReadSparseArray(ClassLoader, Class)	Same as #readSparseArray(ClassLoader) but accepts clazz parameter as the type required for each item.
ReadSparseArray(ClassLoader)	Read and return a new SparseArray object from the parcel at the current dataPosition().
ReadSparseBooleanArray()	Read and return a new SparseBooleanArray object from the parcel at the current dataPosition().
ReadString()	Read a string value from the parcel at the current dataPosition().
ReadStringArray(String[])
ReadStringList(IList<String>)	Read into the given List items String objects that were written with #writeStringList at the current dataPosition().
ReadStrongBinder()	Read an object from the parcel at the current dataPosition().
ReadTypedArray(Object[], IParcelableCreator)
ReadTypedList(IList, IParcelableCreator)	Read into the given List items containing a particular object type that were written with #writeTypedList at the current dataPosition().
ReadTypedObject(IParcelableCreator)	Read and return a typed Parcelable object from a parcel.
ReadValue(ClassLoader)	Read a typed object from a parcel.
Recycle()	Put a Parcel object back into the pool.
SetDataCapacity(Int32)	Change the capacity (current available space) of the parcel.
SetDataPosition(Int32)	Move the current read/write position in the parcel.
SetDataSize(Int32)	Change the amount of data in the parcel.
SetHandle(IntPtr, JniHandleOwnership)	Sets the Handle property. (Inherited from Object)
SetPropagateAllowBlocking()	This method is used by the AIDL compiler for system components.
ToArray<T>()	(Inherited from Object)
ToString()	Returns a string representation of the object. (Inherited from Object)
Unmarshall(Byte[], Int32, Int32)	Fills the raw bytes of this Parcel with the supplied data.
UnregisterFromRuntime()	(Inherited from Object)
Wait()	Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>. (Inherited from Object)
Wait(Int64, Int32)	Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object)
Wait(Int64)	Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object)
WriteArray(Object[])	Flatten an Object array into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteBinderArray(IBinder[])
WriteBinderList(IList<IBinder>)	Flatten a List containing IBinder objects into the parcel, at the current dataPosition() and growing dataCapacity() if needed.
WriteBlob(Byte[], Int32, Int32)	Write a blob of data into the parcel at the current #dataPosition, growing #dataCapacity if needed.
WriteBlob(Byte[])	Write a blob of data into the parcel at the current #dataPosition, growing #dataCapacity if needed.
WriteBoolean(Boolean)	Write a boolean value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteBooleanArray(Boolean[])
WriteBundle(Bundle)	Flatten a Bundle into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteByte(SByte)	Write a byte value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteByteArray(Byte[], Int32, Int32)	Write a byte array into the parcel at the current #dataPosition, growing #dataCapacity if needed.
WriteByteArray(Byte[])	Write a byte array into the parcel at the current #dataPosition, growing #dataCapacity if needed.
WriteCharArray(Char[])
WriteDouble(Double)	Write a double precision floating point value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteDoubleArray(Double[])
WriteException(Exception)	Special function for writing an exception result at the header of a parcel, to be used when returning an exception from a transaction.
WriteFileDescriptor(FileDescriptor)	Write a FileDescriptor into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteFixedArray(Object, Int32, Int32[])	Flatten a homogeneous multi-dimensional array with fixed-size.
WriteFloat(Single)	Write a floating point value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteFloatArray(Single[])
WriteInt(Int32)	Write an integer value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteIntArray(Int32[])
WriteInterfaceArray(Object[])	Flatten a homogeneous array containing an IInterface type into the parcel, at the current dataPosition() and growing dataCapacity() if needed.
WriteInterfaceList(IList)	Flatten a List containing T (IInterface) objects into this parcel at the current position.
WriteInterfaceToken(String)	Store or read an IBinder interface token in the parcel at the current #dataPosition.
WriteList(IList)	Flatten a List into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteLong(Int64)	Write a long integer value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteLongArray(Int64[])
WriteMap(IDictionary)	Please use #writeBundle instead.
WriteNoException()	Special function for writing information at the front of the Parcel indicating that no exception occurred.
WriteParcelable(IParcelable, ParcelableWriteFlags)	Flatten the name of the class of the Parcelable and its contents into the parcel.
WriteParcelableArray(Object[], ParcelableWriteFlags)	Write a heterogeneous array of Parcelable objects into the Parcel.
WriteParcelableCreator(IParcelable)	Flatten the name of the class of the Parcelable into this Parcel.
WriteParcelableList(IList, Int32)	Flatten a List containing arbitrary Parcelable objects into this parcel at the current position.
WritePersistableBundle(PersistableBundle)	Flatten a PersistableBundle into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteSerializable(ISerializable)	Write a generic serializable object in to a Parcel.
WriteSize(Size)	Flatten a Size into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteSizeF(SizeF)	Flatten a SizeF into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteSparseArray(SparseArray)	Flatten a generic SparseArray into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteSparseBooleanArray(SparseBooleanArray)
WriteString(String)	Write a string value into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteStringArray(String[])
WriteStringList(IList<String>)	Flatten a List containing String objects into the parcel, at the current dataPosition() and growing dataCapacity() if needed.
WriteStrongBinder(IBinder)	Write an object into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteStrongInterface(IInterface)	Write an object into the parcel at the current dataPosition(), growing dataCapacity() if needed.
WriteTypedArray(Object[], ParcelableWriteFlags)	Flatten a homogeneous array containing a particular object type into the parcel, at the current dataPosition() and growing dataCapacity() if needed.
WriteTypedArrayMap(ArrayMap, Int32)	Flatten an ArrayMap with string keys containing a particular object type into the parcel at the current dataPosition() and growing dataCapacity() if needed.
WriteTypedList(IList, ParcelableWriteFlags)	Flatten a List containing a particular object type into the parcel, at the current dataPosition() and growing dataCapacity() if needed.
WriteTypedList(IList)	Flatten a List containing a particular object type into the parcel, at the current dataPosition() and growing dataCapacity() if needed.
WriteTypedObject(Object, ParcelableWriteFlags)	Flatten the Parcelable object into the parcel.
WriteTypedSparseArray(SparseArray, Int32)	Flatten a SparseArray containing a particular object type into the parcel at the current dataPosition() and growing dataCapacity() if needed.
WriteValue(Object)	Flatten a generic object in to a parcel.

Explicit Interface Implementations

IJavaPeerable.Disposed()	(Inherited from Object)
IJavaPeerable.DisposeUnlessReferenced()	(Inherited from Object)
IJavaPeerable.Finalized()	(Inherited from Object)
IJavaPeerable.JniManagedPeerState	(Inherited from Object)
IJavaPeerable.SetJniIdentityHashCode(Int32)	(Inherited from Object)
IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates)	(Inherited from Object)
IJavaPeerable.SetPeerReference(JniObjectReference)	(Inherited from Object)

Extension Methods

JavaCast<TResult>(IJavaObject)	Performs an Android runtime-checked type conversion.
JavaCast<TResult>(IJavaObject)
GetJniTypeName(IJavaPeerable)