include/mapi/msg_storage.h

   1 /*
   2 * Copyright 2012  Samsung Electronics Co., Ltd
   3 *
   4 * Licensed under the Flora License, Version 1.0 (the "License");
   5 * you may not use this file except in compliance with the License.
   6 * You may obtain a copy of the License at
   7 *
   8 *    http://www.tizenopensource.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
 917 /**
 918
 919  * \par Description:
 920  * Returns the common information list of messages with selected folder id.
 921  *
 922  * \par Purpose:
 923  * This API is used to get the common information list of messages with selected folder id from database.
 924  *
 925  * \par Typical use case:
 926  * Get the common information from the specified folder from database.
 927  *
 928  * \par Method of function operation:
 929  * Sets up the database connection and queries the common information based on selected folder id from the message and folder tables.
 930  *
 931  * \par Sync (or) Async:
 932  * This is a Synchronous API.
 933  *
 934  * \par Important notes:
 935  * - The memory for a message will be allocated in this function.
 936  * - Applications need to call msg_release_folder_view_list to free the memory.
 937  * - However, if this function is failed, the memory for the message is NOT allocated in this function.
 938  *
 939  * \param input - handle is Message handle.
 940  * \param input - folder_id is the ID of the folder to be returned.
 941  * \param input - sort_rule indicates a sort type and sort order for querying messages.
 942  * \param output - msg_folder_view_list is a pointer to an MSG_FOLDER_VIEW_LIST_S structure.
 943  *
 944  * \return Return Type (int(msg_error_t)) \n
 945  * - MSG_SUCCESS        - Success in operation.
 946  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
 947  * - MSG_ERR_STORAGE_ERROR - Storage is error.
 948  *
 949  * \par Prospective clients:
 950  * External/Native Apps using Messaging Services.
 951  *
 952  * \par Related functions:
 953  * - None
 954  *
 955  * \par Known issues/bugs:
 956  * None
 957  *
 958  * \par Sample code:
 959  * \code
 960  * ...
 961  *
 962  * msg_handle_t msgHandle = NULL;
 963  *
 964  * ...
 965  * MSG_FOLDER_VIEW_LIST_S folderViewList;
 966  * ...
 967  * err = msg_get_folder_view_list(hMsgHandle, 0, NULL, &folderViewList);
 968  * if( err != MSG_SUCCESS )
 969  * {
 970  *      printf("err [%d]", err);
 971  *      return err;
 972  * }
 973  *
 974  * ...
 975  * \endcode
 976  */
 977 /*================================================================================================*/
 978 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);
 979
 980
 981 /**
 982
 983  * \par Description:
 984  * Returns the information of all peers to whom messages have been sent or recieved.
 985  *
 986  * \par Purpose:
 987  * This API is used to get the information of all peers to whom messages have been sent or recieved.
 988  *
 989  * \par Typical use case:
 990  * Get the common information from the specified folder from database.
 991  *
 992  * \par Method of function operation:
 993  * Frees the memory occupied by MSG_FOLDER_VIEW_LIST_S object and its members.
 994  *
 995  * \par Sync (or) Async:
 996  * This is a Synchronous API.
 997  *
 998  * \par Important notes:
 999  * - The memory for a list will be allocated in this function.
1000  * - Applications need to call msg_release_thread_view_list to free the memory.
1001  * - However, if this function is failed, the memory for a list is NOT allocated in this function.
1002  *
1003  * \param input - handle is Message handle.
1004  * \param input - sort_rule indicates a sort type and sort order for querying messages.
1005  * \param output - msg_thread_view_list is a pointer to an msg_struct_list_s structure.
1006  *
1007  * \return Return Type (int(msg_error_t)) \n
1008  * - MSG_SUCCESS        - Success in operation.
1009  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1010  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1011  *
1012  * \par Prospective clients:
1013  * External/Native Apps using Messaging Services.
1014  *
1015  * \par Related functions:
1016  * None
1017  *
1018  * \par Known issues/bugs:
1019  * None
1020  *
1021  * \par Sample code:
1022  * \code
1023  * ...
1024  *
1025  * msg_handle_t msgHandle = NULL;
1026  *
1027  * ...
1028  * msg_struct_list_s threadViewList;
1029  * ...
1030  * err = msg_get_thread_view_list(hMsgHandle, NULL, &threadViewList);
1031  * ...
1032  * msg_release_thread_view_list(&threadViewList);
1033  * if( err != MSG_SUCCESS )
1034  * {
1035  *      printf("err [%d]", err);
1036  *      return err;
1037  * }
1038  * \endcode
1039  */
1040 /*================================================================================================*/
1041 int msg_get_thread_view_list(msg_handle_t handle, const msg_struct_t sort_rule, msg_struct_list_s *msg_thread_view_list);
1042
1043
1044 /**
1045
1046  * \par Description:
1047  * Returns the common information list of messages with selected thread_id.
1048  *
1049  * \par Purpose:
1050  * This API is used to get the common information list of messages with selected thread_id.
1051  *
1052  * \par Typical use case:
1053  * Gets the common information list of messages with the selected thread id from the database.
1054  *
1055  * \par Method of function operation:
1056  * Connects to the database and queries the common infomation of  list messages with the provided thread id.
1057  *
1058  * \par Sync (or) Async:
1059  * This is a Synchronous API.
1060  *
1061  * \par Important notes:
1062  * - The memory for a list will be allocated in this function.
1063  * - Applications need to call msg_release_conversation_view_list to free the memory.
1064  * - However, if this function is failed, the memory for a list is NOT allocated in this function.
1065  *
1066  * \param input - hMsgHandle is Message handle.
1067  * \param input - thread_id is the ID of the thread to be returned.
1068  * \param output - msg_conv_view_list is a pointer to an MSG_CONV_VIEW_LIST_S structure.
1069  *
1070  * \return Return Type (int(msg_error_t)) \n
1071  * - MSG_SUCCESS        - Success in operation.
1072  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1073  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1074  *
1075  * \par Prospective clients:
1076  * External/Native Apps using Messaging Services.
1077  *
1078  * \par Related functions:
1079  * - None
1080  *
1081  * \par Known issues/bugs:
1082  * None
1083  *
1084  * \par Sample code:
1085  * \code
1086  * ...
1087  *
1088  * msg_handle_t msgHandle = NULL;
1089  * msg_error_t err = MSG_SUCCESS;
1090  * ...
1091  * MSG_CONV_VIEW_LIST_S convViewList;
1092  * ...
1093  * err = msg_get_conversation_view_list(hMsgHandle, ThreadId, &convViewList);
1094  * if( err != MSG_SUCCESS )
1095  * {
1096  *      printf("err [%d]", err);
1097  *      return err;
1098  * }
1099  * msg_release_conversation_view_list(&convViewList);
1100  * ...
1101  * \endcode
1102  */
1103 /*================================================================================================*/
1104 int msg_get_conversation_view_list(msg_handle_t handle, msg_thread_id_t thread_id, msg_struct_list_s *msg_conv_view_list);
1105
1106
1107 /**
1108
1109  * \par Description:
1110  * Deletes all the Messages Sent/Received from the selected list.
1111  *
1112  * \par Purpose:
1113  * This API is used to delete all the Messages Sent/Received from the selected list.
1114  *
1115  * \par Typical use case:
1116  * Deletes all messages sent/received from the selected list.
1117  *
1118  * \par Method of function operation:
1119  * Sets up the database connection and deletes all messages sent/received from a selected list.
1120  *
1121  * \par Sync (or) Async:
1122  * This is a Synchronous API.
1123  *
1124  * \par Important notes:
1125  * - If addr_info is NULL, nothing happens.
1126  *
1127  * \param input - handle is Message handle.
1128  * \param input - thread_id is the ID of the thread to be deleted.
1129  *
1130  * \return Return Type (int(msg_error_t)) \n
1131  * - MSG_SUCCESS        - Success in operation.
1132  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1133  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1134  *
1135  * \par Prospective clients:
1136  * External/Native Apps using Messaging Services.
1137  *
1138  * \par Related functions:
1139  * None
1140  *
1141  * \par Known issues/bugs:
1142  * None
1143  *
1144  * \par Sample code:
1145  * \code
1146  * ...
1147  *
1148  * msg_handle_t msgHandle = NULL;
1149  * MSG_SYNCML_MESSAGE_S syncMLMsg;
1150  * MSG_SENDINGOPT_S sendingOpt = {0};
1151  *
1152  * ...
1153  *
1154  * err = msg_open_msg_handle(&msgHandle);
1155  *
1156  * ...
1157  *
1158  * err = msg_delete_thread_message_list(hMsgHandle, 0);
1159  * if( err != MSG_SUCCESS )
1160  * {
1161  *      printf("err [%d]", err);
1162  *      return err;
1163  * }
1164  * ...
1165  * \endcode
1166  */
1167 /*================================================================================================*/
1168 int msg_delete_thread_message_list(msg_handle_t handle, msg_thread_id_t thread_id);
1169
1170
1171 /**
1172
1173  * \par Description:
1174  * Adds a new folder.
1175  *
1176  * \par Purpose:
1177  * This API is used to add a new folder.
1178  *
1179  * \par Typical use case:
1180  * Adds a new folder with the specified folder info
1181  *
1182  * \par Method of function operation:
1183  * Sets up the database connection and add a new folder to the folder table.
1184  *
1185  * \par Sync (or) Async:
1186  * This is a Synchronous API.
1187  *
1188  * \par Important notes:
1189  * - None.
1190  *
1191  * \param - handle is Message handle.
1192  * \param - folder_info is a pointer to an MSG_FOLDER_INFO_S structure.
1193  *
1194  * \return Return Type (int(msg_error_t)) \n
1195  * - MSG_SUCCESS        - Success in operation.
1196  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1197  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1198  *
1199  * \par Prospective clients:
1200  * External/Native Apps using Messaging Services.
1201  *
1202  * \par Related functions:
1203  * None
1204  *
1205  * \par Known issues/bugs:
1206  * None
1207  *
1208  * \par Sample code:
1209  * \code
1210  * ...
1211  *
1212  * msg_handle_t msgHandle = NULL;
1213  *  Make Folder
1214  * MSG_FOLDER_INFO_S folderInfo;
1215  * ...
1216  * err = msg_open_msg_handle(&msgHandle);
1217  *
1218  * folderInfo.folderId = 1;
1219  * folderInfo.folderType = MSG_FOLDER_TYPE_USER_DEF;
1220  * ...
1221  *
1222  * err = msg_add_folder(hMsgHandle, &folderInfo);
1223  * if( err != MSG_SUCCESS )
1224  * {
1225  *      printf("err [%d]", err);
1226  *      return err;
1227  * }
1228  * ...
1229  * \endcode
1230  */
1231 /*================================================================================================*/
1232 int msg_add_folder(msg_handle_t handle, const msg_struct_t folder_info);
1233
1234
1235 /**
1236
1237  * \par Description:
1238  * Updates the folder info.
1239  *
1240  * \par Purpose:
1241  * This API is used to add a new folder.
1242  *
1243  * \par Typical use case:
1244  * Adds a new folder with the specified folder info
1245  *
1246  * \par Method of function operation:
1247  * Sets up the database connection and add a new folder to the folder table.
1248  *
1249  * \par Sync (or) Async:
1250  * This is a Synchronous API.
1251  *
1252  * \par Important notes:
1253  * - None.
1254  *
1255  * \param - handle is Message handle.
1256  * \param - folder_info is a pointer to an MSG_FOLDER_INFO_S structure.
1257  *
1258  * \return Return Type (int(msg_error_t)) \n
1259  * - MSG_SUCCESS        - Success in operation.
1260  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1261  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1262  *
1263  * \par Prospective clients:
1264  * External/Native Apps using Messaging Services.
1265  *
1266  * \par Related functions:
1267  * None
1268  *
1269  * \par Known issues/bugs:
1270  * None
1271  *
1272  * \par Sample code:
1273  * \code
1274  * ...
1275  *
1276  * msg_handle_t msgHandle = NULL;
1277  *  Make Folder
1278  * MSG_FOLDER_INFO_S folderInfo;
1279  * ...
1280  * err = msg_open_msg_handle(&msgHandle);
1281  *
1282  * folderInfo.folderId = 2;
1283  * folderInfo.folderType = MSG_FOLDER_TYPE_USER_DEF;
1284  * ...
1285  * err = msg_update_folder(msgHandle, &folderInfo);
1286  * if( err != MSG_SUCCESS )
1287  * {
1288  *      printf("err [%d]", err);
1289  *      return err;
1290  * }
1291  * ...
1292  * \endcode
1293  */
1294 /*================================================================================================*/
1295 int msg_update_folder(msg_handle_t handle, const msg_struct_t folder_info);
1296
1297
1298 /**
1299
1300  * \par Description:
1301  * Deletes an exisiting folder.
1302  *
1303  * \par Purpose:
1304  * This API is used to delete an existing folder.
1305  *
1306  * \par Typical use case:
1307  * Deletes an existing folder.
1308  *
1309  * \par Method of function operation:
1310  * Sets up the database connection and deletes an existing folder to the folder table.
1311  *
1312  * \par Sync (or) Async:
1313  * This is a Synchronous API.
1314  *
1315  * \par Important notes:
1316  * - None.
1317  *
1318  * \param input - handle is Message handle.
1319  * \param input - folder_id is the ID of the folder to be deleted.
1320  *
1321  * \return Return Type (int(msg_error_t)) \n
1322  * - MSG_SUCCESS        - Success in operation.
1323  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1324  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1325  *
1326  * \par Prospective clients:
1327  * External/Native Apps using Messaging Services.
1328  *
1329  * \par Related functions:
1330  * None
1331  *
1332  * \par Known issues/bugs:
1333  * None
1334  *
1335  * \par Sample code:
1336  * \code
1337  * ...
1338  *
1339  * msg_handle_t msgHandle = NULL;
1340  * err = msg_open_msg_handle(&msgHandle);
1341  *
1342  * ...
1343  * err = msg_delete_folder(hMsgHandle, MSG_INBOX_ID);
1344  * if( err != MSG_SUCCESS )
1345  * {
1346  *      printf("err [%d]", err);
1347  *      return err;
1348  * }
1349  * ...
1350  * \endcode
1351  */
1352 /*================================================================================================*/
1353 int msg_delete_folder(msg_handle_t handle, msg_folder_id_t folder_id);
1354
1355
1356 /**
1357
1358  * \par Description:
1359  * Returns the information list of folders.
1360  *
1361  * \par Purpose:
1362  * This API is used to get the information list of folders.
1363  *
1364  * \par Typical use case:
1365  * Gets the folder list information.
1366  *
1367  * \par Method of function operation:
1368  * Sets up the database connection and queries for the folder list information.
1369  *
1370  * \par Sync (or) Async:
1371  * This is a Synchronous API.
1372  *
1373  * \par Important notes:
1374  * - None.
1375  *
1376  * \param input - handle is Message handle.
1377  * \param output - folder_list is a pointer to an msg_struct_list_s structure.
1378  *
1379  * \return Return Type (int(msg_error_t)) \n
1380  * - MSG_SUCCESS        - Success in operation.
1381  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
1382  * - MSG_ERR_STORAGE_ERROR - Storage is error.
1383  *
1384  * \par Prospective clients:
1385  * External/Native Apps using Messaging Services.
1386  *
1387  * \par Related functions:
1388  * None
1389  *
1390  * \par Known issues/bugs:
1391  * None
1392  *
1393  * \par Sample code:
1394  * \code
1395  * ...
1396  *
1397  * msg_handle_t msgHandle = NULL;
1398  *  msg_struct_list_s folderList;
1399
1400  * err = msg_open_msg_handle(&msgHandle);
1401  *
1402  * ...
1403  * err = msg_get_folder_list(msgHandle, &folderList);
1404  * if( err != MSG_SUCCESS )
1405  * {
1406  *      printf("err [%d]", err);
1407  *      return err;
1408  * }
1409  * ...
1410  * msg_release_folder_list(&folderList);
1411  * \endcode
1412  */
1413 /*================================================================================================*/
1414 int msg_get_folder_list(msg_handle_t handle, msg_struct_list_s *folder_list);
1415
1416
1417 /**
1418
1419  * \par Description:
1420  * Creates the specified number of messages in database.
1421  *
1422  * \par Purpose:
1423  * This API is used to generate specified number of messages in the database
1424  *
1425  * \par Typical use case:
1426  * Generate large number of messages in the database.
1427  *
1428  * \par Method of function operation:
1429  * Creates the specified number of messages in database for specified message type in the specified folder
1430  *
1431  * \par Sync (or) Async:
1432  * This is a Synchronous API.
1433  *
1434  * \par Important notes:
1435  * - None
1436  *
1437  * \param input - handle is Message handle.
1438  * \param input - msg_type is one of enum _MSG_MESSAGE_TYPE_E.
1439  * \param input - folder_id is the folder for the test messages.
1440  * \param input - num_msg is the number of messages.
1441  *
1442  * \return Return Type (int(msg_error_t)) \n
1443  * - MSG_SUCCESS                                        Success in operation.
1444  * - MSG_ERR_INVALID_MSGHANDLE  Parameter is invalid.
1445  * - MSG_ERR_INVALID_FOLDER_ID  Storage is error.
1446  *
1447  * \par Prospective clients:
1448  * External/Native Apps using Messaging Services.
1449  *
1450  * \par Related functions:
1451  * None
1452  *
1453  * \par Known issues/bugs:
1454  * None
1455  *
1456  * \par Sample code:
1457  * \code
1458  * ...
1459  *
1460  * msg_handle_t msgHandle = NULL;
1461  *  msg_struct_list_s folderList;
1462
1463  * err = msg_open_msg_handle(&msgHandle);
1464  *
1465  * ...
1466  * err = msg_generate_message(msgHandle, MSG_TYPE_SMS, MSG_INBOX_ID, 100);
1467  * if( err != MSG_SUCCESS )
1468  * {
1469  *      printf("err [%d]", err);
1470  *      return err;
1471  * }
1472  * ...
1473  * \endcode
1474  */
1475 /*================================================================================================*/
1476 int msg_generate_message(msg_handle_t handle, msg_message_type_t msg_type, msg_folder_id_t folder_id, unsigned int num_msg);
1477 int msg_generate_sms(msg_handle_t handle, msg_folder_id_t folder_id, unsigned int num_msg) DEPRECATED;
1478
1479
1480 /**
1481
1482  * \par Description:
1483  * Returns the Message Data to be used by the Quick Panel.
1484  *
1485  * \par Purpose:
1486  * This API is used to get the Message Datato be used by the Quick Panel.
1487  *
1488  * \par Typical use case:
1489  * Quick panel needs the message information to show new message notification.
1490  *
1491  * \par Method of function operation:
1492  * Connects to database and queries for information needed by the quick panel.
1493  *
1494  * \par Sync (or) Async:
1495  * This is a Synchronous API.
1496  *
1497  * \par Important notes:
1498  * - None
1499  *
1500  * \param input - handle is Message handle.
1501  * \param input - type is the type of message that Quick Panel need.
1502  * \param output - msg is a pointer to an msg_message_t structure.
1503  *
1504  * \return Return Type (int(msg_error_t)) \n
1505  * - MSG_SUCCESS                                        Success in operation.
1506  * - MSG_ERR_INVALID_MSGHANDLE  Parameter is invalid.
1507  * - MSG_ERR_INVALID_FOLDER_ID  Storage is error.
1508  *
1509  * \par Prospective clients:
1510  * External/Native Apps using Messaging Services.
1511  *
1512  * \par Related functions:
1513  * None
1514  *
1515  * \par Known issues/bugs:
1516  * None
1517  *
1518  * \par Sample code:
1519  * \code
1520  * ...
1521  *
1522  * msg_handle_t msgHandle = NULL;
1523  * msg_message_t msgInfo;
1524
1525  * err = msg_open_msg_handle(&msgHandle);
1526  *
1527  * ...
1528  * err = msg_get_quick_panel_data(msgHandle, MSG_QUICKPANEL_SMS, msgInfo);
1529  * if( err != MSG_SUCCESS )
1530  * {
1531  *      printf("err [%d]", err);
1532  *      return err;
1533  * }
1534  * ...
1535  * \endcode
1536  */
1537 /*================================================================================================*/
1538 int msg_get_quick_panel_data(msg_handle_t handle, msg_quickpanel_type_t type, msg_struct_t msg);
1539
1540
1541 /**
1542
1543  * \par Description:
1544  * Resets the Messaging database.
1545  *
1546  * \par Purpose:
1547  * This API is used to reset the messaging database.
1548  *
1549  * \par Typical use case:
1550  * Completely delete the messaging database.
1551  *
1552  * \par Method of function operation:
1553  * Connects to database and deletes all the messaging tables.
1554  *
1555  * \par Sync (or) Async:
1556  * This is a Synchronous API.
1557  *
1558  * \par Important notes:
1559  * - None
1560  *
1561  * \param input - handle is Message handle.
1562  *
1563  * \return Return Type (int(msg_error_t)) \n
1564  * - MSG_SUCCESS                                        Success in operation.
1565  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1566  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1567  *
1568  * \par Prospective clients:
1569  * External/Native Apps using Messaging Services.
1570  *
1571  * \par Related functions:
1572  * None
1573  *
1574  * \par Known issues/bugs:
1575  * None
1576  *
1577  * \par Sample code:
1578  * \code
1579  * ...
1580  *
1581  * msg_handle_t msgHandle = NULL;
1582  * msg_error_t err = MSG_SUCCESS;
1583  * err = msg_open_msg_handle(&msgHandle);
1584  *
1585  * ...
1586  * err = msg_reset_database(msgHandle);
1587  * if (err != MSG_SUCCESS)
1588  *{
1589  *      printf("err [%d]", err);
1590  *      return err;
1591  * }
1592  * ...
1593  * \endcode
1594  */
1595 /*================================================================================================*/
1596 int msg_reset_database(msg_handle_t handle);
1597
1598
1599 /**
1600
1601  * \par Description:
1602  * Returns the total size used for message contents.
1603  *
1604  * \par Purpose:
1605  * This API is used to get the total size used for message contents.
1606  *
1607  * \par Typical use case:
1608  * To get the total space used by message contents.
1609  *
1610  * \par Method of function operation:
1611  * Uses linux system calls to query the space used by message contents.
1612  *
1613  * \par Sync (or) Async:
1614  * This is a Synchronous API.
1615  *
1616  * \par Important notes:
1617  * - None
1618  *
1619  * \param input - handle is Message handle.
1620  * \param output -      memsize is a pointer to the size.
1621  *
1622  * \return Return Type (int(msg_error_t)) \n
1623  * - MSG_SUCCESS                                        Success in operation.
1624  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1625  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1626  *
1627  * \par Prospective clients:
1628  * External/Native Apps using Messaging Services.
1629  *
1630  * \par Related functions:
1631  * None
1632  *
1633  * \par Known issues/bugs:
1634  * None
1635  *
1636  * \par Sample code:
1637  * \code
1638  * ...
1639  *
1640  * msg_handle_t msgHandle = NULL;
1641  * int memsize = 0;
1642  * err = msg_open_msg_handle(&msgHandle);
1643  *
1644  * ...
1645  * err = msg_get_mem_size(msgHandle, &memsize);
1646  * if( err != MSG_SUCCESS )
1647  * {
1648  *      printf("err [%d]", err);
1649  *      return err;
1650  * }
1651  * ...
1652  * \endcode
1653  */
1654 /*================================================================================================*/
1655 int msg_get_mem_size(msg_handle_t handle, unsigned int* memsize);
1656
1657 /**
1658
1659  * \par Description:
1660  * Backup messages to storage.
1661  *
1662  * \par Purpose:
1663  * This API is used to backup messages to storage.
1664  *
1665  * \par Typical use case:
1666  * Backup messages to storage.
1667  *
1668  * \par Method of function operation:
1669  * Reads all the messages from Messaging database and writes to storage in V-Message format
1670  *
1671  * \par Sync (or) Async:
1672  * This is a Synchronous API.
1673  *
1674  * \par Important notes:
1675  * None
1676  *
1677  * \param input - msg_handle_t  handle is Message handle.
1678  *
1679  * \return Return Type int (msg_error_t) \n
1680  * - MSG_SUCCESS                                        Success in operation.
1681  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1682  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1683  *
1684  * \par Prospective clients:
1685  * External/Native Apps using Messaging Services.
1686  *
1687  * \par Related functions:
1688  * None
1689  *
1690  * \par Known issues/bugs:
1691  * None
1692  *
1693  * \par Sample code:
1694  * \code
1695  * ...
1696  *
1697  * msg_handle_t msgHandle = NULL;
1698  * msg_error_t err;
1699  *
1700  * ...
1701  * err = msg_backup_message(&msgHandle);
1702  * ...
1703  * \endcode
1704  */
1705 /*================================================================================================*/
1706 int msg_backup_message(msg_handle_t handle);
1707
1708
1709 /**
1710
1711  * \par Description:
1712  * Restore messages from backed up messages.
1713  *
1714  * \par Purpose:
1715  * This API is used to restore messages from backed up messages.
1716  *
1717  * \par Typical use case:
1718  * Restore messages from previously backed up messages.
1719  *
1720  * \par Method of function operation:
1721  * Reads the previously backup up messages and restores the database.
1722  *
1723  * \par Sync (or) Async:
1724  * This is a Synchronous API.
1725  *
1726  * \par Important notes:
1727  * None
1728  *
1729  * \param input - msg_handle_t  handle is Message handle.
1730  *
1731  * \return Return Type int (msg_error_t) \n
1732  * - MSG_SUCCESS                                        Success in operation.
1733  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1734  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1735  *
1736  * \par Prospective clients:
1737  * External/Native Apps using Messaging Services.
1738  *
1739  * \par Related functions:
1740  * None
1741  *
1742  * \par Known issues/bugs:
1743  * None
1744  *
1745  * \par Sample code:
1746  * \code
1747  * ...
1748  *
1749  * msg_handle_t msgHandle = NULL;
1750  * msg_error_t err;
1751   * ...
1752  * err = msg_restore_message(&msgHandle);
1753  * ...
1754  * \endcode
1755  */
1756 /*================================================================================================*/
1757 int msg_restore_message(msg_handle_t handle);
1758
1759
1760 /**
1761
1762  * \par Description:
1763  * Search messages or addresses which including a string that applcation want to find.
1764  *
1765  * \par Purpose:
1766  * This API is used to search messages or addresses from storage.
1767  *
1768  * \par Typical use case:
1769  * Search messages or addresses from storage.
1770  *
1771  * \par Method of function operation:
1772  * search messages or addresses from storage.
1773  *
1774  * \par Sync (or) Async:
1775  * This is a Synchronous API.
1776  *
1777  * \par Important notes:
1778  * None
1779  *
1780  * \param input - msg_handle_t  handle is Message handle.
1781  * \param input - search_string is the string to search.
1782  * \param output - msg_thread_view_list is a pointer to an msg_struct_list_s structure.
1783  *
1784  * \return Return Type int (msg_error_t) \n
1785  * - MSG_SUCCESS                                        Success in operation.
1786  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1787  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1788  *
1789  * \par Prospective clients:
1790  * External/Native Apps using Messaging Services.
1791  *
1792  * \par Related functions:
1793  * None
1794  *
1795  * \par Known issues/bugs:
1796  * None
1797  *
1798  * \par Sample code:
1799  * \code
1800  * ...
1801  *
1802  * msg_handle_t msgHandle = NULL;
1803  * msg_error_t err = MSG_SUCCESS;
1804  * ...
1805  * char* search_string = "hello";
1806  * msg_struct_list_s threadViewList;
1807  * ...
1808  * err = msg_search_message_for_thread_view(&msgHandle, search_string, &threadViewList);
1809  *
1810  * if( err != MSG_SUCCESS )
1811  * {
1812  *      printf("err [%d]", err);
1813  *      return err;
1814  * }
1815  * ...
1816  * \endcode
1817  */
1818 /*================================================================================================*/
1819 int msg_search_message_for_thread_view(msg_handle_t handle, const char *search_string, msg_struct_list_s *msg_thread_view_list);
1820
1821
1822 /**
1823
1824  * \par Description:
1825  * Search messages or addresses which including a string that applcation want to find.
1826  *
1827  * \par Purpose:
1828  * This API is used to search messages or addresses from storage.
1829  *
1830  * \par Typical use case:
1831  * Search messages or addresses from storage.
1832  *
1833  * \par Method of function operation:
1834  * search messages or addresses from storage.
1835  *
1836  * \par Sync (or) Async:
1837  * This is a Synchronous API.
1838  *
1839  * \par Important notes:
1840  * None
1841  *
1842  * \param input - msg_handle_t  handle is Message handle.
1843  * \param input - search_string is the string to search.
1844  * \param input - offset is the offset of the search result.
1845  * \param input - limit is the limit of the search result.
1846  * \param output - msg_list is a pointer to an msg_struct_list_s structure.
1847  *
1848  * \return Return Type int (msg_error_t) \n
1849  * - MSG_SUCCESS                                        Success in operation.
1850  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1851  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1852  *
1853  * \par Prospective clients:
1854  * External/Native Apps using Messaging Services.
1855  *
1856  * \par Related functions:
1857  * None
1858  *
1859  * \par Known issues/bugs:
1860  * None
1861  *
1862  * \par Sample code:
1863  * \code
1864  * ...
1865  *
1866  * msg_handle_t msgHandle = NULL;
1867  * msg_error_t err = MSG_SUCCESS;
1868  * ...
1869  * msg_struct_list_s msg_list;
1870  * int offset = 0;
1871  * int limit = 10;
1872  *
1873  * MSG_SEARCH_CONDITION_S searchCon;
1874  *
1875  * searchCon.msgType = MSG_TYPE_SMS;
1876  * searchCon.folderId = MSG_INBOX_ID;
1877  * searchCon.pSearchVal = "keyString";
1878  * searchCon.pAddressVal = "01000000000";
1879  *
1880  * ...
1881  * err = msg_search_message(hMsgHandle, &searchCon, offset, limit, &msgList);
1882  *
1883  * if( err != MSG_SUCCESS )
1884  * {
1885  *      printf("err [%d]", err);
1886  *      return err;
1887  * }
1888  * ...
1889  * \endcode
1890  */
1891 /*================================================================================================*/
1892 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);
1893
1894 /**
1895
1896  * \par Description:
1897  * Get reject message list that application wants to find by phone number.
1898  *
1899  * \par Purpose:
1900  * This API is used to get reject message list from storage.
1901  *
1902  * \par Typical use case:
1903  * Get reject message list from storage.
1904  *
1905  * \par Method of function operation:
1906  * Get reject message list from storage.
1907  *
1908  * \par Sync (or) Async:
1909  * This is a Synchronous API.
1910  *
1911  * \par Important notes:
1912  * None
1913  *
1914  * \param input - msg_handle_t  handle is Message handle.
1915  * \param input - phone_num is the string of phone number to find.
1916  * \param output - msg_reject_msg_list is a pointer to an msg_struct_list_s structure.
1917
1918  * \return Return Type int (msg_error_t) \n
1919  * - MSG_SUCCESS                                        Success in operation.
1920  * - MSG_ERR_INVALID_PARAMETER  Parameter is invalid.
1921  * - MSG_ERR_STORAGE_ERROR              Storage is error.
1922  *
1923  * \par Prospective clients:
1924  * External/Native Apps using Messaging Services.
1925  *
1926  * \par Related functions:
1927  * None
1928  *
1929  * \par Known issues/bugs:
1930  * None
1931  *
1932  * \par Sample code:
1933  * \code
1934  * ...
1935  *
1936  * msg_handle_t msgHandle = NULL;
1937  * msg_error_t err = MSG_SUCCESS;
1938  * ...
1939  * char* phone_num = "01030016057";
1940  * msg_struct_list_s rejectMsgList;
1941  * ...
1942  * err = msg_get_reject_msg_list(hMsgHandle, phone_num, &rejectMsgList);
1943  *
1944  * if( err != MSG_SUCCESS )
1945  * {
1946  *      printf("err [%d]", err);
1947  *      return err;
1948  * }
1949  * ...
1950  * \endcode
1951  */
1952 /*================================================================================================*/
1953 int msg_get_reject_msg_list(msg_handle_t handle, const char* phone_num, msg_struct_list_s *msg_reject_msg_list);
1954
1955
1956 /**
1957
1958  * \par Description:
1959  * Registers a callback function about the change of storage status to Message handle.
1960  *
1961  * \par Purpose:
1962  * This API is used to register a callback function about the change of storage status "msg_storage_change_cb" to Message handle.
1963  *
1964  * \par Typical use case:
1965  * Register a callback function about the change of storage status.
1966  *
1967  * \par Method of function operation:
1968  * Adds the msg_storage_change_cb API to a callback function list.
1969  *
1970  * \par Sync (or) Async:
1971  * This is a Synchronous API.
1972  *
1973  * \par Important notes:
1974  *      This function MUST be called after Message handle is opened.
1975  *
1976  * \param input - handle is Message handle.
1977  * \param input - cb is a function to be called.
1978  * \param input - user_param is a pointer to user data.
1979  *
1980  * \return Return Type (int(msg_error_t)) \n
1981  * - MSG_SUCCESS                                                        Success in operation.
1982  * - MSG_ERR_MSGHANDLE_NOT_CONNECTED    Message handle is not connected.
1983  * - MSG_ERR_MEMORY_ERROR                               Memory is error.
1984  *
1985  * \par Prospective clients:
1986  * External/Native Apps using Messaging Services.
1987  *
1988  * \par Related functions:
1989  * None
1990  *
1991  * \par Known issues/bugs:
1992  * None
1993  *
1994  * \par Sample code:
1995  * \code
1996  * ...
1997  *
1998  * int err = MSG_SUCCESS;
1999  *
2000  * err = msg_reg_storage_change_callback(msgHandle, &storageCB, NULL);
2001  * if (err != MSG_SUCCESS)
2002  * {
2003  * ...
2004  * }
2005  * return;
2006  * }
2007  *
2008  * void storageCB(msg_handle_t handle, msg_thread_id_t threadId, msg_message_id_t msgId, void *user_param)
2009  * {
2010  *      ...
2011  * }
2012  * ...
2013  * \endcode
2014  */
2015 /*================================================================================================*/
2016 int msg_reg_storage_change_callback(msg_handle_t handle, msg_storage_change_cb cb, void *user_param);
2017
2018
2019 /**
2020
2021  * \par Description:
2022  * Gets the report status information of message.
2023  *
2024  * \par Purpose:
2025  * This API is used to get the report status information of specified message.
2026  *
2027  * \par Typical use case:
2028  * Gets the report status information of specified message from the database.
2029  *
2030  * \par Method of function operation:
2031  * Sets up the database connection and Gets the report status information of specified message from the report table.
2032  *
2033  * \par Sync (or) Async:
2034  * This is a Synchronous API.
2035  *
2036  * \par Important notes:
2037  * - None
2038  *
2039  * \param input - handle is Message handle.
2040  * \param input - msg_id is the ID of the message.
2041  * \param output - report_status is a pointer to a MSG_REPORT_STATUS_INFO_S structure.
2042  *
2043  * \return Return Type (int(msg_error_t)) \n
2044  * - MSG_SUCCESS        - Success in operation.
2045  * - MSG_ERR_INVALID_PARAMETER - Parameter is invalid.
2046  * - MSG_ERR_STORAGE_ERROR - Storage is error.
2047  *
2048  * \par Prospective clients:
2049  * External/Native Apps using Messaging Services.
2050  *
2051  * \par Related functions:
2052  * None
2053  *
2054  * \par Known issues/bugs:
2055  * None
2056  *
2057  * \par Sample code:
2058  * \code
2059  * ...
2060  *
2061  * msg_handle_t msgHandle = NULL;
2062  * MSG_REPORT_STATUS_INFO_S reportStatus;
2063  *
2064  * ...
2065  *
2066  * err = msg_open_msg_handle(&msgHandle);
2067  *
2068  * ...
2069  *
2070  * err = msg_get_report_status(msgHandle, msgID, &reportStatus)
2071 * if( err != MSG_SUCCESS )
2072  * {
2073  *      printf("err [%d]", err);
2074  *      return err;
2075  * }
2076  *
2077  * ...
2078  * \endcode
2079  */
2080 /*================================================================================================*/
2081 int msg_get_report_status(msg_handle_t handle, msg_message_id_t msg_id, msg_struct_t report_status);
2082
2083
2084
2085
2086 int msg_get_address_list(msg_handle_t handle, msg_thread_id_t thread_id, msg_struct_list_s *msg_address_list);
2087
2088
2089 int msg_get_thread_id_by_address(msg_handle_t handle, msg_struct_list_s *msg_address_list, msg_thread_id_t *thread_id);
2090
2091
2092 int msg_get_thread(msg_handle_t handle, msg_thread_id_t thread_id, msg_struct_t msg_thread);
2093
2094
2095 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);
2096
2097 /**
2098  *      @}
2099  */
2100
2101 #ifdef __cplusplus
2102 }
2103 #endif
2104
2105 #endif // MAPI_STORAGE_H
2106