1 /*
2  * Copyright (C) 2023 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 #pragma once
18 
19 #include <android/binder_parcel.h>
20 #if defined(__ANDROID_VENDOR__)
21 #include <android/llndk-versioning.h>
22 #else
23 #if !defined(__INTRODUCED_IN_LLNDK)
24 #define __INTRODUCED_IN_LLNDK(level) __attribute__((annotate("introduced_in_llndk=" #level)))
25 #endif
26 #endif  // __ANDROID_VENDOR__
27 #include <stdbool.h>
28 #include <stdint.h>
29 #include <sys/cdefs.h>
30 #include <sys/types.h>
31 
32 __BEGIN_DECLS
33 
34 /*
35  * A mapping from string keys to values of various types.
36  * See frameworks/base/core/java/android/os/PersistableBundle.java
37  * for the Java type than can be used in SDK APIs.
38  * APersistableBundle exists to be used in AIDL interfaces and seamlessly
39  * interact with framework services.
40  * frameworks/native/libs/binder/ndk/include_cpp/android/persistable_bundle_aidl.h
41  * contains the AIDL type used in the ndk backend of AIDL interfaces.
42  */
43 struct APersistableBundle;
44 typedef struct APersistableBundle APersistableBundle;
45 
46 enum {
47     /**
48      * This can be returned from functions that need to distinguish between an empty
49      * value and a non-existent key.
50      */
51     APERSISTABLEBUNDLE_KEY_NOT_FOUND = -1,
52 
53     /**
54      * This can be returned from functions that take a APersistableBundle_stringAllocator.
55      * This means the allocator has failed and returned a nullptr.
56      */
57     APERSISTABLEBUNDLE_ALLOCATOR_FAILED = -2,
58 };
59 
60 /**
61  * This is a user supplied allocator that allocates a buffer for the
62  * APersistableBundle APIs to fill in with a UTF-8 string.
63  * The caller that supplies this function is responsible for freeing the
64  * returned data.
65  *
66  * \param the required size in bytes for the allocated buffer
67  * \param context pointer if needed by the callback
68  *
69  * \return allocated buffer of sizeBytes for a UTF-8 string. Null if allocation failed.
70  */
71 typedef char* _Nullable (*_Nonnull APersistableBundle_stringAllocator)(int32_t sizeBytes,
72                                                                        void* _Nullable context);
73 
74 /**
75  * Create a new APersistableBundle.
76  *
77  * Available since API level 202404.
78  *
79  * \return Pointer to a new APersistableBundle
80  */
81 APersistableBundle* _Nullable APersistableBundle_new() __INTRODUCED_IN(__ANDROID_API_V__)
82         __INTRODUCED_IN_LLNDK(202404);
83 
84 /**
85  * Create a new APersistableBundle based off an existing APersistableBundle.
86  * This is a deep copy, so the new APersistableBundle has its own values from
87  * copying the original underlying PersistableBundle.
88  *
89  * Available since API level 202404.
90  *
91  * \param pBundle to duplicate
92  *
93  * \return Pointer to a new APersistableBundle
94  */
95 APersistableBundle* _Nullable APersistableBundle_dup(const APersistableBundle* _Nonnull pBundle)
96         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
97 
98 /**
99  * Delete an APersistableBundle. This must always be called when finished using
100  * the object.
101  *
102  * \param pBundle to delete. No-op if null.
103  *
104  * Available since API level 202404.
105  */
106 void APersistableBundle_delete(APersistableBundle* _Nullable pBundle)
107         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
108 
109 /**
110  * Check for equality of APersistableBundles.
111  *
112  * Available since API level 202404.
113  *
114  * \param lhs bundle to compare against the other param
115  * \param rhs bundle to compare against the other param
116  *
117  * \return true when equal, false when not
118  */
119 bool APersistableBundle_isEqual(const APersistableBundle* _Nonnull lhs,
120                                 const APersistableBundle* _Nonnull rhs)
121         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
122 
123 /**
124  * Read an APersistableBundle from an AParcel.
125  *
126  * Available since API level 202404.
127  *
128  * \param parcel to read from
129  * \param outPBundle bundle to write to
130  *
131  * \return STATUS_OK on success
132  *         STATUS_BAD_VALUE if the parcel or outBuffer is null, or if there's an
133  *                          issue deserializing (eg, corrupted parcel)
134  *         STATUS_BAD_TYPE if the parcel's current data position is not that of
135  *                         an APersistableBundle type
136  *         STATUS_NO_MEMORY if an allocation fails
137  */
138 binder_status_t APersistableBundle_readFromParcel(
139         const AParcel* _Nonnull parcel, APersistableBundle* _Nullable* _Nonnull outPBundle)
140         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
141 
142 /**
143  * Write an APersistableBundle to an AParcel.
144  *
145  * Available since API level 202404.
146  *
147  * \param pBundle bundle to write to the parcel
148  * \param parcel to write to
149  *
150  * \return STATUS_OK on success.
151  *         STATUS_BAD_VALUE if either pBundle or parcel is null, or if the
152  *         APersistableBundle*
153  *                          fails to serialize (eg, internally corrupted)
154  *         STATUS_NO_MEMORY if the parcel runs out of space to store the pBundle & is
155  *                          unable to allocate more
156  *         STATUS_FDS_NOT_ALLOWED if the parcel does not allow storing FDs
157  */
158 binder_status_t APersistableBundle_writeToParcel(const APersistableBundle* _Nonnull pBundle,
159                                                  AParcel* _Nonnull parcel)
160         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
161 
162 /**
163  * Get the size of an APersistableBundle. This is the number of mappings in the
164  * object.
165  *
166  * Available since API level 202404.
167  *
168  * \param pBundle to get the size of (number of mappings)
169  *
170  * \return number of mappings in the object
171  */
172 int32_t APersistableBundle_size(const APersistableBundle* _Nonnull pBundle)
173         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
174 
175 /**
176  * Erase any entries added with the provided key.
177  *
178  * Available since API level 202404.
179  *
180  * \param pBundle to operate on
181  * \param key for the mapping in UTF-8 to erase
182  *
183  * \return number of entries erased. Either 0 or 1.
184  */
185 int32_t APersistableBundle_erase(APersistableBundle* _Nonnull pBundle, const char* _Nonnull key)
186         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
187 
188 /**
189  * Put a boolean associated with the provided key.
190  * New values with the same key will overwrite existing values.
191  *
192  * \param pBundle to operate on
193  * \param key for the mapping in UTF-8
194  * \param value to put for the mapping
195  *
196  * Available since API level 202404.
197  */
198 void APersistableBundle_putBoolean(APersistableBundle* _Nonnull pBundle, const char* _Nonnull key,
199                                    bool val) __INTRODUCED_IN(__ANDROID_API_V__)
200         __INTRODUCED_IN_LLNDK(202404);
201 
202 /**
203  * Put an int32_t associated with the provided key.
204  * New values with the same key will overwrite existing values.
205  *
206  * \param pBundle to operate on
207  * \param key for the mapping in UTF-8
208  * \param val value to put for the mapping
209  *
210  * Available since API level 202404.
211  */
212 void APersistableBundle_putInt(APersistableBundle* _Nonnull pBundle, const char* _Nonnull key,
213                                int32_t val) __INTRODUCED_IN(__ANDROID_API_V__)
214         __INTRODUCED_IN_LLNDK(202404);
215 
216 /**
217  * Put an int64_t associated with the provided key.
218  * New values with the same key will overwrite existing values.
219  *
220  * \param pBundle to operate on
221  * \param key for the mapping in UTF-8
222  * \param val value to put for the mapping
223  *
224  * Available since API level 202404.
225  */
226 void APersistableBundle_putLong(APersistableBundle* _Nonnull pBundle, const char* _Nonnull key,
227                                 int64_t val) __INTRODUCED_IN(__ANDROID_API_V__)
228         __INTRODUCED_IN_LLNDK(202404);
229 
230 /**
231  * Put a double associated with the provided key.
232  * New values with the same key will overwrite existing values.
233  *
234  * \param pBundle to operate on
235  * \param key for the mapping in UTF-8
236  * \param val value to put for the mapping
237  *
238  * Available since API level 202404.
239  */
240 void APersistableBundle_putDouble(APersistableBundle* _Nonnull pBundle, const char* _Nonnull key,
241                                   double val) __INTRODUCED_IN(__ANDROID_API_V__)
242         __INTRODUCED_IN_LLNDK(202404);
243 
244 /**
245  * Put a string associated with the provided key.
246  * New values with the same key will overwrite existing values.
247  * The value is copied.
248  *
249  * \param pBundle to operate on
250  * \param key for the mapping in UTF-8
251  * \param vec vector to put for the mapping
252  *
253  * Available since API level 202404.
254  */
255 void APersistableBundle_putString(APersistableBundle* _Nonnull pBundle, const char* _Nonnull key,
256                                   const char* _Nonnull val) __INTRODUCED_IN(__ANDROID_API_V__)
257         __INTRODUCED_IN_LLNDK(202404);
258 
259 /**
260  * Put a boolean vector associated with the provided key.
261  * New values with the same key will overwrite existing values.
262  * The values are copied.
263  *
264  * \param pBundle to operate on
265  * \param key for the mapping in UTF-8
266  * \param vec vector to put for the mapping
267  * \param num number of elements in the vector
268  *
269  * Available since API level 202404.
270  */
271 void APersistableBundle_putBooleanVector(APersistableBundle* _Nonnull pBundle,
272                                          const char* _Nonnull key, const bool* _Nonnull vec,
273                                          int32_t num) __INTRODUCED_IN(__ANDROID_API_V__)
274         __INTRODUCED_IN_LLNDK(202404);
275 
276 /**
277  * Put an int32_t vector associated with the provided key.
278  * New values with the same key will overwrite existing values.
279  * The values are copied.
280  *
281  * \param pBundle to operate on
282  * \param key for the mapping in UTF-8
283  * \param vec vector to put for the mapping
284  * \param num number of elements in the vector
285  *
286  * Available since API level 202404.
287  */
288 void APersistableBundle_putIntVector(APersistableBundle* _Nonnull pBundle, const char* _Nonnull key,
289                                      const int32_t* _Nonnull vec, int32_t num)
290         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
291 
292 /**
293  * Put an int64_t vector associated with the provided key.
294  * New values with the same key will overwrite existing values.
295  * The values are copied.
296  *
297  * \param pBundle to operate on
298  * \param key for the mapping in UTF-8
299  * \param vec vector to put for the mapping
300  * \param num number of elements in the vector
301  *
302  * Available since API level 202404.
303  */
304 void APersistableBundle_putLongVector(APersistableBundle* _Nonnull pBundle,
305                                       const char* _Nonnull key, const int64_t* _Nonnull vec,
306                                       int32_t num) __INTRODUCED_IN(__ANDROID_API_V__)
307         __INTRODUCED_IN_LLNDK(202404);
308 
309 /**
310  * Put a double vector associated with the provided key.
311  * New values with the same key will overwrite existing values.
312  * The values are copied.
313  *
314  * \param pBundle to operate on
315  * \param key for the mapping in UTF-8
316  * \param vec vector to put for the mapping
317  * \param num number of elements in the vector
318  *
319  * Available since API level 202404.
320  */
321 void APersistableBundle_putDoubleVector(APersistableBundle* _Nonnull pBundle,
322                                         const char* _Nonnull key, const double* _Nonnull vec,
323                                         int32_t num) __INTRODUCED_IN(__ANDROID_API_V__)
324         __INTRODUCED_IN_LLNDK(202404);
325 
326 /**
327  * Put a string vector associated with the provided key.
328  * New values with the same key will overwrite existing values.
329  * The values are copied.
330  *
331  * \param pBundle to operate on
332  * \param key for the mapping in UTF-8
333  * \param vec vector to put for the mapping
334  * \param num number of elements in the vector
335  *
336  * Available since API level 202404.
337  */
338 void APersistableBundle_putStringVector(APersistableBundle* _Nonnull pBundle,
339                                         const char* _Nonnull key,
340                                         const char* _Nullable const* _Nullable vec, int32_t num)
341         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
342 
343 /**
344  * Put an APersistableBundle associated with the provided key.
345  * New values with the same key will overwrite existing values.
346  * The value is deep-copied.
347  *
348  * \param pBundle to operate on
349  * \param key for the mapping in UTF-8
350  * \param val value to put for the mapping
351  *
352  * Available since API level 202404.
353  */
354 void APersistableBundle_putPersistableBundle(APersistableBundle* _Nonnull pBundle,
355                                              const char* _Nonnull key,
356                                              const APersistableBundle* _Nonnull val)
357         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
358 
359 /**
360  * Get a boolean associated with the provided key.
361  *
362  * Available since API level 202404.
363  *
364  * \param pBundle to operate on
365  * \param key for the mapping in UTF-8
366  * \param val pointer to write the value to
367  *
368  * \return true if a value exists for the provided key
369  */
370 bool APersistableBundle_getBoolean(const APersistableBundle* _Nonnull pBundle,
371                                    const char* _Nonnull key, bool* _Nonnull val)
372         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
373 
374 /**
375  * Get an int32_t associated with the provided key.
376  *
377  * Available since API level 202404.
378  *
379  * \param pBundle to operate on
380  * \param key for the mapping in UTF-8
381  * \param val pointer to write the value to
382  *
383  * \return true if a value exists for the provided key
384  */
385 bool APersistableBundle_getInt(const APersistableBundle* _Nonnull pBundle, const char* _Nonnull key,
386                                int32_t* _Nonnull val) __INTRODUCED_IN(__ANDROID_API_V__)
387         __INTRODUCED_IN_LLNDK(202404);
388 
389 /**
390  * Get an int64_t associated with the provided key.
391  *
392  * Available since API level 202404.
393  *
394  * \param pBundle to operate on
395  * \param key for the mapping in UTF-8
396  * \param val pointer to write the value to
397  *
398  * \return true if a value exists for the provided key
399  */
400 bool APersistableBundle_getLong(const APersistableBundle* _Nonnull pBundle,
401                                 const char* _Nonnull key, int64_t* _Nonnull val)
402         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
403 
404 /**
405  * Get a double associated with the provided key.
406  *
407  * Available since API level 202404.
408  *
409  * \param pBundle to operate on
410  * \param key for the mapping in UTF-8
411  * \param val pointer to write the value to
412  *
413  * \return true if a value exists for the provided key
414  */
415 bool APersistableBundle_getDouble(const APersistableBundle* _Nonnull pBundle,
416                                   const char* _Nonnull key, double* _Nonnull val)
417         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
418 
419 /**
420  * Get a string associated with the provided key.
421  * The caller is responsible for freeing the returned data.
422  *
423  * Available since API level 202404.
424  *
425  * \param pBundle to operate on
426  * \param key for the mapping in UTF-8
427  * \param val pointer to write the value to in UTF-8
428  * \param stringAllocator function pointer to the string allocator
429  * \param context pointer that will be passed to the stringAllocator
430  *
431  * \return size of string in bytes associated with the provided key on success
432  *         APERSISTABLEBUNDLE_KEY_NOT_FOUND if the key was not found
433  *         APERSISTABLEBUNDLE_ALLOCATOR_FAILED if the provided allocator fails
434  */
435 int32_t APersistableBundle_getString(const APersistableBundle* _Nonnull pBundle,
436                                      const char* _Nonnull key, char* _Nullable* _Nonnull val,
437                                      APersistableBundle_stringAllocator stringAllocator,
438                                      void* _Nullable context) __INTRODUCED_IN(__ANDROID_API_V__)
439         __INTRODUCED_IN_LLNDK(202404);
440 
441 /**
442  * Get a boolean vector associated with the provided key and place it in the
443  * provided pre-allocated buffer from the user.
444  *
445  * This function returns the size in bytes of stored vector.
446  * The supplied buffer will be filled in based on the smaller of the supplied
447  * bufferSizeBytes or the actual size of the stored data.
448  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
449  * actual stored data, then not all of the stored data will be returned.
450  *
451  * Users can call this function with null buffer and 0 bufferSizeBytes to get
452  * the required size of the buffer to use on a subsequent call.
453  *
454  * \param pBundle to operate on
455  * \param key for the mapping in UTF-8
456  * \param buffer pointer to a pre-allocated buffer to write the values to
457  * \param bufferSizeBytes size of the pre-allocated buffer
458  *
459  * \return size of the stored vector in bytes. This is the required size of the
460  * pre-allocated user supplied buffer if all of the stored contents are desired.
461  *         APERSISTABLEBUNDLE_KEY_NOT_FOUND if the key was not found
462  */
463 int32_t APersistableBundle_getBooleanVector(const APersistableBundle* _Nonnull pBundle,
464                                             const char* _Nonnull key, bool* _Nullable buffer,
465                                             int32_t bufferSizeBytes)
466         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
467 
468 /**
469  * Get an int32_t vector associated with the provided key and place it in the
470  * provided pre-allocated buffer from the user.
471  *
472  * This function returns the size in bytes of stored vector.
473  * The supplied buffer will be filled in based on the smaller of the supplied
474  * bufferSizeBytes or the actual size of the stored data.
475  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
476  * actual stored data, then not all of the stored data will be returned.
477  *
478  * Users can call this function with null buffer and 0 bufferSizeBytes to get
479  * the required size of the buffer to use on a subsequent call.
480  *
481  * \param pBundle to operate on
482  * \param key for the mapping in UTF-8
483  * \param buffer pointer to a pre-allocated buffer to write the values to
484  * \param bufferSizeBytes size of the pre-allocated buffer
485  *
486  * \return size of the stored vector in bytes. This is the required size of the
487  * pre-allocated user supplied buffer if all of the stored contents are desired.
488  *         APERSISTABLEBUNDLE_KEY_NOT_FOUND if the key was not found
489  */
490 int32_t APersistableBundle_getIntVector(const APersistableBundle* _Nonnull pBundle,
491                                         const char* _Nonnull key, int32_t* _Nullable buffer,
492                                         int32_t bufferSizeBytes) __INTRODUCED_IN(__ANDROID_API_V__)
493         __INTRODUCED_IN_LLNDK(202404);
494 
495 /**
496  * Get an int64_t vector associated with the provided key and place it in the
497  * provided pre-allocated buffer from the user.
498  *
499  * This function returns the size in bytes of stored vector.
500  * The supplied buffer will be filled in based on the smaller of the supplied
501  * bufferSizeBytes or the actual size of the stored data.
502  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
503  * actual stored data, then not all of the stored data will be returned.
504  *
505  * Users can call this function with null buffer and 0 bufferSizeBytes to get
506  * the required size of the buffer to use on a subsequent call.
507  *
508  * \param pBundle to operate on
509  * \param key for the mapping in UTF-8
510  * \param buffer pointer to a pre-allocated buffer to write the values to
511  * \param bufferSizeBytes size of the pre-allocated buffer
512  *
513  * \return size of the stored vector in bytes. This is the required size of the
514  * pre-allocated user supplied buffer if all of the stored contents are desired.
515  *         APERSISTABLEBUNDLE_KEY_NOT_FOUND if the key was not found
516  */
517 int32_t APersistableBundle_getLongVector(const APersistableBundle* _Nonnull pBundle,
518                                          const char* _Nonnull key, int64_t* _Nullable buffer,
519                                          int32_t bufferSizeBytes) __INTRODUCED_IN(__ANDROID_API_V__)
520         __INTRODUCED_IN_LLNDK(202404);
521 
522 /**
523  * Get a double vector associated with the provided key and place it in the
524  * provided pre-allocated buffer from the user.
525  *
526  * This function returns the size in bytes of stored vector.
527  * The supplied buffer will be filled in based on the smaller of the supplied
528  * bufferSizeBytes or the actual size of the stored data.
529  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
530  * actual stored data, then not all of the stored data will be returned.
531  *
532  * Users can call this function with null buffer and 0 bufferSizeBytes to get
533  * the required size of the buffer to use on a subsequent call.
534  *
535  * \param pBundle to operate on
536  * \param key for the mapping in UTF-8
537  * \param buffer pointer to a pre-allocated buffer to write the values to
538  * \param bufferSizeBytes size of the pre-allocated buffer
539  *
540  * \return size of the stored vector in bytes. This is the required size of the
541  * pre-allocated user supplied buffer if all of the stored contents are desired.
542  *         APERSISTABLEBUNDLE_KEY_NOT_FOUND if the key was not found
543  */
544 int32_t APersistableBundle_getDoubleVector(const APersistableBundle* _Nonnull pBundle,
545                                            const char* _Nonnull key, double* _Nullable buffer,
546                                            int32_t bufferSizeBytes)
547         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
548 
549 /**
550  * Get a string vector associated with the provided key and place it in the
551  * provided pre-allocated buffer from the user. The user must provide an
552  * APersistableBundle_stringAllocator for the individual strings to be
553  * allocated.
554  * The caller is responsible for freeing the returned data.
555  *
556  * This function returns the size in bytes of stored vector.
557  * The supplied buffer will be filled in based on the smaller of the supplied
558  * bufferSizeBytes or the actual size of the stored data.
559  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
560  * actual stored data, then not all of the stored data will be returned.
561  *
562  * Users can call this function with null buffer and 0 bufferSizeBytes to get
563  * the required size of the buffer to use on a subsequent call.
564  *
565  * \param pBundle to operate on
566  * \param key for the mapping in UTF-8
567  * \param buffer pointer to a pre-allocated buffer to write the string pointers to
568  * \param bufferSizeBytes size of the pre-allocated buffer
569  * \param stringAllocator function pointer to the string allocator
570  * \param context pointer that will be passed to the stringAllocator
571  *
572  * \return size of the stored vector in bytes. This is the required size of the
573  * pre-allocated user supplied buffer if all of the stored contents are desired.
574  *         0 if no string vector exists for the provided key
575  *         APERSISTABLEBUNDLE_KEY_NOT_FOUND if the key was not found
576  *         APERSISTABLEBUNDLE_ALLOCATOR_FAILED if the provided allocator fails
577  */
578 int32_t APersistableBundle_getStringVector(const APersistableBundle* _Nonnull pBundle,
579                                            const char* _Nonnull key,
580                                            char* _Nullable* _Nullable buffer,
581                                            int32_t bufferSizeBytes,
582                                            APersistableBundle_stringAllocator stringAllocator,
583                                            void* _Nullable context)
584         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
585 
586 /**
587  * Get an APersistableBundle* associated with the provided key.
588  *
589  * Available since API level 202404.
590  *
591  * \param pBundle to operate on
592  * \param key for the mapping in UTF-8
593  * \param val pointer to an APersistableBundle pointer to write to point to
594  * a new copy of the stored APersistableBundle. The caller takes ownership of
595  * the new APersistableBundle and must be deleted with
596  * APersistableBundle_delete.
597  *
598  * \return true if a value exists for the provided key
599  */
600 bool APersistableBundle_getPersistableBundle(const APersistableBundle* _Nonnull pBundle,
601                                              const char* _Nonnull key,
602                                              APersistableBundle* _Nullable* _Nonnull outBundle)
603         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
604 
605 /**
606  * Get all of the keys associated with this specific type and place it in the
607  * provided pre-allocated buffer from the user. The user must provide an
608  * APersistableBundle_stringAllocator for the individual strings to be
609  * allocated.
610  * The caller is responsible for freeing the returned data.
611  *
612  * This function returns the size in bytes required to fit the fill list of keys.
613  * The supplied buffer will be filled in based on the smaller of the supplied
614  * bufferSizeBytes or the actual size of the stored data.
615  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
616  * actual stored data, then not all of the stored data will be returned.
617  *
618  * Users can call this function with null buffer and 0 bufferSizeBytes to get
619  * the required size of the buffer to use on a subsequent call.
620  *
621  * \param pBundle to operate on
622  * \param outKeys pointer to a pre-allocated buffer to write the UTF-8 keys to
623  * \param bufferSizeBytes size of the pre-allocated buffer
624  * \param stringAllocator function pointer to the string allocator
625  * \param context pointer that will be passed to the stringAllocator
626  *
627  * \return size of the buffer of keys in bytes. This is the required size of the
628  * pre-allocated user supplied buffer if all of the stored contents are desired.
629  *         APERSISTABLEBUNDLE_ALLOCATOR_FAILED if the provided allocator fails
630  */
631 int32_t APersistableBundle_getBooleanKeys(const APersistableBundle* _Nonnull pBundle,
632                                           char* _Nullable* _Nullable outKeys,
633                                           int32_t bufferSizeBytes,
634                                           APersistableBundle_stringAllocator stringAllocator,
635                                           void* _Nullable context)
636         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
637 
638 /**
639  * Get all of the keys associated with this specific type and place it in the
640  * provided pre-allocated buffer from the user. The user must provide an
641  * APersistableBundle_stringAllocator for the individual strings to be
642  * allocated.
643  * The caller is responsible for freeing the returned data.
644  *
645  * This function returns the size in bytes required to fit the fill list of keys.
646  * The supplied buffer will be filled in based on the smaller of the supplied
647  * bufferSizeBytes or the actual size of the stored data.
648  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
649  * actual stored data, then not all of the stored data will be returned.
650  *
651  * Users can call this function with null buffer and 0 bufferSizeBytes to get
652  * the required size of the buffer to use on a subsequent call.
653  *
654  * \param pBundle to operate on
655  * \param outKeys pointer to a pre-allocated buffer to write the UTF-8 keys to
656  * \param bufferSizeBytes size of the pre-allocated buffer
657  * \param stringAllocator function pointer to the string allocator
658  * \param context pointer that will be passed to the stringAllocator
659  *
660  * \return size of the buffer of keys in bytes. This is the required size of the
661  * pre-allocated user supplied buffer if all of the stored contents are desired.
662  *         APERSISTABLEBUNDLE_ALLOCATOR_FAILED if the provided allocator fails
663  */
664 int32_t APersistableBundle_getIntKeys(const APersistableBundle* _Nonnull pBundle,
665                                       char* _Nullable* _Nullable outKeys, int32_t bufferSizeBytes,
666                                       APersistableBundle_stringAllocator stringAllocator,
667                                       void* _Nullable context) __INTRODUCED_IN(__ANDROID_API_V__)
668         __INTRODUCED_IN_LLNDK(202404);
669 
670 /**
671  * Get all of the keys associated with this specific type and place it in the
672  * provided pre-allocated buffer from the user. The user must provide an
673  * APersistableBundle_stringAllocator for the individual strings to be
674  * allocated.
675  * The caller is responsible for freeing the returned data.
676  *
677  * This function returns the size in bytes required to fit the fill list of keys.
678  * The supplied buffer will be filled in based on the smaller of the supplied
679  * bufferSizeBytes or the actual size of the stored data.
680  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
681  * actual stored data, then not all of the stored data will be returned.
682  *
683  * Users can call this function with null buffer and 0 bufferSizeBytes to get
684  * the required size of the buffer to use on a subsequent call.
685  *
686  * \param pBundle to operate on
687  * \param outKeys pointer to a pre-allocated buffer to write the UTF-8 keys to
688  * \param bufferSizeBytes size of the pre-allocated buffer
689  * \param stringAllocator function pointer to the string allocator
690  * \param context pointer that will be passed to the stringAllocator
691  *
692  * \return size of the buffer of keys in bytes. This is the required size of the
693  * pre-allocated user supplied buffer if all of the stored contents are desired.
694  *         APERSISTABLEBUNDLE_ALLOCATOR_FAILED if the provided allocator fails
695  */
696 int32_t APersistableBundle_getLongKeys(const APersistableBundle* _Nonnull pBundle,
697                                        char* _Nullable* _Nullable outKeys, int32_t bufferSizeBytes,
698                                        APersistableBundle_stringAllocator stringAllocator,
699                                        void* _Nullable context) __INTRODUCED_IN(__ANDROID_API_V__)
700         __INTRODUCED_IN_LLNDK(202404);
701 
702 /**
703  * Get all of the keys associated with this specific type and place it in the
704  * provided pre-allocated buffer from the user. The user must provide an
705  * APersistableBundle_stringAllocator for the individual strings to be
706  * allocated.
707  * The caller is responsible for freeing the returned data.
708  *
709  * This function returns the size in bytes required to fit the fill list of keys.
710  * The supplied buffer will be filled in based on the smaller of the supplied
711  * bufferSizeBytes or the actual size of the stored data.
712  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
713  * actual stored data, then not all of the stored data will be returned.
714  *
715  * Users can call this function with null buffer and 0 bufferSizeBytes to get
716  * the required size of the buffer to use on a subsequent call.
717  *
718  * \param pBundle to operate on
719  * \param outKeys pointer to a pre-allocated buffer to write the UTF-8 keys to
720  * \param bufferSizeBytes size of the pre-allocated buffer
721  * \param stringAllocator function pointer to the string allocator
722  * \param context pointer that will be passed to the stringAllocator
723  *
724  * \return size of the buffer of keys in bytes. This is the required size of the
725  * pre-allocated user supplied buffer if all of the stored contents are desired.
726  *         APERSISTABLEBUNDLE_ALLOCATOR_FAILED if the provided allocator fails
727  */
728 int32_t APersistableBundle_getDoubleKeys(const APersistableBundle* _Nonnull pBundle,
729                                          char* _Nullable* _Nullable outKeys,
730                                          int32_t bufferSizeBytes,
731                                          APersistableBundle_stringAllocator stringAllocator,
732                                          void* _Nullable context) __INTRODUCED_IN(__ANDROID_API_V__)
733         __INTRODUCED_IN_LLNDK(202404);
734 
735 /**
736  * Get all of the keys associated with this specific type and place it in the
737  * provided pre-allocated buffer from the user. The user must provide an
738  * APersistableBundle_stringAllocator for the individual strings to be
739  * allocated.
740  * The caller is responsible for freeing the returned data.
741  *
742  * This function returns the size in bytes required to fit the fill list of keys.
743  * The supplied buffer will be filled in based on the smaller of the supplied
744  * bufferSizeBytes or the actual size of the stored data.
745  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
746  * actual stored data, then not all of the stored data will be returned.
747  *
748  * Users can call this function with null buffer and 0 bufferSizeBytes to get
749  * the required size of the buffer to use on a subsequent call.
750  *
751  * \param pBundle to operate on
752  * \param outKeys pointer to a pre-allocated buffer to write the UTF-8 keys to
753  * \param bufferSizeBytes size of the pre-allocated buffer
754  * \param stringAllocator function pointer to the string allocator
755  * \param context pointer that will be passed to the stringAllocator
756  *
757  * \return size of the buffer of keys in bytes. This is the required size of the
758  * pre-allocated user supplied buffer if all of the stored contents are desired.
759  *         APERSISTABLEBUNDLE_ALLOCATOR_FAILED if the provided allocator fails
760  */
761 int32_t APersistableBundle_getStringKeys(const APersistableBundle* _Nonnull pBundle,
762                                          char* _Nullable* _Nullable outKeys,
763                                          int32_t bufferSizeBytes,
764                                          APersistableBundle_stringAllocator stringAllocator,
765                                          void* _Nullable context) __INTRODUCED_IN(__ANDROID_API_V__)
766         __INTRODUCED_IN_LLNDK(202404);
767 
768 /**
769  * Get all of the keys associated with this specific type and place it in the
770  * provided pre-allocated buffer from the user. The user must provide an
771  * APersistableBundle_stringAllocator for the individual strings to be
772  * allocated.
773  * The caller is responsible for freeing the returned data.
774  *
775  * This function returns the size in bytes required to fit the fill list of keys.
776  * The supplied buffer will be filled in based on the smaller of the supplied
777  * bufferSizeBytes or the actual size of the stored data.
778  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
779  * actual stored data, then not all of the stored data will be returned.
780  *
781  * Users can call this function with null buffer and 0 bufferSizeBytes to get
782  * the required size of the buffer to use on a subsequent call.
783  *
784  * \param pBundle to operate on
785  * \param outKeys pointer to a pre-allocated buffer to write the UTF-8 keys to
786  * \param bufferSizeBytes size of the pre-allocated buffer
787  * \param stringAllocator function pointer to the string allocator
788  * \param context pointer that will be passed to the stringAllocator
789  *
790  * \return size of the buffer of keys in bytes. This is the required size of the
791  * pre-allocated user supplied buffer if all of the stored contents are desired.
792  *         APERSISTABLEBUNDLE_ALLOCATOR_FAILED if the provided allocator fails
793  */
794 int32_t APersistableBundle_getBooleanVectorKeys(const APersistableBundle* _Nonnull pBundle,
795                                                 char* _Nullable* _Nullable outKeys,
796                                                 int32_t bufferSizeBytes,
797                                                 APersistableBundle_stringAllocator stringAllocator,
798                                                 void* _Nullable context)
799         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
800 
801 /**
802  * Get all of the keys associated with this specific type and place it in the
803  * provided pre-allocated buffer from the user. The user must provide an
804  * APersistableBundle_stringAllocator for the individual strings to be
805  * allocated.
806  * The caller is responsible for freeing the returned data.
807  *
808  * This function returns the size in bytes required to fit the fill list of keys.
809  * The supplied buffer will be filled in based on the smaller of the supplied
810  * bufferSizeBytes or the actual size of the stored data.
811  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
812  * actual stored data, then not all of the stored data will be returned.
813  *
814  * Users can call this function with null buffer and 0 bufferSizeBytes to get
815  * the required size of the buffer to use on a subsequent call.
816  *
817  * \param pBundle to operate on
818  * \param outKeys pointer to a pre-allocated buffer to write the UTF-8 keys to
819  * \param bufferSizeBytes size of the pre-allocated buffer
820  * \param stringAllocator function pointer to the string allocator
821  * \param context pointer that will be passed to the stringAllocator
822  *
823  * \return size of the buffer of keys in bytes. This is the required size of the
824  * pre-allocated user supplied buffer if all of the stored contents are desired.
825  *         APERSISTABLEBUNDLE_ALLOCATOR_FAILED if the provided allocator fails
826  */
827 int32_t APersistableBundle_getIntVectorKeys(const APersistableBundle* _Nonnull pBundle,
828                                             char* _Nullable* _Nullable outKeys,
829                                             int32_t bufferSizeBytes,
830                                             APersistableBundle_stringAllocator stringAllocator,
831                                             void* _Nullable context)
832         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
833 
834 /**
835  * Get all of the keys associated with this specific type and place it in the
836  * provided pre-allocated buffer from the user. The user must provide an
837  * APersistableBundle_stringAllocator for the individual strings to be
838  * allocated.
839  * The caller is responsible for freeing the returned data.
840  *
841  * This function returns the size in bytes required to fit the fill list of keys.
842  * The supplied buffer will be filled in based on the smaller of the supplied
843  * bufferSizeBytes or the actual size of the stored data.
844  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
845  * actual stored data, then not all of the stored data will be returned.
846  *
847  * Users can call this function with null buffer and 0 bufferSizeBytes to get
848  * the required size of the buffer to use on a subsequent call.
849  *
850  * \param pBundle to operate on
851  * \param outKeys pointer to a pre-allocated buffer to write the UTF-8 keys to
852  * \param bufferSizeBytes size of the pre-allocated buffer
853  * \param stringAllocator function pointer to the string allocator
854  * \param context pointer that will be passed to the stringAllocator
855  *
856  * \return size of the buffer of keys in bytes. This is the required size of the
857  * pre-allocated user supplied buffer if all of the stored contents are desired.
858  *         APERSISTABLEBUNDLE_ALLOCATOR_FAILED if the provided allocator fails
859  */
860 int32_t APersistableBundle_getLongVectorKeys(const APersistableBundle* _Nonnull pBundle,
861                                              char* _Nullable* _Nullable outKeys,
862                                              int32_t bufferSizeBytes,
863                                              APersistableBundle_stringAllocator stringAllocator,
864                                              void* _Nullable context)
865         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
866 
867 /**
868  * Get all of the keys associated with this specific type and place it in the
869  * provided pre-allocated buffer from the user. The user must provide an
870  * APersistableBundle_stringAllocator for the individual strings to be
871  * allocated.
872  * The caller is responsible for freeing the returned data.
873  *
874  * This function returns the size in bytes required to fit the fill list of keys.
875  * The supplied buffer will be filled in based on the smaller of the supplied
876  * bufferSizeBytes or the actual size of the stored data.
877  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
878  * actual stored data, then not all of the stored data will be returned.
879  *
880  * Users can call this function with null buffer and 0 bufferSizeBytes to get
881  * the required size of the buffer to use on a subsequent call.
882  *
883  * \param pBundle to operate on
884  * \param outKeys pointer to a pre-allocated buffer to write the UTF-8 keys to
885  * \param bufferSizeBytes size of the pre-allocated buffer
886  * \param stringAllocator function pointer to the string allocator
887  * \param context pointer that will be passed to the stringAllocator
888  *
889  * \return size of the buffer of keys in bytes. This is the required size of the
890  * pre-allocated user supplied buffer if all of the stored contents are desired.
891  */
892 int32_t APersistableBundle_getDoubleVectorKeys(const APersistableBundle* _Nonnull pBundle,
893                                                char* _Nullable* _Nullable outKeys,
894                                                int32_t bufferSizeBytes,
895                                                APersistableBundle_stringAllocator stringAllocator,
896                                                void* _Nullable context)
897         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
898 
899 /**
900  * Get all of the keys associated with this specific type and place it in the
901  * provided pre-allocated buffer from the user. The user must provide an
902  * APersistableBundle_stringAllocator for the individual strings to be
903  * allocated.
904  * The caller is responsible for freeing the returned data.
905  *
906  * This function returns the size in bytes required to fit the fill list of keys.
907  * The supplied buffer will be filled in based on the smaller of the supplied
908  * bufferSizeBytes or the actual size of the stored data.
909  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
910  * actual stored data, then not all of the stored data will be returned.
911  *
912  * Users can call this function with null buffer and 0 bufferSizeBytes to get
913  * the required size of the buffer to use on a subsequent call.
914  *
915  * \param pBundle to operate on
916  * \param outKeys pointer to a pre-allocated buffer to write the UTF-8 keys to
917  * \param bufferSizeBytes size of the pre-allocated buffer
918  * \param stringAllocator function pointer to the string allocator
919  * \param context pointer that will be passed to the stringAllocator
920  *
921  * \return size of the buffer of keys in bytes. This is the required size of the
922  * pre-allocated user supplied buffer if all of the stored contents are desired.
923  *         false
924  */
925 int32_t APersistableBundle_getStringVectorKeys(const APersistableBundle* _Nonnull pBundle,
926                                                char* _Nullable* _Nullable outKeys,
927                                                int32_t bufferSizeBytes,
928                                                APersistableBundle_stringAllocator stringAllocator,
929                                                void* _Nullable context)
930         __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
931 
932 /**
933  * Get all of the keys associated with this specific type and place it in the
934  * provided pre-allocated buffer from the user. The user must provide an
935  * APersistableBundle_stringAllocator for the individual strings to be
936  * allocated.
937  * The caller is responsible for freeing the returned data in bytes.
938  *
939  * This function returns the size in bytes required to fit the fill list of keys.
940  * The supplied buffer will be filled in based on the smaller of the supplied
941  * bufferSizeBytes or the actual size of the stored data.
942  * If the buffer is null or if the supplied bufferSizeBytes is smaller than the
943  * actual stored data, then not all of the stored data will be returned.
944  *
945  * Users can call this function with null buffer and 0 bufferSizeBytes to get
946  * the required size of the buffer to use on a subsequent call.
947  *
948  * \param pBundle to operate on
949  * \param outKeys pointer to a pre-allocated buffer to write the UTF-8 keys to
950  * \param bufferSizeBytes size of the pre-allocated buffer
951  * \param stringAllocator function pointer to the string allocator
952  * \param context pointer that will be passed to the stringAllocator
953  *
954  * \return size of the buffer of keys in bytes. This is the required size of the
955  * pre-allocated user supplied buffer if all of the stored contents are desired.
956  *         APERSISTABLEBUNDLE_ALLOCATOR_FAILED if the provided allocator fails
957  */
958 int32_t APersistableBundle_getPersistableBundleKeys(
959         const APersistableBundle* _Nonnull pBundle, char* _Nullable* _Nullable outKeys,
960         int32_t bufferSizeBytes, APersistableBundle_stringAllocator stringAllocator,
961         void* _Nullable context) __INTRODUCED_IN(__ANDROID_API_V__) __INTRODUCED_IN_LLNDK(202404);
962 
963 __END_DECLS
964