include/mapi/MapiStorage.h

   1 /*
   2 *
   3 * Copyright (c) 2000-2012 Samsung Electronics Co., Ltd. All Rights Reserved.
   4 *
   5 * This file is part of msg-service.
   6 *
   7 * Contact: Jaeyun Jeong <jyjeong@samsung.com>
   8 *          Sangkoo Kim <sangkoo.kim@samsung.com>
   9 *          Seunghwan Lee <sh.cat.lee@samsung.com>
  10 *          SoonMin Jung <sm0415.jung@samsung.com>
  11 *          Jae-Young Lee <jy4710.lee@samsung.com>
  12 *          KeeBum Kim <keebum.kim@samsung.com>
  13 *
  14 * PROPRIETARY/CONFIDENTIAL
  15 *
  16 * This software is the confidential and proprietary information of
  17 * SAMSUNG ELECTRONICS ("Confidential Information"). You shall not
  18 * disclose such Confidential Information and shall use it only in
  19 * accordance with the terms of the license agreement you entered
  20 * into with SAMSUNG ELECTRONICS.
  21 *
  22 * SAMSUNG make no representations or warranties about the suitability
  23 * of the software, either express or implied, including but not limited
  24 * to the implied warranties of merchantability, fitness for a particular
  25 * purpose, or non-infringement. SAMSUNG shall not be liable for any
  26 * damages suffered by licensee as a result of using, modifying or
  27 * distributing this software or its derivatives.
  28 *
  29 */
  30
  31 /**
  32  *      @file           MapiStorage.h
  33  *      @brief          Defines storage API of messaging framework
  34  *      @version        1.0
  35  */
  36
  37 #ifndef MAPI_STORAGE_H
  38 #define MAPI_STORAGE_H
  39
  40 /**
  41  *      @section                Introduction
  42  *      - Introduction : Overview on Messaging Storage API
  43  *      @section                Program
  44  *      - Program : Messaging Storage API Reference
  45  */
  46
  47 /*==================================================================================================
  48                                          INCLUDE FILES
  49 ==================================================================================================*/
  50
  51 #include "MsgStorageTypes.h"
  52
  53 #ifdef __cplusplus
  54 extern "C"
  55 {
  56 #endif
  57
  58 /**
  59  *      @ingroup                MESSAGING_FRAMEWORK
  60  *      @defgroup       MESSAGING_STORAGE_API   Messaging Storage API
  61  *      @{
  62  */
  63
  64 /*==================================================================================================
  65                                      FUNCTION PROTOTYPES
  66 ==================================================================================================*/
  67
  68 /**
  69
  70  * \par Description:
  71  * Saves a message to the database.
  72  *
  73  * \par Purpose:
  74  * This API is used to save Message object to the database.
  75  *
  76  * \par Typical use case:
  77  * Save Message feature is used when the message is to be stored to persistent memory for later reference.
  78  *
  79  * \par Method of function operation:
  80  * Sets up the database connection and inserts the message to message table.
  81  *
  82  * \par Sync (or) Async:
  83  * This is a Synchronous API.
  84  *
  85  * \par Important notes:
  86  * - Mandatory fields of a message structure MUST be valid, otherwise the function will be failed.
  87  *
  88  * \param input - MSG_HANDLE_T  handle is Message handle.
  89  * \param input - msg_message_t  msg is a pointer to an msg_message_t structure.
  90  * \param input - send_opt is a pointer to an MSG_SENDINGOPT_S structure.
  91  *
  92  * \return Return Type (int(MSG_ERROR_T)) \n
  93  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
  94  * - MSG_ERR_NULL_POINTER       - Input parameter is NULL.
  95  * - MSG_ERR_STORAGE_ERROR - Storage is error.
  96  *
  97  * \par Prospective clients:
  98  * External/Native Apps using Messaging Services.
  99  *
 100  * \par Related functions:
 101  * None
 102  *
 103  * \par Known issues/bugs:
 104  * None
 105  *
 106  * \par Sample code:
 107  * \code
 108  * ...
 109  *
 110  * MSG_HANDLE_T msgHandle = NULL;
 111  * msg_message_t                msg;
 112  * MSG_SENDINGOPT_S sendingOpt = {0};
 113  *
 114  * ...
 115  *
 116  * err = msg_open_msg_handle(&msgHandle);
 117  *
 118  * ...
 119  *
 120  * err = msg_add_message(handle, (msg_message_t) &msg, &sendingOpt);
 121  * if( err != MSG_SUCCESS )
 122  * {
 123  *      printf("err [%d]", err);
 124  *      return err;
 125  * }
 126  *
 127  * ...
 128  * \endcode
 129  */
 130 /*================================================================================================*/
 131 int msg_add_message(MSG_HANDLE_T handle, const msg_message_t msg, const MSG_SENDINGOPT_S *send_opt);
 132
 133
 134 /**
 135
 136  * \par Description:
 137  * Adds a SyncML message to the database.
 138  *
 139  * \par Purpose:
 140  * This API is used to save  a SyncML message to the database.
 141  *
 142  * \par Typical use case:
 143  * Save Message feature is used when the message is to be stored to persistent memory for later reference.
 144  *
 145  * \par Method of function operation:
 146  * Sets up the database connection and inserts the syncml message to message table.
 147  *
 148  * \par Sync (or) Async:
 149  * This is a Synchronous API.
 150  *
 151  * \par Important notes:
 152  * - Mandatory fields of a message structure MUST be valid, otherwise the function will be failed.
 153  *
 154  * \param input - MSG_HANDLE_T  handle is Message handle.
 155  * \param input - MSG_SYNCML_MESSAGE_S  syncml_msg is a pointer to an MSG_SYNCML_MESSAGE_S structure.
 156  *
 157  * \return Return Type (int(MSG_ERROR_T)) \n
 158  * - MSG_SUCCESS        - Success in operation.
 159  * - MSG_ERR_NULL_POINTER - pMsg is NULL.
 160  * - MSG_ERR_INVALID_MSGHANDLE - Message handle is invalid.
 161  * - MSG_ERR_MSGHANDLE_NOT_CONNECTED - Message handle is not connected.
 162  * - MSG_ERR_STORAGE_FULL - Storage is FULL.
 163  * - MSG_ERR_COMMUNICATION_ERROR - Communication between client and server is error.
 164  * - MSG_ERR_MEMORY_ERROR - Memory is error.
 165  * - MSG_ERR_MAX_NUMBER_REACHED - Max number is reached.
 166  * - MSG_ERR_PLUGIN - Generic error code for plugin.
 167  *
 168  * \par Prospective clients:
 169  * External/Native Apps using Messaging Services.
 170  *
 171  * \par Related functions:
 172  * None
 173  *
 174  * \par Known issues/bugs:
 175  * None
 176  *
 177  * \par Sample code:
 178  * \code
 179  * ...
 180  *
 181  * MSG_HANDLE_T msgHandle = NULL;
 182  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 183  *
 184  * ...
 185  *
 186  * err = msg_open_msg_handle(&msgHandle);
 187  *
 188  * ...
 189  *
 190  * int err = msg_add_syncml_message(msgHandle, &syncMLMsg);
 191  * if( err != MSG_SUCCESS )
 192  * {
 193  *      printf("err [%d]", err);
 194  *      return err;
 195  * }
 196  *
 197  * ...
 198  * \endcode
 199  */
 200 /*================================================================================================*/
 201 int msg_add_syncml_message(MSG_HANDLE_T handle, const MSG_SYNCML_MESSAGE_S *syncml_msg);
 202
 203
 204 /**
 205
 206  * \par Description:
 207  * Updates a message in the database.
 208  *
 209  * \par Purpose:
 210  * This API is used to update a message in the database.
 211  *
 212  * \par Typical use case:
 213  * Update message feature is used when a previously saved message is to be updated.
 214  *
 215  * \par Method of function operation:
 216  * Sets up the database connection and set the message's new values to message table.
 217  *
 218  * \par Sync (or) Async:
 219  * This is a Synchronous API.
 220  *
 221  * \par Important notes:
 222  * - The function is to update message data for the message indentified by the given msgId as long as the given values are valid.
 223  * - msg->msgId MUST NOT be updated because msg->msgId is a unique Id on platform.
 224  * - If applications want to move a message between folders, applications SHOULD call msg_move_to_folder.
 225  * - msg->storageId MUST NOT be updated.
 226  * - The function will return MSG_ERR_INVALID_MESSAGE, if inputting a new msg->storageId.
 227  * - If applications want to move the message between storages, applications SHOULD call msg_move_to_storage.
 228  *
 229  * \param input - handle is Message handle.
 230  * \param input - msg is a pointer to an msg_message_t structure.
 231  * \param input - send_opt is a pointer to an MSG_SENDINGOPT_S structure.
 232  *
 233  * \return Return Type (int(MSG_ERROR_T)) \n
 234  * - MSG_SUCCESS        - Success in operation.
 235  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 236  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 237  *
 238  * \par Prospective clients:
 239  * External/Native Apps using Messaging Services.
 240  *
 241  * \par Related functions:
 242  * None
 243  *
 244  * \par Known issues/bugs:
 245  * None
 246  *
 247  * \par Sample code:
 248  * \code
 249  * ...
 250  *
 251  * MSG_HANDLE_T msgHandle = NULL;
 252  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 253  * MSG_SENDINGOPT_S sendingOpt = {0};
 254  *
 255  * ...
 256  *
 257  * err = msg_open_msg_handle(&msgHandle);
 258  *
 259  * ...
 260  *
 261  * err = msg_update_message(hMsgHandle, pMsg, &sendOpt);
 262  * if( err != MSG_SUCCESS )
 263  * {
 264  *      printf("err [%d]", err);
 265  *      return err;
 266  * }
 267  *
 268  * ...
 269  * \endcode
 270  */
 271 /*================================================================================================*/
 272 int msg_update_message(MSG_HANDLE_T handle, const msg_message_t msg, const MSG_SENDINGOPT_S *send_opt);
 273
 274
 275 /**
 276
 277  * \par Description:
 278  * Updates a message's read status in the database.
 279  *
 280  * \par Purpose:
 281  * This API is used to Updates a message's read status in the database.
 282  *
 283  * \par Typical use case:
 284  * Update message's read status for a previously saved message.
 285  *
 286  * \par Method of function operation:
 287  * Sets up the database connection and updates the message's read status to message table.
 288  *
 289  * \par Sync (or) Async:
 290  * This is a Synchronous API.
 291  *
 292  * \par Important notes:
 293  * - None
 294  *
 295  * \param input - handle is Message handle.
 296  * \param input - msg_id is Message ID.
 297  * \parem input - read is boolean for indicating whether a message is read or not.
 298  *
 299  * \return Return Type (int(MSG_ERROR_T)) \n
 300  * - MSG_SUCCESS        - Success in operation.
 301  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 302  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 303  *
 304  * \par Prospective clients:
 305  * External/Native Apps using Messaging Services.
 306  *
 307  * \par Related functions:
 308  * None
 309  *
 310  * \par Known issues/bugs:
 311  * None
 312  *
 313  * \par Sample code:
 314  * \code
 315  * ...
 316  *
 317  * MSG_HANDLE_T msgHandle = NULL;
 318  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 319  * MSG_SENDINGOPT_S sendingOpt = {0};
 320  *
 321  * ...
 322  *
 323  * err = msg_open_msg_handle(&msgHandle);
 324  *
 325  * ...
 326  *
 327  * err = msg_update_message(hMsgHandle, pMsg, &sendOpt);
 328  * if( err != MSG_SUCCESS )
 329  * {
 330  *      printf("err [%d]", err);
 331  *      return err;
 332  * }
 333  *
 334  * ...
 335  * \endcode
 336  */
 337 /*================================================================================================*/
 338 int msg_update_read_status(MSG_HANDLE_T handle, MSG_MESSAGE_ID_T msg_id, bool read);
 339
 340
 341 /**
 342
 343  * \par Description:
 344  * Updates a message's protected status in the database.
 345  *
 346  * \par Purpose:
 347  * This API is used to Updates a message's protected status in the database.
 348  *
 349  * \par Typical use case:
 350  * Update message's protected status for a previously saved message.
 351  *
 352  * \par Method of function operation:
 353  * Sets up the database connection and updates the message's protected status to message table.
 354  *
 355  * \par Sync (or) Async:
 356  * This is a Synchronous API.
 357  *
 358  * \par Important notes:
 359  * - None
 360  *
 361  * \param input - handle is Message handle.
 362  * \param input - msg_id is Message ID.
 363  * \parem input - is_protected is boolean for indicating whether a message is protected or not.
 364  *
 365  * \return Return Type (int(MSG_ERROR_T)) \n
 366  * - MSG_SUCCESS        - Success in operation.
 367  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 368  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 369  *
 370  * \par Prospective clients:
 371  * External/Native Apps using Messaging Services.
 372  *
 373  * \par Related functions:
 374  * None
 375  *
 376  * \par Known issues/bugs:
 377  * None
 378  *
 379  * \par Sample code:
 380  * \code
 381  * ...
 382  *
 383  * MSG_HANDLE_T msgHandle = NULL;
 384  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 385  * MSG_SENDINGOPT_S sendingOpt = {0};
 386  *
 387  * ...
 388  *
 389  * err = msg_open_msg_handle(&msgHandle);
 390  *
 391  * ...
 392  *
 393  * err = msg_update_protected_status(hMsgHandle, 0, true);
 394  * if( err != MSG_SUCCESS )
 395  * {
 396  *      printf("err [%d]", err);
 397  *      return err;
 398  * }
 399  *
 400  * ...
 401  * \endcode
 402  */
 403 /*================================================================================================*/
 404 int msg_update_protected_status(MSG_HANDLE_T handle, MSG_MESSAGE_ID_T msg_id, bool is_protected);
 405
 406
 407 /**
 408
 409  * \par Description:
 410  * Deletes a message by Message ID from the database.
 411  *
 412  * \par Purpose:
 413  * This API is used to delete a message by Message ID from the database.
 414  *
 415  * \par Typical use case:
 416  * Deletes a previously saved message from the database.
 417  *
 418  * \par Method of function operation:
 419  * Sets up the database connection and deletes a message by Message ID from the message table.
 420  *
 421  * \par Sync (or) Async:
 422  * This is a Synchronous API.
 423  *
 424  * \par Important notes:
 425  * - None
 426  *
 427  * \param input - handle is Message handle.
 428  * \param input - msg_id is the ID of the Message to be deleted.
 429  *
 430  * \return Return Type (int(MSG_ERROR_T)) \n
 431  * - MSG_SUCCESS        - Success in operation.
 432  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 433  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 434  *
 435  * \par Prospective clients:
 436  * External/Native Apps using Messaging Services.
 437  *
 438  * \par Related functions:
 439  * None
 440  *
 441  * \par Known issues/bugs:
 442  * None
 443  *
 444  * \par Sample code:
 445  * \code
 446  * ...
 447  *
 448  * MSG_HANDLE_T msgHandle = NULL;
 449  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 450  * MSG_SENDINGOPT_S sendingOpt = {0};
 451  *
 452  * ...
 453  *
 454  * err = msg_open_msg_handle(&msgHandle);
 455  *
 456  * ...
 457  *
 458  * err = msg_delete_message(msgHandle, 0);
 459  * if( err != MSG_SUCCESS )
 460  * {
 461  *      printf("err [%d]", err);
 462  *      return err;
 463  * }
 464  *
 465  * ...
 466  * \endcode
 467  */
 468 /*================================================================================================*/
 469 int msg_delete_message(MSG_HANDLE_T handle, MSG_MESSAGE_ID_T msg_id);
 470
 471
 472 /**
 473
 474  * \par Description:
 475  * Deletes all messages in the specified folder from the database.
 476  *
 477  * \par Purpose:
 478  * This API is used to delete all messages in the specified folder from the database.
 479  *
 480  * \par Typical use case:
 481  * Deletes all messages in the specified folder from the database.
 482  *
 483  * \par Method of function operation:
 484  * Sets up the database connection and Deletes all messages in the specified folder from the message table.
 485  *
 486  * \par Sync (or) Async:
 487  * This is a Synchronous API.
 488  *
 489  * \par Important notes:
 490  * - None
 491  *
 492  * \param input - handle is Message handle.
 493  * \param input - folder_id is the ID of the folder to be deleted.
 494  *
 495  * \return Return Type (int(MSG_ERROR_T)) \n
 496  * - MSG_SUCCESS        - Success in operation.
 497  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 498  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 499  *
 500  * \par Prospective clients:
 501  * External/Native Apps using Messaging Services.
 502  *
 503  * \par Related functions:
 504  * None
 505  *
 506  * \par Known issues/bugs:
 507  * None
 508  *
 509  * \par Sample code:
 510  * \code
 511  * ...
 512  *
 513  * MSG_HANDLE_T msgHandle = NULL;
 514  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 515  * MSG_SENDINGOPT_S sendingOpt = {0};
 516  *
 517  * ...
 518  *
 519  * err = msg_open_msg_handle(&msgHandle);
 520  *
 521  * ...
 522  *
 523  * err = msg_delete_all_msgs_in_folder(msgHandle, MSG_DRAFT_ID);
 524  * if( err != MSG_SUCCESS )
 525  * {
 526  *      printf("err [%d]", err);
 527  *      return err;
 528  * }
 529  *
 530  * ...
 531  * \endcode
 532  */
 533 /*================================================================================================*/
 534 int msg_delete_all_msgs_in_folder(MSG_HANDLE_T handle, MSG_FOLDER_ID_T folder_id, bool bOnlyDB);
 535
 536
 537
 538 /**
 539
 540  * \par Description:
 541  * Moves a message to the specified folder in the database.
 542  *
 543  * \par Purpose:
 544  * This API is used to move a message to the specified folder the database.
 545  *
 546  * \par Typical use case:
 547  * Deletes all messages in the specified folder from the database.
 548  *
 549  * \par Method of function operation:
 550  * Sets up the database connection and Deletes all messages in the specified folder from the message table.
 551  *
 552  * \par Sync (or) Async:
 553  * This is a Synchronous API.
 554  *
 555  * \par Important notes:
 556  * - None
 557  *
 558  * \param input - handle is Message handle.
 559  * \param input - msg_id is the ID of the message to be moved.
 560  * \param input - dest_folder_id is the ID of the destination folder.
 561  *
 562  * \return Return Type (int(MSG_ERROR_T)) \n
 563  * - MSG_SUCCESS        - Success in operation.
 564  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 565  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 566  *
 567  * \par Prospective clients:
 568  * External/Native Apps using Messaging Services.
 569  *
 570  * \par Related functions:
 571  * None
 572  *
 573  * \par Known issues/bugs:
 574  * None
 575  *
 576  * \par Sample code:
 577  * \code
 578  * ...
 579  *
 580  * MSG_HANDLE_T msgHandle = NULL;
 581  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 582  * MSG_SENDINGOPT_S sendingOpt = {0};
 583  *
 584  * ...
 585  *
 586  * err = msg_open_msg_handle(&msgHandle);
 587  *
 588  * ...
 589  *
 590  * err = msg_move_msg_to_folder(hMsgHandle, 0, MSG_OUTBOX_ID);
 591  * if( err != MSG_SUCCESS )
 592  * {
 593  *      printf("err [%d]", err);
 594  *      return err;
 595  * }
 596  *
 597  * ...
 598  * \endcode
 599  */
 600 /*================================================================================================*/
 601 int msg_move_msg_to_folder(MSG_HANDLE_T handle, MSG_MESSAGE_ID_T msg_id, MSG_FOLDER_ID_T dest_folder_id);
 602
 603
 604 /**
 605
 606  * \par Description:
 607  * Moves a message to the other storage.
 608  *
 609  * \par Purpose:
 610  * This API is usd to move a message to the other storage.
 611  *
 612  * \par Typical use case:
 613  * Moves a message to the other storage type.
 614  *
 615  * \par Method of function operation:
 616  * Sets up the database connection and  moves a messages to specified storage type.
 617  *
 618  * \par Sync (or) Async:
 619  * This is a Synchronous API.
 620  *
 621  * \par Important notes:
 622  * - None
 623  *
 624  * \param input - handle is Message handle.
 625  * \param input - msg_id is the ID of the message to be moved.
 626  * \param input - storage_id is the ID of the destination storage.
 627  *
 628  * \return Return Type (int(MSG_ERROR_T)) \n
 629  * - MSG_SUCCESS        - Success in operation.
 630  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 631  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 632  *
 633  * \par Prospective clients:
 634  * External/Native Apps using Messaging Services.
 635  *
 636  * \par Related functions:
 637  * None
 638  *
 639  * \par Known issues/bugs:
 640  * None
 641  *
 642  * \par Sample code:
 643  * \code
 644  * ...
 645  *
 646  * MSG_HANDLE_T msgHandle = NULL;
 647  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 648  * MSG_SENDINGOPT_S sendingOpt = {0};
 649  *
 650  * ...
 651  *
 652  * err = msg_open_msg_handle(&msgHandle);
 653  *
 654  * ...
 655  *
 656  * err = msg_move_msg_to_storage( msgHandle, 0, MSG_STORAGE_PHONE);
 657  * if( err != MSG_SUCCESS )
 658  * {
 659  *      printf("err [%d]", err);
 660  *      return err;
 661  * }
 662  *
 663  * ...
 664  * \endcode
 665  */
 666 /*================================================================================================*/
 667 int msg_move_msg_to_storage(MSG_HANDLE_T handle, MSG_MESSAGE_ID_T msg_id, MSG_STORAGE_ID_T storage_id);
 668
 669
 670 /**
 671
 672  * \par Description:
 673  * Gets the number of messages in the specified folder from the database.
 674  *
 675  * \par Purpose:
 676  * This API is used to get the number of messages in the specified folder from the database.
 677  *
 678  * \par Typical use case:
 679  * Gets the number of messages in the specified folder from the database.
 680  *
 681  * \par Method of function operation:
 682  * Sets up the database connection and Gets the number of messages in the specified folder from the message table.
 683  *
 684  * \par Sync (or) Async:
 685  * This is a Synchronous API.
 686  *
 687  * \par Important notes:
 688  * - None
 689  *
 690  * \param input - handle is Message handle.
 691  * \param input - folder_id is the ID of the folder to be counted.
 692  * \param output - count_info is a pointer to an MSG_COUNT_INFO_S structure.
 693  *
 694  * \return Return Type (int(MSG_ERROR_T)) \n
 695  * - MSG_SUCCESS        - Success in operation.
 696  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 697  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 698  *
 699  * \par Prospective clients:
 700  * External/Native Apps using Messaging Services.
 701  *
 702  * \par Related functions:
 703  * None
 704  *
 705  * \par Known issues/bugs:
 706  * None
 707  *
 708  * \par Sample code:
 709  * \code
 710  * ...
 711  *
 712  * MSG_HANDLE_T msgHandle = NULL;
 713  * MSG_COUNT_INFO_S countInfo;
 714  *
 715  * ...
 716  *
 717  * err = msg_open_msg_handle(&msgHandle);
 718  *
 719  * ...
 720  *
 721  * err = msg_count_message(msgHandle, MSG_OUTBOX_ID, &countInfo)
 722 * if( err != MSG_SUCCESS )
 723  * {
 724  *      printf("err [%d]", err);
 725  *      return err;
 726  * }
 727  *
 728  * ...
 729  * \endcode
 730  */
 731 /*================================================================================================*/
 732 int msg_count_message(MSG_HANDLE_T handle, MSG_FOLDER_ID_T folder_id, MSG_COUNT_INFO_S *count_info);
 733
 734
 735 /**
 736
 737  * \par Description:
 738  * Gets the number of messages of specific message type.
 739  *
 740  * \par Purpose:
 741  * This API is used to get the number of messages of specific type.
 742  *
 743  * \par Typical use case:
 744  * Gets the count of message of specific types such as SMS, MMS.
 745  *
 746  * \par Method of function operation:
 747  * Sets up the database connection and queries the number of messages in the specified folder from the message table based on required message type.
 748  *
 749  * \par Sync (or) Async:
 750  * This is a Synchronous API.
 751  *
 752  * \par Important notes:
 753  * - None
 754  *
 755  * \param input - handle is Message handle.
 756  * \param input - msg_type is the message type to be counted.
 757  * \param output - msg_count is a pointer to the number of message.
 758  *
 759  * \return Return Type (int(MSG_ERROR_T)) \n
 760  * - MSG_SUCCESS        - Success in operation.
 761  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 762  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 763  *
 764  * \par Prospective clients:
 765  * External/Native Apps using Messaging Services.
 766  *
 767  * \par Related functions:
 768  * None
 769  *
 770  * \par Known issues/bugs:
 771  * None
 772  *
 773  * \par Sample code:
 774  * \code
 775  * ...
 776  *
 777  * MSG_HANDLE_T msgHandle = NULL;
 778  * MSG_COUNT_INFO_S countInfo;
 779  *
 780  * ...
 781  *
 782  * err = msg_open_msg_handle(&msgHandle);
 783  *
 784  * ...
 785  *
 786  * err = msg_count_msg_by_type(msgHandle, MSG_TYPE_SMS, &countInfo);
 787  * if( err != MSG_SUCCESS )
 788  * {
 789  *      printf("err [%d]", err);
 790  *      return err;
 791  * }
 792  *
 793  * ...
 794  * \endcode
 795  */
 796 /*================================================================================================*/
 797 int msg_count_msg_by_type(MSG_HANDLE_T handle, MSG_MESSAGE_TYPE_T msg_type, int *msg_count);
 798
 799
 800 /**
 801
 802  * \par Description:
 803  * Gets the number of messages of specific address.
 804  *
 805  * \par Purpose:
 806  * This API is used to get the number of messages from a specific address.
 807  *
 808  * \par Typical use case:
 809  * Get the count of messages from the specified address
 810  *
 811  * \par Method of function operation:
 812  * Sets up the database connection and queries the number of messages based on address from the message table.
 813  *
 814  * \par Sync (or) Async:
 815  * This is a Synchronous API.
 816  *
 817  * \par Important notes:
 818  * - If addr_info is NULL, nothing happens.
 819  *
 820  * \param input - handle is Message handle.
 821  * \param input - addr_info is a pointer to an MSG_ADDRESS_INFO_LIST_S structure.
 822  * \param input - msg_thread_count_list is a pointer to an MSG_THREAD_COUNT_INFO_S structure.
 823  *
 824  * \return Return Type (int(MSG_ERROR_T)) \n
 825  * - MSG_SUCCESS        - Success in operation.
 826  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 827  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 828  *
 829  * \par Prospective clients:
 830  * External/Native Apps using Messaging Services.
 831  *
 832  * \par Related functions:
 833  * None
 834  *
 835  * \par Known issues/bugs:
 836  * None
 837  *
 838  * \par Sample code:
 839  * \code
 840  * ...
 841  *
 842  * MSG_HANDLE_T msgHandle = NULL;
 843  * MSG_COUNT_INFO_S countInfo;
 844  *
 845  * ...
 846  *
 847  * err = msg_open_msg_handle(&msgHandle);
 848  *
 849  * ...
 850  *
 851  * err = msg_count_msg_by_type(msgHandle, MSG_TYPE_SMS, &countInfo);
 852  * if( err != MSG_SUCCESS )
 853  * {
 854  *      printf("err [%d]", err);
 855  *      return err;
 856  * }
 857  *
 858  * ...
 859  * \endcode
 860  */
 861 /*================================================================================================*/
 862 int msg_count_msg_by_contact(MSG_HANDLE_T handle, const MSG_THREAD_LIST_INDEX_S *addr_info, MSG_THREAD_COUNT_INFO_S *msg_thread_count_list);
 863
 864
 865 /**
 866
 867  * \par Description:
 868  * Gets the detail information of a message from the database.
 869  *
 870  * \par Purpose:
 871  * This API is used to get the number of messages from a specific address.
 872  *
 873  * \par Typical use case:
 874  * Get the count of messages from the specified address
 875  *
 876  * \par Method of function operation:
 877  * Sets up the database connection and queries the number of messages based on address from the message table.
 878  *
 879  * \par Sync (or) Async:
 880  * This is a Synchronous API.
 881  *
 882  * \par Important notes:
 883  * - If addr_info is NULL, nothing happens.
 884  * - Applications need to call msg_release_message to free the memory.
 885  * - However, if this function is failed, the memory for the message is NOT allocated in this function.
 886  *
 887 handle is Message handle.
 888  * \param input - handle is Message handle.
 889  * \param input - msg_id is the ID of the Message to be returned.
 890  * \param output - msg is a pointer to an msg_message_t structure.
 891  * \param input - send_opt is a pointer to an MSG_SENDINGOPT_S structure.
 892  *
 893  * \return Return Type (int(MSG_ERROR_T)) \n
 894  * - MSG_SUCCESS        - Success in operation.
 895  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 896  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 897  *
 898  * \par Prospective clients:
 899  * External/Native Apps using Messaging Services.
 900  *
 901  * \par Related functions:
 902  * - None
 903  *
 904  * \par Known issues/bugs:
 905  * None
 906  *
 907  * \par Sample code:
 908  * \code
 909  * ...
 910  *
 911  * MSG_HANDLE_T msgHandle = NULL;
 912  *
 913  * ...
 914  * msg_message_t msg = msg_new_message();
 915  * MSG_SENDINGOPT_S sendOpt = {0, };
 916  * ...
 917  * err = msg_get_message(msgHandle, 0, msg, &sendOpt);
 918  * if( err != MSG_SUCCESS )
 919  * {
 920  *      printf("err [%d]", err);
 921  *      return err;
 922  * }
 923  *
 924  * ...
 925  * \endcode
 926  */
 927 /*================================================================================================*/
 928 int msg_get_message(MSG_HANDLE_T handle, MSG_MESSAGE_ID_T msg_id, msg_message_t msg, MSG_SENDINGOPT_S *send_opt);
 929
 930
 931 /**
 932
 933  * \par Description:
 934  * Returns the common information list of messages with selected folder id.
 935  *
 936  * \par Purpose:
 937  * This API is used to get the common information list of messages with selected folder id from database.
 938  *
 939  * \par Typical use case:
 940  * Get the common information from the specified folder from database.
 941  *
 942  * \par Method of function operation:
 943  * Sets up the database connection and queries the common information based on selected folder id from the message and folder tables.
 944  *
 945  * \par Sync (or) Async:
 946  * This is a Synchronous API.
 947  *
 948  * \par Important notes:
 949  * - The memory for a message will be allocated in this function.
 950  * - Applications need to call msg_release_folder_view_list to free the memory.
 951  * - However, if this function is failed, the memory for the message is NOT allocated in this function.
 952  *
 953  * \param input - handle is Message handle.
 954  * \param input - folder_id is the ID of the folder to be returned.
 955  * \param input - sort_rule indicates a sort type and sort order for querying messages.
 956  * \param output - msg_folder_view_list is a pointer to an MSG_FOLDER_VIEW_LIST_S structure.
 957  *
 958  * \return Return Type (int(MSG_ERROR_T)) \n
 959  * - MSG_SUCCESS        - Success in operation.
 960  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 961  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 962  *
 963  * \par Prospective clients:
 964  * External/Native Apps using Messaging Services.
 965  *
 966  * \par Related functions:
 967  * - None
 968  *
 969  * \par Known issues/bugs:
 970  * None
 971  *
 972  * \par Sample code:
 973  * \code
 974  * ...
 975  *
 976  * MSG_HANDLE_T msgHandle = NULL;
 977  *
 978  * ...
 979  * MSG_FOLDER_VIEW_LIST_S folderViewList;
 980  * ...
 981  * err = msg_get_folder_view_list(hMsgHandle, 0, NULL, &folderViewList);
 982  * if( err != MSG_SUCCESS )
 983  * {
 984  *      printf("err [%d]", err);
 985  *      return err;
 986  * }
 987  *
 988  * ...
 989  * \endcode
 990  */
 991 /*================================================================================================*/
 992 int msg_get_folder_view_list(MSG_HANDLE_T handle, MSG_FOLDER_ID_T folder_id, const MSG_SORT_RULE_S *sort_rule, MSG_LIST_S *msg_folder_view_list);
 993
 994
 995 /**
 996
 997  * \par Description:
 998  * Returns the information of all peers to whom messages have been sent or recieved.
 999  *
1000  * \par Purpose:
1001  * This API is used to get the information of all peers to whom messages have been sent or recieved.
1002  *
1003  * \par Typical use case:
1004  * Get the common information from the specified folder from database.
1005  *
1006  * \par Method of function operation:
1007  * Frees the memory occupied by MSG_FOLDER_VIEW_LIST_S object and its members.
1008  *
1009  * \par Sync (or) Async:
1010  * This is a Synchronous API.
1011  *
1012  * \par Important notes:
1013  * - The memory for a list will be allocated in this function.
1014  * - Applications need to call msg_release_thread_view_list to free the memory.
1015  * - However, if this function is failed, the memory for a list is NOT allocated in this function.
1016  *
1017  * \param input - handle is Message handle.
1018  * \param input - sort_rule indicates a sort type and sort order for querying messages.
1019  * \param output - msg_thread_view_list is a pointer to an MSG_THREAD_VIEW_LIST_S structure.
1020  *
1021  * \return Return Type (int(MSG_ERROR_T)) \n
1022  * - MSG_SUCCESS        - Success in operation.
1023  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1024  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1025  *
1026  * \par Prospective clients:
1027  * External/Native Apps using Messaging Services.
1028  *
1029  * \par Related functions:
1030  * None
1031  *
1032  * \par Known issues/bugs:
1033  * None
1034  *
1035  * \par Sample code:
1036  * \code
1037  * ...
1038  *
1039  * MSG_HANDLE_T msgHandle = NULL;
1040  *
1041  * ...
1042  * MSG_THREAD_VIEW_LIST_S threadViewList;
1043  * ...
1044  * err = msg_get_thread_view_list(hMsgHandle, NULL, &threadViewList);
1045  * ...
1046  * msg_release_thread_view_list(&threadViewList);
1047  * if( err != MSG_SUCCESS )
1048  * {
1049  *      printf("err [%d]", err);
1050  *      return err;
1051  * }
1052  * \endcode
1053  */
1054 /*================================================================================================*/
1055 int msg_get_thread_view_list(MSG_HANDLE_T handle, const MSG_SORT_RULE_S *sort_rule, MSG_THREAD_VIEW_LIST_S *msg_thread_view_list);
1056
1057
1058 /**
1059
1060  * \par Description:
1061  * Frees the memory of MSG_PEER_INFO_LIST_S allocated in msg_get_thread_view_list.
1062  *
1063  * \par Purpose:
1064  * This API is used to get the information of all peers to whom messages have been sent or recieved.
1065  *
1066  * \par Typical use case:
1067  * Get the common information from the specified folder from database.
1068  *
1069  * \par Method of function operation:
1070  * Frees the memory occupied by MSG_FOLDER_VIEW_LIST_S object and its members.
1071  *
1072  * \par Sync (or) Async:
1073  * This is a Synchronous API.
1074  *
1075  * \par Important notes:
1076  * - The memory for a list will be allocated in this function.
1077  * - Applications need to call msg_release_thread_view_list to free the memory.
1078  * - However, if this function is failed, the memory for a list is NOT allocated in this function.
1079  *
1080  * \param input - msg_thread_view_list is a pointer to an MSG_THREAD_VIEW_LIST_S structure.
1081  *
1082  * \return Return Type (int(MSG_ERROR_T)) \n
1083  * - MSG_SUCCESS        - Success in operation.
1084  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1085  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1086  *
1087  * \par Prospective clients:
1088  * External/Native Apps using Messaging Services.
1089  *
1090  * \par Related functions:
1091  * None
1092  *
1093  * \par Known issues/bugs:
1094  * None
1095  *
1096  * \par Sample code:
1097  * \code
1098  * ...
1099  *
1100  * MSG_HANDLE_T msgHandle = NULL;
1101  *
1102  * ...
1103  * MSG_THREAD_VIEW_LIST_S threadViewList;
1104  * ...
1105  * err = msg_get_thread_view_list(hMsgHandle, NULL, &threadViewList);
1106  * ...
1107  * msg_release_thread_view_list(&threadViewList);
1108  * ...
1109  * \endcode
1110  */
1111 /*================================================================================================*/
1112 void msg_release_thread_view_list(MSG_THREAD_VIEW_LIST_S *msg_thread_view_list);
1113
1114
1115 /**
1116
1117  * \par Description:
1118  * Returns the common information list of messages with selected thread_id.
1119  *
1120  * \par Purpose:
1121  * This API is used to get the common information list of messages with selected thread_id.
1122  *
1123  * \par Typical use case:
1124  * Gets the common information list of messages with the selected thread id from the database.
1125  *
1126  * \par Method of function operation:
1127  * Connects to the database and queries the common infomation of  list messages with the provided thread id.
1128  *
1129  * \par Sync (or) Async:
1130  * This is a Synchronous API.
1131  *
1132  * \par Important notes:
1133  * - The memory for a list will be allocated in this function.
1134  * - Applications need to call msg_release_conversation_view_list to free the memory.
1135  * - However, if this function is failed, the memory for a list is NOT allocated in this function.
1136  *
1137  * \param input - hMsgHandle is Message handle.
1138  * \param input - thread_id is the ID of the thread to be returned.
1139  * \param output - msg_conv_view_list is a pointer to an MSG_CONV_VIEW_LIST_S structure.
1140  *
1141  * \return Return Type (int(MSG_ERROR_T)) \n
1142  * - MSG_SUCCESS        - Success in operation.
1143  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1144  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1145  *
1146  * \par Prospective clients:
1147  * External/Native Apps using Messaging Services.
1148  *
1149  * \par Related functions:
1150  * - None
1151  *
1152  * \par Known issues/bugs:
1153  * None
1154  *
1155  * \par Sample code:
1156  * \code
1157  * ...
1158  *
1159  * MSG_HANDLE_T msgHandle = NULL;
1160  * MSG_ERROR_T err = MSG_SUCCESS;
1161  * ...
1162  * MSG_CONV_VIEW_LIST_S convViewList;
1163  * ...
1164  * err = msg_get_conversation_view_list(hMsgHandle, ThreadId, &convViewList);
1165  * if( err != MSG_SUCCESS )
1166  * {
1167  *      printf("err [%d]", err);
1168  *      return err;
1169  * }
1170  * msg_release_conversation_view_list(&convViewList);
1171  * ...
1172  * \endcode
1173  */
1174 /*================================================================================================*/
1175 int msg_get_conversation_view_list(MSG_HANDLE_T handle, MSG_THREAD_ID_T thread_id, MSG_LIST_S *msg_conv_view_list);
1176
1177
1178 /**
1179
1180  * \par Description:
1181  * Deletes all the Messages Sent/Received from the selected list.
1182  *
1183  * \par Purpose:
1184  * This API is used to delete all the Messages Sent/Received from the selected list.
1185  *
1186  * \par Typical use case:
1187  * Deletes all messages sent/received from the selected list.
1188  *
1189  * \par Method of function operation:
1190  * Sets up the database connection and deletes all messages sent/received from a selected list.
1191  *
1192  * \par Sync (or) Async:
1193  * This is a Synchronous API.
1194  *
1195  * \par Important notes:
1196  * - If addr_info is NULL, nothing happens.
1197  *
1198  * \param input - handle is Message handle.
1199  * \param input - thread_id is the ID of the thread to be deleted.
1200  *
1201  * \return Return Type (int(MSG_ERROR_T)) \n
1202  * - MSG_SUCCESS        - Success in operation.
1203  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1204  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1205  *
1206  * \par Prospective clients:
1207  * External/Native Apps using Messaging Services.
1208  *
1209  * \par Related functions:
1210  * None
1211  *
1212  * \par Known issues/bugs:
1213  * None
1214  *
1215  * \par Sample code:
1216  * \code
1217  * ...
1218  *
1219  * MSG_HANDLE_T msgHandle = NULL;
1220  * MSG_SYNCML_MESSAGE_S syncMLMsg;
1221  * MSG_SENDINGOPT_S sendingOpt = {0};
1222  *
1223  * ...
1224  *
1225  * err = msg_open_msg_handle(&msgHandle);
1226  *
1227  * ...
1228  *
1229  * err = msg_delete_thread_message_list(hMsgHandle, 0);
1230  * if( err != MSG_SUCCESS )
1231  * {
1232  *      printf("err [%d]", err);
1233  *      return err;
1234  * }
1235  * ...
1236  * \endcode
1237  */
1238 /*================================================================================================*/
1239 int msg_delete_thread_message_list(MSG_HANDLE_T handle, MSG_THREAD_ID_T thread_id);
1240
1241
1242 /**
1243
1244  * \par Description:
1245  * Adds a new folder.
1246  *
1247  * \par Purpose:
1248  * This API is used to add a new folder.
1249  *
1250  * \par Typical use case:
1251  * Adds a new folder with the specified folder info
1252  *
1253  * \par Method of function operation:
1254  * Sets up the database connection and add a new folder to the folder table.
1255  *
1256  * \par Sync (or) Async:
1257  * This is a Synchronous API.
1258  *
1259  * \par Important notes:
1260  * - None.
1261  *
1262  * \param - handle is Message handle.
1263  * \param - folder_info is a pointer to an MSG_FOLDER_INFO_S structure.
1264  *
1265  * \return Return Type (int(MSG_ERROR_T)) \n
1266  * - MSG_SUCCESS        - Success in operation.
1267  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1268  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1269  *
1270  * \par Prospective clients:
1271  * External/Native Apps using Messaging Services.
1272  *
1273  * \par Related functions:
1274  * None
1275  *
1276  * \par Known issues/bugs:
1277  * None
1278  *
1279  * \par Sample code:
1280  * \code
1281  * ...
1282  *
1283  * MSG_HANDLE_T msgHandle = NULL;
1284  *  Make Folder
1285  * MSG_FOLDER_INFO_S folderInfo;
1286  * ...
1287  * err = msg_open_msg_handle(&msgHandle);
1288  *
1289  * folderInfo.folderId = 1;
1290  * folderInfo.folderType = MSG_FOLDER_TYPE_USER_DEF;
1291  * ...
1292  *
1293  * err = msg_add_folder(hMsgHandle, &folderInfo);
1294  * if( err != MSG_SUCCESS )
1295  * {
1296  *      printf("err [%d]", err);
1297  *      return err;
1298  * }
1299  * ...
1300  * \endcode
1301  */
1302 /*================================================================================================*/
1303 int msg_add_folder(MSG_HANDLE_T handle, const MSG_FOLDER_INFO_S *folder_info);
1304
1305
1306 /**
1307
1308  * \par Description:
1309  * Updates the folder info.
1310  *
1311  * \par Purpose:
1312  * This API is used to add a new folder.
1313  *
1314  * \par Typical use case:
1315  * Adds a new folder with the specified folder info
1316  *
1317  * \par Method of function operation:
1318  * Sets up the database connection and add a new folder to the folder table.
1319  *
1320  * \par Sync (or) Async:
1321  * This is a Synchronous API.
1322  *
1323  * \par Important notes:
1324  * - None.
1325  *
1326  * \param - handle is Message handle.
1327  * \param - folder_info is a pointer to an MSG_FOLDER_INFO_S structure.
1328  *
1329  * \return Return Type (int(MSG_ERROR_T)) \n
1330  * - MSG_SUCCESS        - Success in operation.
1331  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1332  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1333  *
1334  * \par Prospective clients:
1335  * External/Native Apps using Messaging Services.
1336  *
1337  * \par Related functions:
1338  * None
1339  *
1340  * \par Known issues/bugs:
1341  * None
1342  *
1343  * \par Sample code:
1344  * \code
1345  * ...
1346  *
1347  * MSG_HANDLE_T msgHandle = NULL;
1348  *  Make Folder
1349  * MSG_FOLDER_INFO_S folderInfo;
1350  * ...
1351  * err = msg_open_msg_handle(&msgHandle);
1352  *
1353  * folderInfo.folderId = 2;
1354  * folderInfo.folderType = MSG_FOLDER_TYPE_USER_DEF;
1355  * ...
1356  * err = msg_update_folder(msgHandle, &folderInfo);
1357  * if( err != MSG_SUCCESS )
1358  * {
1359  *      printf("err [%d]", err);
1360  *      return err;
1361  * }
1362  * ...
1363  * \endcode
1364  */
1365 /*================================================================================================*/
1366 int msg_update_folder(MSG_HANDLE_T handle, const MSG_FOLDER_INFO_S *folder_info);
1367
1368
1369 /**
1370
1371  * \par Description:
1372  * Deletes an exisiting folder.
1373  *
1374  * \par Purpose:
1375  * This API is used to delete an existing folder.
1376  *
1377  * \par Typical use case:
1378  * Deletes an existing folder.
1379  *
1380  * \par Method of function operation:
1381  * Sets up the database connection and deletes an existing folder to the folder table.
1382  *
1383  * \par Sync (or) Async:
1384  * This is a Synchronous API.
1385  *
1386  * \par Important notes:
1387  * - None.
1388  *
1389  * \param input - handle is Message handle.
1390  * \param input - folder_id is the ID of the folder to be deleted.
1391  *
1392  * \return Return Type (int(MSG_ERROR_T)) \n
1393  * - MSG_SUCCESS        - Success in operation.
1394  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1395  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1396  *
1397  * \par Prospective clients:
1398  * External/Native Apps using Messaging Services.
1399  *
1400  * \par Related functions:
1401  * None
1402  *
1403  * \par Known issues/bugs:
1404  * None
1405  *
1406  * \par Sample code:
1407  * \code
1408  * ...
1409  *
1410  * MSG_HANDLE_T msgHandle = NULL;
1411  * err = msg_open_msg_handle(&msgHandle);
1412  *
1413  * ...
1414  * err = msg_delete_folder(hMsgHandle, MSG_INBOX_ID);
1415  * if( err != MSG_SUCCESS )
1416  * {
1417  *      printf("err [%d]", err);
1418  *      return err;
1419  * }
1420  * ...
1421  * \endcode
1422  */
1423 /*================================================================================================*/
1424 int msg_delete_folder(MSG_HANDLE_T handle, MSG_FOLDER_ID_T folder_id);
1425
1426
1427 /**
1428
1429  * \par Description:
1430  * Returns the information list of folders.
1431  *
1432  * \par Purpose:
1433  * This API is used to get the information list of folders.
1434  *
1435  * \par Typical use case:
1436  * Gets the folder list information.
1437  *
1438  * \par Method of function operation:
1439  * Sets up the database connection and queries for the folder list information.
1440  *
1441  * \par Sync (or) Async:
1442  * This is a Synchronous API.
1443  *
1444  * \par Important notes:
1445  * - None.
1446  *
1447  * \param input - handle is Message handle.
1448  * \param output - folder_list is a pointer to an MSG_FOLDER_LIST_S structure.
1449  *
1450  * \return Return Type (int(MSG_ERROR_T)) \n
1451  * - MSG_SUCCESS        - Success in operation.
1452  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1453  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1454  *
1455  * \par Prospective clients:
1456  * External/Native Apps using Messaging Services.
1457  *
1458  * \par Related functions:
1459  * None
1460  *
1461  * \par Known issues/bugs:
1462  * None
1463  *
1464  * \par Sample code:
1465  * \code
1466  * ...
1467  *
1468  * MSG_HANDLE_T msgHandle = NULL;
1469  *  MSG_FOLDER_LIST_S folderList;
1470
1471  * err = msg_open_msg_handle(&msgHandle);
1472  *
1473  * ...
1474  * err = msg_get_folder_list(msgHandle, &folderList);
1475  * if( err != MSG_SUCCESS )
1476  * {
1477  *      printf("err [%d]", err);
1478  *      return err;
1479  * }
1480  * ...
1481  * msg_release_folder_list(&folderList);
1482  * \endcode
1483  */
1484 /*================================================================================================*/
1485 int msg_get_folder_list(MSG_HANDLE_T handle, MSG_FOLDER_LIST_S *folder_list);
1486
1487
1488
1489 /**
1490
1491  * \par Description:
1492  * Releases the memory of a folder list.
1493  *
1494  * \par Purpose:
1495  * This API is used to get the information list of folders.
1496  *
1497  * \par Typical use case:
1498  * Gets the folder list information.
1499  *
1500  * \par Method of function operation:
1501  * Sets up the database connection and queries for the folder list information.
1502  *
1503  * \par Sync (or) Async:
1504  * This is a Synchronous API.
1505  *
1506  * \par Important notes:
1507  * - If folder_list is NULL, nothing happens.
1508  * - If folder_list is invalid, undefined behavior happens.
1509  *
1510  * \param input - folder_list is a pointer to an MSG_FOLDER_LIST_S structure.
1511  *
1512  * \return Return Type (int(MSG_ERROR_T)) \n
1513  * - MSG_SUCCESS        - Success in operation.
1514  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1515  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1516  *
1517  * \par Prospective clients:
1518  * External/Native Apps using Messaging Services.
1519  *
1520  * \par Related functions:
1521  * None
1522  *
1523  * \par Known issues/bugs:
1524  * None
1525  *
1526  * \par Sample code:
1527  * \code
1528  * ...
1529  *
1530  * MSG_HANDLE_T msgHandle = NULL;
1531  *  MSG_FOLDER_LIST_S folderList;
1532
1533  * err = msg_open_msg_handle(&msgHandle);
1534  *
1535  * ...
1536  * err = msg_get_folder_list(msgHandle, &folderList);
1537  * if( err != MSG_SUCCESS )
1538  * {
1539  *      printf("err [%d]", err);
1540  *      return err;
1541  * }
1542  * ...
1543  * msg_release_folder_list(&folderList);
1544  * \endcode
1545  */
1546 /*================================================================================================*/
1547 void msg_release_folder_list(MSG_FOLDER_LIST_S *folder_list);
1548
1549
1550 /**
1551
1552  * \par Description:
1553  * Creates the specified number of messages in database.
1554  *
1555  * \par Purpose:
1556  * This API is used to generate specified number of messages in the database
1557  *
1558  * \par Typical use case:
1559  * Generate large number of messages in the database.
1560  *
1561  * \par Method of function operation:
1562  * Creates the specified number of messages in database for specified message type in the specified folder
1563  *
1564  * \par Sync (or) Async:
1565  * This is a Synchronous API.
1566  *
1567  * \par Important notes:
1568  * - None
1569  *
1570  * \param input - handle is Message handle.
1571  * \param input - msg_type is one of enum _MSG_MESSAGE_TYPE_E.
1572  * \param input - folder_id is the folder for the test messages.
1573  * \param input - num_msg is the number of messages.
1574  *
1575  * \return Return Type (int(MSG_ERROR_T)) \n
1576  * - MSG_SUCCESS                                        Success in operation.
1577  * - MSG_ERR_INVALID_MSGHANDLE  Parameter is invalid.
1578  * - MSG_ERR_INVALID_FOLDER_ID  Storage is error.
1579  *
1580  * \par Prospective clients:
1581  * External/Native Apps using Messaging Services.
1582  *
1583  * \par Related functions:
1584  * None
1585  *
1586  * \par Known issues/bugs:
1587  * None
1588  *
1589  * \par Sample code:
1590  * \code
1591  * ...
1592  *
1593  * MSG_HANDLE_T msgHandle = NULL;
1594  *  MSG_FOLDER_LIST_S folderList;
1595
1596  * err = msg_open_msg_handle(&msgHandle);
1597  *
1598  * ...
1599  * err = msg_generate_message(msgHandle, MSG_TYPE_SMS, MSG_INBOX_ID, 100);
1600  * if( err != MSG_SUCCESS )
1601  * {
1602  *      printf("err [%d]", err);
1603  *      return err;
1604  * }
1605  * ...
1606  * \endcode
1607  */
1608 /*================================================================================================*/
1609 int msg_generate_message(MSG_HANDLE_T handle, MSG_MESSAGE_TYPE_T msg_type, MSG_FOLDER_ID_T folder_id, unsigned int num_msg);
1610 int msg_generate_sms(MSG_HANDLE_T handle, MSG_FOLDER_ID_T folder_id, unsigned int num_msg) DEPRECATED;
1611
1612
1613 /**
1614
1615  * \par Description:
1616  * Returns the Message Data to be used by the Quick Panel.
1617  *
1618  * \par Purpose:
1619  * This API is used to get the Message Datato be used by the Quick Panel.
1620  *
1621  * \par Typical use case:
1622  * Quick panel needs the message information to show new message notification.
1623  *
1624  * \par Method of function operation:
1625  * Connects to database and queries for information needed by the quick panel.
1626  *
1627  * \par Sync (or) Async:
1628  * This is a Synchronous API.
1629  *
1630  * \par Important notes:
1631  * - None
1632  *
1633  * \param input - handle is Message handle.
1634  * \param input - type is the type of message that Quick Panel need.
1635  * \param output - msg is a pointer to an msg_message_t structure.
1636  *
1637  * \return Return Type (int(MSG_ERROR_T)) \n
1638  * - MSG_SUCCESS                                        Success in operation.
1639  * - MSG_ERR_INVALID_MSGHANDLE  Parameter is invalid.
1640  * - MSG_ERR_INVALID_FOLDER_ID  Storage is error.
1641  *
1642  * \par Prospective clients:
1643  * External/Native Apps using Messaging Services.
1644  *
1645  * \par Related functions:
1646  * None
1647  *
1648  * \par Known issues/bugs:
1649  * None
1650  *
1651  * \par Sample code:
1652  * \code
1653  * ...
1654  *
1655  * MSG_HANDLE_T msgHandle = NULL;
1656  * msg_message_t msgInfo;
1657
1658  * err = msg_open_msg_handle(&msgHandle);
1659  *
1660  * ...
1661  * err = msg_get_quick_panel_data(msgHandle, MSG_QUICKPANEL_SMS, msgInfo);
1662  * if( err != MSG_SUCCESS )
1663  * {
1664  *      printf("err [%d]", err);
1665  *      return err;
1666  * }
1667  * ...
1668  * \endcode
1669  */
1670 /*================================================================================================*/
1671 int msg_get_quick_panel_data(MSG_HANDLE_T handle, MSG_QUICKPANEL_TYPE_T type, msg_message_t msg);
1672
1673
1674 /**
1675
1676  * \par Description:
1677  * Resets the Messaging database.
1678  *
1679  * \par Purpose:
1680  * This API is used to reset the messaging database.
1681  *
1682  * \par Typical use case:
1683  * Completely delete the messaging database.
1684  *
1685  * \par Method of function operation:
1686  * Connects to database and deletes all the messaging tables.
1687  *
1688  * \par Sync (or) Async:
1689  * This is a Synchronous API.
1690  *
1691  * \par Important notes:
1692  * - None
1693  *
1694  * \param input - handle is Message handle.
1695  *
1696  * \return Return Type (int(MSG_ERROR_T)) \n
1697  * - MSG_SUCCESS                                        Success in operation.
1698  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1699  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1700  *
1701  * \par Prospective clients:
1702  * External/Native Apps using Messaging Services.
1703  *
1704  * \par Related functions:
1705  * None
1706  *
1707  * \par Known issues/bugs:
1708  * None
1709  *
1710  * \par Sample code:
1711  * \code
1712  * ...
1713  *
1714  * MSG_HANDLE_T msgHandle = NULL;
1715  * MSG_ERROR_T err = MSG_SUCCESS;
1716  * err = msg_open_msg_handle(&msgHandle);
1717  *
1718  * ...
1719  * err = msg_reset_database(msgHandle);
1720  * if (err != MSG_SUCCESS)
1721  *{
1722  *      printf("err [%d]", err);
1723  *      return err;
1724  * }
1725  * ...
1726  * \endcode
1727  */
1728 /*================================================================================================*/
1729 int msg_reset_database(MSG_HANDLE_T handle);
1730
1731
1732 /**
1733
1734  * \par Description:
1735  * Returns the total size used for message contents.
1736  *
1737  * \par Purpose:
1738  * This API is used to get the total size used for message contents.
1739  *
1740  * \par Typical use case:
1741  * To get the total space used by message contents.
1742  *
1743  * \par Method of function operation:
1744  * Uses linux system calls to query the space used by message contents.
1745  *
1746  * \par Sync (or) Async:
1747  * This is a Synchronous API.
1748  *
1749  * \par Important notes:
1750  * - None
1751  *
1752  * \param input - handle is Message handle.
1753  * \param output -      memsize is a pointer to the size.
1754  *
1755  * \return Return Type (int(MSG_ERROR_T)) \n
1756  * - MSG_SUCCESS                                        Success in operation.
1757  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1758  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1759  *
1760  * \par Prospective clients:
1761  * External/Native Apps using Messaging Services.
1762  *
1763  * \par Related functions:
1764  * None
1765  *
1766  * \par Known issues/bugs:
1767  * None
1768  *
1769  * \par Sample code:
1770  * \code
1771  * ...
1772  *
1773  * MSG_HANDLE_T msgHandle = NULL;
1774  * int memsize = 0;
1775  * err = msg_open_msg_handle(&msgHandle);
1776  *
1777  * ...
1778  * err = msg_get_mem_size(msgHandle, &memsize);
1779  * if( err != MSG_SUCCESS )
1780  * {
1781  *      printf("err [%d]", err);
1782  *      return err;
1783  * }
1784  * ...
1785  * \endcode
1786  */
1787 /*================================================================================================*/
1788 int msg_get_mem_size(MSG_HANDLE_T handle, unsigned int* memsize);
1789
1790
1791 /**
1792
1793  * \par Description:
1794  * Return thread id in thread view object.
1795  *
1796  * \par Purpose:
1797  * This API is used to get the thread id field in folder view object.
1798  *
1799  * \par Typical use case:
1800  * Returns thread id value in thread view object.
1801  *
1802  * \par Method of function operation:
1803  * Returns the threadId member of thread view object msg.
1804  *
1805  * \par Sync (or) Async:
1806  * This is a Synchronous API.
1807  *
1808  * \par Important notes:
1809  * - If msg_thread is NULL, nothing happens.
1810  * - If msg_thread is invalid, undefined behavior happens.
1811  *
1812  * \param msg_thread_view_t input - msg_thread is a thread view object.
1813  *
1814  * \return Return Type int (MSG_ERROR_T when negative, msg_id when positive) \n
1815  * - positive int                                               thread id.
1816  * - MSG_ERR_NULL_POINTER                               msg_thread is NULL.
1817  *
1818  * \par Prospective clients:
1819  * External/Native Apps using Messaging Services.
1820  *
1821  * \par Related functions:
1822  * None
1823  *
1824  * \par Known issues/bugs:
1825  * None
1826  *
1827  * \par Sample code:
1828  * \code
1829  * ...
1830  *
1831  * MSG_HANDLE_T msgHandle = NULL;
1832  * msg_thread_view_t    msgThreadInfo;
1833  * MSG_ERROR_T err;
1834  *
1835  * ...
1836  * err = msg_thread_view_get_thread_id(&msgThreadInfo);
1837  * if(msg_size > 0)
1838  * {
1839  * ...
1840  * }
1841  * ...
1842  * \endcode
1843  */
1844 /*================================================================================================*/
1845 int msg_thread_view_get_thread_id(msg_thread_view_t msg_thread);
1846
1847
1848 /**
1849
1850  * \par Description:
1851  * Return address value in thread view object.
1852  *
1853  * \par Purpose:
1854  * This API is used to get the address value in thread view object.
1855  *
1856  * \par Typical use case:
1857  * Returns address value in thread view object.
1858  *
1859  * \par Method of function operation:
1860  * Returns the threadAddr member of thread view object msg.
1861  *
1862  * \par Sync (or) Async:
1863  * This is a Synchronous API.
1864  *
1865  * \par Important notes:
1866  * - If msg_thread is NULL, nothing happens.
1867  * - If msg_thread is invalid, undefined behavior happens.
1868  * - You do not need to free the return value. It will be freed when you call msg_release_thread_view_list().
1869  * - Also, the value is valid until msg_thread_view_t is freed by calling msg_release_thread_view_list().
1870  *
1871  * \param msg_thread_view_t input - msg_thread is a thread view object.
1872  *
1873  * \return Return Type int const char* (address value) \n
1874  * - const char*                                        address value.
1875  * - NULL                                                       msg_thread is NULL.
1876  *
1877  * \par Prospective clients:
1878  * External/Native Apps using Messaging Services.
1879  *
1880  * \par Related functions:
1881  * None
1882  *
1883  * \par Known issues/bugs:
1884  * None
1885  *
1886  * \par Sample code:
1887  * \code
1888  * ...
1889  *
1890  * MSG_HANDLE_T msgHandle = NULL;
1891  * msg_thread_view_t    msgThreadInfo;
1892  * char* addr = NULL;
1893  *
1894  * ...
1895  * addr = msg_thread_view_get_address(&msgThreadInfo);
1896  * if(addr != 0 && strlen(addt) > 0)
1897  * {
1898  * ...
1899  * }
1900  * ...
1901  * \endcode
1902  */
1903 /*================================================================================================*/
1904 const char* msg_thread_view_get_address(msg_thread_view_t msg_thread);
1905
1906
1907 /**
1908
1909  * \par Description:
1910  * Return display name value in thread view object.
1911  *
1912  * \par Purpose:
1913  * This API is used to get the display name value in thread view object.
1914  *
1915  * \par Typical use case:
1916  * Returns address value in thread view object.
1917  *
1918  * \par Method of function operation:
1919  * Returns the threadName member of thread view object msg.
1920  *
1921  * \par Sync (or) Async:
1922  * This is a Synchronous API.
1923  *
1924  * \par Important notes:
1925  * - If msg_thread is NULL, nothing happens.
1926  * - If msg_thread is invalid, undefined behavior happens.
1927  * - You do not need to free the return value. It will be freed when you call msg_release_thread_view_list().
1928  * - Also, the value is valid until msg_thread_view_t is freed by calling msg_release_thread_view_list().
1929  *
1930  * \param msg_thread_view_t input - msg_thread is a thread view object.
1931  *
1932  * \return Return Type int const char* (display name) \n
1933  * - const char*                                        display name.
1934  * - NULL                                                       msg_thread is NULL.
1935  *
1936  * \par Prospective clients:
1937  * External/Native Apps using Messaging Services.
1938  *
1939  * \par Related functions:
1940  * None
1941  *
1942  * \par Known issues/bugs:
1943  * None
1944  *
1945  * \par Sample code:
1946  * \code
1947  * ...
1948  *
1949  * MSG_HANDLE_T msgHandle = NULL;
1950  * msg_thread_view_t    msgThreadInfo;
1951  * char* disp_name = NULL;
1952  *
1953  * ...
1954  * disp_name = msg_thread_view_get_name(&msgThreadInfo);
1955  * if(disp_name != 0 && strlen(disp_name) > 0)
1956  * {
1957  * ...
1958  * }
1959  * ...
1960  * \endcode
1961  */
1962 /*================================================================================================*/
1963 const char* msg_thread_view_get_name(msg_thread_view_t msg_thread);
1964
1965
1966 /**
1967
1968  * \par Description:
1969  * Return image path in thread view object.
1970  *
1971  * \par Purpose:
1972  * This API is used to get the image path value in thread view object.
1973  *
1974  * \par Typical use case:
1975  * Returns image path value in thread view object.
1976  *
1977  * \par Method of function operation:
1978  * Returns the threadImagePath member of thread view object msg.
1979  *
1980  * \par Sync (or) Async:
1981  * This is a Synchronous API.
1982  *
1983  * \par Important notes:
1984  * - If msg_thread is NULL, nothing happens.
1985  * - If msg_thread is invalid, undefined behavior happens.
1986  * - You do not need to free the return value. It will be freed when you call msg_release_thread_view_list().
1987  * - Also, the value is valid until msg_thread_view_t is freed by calling msg_release_thread_view_list().
1988  *
1989  * \param msg_thread_view_t input - msg_thread is a thread view object.
1990  *
1991  * \return Return Type int const char* (thread image path) \n
1992  * - const char*                                        thread image path.
1993  * - NULL                                                       msg_thread is NULL.
1994  *
1995  * \par Prospective clients:
1996  * External/Native Apps using Messaging Services.
1997  *
1998  * \par Related functions:
1999  * None
2000  *
2001  * \par Known issues/bugs:
2002  * None
2003  *
2004  * \par Sample code:
2005  * \code
2006  * ...
2007  *
2008  * MSG_HANDLE_T msgHandle = NULL;
2009  * msg_thread_view_t    msgThreadInfo;
2010  * char* img_path = NULL;
2011  *
2012  * ...
2013  * img_path = msg_thread_view_get_name(&msgThreadInfo);
2014  * if(img_path != 0 && strlen(img_path) > 0)
2015  * {
2016  * ...
2017  * }
2018  * ...
2019  * \endcode
2020  */
2021 /*================================================================================================*/
2022 const char* msg_thread_view_get_image_path(msg_thread_view_t msg_thread);
2023
2024
2025 /**
2026
2027  * \par Description:
2028  * Return the message type field in thread view object.
2029  *
2030  * \par Purpose:
2031  * This API is used to get the message type field value in thread view object.
2032  *
2033  * \par Typical use case:
2034  * Returns the message type value in thread view object.
2035  *
2036  * \par Method of function operation:
2037  * Returns the msgType member of thread view object msg.
2038  *
2039  * \par Sync (or) Async:
2040  * This is a Synchronous API.
2041  *
2042  * \par Important notes:
2043  * - If msg_thread is NULL, nothing happens.
2044  * - If msg_thread is invalid, undefined behavior happens.
2045  * - You do not need to free the return value. It will be freed when you call msg_release_thread_view_list().
2046  * - Also, the value is valid until msg_thread_view_t is freed by calling msg_release_thread_view_list().
2047  *
2048  * \param msg_thread_view_t input - msg_thread is a thread view object.
2049  *
2050  * \return Return Type (int (MSG_ERROR_T when negative, msg_type when positive)) \n
2051  * - positive int                                       enum _MSG_MESSAGE_TYPE_E.
2052  * - EINVAL                                             msg_thread is NULL.
2053  *
2054  * \par Prospective clients:
2055  * External/Native Apps using Messaging Services.
2056  *
2057  * \par Related functions:
2058  * None
2059  *
2060  * \par Known issues/bugs:
2061  * None
2062  *
2063  * \par Sample code:
2064  * \code
2065  * ...
2066  *
2067  * MSG_HANDLE_T msgHandle = NULL;
2068  * msg_thread_view_t    msgThreadInfo;
2069  * MSG_MESSAGE_TYPE_T msg_type;
2070  *
2071  * ...
2072  * msg_type = msg_thread_view_get_message_type(&msgThreadInfo);
2073  * ...
2074  * \endcode
2075  */
2076 /*================================================================================================*/
2077 int msg_thread_view_get_message_type(msg_thread_view_t msg_thread);
2078
2079
2080 /**
2081
2082  * \par Description:
2083  * Return data field in thread view object.
2084  *
2085  * \par Purpose:
2086  * This API is used to get the data field value in thread view object.
2087  *
2088  * \par Typical use case:
2089  * Returns data value in thread view object.
2090  *
2091  * \par Method of function operation:
2092  * Returns the threadData member of thread view object msg.
2093  *
2094  * \par Sync (or) Async:
2095  * This is a Synchronous API.
2096  *
2097  * \par Important notes:
2098  * - If msg_thread is NULL, nothing happens.
2099  * - If msg_thread is invalid, undefined behavior happens.
2100  * - You do not need to free the return value. It will be freed when you call msg_release_thread_view_list().
2101  * - Also, the value is valid until msg_thread_view_t is freed by calling msg_release_thread_view_list().
2102  *
2103  * \param msg_thread_view_t input - msg_thread is a thread view object.
2104  *
2105  * \return Return Type int const char* (message data) \n
2106  * - const char*                                        message data.
2107  * - NULL                                                       msg_thread is NULL.
2108  *
2109  * \par Prospective clients:
2110  * External/Native Apps using Messaging Services.
2111  *
2112  * \par Related functions:
2113  * None
2114  *
2115  * \par Known issues/bugs:
2116  * None
2117  *
2118  * \par Sample code:
2119  * \code
2120  * ...
2121  *
2122  * MSG_HANDLE_T msgHandle = NULL;
2123  * msg_thread_view_t    msgThreadInfo;
2124  * char* msg_data = NULL;
2125  *
2126  * ...
2127  * msg_data = msg_thread_view_get_data(&msgThreadInfo);
2128  * if(msg_data != 0 && strlen(msg_data) > 0)
2129  * {
2130  * ...
2131  * }
2132  * ...
2133  * \endcode
2134  */
2135 /*================================================================================================*/
2136 const char* msg_thread_view_get_data(msg_thread_view_t msg_thread);
2137
2138
2139 /**
2140
2141  * \par Description:
2142  * Return time field in thread view object.
2143  *
2144  * \par Purpose:
2145  * This API is used to get the time field value in thread view object.
2146  *
2147  * \par Typical use case:
2148  * Returns time value in thread view object.
2149  *
2150  * \par Method of function operation:
2151  * Returns the threadTime member of thread view object msg.
2152  *
2153  * \par Sync (or) Async:
2154  * This is a Synchronous API.
2155  *
2156  * \par Important notes:
2157  * - If msg_thread is NULL, nothing happens.
2158  * - If msg_thread is invalid, undefined behavior happens.
2159  * - You do not need to free the return value. It will be freed when you call msg_release_thread_view_list().
2160  * - Also, the value is valid until msg_thread_view_t is freed by calling msg_release_thread_view_list().
2161  *
2162  * \param msg_thread_view_t input - msg_thread is a thread view object.
2163  *
2164  * \return Return Type (time_t) \n
2165  * - time_t                                             message time.
2166  * - NULL                                                       thread view object is NULL.
2167  *
2168  * \par Prospective clients:
2169  * External/Native Apps using Messaging Services.
2170  *
2171  * \par Related functions:
2172  * None
2173  *
2174  * \par Known issues/bugs:
2175  * None
2176  *
2177  * \par Sample code:
2178  * \code
2179  * ...
2180  *
2181  * MSG_HANDLE_T msgHandle = NULL;
2182  * msg_thread_view_t    msgThreadInfo;
2183  * time_t msg_time;
2184  *
2185  * ...
2186  * msg_time = msg_thread_view_get_time(&msgThreadInfo);
2187  * ...
2188  * \endcode
2189  */
2190 /*================================================================================================*/
2191 time_t* msg_thread_view_get_time(msg_thread_view_t msg_thread);
2192
2193
2194 /**
2195
2196  * \par Description:
2197  * Return direction field in thread view object.
2198  *
2199  * \par Purpose:
2200  * This API is used to get the direction field value in thread view object.
2201  *
2202  * \par Typical use case:
2203  * Returns direction value in thread view object.
2204  *
2205  * \par Method of function operation:
2206  * Returns the direction member of thread view object msg.
2207  *
2208  * \par Sync (or) Async:
2209  * This is a Synchronous API.
2210  *
2211  * \par Important notes:
2212  * - If msg_thread is NULL, nothing happens.
2213  * - If msg_thread is invalid, undefined behavior happens.
2214  *
2215  * \param msg_thread_view_t input - msg_thread is a thread view object.
2216  *
2217  * \return Return Type (time_t) \n
2218  * - positive int                                       enum _MSG_DIRECTION_TYPE_E.
2219  * - MSG_ERR_NULL_POINTER                               msg_thread is NULL.
2220  *
2221  * \par Prospective clients:
2222  * External/Native Apps using Messaging Services.
2223  *
2224  * \par Related functions:
2225  * None
2226  *
2227  * \par Known issues/bugs:
2228  * None
2229  *
2230  * \par Sample code:
2231  * \code
2232  * ...
2233  *
2234  * MSG_HANDLE_T msgHandle = NULL;
2235  * msg_thread_view_t    msgThreadInfo;
2236  * int direction;
2237  *
2238  * ...
2239  * direction = msg_thread_view_get_direction(&msgThreadInfo);
2240  * ...
2241  * \endcode
2242  */
2243 /*================================================================================================*/
2244 int msg_thread_view_get_direction(msg_thread_view_t msg_thread);
2245
2246
2247 /**
2248
2249  * \par Description:
2250  * Return contact id field in thread view object.
2251  *
2252  * \par Purpose:
2253  * This API is used to get the contact id field value in thread view object.
2254  *
2255  * \par Typical use case:
2256  * Returns contact id value in thread view object.
2257  *
2258  * \par Method of function operation:
2259  * Returns the contactId member of thread view object msg.
2260  *
2261  * \par Sync (or) Async:
2262  * This is a Synchronous API.
2263  *
2264  * \par Important notes:
2265  * - If msg_thread is NULL, nothing happens.
2266  * - If msg_thread is invalid, undefined behavior happens.
2267  *
2268  * \param msg_thread_view_t input - msg_thread is a thread view object.
2269  *
2270  * \return Return Type (int (MSG_ERROR_T when negative, contact id when positive)) \n
2271  * - positive int                                       contact id
2272  * - MSG_ERR_NULL_POINTER                       msg_thread is NULL.
2273  *
2274  * \par Prospective clients:
2275  * External/Native Apps using Messaging Services.
2276  *
2277  * \par Related functions:
2278  * None
2279  *
2280  * \par Known issues/bugs:
2281  * None
2282  *
2283  * \par Sample code:
2284  * \code
2285  * ...
2286  *
2287  * MSG_HANDLE_T msgHandle = NULL;
2288  * msg_thread_view_t    msgThreadInfo;
2289  * int contact_id;
2290  *
2291  * ...
2292  * contact_id = msg_thread_view_get_contact_id(&msgThreadInfo);
2293  * ...
2294  * \endcode
2295  */
2296 /*================================================================================================*/
2297 int msg_thread_view_get_contact_id(msg_thread_view_t msg_thread);
2298
2299
2300 /**
2301
2302  * \par Description:
2303  * Return unread message count field in thread view object.
2304  *
2305  * \par Purpose:
2306  * This API is used to get the unread message count field value in thread view object.
2307  *
2308  * \par Typical use case:
2309  * Returns unread message count value in thread view object.
2310  *
2311  * \par Method of function operation:
2312  * Returns the unreadCnt member of thread view object msg.
2313  *
2314  * \par Sync (or) Async:
2315  * This is a Synchronous API.
2316  *
2317  * \par Important notes:
2318  * - If msg_thread is NULL, nothing happens.
2319  * - If msg_thread is invalid, undefined behavior happens.
2320  *
2321  * \param msg_thread_view_t input - msg_thread is a thread view object.
2322  *
2323  * \return Return Type nt (MSG_ERROR_T when negative, unread message count  when positive) \n
2324  * - positive int                                       unread message count \n
2325  * - MSG_ERR_NULL_POINTER                       msg_thread is NULL.
2326  *
2327  * \par Prospective clients:
2328  * External/Native Apps using Messaging Services.
2329  *
2330  * \par Related functions:
2331  * None
2332  *
2333  * \par Known issues/bugs:
2334  * None
2335  *
2336  * \par Sample code:
2337  * \code
2338  * ...
2339  *
2340  * MSG_HANDLE_T msgHandle = NULL;
2341  * msg_thread_view_t    msgThreadInfo;
2342  * int unread_count;
2343  *
2344  * ...
2345  * unread_count= msg_thread_view_get_unread_cnt(&msgThreadInfo);
2346  * ...
2347  * \endcode
2348  */
2349 /*================================================================================================*/
2350 int msg_thread_view_get_unread_cnt(msg_thread_view_t msg_thread);
2351
2352
2353
2354 /**
2355
2356  * \par Description:
2357  * Return sms message count field in thread view object.
2358  *
2359  * \par Purpose:
2360  * This API is used to get the sms message count field value in thread view object.
2361  *
2362  * \par Typical use case:
2363  * Returns sms message count value in thread view object.
2364  *
2365  * \par Method of function operation:
2366  * Returns the smsCnt member of thread view object msg.
2367  *
2368  * \par Sync (or) Async:
2369  * This is a Synchronous API.
2370  *
2371  * \par Important notes:
2372  * - If msg_thread is NULL, nothing happens.
2373  * - If msg_thread is invalid, undefined behavior happens.
2374  *
2375  * \param msg_thread_view_t input - msg_thread is a thread view object.
2376  *
2377  * \return Return Type int (MSG_ERROR_T when negative, sms message count when positive) \n
2378  * - positive int                                       sms message count
2379  * - MSG_ERR_NULL_POINTER                       msg_thread is NULL.
2380  *
2381  * \par Prospective clients:
2382  * External/Native Apps using Messaging Services.
2383  *
2384  * \par Related functions:
2385  * None
2386  *
2387  * \par Known issues/bugs:
2388  * None
2389  *
2390  * \par Sample code:
2391  * \code
2392  * ...
2393  *
2394  * MSG_HANDLE_T msgHandle = NULL;
2395  * msg_thread_view_t    msgThreadInfo;
2396  * int sms_count;
2397  *
2398  * ...
2399  * sms_count= msg_thread_view_get_sms_cnt(&msgThreadInfo);
2400  * ...
2401  * \endcode
2402  */
2403 /*================================================================================================*/
2404 int msg_thread_view_get_sms_cnt(msg_thread_view_t msg_thread);
2405
2406
2407 /**
2408
2409  * \par Description:
2410  * Return mms message count field in thread view object.
2411  *
2412  * \par Purpose:
2413  * This API is used to get the mms message count field value in thread view object.
2414  *
2415  * \par Typical use case:
2416  * Returns mms message count value in thread view object.
2417  *
2418  * \par Method of function operation:
2419  * Returns the mmsCnt member of thread view object msg.
2420  *
2421  * \par Sync (or) Async:
2422  * This is a Synchronous API.
2423  *
2424  * \par Important notes:
2425  * - If msg_thread is NULL, nothing happens.
2426  * - If msg_thread is invalid, undefined behavior happens.
2427  *
2428  * \param msg_thread_view_t input - msg_thread is a thread view object.
2429  *
2430  * \return Return Type int (MSG_ERROR_T when negative, mms message count when positive) \n
2431  * - positive int                                       sms message count
2432  * - MSG_ERR_NULL_POINTER                       msg_thread is NULL.
2433  *
2434  * \par Prospective clients:
2435  * External/Native Apps using Messaging Services.
2436  *
2437  * \par Related functions:
2438  * None
2439  *
2440  * \par Known issues/bugs:
2441  * None
2442  *
2443  * \par Sample code:
2444  * \code
2445  * ...
2446  *
2447  * MSG_HANDLE_T msgHandle = NULL;
2448  * msg_thread_view_t    msgThreadInfo;
2449  * int mms_count;
2450  *
2451  * ...
2452  * mms_count= msg_thread_view_get_mms_cnt(&msgThreadInfo);
2453  * ...
2454  * \endcode
2455  */
2456 /*================================================================================================*/
2457 int msg_thread_view_get_mms_cnt(msg_thread_view_t msg_thread);
2458
2459
2460 /**
2461
2462  * \par Description:
2463  * Search messages or addresses which including a string that applcation want to find.
2464  *
2465  * \par Purpose:
2466  * This API is used to search messages or addresses from storage.
2467  *
2468  * \par Typical use case:
2469  * Search messages or addresses from storage.
2470  *
2471  * \par Method of function operation:
2472  * search messages or addresses from storage.
2473  *
2474  * \par Sync (or) Async:
2475  * This is a Synchronous API.
2476  *
2477  * \par Important notes:
2478  * None
2479  *
2480  * \param input - MSG_HANDLE_T  handle is Message handle.
2481  * \param input - search_string is the string to search.
2482  * \param output - msg_thread_view_list is a pointer to an MSG_THREAD_VIEW_LIST_S structure.
2483  *
2484  * \return Return Type int (MSG_ERROR_T) \n
2485  * - MSG_SUCCESS                                        Success in operation.
2486  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
2487  * - MSG_ERR_STORAGE_ERROR              Storage is error.
2488  *
2489  * \par Prospective clients:
2490  * External/Native Apps using Messaging Services.
2491  *
2492  * \par Related functions:
2493  * None
2494  *
2495  * \par Known issues/bugs:
2496  * None
2497  *
2498  * \par Sample code:
2499  * \code
2500  * ...
2501  *
2502  * MSG_HANDLE_T msgHandle = NULL;
2503  * MSG_ERROR_T err = MSG_SUCCESS;
2504  * ...
2505  * char* search_string = "hello";
2506  * MSG_THREAD_VIEW_LIST_S threadViewList;
2507  * ...
2508  * err = msg_search_message_for_thread_view(&msgHandle, search_string, &threadViewList);
2509  *
2510  * if( err != MSG_SUCCESS )
2511  * {
2512  *      printf("err [%d]", err);
2513  *      return err;
2514  * }
2515  * ...
2516  * \endcode
2517  */
2518 /*================================================================================================*/
2519 int msg_search_message_for_thread_view(MSG_HANDLE_T handle, const char *search_string, MSG_THREAD_VIEW_LIST_S *msg_thread_view_list);
2520
2521
2522 /**
2523
2524  * \par Description:
2525  * Search messages or addresses which including a string that applcation want to find.
2526  *
2527  * \par Purpose:
2528  * This API is used to search messages or addresses from storage.
2529  *
2530  * \par Typical use case:
2531  * Search messages or addresses from storage.
2532  *
2533  * \par Method of function operation:
2534  * search messages or addresses from storage.
2535  *
2536  * \par Sync (or) Async:
2537  * This is a Synchronous API.
2538  *
2539  * \par Important notes:
2540  * None
2541  *
2542  * \param input - MSG_HANDLE_T  handle is Message handle.
2543  * \param input - search_string is the string to search.
2544  * \param input - offset is the offset of the search result.
2545  * \param input - limit is the limit of the search result.
2546  * \param output - msg_list is a pointer to an MSG_LIST_S structure.
2547  *
2548  * \return Return Type int (MSG_ERROR_T) \n
2549  * - MSG_SUCCESS                                        Success in operation.
2550  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
2551  * - MSG_ERR_STORAGE_ERROR              Storage is error.
2552  *
2553  * \par Prospective clients:
2554  * External/Native Apps using Messaging Services.
2555  *
2556  * \par Related functions:
2557  * None
2558  *
2559  * \par Known issues/bugs:
2560  * None
2561  *
2562  * \par Sample code:
2563  * \code
2564  * ...
2565  *
2566  * MSG_HANDLE_T msgHandle = NULL;
2567  * MSG_ERROR_T err = MSG_SUCCESS;
2568  * ...
2569  * MSG_LIST_S msg_list;
2570  * int offset = 0;
2571  * int limit = 10;
2572  *
2573  * MSG_SEARCH_CONDITION_S searchCon;
2574  *
2575  * searchCon.msgType = MSG_TYPE_SMS;
2576  * searchCon.folderId = MSG_INBOX_ID;
2577  * searchCon.pSearchVal = "keyString";
2578  * searchCon.pAddressVal = "01000000000";
2579  *
2580  * ...
2581  * err = msg_search_message(hMsgHandle, &searchCon, offset, limit, &msgList);
2582  *
2583  * if( err != MSG_SUCCESS )
2584  * {
2585  *      printf("err [%d]", err);
2586  *      return err;
2587  * }
2588  * ...
2589  * \endcode
2590  */
2591 /*================================================================================================*/
2592 int msg_search_message(MSG_HANDLE_T handle, const MSG_SEARCH_CONDITION_S *msg_search_conditions, int offset, int limit, MSG_LIST_S *msg_list);
2593
2594
2595 /**
2596
2597  * \par Description:
2598  * Free the memory of msg_message_t, which is created by msg_new_message().
2599  *
2600  * \par Purpose:
2601  * This API is used to release memory created by message creation.
2602  *
2603  * \par Typical use case:
2604  * After using message object for send/save scenario, release message need to be called.
2605  *
2606  * \par Method of function operation:
2607  * Frees the memory allocated to message object and deletes the object.
2608  *
2609  * \par Sync (or) Async:
2610  * This is a Synchronous API.
2611  *
2612  * \par Important notes:
2613  * - None
2614  *
2615  * \param msg_message_t    input - message object to be destroyed .
2616  *
2617  * \return Return Type (int(MSG_ERROR_T)) \n
2618  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
2619  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
2620  *
2621  * \par Prospective clients:
2622  * External/Native Apps using Messaging Services.
2623  *
2624  * \par Related functions:
2625  * None
2626  *
2627  * \par Known issues/bugs:
2628  * None
2629  *
2630  * \par Sample code:
2631  * \code
2632  * ...
2633  *
2634  * MSG_HANDLE_T msgHandle = NULL;
2635  * MSG_ERROR_T err = MSG_SUCCESS;
2636  * msg_message_t                msg;
2637  *
2638  * ...
2639  *
2640  * err = msg_open_msg_handle(&msgHandle);
2641  *
2642  * ...
2643  *
2644  * msg = msg_new_message();
2645  * ...
2646  * err = msg_release_message(&msg);
2647  *
2648  * if (err != MSG_SUCCESS)
2649  * {
2650  *      sprintf(str, "msg_release_message() Fail [%d]", err);
2651  *      print(str);
2652  *
2653  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
2654  * }
2655  *
2656  * ...
2657  * \endcode
2658  */
2659 /*================================================================================================*/
2660 int msg_release_message_list(MSG_LIST_S *msg_list);
2661
2662
2663 /**
2664
2665  * \par Description:
2666  * Get message ID list that application wants to find by reference ID.
2667  *
2668  * \par Purpose:
2669  * This API is used to get message ID list from storage.
2670  *
2671  * \par Typical use case:
2672  * Get message ID list from storage.
2673  *
2674  * \par Method of function operation:
2675  * Get message ID list from storage.
2676  *
2677  * \par Sync (or) Async:
2678  * This is a Synchronous API.
2679  *
2680  * \par Important notes:
2681  * None
2682  *
2683  * \param input - MSG_HANDLE_T  handle is Message handle.
2684  * \param input - ref_id is the reference id of message group.
2685  * \param output - msg_msgid_list is a pointer to an MSG_MSGID_LIST_S structure.
2686  *
2687  * \return Return Type int (MSG_ERROR_T) \n
2688  * - MSG_SUCCESS                                        Success in operation.
2689  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
2690  * - MSG_ERR_STORAGE_ERROR              Storage is error.
2691  *
2692  * \par Prospective clients:
2693  * External/Native Apps using Messaging Services.
2694  *
2695  * \par Related functions:
2696  * None
2697  *
2698  * \par Known issues/bugs:
2699  * None
2700  *
2701  * \par Sample code:
2702  * \code
2703  * ...
2704  *
2705  * MSG_HANDLE_T msgHandle = NULL;
2706  * MSG_ERROR_T err = MSG_SUCCESS;
2707  * ...
2708  * MSG_REFERENCE_ID_T refId = 0;
2709  * MSG_MSGID_LIST_S msgIdList;
2710  * ...
2711  * err = msg_get_msgid_list(hMsgHandle, refId, &msgIdList);
2712  *
2713  * if( err != MSG_SUCCESS )
2714  * {
2715  *      printf("err [%d]", err);
2716  *      return err;
2717  * }
2718  * ...
2719  * \endcode
2720  */
2721 /*================================================================================================*/
2722 int msg_get_msgid_list(MSG_HANDLE_T handle, MSG_REFERENCE_ID_T ref_id, MSG_MSGID_LIST_S *msg_msgid_list);
2723
2724
2725 /**
2726
2727  * \par Description:
2728  * Frees the memory of MSG_MSGID_LIST_S allocated in msg_get_msgid_list.
2729  *
2730  * \par Purpose:
2731  * This API is used to free the memory of MSG_MSGID_LIST_S allocated in msg_get_msgid_list.
2732  *
2733  * \par Typical use case:
2734  * To free the memory of MSG_MSGID_LIST_S and its members which was allocated in msg_get_msgid_list.
2735  *
2736  * \par Method of function operation:
2737  * To free the memory of MSG_MSGID_LIST_S and its members which was allocated in msg_get_msgid_list.
2738  *
2739  * \par Sync (or) Async:
2740  * This is a Synchronous API.
2741  *
2742  * \par Important notes:
2743  * - If MSG_MSGID_LIST_S is NULL, nothing happens.
2744  * - If MSG_MSGID_LIST_S is invalid, undefined behavior happens.
2745  *
2746  * \param input - MSG_MSGID_LIST_S structure.
2747  *
2748  * \return Return Type (void) \n
2749  *
2750  * \par Prospective clients:
2751  * External/Native Apps using Messaging Services.
2752  *
2753  * \par Related functions:
2754  * - None
2755  *
2756  * \par Known issues/bugs:
2757  * None
2758  *
2759  * \par Sample code:
2760  * \code
2761  * ...
2762  *
2763  * MSG_HANDLE_T msgHandle = NULL;
2764  * MSG_ERROR_T err = MSG_SUCCESS;
2765  * ...
2766  * MSG_REFERENCE_ID_T refId = 0;
2767  * MSG_MSGID_LIST_S msgIdList;
2768  * ...
2769  * err = msg_get_msgid_list(hMsgHandle, refId, &msgIdList);
2770  *
2771  * if( err != MSG_SUCCESS )
2772  * {
2773  *      printf("err [%d]", err);
2774  *      return err;
2775  * }
2776  *
2777  * msg_release_msgid_list(&msgIdList);
2778  * ...
2779  * \endcode
2780  */
2781 /*================================================================================================*/
2782 void msg_release_msgid_list(MSG_MSGID_LIST_S *msg_msgid_list);
2783
2784
2785 /**
2786
2787  * \par Description:
2788  * Get reject message list that application wants to find by phone number.
2789  *
2790  * \par Purpose:
2791  * This API is used to get reject message list from storage.
2792  *
2793  * \par Typical use case:
2794  * Get reject message list from storage.
2795  *
2796  * \par Method of function operation:
2797  * Get reject message list from storage.
2798  *
2799  * \par Sync (or) Async:
2800  * This is a Synchronous API.
2801  *
2802  * \par Important notes:
2803  * None
2804  *
2805  * \param input - MSG_HANDLE_T  handle is Message handle.
2806  * \param input - phone_num is the string of phone number to find.
2807  * \param output - msg_reject_msg_list is a pointer to an MSG_REJECT_MSG_LIST_S structure.
2808
2809  * \return Return Type int (MSG_ERROR_T) \n
2810  * - MSG_SUCCESS                                        Success in operation.
2811  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
2812  * - MSG_ERR_STORAGE_ERROR              Storage is error.
2813  *
2814  * \par Prospective clients:
2815  * External/Native Apps using Messaging Services.
2816  *
2817  * \par Related functions:
2818  * None
2819  *
2820  * \par Known issues/bugs:
2821  * None
2822  *
2823  * \par Sample code:
2824  * \code
2825  * ...
2826  *
2827  * MSG_HANDLE_T msgHandle = NULL;
2828  * MSG_ERROR_T err = MSG_SUCCESS;
2829  * ...
2830  * char* phone_num = "01030016057";
2831  * MSG_REJECT_MSG_LIST_S rejectMsgList;
2832  * ...
2833  * err = msg_get_reject_msg_list(hMsgHandle, phone_num, &rejectMsgList);
2834  *
2835  * if( err != MSG_SUCCESS )
2836  * {
2837  *      printf("err [%d]", err);
2838  *      return err;
2839  * }
2840  * ...
2841  * \endcode
2842  */
2843 /*================================================================================================*/
2844 int msg_get_reject_msg_list(MSG_HANDLE_T handle, const char* phone_num, MSG_REJECT_MSG_LIST_S *msg_reject_msg_list);
2845
2846
2847 /**
2848
2849  * \par Description:
2850  * Frees the memory of MSG_REJECT_MSG_LIST_S allocated in msg_get_reject_msg_list.
2851  *
2852  * \par Purpose:
2853  * This API is used to free the memory of MSG_REJECT_MSG_LIST_S allocated in msg_get_reject_msg_list.
2854  *
2855  * \par Typical use case:
2856  * To free the memory of MSG_REJECT_MSG_LIST_S and its members which was allocated in msg_get_reject_msg_list.
2857  *
2858  * \par Method of function operation:
2859  * To free the memory of MSG_REJECT_MSG_LIST_S and its members which was allocated in msg_get_reject_msg_list.
2860  *
2861  * \par Sync (or) Async:
2862  * This is a Synchronous API.
2863  *
2864  * \par Important notes:
2865  * - If MSG_REJECT_MSG_LIST_S is NULL, nothing happens.
2866  * - If MSG_REJECT_MSG_LIST_S is invalid, undefined behavior happens.
2867  *
2868  * \param input - MSG_REJECT_MSG_LIST_S structure.
2869  *
2870  * \return Return Type (void) \n
2871  *
2872  * \par Prospective clients:
2873  * External/Native Apps using Messaging Services.
2874  *
2875  * \par Related functions:
2876  * - None
2877  *
2878  * \par Known issues/bugs:
2879  * None
2880  *
2881  * \par Sample code:
2882  * \code
2883  * ...
2884  *
2885  * MSG_HANDLE_T msgHandle = NULL;
2886  * MSG_ERROR_T err = MSG_SUCCESS;
2887  * ...
2888  * char* phone_num = "01030016057";
2889  * MSG_REJECT_MSG_LIST_S rejectMsgList;
2890  * ...
2891  * err = msg_get_reject_msg_list(hMsgHandle, phone_num, &rejectMsgList);
2892  *
2893  * if( err != MSG_SUCCESS )
2894  * {
2895  *      printf("err [%d]", err);
2896  *      return err;
2897  * }
2898  *
2899  * msg_release_reject_msg_list(&rejectMsgList);
2900  * ...
2901  * \endcode
2902  */
2903 /*================================================================================================*/
2904 void msg_release_reject_msg_list(MSG_REJECT_MSG_LIST_S *msg_reject_msg_list);
2905
2906
2907 /**
2908
2909  * \par Description:
2910  * Registers a callback function about the change of storage status to Message handle.
2911  *
2912  * \par Purpose:
2913  * This API is used to register a callback function about the change of storage status "msg_storage_change_cb" to Message handle.
2914  *
2915  * \par Typical use case:
2916  * Register a callback function about the change of storage status.
2917  *
2918  * \par Method of function operation:
2919  * Adds the msg_storage_change_cb API to a callback function list.
2920  *
2921  * \par Sync (or) Async:
2922  * This is a Synchronous API.
2923  *
2924  * \par Important notes:
2925  *      This function MUST be called after Message handle is opened.
2926  *
2927  * \param input - handle is Message handle.
2928  * \param input - cb is a function to be called.
2929  * \param input - user_param is a pointer to user data.
2930  *
2931  * \return Return Type (int(MSG_ERROR_T)) \n
2932  * - MSG_SUCCESS                                                        Success in operation.
2933  * - MSG_ERR_MSGHANDLE_NOT_CONNECTED    Message handle is not connected.
2934  * - MSG_ERR_MEMORY_ERROR                               Memory is error.
2935  *
2936  * \par Prospective clients:
2937  * External/Native Apps using Messaging Services.
2938  *
2939  * \par Related functions:
2940  * None
2941  *
2942  * \par Known issues/bugs:
2943  * None
2944  *
2945  * \par Sample code:
2946  * \code
2947  * ...
2948  *
2949  * int err = MSG_SUCCESS;
2950  *
2951  * err = msg_reg_storage_change_callback(msgHandle, &storageCB, NULL);
2952  * if (err != MSG_SUCCESS)
2953  * {
2954  * ...
2955  * }
2956  * return;
2957  * }
2958  *
2959  * void storageCB(MSG_HANDLE_T handle, MSG_THREAD_ID_T threadId, MSG_MESSAGE_ID_T msgId, void *user_param)
2960  * {
2961  *      ...
2962  * }
2963  * ...
2964  * \endcode
2965  */
2966 /*================================================================================================*/
2967 int msg_reg_storage_change_callback(MSG_HANDLE_T handle, msg_storage_change_cb cb, void *user_param);
2968
2969
2970 /**
2971
2972  * \par Description:
2973  * Gets the report status information of message.
2974  *
2975  * \par Purpose:
2976  * This API is used to get the report status information of specified message.
2977  *
2978  * \par Typical use case:
2979  * Gets the report status information of specified message from the database.
2980  *
2981  * \par Method of function operation:
2982  * Sets up the database connection and Gets the report status information of specified message from the report table.
2983  *
2984  * \par Sync (or) Async:
2985  * This is a Synchronous API.
2986  *
2987  * \par Important notes:
2988  * - None
2989  *
2990  * \param input - handle is Message handle.
2991  * \param input - msg_id is the ID of the message.
2992  * \param output - report_status is a pointer to a MSG_REPORT_STATUS_INFO_S structure.
2993  *
2994  * \return Return Type (int(MSG_ERROR_T)) \n
2995  * - MSG_SUCCESS        - Success in operation.
2996  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
2997  * - MSG_ERR_STORAGE_ERROR - Storage is error.
2998  *
2999  * \par Prospective clients:
3000  * External/Native Apps using Messaging Services.
3001  *
3002  * \par Related functions:
3003  * None
3004  *
3005  * \par Known issues/bugs:
3006  * None
3007  *
3008  * \par Sample code:
3009  * \code
3010  * ...
3011  *
3012  * MSG_HANDLE_T msgHandle = NULL;
3013  * MSG_REPORT_STATUS_INFO_S reportStatus;
3014  *
3015  * ...
3016  *
3017  * err = msg_open_msg_handle(&msgHandle);
3018  *
3019  * ...
3020  *
3021  * err = msg_get_report_status(msgHandle, msgID, &reportStatus)
3022 * if( err != MSG_SUCCESS )
3023  * {
3024  *      printf("err [%d]", err);
3025  *      return err;
3026  * }
3027  *
3028  * ...
3029  * \endcode
3030  */
3031 /*================================================================================================*/
3032 int msg_get_report_status(MSG_HANDLE_T handle, MSG_MESSAGE_ID_T msg_id, MSG_REPORT_STATUS_INFO_S *report_status);
3033
3034 /**
3035  *      @}
3036  */
3037
3038 #ifdef __cplusplus
3039 }
3040 #endif
3041
3042 #endif // MAPI_STORAGE_H
3043