parcel/api/parcel.h

   1 /*
   2  * Copyright (c) 2020 Samsung Electronics Co., Ltd. All rights reserved.
   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 #ifndef __PARCEL_H__
  18 #define __PARCEL_H__
  19
  20 #include <stdint.h>
  21 #include <stddef.h>
  22 #include <tizen.h>
  23
  24 /**
  25  * @addtogroup CORE_LIB_PARCEL_MODULE
  26  * @{
  27  */
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34  * @brief The parcel handle.
  35  * @since_tizen 6.5
  36  */
  37 typedef void *parcel_h;
  38
  39 /**
  40  * @brief The interface for converting data to/from a parcel.
  41  * @since_tizen 6.5
  42  */
  43 typedef struct {
  44         void (*to)(parcel_h parcel, void *data);
  45         void (*from)(parcel_h parcel, void *data);
  46 } parcelable_t;
  47
  48 /**
  49  * @brief Enumeration for error codes for a parcel.
  50  * @since_tizen 6.5
  51  */
  52 typedef enum {
  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 */
  58 } parcel_error_e;
  59
  60 /**
  61  * @brief Creates a parcel handle.
  62  * @since_tizen 6.5
  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()
  71  */
  72 int parcel_create(parcel_h *parcel);
  73
  74 /**
  75  * @brief Destroys a parcel handle.
  76  * @since_tizen 6.5
  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()
  83  */
  84 int parcel_destroy(parcel_h parcel);
  85
  86 /**
  87  * @brief Creates and returns a copy of the given parcel handle.
  88  * @since_tizen 6.5
  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()
  97  */
  98 int parcel_clone(parcel_h parcel, parcel_h *clone);
  99
 100 /**
 101  * @brief Writes bytes to the parcel handle.
 102  * @since_tizen 6.5
 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()
 111  */
 112 int parcel_burst_write(parcel_h parcel, const void *buf, uint32_t size);
 113
 114 /**
 115  * @brief Reads bytes from the parcel handle.
 116  * @since_tizen 6.5
 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()
 127  */
 128 int parcel_burst_read(parcel_h parcel, void *buf, uint32_t size);
 129
 130 /**
 131  * @brief Writes a boolean value into the parcel handle.
 132  * @since_tizen 6.5
 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()
 140  */
 141 int parcel_write_bool(parcel_h parcel, bool val);
 142
 143 /**
 144  * @brief Writes a byte value into the parcel handle.
 145  * @since_tizen 6.5
 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()
 153  */
 154 int parcel_write_byte(parcel_h parcel, char val);
 155
 156 /**
 157  * @brief Writes an unsigned short value into the parcel handle.
 158  * @since_tizen 6.5
 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()
 166  */
 167 int parcel_write_uint16(parcel_h parcel, uint16_t val);
 168
 169 /**
 170  * @brief Writes an unsigned integer value into the parcel handle.
 171  * @since_tizen 6.5
 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()
 179  */
 180 int parcel_write_uint32(parcel_h parcel, uint32_t val);
 181
 182 /**
 183  * @brief Writes an unsigned long long integer value into the parcel handle.
 184  * @since_tizen 6.5
 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()
 192  */
 193 int parcel_write_uint64(parcel_h parcel, uint64_t val);
 194
 195 /**
 196  * @brief Writes a signed short value into the parcel handle.
 197  * @since_tizen 6.5
 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()
 205  */
 206 int parcel_write_int16(parcel_h parcel, int16_t val);
 207
 208 /**
 209  * @brief Writes a signed integer value into the parcel handle.
 210  * @since_tizen 6.5
 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()
 218  */
 219 int parcel_write_int32(parcel_h parcel, int32_t val);
 220
 221 /**
 222  * @brief Writes a signed long long integer value into the parcel handle.
 223  * @since_tizen 6.5
 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()
 231  */
 232 int parcel_write_int64(parcel_h parcel, int64_t val);
 233
 234 /**
 235  * @brief Writes a floating point value into the parcel handle.
 236  * @since_tizen 6.5
 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()
 244  */
 245 int parcel_write_float(parcel_h parcel, float val);
 246
 247 /**
 248  * @brief Writes a double precision floating point value into the parcel handle.
 249  * @since_tizen 6.5
 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()
 257  */
 258 int parcel_write_double(parcel_h parcel, double val);
 259
 260 /**
 261  * @brief Writes a string data into the parcel handle.
 262  * @since_tizen 6.5
 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()
 270  */
 271 int parcel_write_string(parcel_h parcel, const char *str);
 272
 273 /**
 274  * @brief Reads a boolean value from the parcel handle.
 275  * @since_tizen 6.5
 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()
 285  */
 286 int parcel_read_bool(parcel_h parcel, bool *val);
 287
 288 /**
 289  * @brief Reads a byte value from the parcel handle.
 290  * @since_tizen 6.5
 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()
 300  */
 301 int parcel_read_byte(parcel_h parcel, char *val);
 302
 303 /**
 304  * @brief Reads an unsigned short value from the parcel handle.
 305  * @since_tizen 6.5
 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()
 315  */
 316 int parcel_read_uint16(parcel_h parcel, uint16_t *val);
 317
 318 /**
 319  * @brief Reads an unsigned integer value from the parcel handle.
 320  * @since_tizen 6.5
 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()
 330  */
 331 int parcel_read_uint32(parcel_h parcel, uint32_t *val);
 332
 333 /**
 334  * @brief Reads an unsigned long long integer value from the parcel handle.
 335  * @since_tizen 6.5
 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()
 345  */
 346 int parcel_read_uint64(parcel_h parcel, uint64_t *val);
 347
 348 /**
 349  * @brief Reads a signed short value from the parcel handle.
 350  * @since_tizen 6.5
 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()
 360  */
 361 int parcel_read_int16(parcel_h parcel, int16_t *val);
 362
 363 /**
 364  * @brief Reads a signed integer value from the parcel handle.
 365  * @since_tizen 6.5
 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()
 375  */
 376 int parcel_read_int32(parcel_h parcel, int32_t *val);
 377
 378 /**
 379  * @brief Reads a signed long long integer value from the parcel handle.
 380  * @since_tizen 6.5
 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()
 390  */
 391 int parcel_read_int64(parcel_h parcel, int64_t *val);
 392
 393 /**
 394  * @brief Reads a floating point value from the parcel handle.
 395  * @since_tizen 6.5
 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()
 405  */
 406 int parcel_read_float(parcel_h parcel, float *val);
 407
 408 /**
 409  * @brief Reads a double precision floating point value from the parcel handle.
 410  * @since_tizen 6.5
 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()
 420  */
 421 int parcel_read_double(parcel_h parcel, double *val);
 422
 423 /**
 424  * @brief Reads a string data from the parcel handle.
 425  * @since_tizen 6.5
 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()
 436  */
 437 int parcel_read_string(parcel_h parcel, char **str);
 438
 439 /**
 440  * @brief Resets the reader pointer of the parcel handle to the start.
 441  * @since_tizen 6.5
 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
 447  */
 448 int parcel_reset_reader(parcel_h parcel);
 449
 450 /**
 451  * @brief Clears the data of the parcel handle.
 452  * @since_tizen 6.5
 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
 458  */
 459 int parcel_clear(parcel_h parcel);
 460
 461 /**
 462  * @brief Resets the data of the parcel handle.
 463  * @since_tizen 6.5
 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
 471  */
 472 int parcel_reset(parcel_h parcel, const void *buf, uint32_t size);
 473
 474 /**
 475  * @brief Writes the data using @a parcelable to the parcel handle.
 476  * @since_tizen 6.5
 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
 484  * @see parcel_read()
 485  */
 486 int parcel_write(parcel_h parcel, parcelable_t *parcelable, void *data);
 487
 488 /**
 489  * @brief Reads the data using @a parcelable from the parcel handle.
 490  * @since_tizen 6.5
 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()
 499  */
 500 int parcel_read(parcel_h parcel, parcelable_t *parcelable, void *data);
 501
 502 /**
 503  * @brief Gets the raw data of the parcel handle.
 504  * @since_tizen 6.5
 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
 513  */
 514 int parcel_get_raw(parcel_h parcel, void **raw, uint32_t *size);
 515
 516 /**
 517  * @brief Sets byte order of the parcel handle.
 518  * @since_tizen 6.5
 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
 529  */
 530 int parcel_set_byte_order(parcel_h parcle, bool big_endian);
 531
 532 #ifdef __cplusplus
 533 }
 534 #endif
 535
 536 /**
 537  * @}
 538  */
 539
 540 #endif /* __PARCEL_H__ */