2 * Copyright (c) 2020 Samsung Electronics Co., Ltd. All rights reserved.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
25 * @addtogroup CORE_LIB_PARCEL_MODULE
34 * @brief The parcel handle.
37 typedef void *parcel_h;
40 * @brief The interface for converting data to/from a parcel.
44 void (*to)(parcel_h parcel, void *data);
45 void (*from)(parcel_h parcel, void *data);
49 * @brief Enumeration for error codes for a parcel.
53 PARCEL_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
54 PARCEL_ERROR_ILLEGAL_BYTE_SEQ = TIZEN_ERROR_ILLEGAL_BYTE_SEQ, /**< Illegal byte sequence */
55 PARCEL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
56 PARCEL_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA, /**< No data available */
57 PARCEL_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
61 * @brief Creates a parcel handle.
63 * @remarks You MUST release @a parcel using parcel_destroy().
64 * @param[out] parcel The parcel handle that is newly created
65 * @return @c 0 on success,
66 * otherwise a negative error value
67 * @retval #PARCEL_ERROR_NONE Successful
68 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
69 * @retval #PARCEL_ERROR_OUT_OF_MEMORY Out of memory
70 * @see parcel_destroy()
72 int parcel_create(parcel_h *parcel);
75 * @brief Destroys a parcel handle.
77 * @param[in] parcel The parcel handle
78 * @return @c 0 on success,
79 * otherwise a negative error value
80 * @retval #PARCEL_ERROR_NONE Successful
81 * @retval #PARCEL_ERROR_INVALID_PARAMETER
82 * @see parcel_create()
84 int parcel_destroy(parcel_h parcel);
87 * @brief Creates and returns a copy of the given parcel handle.
89 * @remarks A newly created parcel should be destroyed by calling the parcel_destroy() if it is no longer needed.
90 * @param[in] parcel The parcel handle
91 * @param[out] If successful, a newly created parcel handle will be returned
92 * @return @c 0 on success,
93 * otherwise a negative error value
94 * @retval #PARCEL_ERROR_NONE Successful
95 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
96 * @see parcel_destroy()
98 int parcel_clone(parcel_h parcel, parcel_h *clone);
101 * @brief Writes bytes to the parcel handle.
103 * @param[in] parcel The parcel handle
104 * @param[in] buf The array buffer to write
105 * @param[in] size The size of bytes to write
106 * @return @c 0 on success,
107 * otherwise a negative error value
108 * @retval #PARCEL_ERROR_NONE Successful
109 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
110 * @see parcel_burst_read()
112 int parcel_burst_write(parcel_h parcel, const void *buf, uint32_t size);
115 * @brief Reads bytes from the parcel handle.
117 * @param[in] parcel The parcel handle
118 * @param[out] buf The array buffer to read
119 * @param[in] size The size of bytes to read
120 * @return @c 0 on success,
121 * otherwise a negative error value
122 * @retval #PARCEL_ERROR_NONE Successful
123 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
124 * @retval #PARCEL_ERROR_NO_DATA No data available
125 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
126 * @see parcel_burst_write()
128 int parcel_burst_read(parcel_h parcel, void *buf, uint32_t size);
131 * @brief Writes a boolean value into the parcel handle.
133 * @param[in] parcel The parcel handle
134 * @param[in] val The boolean value
135 * @return @c 0 on success,
136 * otherwise a negative error value
137 * @retval #PARCEL_ERROR_NONE Successful
138 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
139 * @see parcel_read_bool()
141 int parcel_write_bool(parcel_h parcel, bool val);
144 * @brief Writes a byte value into the parcel handle.
146 * @param[in] parcel The parcel handle
147 * @param[in] val The byte value
148 * @return @c 0 on success,
149 * otherwise a negative error value
150 * @retval #PARCEL_ERROR_NONE Successful
151 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
152 * @see parcel_read_uint8()
154 int parcel_write_byte(parcel_h parcel, char val);
157 * @brief Writes an unsigned short value into the parcel handle.
159 * @param[in] parcel The parcel handle
160 * @param[in] val The unsigned short value
161 * @return @c 0 on success,
162 * otherwise a negative error value
163 * @retval #PARCEL_ERROR_NONE Successful
164 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
165 * @see parcel_read_uint16()
167 int parcel_write_uint16(parcel_h parcel, uint16_t val);
170 * @brief Writes an unsigned integer value into the parcel handle.
172 * @param[in] parcel The parcel handle
173 * @param[in] val The unsigned integer value
174 * @return @c 0 on success,
175 * otherwise a negative error value
176 * @retval #PARCEL_ERROR_NONE Successful
177 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
178 * @see parcel_read_uint32()
180 int parcel_write_uint32(parcel_h parcel, uint32_t val);
183 * @brief Writes an unsigned long long integer value into the parcel handle.
185 * @param[in] parcel The parcel handle
186 * @param[in] val The unsigned long long interger value
187 * @return @c 0 on success,
188 * otherwise a negative error value
189 * @retval #PARCEL_ERROR_NONE Successful
190 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
191 * @see parcel_read_uint64()
193 int parcel_write_uint64(parcel_h parcel, uint64_t val);
196 * @brief Writes a signed short value into the parcel handle.
198 * @param[in] parcel The parcel handle
199 * @param[in] val The signed short value
200 * @return @c 0 on success,
201 * otherwise a negative error value
202 * @retval #PARCEL_ERROR_NONE Successful
203 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
204 * @see parcel_read_int16()
206 int parcel_write_int16(parcel_h parcel, int16_t val);
209 * @brief Writes a signed integer value into the parcel handle.
211 * @param[in] parcel The parcel handle
212 * @param[in] val The signed integer value
213 * @return @c 0 on success,
214 * otherwise a negative error value
215 * @retval #PARCEL_ERROR_NONE Successful
216 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
217 * @see parcel_read_int32()
219 int parcel_write_int32(parcel_h parcel, int32_t val);
222 * @brief Writes a signed long long integer value into the parcel handle.
224 * @param[in] parcel The parcel handle
225 * @param[in] val The signedi long long integer value
226 * @return @c 0 on success,
227 * otherwise a negative error value
228 * @retval #PARCEL_ERROR_NONE Successful
229 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
230 * @see parcel_read_int64()
232 int parcel_write_int64(parcel_h parcel, int64_t val);
235 * @brief Writes a floating point value into the parcel handle.
237 * @param[in] parcel The parcel handle
238 * @param[in] val The floating point value
239 * @return @c 0 on success,
240 * otherwise a negative error value
241 * @retval #PARCEL_ERROR_NONE Successful
242 * @retval #PARCLE_ERROR_INVALID_PARAMETER Invalid parameter
243 * @see parcel_read_float()
245 int parcel_write_float(parcel_h parcel, float val);
248 * @brief Writes a double precision floating point value into the parcel handle.
250 * @param[in] parcel The parcel handle
251 * @param[in] val The double precision floating point value
252 * @return @c 0 on success,
253 * otherwise a negative error value
254 * @retval #PARCEL_ERROR_NONE Successful
255 * @retval #PARCLE_ERROR_INVALID_PARAMETER Invalid parameter
256 * @see parcel_read_double()
258 int parcel_write_double(parcel_h parcel, double val);
261 * @brief Writes a string data into the parcel handle.
263 * @param[in] parcel The parcel handle
264 * @param[in] str The string data
265 * @return @c 0 on success,
266 * otherwise a negative error value
267 * @retval #PARCEL_ERROR_NONE Successful
268 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
269 * @see parcel_read_string()
271 int parcel_write_string(parcel_h parcel, const char *str);
274 * @brief Reads a boolean value from the parcel handle.
276 * @param[in] parcel The parcel handle
277 * @param[out] val The boolean value
278 * @return @c 0 on success,
279 * otherwise a negative error value
280 * @retval #PARCEL_ERROR_NONE Successful
281 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
282 * @retval #PARCEL_ERROR_NO_DATA No data available
283 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
284 * @see parcel_write_bool()
286 int parcel_read_bool(parcel_h parcel, bool *val);
289 * @brief Reads a byte value from the parcel handle.
291 * @param[in] parcel The parcel handle
292 * @param[out] val The byte value
293 * @return @c 0 on success,
294 * otherwise a negative error value
295 * @retval #PARCEL_ERROR_NONE Successful
296 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
297 * @retval #PARCEL_ERROR_NO_DATA No data available
298 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
299 * @see parcel_write_uint8()
301 int parcel_read_byte(parcel_h parcel, char *val);
304 * @brief Reads an unsigned short value from the parcel handle.
306 * @param[in] parcel The parcel handle
307 * @param[out] val The unsigned short value
308 * @return @c 0 on success,
309 * otherwise a negative error value
310 * @retval #PARCEL_ERROR_NONE Successful
311 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
312 * @retval #PARCEL_ERROR_NO_DATA No data available
313 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
314 * @see parcel_write_uint16()
316 int parcel_read_uint16(parcel_h parcel, uint16_t *val);
319 * @brief Reads an unsigned integer value from the parcel handle.
321 * @param[in] parcel The parcel handle
322 * @param[out] val The unsigned integer value
323 * @return @c 0 on success,
324 * otherwise a negative error value
325 * @retval #PARCEL_ERROR_NONE Successful
326 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
327 * @retval #PARCEL_ERROR_NO_DATA No data available
328 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
329 * @see parcel_write_uint32()
331 int parcel_read_uint32(parcel_h parcel, uint32_t *val);
334 * @brief Reads an unsigned long long integer value from the parcel handle.
336 * @param[in] parcel The parcel handle
337 * @param[out] val The unsigned long long integer value
338 * @return @c 0 on success,
339 * otherwise a negative error value
340 * @retval #PARCEL_ERROR_NONE Successful
341 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
342 * @retval #PARCEL_ERROR_NO_DATA No data available
343 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
344 * @see parcel_write_uint64()
346 int parcel_read_uint64(parcel_h parcel, uint64_t *val);
349 * @brief Reads a signed short value from the parcel handle.
351 * @param[in] parcel The parcel handle
352 * @param[out] val The signed short value
353 * @return @c 0 on success,
354 * otherwise a negative error value
355 * @retval #PARCEL_ERROR_NONE Successful
356 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
357 * @retval #PARCEL_ERROR_NO_DATA No data available
358 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
359 * @see parcel_write_int16()
361 int parcel_read_int16(parcel_h parcel, int16_t *val);
364 * @brief Reads a signed integer value from the parcel handle.
366 * @param[in] parcel The parcel handle
367 * @param[out] val The signed integer value
368 * @return @c 0 on success,
369 * otherwise a negative error value
370 * @retval #PARCEL_ERROR_NONE Successful
371 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
372 * @retval #PARCEL_ERROR_NO_DATA No data available
373 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
374 * @see parcel_write_int32()
376 int parcel_read_int32(parcel_h parcel, int32_t *val);
379 * @brief Reads a signed long long integer value from the parcel handle.
381 * @param[in] parcel The parcel handle
382 * @param[out] val The signed long long integer value
383 * @return @c 0 on success,
384 * otherwise a negative error value
385 * @retval #PARCEL_ERROR_NONE Successful
386 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
387 * @retval #PARCEL_ERROR_NO_DATA No data available
388 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
389 * @see parcel_write_int64()
391 int parcel_read_int64(parcel_h parcel, int64_t *val);
394 * @brief Reads a floating point value from the parcel handle.
396 * @param[in] parcel The parcel handle
397 * @param[out] val The floating point value
398 * @return @c 0 on success,
399 * otherwise a negative error value
400 * @retval #PARCEL_ERROR_NONE Successful
401 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
402 * @retval #PARCEL_ERROR_NO_DATA No data available
403 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
404 * @see parcel_write_uint8()
406 int parcel_read_float(parcel_h parcel, float *val);
409 * @brief Reads a double precision floating point value from the parcel handle.
411 * @param[in] parcel The parcel handle
412 * @param[out] val The double precision floating point value
413 * @return @c 0 on success,
414 * otherwise a negative error value
415 * @retval #PARCEL_ERROR_NONE Successful
416 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
417 * @retval #PARCEL_ERROR_NO_DATA No data available
418 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
419 * @see parcel_write_uint8()
421 int parcel_read_double(parcel_h parcel, double *val);
424 * @brief Reads a string data from the parcel handle.
426 * @param[in] parcel The parcel handle
427 * @param[out] str The string data
428 * @return @c 0 on success,
429 * otherwise a negative error value
430 * @retval #PARCEL_ERROR_NONE Successful
431 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
432 * @retval #PARCEL_ERROR_NO_DATA No data available
433 * @retval #PARCEL_ERROR_ILLEGAL_BYTE_SEQ Illegal byte sequence
434 * @retval #PARCEL_ERROR_OUT_OF_MEMORY Out of memory
435 * @see parcel_write_uint8()
437 int parcel_read_string(parcel_h parcel, char **str);
440 * @brief Resets the reader pointer of the parcel handle to the start.
442 * @param[in] parcel The parcel handle
443 * @return @c 0 on success,
444 * otherwise a negative error value
445 * @retval #PARCEL_ERROR_NONE Successful
446 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
448 int parcel_reset_reader(parcel_h parcel);
451 * @brief Clears the data of the parcel handle.
453 * @param[in] parcel The parcel handle
454 * @return @c 0 on success,
455 * otherwise a negative error value
456 * @retval #PARCEL_ERROR_NONE Successful
457 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
459 int parcel_clear(parcel_h parcel);
462 * @brief Resets the data of the parcel handle.
464 * @param[in] parcel The parcel handle
465 * @param[in] buf The array buffer to write
466 * @param[in] size The size of bytes to write
467 * @return @c 0 on success,
468 * otherwise a negative error value
469 * @retval #PARCEL_ERROR_NONE Successful
470 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
472 int parcel_reset(parcel_h parcel, const void *buf, uint32_t size);
475 * @brief Writes the data using @a parcelable to the parcel handle.
477 * @param[in] parcel The parcel handle
478 * @param[in] parcelable The interface to write the data into the parcel handle
479 * @param[in] data The user data which writes into the parcel handle
480 * @return @c 0 on success,
481 * otherwise a negative error value
482 * @retval #PARCEL_ERROR_NONE Successful
483 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
486 int parcel_write(parcel_h parcel, parcelable_t *parcelable, void *data);
489 * @brief Reads the data using @a parcelable from the parcel handle.
491 * @param[in] parcel The parcel handle
492 * @param[in] parcelable The interface to read the data from the parcel handle
493 * @param[in] data The user data which reads from the parcel handle
494 * @return @c 0 on success,
495 * otherwise a negative error value
496 * @retval #PARCEL_ERROR_NONE Successful
497 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
498 * @see parcel_write()
500 int parcel_read(parcel_h parcel, parcelable_t *parcelable, void *data);
503 * @brief Gets the raw data of the parcel handle.
505 * @remarks You MUST NOT release @a raw using free(). It's managed by platform.
506 * @param[in] parcel The parcel handle
507 * @param[out] raw The raw data
508 * @param[out] size The size of the raw data
509 * @return @c 0 on success,
510 * otherwise a negative error value
511 * @retval #PARCEL_ERROR_NONE Successful
512 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
514 int parcel_get_raw(parcel_h parcel, void **raw, uint32_t *size);
517 * @brief Sets byte order of the parcel handle.
519 * @remarks The platform byte order is little-endian.
520 * The network byte order is defined to always be big-endian.
521 * If you want to change byte order of the raw data of the parcel handle,
522 * you set byte order of the parcel handle using the function.
523 * @param[in] parcel The parcel handle
524 * @param[in] big_endian @ true, if byte order of the parcel is big-endian
525 * @return @c 0 on success,
526 * otherwise a negative error value
527 * @retval #PARCEL_ERROR_NONE Successful
528 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
530 int parcel_set_byte_order(parcel_h parcle, bool big_endian);
533 * @brief Gets the size of the data capacity of the parcel handle.
535 * @param[in] parcel The parcel handle
536 * @param[out] size The size of the data capacity
537 * @return @c 0 on success,
538 * otherwise a negative error value
539 * @retval #PARCEL_ERROR_NONE Successful
540 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
542 int parcel_get_data_capacity(parcel_h parcel, size_t *size);
545 * @brief Sets the size of the data capacity of the parcel handle.
547 * @remarks The raw data will be reallocated using the given size.
548 * @param[in] parcel The parcel handle
549 * @param[in] size The size of the data capacity
550 * @return @c 0 on success,
551 * otherwise a negative error value
552 * @retval #PARCEL_ERROR_NONE Successful
553 * @retval #PARCEL_ERROR_INVALID_PARAMETER Invalid parameter
554 * @retval #PARCEL_ERROR_OUT_OF_MEMORY
556 int parcel_set_data_capacity(parcel_h parcel, size_t size);
566 #endif /* __PARCEL_H__ */