include/messages.h

   1 /*
   2  * Copyright (c) 2011 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 __TIZEN_MESSAGING_H__
  18 #define __TIZEN_MESSAGING_H__
  19
  20
  21 #include <time.h>
  22 #include <messages_types.h>
  23 #include <messages_error.h>
  24
  25 #ifdef __cplusplus
  26 extern "C"
  27 {
  28 #endif
  29
  30 /*
  31  * @file messages.h
  32  * @brief This file contains the messages API.
  33  */
  34
  35
  36 /**
  37  * @addtogroup CAPI_MESSAGING_MESSAGES_MODULE
  38  * @{
  39  */
  40
  41
  42 /**
  43  * @brief Opens a handle for the messaging service.
  44  *
  45  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  46  * @privlevel public
  47  * @privilege %http://tizen.org/privilege/message.read
  48  *
  49  * @remarks You must release @a service using messages_close_service().
  50  *
  51  * @param[out] service The message service handle
  52  *
  53  * @return @c 0 on success,
  54  *       otherwise a negative error value
  55  *
  56  * @retval #MESSAGES_ERROR_NONE                             Successful
  57  * @retval #MESSAGES_ERROR_INVALID_PARAMETER                Invalid parameter
  58  * @retval #MESSAGES_ERROR_SERVER_NOT_READY                 Server is not read
  59  * @retval #MESSAGES_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed
  60  * @retval #MESSAGES_ERROR_PERMISSION_DENIED                The application does not have the privilege to call this method
  61  * @retval #MESSAGES_ERROR_NOT_SUPPORTED                    Not supported
  62  *
  63  * @see messages_close_service()
  64  */
  65 int messages_open_service(messages_service_h *service);
  66
  67
  68 /**
  69  * @brief Closes a handle for the messaging service.
  70  *
  71  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  72  * @privlevel public
  73  * @privilege %http://tizen.org/privilege/message.read
  74  *
  75  * @param[in] service The message service handle
  76  *
  77  * @return @c 0 on success,
  78  *        otherwise a negative error value
  79  *
  80  * @retval #MESSAGES_ERROR_NONE                             Successful
  81  * @retval #MESSAGES_ERROR_INVALID_PARAMETER                Invalid parameter
  82  * @retval #MESSAGES_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed
  83  * @retval #MESSAGES_ERROR_PERMISSION_DENIED                The application does not have the privilege to call this method
  84  * @retval #MESSAGES_ERROR_NOT_SUPPORTED                    Not supported
  85  *
  86  * @see messages_open_service()
  87  */
  88 int messages_close_service(messages_service_h service);
  89
  90
  91 /**
  92  * @brief Creates a message handle.
  93  *
  94  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  95  *
  96  * @remarks You must release @a msg using messages_destroy_message().
  97  *
  98  * @param[in] type  The message type (#MESSAGES_TYPE_SMS or #MESSAGES_TYPE_MMS) \n
  99  *                  If @a type is #MESSAGES_TYPE_UNKNOWN, #MESSAGES_ERROR_INVALID_PARAMETER occurs.
 100  * @param[out] msg  The message handle that is newly created if successful
 101  *
 102  * @return @c 0 on success,
 103  *       otherwise a negative error value
 104  *
 105  * @retval #MESSAGES_ERROR_NONE              Successful
 106  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 107  * @retval #MESSAGES_ERROR_OUT_OF_MEMORY     Out of memory
 108  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 109  *
 110  * @see messages_destroy_message()
 111  */
 112 int messages_create_message(messages_message_type_e type, messages_message_h *msg);
 113
 114
 115 /**
 116  * @brief Destroys a message handle and releases all its resources.
 117  *
 118  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 119  *
 120  * @param[in] msg The message handle to destroy
 121  *
 122  * @return @c 0 on success,
 123  *       otherwise a negative error value
 124  *
 125  * @retval #MESSAGES_ERROR_NONE               Successful
 126  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 127  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 128  *
 129  * @see messages_create_message()
 130  */
 131 int messages_destroy_message(messages_message_h msg);
 132
 133 /**
 134  * @brief Gets the message ID of the message.
 135  *
 136  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 137  *
 138  * @param[in]  msg     The message handle
 139  * @param[out] msg_id  The message ID
 140  *
 141  * @return @c 0 on success,
 142  *       otherwise a negative error value
 143  *
 144  * @retval #MESSAGES_ERROR_NONE               Successful
 145  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 146  * @retval #MESSAGES_ERROR_OPERATION_FAILED   Messaging operation failed
 147  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 148  *
 149  * @see messages_search_message_by_id()
 150  */
 151 int messages_get_message_id(messages_message_h msg, int *msg_id);
 152
 153
 154 /**
 155  * @brief Sets the SIM ID of the sending message.
 156  *
 157  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 158  *
 159  * @param[in]  msg     The message handle
 160  * @param[in]  sim_id  The SIM id to send message
 161  *
 162  * @return @c 0 on success,
 163  *       otherwise a negative error value
 164  *
 165  * @retval #MESSAGES_ERROR_NONE               Successful
 166  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 167  * @retval #MESSAGES_ERROR_OPERATION_FAILED   Messaging operation failed
 168  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 169  *
 170  * @see messages_get_sim_id()
 171  */
 172 int messages_set_sim_id(messages_message_h msg, int sim_id);
 173
 174
 175 /**
 176  * @brief Gets the SIM ID of the message.
 177  *
 178  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 179  *
 180  * @param[in]  msg     The message handle
 181  * @param[out] sim_id  The SIM id of message
 182  *
 183  * @return @c 0 on success,
 184  *       otherwise a negative error value
 185  *
 186  * @retval #MESSAGES_ERROR_NONE               Successful
 187  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 188  * @retval #MESSAGES_ERROR_OPERATION_FAILED   Messaging operation failed
 189  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 190  *
 191  * @see messages_set_sim_id()
 192  */
 193 int messages_get_sim_id(messages_message_h msg, int *sim_id);
 194
 195
 196 /**
 197  * @brief Gets the message box type of the message.
 198  *
 199  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 200  *
 201  * @param[in]  msg   The message handle
 202  * @param[out] mbox  The message box type
 203  *
 204  * @return @c 0 on success,
 205  *       otherwise a negative error value
 206  *
 207  * @retval #MESSAGES_ERROR_NONE               Successful
 208  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 209  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 210  */
 211 int messages_get_mbox_type(messages_message_h msg, messages_message_box_e *mbox);
 212
 213 /**
 214  * @brief Gets the destination port of the message.
 215  *
 216  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 217  *
 218  * @param[in]  msg   The message handle
 219  * @param[out] port  The destination port of the message
 220  *
 221  * @return @c 0 on success,
 222  *       otherwise a negative error value
 223  *
 224  * @retval #MESSAGES_ERROR_NONE               Successful
 225  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 226  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 227  *
 228  * @see messages_add_sms_listening_port()
 229  */
 230 int messages_get_message_port(messages_message_h msg, int *port);
 231
 232 /**
 233  * @brief Gets the type of the message.
 234  *
 235  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 236  *
 237  * @param[in]  msg  The message handle
 238  * @param[out] type The message type
 239  *
 240  * @return @c 0 on success,
 241  *       otherwise a negative error value
 242  *
 243  * @retval #MESSAGES_ERROR_NONE               Successful
 244  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 245  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 246  */
 247 int messages_get_message_type(messages_message_h msg, messages_message_type_e *type);
 248
 249
 250 /**
 251  * @brief Adds an recipient's address(phone number) to the message.
 252  * @details The maximum number of recipients per a message is 10.
 253  *
 254  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 255  *
 256  * @param[in] msg      The message handle
 257  * @param[in] address  The recipient's address to receive a message \n
 258  *                     The maximum length of @a address is @c 254.
 259  * @param[in] type     The recipient's type of the @a address
 260  *
 261  * @return @c 0 on success,
 262  *       otherwise a negative error value
 263  *
 264  * @retval #MESSAGES_ERROR_NONE               Successful
 265  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 266  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 267  *
 268  * @see messages_get_address()
 269  * @see messages_remove_all_addresses()
 270  */
 271 int messages_add_address(messages_message_h msg, const char *address, messages_recipient_type_e type);
 272
 273
 274 /**
 275  * @brief Gets the total number of recipients in the message.
 276  *
 277  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 278  *
 279  * @param[in]  msg    The message handle
 280  * @param[out] count  The total number of recipients
 281  *
 282  * @return @c 0 on success,
 283  *       otherwise a negative error value
 284  *
 285  * @retval #MESSAGES_ERROR_NONE               Successful
 286  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 287  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 288  *
 289  * @see messages_add_address()
 290  * @see messages_remove_all_addresses()
 291  */
 292 int messages_get_address_count(messages_message_h msg, int *count);
 293
 294
 295 /**
 296  * @brief Gets a recipient's address with specified index.
 297  *
 298  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 299  *
 300  * @remarks You must release @a address using free().
 301  *
 302  * @param[in]  msg      The message handle
 303  * @param[in]  index    The zero-based index of an address to receive a message.
 304  * @param[out] address  The recipient's address with specified index
 305  * @param[out] type     The recipient's type of the @a address
 306  *
 307  * @return @c 0 on success,
 308  *       otherwise a negative error value
 309  *
 310  * @retval #MESSAGES_ERROR_NONE               Successful
 311  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 312  * @retval #MESSAGES_ERROR_OUT_OF_MEMORY      Out of memory
 313  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 314  *
 315  * @see messages_add_address()
 316  * @see messages_remove_all_addresses()
 317  */
 318 int messages_get_address(messages_message_h msg, int index, char **address, messages_recipient_type_e *type);
 319
 320
 321 /**
 322  * @brief Removes all recipients in the message.
 323  *
 324  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 325  *
 326  * @param[in] msg The message handle
 327  *
 328  * @return @c 0 on success,
 329  *       otherwise a negative error value
 330  *
 331  * @retval #MESSAGES_ERROR_NONE               Successful
 332  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 333  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 334  *
 335  * @see messages_add_address()
 336  * @see messages_get_address()
 337  */
 338 int messages_remove_all_addresses(messages_message_h msg);
 339
 340
 341 /**
 342  * @brief Sets the text of the message.
 343  *
 344  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 345  *
 346  * @param[in] msg  The message handle
 347  * @param[in] text The text of the message \n
 348  *                 The maximum length of @a text is @c 1530.
 349  *
 350  * @return @c 0 on success,
 351  *       otherwise a negative error value
 352  *
 353  * @retval #MESSAGES_ERROR_NONE               Successful
 354  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 355  * @retval #MESSAGES_ERROR_OUT_OF_MEMORY      Out of memory
 356  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 357  *
 358  * @see messages_get_text()
 359  */
 360 int messages_set_text(messages_message_h msg, const char *text);
 361
 362
 363 /**
 364  * @brief Gets the text of the message.
 365  *
 366  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 367  *
 368  * @remarks You must release @a text using free().
 369  *
 370  * @param[in]  msg   The message handle
 371  * @param[out] text  The text of the message
 372  *
 373  * @return @c 0 on success,
 374  *       otherwise a negative error value
 375  *
 376  * @retval #MESSAGES_ERROR_NONE               Successful
 377  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 378  * @retval #MESSAGES_ERROR_OUT_OF_MEMORY      Out of memory
 379  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 380  *
 381  * @see messages_set_text()
 382  */
 383 int messages_get_text(messages_message_h msg, char **text);
 384
 385
 386 /**
 387  * @brief Gets the time of the message.
 388  *
 389  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 390  *
 391  * @param[in]  msg   The message handle
 392  * @param[out] time  The time of the message
 393  *
 394  * @return @c 0 on success,
 395  *       otherwise a negative error value
 396  *
 397  * @retval #MESSAGES_ERROR_NONE               Successful
 398  * @retval #MESSAGES_ERROR_INVALID_PARAMETER  Invalid parameter
 399  * @retval #MESSAGES_ERROR_NOT_SUPPORTED      Not supported
 400  */
 401 int messages_get_time(messages_message_h msg, time_t *time);
 402
 403 /**
 404  * @brief Sends the message to all recipients.
 405  *
 406  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 407  * @privlevel public
 408  * @privilege %http://tizen.org/privilege/message.write
 409  *
 410  * @param[in] service         The message service handle
 411  * @param[in] msg             The message handle
 412  * @param[in] save_to_sentbox Set to @c true to save the message in the sentbox,
 413  *                            otherwise set to @c false to not save the message in the sentbox
 414  * @param[in] callback        The callback function
 415  * @param[in] user_data       The user data to be passed to the callback function
 416  *
 417  * @return @c 0 on success,
 418  *       otherwise a negative error value
 419  *
 420  * @retval #MESSAGES_ERROR_NONE              Successful
 421  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 422  * @retval #MESSAGES_ERROR_SENDING_FAILED    Sending a message failed
 423  * @retval #MESSAGES_ERROR_OPERATION_FAILED  Messaging operation failed
 424  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 425  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 426  *
 427  * @see messages_sent_cb()
 428  */
 429 int messages_send_message(messages_service_h service, messages_message_h msg, bool save_to_sentbox, messages_sent_cb callback, void *user_data);
 430
 431 /**
 432  * @brief Gets the message count in the specific message box.
 433  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 434  *
 435  * @privlevel public
 436  * @privilege %http://tizen.org/privilege/message.read
 437  *
 438  * @param[in]  service The message service handle
 439  * @param[in]  mbox    The message box type
 440  * @param[in]  type    The message type \n
 441  *                     If @a type is #MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are counted.
 442  * @param[out] count   The number of messages
 443  *
 444  * @return @c 0 on success,
 445  *       otherwise a negative error value
 446  *
 447  * @retval #MESSAGES_ERROR_NONE              Successful
 448  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 449  * @retval #MESSAGES_ERROR_OPERATION_FAILED  Messaging operation failed
 450  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 451  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 452  *
 453  */
 454 int messages_get_message_count(messages_service_h service,
 455                                                         messages_message_box_e mbox, messages_message_type_e type,
 456                                                         int *count);
 457
 458
 459
 460 /**
 461  * @brief Searches for messages.
 462  *
 463  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 464  * @privlevel public
 465  * @privilege %http://tizen.org/privilege/message.read
 466  *
 467  * @remarks You must release @a message_array using messages_free_message_array().
 468  *
 469  * @param[in] service         The message service handle
 470  * @param[in] mbox            The message box type
 471  * @param[in] type            The message type \n
 472  *                            If @a type is #MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are searched.
 473  * @param[in] keyword         The keyword search in the text and subject
 474  * @param[in] address         The recipient address
 475  * @param[in] offset          The start position (base @c 0)
 476  * @param[in] limit           The maximum amount of messages to get \n
 477  *                    In case of @c 0, this method passes to the callback all searched messages.
 478  * @param[out] message_array  The array of the message handle
 479  * @param[out] length         The number of messages of the @a message_array
 480  * @param[out] total          The count of the messages that have been retrieved as a result without applying @a limit and @a offset\ n
 481  *                            The value can be used to calculate the total number of page views for the searched messages\ n
 482  *                            For example, if the count of message search is @c 50 and the limit is @c 20, then using this value, you can notice the total page is @c 3.
 483  *
 484  * @return @c 0 on success,
 485  *       otherwise a negative error value
 486  *
 487  * @retval #MESSAGES_ERROR_NONE              Successful
 488  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 489  * @retval #MESSAGES_ERROR_OUT_OF_MEMORY     Out of memory
 490  * @retval #MESSAGES_ERROR_OPERATION_FAILED  Messaging operation failed
 491  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 492  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 493  *
 494  * @see messages_free_message_array()
 495  */
 496 int messages_search_message(messages_service_h service,
 497                                                         messages_message_box_e mbox,
 498                                                         messages_message_type_e type,
 499                                                         const char *keyword, const char *address,
 500                                                         int offset, int limit,
 501                                                         messages_message_h **message_array, int *length, int *total);
 502
 503 /**
 504  * @brief Searches a message with the given message ID.
 505  *
 506  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 507  * @privlevel public
 508  * @privilege %http://tizen.org/privilege/message.read
 509  *
 510  * @remarks You must release @a msg using messages_destroy_message().
 511  *
 512  * @param[in]  service The message service handle
 513  * @param[in]  msg_id  The message ID
 514  * @param[out] msg     The message handle that is newly created if successful
 515  *
 516  * @return @c 0 on success,
 517  *       otherwise a negative error value
 518  *
 519  * @retval #MESSAGES_ERROR_NONE              Successful
 520  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 521  * @retval #MESSAGES_ERROR_OUT_OF_MEMORY     Out of memory
 522  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 523  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 524  *
 525  * @see messages_get_message_id()
 526  */
 527 int messages_search_message_by_id(messages_service_h service, int msg_id, messages_message_h *msg);
 528
 529
 530 /**
 531  * @brief Frees the message array.
 532  *
 533  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 534  *
 535  * @param[in] message_array The array of the message handle
 536  *
 537  * @return @c 0 on success,
 538  *       otherwise a negative error value
 539  *
 540  * @retval #MESSAGES_ERROR_NONE              Successful
 541  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 542  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 543  *
 544  * @see messages_search_message()
 545  */
 546 int messages_free_message_array(messages_message_h *message_array);
 547
 548
 549 /**
 550  * @brief Retrieves the searched messages by invoking the given callback function iteratively.
 551  *
 552  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 553  * @privlevel public
 554  * @privilege %http://tizen.org/privilege/message.read
 555  *
 556  * @param[in] service   The message service handle
 557  * @param[in] mbox      The message box type
 558  * @param[in] type      The message type \n
 559  *                      If @a type is #MESSAGES_TYPE_UNKNOWN, all SMS and MMS messages are searched.
 560  * @param[in] keyword   The keyword search in the text and subject
 561  * @param[in] address   The recipient address
 562  * @param[in] offset    The start position (base 0)
 563  * @param[in] limit     The maximum amount of messages to get \n
 564  *              In case of @c 0, this method passes to the callback all searched messages.
 565  * @param[in] callback  The callback function to get a message
 566  * @param[in] user_data The user data to be passed to the callback function
 567  *
 568  * @return @c 0 on success,
 569  *       otherwise a negative error value
 570  *
 571  * @retval #MESSAGES_ERROR_NONE              Successful
 572  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 573  * @retval #MESSAGES_ERROR_OUT_OF_MEMORY     Out of memory
 574  * @retval #MESSAGES_ERROR_OPERATION_FAILED  Messaging operation failed
 575  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 576  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 577  *
 578  * @post It invokes messages_search_cb().
 579  *
 580  * @see messages_search_cb()
 581  */
 582 int messages_foreach_message(messages_service_h service,
 583                                                          messages_message_box_e mbox,
 584                                                          messages_message_type_e type,
 585                                                          const char *keyword, const char *address,
 586                                                          int offset, int limit,
 587                                                          messages_search_cb callback, void *user_data);
 588
 589 /**
 590  * @brief Registers a callback to be invoked when an incoming message is received.
 591  *
 592  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 593  * @privlevel public
 594  * @privilege %http://tizen.org/privilege/message.read
 595  *
 596  * @param[in] service   The message service handle
 597  * @param[in] callback  The callback function
 598  * @param[in] user_data The user data to be passed to the callback function
 599  *
 600  * @return @c 0 on success,
 601  *       otherwise a negative error value
 602  *
 603  * @retval #MESSAGES_ERROR_NONE              Successful
 604  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 605  * @retval #MESSAGES_ERROR_OPERATION_FAILED  Messaging operation failed
 606  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 607  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 608  *
 609  * @post It will invoke messages_incoming_cb().
 610  *
 611  * @see messages_unset_message_incoming_cb()
 612  * @see messages_incoming_cb()
 613  */
 614 int messages_set_message_incoming_cb(messages_service_h service, messages_incoming_cb callback, void *user_data);
 615
 616
 617 /**
 618  * @brief Unregisters the callback function.
 619  *
 620  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 621  * @privlevel public
 622  * @privilege %http://tizen.org/privilege/message.write
 623  *
 624  * @param[in] service The message service handle
 625  *
 626  * @return @c 0 on success,
 627  *       otherwise a negative error value
 628  *
 629  * @retval #MESSAGES_ERROR_NONE              Successful
 630  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 631  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 632  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 633  *
 634  * @see messages_set_message_incoming_cb()
 635  * @see messages_incoming_cb()
 636  */
 637 int messages_unset_message_incoming_cb(messages_service_h service);
 638
 639 /**
 640  * @brief Adds an additional listening port for the incoming SMS messages.
 641  *
 642  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 643  * @privlevel public
 644  * @privilege %http://tizen.org/privilege/message.read
 645  *
 646  * @param[in] service The message service handle
 647  * @param[in] port    The listening port for the SMS messages
 648  *
 649  * @return @c 0 on success,
 650  *       otherwise a negative error value
 651  *
 652  * @retval #MESSAGES_ERROR_NONE              Successful
 653  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 654  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 655  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 656  *
 657  * @see messages_set_message_incoming_cb()
 658  * @see messages_get_message_port()
 659  */
 660 int messages_add_sms_listening_port(messages_service_h service, int port);
 661
 662 /**
 663  * @addtogroup CAPI_MESSAGING_MESSAGES_MMS_MODULE
 664  * @{
 665  */
 666 /**
 667  * @brief Sets the subject of the message.
 668  *
 669  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 670  *
 671  * @param[in] msg     The message handle
 672  * @param[in] subject The subject of the message \n
 673  *                    The maximum length of @a subject is @c 120.
 674  *
 675  * @return @c 0 on success,
 676  *       otherwise a negative error value
 677  *
 678  * @retval #MESSAGES_ERROR_NONE              Successful
 679  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 680  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 681  *
 682  * @pre @a msg is created as a #MESSAGES_TYPE_MMS.
 683  *
 684  * @see messages_mms_get_subject()
 685  */
 686 int messages_mms_set_subject(messages_message_h msg, const char *subject);
 687
 688
 689 /**
 690  * @brief Gets the subject of the message.
 691  *
 692  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 693  *
 694  * @remarks You must release @a subject using free().
 695  *
 696  * @param[in]  msg     The message handle
 697  * @param[out] subject The subject of the message
 698  *
 699  * @return @c 0 on success,
 700  *       otherwise a negative error value
 701  *
 702  * @retval #MESSAGES_ERROR_NONE              Successful
 703  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 704  * @retval #MESSAGES_ERROR_OUT_OF_MEMORY     Out of memory
 705  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 706  *
 707  * @pre @a msg is created as a #MESSAGES_TYPE_MMS.
 708  *
 709  * @see messages_mms_set_subject()
 710  */
 711 int messages_mms_get_subject(messages_message_h msg, char **subject);
 712
 713
 714 /**
 715  * @brief Adds the attachment to the MMS message.
 716  *
 717  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 718  *
 719  * @param[in] msg  The message handle
 720  * @param[in] type The attachment type
 721  * @param[in] path The file path to attach \n
 722  *                 The maximum length of @a path is @c 1024.
 723  *
 724  * @return @c 0 on success,
 725  *       otherwise a negative error value
 726  *
 727  * @retval #MESSAGES_ERROR_NONE              Successful
 728  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 729  * @retval #MESSAGES_ERROR_OUT_OF_MEMORY     Out of memory
 730  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 731  *
 732  * @pre @a msg is created as a #MESSAGES_TYPE_MMS.
 733  *
 734  * @see messages_mms_get_attachment()
 735  * @see messages_mms_get_attachment_count()
 736  * @see messages_mms_remove_all_attachments()
 737  */
 738 int messages_mms_add_attachment(messages_message_h msg, messages_media_type_e type, const char *path);
 739
 740
 741 /**
 742  * @brief Gets the file path of the attachment with the specified index.
 743  *
 744  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 745  *
 746  * @remarks You must release @a path using free().
 747  *
 748  * @param[in]  msg   The message handle
 749  * @param[in]  index The zero-based index of the attachment
 750  * @param[out] type  The attachment type
 751  * @param[out] path  The file path to attach
 752  *
 753  * @return @c 0 on success,
 754  *       otherwise a negative error value
 755  *
 756  * @retval #MESSAGES_ERROR_NONE              Successful
 757  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 758  * @retval #MESSAGES_ERROR_OUT_OF_MEMORY     Out of memory
 759  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 760  *
 761  * @pre @a msg is created as a #MESSAGES_TYPE_MMS.
 762  *
 763  * @see messages_mms_add_attachment()
 764  * @see messages_mms_get_attachment_count()
 765  * @see messages_mms_remove_all_attachments()
 766  */
 767 int messages_mms_get_attachment(messages_message_h msg, int index, messages_media_type_e *type, char **path);
 768
 769
 770 /**
 771  * @brief Gets the attachment with the specified index.
 772  *
 773  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 774  *
 775  * @param[in]  msg   The message handle
 776  * @param[out] count The total number of attachments
 777  *
 778  * @return @c 0 on success,
 779  *       otherwise a negative error value
 780  *
 781  * @retval #MESSAGES_ERROR_NONE              Successful
 782  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 783  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 784  *
 785  * @pre @a msg is created as a #MESSAGES_TYPE_MMS.
 786  *
 787  * @see messages_mms_add_attachment()
 788  * @see messages_mms_get_attachment()
 789  * @see messages_mms_remove_all_attachments()
 790  */
 791 int messages_mms_get_attachment_count(messages_message_h msg, int *count);
 792
 793
 794 /**
 795  * @brief Removes all attachments to the MMS message.
 796  *
 797  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 798  *
 799  * @param[in] msg The message handle
 800  *
 801  * @return @c 0 on success,
 802  *       otherwise a negative error value
 803  *
 804  * @retval #MESSAGES_ERROR_NONE              Successful
 805  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 806  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 807  *
 808  * @pre @a msg is created as a #MESSAGES_TYPE_MMS.
 809  *
 810  * @see messages_mms_add_attachment()
 811  * @see messages_mms_get_attachment()
 812  * @see messages_mms_get_attachment_count()
 813  */
 814 int messages_mms_remove_all_attachments(messages_message_h msg);
 815 /**
 816  * @}
 817  */
 818
 819 /**
 820  * @addtogroup CAPI_MESSAGING_MESSAGES_PUSH_MODULE
 821  * @{
 822  */
 823
 824 /**
 825  * @brief Registers a callback to be invoked when an WAP Push message is received.
 826  *
 827  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 828  * @privlevel public
 829  * @privilege %http://tizen.org/privilege/message.read
 830  *
 831  * @param[in] service   The message service handle
 832  * @param[in] app_id    The "X-WAP-Application-ID" to indicate a destination WAP Push application ID
 833  * @param[in] callback  The callback function
 834  * @param[in] user_data The user data to be passed to the callback function
 835  *
 836  * @return @c 0 on success,
 837  *       otherwise a negative error value
 838  *
 839  * @retval #MESSAGES_ERROR_NONE              Successful
 840  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 841  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 842  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 843  */
 844 int messages_push_add_incoming_cb(messages_service_h service, const char *app_id,
 845                                           messages_push_incoming_cb callback, void *user_data);
 846
 847
 848 /**
 849  * @brief Unregisters the WAP push incoming callback function.
 850  *
 851  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 852  *
 853  * @param[in] service The message service handle
 854  * @param[in] app_id  The "X-WAP-Application-ID" to indicate a destination WAP Push application ID
 855  *
 856  * @return @c 0 on success,
 857  *       otherwise a negative error value
 858  *
 859  * @retval #MESSAGES_ERROR_NONE              Successful
 860  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 861  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 862  */
 863 int messages_push_remove_incoming_cb(messages_service_h service, const char *app_id);
 864
 865
 866 /**
 867  * @brief Registers an application to the mapping table of the WAP Push service.
 868  *
 869  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 870  * @privlevel public
 871  * @privilege %http://tizen.org/privilege/message.write
 872  *
 873  * @param[in] service      The message service handle
 874  * @param[in] content_type The MIME content type of the content
 875  * @param[in] app_id       The "X-WAP-Application-ID" to indicate a destination WAP Push application ID
 876  *
 877  * @return @c 0 on success,
 878  *       otherwise a negative error value
 879  *
 880  * @retval #MESSAGES_ERROR_NONE              Successful
 881  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 882  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 883  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 884  */
 885 int messages_push_register(messages_service_h service, const char *content_type, const char *app_id);
 886
 887
 888 /**
 889  * @brief De-registers an application from the mapping table of the WAP Push service.
 890  *
 891  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 892  * @privlevel public
 893  * @privilege %http://tizen.org/privilege/message.write
 894  *
 895  * @param[in] service      The message service handle
 896  * @param[in] content_type The MIME content type of the content
 897  * @param[in] app_id       The "X-WAP-Application-ID" to indicate a destination WAP Push application ID
 898  *
 899  * @return @c 0 on success,
 900  *       otherwise a negative error value
 901  *
 902  * @retval #MESSAGES_ERROR_NONE              Successful
 903  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 904  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 905  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 906  */
 907 int messages_push_deregister(messages_service_h service, const char *content_type, const char *app_id);
 908
 909
 910 /**
 911  * @brief Re-registers an application to the mapping table of the WAP Push service.
 912  *
 913  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 914  * @privlevel public
 915  * @privilege %http://tizen.org/privilege/message.write
 916  *
 917  * @param[in] service          The message service handle
 918  * @param[in] content_type     An element of the composite key for searching registered entry \n
 919  *                             The MIME content type of the content.
 920  * @param[in] app_id           The composite key for searching mapping information \n
 921  *                             The "X-WAP-Application-ID" to indicate a destination WAP Push application ID.
 922  * @param[in] dst_content_type The MIME content type of the content
 923  * @param[in] dst_app_id       The "X-WAP-Application-ID" to indicate a destination WAP Push application ID
 924  *
 925  * @return @c 0 on success,
 926  *       otherwise a negative error value
 927  *
 928  * @retval #MESSAGES_ERROR_NONE              Successful
 929  * @retval #MESSAGES_ERROR_INVALID_PARAMETER Invalid parameter
 930  * @retval #MESSAGES_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 931  * @retval #MESSAGES_ERROR_NOT_SUPPORTED     Not supported
 932  *
 933  */
 934 int messages_push_reregister(messages_service_h service, const char *content_type, const char *app_id,
 935                                                          const char *dst_content_type, const char *dst_app_id);
 936
 937 /**
 938  * @}
 939  */
 940
 941 /**
 942  * @}
 943  */
 944
 945
 946 #ifdef __cplusplus
 947 }
 948 #endif
 949
 950
 951 #endif /* __TIZEN_MESSAGING_H__ */