libbinder*: clarify setDataPosition constraints
Documenting constraints on the setDataPosition API. This is how it
is currently used, and adding checks before any write, to validate
objects would be expensive/complex.
Fixes: 232463516
Test: N/A
Change-Id: I5d3c8918e6389d3506ef0b97393be31e4cbe0b70
diff --git a/libs/binder/include/binder/Parcel.h b/libs/binder/include/binder/Parcel.h
index e2b2c51..39d0c90 100644
--- a/libs/binder/include/binder/Parcel.h
+++ b/libs/binder/include/binder/Parcel.h
@@ -76,6 +76,11 @@
size_t dataCapacity() const;
status_t setDataSize(size_t size);
+
+ // this must only be used to set a data position that was previously returned from
+ // dataPosition(). If writes are made, the exact same types of writes must be made (e.g.
+ // auto i = p.dataPosition(); p.writeInt32(0); p.setDataPosition(i); p.writeInt32(1);).
+ // Writing over objects, such as file descriptors and binders, is not supported.
void setDataPosition(size_t pos) const;
status_t setDataCapacity(size_t size);
diff --git a/libs/binder/ndk/include_ndk/android/binder_parcel.h b/libs/binder/ndk/include_ndk/android/binder_parcel.h
index 8457581..f68612c 100644
--- a/libs/binder/ndk/include_ndk/android/binder_parcel.h
+++ b/libs/binder/ndk/include_ndk/android/binder_parcel.h
@@ -59,6 +59,11 @@
/**
* Sets the position within the parcel.
*
+ * This must be called with a position that has been previously returned from
+ * AParcel_getDataPosition. If writes are made after setting the data position, they must
+ * be made in the exact same sequence used before resetting data position. Writing over
+ * objects such as binders or file descriptors is not supported.
+ *
* Available since API level 29.
*
* \param parcel The parcel of which to set the position.