1 /* 2 * Copyright (C) 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * @addtogroup NdkBinder 19 * @{ 20 */ 21 22 /** 23 * @file binder_parcel.h 24 * @brief A collection of data that can be sent as a single packet. 25 */ 26 27 #pragma once 28 29 #include <android/binder_status.h> 30 #include <stdbool.h> 31 #include <stddef.h> 32 #include <sys/cdefs.h> 33 #include <uchar.h> 34 35 struct AIBinder; 36 typedef struct AIBinder AIBinder; 37 38 __BEGIN_DECLS 39 40 /** 41 * This object represents a package of data that can be sent between processes. When transacting, an 42 * instance of it is automatically created to be used for the transaction. When two processes use 43 * binder to communicate, they must agree on a format of this parcel to be used in order to transfer 44 * data. This is usually done in an IDL (see AIDL, specificially). 45 */ 46 struct AParcel; 47 typedef struct AParcel AParcel; 48 49 /** 50 * Cleans up a parcel. 51 * 52 * Available since API level 29. 53 * 54 * \param parcel A parcel returned by AIBinder_prepareTransaction or AIBinder_transact when a 55 * transaction is being aborted. 56 */ 57 void AParcel_delete(AParcel* parcel) __INTRODUCED_IN(29); 58 59 /** 60 * Sets the position within the parcel. 61 * 62 * This must be called with a position that has been previously returned from 63 * AParcel_getDataPosition. If writes are made after setting the data position, they must 64 * be made in the exact same sequence used before resetting data position. Writing over 65 * objects such as binders or file descriptors is not supported. 66 * 67 * Available since API level 29. 68 * 69 * \param parcel The parcel of which to set the position. 70 * \param position Position of the parcel to set. This must be a value returned by 71 * AParcel_getDataPosition. Positions are constant for a given parcel between processes. 72 * 73 * \return STATUS_OK on success. If position is negative, then STATUS_BAD_VALUE will be returned. 74 */ 75 binder_status_t AParcel_setDataPosition(const AParcel* parcel, int32_t position) 76 __INTRODUCED_IN(29); 77 78 /** 79 * Gets the current position within the parcel. 80 * 81 * Available since API level 29. 82 * 83 * \param parcel The parcel of which to get the position. 84 * 85 * \return The size of the parcel. This will always be greater than 0. The values returned by this 86 * function before and after calling various reads and writes are not defined. Only the delta 87 * between two positions between a specific sequence of calls is defined. For instance, if position 88 * is X, writeBool is called, and then position is Y, readBool can be called from position X will 89 * return the same value, and then position will be Y. 90 */ 91 int32_t AParcel_getDataPosition(const AParcel* parcel) __INTRODUCED_IN(29); 92 93 /** 94 * This is called to allocate a buffer for a C-style string (null-terminated). The returned buffer 95 * should be at least length bytes. This includes space for a null terminator. For a string, length 96 * will always be strictly less than or equal to the maximum size that can be held in a size_t and 97 * will always be greater than 0. However, if a 'null' string is being read, length will be -1. 98 * 99 * See also AParcel_readString. 100 * 101 * If allocation fails, null should be returned. 102 * 103 * \param stringData some external representation of a string 104 * \param length the length of the buffer needed to fill (including the null-terminator) 105 * \param buffer a buffer of size 'length' or null if allocation failed. 106 * 107 * \return true if the allocation succeeded, false otherwise. If length is -1, a true return here 108 * means that a 'null' value (or equivalent) was successfully stored. 109 */ 110 typedef bool (*AParcel_stringAllocator)(void* stringData, int32_t length, char** buffer); 111 112 /** 113 * This is called to allocate an array of size 'length'. If length is -1, then a 'null' array (or 114 * equivalent) should be created. 115 * 116 * See also AParcel_readStringArray 117 * 118 * \param arrayData some external representation of an array 119 * \param length the length to allocate this array to 120 * 121 * \return true if allocation succeeded. If length is -1, a true return here means that a 'null' 122 * value (or equivalent) was successfully stored. 123 */ 124 typedef bool (*AParcel_stringArrayAllocator)(void* arrayData, int32_t length); 125 126 /** 127 * This is called to allocate a string inside of an array that was allocated by an 128 * AParcel_stringArrayAllocator. 129 * 130 * The index returned will always be within the range [0, length of arrayData). The returned buffer 131 * should be at least length bytes. This includes space for a null-terminator. For a string, length 132 * will always be strictly less than or equal to the maximum size that can be held in a size_t and 133 * will always be greater than 0. However, if a 'null' string is being read, length will be -1. 134 * 135 * See also AParcel_readStringArray 136 * 137 * \param arrayData some external representation of an array. 138 * \param index the index at which a string should be allocated. 139 * \param length the length of the string to be allocated at this index. See also 140 * AParcel_stringAllocator. This includes the length required for a null-terminator. 141 * \param buffer a buffer of size 'length' or null if allocation failed. 142 * 143 * \return true if the allocation succeeded, false otherwise. If length is -1, a true return here 144 * means that a 'null' value (or equivalent) was successfully stored. 145 */ 146 typedef bool (*AParcel_stringArrayElementAllocator)(void* arrayData, size_t index, int32_t length, 147 char** buffer); 148 149 /** 150 * This returns the length and buffer of an array at a specific index in an arrayData object. 151 * 152 * See also AParcel_writeStringArray 153 * 154 * \param arrayData some external representation of an array. 155 * \param index the index at which a string should be allocated. 156 * \param outLength an out parameter for the length of the string at the specified index. This 157 * should not include the length for a null-terminator if there is one. If the object at this index 158 * is 'null', then this should be set to -1. 159 * 160 * \param a buffer of size outLength or more representing the string at the provided index. This is 161 * not required to be null-terminated. If the object at index is null, then this should be null. 162 */ 163 typedef const char* (*AParcel_stringArrayElementGetter)(const void* arrayData, size_t index, 164 int32_t* outLength); 165 166 /** 167 * This is called to allocate an array of size 'length'. If length is -1, then a 'null' array (or 168 * equivalent) should be created. 169 * 170 * See also AParcel_readParcelableArray 171 * 172 * \param arrayData some external representation of an array 173 * \param length the length to allocate this array to 174 * 175 * \return true if allocation succeeded. If length is -1, a true return here means that a 'null' 176 * value (or equivalent) was successfully stored. 177 */ 178 typedef bool (*AParcel_parcelableArrayAllocator)(void* arrayData, int32_t length); 179 180 /** 181 * This is called to parcel the underlying data from an arrayData object at index. 182 * 183 * See also AParcel_writeParcelableArray 184 * 185 * \param parcel parcel to write the parcelable to 186 * \param arrayData some external representation of an array of parcelables (a user-defined type). 187 * \param index the index of the value to be retrieved. 188 * 189 * \return status (usually returned from other parceling functions). STATUS_OK for success. 190 */ 191 typedef binder_status_t (*AParcel_writeParcelableElement)(AParcel* parcel, const void* arrayData, 192 size_t index); 193 194 /** 195 * This is called to set an underlying value in an arrayData object at index. 196 * 197 * See also AParcel_readParcelableArray 198 * 199 * \param parcel parcel to read the parcelable from 200 * \param arrayData some external representation of an array of parcelables (a user-defined type). 201 * \param index the index of the value to be set. 202 * 203 * \return status (usually returned from other parceling functions). STATUS_OK for success. 204 */ 205 typedef binder_status_t (*AParcel_readParcelableElement)(const AParcel* parcel, void* arrayData, 206 size_t index); 207 208 // @START-PRIMITIVE-VECTOR-GETTERS 209 /** 210 * This is called to get the underlying data from an arrayData object. 211 * 212 * The implementation of this function should allocate a contiguous array of size 'length' and 213 * return that underlying buffer to be filled out. If there is an error or length is 0, null may be 214 * returned. If length is -1, this should allocate some representation of a null array. 215 * 216 * See also AParcel_readInt32Array 217 * 218 * \param arrayData some external representation of an array of int32_t. 219 * \param length the length to allocate arrayData to. 220 * \param outBuffer a buffer of int32_t of size 'length' (if length is >= 0, if length is 0, this 221 * may be nullptr). 222 * 223 * \return whether or not the allocation was successful (or whether a null array is represented when 224 * length is -1). 225 */ 226 typedef bool (*AParcel_int32ArrayAllocator)(void* arrayData, int32_t length, int32_t** outBuffer); 227 228 /** 229 * This is called to get the underlying data from an arrayData object. 230 * 231 * The implementation of this function should allocate a contiguous array of size 'length' and 232 * return that underlying buffer to be filled out. If there is an error or length is 0, null may be 233 * returned. If length is -1, this should allocate some representation of a null array. 234 * 235 * See also AParcel_readUint32Array 236 * 237 * \param arrayData some external representation of an array of uint32_t. 238 * \param length the length to allocate arrayData to. 239 * \param outBuffer a buffer of uint32_t of size 'length' (if length is >= 0, if length is 0, this 240 * may be nullptr). 241 * 242 * \return whether or not the allocation was successful (or whether a null array is represented when 243 * length is -1). 244 */ 245 typedef bool (*AParcel_uint32ArrayAllocator)(void* arrayData, int32_t length, uint32_t** outBuffer); 246 247 /** 248 * This is called to get the underlying data from an arrayData object. 249 * 250 * The implementation of this function should allocate a contiguous array of size 'length' and 251 * return that underlying buffer to be filled out. If there is an error or length is 0, null may be 252 * returned. If length is -1, this should allocate some representation of a null array. 253 * 254 * See also AParcel_readInt64Array 255 * 256 * \param arrayData some external representation of an array of int64_t. 257 * \param length the length to allocate arrayData to. 258 * \param outBuffer a buffer of int64_t of size 'length' (if length is >= 0, if length is 0, this 259 * may be nullptr). 260 * 261 * \return whether or not the allocation was successful (or whether a null array is represented when 262 * length is -1). 263 */ 264 typedef bool (*AParcel_int64ArrayAllocator)(void* arrayData, int32_t length, int64_t** outBuffer); 265 266 /** 267 * This is called to get the underlying data from an arrayData object. 268 * 269 * The implementation of this function should allocate a contiguous array of size 'length' and 270 * return that underlying buffer to be filled out. If there is an error or length is 0, null may be 271 * returned. If length is -1, this should allocate some representation of a null array. 272 * 273 * See also AParcel_readUint64Array 274 * 275 * \param arrayData some external representation of an array of uint64_t. 276 * \param length the length to allocate arrayData to. 277 * \param outBuffer a buffer of uint64_t of size 'length' (if length is >= 0, if length is 0, this 278 * may be nullptr). 279 * 280 * \return whether or not the allocation was successful (or whether a null array is represented when 281 * length is -1). 282 */ 283 typedef bool (*AParcel_uint64ArrayAllocator)(void* arrayData, int32_t length, uint64_t** outBuffer); 284 285 /** 286 * This is called to get the underlying data from an arrayData object. 287 * 288 * The implementation of this function should allocate a contiguous array of size 'length' and 289 * return that underlying buffer to be filled out. If there is an error or length is 0, null may be 290 * returned. If length is -1, this should allocate some representation of a null array. 291 * 292 * See also AParcel_readFloatArray 293 * 294 * \param arrayData some external representation of an array of float. 295 * \param length the length to allocate arrayData to. 296 * \param outBuffer a buffer of float of size 'length' (if length is >= 0, if length is 0, this may 297 * be nullptr). 298 * 299 * \return whether or not the allocation was successful (or whether a null array is represented when 300 * length is -1). 301 */ 302 typedef bool (*AParcel_floatArrayAllocator)(void* arrayData, int32_t length, float** outBuffer); 303 304 /** 305 * This is called to get the underlying data from an arrayData object. 306 * 307 * The implementation of this function should allocate a contiguous array of size 'length' and 308 * return that underlying buffer to be filled out. If there is an error or length is 0, null may be 309 * returned. If length is -1, this should allocate some representation of a null array. 310 * 311 * See also AParcel_readDoubleArray 312 * 313 * \param arrayData some external representation of an array of double. 314 * \param length the length to allocate arrayData to. 315 * \param outBuffer a buffer of double of size 'length' (if length is >= 0, if length is 0, this may 316 * be nullptr). 317 * 318 * \return whether or not the allocation was successful (or whether a null array is represented when 319 * length is -1). 320 */ 321 typedef bool (*AParcel_doubleArrayAllocator)(void* arrayData, int32_t length, double** outBuffer); 322 323 /** 324 * This allocates an array of size 'length' inside of arrayData and returns whether or not there was 325 * a success. If length is -1, then this should allocate some representation of a null array. 326 * 327 * See also AParcel_readBoolArray 328 * 329 * \param arrayData some external representation of an array of bool. 330 * \param length the length to allocate arrayData to (or -1 if this represents a null array). 331 * 332 * \return whether the allocation succeeded. 333 */ 334 typedef bool (*AParcel_boolArrayAllocator)(void* arrayData, int32_t length); 335 336 /** 337 * This is called to get the underlying data from an arrayData object at index. 338 * 339 * See also AParcel_writeBoolArray 340 * 341 * \param arrayData some external representation of an array of bool. 342 * \param index the index of the value to be retrieved. 343 * 344 * \return the value of the array at index index. 345 */ 346 typedef bool (*AParcel_boolArrayGetter)(const void* arrayData, size_t index); 347 348 /** 349 * This is called to set an underlying value in an arrayData object at index. 350 * 351 * See also AParcel_readBoolArray 352 * 353 * \param arrayData some external representation of an array of bool. 354 * \param index the index of the value to be set. 355 * \param value the value to set at index index. 356 */ 357 typedef void (*AParcel_boolArraySetter)(void* arrayData, size_t index, bool value); 358 359 /** 360 * This is called to get the underlying data from an arrayData object. 361 * 362 * The implementation of this function should allocate a contiguous array of size 'length' and 363 * return that underlying buffer to be filled out. If there is an error or length is 0, null may be 364 * returned. If length is -1, this should allocate some representation of a null array. 365 * 366 * See also AParcel_readCharArray 367 * 368 * \param arrayData some external representation of an array of char16_t. 369 * \param length the length to allocate arrayData to. 370 * \param outBuffer a buffer of char16_t of size 'length' (if length is >= 0, if length is 0, this 371 * may be nullptr). 372 * 373 * \return whether or not the allocation was successful (or whether a null array is represented when 374 * length is -1). 375 */ 376 typedef bool (*AParcel_charArrayAllocator)(void* arrayData, int32_t length, char16_t** outBuffer); 377 378 /** 379 * This is called to get the underlying data from an arrayData object. 380 * 381 * The implementation of this function should allocate a contiguous array of size 'length' and 382 * return that underlying buffer to be filled out. If there is an error or length is 0, null may be 383 * returned. If length is -1, this should allocate some representation of a null array. 384 * 385 * See also AParcel_readByteArray 386 * 387 * \param arrayData some external representation of an array of int8_t. 388 * \param length the length to allocate arrayData to. 389 * \param outBuffer a buffer of int8_t of size 'length' (if length is >= 0, if length is 0, this may 390 * be nullptr). 391 * 392 * \return whether or not the allocation was successful (or whether a null array is represented when 393 * length is -1). 394 */ 395 typedef bool (*AParcel_byteArrayAllocator)(void* arrayData, int32_t length, int8_t** outBuffer); 396 397 // @END-PRIMITIVE-VECTOR-GETTERS 398 399 /** 400 * Writes an AIBinder to the next location in a non-null parcel. Can be null. This does not take any 401 * refcounts of ownership of the binder from the client. 402 * 403 * Available since API level 29. 404 * 405 * \param parcel the parcel to write to. 406 * \param binder the value to write to the parcel. 407 * 408 * \return STATUS_OK on successful write. 409 */ 410 binder_status_t AParcel_writeStrongBinder(AParcel* parcel, AIBinder* binder) __INTRODUCED_IN(29); 411 412 /** 413 * Reads an AIBinder from the next location in a non-null parcel. One strong ref-count of ownership 414 * is passed to the caller of this function. 415 * 416 * Available since API level 29. 417 * 418 * \param parcel the parcel to read from. 419 * \param binder the out parameter for what is read from the parcel. This may be null. 420 * 421 * \return STATUS_OK on successful write. 422 */ 423 binder_status_t AParcel_readStrongBinder(const AParcel* parcel, AIBinder** binder) 424 __INTRODUCED_IN(29); 425 426 /** 427 * Writes a file descriptor to the next location in a non-null parcel. This does not take ownership 428 * of fd. 429 * 430 * This corresponds to the SDK's android.os.ParcelFileDescriptor. 431 * 432 * Available since API level 29. 433 * 434 * \param parcel the parcel to write to. 435 * \param fd the value to write to the parcel (-1 to represent a null ParcelFileDescriptor). 436 * 437 * \return STATUS_OK on successful write. 438 */ 439 binder_status_t AParcel_writeParcelFileDescriptor(AParcel* parcel, int fd) __INTRODUCED_IN(29); 440 441 /** 442 * Reads an int from the next location in a non-null parcel. 443 * 444 * The returned fd must be closed. 445 * 446 * This corresponds to the SDK's android.os.ParcelFileDescriptor. 447 * 448 * Available since API level 29. 449 * 450 * \param parcel the parcel to read from. 451 * \param fd the out parameter for what is read from the parcel (or -1 to represent a null 452 * ParcelFileDescriptor) 453 * 454 * \return STATUS_OK on successful write. 455 */ 456 binder_status_t AParcel_readParcelFileDescriptor(const AParcel* parcel, int* fd) 457 __INTRODUCED_IN(29); 458 459 /** 460 * Writes an AStatus object to the next location in a non-null parcel. 461 * 462 * If the status is considered to be a low-level status and has no additional information other 463 * than a binder_status_t (for instance, if it is created with AStatus_fromStatus), then that 464 * status will be returned from this method and nothing will be written to the parcel. If either 465 * this happens or if writing the status object itself fails, the return value from this function 466 * should be propagated to the client, and AParcel_readStatusHeader shouldn't be called. 467 * 468 * Available since API level 29. 469 * 470 * \param parcel the parcel to write to. 471 * \param status the value to write to the parcel. 472 * 473 * \return STATUS_OK on successful write. 474 */ 475 binder_status_t AParcel_writeStatusHeader(AParcel* parcel, const AStatus* status) 476 __INTRODUCED_IN(29); 477 478 /** 479 * Reads an AStatus from the next location in a non-null parcel. Ownership is passed to the caller 480 * of this function. 481 * 482 * Available since API level 29. 483 * 484 * \param parcel the parcel to read from. 485 * \param status the out parameter for what is read from the parcel. 486 * 487 * \return STATUS_OK on successful write. 488 */ 489 binder_status_t AParcel_readStatusHeader(const AParcel* parcel, AStatus** status) 490 __INTRODUCED_IN(29); 491 492 /** 493 * Writes utf-8 string value to the next location in a non-null parcel. 494 * 495 * If length is -1, and string is nullptr, this will write a 'null' string to the parcel. 496 * 497 * Available since API level 29. 498 * 499 * \param parcel the parcel to write to. 500 * \param string the null-terminated string to write to the parcel, at least of size 'length'. 501 * \param length the length of the string to be written. 502 * 503 * \return STATUS_OK on successful write. 504 */ 505 binder_status_t AParcel_writeString(AParcel* parcel, const char* string, int32_t length) 506 __INTRODUCED_IN(29); 507 508 /** 509 * Reads and allocates utf-8 string value from the next location in a non-null parcel. 510 * 511 * Data is passed to the string allocator once the string size is known. This size includes the 512 * space for the null-terminator of this string. This allocator returns a buffer which is used as 513 * the output buffer from this read. If there is a 'null' string on the binder buffer, the allocator 514 * will be called with length -1. 515 * 516 * Available since API level 29. 517 * 518 * \param parcel the parcel to read from. 519 * \param stringData some external representation of a string. 520 * \param allocator allocator that will be called once the size of the string is known. 521 * 522 * \return STATUS_OK on successful write. 523 */ 524 binder_status_t AParcel_readString(const AParcel* parcel, void* stringData, 525 AParcel_stringAllocator allocator) __INTRODUCED_IN(29); 526 527 /** 528 * Writes utf-8 string array data to the next location in a non-null parcel. 529 * 530 * length is the length of the array. AParcel_stringArrayElementGetter will be called for all 531 * indices in range [0, length) with the arrayData provided here. The string length and buffer 532 * returned from this function will be used to fill out the data from the parcel. If length is -1, 533 * this will write a 'null' string array to the binder buffer. 534 * 535 * Available since API level 29. 536 * 537 * \param parcel the parcel to write to. 538 * \param arrayData some external representation of an array. 539 * \param length the length of the array to be written. 540 * \param getter the callback that will be called for every index of the array to retrieve the 541 * corresponding string buffer. 542 * 543 * \return STATUS_OK on successful write. 544 */ 545 binder_status_t AParcel_writeStringArray(AParcel* parcel, const void* arrayData, int32_t length, 546 AParcel_stringArrayElementGetter getter) 547 __INTRODUCED_IN(29); 548 549 /** 550 * Reads and allocates utf-8 string array value from the next location in a non-null parcel. 551 * 552 * First, AParcel_stringArrayAllocator will be called with the size of the array to be read where 553 * length is the length of the array to be read from the parcel. Then, for each index i in [0, 554 * length), AParcel_stringArrayElementAllocator will be called with the length of the string to be 555 * read from the parcel. The resultant buffer from each of these calls will be filled according to 556 * the contents of the string that is read. If the string array being read is 'null', this will 557 * instead just pass -1 to AParcel_stringArrayAllocator. 558 * 559 * Available since API level 29. 560 * 561 * \param parcel the parcel to read from. 562 * \param arrayData some external representation of an array. 563 * \param allocator the callback that will be called with arrayData once the size of the output 564 * array is known. 565 * \param elementAllocator the callback that will be called on every index of arrayData to allocate 566 * the string at that location. 567 * 568 * \return STATUS_OK on successful read. 569 */ 570 binder_status_t AParcel_readStringArray(const AParcel* parcel, void* arrayData, 571 AParcel_stringArrayAllocator allocator, 572 AParcel_stringArrayElementAllocator elementAllocator) 573 __INTRODUCED_IN(29); 574 575 /** 576 * Writes an array of parcelables (user-defined types) to the next location in a non-null parcel. 577 * 578 * Available since API level 29. 579 * 580 * \param parcel the parcel to write to. 581 * \param arrayData an array of size 'length' (or null if length is -1, may be null if length is 0). 582 * \param length the length of arrayData or -1 if this represents a null array. 583 * \param elementWriter function to be called for every array index to write the user-defined type 584 * at that location. 585 * 586 * \return STATUS_OK on successful write. 587 */ 588 binder_status_t AParcel_writeParcelableArray(AParcel* parcel, const void* arrayData, int32_t length, 589 AParcel_writeParcelableElement elementWriter) 590 __INTRODUCED_IN(29); 591 592 /** 593 * Reads an array of parcelables (user-defined types) from the next location in a non-null parcel. 594 * 595 * First, allocator will be called with the length of the array. If the allocation succeeds and the 596 * length is greater than zero, elementReader will be called for every index to read the 597 * corresponding parcelable. 598 * 599 * Available since API level 29. 600 * 601 * \param parcel the parcel to read from. 602 * \param arrayData some external representation of an array. 603 * \param allocator the callback that will be called to allocate the array. 604 * \param elementReader the callback that will be called to fill out individual elements. 605 * 606 * \return STATUS_OK on successful read. 607 */ 608 binder_status_t AParcel_readParcelableArray(const AParcel* parcel, void* arrayData, 609 AParcel_parcelableArrayAllocator allocator, 610 AParcel_readParcelableElement elementReader) 611 __INTRODUCED_IN(29); 612 613 // @START-PRIMITIVE-READ-WRITE 614 /** 615 * Writes int32_t value to the next location in a non-null parcel. 616 * 617 * Available since API level 29. 618 * 619 * \param parcel the parcel to write to. 620 * \param value the value to write to the parcel. 621 * 622 * \return STATUS_OK on successful write. 623 */ 624 binder_status_t AParcel_writeInt32(AParcel* parcel, int32_t value) __INTRODUCED_IN(29); 625 626 /** 627 * Writes uint32_t value to the next location in a non-null parcel. 628 * 629 * Available since API level 29. 630 * 631 * \param parcel the parcel to write to. 632 * \param value the value to write to the parcel. 633 * 634 * \return STATUS_OK on successful write. 635 */ 636 binder_status_t AParcel_writeUint32(AParcel* parcel, uint32_t value) __INTRODUCED_IN(29); 637 638 /** 639 * Writes int64_t value to the next location in a non-null parcel. 640 * 641 * Available since API level 29. 642 * 643 * \param parcel the parcel to write to. 644 * \param value the value to write to the parcel. 645 * 646 * \return STATUS_OK on successful write. 647 */ 648 binder_status_t AParcel_writeInt64(AParcel* parcel, int64_t value) __INTRODUCED_IN(29); 649 650 /** 651 * Writes uint64_t value to the next location in a non-null parcel. 652 * 653 * Available since API level 29. 654 * 655 * \param parcel the parcel to write to. 656 * \param value the value to write to the parcel. 657 * 658 * \return STATUS_OK on successful write. 659 */ 660 binder_status_t AParcel_writeUint64(AParcel* parcel, uint64_t value) __INTRODUCED_IN(29); 661 662 /** 663 * Writes float value to the next location in a non-null parcel. 664 * 665 * Available since API level 29. 666 * 667 * \param parcel the parcel to write to. 668 * \param value the value to write to the parcel. 669 * 670 * \return STATUS_OK on successful write. 671 */ 672 binder_status_t AParcel_writeFloat(AParcel* parcel, float value) __INTRODUCED_IN(29); 673 674 /** 675 * Writes double value to the next location in a non-null parcel. 676 * 677 * Available since API level 29. 678 * 679 * \param parcel the parcel to write to. 680 * \param value the value to write to the parcel. 681 * 682 * \return STATUS_OK on successful write. 683 */ 684 binder_status_t AParcel_writeDouble(AParcel* parcel, double value) __INTRODUCED_IN(29); 685 686 /** 687 * Writes bool value to the next location in a non-null parcel. 688 * 689 * Available since API level 29. 690 * 691 * \param parcel the parcel to write to. 692 * \param value the value to write to the parcel. 693 * 694 * \return STATUS_OK on successful write. 695 */ 696 binder_status_t AParcel_writeBool(AParcel* parcel, bool value) __INTRODUCED_IN(29); 697 698 /** 699 * Writes char16_t value to the next location in a non-null parcel. 700 * 701 * Available since API level 29. 702 * 703 * \param parcel the parcel to write to. 704 * \param value the value to write to the parcel. 705 * 706 * \return STATUS_OK on successful write. 707 */ 708 binder_status_t AParcel_writeChar(AParcel* parcel, char16_t value) __INTRODUCED_IN(29); 709 710 /** 711 * Writes int8_t value to the next location in a non-null parcel. 712 * 713 * Available since API level 29. 714 * 715 * \param parcel the parcel to write to. 716 * \param value the value to write to the parcel. 717 * 718 * \return STATUS_OK on successful write. 719 */ 720 binder_status_t AParcel_writeByte(AParcel* parcel, int8_t value) __INTRODUCED_IN(29); 721 722 /** 723 * Reads into int32_t value from the next location in a non-null parcel. 724 * 725 * Available since API level 29. 726 * 727 * \param parcel the parcel to read from. 728 * \param value the value to read from the parcel. 729 * 730 * \return STATUS_OK on successful read. 731 */ 732 binder_status_t AParcel_readInt32(const AParcel* parcel, int32_t* value) __INTRODUCED_IN(29); 733 734 /** 735 * Reads into uint32_t value from the next location in a non-null parcel. 736 * 737 * Available since API level 29. 738 * 739 * \param parcel the parcel to read from. 740 * \param value the value to read from the parcel. 741 * 742 * \return STATUS_OK on successful read. 743 */ 744 binder_status_t AParcel_readUint32(const AParcel* parcel, uint32_t* value) __INTRODUCED_IN(29); 745 746 /** 747 * Reads into int64_t value from the next location in a non-null parcel. 748 * 749 * Available since API level 29. 750 * 751 * \param parcel the parcel to read from. 752 * \param value the value to read from the parcel. 753 * 754 * \return STATUS_OK on successful read. 755 */ 756 binder_status_t AParcel_readInt64(const AParcel* parcel, int64_t* value) __INTRODUCED_IN(29); 757 758 /** 759 * Reads into uint64_t value from the next location in a non-null parcel. 760 * 761 * Available since API level 29. 762 * 763 * \param parcel the parcel to read from. 764 * \param value the value to read from the parcel. 765 * 766 * \return STATUS_OK on successful read. 767 */ 768 binder_status_t AParcel_readUint64(const AParcel* parcel, uint64_t* value) __INTRODUCED_IN(29); 769 770 /** 771 * Reads into float value from the next location in a non-null parcel. 772 * 773 * Available since API level 29. 774 * 775 * \param parcel the parcel to read from. 776 * \param value the value to read from the parcel. 777 * 778 * \return STATUS_OK on successful read. 779 */ 780 binder_status_t AParcel_readFloat(const AParcel* parcel, float* value) __INTRODUCED_IN(29); 781 782 /** 783 * Reads into double value from the next location in a non-null parcel. 784 * 785 * Available since API level 29. 786 * 787 * \param parcel the parcel to read from. 788 * \param value the value to read from the parcel. 789 * 790 * \return STATUS_OK on successful read. 791 */ 792 binder_status_t AParcel_readDouble(const AParcel* parcel, double* value) __INTRODUCED_IN(29); 793 794 /** 795 * Reads into bool value from the next location in a non-null parcel. 796 * 797 * Available since API level 29. 798 * 799 * \param parcel the parcel to read from. 800 * \param value the value to read from the parcel. 801 * 802 * \return STATUS_OK on successful read. 803 */ 804 binder_status_t AParcel_readBool(const AParcel* parcel, bool* value) __INTRODUCED_IN(29); 805 806 /** 807 * Reads into char16_t value from the next location in a non-null parcel. 808 * 809 * Available since API level 29. 810 * 811 * \param parcel the parcel to read from. 812 * \param value the value to read from the parcel. 813 * 814 * \return STATUS_OK on successful read. 815 */ 816 binder_status_t AParcel_readChar(const AParcel* parcel, char16_t* value) __INTRODUCED_IN(29); 817 818 /** 819 * Reads into int8_t value from the next location in a non-null parcel. 820 * 821 * Available since API level 29. 822 * 823 * \param parcel the parcel to read from. 824 * \param value the value to read from the parcel. 825 * 826 * \return STATUS_OK on successful read. 827 */ 828 binder_status_t AParcel_readByte(const AParcel* parcel, int8_t* value) __INTRODUCED_IN(29); 829 830 /** 831 * Writes an array of int32_t to the next location in a non-null parcel. 832 * 833 * Available since API level 29. 834 * 835 * \param parcel the parcel to write to. 836 * \param arrayData an array of size 'length' (or null if length is -1, may be null if length is 0). 837 * \param length the length of arrayData or -1 if this represents a null array. 838 * 839 * \return STATUS_OK on successful write. 840 */ 841 binder_status_t AParcel_writeInt32Array(AParcel* parcel, const int32_t* arrayData, int32_t length) 842 __INTRODUCED_IN(29); 843 844 /** 845 * Writes an array of uint32_t to the next location in a non-null parcel. 846 * 847 * Available since API level 29. 848 * 849 * \param parcel the parcel to write to. 850 * \param arrayData an array of size 'length' (or null if length is -1, may be null if length is 0). 851 * \param length the length of arrayData or -1 if this represents a null array. 852 * 853 * \return STATUS_OK on successful write. 854 */ 855 binder_status_t AParcel_writeUint32Array(AParcel* parcel, const uint32_t* arrayData, int32_t length) 856 __INTRODUCED_IN(29); 857 858 /** 859 * Writes an array of int64_t to the next location in a non-null parcel. 860 * 861 * Available since API level 29. 862 * 863 * \param parcel the parcel to write to. 864 * \param arrayData an array of size 'length' (or null if length is -1, may be null if length is 0). 865 * \param length the length of arrayData or -1 if this represents a null array. 866 * 867 * \return STATUS_OK on successful write. 868 */ 869 binder_status_t AParcel_writeInt64Array(AParcel* parcel, const int64_t* arrayData, int32_t length) 870 __INTRODUCED_IN(29); 871 872 /** 873 * Writes an array of uint64_t to the next location in a non-null parcel. 874 * 875 * Available since API level 29. 876 * 877 * \param parcel the parcel to write to. 878 * \param arrayData an array of size 'length' (or null if length is -1, may be null if length is 0). 879 * \param length the length of arrayData or -1 if this represents a null array. 880 * 881 * \return STATUS_OK on successful write. 882 */ 883 binder_status_t AParcel_writeUint64Array(AParcel* parcel, const uint64_t* arrayData, int32_t length) 884 __INTRODUCED_IN(29); 885 886 /** 887 * Writes an array of float to the next location in a non-null parcel. 888 * 889 * Available since API level 29. 890 * 891 * \param parcel the parcel to write to. 892 * \param arrayData an array of size 'length' (or null if length is -1, may be null if length is 0). 893 * \param length the length of arrayData or -1 if this represents a null array. 894 * 895 * \return STATUS_OK on successful write. 896 */ 897 binder_status_t AParcel_writeFloatArray(AParcel* parcel, const float* arrayData, int32_t length) 898 __INTRODUCED_IN(29); 899 900 /** 901 * Writes an array of double to the next location in a non-null parcel. 902 * 903 * Available since API level 29. 904 * 905 * \param parcel the parcel to write to. 906 * \param arrayData an array of size 'length' (or null if length is -1, may be null if length is 0). 907 * \param length the length of arrayData or -1 if this represents a null array. 908 * 909 * \return STATUS_OK on successful write. 910 */ 911 binder_status_t AParcel_writeDoubleArray(AParcel* parcel, const double* arrayData, int32_t length) 912 __INTRODUCED_IN(29); 913 914 /** 915 * Writes an array of bool to the next location in a non-null parcel. 916 * 917 * getter(arrayData, i) will be called for each i in [0, length) in order to get the underlying 918 * values to write to the parcel. 919 * 920 * Available since API level 29. 921 * 922 * \param parcel the parcel to write to. 923 * \param arrayData some external representation of an array. 924 * \param length the length of arrayData (or -1 if this represents a null array). 925 * \param getter the callback to retrieve data at specific locations in the array. 926 * 927 * \return STATUS_OK on successful write. 928 */ 929 binder_status_t AParcel_writeBoolArray(AParcel* parcel, const void* arrayData, int32_t length, 930 AParcel_boolArrayGetter getter) __INTRODUCED_IN(29); 931 932 /** 933 * Writes an array of char16_t to the next location in a non-null parcel. 934 * 935 * Available since API level 29. 936 * 937 * \param parcel the parcel to write to. 938 * \param arrayData an array of size 'length' (or null if length is -1, may be null if length is 0). 939 * \param length the length of arrayData or -1 if this represents a null array. 940 * 941 * \return STATUS_OK on successful write. 942 */ 943 binder_status_t AParcel_writeCharArray(AParcel* parcel, const char16_t* arrayData, int32_t length) 944 __INTRODUCED_IN(29); 945 946 /** 947 * Writes an array of int8_t to the next location in a non-null parcel. 948 * 949 * Available since API level 29. 950 * 951 * \param parcel the parcel to write to. 952 * \param arrayData an array of size 'length' (or null if length is -1, may be null if length is 0). 953 * \param length the length of arrayData or -1 if this represents a null array. 954 * 955 * \return STATUS_OK on successful write. 956 */ 957 binder_status_t AParcel_writeByteArray(AParcel* parcel, const int8_t* arrayData, int32_t length) 958 __INTRODUCED_IN(29); 959 960 /** 961 * Reads an array of int32_t from the next location in a non-null parcel. 962 * 963 * First, allocator will be called with the length of the array. If the allocation succeeds and the 964 * length is greater than zero, the buffer returned by the allocator will be filled with the 965 * corresponding data 966 * 967 * Available since API level 29. 968 * 969 * \param parcel the parcel to read from. 970 * \param arrayData some external representation of an array. 971 * \param allocator the callback that will be called to allocate the array. 972 * 973 * \return STATUS_OK on successful read. 974 */ 975 binder_status_t AParcel_readInt32Array(const AParcel* parcel, void* arrayData, 976 AParcel_int32ArrayAllocator allocator) __INTRODUCED_IN(29); 977 978 /** 979 * Reads an array of uint32_t from the next location in a non-null parcel. 980 * 981 * First, allocator will be called with the length of the array. If the allocation succeeds and the 982 * length is greater than zero, the buffer returned by the allocator will be filled with the 983 * corresponding data 984 * 985 * Available since API level 29. 986 * 987 * \param parcel the parcel to read from. 988 * \param arrayData some external representation of an array. 989 * \param allocator the callback that will be called to allocate the array. 990 * 991 * \return STATUS_OK on successful read. 992 */ 993 binder_status_t AParcel_readUint32Array(const AParcel* parcel, void* arrayData, 994 AParcel_uint32ArrayAllocator allocator) __INTRODUCED_IN(29); 995 996 /** 997 * Reads an array of int64_t from the next location in a non-null parcel. 998 * 999 * First, allocator will be called with the length of the array. If the allocation succeeds and the 1000 * length is greater than zero, the buffer returned by the allocator will be filled with the 1001 * corresponding data 1002 * 1003 * Available since API level 29. 1004 * 1005 * \param parcel the parcel to read from. 1006 * \param arrayData some external representation of an array. 1007 * \param allocator the callback that will be called to allocate the array. 1008 * 1009 * \return STATUS_OK on successful read. 1010 */ 1011 binder_status_t AParcel_readInt64Array(const AParcel* parcel, void* arrayData, 1012 AParcel_int64ArrayAllocator allocator) __INTRODUCED_IN(29); 1013 1014 /** 1015 * Reads an array of uint64_t from the next location in a non-null parcel. 1016 * 1017 * First, allocator will be called with the length of the array. If the allocation succeeds and the 1018 * length is greater than zero, the buffer returned by the allocator will be filled with the 1019 * corresponding data 1020 * 1021 * Available since API level 29. 1022 * 1023 * \param parcel the parcel to read from. 1024 * \param arrayData some external representation of an array. 1025 * \param allocator the callback that will be called to allocate the array. 1026 * 1027 * \return STATUS_OK on successful read. 1028 */ 1029 binder_status_t AParcel_readUint64Array(const AParcel* parcel, void* arrayData, 1030 AParcel_uint64ArrayAllocator allocator) __INTRODUCED_IN(29); 1031 1032 /** 1033 * Reads an array of float from the next location in a non-null parcel. 1034 * 1035 * First, allocator will be called with the length of the array. If the allocation succeeds and the 1036 * length is greater than zero, the buffer returned by the allocator will be filled with the 1037 * corresponding data 1038 * 1039 * Available since API level 29. 1040 * 1041 * \param parcel the parcel to read from. 1042 * \param arrayData some external representation of an array. 1043 * \param allocator the callback that will be called to allocate the array. 1044 * 1045 * \return STATUS_OK on successful read. 1046 */ 1047 binder_status_t AParcel_readFloatArray(const AParcel* parcel, void* arrayData, 1048 AParcel_floatArrayAllocator allocator) __INTRODUCED_IN(29); 1049 1050 /** 1051 * Reads an array of double from the next location in a non-null parcel. 1052 * 1053 * First, allocator will be called with the length of the array. If the allocation succeeds and the 1054 * length is greater than zero, the buffer returned by the allocator will be filled with the 1055 * corresponding data 1056 * 1057 * Available since API level 29. 1058 * 1059 * \param parcel the parcel to read from. 1060 * \param arrayData some external representation of an array. 1061 * \param allocator the callback that will be called to allocate the array. 1062 * 1063 * \return STATUS_OK on successful read. 1064 */ 1065 binder_status_t AParcel_readDoubleArray(const AParcel* parcel, void* arrayData, 1066 AParcel_doubleArrayAllocator allocator) __INTRODUCED_IN(29); 1067 1068 /** 1069 * Reads an array of bool from the next location in a non-null parcel. 1070 * 1071 * First, allocator will be called with the length of the array. Then, for every i in [0, length), 1072 * setter(arrayData, i, x) will be called where x is the value at the associated index. 1073 * 1074 * Available since API level 29. 1075 * 1076 * \param parcel the parcel to read from. 1077 * \param arrayData some external representation of an array. 1078 * \param allocator the callback that will be called to allocate the array. 1079 * \param setter the callback that will be called to set a value at a specific location in the 1080 * array. 1081 * 1082 * \return STATUS_OK on successful read. 1083 */ 1084 binder_status_t AParcel_readBoolArray(const AParcel* parcel, void* arrayData, 1085 AParcel_boolArrayAllocator allocator, 1086 AParcel_boolArraySetter setter) __INTRODUCED_IN(29); 1087 1088 /** 1089 * Reads an array of char16_t from the next location in a non-null parcel. 1090 * 1091 * First, allocator will be called with the length of the array. If the allocation succeeds and the 1092 * length is greater than zero, the buffer returned by the allocator will be filled with the 1093 * corresponding data 1094 * 1095 * Available since API level 29. 1096 * 1097 * \param parcel the parcel to read from. 1098 * \param arrayData some external representation of an array. 1099 * \param allocator the callback that will be called to allocate the array. 1100 * 1101 * \return STATUS_OK on successful read. 1102 */ 1103 binder_status_t AParcel_readCharArray(const AParcel* parcel, void* arrayData, 1104 AParcel_charArrayAllocator allocator) __INTRODUCED_IN(29); 1105 1106 /** 1107 * Reads an array of int8_t from the next location in a non-null parcel. 1108 * 1109 * First, allocator will be called with the length of the array. If the allocation succeeds and the 1110 * length is greater than zero, the buffer returned by the allocator will be filled with the 1111 * corresponding data 1112 * 1113 * Available since API level 29. 1114 * 1115 * \param parcel the parcel to read from. 1116 * \param arrayData some external representation of an array. 1117 * \param allocator the callback that will be called to allocate the array. 1118 * 1119 * \return STATUS_OK on successful read. 1120 */ 1121 binder_status_t AParcel_readByteArray(const AParcel* parcel, void* arrayData, 1122 AParcel_byteArrayAllocator allocator) __INTRODUCED_IN(29); 1123 1124 // @END-PRIMITIVE-READ-WRITE 1125 1126 /** 1127 * Reset the parcel to the initial status. 1128 * 1129 * Available since API level 31. 1130 * 1131 * \param parcel The parcel of which to be reset. 1132 * 1133 * \return STATUS_OK on success. 1134 */ 1135 binder_status_t AParcel_reset(AParcel* parcel) __INTRODUCED_IN(31); 1136 1137 /** 1138 * Gets the size of the parcel. 1139 * 1140 * Available since API level 31. 1141 * 1142 * \param parcel The parcel of which to get the size. 1143 * 1144 * \return The size of the parcel. 1145 */ 1146 int32_t AParcel_getDataSize(const AParcel* parcel) __INTRODUCED_IN(31); 1147 1148 /** 1149 * Copy the data of a parcel to other parcel. 1150 * 1151 * Available since API level 31. 1152 * 1153 * \param from The source 1154 * \param to The detination 1155 * \param start The position where the copied data starts. 1156 * \param size The amount of data which will be copied. 1157 * 1158 * \return STATUS_OK on success. 1159 */ 1160 binder_status_t AParcel_appendFrom(const AParcel* from, AParcel* to, int32_t start, int32_t size) 1161 __INTRODUCED_IN(31); 1162 1163 /** 1164 * Creates a parcel. 1165 * 1166 * Available since API level 31. 1167 * 1168 * \return A parcel which is not related to any IBinder objects. 1169 */ 1170 AParcel* AParcel_create() __INTRODUCED_IN(31); 1171 1172 /** 1173 * Marshals the raw bytes of the Parcel to a buffer. 1174 * 1175 * Available since API level 33. 1176 * 1177 * The parcel must not contain any binders or file descriptors. 1178 * 1179 * The data you retrieve here must not be placed in any kind of persistent storage. (on local disk, 1180 * across a network, etc). For that, you should use standard serialization or another kind of 1181 * general serialization mechanism. The Parcel marshalled representation is highly optimized for 1182 * local IPC, and as such does not attempt to maintain compatibility with data created in different 1183 * versions of the platform. 1184 * 1185 * \param parcel The parcel of which to get the data. 1186 * \param buffer The buffer to copy the raw bytes to. 1187 * \param start The start position in the buffer to copy from. 1188 * \param len The size of the data to copy, buffer size must be larger or equal to this. 1189 * 1190 * \return STATUS_OK on success, STATUS_INVALID_OPERATION if parcel contains binders or file 1191 * descriptors. STATUS_BAD_VALUE if the buffer size is less than parcel size. 1192 */ 1193 binder_status_t AParcel_marshal(const AParcel* parcel, uint8_t* buffer, size_t start, size_t len) 1194 __INTRODUCED_IN(33); 1195 1196 /** 1197 * Set the data in the parcel to the raw bytes from the buffer. 1198 * 1199 * Available since API level 33. 1200 * 1201 * \param parcel The parcel to set data. 1202 * \param buffer The data buffer to set. 1203 * \param len The size of the data to set. 1204 * 1205 * \return STATUS_OK on success. 1206 */ 1207 binder_status_t AParcel_unmarshal(AParcel* parcel, const uint8_t* buffer, size_t len) 1208 __INTRODUCED_IN(33); 1209 1210 __END_DECLS 1211 1212 /** @} */ 1213