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