Struct Parcel

pub struct Parcel { /* private fields */ }

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

A Parcel can contain both serialized data that will be deserialized on the other side of the IPC, and references to live Binder objects that will result in the other side receiving a proxy Binder connected with the original Binder in the Parcel.

This type represents a parcel that is owned by Rust code.

Implementations

impl Parcel

pub fn new() -> Parcel

Create a new empty Parcel.

pub unsafe fn from_raw(ptr: *mut AParcel) -> Option<Parcel>

Create an owned reference to a parcel object from a raw pointer.

Safety

This constructor is safe if the raw pointer parameter is either null (resulting in None), or a valid pointer to an AParcel object. The parcel object must be owned by the caller prior to this call, as this constructor takes ownership of the parcel and will destroy it on drop.

Additionally, the caller must guarantee that it is valid to take ownership of the AParcel object. All future access to the AParcel must happen through this Parcel.

Because Parcel implements Send, the pointer must never point to any thread-local data, e.g., a variable on the stack, either directly or indirectly.

pub fn borrowed(&mut self) -> BorrowedParcel<'_>

Get a borrowed view into the contents of this Parcel.

pub fn borrowed_ref(&self) -> &BorrowedParcel<'_>

Get an immutable borrowed view into the contents of this Parcel.

impl Parcel

pub fn mark_sensitive(&mut self)

Data written to parcelable is zero’d before being deleted or reallocated.

pub fn write<S: Serialize + ?Sized>( &mut self, parcelable: &S, ) -> Result<(), StatusCode>

Write a type that implements Serialize to the parcel.

pub fn write_slice_size<T>( &mut self, slice: Option<&[T]>, ) -> Result<(), StatusCode>

Writes the length of a slice to the parcel.

This is used in AIDL-generated client side code to indicate the allocated space for an output array parameter.

pub fn sized_write<F>(&mut self, f: F) -> Result<(), StatusCode>

where for<'b> F: FnOnce(&'b mut WritableSubParcel<'b>) -> Result<(), StatusCode>,

Perform a series of writes to the parcel, prepended with the length (in bytes) of the written data.

The length 0i32 will be written to the parcel first, followed by the writes performed by the callback. The initial length will then be updated to the length of all data written by the callback, plus the size of the length elemement itself (4 bytes).

Examples

After the following call:

parcel.sized_write(|subparcel| {
    subparcel.write(&1u32)?;
    subparcel.write(&2u32)?;
    subparcel.write(&3u32)
});

parcel will contain the following:

[16i32, 1u32, 2u32, 3u32]

pub fn get_data_position(&self) -> i32

Returns the current position in the parcel data.

pub fn get_data_size(&self) -> i32

Returns the total size of the parcel.

pub unsafe fn set_data_position(&self, pos: i32) -> Result<(), StatusCode>

Move the current read/write position in the parcel.

Safety

This method is safe if pos is less than the current size of the parcel data buffer. Otherwise, we are relying on correct bounds checking in the Parcel C++ code on every subsequent read or write to this parcel. If all accesses are bounds checked, this call is still safe, but we can’t rely on that.

pub fn append_from( &mut self, other: &impl AsNative<AParcel>, start: i32, size: i32, ) -> Result<(), StatusCode>

Append a subset of another parcel.

This appends size bytes of data from other starting at offset start to the current parcel, or returns an error if not possible.

pub fn append_all_from( &mut self, other: &impl AsNative<AParcel>, ) -> Result<(), StatusCode>

Append the contents of another parcel.

impl Parcel

pub fn read<D: Deserialize>(&self) -> Result<D, StatusCode>

Attempt to read a type that implements Deserialize from this parcel.

pub fn read_onto<D: Deserialize>(&self, x: &mut D) -> Result<(), StatusCode>

Attempt to read a type that implements Deserialize from this parcel onto an existing value. This operation will overwrite the old value partially or completely, depending on how much data is available.

pub fn sized_read<F>(&self, f: F) -> Result<(), StatusCode>

where for<'b> F: FnOnce(ReadableSubParcel<'b>) -> Result<(), StatusCode>,

Safely read a sized parcelable.

Read the size of a parcelable, compute the end position of that parcelable, then build a sized readable sub-parcel and call a closure with the sub-parcel as its parameter. The closure can keep reading data from the sub-parcel until it runs out of input data. The closure is responsible for calling ReadableSubParcel::has_more_data to check for more data before every read, at least until Rust generators are stabilized. After the closure returns, skip to the end of the current parcelable regardless of how much the closure has read.

Examples

let mut parcelable = Default::default();
parcel.sized_read(|subparcel| {
    if subparcel.has_more_data() {
        parcelable.a = subparcel.read()?;
    }
    if subparcel.has_more_data() {
        parcelable.b = subparcel.read()?;
    }
    Ok(())
});

pub fn resize_out_vec<D: Default + Deserialize>( &self, out_vec: &mut Vec<D>, ) -> Result<(), StatusCode>

Read a vector size from the parcel and resize the given output vector to be correctly sized for that amount of data.

This method is used in AIDL-generated server side code for methods that take a mutable slice reference parameter.

pub fn resize_nullable_out_vec<D: Default + Deserialize>( &self, out_vec: &mut Option<Vec<D>>, ) -> Result<(), StatusCode>

Read a vector size from the parcel and either create a correctly sized vector for that amount of data or set the output parameter to None if the vector should be null.

This method is used in AIDL-generated server side code for methods that take a mutable slice reference parameter.

Trait Implementations

impl Clone for Parcel

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Parcel

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Parcel

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Parcel

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Parcel

Safety: This type guarantees that it owns the AParcel and that all access to the AParcel happens through the Parcel, so it is ok to send across threads.

It would not be okay to implement Sync, because that would allow you to call the reading methods from several threads in parallel, which would be a data race on the cursor position inside the AParcel.