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