include/mapi/msg_storage.h

   1 /*
   2 * Copyright 2012-2013  Samsung Electronics Co., Ltd
   3 *
   4 * Licensed under the Flora License, Version 1.1 (the "License");
   5 * you may not use this file except in compliance with the License.
   6 * You may obtain a copy of the License at
   7 *
   8 *    http://floralicense.org/license/
   9 *
  10 * Unless required by applicable law or agreed to in writing, software
  11 * distributed under the License is distributed on an "AS IS" BASIS,
  12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 * See the License for the specific language governing permissions and
  14 * limitations under the License.
  15 */
  16
  17 /**
  18  *      @file           MapiStorage.h
  19  *      @brief          Defines storage API of messaging framework
  20  *      @version        1.0
  21  */
  22
  23 #ifndef MAPI_STORAGE_H
  24 #define MAPI_STORAGE_H
  25
  26 /**
  27  *      @section                Introduction
  28  *      - Introduction : Overview on Messaging Storage API
  29  *      @section                Program
  30  *      - Program : Messaging Storage API Reference
  31  */
  32
  33 /*==================================================================================================
  34                                          INCLUDE FILES
  35 ==================================================================================================*/
  36
  37 #include "msg_storage_types.h"
  38
  39 #ifdef __cplusplus
  40 extern "C"
  41 {
  42 #endif
  43
  44 /**
  45  *      @ingroup                MESSAGING_FRAMEWORK
  46  *      @defgroup       MESSAGING_STORAGE_API   Messaging Storage API
  47  *      @{
  48  */
  49
  50 /*==================================================================================================
  51                                      FUNCTION PROTOTYPES
  52 ==================================================================================================*/
  53
  54 /**
  55
  56  * \par Description:
  57  * Saves a message to the database.
  58  *
  59  * \par Purpose:
  60  * This API is used to save Message object to the database.
  61  *
  62  * \par Typical use case:
  63  * Save Message feature is used when the message is to be stored to persistent memory for later reference.
  64  *
  65  * \par Method of function operation:
  66  * Sets up the database connection and inserts the message to message table.
  67  *
  68  * \par Sync (or) Async:
  69  * This is a Synchronous API.
  70  *
  71  * \par Important notes:
  72  * - Mandatory fields of a message structure MUST be valid, otherwise the function will be failed.
  73  *
  74  * \param input - msg_handle_t  handle is Message handle.
  75  * \param input - msg_message_t  msg is a pointer to an msg_message_t structure.
  76  * \param input - send_opt is a pointer to an MSG_SENDINGOPT_S structure.
  77  *
  78  * \return Return Type (int(msg_error_t)) \n
  79  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
  80  * - MSG_ERR_NULL_POINTER       - Input parameter is NULL.
  81  * - MSG_ERR_STORAGE_ERROR - Storage is error.
  82  *
  83  * \par Prospective clients:
  84  * External/Native Apps using Messaging Services.
  85  *
  86  * \par Related functions:
  87  * None
  88  *
  89  * \par Known issues/bugs:
  90  * None
  91  *
  92  * \par Sample code:
  93  * \code
  94  * ...
  95  *
  96  * msg_handle_t msgHandle = NULL;
  97  * msg_message_t                msg;
  98  * MSG_SENDINGOPT_S sendingOpt = {0};
  99  *
 100  * ...
 101  *
 102  * err = msg_open_msg_handle(&msgHandle);
 103  *
 104  * ...
 105  *
 106  * err = msg_add_message(handle, (msg_message_t) &msg, &sendingOpt);
 107  * if( err != MSG_SUCCESS )
 108  * {
 109  *      printf("err [%d]", err);
 110  *      return err;
 111  * }
 112  *
 113  * ...
 114  * \endcode
 115  */
 116 /*================================================================================================*/
 117 int msg_add_message(msg_handle_t handle, const msg_struct_t msg, const msg_struct_t send_opt);
 118
 119
 120 /**
 121
 122  * \par Description:
 123  * Adds a SyncML message to the database.
 124  *
 125  * \par Purpose:
 126  * This API is used to save  a SyncML message to the database.
 127  *
 128  * \par Typical use case:
 129  * Save Message feature is used when the message is to be stored to persistent memory for later reference.
 130  *
 131  * \par Method of function operation:
 132  * Sets up the database connection and inserts the syncml message to message table.
 133  *
 134  * \par Sync (or) Async:
 135  * This is a Synchronous API.
 136  *
 137  * \par Important notes:
 138  * - Mandatory fields of a message structure MUST be valid, otherwise the function will be failed.
 139  *
 140  * \param input - msg_handle_t  handle is Message handle.
 141  * \param input - MSG_SYNCML_MESSAGE_S  syncml_msg is a pointer to an MSG_SYNCML_MESSAGE_S structure.
 142  *
 143  * \return Return Type (int(msg_error_t)) \n
 144  * - MSG_SUCCESS        - Success in operation.
 145  * - MSG_ERR_NULL_POINTER - pMsg is NULL.
 146  * - MSG_ERR_INVALID_MSGHANDLE - Message handle is invalid.
 147  * - MSG_ERR_MSGHANDLE_NOT_CONNECTED - Message handle is not connected.
 148  * - MSG_ERR_STORAGE_FULL - Storage is FULL.
 149  * - MSG_ERR_COMMUNICATION_ERROR - Communication between client and server is error.
 150  * - MSG_ERR_MEMORY_ERROR - Memory is error.
 151  * - MSG_ERR_MAX_NUMBER_REACHED - Max number is reached.
 152  * - MSG_ERR_PLUGIN - Generic error code for plugin.
 153  *
 154  * \par Prospective clients:
 155  * External/Native Apps using Messaging Services.
 156  *
 157  * \par Related functions:
 158  * None
 159  *
 160  * \par Known issues/bugs:
 161  * None
 162  *
 163  * \par Sample code:
 164  * \code
 165  * ...
 166  *
 167  * msg_handle_t msgHandle = NULL;
 168  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 169  *
 170  * ...
 171  *
 172  * err = msg_open_msg_handle(&msgHandle);
 173  *
 174  * ...
 175  *
 176  * int err = msg_add_syncml_message(msgHandle, &syncMLMsg);
 177  * if( err != MSG_SUCCESS )
 178  * {
 179  *      printf("err [%d]", err);
 180  *      return err;
 181  * }
 182  *
 183  * ...
 184  * \endcode
 185  */
 186 /*================================================================================================*/
 187 int msg_add_syncml_message(msg_handle_t handle, const msg_struct_t syncml_msg);
 188
 189
 190 /**
 191
 192  * \par Description:
 193  * Updates a message in the database.
 194  *
 195  * \par Purpose:
 196  * This API is used to update a message in the database.
 197  *
 198  * \par Typical use case:
 199  * Update message feature is used when a previously saved message is to be updated.
 200  *
 201  * \par Method of function operation:
 202  * Sets up the database connection and set the message's new values to message table.
 203  *
 204  * \par Sync (or) Async:
 205  * This is a Synchronous API.
 206  *
 207  * \par Important notes:
 208  * - The function is to update message data for the message indentified by the given msgId as long as the given values are valid.
 209  * - msg->msgId MUST NOT be updated because msg->msgId is a unique Id on platform.
 210  * - If applications want to move a message between folders, applications SHOULD call msg_move_to_folder.
 211  * - msg->storageId MUST NOT be updated.
 212  * - The function will return MSG_ERR_INVALID_MESSAGE, if inputting a new msg->storageId.
 213  * - If applications want to move the message between storages, applications SHOULD call msg_move_to_storage.
 214  *
 215  * \param input - handle is Message handle.
 216  * \param input - msg is a pointer to an msg_message_t structure.
 217  * \param input - send_opt is a pointer to an MSG_SENDINGOPT_S structure.
 218  *
 219  * \return Return Type (int(msg_error_t)) \n
 220  * - MSG_SUCCESS        - Success in operation.
 221  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 222  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 223  *
 224  * \par Prospective clients:
 225  * External/Native Apps using Messaging Services.
 226  *
 227  * \par Related functions:
 228  * None
 229  *
 230  * \par Known issues/bugs:
 231  * None
 232  *
 233  * \par Sample code:
 234  * \code
 235  * ...
 236  *
 237  * msg_handle_t msgHandle = NULL;
 238  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 239  * MSG_SENDINGOPT_S sendingOpt = {0};
 240  *
 241  * ...
 242  *
 243  * err = msg_open_msg_handle(&msgHandle);
 244  *
 245  * ...
 246  *
 247  * err = msg_update_message(hMsgHandle, pMsg, &sendOpt);
 248  * if( err != MSG_SUCCESS )
 249  * {
 250  *      printf("err [%d]", err);
 251  *      return err;
 252  * }
 253  *
 254  * ...
 255  * \endcode
 256  */
 257 /*================================================================================================*/
 258 int msg_update_message(msg_handle_t handle, const msg_struct_t msg, const msg_struct_t send_opt);
 259
 260
 261 /**
 262
 263  * \par Description:
 264  * Updates a message's read status in the database.
 265  *
 266  * \par Purpose:
 267  * This API is used to Updates a message's read status in the database.
 268  *
 269  * \par Typical use case:
 270  * Update message's read status for a previously saved message.
 271  *
 272  * \par Method of function operation:
 273  * Sets up the database connection and updates the message's read status to message table.
 274  *
 275  * \par Sync (or) Async:
 276  * This is a Synchronous API.
 277  *
 278  * \par Important notes:
 279  * - None
 280  *
 281  * \param input - handle is Message handle.
 282  * \param input - msg_id is Message ID.
 283  * \parem input - read is boolean for indicating whether a message is read or not.
 284  *
 285  * \return Return Type (int(msg_error_t)) \n
 286  * - MSG_SUCCESS        - Success in operation.
 287  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 288  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 289  *
 290  * \par Prospective clients:
 291  * External/Native Apps using Messaging Services.
 292  *
 293  * \par Related functions:
 294  * None
 295  *
 296  * \par Known issues/bugs:
 297  * None
 298  *
 299  * \par Sample code:
 300  * \code
 301  * ...
 302  *
 303  * msg_handle_t msgHandle = NULL;
 304  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 305  * MSG_SENDINGOPT_S sendingOpt = {0};
 306  *
 307  * ...
 308  *
 309  * err = msg_open_msg_handle(&msgHandle);
 310  *
 311  * ...
 312  *
 313  * err = msg_update_message(hMsgHandle, pMsg, &sendOpt);
 314  * if( err != MSG_SUCCESS )
 315  * {
 316  *      printf("err [%d]", err);
 317  *      return err;
 318  * }
 319  *
 320  * ...
 321  * \endcode
 322  */
 323 /*================================================================================================*/
 324 int msg_update_read_status(msg_handle_t handle, msg_message_id_t msg_id, bool read);
 325
 326
 327 /**
 328
 329  * \par Description:
 330  * Updates a message's protected status in the database.
 331  *
 332  * \par Purpose:
 333  * This API is used to Updates a message's protected status in the database.
 334  *
 335  * \par Typical use case:
 336  * Update message's protected status for a previously saved message.
 337  *
 338  * \par Method of function operation:
 339  * Sets up the database connection and updates the message's protected status to message table.
 340  *
 341  * \par Sync (or) Async:
 342  * This is a Synchronous API.
 343  *
 344  * \par Important notes:
 345  * - None
 346  *
 347  * \param input - handle is Message handle.
 348  * \param input - msg_id is Message ID.
 349  * \parem input - is_protected is boolean for indicating whether a message is protected or not.
 350  *
 351  * \return Return Type (int(msg_error_t)) \n
 352  * - MSG_SUCCESS        - Success in operation.
 353  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 354  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 355  *
 356  * \par Prospective clients:
 357  * External/Native Apps using Messaging Services.
 358  *
 359  * \par Related functions:
 360  * None
 361  *
 362  * \par Known issues/bugs:
 363  * None
 364  *
 365  * \par Sample code:
 366  * \code
 367  * ...
 368  *
 369  * msg_handle_t msgHandle = NULL;
 370  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 371  * MSG_SENDINGOPT_S sendingOpt = {0};
 372  *
 373  * ...
 374  *
 375  * err = msg_open_msg_handle(&msgHandle);
 376  *
 377  * ...
 378  *
 379  * err = msg_update_protected_status(hMsgHandle, 0, true);
 380  * if( err != MSG_SUCCESS )
 381  * {
 382  *      printf("err [%d]", err);
 383  *      return err;
 384  * }
 385  *
 386  * ...
 387  * \endcode
 388  */
 389 /*================================================================================================*/
 390 int msg_update_protected_status(msg_handle_t handle, msg_message_id_t msg_id, bool is_protected);
 391
 392
 393 /**
 394
 395  * \par Description:
 396  * Deletes a message by Message ID from the database.
 397  *
 398  * \par Purpose:
 399  * This API is used to delete a message by Message ID from the database.
 400  *
 401  * \par Typical use case:
 402  * Deletes a previously saved message from the database.
 403  *
 404  * \par Method of function operation:
 405  * Sets up the database connection and deletes a message by Message ID from the message table.
 406  *
 407  * \par Sync (or) Async:
 408  * This is a Synchronous API.
 409  *
 410  * \par Important notes:
 411  * - None
 412  *
 413  * \param input - handle is Message handle.
 414  * \param input - msg_id is the ID of the Message to be deleted.
 415  *
 416  * \return Return Type (int(msg_error_t)) \n
 417  * - MSG_SUCCESS        - Success in operation.
 418  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 419  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 420  *
 421  * \par Prospective clients:
 422  * External/Native Apps using Messaging Services.
 423  *
 424  * \par Related functions:
 425  * None
 426  *
 427  * \par Known issues/bugs:
 428  * None
 429  *
 430  * \par Sample code:
 431  * \code
 432  * ...
 433  *
 434  * msg_handle_t msgHandle = NULL;
 435  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 436  * MSG_SENDINGOPT_S sendingOpt = {0};
 437  *
 438  * ...
 439  *
 440  * err = msg_open_msg_handle(&msgHandle);
 441  *
 442  * ...
 443  *
 444  * err = msg_delete_message(msgHandle, 0);
 445  * if( err != MSG_SUCCESS )
 446  * {
 447  *      printf("err [%d]", err);
 448  *      return err;
 449  * }
 450  *
 451  * ...
 452  * \endcode
 453  */
 454 /*================================================================================================*/
 455 int msg_delete_message(msg_handle_t handle, msg_message_id_t msg_id);
 456
 457
 458 /**
 459
 460  * \par Description:
 461  * Deletes all messages in the specified folder from the database.
 462  *
 463  * \par Purpose:
 464  * This API is used to delete all messages in the specified folder from the database.
 465  *
 466  * \par Typical use case:
 467  * Deletes all messages in the specified folder from the database.
 468  *
 469  * \par Method of function operation:
 470  * Sets up the database connection and Deletes all messages in the specified folder from the message table.
 471  *
 472  * \par Sync (or) Async:
 473  * This is a Synchronous API.
 474  *
 475  * \par Important notes:
 476  * - None
 477  *
 478  * \param input - handle is Message handle.
 479  * \param input - folder_id is the ID of the folder to be deleted.
 480  *
 481  * \return Return Type (int(msg_error_t)) \n
 482  * - MSG_SUCCESS        - Success in operation.
 483  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 484  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 485  *
 486  * \par Prospective clients:
 487  * External/Native Apps using Messaging Services.
 488  *
 489  * \par Related functions:
 490  * None
 491  *
 492  * \par Known issues/bugs:
 493  * None
 494  *
 495  * \par Sample code:
 496  * \code
 497  * ...
 498  *
 499  * msg_handle_t msgHandle = NULL;
 500  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 501  * MSG_SENDINGOPT_S sendingOpt = {0};
 502  *
 503  * ...
 504  *
 505  * err = msg_open_msg_handle(&msgHandle);
 506  *
 507  * ...
 508  *
 509  * err = msg_delete_all_msgs_in_folder(msgHandle, MSG_DRAFT_ID);
 510  * if( err != MSG_SUCCESS )
 511  * {
 512  *      printf("err [%d]", err);
 513  *      return err;
 514  * }
 515  *
 516  * ...
 517  * \endcode
 518  */
 519 /*================================================================================================*/
 520 int msg_delete_all_msgs_in_folder(msg_handle_t handle, msg_folder_id_t folder_id, bool bOnlyDB);
 521
 522
 523
 524 /**
 525
 526  * \par Description:
 527  * Moves a message to the specified folder in the database.
 528  *
 529  * \par Purpose:
 530  * This API is used to move a message to the specified folder the database.
 531  *
 532  * \par Typical use case:
 533  * Deletes all messages in the specified folder from the database.
 534  *
 535  * \par Method of function operation:
 536  * Sets up the database connection and Deletes all messages in the specified folder from the message table.
 537  *
 538  * \par Sync (or) Async:
 539  * This is a Synchronous API.
 540  *
 541  * \par Important notes:
 542  * - None
 543  *
 544  * \param input - handle is Message handle.
 545  * \param input - msg_id is the ID of the message to be moved.
 546  * \param input - dest_folder_id is the ID of the destination folder.
 547  *
 548  * \return Return Type (int(msg_error_t)) \n
 549  * - MSG_SUCCESS        - Success in operation.
 550  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 551  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 552  *
 553  * \par Prospective clients:
 554  * External/Native Apps using Messaging Services.
 555  *
 556  * \par Related functions:
 557  * None
 558  *
 559  * \par Known issues/bugs:
 560  * None
 561  *
 562  * \par Sample code:
 563  * \code
 564  * ...
 565  *
 566  * msg_handle_t msgHandle = NULL;
 567  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 568  * MSG_SENDINGOPT_S sendingOpt = {0};
 569  *
 570  * ...
 571  *
 572  * err = msg_open_msg_handle(&msgHandle);
 573  *
 574  * ...
 575  *
 576  * err = msg_move_msg_to_folder(hMsgHandle, 0, MSG_OUTBOX_ID);
 577  * if( err != MSG_SUCCESS )
 578  * {
 579  *      printf("err [%d]", err);
 580  *      return err;
 581  * }
 582  *
 583  * ...
 584  * \endcode
 585  */
 586 /*================================================================================================*/
 587 int msg_move_msg_to_folder(msg_handle_t handle, msg_message_id_t msg_id, msg_folder_id_t dest_folder_id);
 588
 589
 590 /**
 591
 592  * \par Description:
 593  * Moves a message to the other storage.
 594  *
 595  * \par Purpose:
 596  * This API is usd to move a message to the other storage.
 597  *
 598  * \par Typical use case:
 599  * Moves a message to the other storage type.
 600  *
 601  * \par Method of function operation:
 602  * Sets up the database connection and  moves a messages to specified storage type.
 603  *
 604  * \par Sync (or) Async:
 605  * This is a Synchronous API.
 606  *
 607  * \par Important notes:
 608  * - None
 609  *
 610  * \param input - handle is Message handle.
 611  * \param input - msg_id is the ID of the message to be moved.
 612  * \param input - storage_id is the ID of the destination storage.
 613  *
 614  * \return Return Type (int(msg_error_t)) \n
 615  * - MSG_SUCCESS        - Success in operation.
 616  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 617  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 618  *
 619  * \par Prospective clients:
 620  * External/Native Apps using Messaging Services.
 621  *
 622  * \par Related functions:
 623  * None
 624  *
 625  * \par Known issues/bugs:
 626  * None
 627  *
 628  * \par Sample code:
 629  * \code
 630  * ...
 631  *
 632  * msg_handle_t msgHandle = NULL;
 633  * MSG_SYNCML_MESSAGE_S syncMLMsg;
 634  * MSG_SENDINGOPT_S sendingOpt = {0};
 635  *
 636  * ...
 637  *
 638  * err = msg_open_msg_handle(&msgHandle);
 639  *
 640  * ...
 641  *
 642  * err = msg_move_msg_to_storage( msgHandle, 0, MSG_STORAGE_PHONE);
 643  * if( err != MSG_SUCCESS )
 644  * {
 645  *      printf("err [%d]", err);
 646  *      return err;
 647  * }
 648  *
 649  * ...
 650  * \endcode
 651  */
 652 /*================================================================================================*/
 653 int msg_move_msg_to_storage(msg_handle_t handle, msg_message_id_t msg_id, msg_storage_id_t storage_id);
 654
 655
 656 /**
 657
 658  * \par Description:
 659  * Gets the number of messages in the specified folder from the database.
 660  *
 661  * \par Purpose:
 662  * This API is used to get the number of messages in the specified folder from the database.
 663  *
 664  * \par Typical use case:
 665  * Gets the number of messages in the specified folder from the database.
 666  *
 667  * \par Method of function operation:
 668  * Sets up the database connection and Gets the number of messages in the specified folder from the message table.
 669  *
 670  * \par Sync (or) Async:
 671  * This is a Synchronous API.
 672  *
 673  * \par Important notes:
 674  * - None
 675  *
 676  * \param input - handle is Message handle.
 677  * \param input - folder_id is the ID of the folder to be counted.
 678  * \param output - count_info is a pointer to an MSG_COUNT_INFO_S structure.
 679  *
 680  * \return Return Type (int(msg_error_t)) \n
 681  * - MSG_SUCCESS        - Success in operation.
 682  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 683  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 684  *
 685  * \par Prospective clients:
 686  * External/Native Apps using Messaging Services.
 687  *
 688  * \par Related functions:
 689  * None
 690  *
 691  * \par Known issues/bugs:
 692  * None
 693  *
 694  * \par Sample code:
 695  * \code
 696  * ...
 697  *
 698  * msg_handle_t msgHandle = NULL;
 699  * MSG_COUNT_INFO_S countInfo;
 700  *
 701  * ...
 702  *
 703  * err = msg_open_msg_handle(&msgHandle);
 704  *
 705  * ...
 706  *
 707  * err = msg_count_message(msgHandle, MSG_OUTBOX_ID, &countInfo)
 708 * if( err != MSG_SUCCESS )
 709  * {
 710  *      printf("err [%d]", err);
 711  *      return err;
 712  * }
 713  *
 714  * ...
 715  * \endcode
 716  */
 717 /*================================================================================================*/
 718 int msg_count_message(msg_handle_t handle, msg_folder_id_t folder_id, msg_struct_t count_info);
 719
 720
 721 /**
 722
 723  * \par Description:
 724  * Gets the number of messages of specific message type.
 725  *
 726  * \par Purpose:
 727  * This API is used to get the number of messages of specific type.
 728  *
 729  * \par Typical use case:
 730  * Gets the count of message of specific types such as SMS, MMS.
 731  *
 732  * \par Method of function operation:
 733  * Sets up the database connection and queries the number of messages in the specified folder from the message table based on required message type.
 734  *
 735  * \par Sync (or) Async:
 736  * This is a Synchronous API.
 737  *
 738  * \par Important notes:
 739  * - None
 740  *
 741  * \param input - handle is Message handle.
 742  * \param input - msg_type is the message type to be counted.
 743  * \param output - msg_count is a pointer to the number of message.
 744  *
 745  * \return Return Type (int(msg_error_t)) \n
 746  * - MSG_SUCCESS        - Success in operation.
 747  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 748  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 749  *
 750  * \par Prospective clients:
 751  * External/Native Apps using Messaging Services.
 752  *
 753  * \par Related functions:
 754  * None
 755  *
 756  * \par Known issues/bugs:
 757  * None
 758  *
 759  * \par Sample code:
 760  * \code
 761  * ...
 762  *
 763  * msg_handle_t msgHandle = NULL;
 764  * MSG_COUNT_INFO_S countInfo;
 765  *
 766  * ...
 767  *
 768  * err = msg_open_msg_handle(&msgHandle);
 769  *
 770  * ...
 771  *
 772  * err = msg_count_msg_by_type(msgHandle, MSG_TYPE_SMS, &countInfo);
 773  * if( err != MSG_SUCCESS )
 774  * {
 775  *      printf("err [%d]", err);
 776  *      return err;
 777  * }
 778  *
 779  * ...
 780  * \endcode
 781  */
 782 /*================================================================================================*/
 783 int msg_count_msg_by_type(msg_handle_t handle, msg_message_type_t msg_type, int *msg_count);
 784
 785
 786 /**
 787
 788  * \par Description:
 789  * Gets the number of messages of specific address.
 790  *
 791  * \par Purpose:
 792  * This API is used to get the number of messages from a specific address.
 793  *
 794  * \par Typical use case:
 795  * Get the count of messages from the specified address
 796  *
 797  * \par Method of function operation:
 798  * Sets up the database connection and queries the number of messages based on address from the message table.
 799  *
 800  * \par Sync (or) Async:
 801  * This is a Synchronous API.
 802  *
 803  * \par Important notes:
 804  * - If addr_info is NULL, nothing happens.
 805  *
 806  * \param input - handle is Message handle.
 807  * \param input - addr_info is a pointer to an MSG_ADDRESS_INFO_LIST_S structure.
 808  * \param input - msg_thread_count_list is a pointer to an MSG_THREAD_COUNT_INFO_S structure.
 809  *
 810  * \return Return Type (int(msg_error_t)) \n
 811  * - MSG_SUCCESS        - Success in operation.
 812  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 813  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 814  *
 815  * \par Prospective clients:
 816  * External/Native Apps using Messaging Services.
 817  *
 818  * \par Related functions:
 819  * None
 820  *
 821  * \par Known issues/bugs:
 822  * None
 823  *
 824  * \par Sample code:
 825  * \code
 826  * ...
 827  *
 828  * msg_handle_t msgHandle = NULL;
 829  * MSG_COUNT_INFO_S countInfo;
 830  *
 831  * ...
 832  *
 833  * err = msg_open_msg_handle(&msgHandle);
 834  *
 835  * ...
 836  *
 837  * err = msg_count_msg_by_type(msgHandle, MSG_TYPE_SMS, &countInfo);
 838  * if( err != MSG_SUCCESS )
 839  * {
 840  *      printf("err [%d]", err);
 841  *      return err;
 842  * }
 843  *
 844  * ...
 845  * \endcode
 846  */
 847 /*================================================================================================*/
 848 int msg_count_msg_by_contact(msg_handle_t handle, const msg_struct_t addr_info, msg_struct_t msg_thread_count_list);
 849
 850
 851 /**
 852
 853  * \par Description:
 854  * Gets the detail information of a message from the database.
 855  *
 856  * \par Purpose:
 857  * This API is used to get the number of messages from a specific address.
 858  *
 859  * \par Typical use case:
 860  * Get the count of messages from the specified address
 861  *
 862  * \par Method of function operation:
 863  * Sets up the database connection and queries the number of messages based on address from the message table.
 864  *
 865  * \par Sync (or) Async:
 866  * This is a Synchronous API.
 867  *
 868  * \par Important notes:
 869  * - If addr_info is NULL, nothing happens.
 870  * - Applications need to call msg_release_message to free the memory.
 871  * - However, if this function is failed, the memory for the message is NOT allocated in this function.
 872  *
 873 handle is Message handle.
 874  * \param input - handle is Message handle.
 875  * \param input - msg_id is the ID of the Message to be returned.
 876  * \param output - msg is a pointer to an msg_message_t structure.
 877  * \param input - send_opt is a pointer to an MSG_SENDINGOPT_S structure.
 878  *
 879  * \return Return Type (int(msg_error_t)) \n
 880  * - MSG_SUCCESS        - Success in operation.
 881  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 882  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 883  *
 884  * \par Prospective clients:
 885  * External/Native Apps using Messaging Services.
 886  *
 887  * \par Related functions:
 888  * - None
 889  *
 890  * \par Known issues/bugs:
 891  * None
 892  *
 893  * \par Sample code:
 894  * \code
 895  * ...
 896  *
 897  * msg_handle_t msgHandle = NULL;
 898  *
 899  * ...
 900  * msg_message_t msg = msg_new_message();
 901  * MSG_SENDINGOPT_S sendOpt = {0, };
 902  * ...
 903  * err = msg_get_message(msgHandle, 0, msg, &sendOpt);
 904  * if( err != MSG_SUCCESS )
 905  * {
 906  *      printf("err [%d]", err);
 907  *      return err;
 908  * }
 909  *
 910  * ...
 911  * \endcode
 912  */
 913 /*================================================================================================*/
 914 int msg_get_message(msg_handle_t handle, msg_message_id_t msg_id, msg_struct_t msg, msg_struct_t send_opt);
 915
 916 int msg_get_conversation(msg_handle_t handle, msg_message_id_t msg_id, msg_struct_t conv);
 917 int msg_get_vobject_data(msg_handle_t handle, msg_message_id_t msg_id, void** encoded_data);
 918
 919 /**
 920
 921  * \par Description:
 922  * Returns the common information list of messages with selected folder id.
 923  *
 924  * \par Purpose:
 925  * This API is used to get the common information list of messages with selected folder id from database.
 926  *
 927  * \par Typical use case:
 928  * Get the common information from the specified folder from database.
 929  *
 930  * \par Method of function operation:
 931  * Sets up the database connection and queries the common information based on selected folder id from the message and folder tables.
 932  *
 933  * \par Sync (or) Async:
 934  * This is a Synchronous API.
 935  *
 936  * \par Important notes:
 937  * - The memory for a message will be allocated in this function.
 938  * - Applications need to call msg_release_folder_view_list to free the memory.
 939  * - However, if this function is failed, the memory for the message is NOT allocated in this function.
 940  *
 941  * \param input - handle is Message handle.
 942  * \param input - folder_id is the ID of the folder to be returned.
 943  * \param input - sort_rule indicates a sort type and sort order for querying messages.
 944  * \param output - msg_folder_view_list is a pointer to an MSG_FOLDER_VIEW_LIST_S structure.
 945  *
 946  * \return Return Type (int(msg_error_t)) \n
 947  * - MSG_SUCCESS        - Success in operation.
 948  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 949  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 950  *
 951  * \par Prospective clients:
 952  * External/Native Apps using Messaging Services.
 953  *
 954  * \par Related functions:
 955  * - None
 956  *
 957  * \par Known issues/bugs:
 958  * None
 959  *
 960  * \par Sample code:
 961  * \code
 962  * ...
 963  *
 964  * msg_handle_t msgHandle = NULL;
 965  *
 966  * ...
 967  * MSG_FOLDER_VIEW_LIST_S folderViewList;
 968  * ...
 969  * err = msg_get_folder_view_list(hMsgHandle, 0, NULL, &folderViewList);
 970  * if( err != MSG_SUCCESS )
 971  * {
 972  *      printf("err [%d]", err);
 973  *      return err;
 974  * }
 975  *
 976  * ...
 977  * \endcode
 978  */
 979 /*================================================================================================*/
 980 int msg_get_folder_view_list(msg_handle_t handle, msg_folder_id_t folder_id, const msg_struct_t sort_rule, msg_struct_list_s *msg_folder_view_list);
 981
 982
 983 /**
 984
 985  * \par Description:
 986  * Returns the information of all peers to whom messages have been sent or recieved.
 987  *
 988  * \par Purpose:
 989  * This API is used to get the information of all peers to whom messages have been sent or recieved.
 990  *
 991  * \par Typical use case:
 992  * Get the common information from the specified folder from database.
 993  *
 994  * \par Method of function operation:
 995  * Frees the memory occupied by MSG_FOLDER_VIEW_LIST_S object and its members.
 996  *
 997  * \par Sync (or) Async:
 998  * This is a Synchronous API.
 999  *
1000  * \par Important notes:
1001  * - The memory for a list will be allocated in this function.
1002  * - Applications need to call msg_release_thread_view_list to free the memory.
1003  * - However, if this function is failed, the memory for a list is NOT allocated in this function.
1004  *
1005  * \param input - handle is Message handle.
1006  * \param input - sort_rule indicates a sort type and sort order for querying messages.
1007  * \param output - msg_thread_view_list is a pointer to an msg_struct_list_s structure.
1008  *
1009  * \return Return Type (int(msg_error_t)) \n
1010  * - MSG_SUCCESS        - Success in operation.
1011  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1012  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1013  *
1014  * \par Prospective clients:
1015  * External/Native Apps using Messaging Services.
1016  *
1017  * \par Related functions:
1018  * None
1019  *
1020  * \par Known issues/bugs:
1021  * None
1022  *
1023  * \par Sample code:
1024  * \code
1025  * ...
1026  *
1027  * msg_handle_t msgHandle = NULL;
1028  *
1029  * ...
1030  * msg_struct_list_s threadViewList;
1031  * ...
1032  * err = msg_get_thread_view_list(hMsgHandle, NULL, &threadViewList);
1033  * ...
1034  * msg_release_thread_view_list(&threadViewList);
1035  * if( err != MSG_SUCCESS )
1036  * {
1037  *      printf("err [%d]", err);
1038  *      return err;
1039  * }
1040  * \endcode
1041  */
1042 /*================================================================================================*/
1043 int msg_get_thread_view_list(msg_handle_t handle, const msg_struct_t sort_rule, msg_struct_list_s *msg_thread_view_list);
1044
1045
1046 /**
1047
1048  * \par Description:
1049  * Returns the common information list of messages with selected thread_id.
1050  *
1051  * \par Purpose:
1052  * This API is used to get the common information list of messages with selected thread_id.
1053  *
1054  * \par Typical use case:
1055  * Gets the common information list of messages with the selected thread id from the database.
1056  *
1057  * \par Method of function operation:
1058  * Connects to the database and queries the common infomation of  list messages with the provided thread id.
1059  *
1060  * \par Sync (or) Async:
1061  * This is a Synchronous API.
1062  *
1063  * \par Important notes:
1064  * - The memory for a list will be allocated in this function.
1065  * - Applications need to call msg_release_conversation_view_list to free the memory.
1066  * - However, if this function is failed, the memory for a list is NOT allocated in this function.
1067  *
1068  * \param input - hMsgHandle is Message handle.
1069  * \param input - thread_id is the ID of the thread to be returned.
1070  * \param output - msg_conv_view_list is a pointer to an MSG_CONV_VIEW_LIST_S structure.
1071  *
1072  * \return Return Type (int(msg_error_t)) \n
1073  * - MSG_SUCCESS        - Success in operation.
1074  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1075  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1076  *
1077  * \par Prospective clients:
1078  * External/Native Apps using Messaging Services.
1079  *
1080  * \par Related functions:
1081  * - None
1082  *
1083  * \par Known issues/bugs:
1084  * None
1085  *
1086  * \par Sample code:
1087  * \code
1088  * ...
1089  *
1090  * msg_handle_t msgHandle = NULL;
1091  * msg_error_t err = MSG_SUCCESS;
1092  * ...
1093  * MSG_CONV_VIEW_LIST_S convViewList;
1094  * ...
1095  * err = msg_get_conversation_view_list(hMsgHandle, ThreadId, &convViewList);
1096  * if( err != MSG_SUCCESS )
1097  * {
1098  *      printf("err [%d]", err);
1099  *      return err;
1100  * }
1101  * msg_release_conversation_view_list(&convViewList);
1102  * ...
1103  * \endcode
1104  */
1105 /*================================================================================================*/
1106 int msg_get_conversation_view_list(msg_handle_t handle, msg_thread_id_t thread_id, msg_struct_list_s *msg_conv_view_list);
1107
1108
1109 /**
1110
1111  * \par Description:
1112  * Deletes all the Messages Sent/Received from the selected list.
1113  *
1114  * \par Purpose:
1115  * This API is used to delete all the Messages Sent/Received from the selected list.
1116  *
1117  * \par Typical use case:
1118  * Deletes all messages sent/received from the selected list.
1119  *
1120  * \par Method of function operation:
1121  * Sets up the database connection and deletes all messages sent/received from a selected list.
1122  *
1123  * \par Sync (or) Async:
1124  * This is a Synchronous API.
1125  *
1126  * \par Important notes:
1127  * - If addr_info is NULL, nothing happens.
1128  *
1129  * \param input - handle is Message handle.
1130  * \param input - thread_id is the ID of the thread to be deleted.
1131  *
1132  * \return Return Type (int(msg_error_t)) \n
1133  * - MSG_SUCCESS        - Success in operation.
1134  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1135  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1136  *
1137  * \par Prospective clients:
1138  * External/Native Apps using Messaging Services.
1139  *
1140  * \par Related functions:
1141  * None
1142  *
1143  * \par Known issues/bugs:
1144  * None
1145  *
1146  * \par Sample code:
1147  * \code
1148  * ...
1149  *
1150  * msg_handle_t msgHandle = NULL;
1151  * MSG_SYNCML_MESSAGE_S syncMLMsg;
1152  * MSG_SENDINGOPT_S sendingOpt = {0};
1153  *
1154  * ...
1155  *
1156  * err = msg_open_msg_handle(&msgHandle);
1157  *
1158  * ...
1159  *
1160  * err = msg_delete_thread_message_list(hMsgHandle, 0);
1161  * if( err != MSG_SUCCESS )
1162  * {
1163  *      printf("err [%d]", err);
1164  *      return err;
1165  * }
1166  * ...
1167  * \endcode
1168  */
1169 /*================================================================================================*/
1170 int msg_delete_thread_message_list(msg_handle_t handle, msg_thread_id_t thread_id, bool include_protected_msg);
1171
1172
1173 /**
1174
1175  * \par Description:
1176  * Adds a new folder.
1177  *
1178  * \par Purpose:
1179  * This API is used to add a new folder.
1180  *
1181  * \par Typical use case:
1182  * Adds a new folder with the specified folder info
1183  *
1184  * \par Method of function operation:
1185  * Sets up the database connection and add a new folder to the folder table.
1186  *
1187  * \par Sync (or) Async:
1188  * This is a Synchronous API.
1189  *
1190  * \par Important notes:
1191  * - None.
1192  *
1193  * \param - handle is Message handle.
1194  * \param - folder_info is a pointer to an MSG_FOLDER_INFO_S structure.
1195  *
1196  * \return Return Type (int(msg_error_t)) \n
1197  * - MSG_SUCCESS        - Success in operation.
1198  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1199  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1200  *
1201  * \par Prospective clients:
1202  * External/Native Apps using Messaging Services.
1203  *
1204  * \par Related functions:
1205  * None
1206  *
1207  * \par Known issues/bugs:
1208  * None
1209  *
1210  * \par Sample code:
1211  * \code
1212  * ...
1213  *
1214  * msg_handle_t msgHandle = NULL;
1215  *  Make Folder
1216  * MSG_FOLDER_INFO_S folderInfo;
1217  * ...
1218  * err = msg_open_msg_handle(&msgHandle);
1219  *
1220  * folderInfo.folderId = 1;
1221  * folderInfo.folderType = MSG_FOLDER_TYPE_USER_DEF;
1222  * ...
1223  *
1224  * err = msg_add_folder(hMsgHandle, &folderInfo);
1225  * if( err != MSG_SUCCESS )
1226  * {
1227  *      printf("err [%d]", err);
1228  *      return err;
1229  * }
1230  * ...
1231  * \endcode
1232  */
1233 /*================================================================================================*/
1234 int msg_add_folder(msg_handle_t handle, const msg_struct_t folder_info);
1235
1236
1237 /**
1238
1239  * \par Description:
1240  * Updates the folder info.
1241  *
1242  * \par Purpose:
1243  * This API is used to add a new folder.
1244  *
1245  * \par Typical use case:
1246  * Adds a new folder with the specified folder info
1247  *
1248  * \par Method of function operation:
1249  * Sets up the database connection and add a new folder to the folder table.
1250  *
1251  * \par Sync (or) Async:
1252  * This is a Synchronous API.
1253  *
1254  * \par Important notes:
1255  * - None.
1256  *
1257  * \param - handle is Message handle.
1258  * \param - folder_info is a pointer to an MSG_FOLDER_INFO_S structure.
1259  *
1260  * \return Return Type (int(msg_error_t)) \n
1261  * - MSG_SUCCESS        - Success in operation.
1262  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1263  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1264  *
1265  * \par Prospective clients:
1266  * External/Native Apps using Messaging Services.
1267  *
1268  * \par Related functions:
1269  * None
1270  *
1271  * \par Known issues/bugs:
1272  * None
1273  *
1274  * \par Sample code:
1275  * \code
1276  * ...
1277  *
1278  * msg_handle_t msgHandle = NULL;
1279  *  Make Folder
1280  * MSG_FOLDER_INFO_S folderInfo;
1281  * ...
1282  * err = msg_open_msg_handle(&msgHandle);
1283  *
1284  * folderInfo.folderId = 2;
1285  * folderInfo.folderType = MSG_FOLDER_TYPE_USER_DEF;
1286  * ...
1287  * err = msg_update_folder(msgHandle, &folderInfo);
1288  * if( err != MSG_SUCCESS )
1289  * {
1290  *      printf("err [%d]", err);
1291  *      return err;
1292  * }
1293  * ...
1294  * \endcode
1295  */
1296 /*================================================================================================*/
1297 int msg_update_folder(msg_handle_t handle, const msg_struct_t folder_info);
1298
1299
1300 /**
1301
1302  * \par Description:
1303  * Deletes an exisiting folder.
1304  *
1305  * \par Purpose:
1306  * This API is used to delete an existing folder.
1307  *
1308  * \par Typical use case:
1309  * Deletes an existing folder.
1310  *
1311  * \par Method of function operation:
1312  * Sets up the database connection and deletes an existing folder to the folder table.
1313  *
1314  * \par Sync (or) Async:
1315  * This is a Synchronous API.
1316  *
1317  * \par Important notes:
1318  * - None.
1319  *
1320  * \param input - handle is Message handle.
1321  * \param input - folder_id is the ID of the folder to be deleted.
1322  *
1323  * \return Return Type (int(msg_error_t)) \n
1324  * - MSG_SUCCESS        - Success in operation.
1325  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1326  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1327  *
1328  * \par Prospective clients:
1329  * External/Native Apps using Messaging Services.
1330  *
1331  * \par Related functions:
1332  * None
1333  *
1334  * \par Known issues/bugs:
1335  * None
1336  *
1337  * \par Sample code:
1338  * \code
1339  * ...
1340  *
1341  * msg_handle_t msgHandle = NULL;
1342  * err = msg_open_msg_handle(&msgHandle);
1343  *
1344  * ...
1345  * err = msg_delete_folder(hMsgHandle, MSG_INBOX_ID);
1346  * if( err != MSG_SUCCESS )
1347  * {
1348  *      printf("err [%d]", err);
1349  *      return err;
1350  * }
1351  * ...
1352  * \endcode
1353  */
1354 /*================================================================================================*/
1355 int msg_delete_folder(msg_handle_t handle, msg_folder_id_t folder_id);
1356
1357
1358 /**
1359
1360  * \par Description:
1361  * Returns the information list of folders.
1362  *
1363  * \par Purpose:
1364  * This API is used to get the information list of folders.
1365  *
1366  * \par Typical use case:
1367  * Gets the folder list information.
1368  *
1369  * \par Method of function operation:
1370  * Sets up the database connection and queries for the folder list information.
1371  *
1372  * \par Sync (or) Async:
1373  * This is a Synchronous API.
1374  *
1375  * \par Important notes:
1376  * - None.
1377  *
1378  * \param input - handle is Message handle.
1379  * \param output - folder_list is a pointer to an msg_struct_list_s structure.
1380  *
1381  * \return Return Type (int(msg_error_t)) \n
1382  * - MSG_SUCCESS        - Success in operation.
1383  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1384  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1385  *
1386  * \par Prospective clients:
1387  * External/Native Apps using Messaging Services.
1388  *
1389  * \par Related functions:
1390  * None
1391  *
1392  * \par Known issues/bugs:
1393  * None
1394  *
1395  * \par Sample code:
1396  * \code
1397  * ...
1398  *
1399  * msg_handle_t msgHandle = NULL;
1400  *  msg_struct_list_s folderList;
1401
1402  * err = msg_open_msg_handle(&msgHandle);
1403  *
1404  * ...
1405  * err = msg_get_folder_list(msgHandle, &folderList);
1406  * if( err != MSG_SUCCESS )
1407  * {
1408  *      printf("err [%d]", err);
1409  *      return err;
1410  * }
1411  * ...
1412  * msg_release_folder_list(&folderList);
1413  * \endcode
1414  */
1415 /*================================================================================================*/
1416 int msg_get_folder_list(msg_handle_t handle, msg_struct_list_s *folder_list);
1417
1418
1419 /**
1420
1421  * \par Description:
1422  * Creates the specified number of messages in database.
1423  *
1424  * \par Purpose:
1425  * This API is used to generate specified number of messages in the database
1426  *
1427  * \par Typical use case:
1428  * Generate large number of messages in the database.
1429  *
1430  * \par Method of function operation:
1431  * Creates the specified number of messages in database for specified message type in the specified folder
1432  *
1433  * \par Sync (or) Async:
1434  * This is a Synchronous API.
1435  *
1436  * \par Important notes:
1437  * - None
1438  *
1439  * \param input - handle is Message handle.
1440  * \param input - msg_type is one of enum _MSG_MESSAGE_TYPE_E.
1441  * \param input - folder_id is the folder for the test messages.
1442  * \param input - num_msg is the number of messages.
1443  *
1444  * \return Return Type (int(msg_error_t)) \n
1445  * - MSG_SUCCESS                                        Success in operation.
1446  * - MSG_ERR_INVALID_MSGHANDLE  Parameter is invalid.
1447  * - MSG_ERR_INVALID_FOLDER_ID  Storage is error.
1448  *
1449  * \par Prospective clients:
1450  * External/Native Apps using Messaging Services.
1451  *
1452  * \par Related functions:
1453  * None
1454  *
1455  * \par Known issues/bugs:
1456  * None
1457  *
1458  * \par Sample code:
1459  * \code
1460  * ...
1461  *
1462  * msg_handle_t msgHandle = NULL;
1463  *  msg_struct_list_s folderList;
1464
1465  * err = msg_open_msg_handle(&msgHandle);
1466  *
1467  * ...
1468  * err = msg_generate_message(msgHandle, MSG_TYPE_SMS, MSG_INBOX_ID, 100);
1469  * if( err != MSG_SUCCESS )
1470  * {
1471  *      printf("err [%d]", err);
1472  *      return err;
1473  * }
1474  * ...
1475  * \endcode
1476  */
1477 /*================================================================================================*/
1478 int msg_generate_message(msg_handle_t handle, msg_message_type_t msg_type, msg_folder_id_t folder_id, unsigned int num_msg);
1479 int msg_generate_sms(msg_handle_t handle, msg_folder_id_t folder_id, unsigned int num_msg) DEPRECATED;
1480
1481
1482 /**
1483
1484  * \par Description:
1485  * Returns the Message Data to be used by the Quick Panel.
1486  *
1487  * \par Purpose:
1488  * This API is used to get the Message Datato be used by the Quick Panel.
1489  *
1490  * \par Typical use case:
1491  * Quick panel needs the message information to show new message notification.
1492  *
1493  * \par Method of function operation:
1494  * Connects to database and queries for information needed by the quick panel.
1495  *
1496  * \par Sync (or) Async:
1497  * This is a Synchronous API.
1498  *
1499  * \par Important notes:
1500  * - None
1501  *
1502  * \param input - handle is Message handle.
1503  * \param input - type is the type of message that Quick Panel need.
1504  * \param output - msg is a pointer to an msg_message_t structure.
1505  *
1506  * \return Return Type (int(msg_error_t)) \n
1507  * - MSG_SUCCESS                                        Success in operation.
1508  * - MSG_ERR_INVALID_MSGHANDLE  Parameter is invalid.
1509  * - MSG_ERR_INVALID_FOLDER_ID  Storage is error.
1510  *
1511  * \par Prospective clients:
1512  * External/Native Apps using Messaging Services.
1513  *
1514  * \par Related functions:
1515  * None
1516  *
1517  * \par Known issues/bugs:
1518  * None
1519  *
1520  * \par Sample code:
1521  * \code
1522  * ...
1523  *
1524  * msg_handle_t msgHandle = NULL;
1525  * msg_message_t msgInfo;
1526
1527  * err = msg_open_msg_handle(&msgHandle);
1528  *
1529  * ...
1530  * err = msg_get_quick_panel_data(msgHandle, MSG_QUICKPANEL_SMS, msgInfo);
1531  * if( err != MSG_SUCCESS )
1532  * {
1533  *      printf("err [%d]", err);
1534  *      return err;
1535  * }
1536  * ...
1537  * \endcode
1538  */
1539 /*================================================================================================*/
1540 int msg_get_quick_panel_data(msg_handle_t handle, msg_quickpanel_type_t type, msg_struct_t msg);
1541
1542
1543 /**
1544
1545  * \par Description:
1546  * Resets the Messaging database.
1547  *
1548  * \par Purpose:
1549  * This API is used to reset the messaging database.
1550  *
1551  * \par Typical use case:
1552  * Completely delete the messaging database.
1553  *
1554  * \par Method of function operation:
1555  * Connects to database and deletes all the messaging tables.
1556  *
1557  * \par Sync (or) Async:
1558  * This is a Synchronous API.
1559  *
1560  * \par Important notes:
1561  * - None
1562  *
1563  * \param input - handle is Message handle.
1564  *
1565  * \return Return Type (int(msg_error_t)) \n
1566  * - MSG_SUCCESS                                        Success in operation.
1567  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1568  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1569  *
1570  * \par Prospective clients:
1571  * External/Native Apps using Messaging Services.
1572  *
1573  * \par Related functions:
1574  * None
1575  *
1576  * \par Known issues/bugs:
1577  * None
1578  *
1579  * \par Sample code:
1580  * \code
1581  * ...
1582  *
1583  * msg_handle_t msgHandle = NULL;
1584  * msg_error_t err = MSG_SUCCESS;
1585  * err = msg_open_msg_handle(&msgHandle);
1586  *
1587  * ...
1588  * err = msg_reset_database(msgHandle);
1589  * if (err != MSG_SUCCESS)
1590  *{
1591  *      printf("err [%d]", err);
1592  *      return err;
1593  * }
1594  * ...
1595  * \endcode
1596  */
1597 /*================================================================================================*/
1598 int msg_reset_database(msg_handle_t handle);
1599
1600
1601 /**
1602
1603  * \par Description:
1604  * Returns the total size used for message contents.
1605  *
1606  * \par Purpose:
1607  * This API is used to get the total size used for message contents.
1608  *
1609  * \par Typical use case:
1610  * To get the total space used by message contents.
1611  *
1612  * \par Method of function operation:
1613  * Uses linux system calls to query the space used by message contents.
1614  *
1615  * \par Sync (or) Async:
1616  * This is a Synchronous API.
1617  *
1618  * \par Important notes:
1619  * - None
1620  *
1621  * \param input - handle is Message handle.
1622  * \param output -      memsize is a pointer to the size.
1623  *
1624  * \return Return Type (int(msg_error_t)) \n
1625  * - MSG_SUCCESS                                        Success in operation.
1626  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1627  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1628  *
1629  * \par Prospective clients:
1630  * External/Native Apps using Messaging Services.
1631  *
1632  * \par Related functions:
1633  * None
1634  *
1635  * \par Known issues/bugs:
1636  * None
1637  *
1638  * \par Sample code:
1639  * \code
1640  * ...
1641  *
1642  * msg_handle_t msgHandle = NULL;
1643  * int memsize = 0;
1644  * err = msg_open_msg_handle(&msgHandle);
1645  *
1646  * ...
1647  * err = msg_get_mem_size(msgHandle, &memsize);
1648  * if( err != MSG_SUCCESS )
1649  * {
1650  *      printf("err [%d]", err);
1651  *      return err;
1652  * }
1653  * ...
1654  * \endcode
1655  */
1656 /*================================================================================================*/
1657 int msg_get_mem_size(msg_handle_t handle, unsigned int* memsize);
1658
1659 /**
1660
1661  * \par Description:
1662  * Backup messages to storage.
1663  *
1664  * \par Purpose:
1665  * This API is used to backup messages to storage.
1666  *
1667  * \par Typical use case:
1668  * Backup messages to storage.
1669  *
1670  * \par Method of function operation:
1671  * Reads all the messages from Messaging database and writes to storage in V-Message format
1672  *
1673  * \par Sync (or) Async:
1674  * This is a Synchronous API.
1675  *
1676  * \par Important notes:
1677  * None
1678  *
1679  * \param input - msg_handle_t  handle is Message handle.
1680  * \param input - msg_message_backup_type_t  type is backup_type.
1681  * \param input - backup_filepath is path to backup message.
1682  *
1683  * \return Return Type int (msg_error_t) \n
1684  * - MSG_SUCCESS                                        Success in operation.
1685  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1686  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1687  *
1688  * \par Prospective clients:
1689  * External/Native Apps using Messaging Services.
1690  *
1691  * \par Related functions:
1692  * None
1693  *
1694  * \par Known issues/bugs:
1695  * None
1696  *
1697  * \par Sample code:
1698  * \code
1699  * ...
1700  *
1701  * msg_handle_t msgHandle = NULL;
1702  * msg_error_t err;
1703  * msg_message_backup_type_t type = MSG_BACKUP_TYPE_MMS;
1704  * const char *filepath = "/backup_mms"
1705  *
1706  * ...
1707  * err = msg_backup_message(&msgHandle, type, filepath);
1708  * ...
1709  * \endcode
1710  */
1711 /*================================================================================================*/
1712 int msg_backup_message(msg_handle_t handle, msg_message_backup_type_t type, const char *backup_filepath);
1713
1714
1715 /**
1716
1717  * \par Description:
1718  * Restore messages from backed up messages.
1719  *
1720  * \par Purpose:
1721  * This API is used to restore messages from backed up messages.
1722  *
1723  * \par Typical use case:
1724  * Restore messages from previously backed up messages.
1725  *
1726  * \par Method of function operation:
1727  * Reads the previously backup up messages and restores the database.
1728  *
1729  * \par Sync (or) Async:
1730  * This is a Synchronous API.
1731  *
1732  * \par Important notes:
1733  * None
1734  *
1735  * \param input - msg_handle_t  handle is Message handle.
1736  * \param input - backup_filepath is path of backup file for restore.
1737  *
1738  *
1739  * \return Return Type int (msg_error_t) \n
1740  * - MSG_SUCCESS                                        Success in operation.
1741  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1742  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1743  *
1744  * \par Prospective clients:
1745  * External/Native Apps using Messaging Services.
1746  *
1747  * \par Related functions:
1748  * None
1749  *
1750  * \par Known issues/bugs:
1751  * None
1752  *
1753  * \par Sample code:
1754  * \code
1755  * ...
1756  *
1757  * msg_handle_t msgHandle = NULL;
1758  * msg_error_t err;
1759  * const char *filepath = "/backup_mms"
1760   * ...
1761  * err = msg_restore_message(&msgHandle, filepath);
1762  * ...
1763  * \endcode
1764  */
1765 /*================================================================================================*/
1766 int msg_restore_message(msg_handle_t handle, const char *backup_filepath);
1767
1768
1769 /**
1770
1771  * \par Description:
1772  * Search messages or addresses which including a string that applcation want to find.
1773  *
1774  * \par Purpose:
1775  * This API is used to search messages or addresses from storage.
1776  *
1777  * \par Typical use case:
1778  * Search messages or addresses from storage.
1779  *
1780  * \par Method of function operation:
1781  * search messages or addresses from storage.
1782  *
1783  * \par Sync (or) Async:
1784  * This is a Synchronous API.
1785  *
1786  * \par Important notes:
1787  * None
1788  *
1789  * \param input - msg_handle_t  handle is Message handle.
1790  * \param input - search_string is the string to search.
1791  * \param output - msg_thread_view_list is a pointer to an msg_struct_list_s structure.
1792  *
1793  * \return Return Type int (msg_error_t) \n
1794  * - MSG_SUCCESS                                        Success in operation.
1795  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1796  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1797  *
1798  * \par Prospective clients:
1799  * External/Native Apps using Messaging Services.
1800  *
1801  * \par Related functions:
1802  * None
1803  *
1804  * \par Known issues/bugs:
1805  * None
1806  *
1807  * \par Sample code:
1808  * \code
1809  * ...
1810  *
1811  * msg_handle_t msgHandle = NULL;
1812  * msg_error_t err = MSG_SUCCESS;
1813  * ...
1814  * char* search_string = "hello";
1815  * msg_struct_list_s threadViewList;
1816  * ...
1817  * err = msg_search_message_for_thread_view(&msgHandle, search_string, &threadViewList);
1818  *
1819  * if( err != MSG_SUCCESS )
1820  * {
1821  *      printf("err [%d]", err);
1822  *      return err;
1823  * }
1824  * ...
1825  * \endcode
1826  */
1827 /*================================================================================================*/
1828 int msg_search_message_for_thread_view(msg_handle_t handle, const char *search_string, msg_struct_list_s *msg_thread_view_list);
1829
1830
1831 /**
1832
1833  * \par Description:
1834  * Search messages or addresses which including a string that applcation want to find.
1835  *
1836  * \par Purpose:
1837  * This API is used to search messages or addresses from storage.
1838  *
1839  * \par Typical use case:
1840  * Search messages or addresses from storage.
1841  *
1842  * \par Method of function operation:
1843  * search messages or addresses from storage.
1844  *
1845  * \par Sync (or) Async:
1846  * This is a Synchronous API.
1847  *
1848  * \par Important notes:
1849  * None
1850  *
1851  * \param input - msg_handle_t  handle is Message handle.
1852  * \param input - search_string is the string to search.
1853  * \param input - offset is the offset of the search result.
1854  * \param input - limit is the limit of the search result.
1855  * \param output - msg_list is a pointer to an msg_struct_list_s structure.
1856  *
1857  * \return Return Type int (msg_error_t) \n
1858  * - MSG_SUCCESS                                        Success in operation.
1859  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1860  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1861  *
1862  * \par Prospective clients:
1863  * External/Native Apps using Messaging Services.
1864  *
1865  * \par Related functions:
1866  * None
1867  *
1868  * \par Known issues/bugs:
1869  * None
1870  *
1871  * \par Sample code:
1872  * \code
1873  * ...
1874  *
1875  * msg_handle_t msgHandle = NULL;
1876  * msg_error_t err = MSG_SUCCESS;
1877  * ...
1878  * msg_struct_list_s msg_list;
1879  * int offset = 0;
1880  * int limit = 10;
1881  *
1882  * MSG_SEARCH_CONDITION_S searchCon;
1883  *
1884  * searchCon.msgType = MSG_TYPE_SMS;
1885  * searchCon.folderId = MSG_INBOX_ID;
1886  * searchCon.pSearchVal = "keyString";
1887  * searchCon.pAddressVal = "01000000000";
1888  *
1889  * ...
1890  * err = msg_search_message(hMsgHandle, &searchCon, offset, limit, &msgList);
1891  *
1892  * if( err != MSG_SUCCESS )
1893  * {
1894  *      printf("err [%d]", err);
1895  *      return err;
1896  * }
1897  * ...
1898  * \endcode
1899  */
1900 /*================================================================================================*/
1901 int msg_search_message(msg_handle_t handle, const msg_struct_t msg_search_conditions, int offset, int limit, msg_struct_list_s *msg_list);
1902
1903 /**
1904
1905  * \par Description:
1906  * Get reject message list that application wants to find by phone number.
1907  *
1908  * \par Purpose:
1909  * This API is used to get reject message list from storage.
1910  *
1911  * \par Typical use case:
1912  * Get reject message list from storage.
1913  *
1914  * \par Method of function operation:
1915  * Get reject message list from storage.
1916  *
1917  * \par Sync (or) Async:
1918  * This is a Synchronous API.
1919  *
1920  * \par Important notes:
1921  * None
1922  *
1923  * \param input - msg_handle_t  handle is Message handle.
1924  * \param input - phone_num is the string of phone number to find.
1925  * \param output - msg_reject_msg_list is a pointer to an msg_struct_list_s structure.
1926
1927  * \return Return Type int (msg_error_t) \n
1928  * - MSG_SUCCESS                                        Success in operation.
1929  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1930  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1931  *
1932  * \par Prospective clients:
1933  * External/Native Apps using Messaging Services.
1934  *
1935  * \par Related functions:
1936  * None
1937  *
1938  * \par Known issues/bugs:
1939  * None
1940  *
1941  * \par Sample code:
1942  * \code
1943  * ...
1944  *
1945  * msg_handle_t msgHandle = NULL;
1946  * msg_error_t err = MSG_SUCCESS;
1947  * ...
1948  * char* phone_num = "01030016057";
1949  * msg_struct_list_s rejectMsgList;
1950  * ...
1951  * err = msg_get_reject_msg_list(hMsgHandle, phone_num, &rejectMsgList);
1952  *
1953  * if( err != MSG_SUCCESS )
1954  * {
1955  *      printf("err [%d]", err);
1956  *      return err;
1957  * }
1958  * ...
1959  * \endcode
1960  */
1961 /*================================================================================================*/
1962 int msg_get_reject_msg_list(msg_handle_t handle, const char* phone_num, msg_struct_list_s *msg_reject_msg_list);
1963
1964
1965 /**
1966
1967  * \par Description:
1968  * Registers a callback function about the change of storage status to Message handle.
1969  *
1970  * \par Purpose:
1971  * This API is used to register a callback function about the change of storage status "msg_storage_change_cb" to Message handle.
1972  *
1973  * \par Typical use case:
1974  * Register a callback function about the change of storage status.
1975  *
1976  * \par Method of function operation:
1977  * Adds the msg_storage_change_cb API to a callback function list.
1978  *
1979  * \par Sync (or) Async:
1980  * This is a Synchronous API.
1981  *
1982  * \par Important notes:
1983  *      This function MUST be called after Message handle is opened.
1984  *
1985  * \param input - handle is Message handle.
1986  * \param input - cb is a function to be called.
1987  * \param input - user_param is a pointer to user data.
1988  *
1989  * \return Return Type (int(msg_error_t)) \n
1990  * - MSG_SUCCESS                                                        Success in operation.
1991  * - MSG_ERR_MSGHANDLE_NOT_CONNECTED    Message handle is not connected.
1992  * - MSG_ERR_MEMORY_ERROR                               Memory is error.
1993  *
1994  * \par Prospective clients:
1995  * External/Native Apps using Messaging Services.
1996  *
1997  * \par Related functions:
1998  * None
1999  *
2000  * \par Known issues/bugs:
2001  * None
2002  *
2003  * \par Sample code:
2004  * \code
2005  * ...
2006  *
2007  * int err = MSG_SUCCESS;
2008  *
2009  * err = msg_reg_storage_change_callback(msgHandle, &storageCB, NULL);
2010  * if (err != MSG_SUCCESS)
2011  * {
2012  * ...
2013  * }
2014  * return;
2015  * }
2016  *
2017  * void storageCB(msg_handle_t handle, msg_thread_id_t threadId, msg_message_id_t msgId, void *user_param)
2018  * {
2019  *      ...
2020  * }
2021  * ...
2022  * \endcode
2023  */
2024 /*================================================================================================*/
2025 int msg_reg_storage_change_callback(msg_handle_t handle, msg_storage_change_cb cb, void *user_param);
2026
2027
2028 /**
2029
2030  * \par Description:
2031  * Gets the report status information of message.
2032  *
2033  * \par Purpose:
2034  * This API is used to get the report status information of specified message.
2035  *
2036  * \par Typical use case:
2037  * Gets the report status information of specified message from the database.
2038  *
2039  * \par Method of function operation:
2040  * Sets up the database connection and Gets the report status information of specified message from the report table.
2041  *
2042  * \par Sync (or) Async:
2043  * This is a Synchronous API.
2044  *
2045  * \par Important notes:
2046  * - None
2047  *
2048  * \param input - handle is Message handle.
2049  * \param input - msg_id is the ID of the message.
2050  * \param output - report_status is a pointer to a MSG_REPORT_STATUS_INFO_S structure.
2051  *
2052  * \return Return Type (int(msg_error_t)) \n
2053  * - MSG_SUCCESS        - Success in operation.
2054  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
2055  * - MSG_ERR_STORAGE_ERROR - Storage is error.
2056  *
2057  * \par Prospective clients:
2058  * External/Native Apps using Messaging Services.
2059  *
2060  * \par Related functions:
2061  * None
2062  *
2063  * \par Known issues/bugs:
2064  * None
2065  *
2066  * \par Sample code:
2067  * \code
2068  * ...
2069  *
2070  * msg_handle_t msgHandle = NULL;
2071  * MSG_REPORT_STATUS_INFO_S reportStatus;
2072  *
2073  * ...
2074  *
2075  * err = msg_open_msg_handle(&msgHandle);
2076  *
2077  * ...
2078  *
2079  * err = msg_get_report_status(msgHandle, msgID, &reportStatus)
2080 * if( err != MSG_SUCCESS )
2081  * {
2082  *      printf("err [%d]", err);
2083  *      return err;
2084  * }
2085  *
2086  * ...
2087  * \endcode
2088  */
2089 /*================================================================================================*/
2090 int msg_get_report_status(msg_handle_t handle, msg_message_id_t msg_id, msg_struct_list_s *report_list);
2091
2092 int msg_get_address_list(msg_handle_t handle, msg_thread_id_t thread_id, msg_struct_list_s *msg_address_list);
2093
2094
2095 int msg_get_thread_id_by_address(msg_handle_t handle, msg_struct_list_s *msg_address_list, msg_thread_id_t *thread_id);
2096
2097
2098 int msg_get_thread(msg_handle_t handle, msg_thread_id_t thread_id, msg_struct_t msg_thread);
2099
2100
2101 int msg_get_message_list(msg_handle_t handle, msg_folder_id_t folder_id, msg_thread_id_t thread_id, msg_message_type_t msg_type, msg_storage_id_t storage_id, msg_struct_list_s *msg_list);
2102
2103
2104 int msg_add_push_event(msg_handle_t handle, const msg_struct_t push_event);
2105
2106 int msg_delete_push_event(msg_handle_t handle, const msg_struct_t push_event);
2107
2108 int msg_update_push_event(msg_handle_t handle, const msg_struct_t src_event, const msg_struct_t dst_event);
2109
2110 int msg_delete_msgs_by_list(msg_handle_t handle, msg_id_list_s *msg_id_list);
2111 /**
2112  *      @}
2113  */
2114
2115 #ifdef __cplusplus
2116 }
2117 #endif
2118
2119 #endif // MAPI_STORAGE_H
2120