include/mapi/MapiMessage.h

   1 /*
   2 *
   3 * Copyright (c) 2000-2012 Samsung Electronics Co., Ltd. All Rights Reserved.
   4 *
   5 * This file is part of msg-service.
   6 *
   7 * Contact: Jaeyun Jeong <jyjeong@samsung.com>
   8 *          Sangkoo Kim <sangkoo.kim@samsung.com>
   9 *          Seunghwan Lee <sh.cat.lee@samsung.com>
  10 *          SoonMin Jung <sm0415.jung@samsung.com>
  11 *          Jae-Young Lee <jy4710.lee@samsung.com>
  12 *          KeeBum Kim <keebum.kim@samsung.com>
  13 *
  14 * PROPRIETARY/CONFIDENTIAL
  15 *
  16 * This software is the confidential and proprietary information of
  17 * SAMSUNG ELECTRONICS ("Confidential Information"). You shall not
  18 * disclose such Confidential Information and shall use it only in
  19 * accordance with the terms of the license agreement you entered
  20 * into with SAMSUNG ELECTRONICS.
  21 *
  22 * SAMSUNG make no representations or warranties about the suitability
  23 * of the software, either express or implied, including but not limited
  24 * to the implied warranties of merchantability, fitness for a particular
  25 * purpose, or non-infringement. SAMSUNG shall not be liable for any
  26 * damages suffered by licensee as a result of using, modifying or
  27 * distributing this software or its derivatives.
  28 *
  29 */
  30
  31 /**
  32  *      @file           MapiMessage.h
  33  *      @brief  Defines message data API of messaging framework
  34  *      @version        1.0
  35  */
  36
  37 #ifndef MAPI_MESSAGE_H
  38 #define MAPI_MESSAGE_H
  39
  40 /**
  41  *      @section                Introduction
  42  *      - Introduction : Overview on message data related API
  43  *      @section                Program
  44  *      - Program : message data related API Reference
  45  */
  46
  47 /*==================================================================================================
  48                                          INCLUDE FILES
  49 ==================================================================================================*/
  50
  51 #include "MsgTypes.h"
  52 #include "MsgMmsTypes.h"
  53
  54
  55 #ifdef __cplusplus
  56 extern "C"
  57 {
  58 #endif
  59
  60 /**
  61  *      @ingroup        MESSAGING_FRAMEWORK
  62  *      @defgroup       MESSAGING_DATA_API      Messaging Data API
  63  *      @{
  64  */
  65
  66 /*==================================================================================================
  67                                                                          FUNCTION PROTOTYPES
  68 ==================================================================================================*/
  69
  70 /**
  71
  72  * \par Description:
  73  * Allocate the memory for new message, which is used for composing SMS or MMS.
  74  *
  75  * \par Purpose:
  76  * This API is used to create Message object and should be called before any operation on the message object.
  77  *
  78  * \par Typical use case:
  79  * Before performing common operations on Messages such as Send, Save, Load, etc., this API should be called to create the message object.
  80  *
  81  * \par Method of function operation:
  82  * Creates the Message Object and initiaizes the members to default values.
  83  *
  84  * \par Sync (or) Async:
  85  * This is a Synchronous API.
  86  *
  87  * \par Important notes:
  88  * - The type msg_message_t represents message object and hides the details of message object.
  89  * - Memory for the Message abject need NOT be created by the called \n
  90  * - You can set or get the value of message object using the below APIs.
  91  * - You should release the memory using msg_release_message(), unless memory leaks.
  92  *
  93  * \param none.
  94  *
  95  * \return Return Type (msg_message_t) \n
  96  * - msg_message_t - valid message object is returned upon success \n
  97  * - NULL       - In case of error in allocation of message object \n
  98  *
  99  * \par Prospective clients:
 100  * External/Native Apps using Messaging Services.
 101  *
 102  * \par Related functions:
 103  * None
 104  *
 105  * \par Known issues/bugs:
 106  * None
 107  *
 108  * \par Sample code:
 109  * \code
 110  * ...
 111  *
 112  * MSG_HANDLE_T msgHandle = NULL;
 113  * msg_message_t                msg;
 114  *
 115  * ...
 116  *
 117  * err = msg_open_msg_handle(&msgHandle);
 118  *
 119  * ...
 120  *
 121  * msg = msg_new_message();
 122  *
 123  * if (msg == NULL)
 124  * {
 125  *      sprintf(str, "msg_new_message() Fail");
 126  *      print(str);
 127  * }
 128  *
 129  * ...
 130  * \endcode
 131  */
 132 /*================================================================================================*/
 133 msg_message_t msg_new_message(void);
 134
 135
 136 /**
 137
 138  * \par Description:
 139  * Free the memory of msg_message_t, which is created by msg_new_message().
 140  *
 141  * \par Purpose:
 142  * This API is used to release memory created by message creation.
 143  *
 144  * \par Typical use case:
 145  * After using message object for send/save scenario, release message need to be called.
 146  *
 147  * \par Method of function operation:
 148  * Frees the memory allocated to message object and deletes the object.
 149  *
 150  * \par Sync (or) Async:
 151  * This is a Synchronous API.
 152  *
 153  * \par Important notes:
 154  * - None
 155  *
 156  * \param msg_message_t    input - message object to be destroyed .
 157  *
 158  * \return Return Type (int(MSG_ERROR_T)) \n
 159  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
 160  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
 161  *
 162  * \par Prospective clients:
 163  * External/Native Apps using Messaging Services.
 164  *
 165  * \par Related functions:
 166  * None
 167  *
 168  * \par Known issues/bugs:
 169  * None
 170  *
 171  * \par Sample code:
 172  * \code
 173  * ...
 174  *
 175  * MSG_HANDLE_T msgHandle = NULL;
 176  * MSG_ERROR_T err = MSG_SUCCESS;
 177  * msg_message_t                msg;
 178  *
 179  * ...
 180  *
 181  * err = msg_open_msg_handle(&msgHandle);
 182  *
 183  * ...
 184  *
 185  * msg = msg_new_message();
 186  * ...
 187  * err = msg_release_message(&msg);
 188  *
 189  * if (err != MSG_SUCCESS)
 190  * {
 191  *      sprintf(str, "msg_release_message() Fail [%d]", err);
 192  *      print(str);
 193  *
 194  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
 195  * }
 196  *
 197  * ...
 198  * \endcode
 199  */
 200 /*================================================================================================*/
 201 int msg_release_message(msg_message_t *msg);
 202
 203
 204
 205 /**
 206
 207  * \par Description:
 208  * Set message id field to the passed msg_id.
 209  *
 210  * \par Purpose:
 211  * This API is used to set the Message Id of the message object
 212  *
 213  * \par Typical use case:
 214  * Explicitly set the msgId member of message object.
 215  *
 216  * \par Method of function operation:
 217  * Set the msgId member of msg_message_t to the passed msgId.
 218  *
 219  * \par Sync (or) Async:
 220  * This is a Synchronous API.
 221  *
 222  * \par Important notes:
 223  * - If msg is NULL, no action is done
 224  * - If msg is invalid, behavior is undefined
 225  *
 226  * \param msg_message_t    input - message object whose msgId is to be set.
 227  * \param int    input - Message Id to be set to the message id.
 228  *
 229  * \return Return Type (int(MSG_ERROR_T)) \n
 230  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
 231  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
 232  *
 233  * \par Prospective clients:
 234  * External/Native Apps using Messaging Services.
 235  *
 236  * \par Related functions:
 237  * None
 238  *
 239  * \par Known issues/bugs:
 240  * None
 241  *
 242  * \par Sample code:
 243  * \code
 244  * ...
 245  *
 246  * MSG_HANDLE_T msgHandle = NULL;
 247  * MSG_ERROR_T err = MSG_SUCCESS;
 248  * msg_message_t                msg;
 249  *
 250  * ...
 251  *
 252  * err = msg_open_msg_handle(&msgHandle);
 253  *
 254  * ...
 255  *
 256  * msg_add_message(msgHandle, msg, &sendOpt);
 257  * ...
 258  * err = msg_set_message_id(msg, 0);
 259  * if (err != MSG_SUCCESS)
 260  * {
 261  *      sprintf(str, "msg_release_message() Fail [%d]", err);
 262  *      print(str);
 263  *
 264  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
 265  * }
 266  * err = msg_release_message(&msg);
 267  * ...
 268  * \endcode
 269  */
 270 /*================================================================================================*/
 271 int msg_set_message_id(msg_message_t msg, int msg_id);
 272
 273
 274 /**
 275
 276  * \par Description:
 277  * Get the message id in message object.
 278  *
 279  * \par Purpose:
 280  * This API is used to get the Message Id of the message object
 281  *
 282  * \par Typical use case:
 283  * Msg Id is needed to perform many operations on the message object.
 284  *
 285  * \par Method of function operation:
 286  * Returns the Message Id of the message object.
 287  *
 288  * \par Sync (or) Async:
 289  * This is a Synchronous API.
 290  *
 291  * \par Important notes:
 292  * - None
 293  *
 294  * \param msg_message_t    input - message object whose msgId is returned.
 295  *
 296  * \return Return Type (int(MSG_ERROR_T)) \n
 297  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
 298  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
 299  *
 300  * \par Prospective clients:
 301  * External/Native Apps using Messaging Services.
 302  *
 303  * \par Related functions:
 304  * None
 305  *
 306  * \par Known issues/bugs:
 307  * None
 308  *
 309  * \par Sample code:
 310  * \code
 311  * ...
 312  *
 313  * MSG_HANDLE_T msgHandle = NULL;
 314  * MSG_ERROR_T err = MSG_SUCCESS;
 315  * msg_message_t                msg;
 316  * int msgId;
 317  *
 318  * ...
 319  *
 320  * err = msg_open_msg_handle(&msgHandle);
 321  *
 322  * ...
 323  *
 324  * msg_add_message(msgHandle, msg, &sendOpt);
 325  * ...
 326  * msgId = msg_get_message_id(msg);
 327  * ...
 328  * err = msg_release_message(&msg);
 329  * ...
 330  * \endcode
 331  */
 332 /*================================================================================================*/
 333 int msg_get_message_id(msg_message_t msg);
 334
 335
 336 /**
 337
 338  * \par Description:
 339  * Check if the message object is an SMS Message
 340  *
 341  * \par Purpose:
 342  * This API is used to to check if the message object is SMS type message
 343  *
 344  * \par Typical use case:
 345  * To check if the message object type is SMS.
 346  *
 347  * \par Method of function operation:
 348  * Compares the message object against SMS message type.
 349  *
 350  * \par Sync (or) Async:
 351  * This is a Synchronous API.
 352  *
 353  * \par Important notes:
 354  * - If msg is NULL, nothing happens.
 355  * - If msg is invalid, undefined behavior happens.
 356  *
 357  * \param msg_message_t    input - message object which is to be decided if its SMS.
 358  *
 359  * \return Return Type (bool) \n
 360  * - true       - If message object is SMS  \n
 361  * - false - If message object is not SMS.
 362  *
 363  * \par Prospective clients:
 364  * External/Native Apps using Messaging Services.
 365  *
 366  * \par Related functions:
 367  * None
 368  *
 369  * \par Known issues/bugs:
 370  * None
 371  *
 372  * \par Sample code:
 373  * \code
 374  * ...
 375  *
 376  * MSG_HANDLE_T msgHandle = NULL;
 377  * MSG_ERROR_T err = MSG_SUCCESS;
 378  * msg_message_t                msg;
 379  * int msgId;
 380  *
 381  * ...
 382  *
 383  * err = msg_open_msg_handle(&msgHandle);
 384  *
 385  * ...
 386  *
 387  * msg_add_message(msgHandle, msg, &sendOpt);
 388  * ...
 389  * if( msg_is_sms(msg) )
 390  * {
 391  *      sprintf(str, "Message object is SMS");
 392  *      print(str);
 393  * }
 394  *...
 395  * err = msg_release_message(&msg);
 396  * ...
 397  * \endcode
 398  */
 399 /*================================================================================================*/
 400 bool msg_is_sms(msg_message_t msg);
 401
 402
 403
 404 /**
 405
 406  * \par Description:
 407  * Check if the message object is an MMS Message
 408  *
 409  * \par Purpose:
 410  * This API is used to to check if the message object is MMS type message
 411  *
 412  * \par Typical use case:
 413  * To check if the message object type is MMS.
 414  *
 415  * \par Method of function operation:
 416  * Compares the message object against MMS message type.
 417  *
 418  * \par Sync (or) Async:
 419  * This is a Synchronous API.
 420  *
 421  * \par Important notes:
 422  * - None
 423  *
 424  * \param msg_message_t    input - message object which is to be decided if its MMS.
 425  *
 426  * \return Return Type (bool) \n
 427  * - true       - If message object is MMS  \n
 428  * - false - If message object is not MMS.
 429  *
 430  * \par Prospective clients:
 431  * External/Native Apps using Messaging Services.
 432  *
 433  * \par Related functions:
 434  * None
 435  *
 436  * \par Known issues/bugs:
 437  * None
 438  *
 439  * \par Sample code:
 440  * \code
 441  * ...
 442  *
 443  * MSG_HANDLE_T msgHandle = NULL;
 444  * MSG_ERROR_T err = MSG_SUCCESS;
 445  * msg_message_t                msg;
 446  * int msgId;
 447  *
 448  * ...
 449  *
 450  * err = msg_open_msg_handle(&msgHandle);
 451  *
 452  * ...
 453  *
 454  * msg_add_message(msgHandle, msg, &sendOpt);
 455  * ...
 456  * if( msg_is_mms(msg) )
 457  * {
 458  *      sprintf(str, "Message object is MMS");
 459  *      print(str);
 460  * }
 461  *...
 462  * err = msg_release_message(&msg);
 463  * ...
 464  * \endcode
 465  */
 466 /*================================================================================================*/
 467 bool msg_is_mms(msg_message_t msg);
 468
 469
 470 /**
 471
 472  * \par Description:
 473  * Set storage id field to the passed storage_id.
 474  *
 475  * \par Purpose:
 476  * This API is used to set the Storage Id of the message object
 477  *
 478  * \par Typical use case:
 479  * Message objects can be saved in either phone memory or SIM card, this API helps in setting the same.
 480  *
 481  * \par Method of function operation:
 482  * Set the storageId member of msg_message_t to the passed Storage Id.
 483  *
 484  * \par Sync (or) Async:
 485  * This is a Synchronous API.
 486  *
 487  * \par Important notes:
 488  * - If msg is NULL, no action is done
 489  * - If msg is invalid, behavior is undefined
 490  *
 491  * \param msg_message_t    input - message object whose msgId is to be set.
 492  * \param MSG_STORAGE_ID_T    input - Storage Id to be set to the message storage id.
 493  *
 494  * \return Return Type (int(MSG_ERROR_T)) \n
 495  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
 496  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
 497  *
 498  * \par Prospective clients:
 499  * External/Native Apps using Messaging Services.
 500  *
 501  * \par Related functions:
 502  * None
 503  *
 504  * \par Known issues/bugs:
 505  * None
 506  *
 507  * \par Sample code:
 508  * \code
 509  * ...
 510  *
 511  * MSG_HANDLE_T msgHandle = NULL;
 512  * MSG_ERROR_T err = MSG_SUCCESS;
 513  * msg_message_t                msg;
 514  * MSG_STORAGE_ID_T storageId = 0;
 515  *
 516  * ...
 517  *
 518  * err = msg_open_msg_handle(&msgHandle);
 519  *
 520  * ...
 521  *
 522  * msg_add_message(msgHandle, msg, &sendOpt);
 523  * ...
 524  * err = msg_set_storage_id(msg, storageId);
 525  * if (err != MSG_SUCCESS)
 526  * {
 527  *      sprintf(str, "msg_set_storage_id() Fail [%d]", err);
 528  *      print(str);
 529  *
 530  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
 531  * }
 532  * err = msg_release_message(&msg);
 533  * ...
 534  * \endcode
 535  */
 536 /*================================================================================================*/
 537 int msg_set_storage_id(msg_message_t opq_msg, MSG_STORAGE_ID_T storage_id);
 538
 539
 540 /**
 541
 542  * \par Description:
 543  * Gets storage id field of the message object.
 544  *
 545  * \par Purpose:
 546  * This API is used to get Storage Id of the message object
 547  *
 548  * \par Typical use case:
 549  *  * Message objects can be saved in either phone memory or SIM card, this API helps in getting the same.
 550  *
 551  * \par Method of function operation:
 552  * Returnsthe storageId member of msg_message_t.
 553  *
 554  * \par Sync (or) Async:
 555  * This is a Synchronous API.
 556  *
 557  * \par Important notes:
 558  * - If msg is invalid, behavior is undefined
 559  *
 560  * \param msg_message_t    input - message object whose msgId is to be set.
 561  *
 562  * \return Return Type (int (MSG_ERROR_T when negative, enum _MSG_STORAGE_ID_E when positive)) \n
 563  * - storageId - Returns the storage Id defined by enum _MSG_STORAGE_ID_E. \n
 564  * - MSG_ERR_NULL_POINTER                       msg is NULL.
 565  *
 566  * \par Prospective clients:
 567  * External/Native Apps using Messaging Services.
 568  *
 569  * \par Related functions:
 570  * None
 571  *
 572  * \par Known issues/bugs:
 573  * None
 574  *
 575  * \par Sample code:
 576  * \code
 577  * ...
 578  *
 579  * MSG_HANDLE_T msgHandle = NULL;
 580  * MSG_ERROR_T err = MSG_SUCCESS;
 581  * msg_message_t                msg;
 582  * MSG_STORAGE_ID_T storageId = 0;
 583  *
 584  * ...
 585  *
 586  * err = msg_open_msg_handle(&msgHandle);
 587  *
 588  * ...
 589  *
 590  * msg_add_message(msgHandle, msg, &sendOpt);
 591  * ...
 592  * storageId = msg_get_storage_id(msg);
 593  *
 594  * sprintf(str, "msg_set_storage_id() storageId [%d]", storageId);
 595  * print(str);
 596  *
 597  * err = msg_release_message(&msg);
 598  * ...
 599  * \endcode
 600  */
 601 /*================================================================================================*/
 602 int msg_get_storage_id(msg_message_t opq_msg);
 603
 604
 605 /**
 606
 607  * \par Description:
 608  * Check if the message object is saved in SIM card
 609  *
 610  * \par Purpose:
 611  * This API is used to to check if the message object is saved in SIM card
 612  *
 613  * \par Typical use case:
 614  * Message can be stored in Phone memory or SIM card, to check this we can use this API.
 615  *
 616  * \par Method of function operation:
 617  * Checks if storage Id is SIM and returns boolean.
 618  *
 619  * \par Sync (or) Async:
 620  * This is a Synchronous API.
 621  *
 622  * \par Important notes:
 623  * - None
 624  *
 625  * \param msg_message_t    input - message object.
 626  *
 627  * \return Return Type (bool) \n
 628  * - true       - If message object is stored in SIM  \n
 629  * - false - If message object is not stored in SIM.
 630  *
 631  * \par Prospective clients:
 632  * External/Native Apps using Messaging Services.
 633  *
 634  * \par Related functions:
 635  * None
 636  *
 637  * \par Known issues/bugs:
 638  * None
 639  *
 640  * \par Sample code:
 641  * \code
 642  * ...
 643  *
 644  * MSG_HANDLE_T msgHandle = NULL;
 645  * MSG_ERROR_T err = MSG_SUCCESS;
 646  * msg_message_t                msg;
 647  * int msgId;
 648  *
 649  * ...
 650  *
 651  * err = msg_open_msg_handle(&msgHandle);
 652  *
 653  * ...
 654  *
 655  * msg_add_message(msgHandle, msg, &sendOpt);
 656  * ...
 657  * if( msg_is_in_sim(msg) )
 658  * {
 659  *      sprintf(str, "Message object stored in SIM");
 660  *      print(str);
 661  * }
 662  *...
 663  * err = msg_release_message(&msg);
 664  * ...
 665  * \endcode
 666  */
 667 /*================================================================================================*/
 668 bool msg_is_in_sim(msg_message_t msg);
 669
 670
 671 /**
 672
 673  * \par Description:
 674  * Set the message type field to msg_type.
 675  *
 676  * \par Purpose:
 677  * This API is used to set the Message Type of the message object
 678  *
 679  * \par Typical use case:
 680  * Message Objects can be SMS, MMS, etc message types, this API helps to set the message type.
 681  *
 682  * \par Method of function operation:
 683  * Set the msgType member of msg_message_t to the passed msgType.
 684  *
 685  * \par Sync (or) Async:
 686  * This is a Synchronous API.
 687  *
 688  * \par Important notes:
 689  * - If msg is NULL, no action is done
 690  * - If msg is invalid, behavior is undefined
 691  *
 692  * \param msg_message_t    input - message object whose msgId is to be set.
 693  * \param MSG_MESSAGE_TYPE_T    input - Message type to be set.
 694  *
 695  * \return Return Type (int(MSG_ERROR_T)) \n
 696  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
 697  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
 698  *
 699  * \par Prospective clients:
 700  * External/Native Apps using Messaging Services.
 701  *
 702  * \par Related functions:
 703  * None
 704  *
 705  * \par Known issues/bugs:
 706  * None
 707  *
 708  * \par Sample code:
 709  * \code
 710  * ...
 711  *
 712  * MSG_HANDLE_T msgHandle = NULL;
 713  * msg_message_t                msg;
 714  * MSG_ERROR_T err = MSG_SUCCESS;
 715  *
 716  * ...
 717  *
 718  * err = msg_open_msg_handle(&msgHandle);
 719  *
 720  * ...
 721  *
 722  * msg_add_message(msgHandle, msg, &sendOpt);
 723  * ...
 724  * err = msg_set_message_type(msg, MSG_TYPE_SMS);
 725  * if (err != MSG_SUCCESS)
 726  * {
 727  *      sprintf(str, "msg_set_message_type() Fail [%d]", err);
 728  *      print(str);
 729  *
 730  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
 731  * }
 732  * err = msg_release_message(&msg);
 733  * ...
 734  * \endcode
 735  */
 736 /*================================================================================================*/
 737 int msg_set_message_type(msg_message_t msg, MSG_MESSAGE_TYPE_T msg_type);
 738
 739
 740 /**
 741
 742  * \par Description:
 743  * Gets Message type field of the message object.
 744  *
 745  * \par Purpose:
 746  * This API is used to get Message Type of the message object
 747  *
 748  * \par Typical use case:
 749  * Message Objects can be SMS, MMS, etc message types, this API helps to get the message type.
 750  *
 751  * \par Method of function operation:
 752  * Returns the msgType member of msg_message_t.
 753  *
 754  * \par Sync (or) Async:
 755  * This is a Synchronous API.
 756  *
 757  * \par Important notes:
 758  * - If msg is invalid, behavior is undefined
 759  *
 760  * \param msg_message_t    input - message object whose msgType  is to be set.
 761  *
 762  * \return Return Type (int) \n
 763  * - msgType - Returns the Message type of the Message object passed \n
 764  *
 765  * \par Prospective clients:
 766  * External/Native Apps using Messaging Services.
 767  *
 768  * \par Related functions:
 769  * None
 770  *
 771  * \par Known issues/bugs:
 772  * None
 773  *
 774  * \par Sample code:
 775  * \code
 776  * ...
 777  *
 778  * MSG_HANDLE_T msgHandle = NULL;
 779  * msg_message_t                msg;
 780  * MSG_ERROR_T err = MSG_SUCCESS;
 781  * int  msgType = 0;
 782
 783  *
 784  * ...
 785  *
 786  * err = msg_open_msg_handle(&msgHandle);
 787  *
 788  * ...
 789  *
 790  * msg_add_message(msgHandle, msg, &sendOpt);
 791  * ...
 792  * msgType = msg_get_message_type(msg);
 793  *
 794  * sprintf(str, "msg_get_message_type() Type [%d]", msgType);
 795  * print(str);
 796  *
 797  * err = msg_release_message(&msg);
 798  * ...
 799  * \endcode
 800  */
 801 /*================================================================================================*/
 802 int msg_get_message_type(msg_message_t msg);
 803
 804
 805 /**
 806
 807  * \par Description:
 808  * Set the folder id field to folder_id.
 809  *
 810  * \par Purpose:
 811  * This API is used to sets the Folder Id of the message object
 812  *
 813  * \par Typical use case:
 814  * Message Objects can be associated with different folders such as Inbox, Outbox, Sent, etc. this API enables to set the folder id.
 815  *
 816  * \par Method of function operation:
 817  * Set the folderId member of msg_message_t to the passed folder_id.
 818  *
 819  * \par Sync (or) Async:
 820  * This is a Synchronous API.
 821  *
 822  * \par Important notes:
 823  * - If msg is NULL, no action is done
 824  * - If msg is invalid, behavior is undefined
 825  *
 826  * \param msg_message_t    input - message object whose msgId is to be set.
 827  * \param MSG_FOLDER_ID_T    input - Folder Id to be set.
 828  *
 829  * \return Return Type (int(MSG_ERROR_T)) \n
 830  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
 831  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
 832  *
 833  * \par Prospective clients:
 834  * External/Native Apps using Messaging Services.
 835  *
 836  * \par Related functions:
 837  * None
 838  *
 839  * \par Known issues/bugs:
 840  * None
 841  *
 842  * \par Sample code:
 843  * \code
 844  * ...
 845  *
 846  * MSG_HANDLE_T msgHandle = NULL;
 847  * MSG_ERROR_T err = MSG_SUCCESS;
 848  * msg_message_t msg;
 849  * MSG_FOLDER_ID_T folder_id = MSG_INBOX_ID;
 850  *
 851  * ...
 852  *
 853  * err = msg_open_msg_handle(&msgHandle);
 854  *
 855  * ...
 856  *
 857  * msg_add_message(msgHandle, msg, &sendOpt);
 858  * ...
 859  * err = msg_set_folder_id(msg, folder_id);
 860  * if (err != MSG_SUCCESS)
 861  * {
 862  *      sprintf(str, "msg_set_folder_id() Fail [%d]", err);
 863  *      print(str);
 864  *
 865  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
 866  * }
 867  * err = msg_release_message(&msg);
 868  * ...
 869  * \endcode
 870  */
 871 /*================================================================================================*/
 872 int msg_set_folder_id(msg_message_t msg, MSG_FOLDER_ID_T folder_id);
 873
 874
 875 /**
 876
 877  * \par Description:
 878  * Gets Folder Id field of the message object.
 879  *
 880  * \par Purpose:
 881  * This API is used to get Folder Id of the message object
 882  *
 883  * \par Typical use case:
 884  * Message Objects can be associated with different folders such as Inbox, Outbox, Sent, etc. this API enables to get the folder id.
 885  *
 886  * \par Method of function operation:
 887  * Returns the folderId member of msg_message_t.
 888  *
 889  * \par Sync (or) Async:
 890  * This is a Synchronous API.
 891  *
 892  * \par Important notes:
 893  * - If msg is invalid, behavior is undefined
 894  *
 895  * \param msg_message_t    input - message object.
 896  *
 897  * \return Return Type (int) \n
 898  * - storageId - Returns the Folder Id of the Message object passed \n
 899  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
 900  *
 901  * \par Prospective clients:
 902  * External/Native Apps using Messaging Services.
 903  *
 904  * \par Related functions:
 905  * None
 906  *
 907  * \par Known issues/bugs:
 908  * None
 909  *
 910  * \par Sample code:
 911  * \code
 912  * ...
 913  *
 914  * MSG_HANDLE_T msgHandle = NULL;
 915  * MSG_ERROR_T err = MSG_SUCCESS;
 916  * msg_message_t msg;
 917  * int  folderId = 0;
 918  *
 919  * ...
 920  *
 921  * err = msg_open_msg_handle(&msgHandle);
 922  *
 923  * ...
 924  *
 925  * msg_add_message(msgHandle, msg, &sendOpt);
 926  * ...
 927  * folderId = msg_get_folder_id(msg);
 928  *
 929  * sprintf(str, "msg_get_folder_id() Folder Id [%d]", folderId);
 930  * print(str);
 931  *
 932  * err = msg_release_message(&msg);
 933  * ...
 934  * \endcode
 935  */
 936 /*================================================================================================*/
 937 int msg_get_folder_id(msg_message_t msg);
 938
 939
 940 /**
 941
 942  * \par Description:
 943  * Reset address field in message object.
 944  *
 945  * \par Purpose:
 946  * This API is used for modifying the message object, such as forwarding a message.
 947  *
 948  * \par Typical use case:
 949  * Message Object address field might be needed to reset. This API helps in the same.
 950  *
 951  * \par Method of function operation:
 952  * Flushes the already set address list and reset to defaults.
 953  *
 954  * \par Sync (or) Async:
 955  * This is a Synchronous API.
 956  *
 957  * \par Important notes:
 958  * - None
 959  *
 960  * \param msg_message_t    input - message object.
 961  *
 962  * \return Return Type (bool) \n
 963  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
 964  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
 965  *
 966  * \par Prospective clients:
 967  * External/Native Apps using Messaging Services.
 968  *
 969  * \par Related functions:
 970  * None
 971  *
 972  * \par Known issues/bugs:
 973  * None
 974  *
 975  * \par Sample code:
 976  * \code
 977  * ...
 978  *
 979  * MSG_HANDLE_T msgHandle = NULL;
 980  * MSG_ERROR_T err = MSG_SUCCESS;
 981  * msg_message_t msg;
 982  * int msgId;
 983  *
 984  * ...
 985  *
 986  * err = msg_open_msg_handle(&msgHandle);
 987  *
 988  * ...
 989  *
 990  * msg = msg_new_message();
 991  * MSG_SENDINGOPT_S sendOpt = {0};
 992  * err = msg_get_message(msgHandle, (MSG_MESSAGE_ID_T)msgId, msg, &sendOpt);
 993  * err = msg_reset_address(msg);
 994  * if (err != MSG_SUCCESS)
 995  * {
 996  *      sprintf(str, "msg_release_message() Fail [%d]", err);
 997  *      print(str);
 998  *
 999  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
1000  * }
1001  * ...
1002  * err = msg_release_message(&msg);
1003  * ...
1004  * \endcode
1005  */
1006 /*================================================================================================*/
1007 int msg_reset_address(msg_message_t msg);
1008
1009
1010 /**
1011
1012  * \par Description:
1013  * Add recipient address in message object.
1014  *
1015  * \par Purpose:
1016  * This API is used for adding address to the message object.
1017  *
1018  * \par Typical use case:
1019  * Message Object recipient address field should be filled before message can be sent over the network.
1020  *
1021  * \par Method of function operation:
1022  * The phone_num_list is added to the addressList member of the message object structure.
1023  *
1024  * \par Sync (or) Async:
1025  * This is a Synchronous API.
1026  *
1027  * \par Important notes:
1028  * - None
1029  *
1030  * \param msg_message_t input - message object.
1031  * \param phone_num_list        input - concatenated number string, which is separated by ",", such as "1112223333, 4445556666".
1032  * \param to_type                       input - to_type is one of enum _MSG_RECIPIENT_TYPE_E.
1033  *
1034  * \return Return Type (bool) \n
1035  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
1036  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
1037  *
1038  * \par Prospective clients:
1039  * External/Native Apps using Messaging Services.
1040  *
1041  * \par Related functions:
1042  * None
1043  *
1044  * \par Known issues/bugs:
1045  * None
1046  *
1047  * \par Sample code:
1048  * \code
1049  * ...
1050  *
1051  * MSG_HANDLE_T msgHandle = NULL;
1052  * MSG_ERROR_T err = MSG_SUCCESS;
1053  * msg_message_t msg;
1054  * int msgId;
1055  *
1056  * ...
1057  *
1058  * err = msg_open_msg_handle(&msgHandle);
1059  *
1060  * ...
1061  *
1062  * msg = msg_new_message();
1063  * MSG_SENDINGOPT_S sendOpt = {0};
1064  * err = msg_get_message(msgHandle, (MSG_MESSAGE_ID_T)msgId, msg, &sendOpt);
1065  * err = msg_add_address(msg, "+1004", MSG_RECIPIENTS_TYPE_TO);
1066  * if (err != MSG_SUCCESS)
1067  * {
1068  *      sprintf(str, "msg_release_message() Fail [%d]", err);
1069  *      print(str);
1070  *
1071  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
1072  * }
1073  * ...
1074  * err = msg_release_message(&msg);
1075  * ...
1076  * \endcode
1077  */
1078 /*================================================================================================*/
1079 int msg_add_address(msg_message_t msg, const char* phone_num_list, MSG_RECIPIENT_TYPE_T to_type);
1080
1081
1082 /**
1083
1084  * \par Description:
1085  * Return count of recipient address in message object.
1086  *
1087  * \par Purpose:
1088  * This API is used for getting the count of recipient addresses in the message object.
1089  *
1090  * \par Typical use case:
1091  * To get the count of the recipient list in the message object.
1092  *
1093  * \par Method of function operation:
1094  * Returns the address count member of the message object..
1095  *
1096  * \par Sync (or) Async:
1097  * This is a Synchronous API.
1098  *
1099  * \par Important notes:
1100  * - None
1101  *
1102  * \param msg_message_t input - message object.
1103  *
1104  * \return Return Type (int) \n
1105  * - recipient count \n
1106  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
1107  *
1108  * \par Prospective clients:
1109  * External/Native Apps using Messaging Services.
1110  *
1111  * \par Related functions:
1112  * None
1113  *
1114  * \par Known issues/bugs:
1115  * None
1116  *
1117  * \par Sample code:
1118  * \code
1119  * ...
1120  *
1121  * MSG_HANDLE_T msgHandle = NULL;
1122  * MSG_ERROR_T err = MSG_SUCCESS;
1123  * msg_message_t msg;
1124  * int nCount;
1125  *
1126  * ...
1127  *
1128  * err = msg_open_msg_handle(&msgHandle);
1129  *
1130  * ...
1131  *
1132  * msg = msg_new_message();
1133  * MSG_SENDINGOPT_S sendOpt = {0};
1134  * nCount = msg_get_address_count(msg);
1135  * sprintf(str, "msg_add_address() nCount [%d]", nCount);
1136  * print(str);
1137  * ...
1138  * err = msg_release_message(&msg);
1139  * ...
1140  * \endcode
1141  */
1142 /*================================================================================================*/
1143 int msg_get_address_count(msg_message_t msg);
1144
1145
1146 /**
1147
1148  * \par Description:
1149  * Return ith thread id in message object.
1150  *
1151  * \par Purpose:
1152  * This API is used for getting the ith thread id in message object.
1153  *
1154  * \par Typical use case:
1155  * Get the requested thread id from the message object.
1156  *
1157  * \par Method of function operation:
1158  * Returns the ith thread id from the message object address list.
1159  *
1160  * \par Sync (or) Async:
1161  * This is a Synchronous API.
1162  *
1163  * \par Important notes:
1164  * - None
1165  *
1166  * \param msg_message_t input - message object.
1167  * \param int                           input - thread id.
1168  *
1169  * \return Return Type (int) \n
1170  * - thread id \n
1171  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
1172  *
1173  * \par Prospective clients:
1174  * External/Native Apps using Messaging Services.
1175  *
1176  * \par Related functions:
1177  * None
1178  *
1179  * \par Known issues/bugs:
1180  * None
1181  *
1182  * \par Sample code:
1183  * \code
1184  * ...
1185  *
1186  * MSG_HANDLE_T msgHandle = NULL;
1187  * MSG_ERROR_T err = MSG_SUCCESS;
1188  * msg_message_t msg;
1189  * int nCount;
1190  *
1191  * ...
1192  *
1193  * err = msg_open_msg_handle(&msgHandle);
1194  *
1195  * ...
1196  *
1197  * err = msg_get_ith_thread_id(msg, 0);
1198  * if(err != MSG_SUCCESS)
1199  * {
1200  *      sprintf(str, "msg_get_ith_thread_id() Fail [%d]", err);
1201  *      print(str);
1202  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
1203  * }
1204  * ...
1205  * err = msg_release_message(&msg);
1206  * ...
1207  * \endcode
1208  */
1209 /*================================================================================================*/
1210 int msg_get_ith_thread_id(msg_message_t msg, int ith);
1211
1212
1213 /**
1214
1215  * \par Description:
1216  * Return ith recipient address in message object.
1217  *
1218  * \par Purpose:
1219  * This API is used for getting the ith recipient address in message object.
1220  *
1221  * \par Typical use case:
1222  * To get the requested recipient address index from the message object.
1223  *
1224  * \par Method of function operation:
1225  * Returns the ith recipient address in address list from the message object.
1226  *
1227  * \par Sync (or) Async:
1228  * This is a Synchronous API.
1229  *
1230  * \par Important notes:
1231  * - You do not need to free the return value. It will be freed when you call msg_release_message().
1232  * -    Also, the value is valid until msg_message_t is freed by calling msg_release_message().
1233  *
1234  * \param msg_message_t input - message object.
1235  * \param int                           input - recipient address index.
1236  *
1237  * \return Return Type (int) \n
1238  * - thread id \n
1239  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
1240  *
1241  * \par Prospective clients:
1242  * External/Native Apps using Messaging Services.
1243  *
1244  * \par Related functions:
1245  * None
1246  *
1247  * \par Known issues/bugs:
1248  * None
1249  *
1250  * \par Sample code:
1251  * \code
1252  * ...
1253  *
1254  * MSG_HANDLE_T msgHandle = NULL;
1255  * MSG_ERROR_T err = MSG_SUCCESS;
1256  * msg_message_t msg;
1257  * const char* address;
1258  *
1259  * ...
1260  *
1261  * err = msg_open_msg_handle(&msgHandle);
1262  *
1263  * ...
1264  *
1265  * address = msg_get_ith_address(msg, 0);
1266  * if(address != NULL && strlen(address) > 0)
1267  * {
1268  *      sprintf(str, "msg_get_ith_address() address [%s]", address);
1269  *      print(str);
1270  * }
1271  * ...
1272  * err = msg_release_message(&msg);
1273  * ...
1274  * \endcode
1275  */
1276 /*================================================================================================*/
1277 const char* msg_get_ith_address(msg_message_t msg, int ith);
1278
1279
1280 /**
1281
1282  * \par Description:
1283  * Return ith recipient type in message object.
1284  *
1285  * \par Purpose:
1286  * This API is used for getting the ith recipient type in message object.
1287  *
1288  * \par Typical use case:
1289  * To get the requested recipient type from the message object.
1290  *
1291  * \par Method of function operation:
1292  * Returns the ith recipient type in address list from the message object.
1293  *
1294  * \par Sync (or) Async:
1295  * This is a Synchronous API.
1296  *
1297  * \par Important notes:
1298  * - None
1299  *
1300  * \param msg_message_t input - message object.
1301  * \param int                           input - recipient address index.
1302  *
1303  * \return Return Type (int) \n
1304  * - thread id \n
1305  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
1306  *
1307  * \par Prospective clients:
1308  * External/Native Apps using Messaging Services.
1309  *
1310  * \par Related functions:
1311  * None
1312  *
1313  * \par Known issues/bugs:
1314  * None
1315  *
1316  * \par Sample code:
1317  * \code
1318  * ...
1319  *
1320  * MSG_HANDLE_T msgHandle = NULL;
1321  * MSG_ERROR_T err = MSG_SUCCESS;
1322  * msg_message_t msg;
1323  * int r_type;
1324  *
1325  * ...
1326  *
1327  * err = msg_open_msg_handle(&msgHandle);
1328  *
1329  * ...
1330  *
1331  * r_type = msg_get_ith_recipient_type(msg, 0);
1332  * sprintf(str, "msg_get_ith_recipient_type() r_type [%s]", r_type);
1333  * print(str);
1334  * ...
1335  * err = msg_release_message(&msg);
1336  * ...
1337  * \endcode
1338  */
1339 /*================================================================================================*/
1340 int msg_get_ith_recipient_type(msg_message_t msg, int ith);
1341
1342
1343 /**
1344
1345  * \par Description:
1346  * Return ith recipient name which is associated with contact engine.
1347  *
1348  * \par Purpose:
1349  * This API is used for getting the ith recipient name which is associated with contact engine.
1350  *
1351  * \par Typical use case:
1352  * To get the requested recipient name from the message object which is associated with the contact engine.
1353  *
1354  * \par Method of function operation:
1355  * Returns the ith recipient name of the address list from the message object.
1356  *
1357  * \par Sync (or) Async:
1358  * This is a Synchronous API.
1359  *
1360  * \par Important notes:
1361  * - You do not need to free the return value. It will be freed when you call msg_release_message().
1362  * - Also, the value is valid until msg_message_t is freed by calling msg_release_message().
1363  *
1364  * \param msg_message_t input - message object.
1365  * \param int                           input - recipient address index.
1366  *
1367  * \return Return Type (int) \n
1368  * - thread id \n
1369  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
1370  *
1371  * \par Prospective clients:
1372  * External/Native Apps using Messaging Services.
1373  *
1374  * \par Related functions:
1375  * None
1376  *
1377  * \par Known issues/bugs:
1378  * None
1379  *
1380  * \par Sample code:
1381  * \code
1382  * ...
1383  *
1384  * MSG_HANDLE_T msgHandle = NULL;
1385  * MSG_ERROR_T err = MSG_SUCCESS;
1386  * msg_message_t msg;
1387  * const char* name;
1388  *
1389  * ...
1390  *
1391  * err = msg_open_msg_handle(&msgHandle);
1392  *
1393  * ...
1394  *
1395  * name = msg_get_ith_name(msg, 0);
1396  * if(name != NULL && strlen(name) > 0)
1397  * {
1398  *      sprintf(str, "msg_get_ith_recipient_type() name [%s]", name);
1399  *      print(str);
1400  * }
1401  * ...
1402  * err = msg_release_message(&msg);
1403  * ...
1404  * \endcode
1405  */
1406 /*================================================================================================*/
1407 const char* msg_get_ith_name(msg_message_t msg, int ith);
1408
1409
1410 /**
1411
1412  * \par Description:
1413  * Return ith recipient contact id which is associated with contact engine.
1414  *
1415  * \par Purpose:
1416  * This API is used for getting the ith recipient contact id which is associated with contact engine.
1417  *
1418  * \par Typical use case:
1419  * To get the requested recipient contact id from the message object which is associated with the contact engine.
1420  *
1421  * \par Method of function operation:
1422  * Returns the ith recipient contact id in address list from the message object.
1423  *
1424  * \par Sync (or) Async:
1425  * This is a Synchronous API.
1426  *
1427  * \par Important notes:
1428  * - If msg is NULL, nothing happens.
1429  * - If msg is invalid, undefined behavior happens.
1430  *
1431  * \param msg_message_t input - message object.
1432  * \param int                           input - recipient address index.
1433  *
1434  * \return Return Type (int) \n
1435  * - thread id \n
1436  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
1437  *
1438  * \par Prospective clients:
1439  * External/Native Apps using Messaging Services.
1440  *
1441  * \par Related functions:
1442  * None
1443  *
1444  * \par Known issues/bugs:
1445  * None
1446  *
1447  * \par Sample code:
1448  * \code
1449  * ...
1450  *
1451  * MSG_HANDLE_T msgHandle = NULL;
1452  * MSG_ERROR_T err = MSG_SUCCESS;
1453  * msg_message_t msg;
1454  * int contact_id;
1455  *
1456  * ...
1457  *
1458  * err = msg_open_msg_handle(&msgHandle);
1459  * ...
1460  * contact_id = msg_get_ith_contact_id(msg, 0);
1461  * sprintf(str, "msg_get_ith_contact_id() contact_id [%d]", contact_id);
1462  * print(str);
1463  * ...
1464  * err = msg_release_message(&msg);
1465  * ...
1466  * \endcode
1467  */
1468 /*================================================================================================*/
1469 int msg_get_ith_contact_id(msg_message_t msg, int ith);
1470
1471
1472 /**
1473
1474  * \par Description:
1475  * Add reply address in message object.
1476  *
1477  * \par Purpose:
1478  * This API is used for adding reply address to the message object.
1479  *
1480  * \par Typical use case:
1481  * Message Object reply address field should be filled before message can be sent over the network.
1482  *
1483  * \par Method of function operation:
1484  * The phone_num is set to the replyAddress of the message object structure.
1485  *
1486  * \par Sync (or) Async:
1487  * This is a Synchronous API.
1488  *
1489  * \par Important notes:
1490  * - None
1491  *
1492  * \param msg_message_t input - message object.
1493  * \param phone_num             input - phone number such as "1112223333, 4445556666".
1494  *
1495  * \return Return Type (bool) \n
1496  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
1497  * - MSG_ERR_NULL_POINTER       - Input parameter is NULL.
1498  * - MSG_ERR_INVALID_PARAMETER - Input parameter is too long.
1499  *
1500  * \par Prospective clients:
1501  * External/Native Apps using Messaging Services.
1502  *
1503  * \par Related functions:
1504  * None
1505  *
1506  * \par Known issues/bugs:
1507  * None
1508  *
1509  * \par Sample code:
1510  * \code
1511  * ...
1512  *
1513  * MSG_HANDLE_T msgHandle = NULL;
1514  * MSG_ERROR_T err = MSG_SUCCESS;
1515  * msg_message_t msg;
1516  * int msgId;
1517  *
1518  * ...
1519  *
1520  * err = msg_open_msg_handle(&msgHandle);
1521  *
1522  * ...
1523  *
1524  * msg = msg_new_message();
1525  * MSG_SENDINGOPT_S sendOpt = {0};
1526  * err = msg_get_message(msgHandle, (MSG_MESSAGE_ID_T)msgId, msg, &sendOpt);
1527  * err = msg_set_reply_address(msg, "+821030016057");
1528  * if (err != MSG_SUCCESS)
1529  * {
1530  *      sprintf(str, "msg_release_message() Fail [%d]", err);
1531  *      print(str);
1532  *
1533  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
1534  * }
1535  * ...
1536  * err = msg_release_message(&msg);
1537  * ...
1538  * \endcode
1539  */
1540 /*================================================================================================*/
1541 int msg_set_reply_address(msg_message_t opq_msg, const char* phone_num);
1542
1543
1544 /**
1545
1546  * \par Description:
1547  * Set data field to mdata of size. SMS data is used for either of text or binary data.
1548  *
1549  * \par Purpose:
1550  * This API is used to set the Message data field of the message object to the passed mdata parameter of size bytes.
1551  *
1552  * \par Typical use case:
1553  * Message Object needs to be filled with the data member, in case of SMS data can be text or binary and in case of MMS data is the MIME encoded buffer.
1554  *
1555  * \par Method of function operation:
1556  * Copies "size" bytes of mdata to the pData member of the message object.
1557  *
1558  * \par Sync (or) Async:
1559  * This is a Synchronous API.
1560  *
1561  * \par Important notes:
1562  * - If msg is NULL, no action is done
1563  * - If msg is invalid, behavior is undefined
1564  *
1565  * \param msg_message_t         input - message object whose msgId is to be set.
1566  * \param const char*                   input - data to be set.
1567  * \param int                           input - size of mdata to be set to message object
1568  *
1569  * \return Return Type (int(MSG_ERROR_T)) \n
1570  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
1571  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
1572  * - MSG_ERR_INVALID_PARAMETER                  class_type is not one of enum _MSG_CLASS_TYPE_E.
1573  *
1574  * \par Prospective clients:
1575  * External/Native Apps using Messaging Services.
1576  *
1577  * \par Related functions:
1578  * None
1579  *
1580  * \par Known issues/bugs:
1581  * None
1582  *
1583  * \par Sample code:
1584  * \code
1585  * ...
1586  *
1587  * MSG_HANDLE_T msgHandle = NULL;
1588  * MSG_ERROR_T err = MSG_SUCCESS;
1589  * msg_message_t msg;
1590  * const char *msg_body = "Sample Message Body";
1591  *
1592  * ...
1593  *
1594  * err = msg_open_msg_handle(&msgHandle);
1595  * ...
1596  * msg = msg_new_message();
1597  *
1598  * ...
1599  * ...
1600  * err = msg_sms_set_message_body(msg, msg_body, strlen(msg_body));
1601  * if (err != MSG_SUCCESS)
1602  * {
1603  *      sprintf(str, "msg_sms_set_message_body() Fail [%d]", err);
1604  *      print(str);
1605  *
1606  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
1607  * }
1608  * err = msg_release_message(&msg);
1609  * ...
1610  * \endcode
1611  */
1612 /*================================================================================================*/
1613 int msg_sms_set_message_body(msg_message_t msg, const char* mdata, int size);
1614
1615
1616 /**
1617
1618  * \par Description:
1619  * Return data field in message object. SMS data is used for either of text or binary data.
1620  *
1621  * \par Purpose:
1622  * This API is used for getting the data field of the message object.
1623  *
1624  * \par Typical use case:
1625  * Message Object needs to be filled with the data member, in case of SMS data can be text or binary and in case of MMS data is the MIME encoded buffer.
1626  *
1627  * \par Method of function operation:
1628  * Returns the storageId member of msg_message_t.
1629  *
1630  * \par Sync (or) Async:
1631  * This is a Synchronous API.
1632  *
1633  * \par Important notes:
1634  * - If msg is invalid, behavior is undefined
1635  *
1636  * \param msg_message_t    input - message object whose msgId is to be set.
1637  *
1638  * \return Return Type (const char* (message body)) \n
1639  * - char array - Message body data \n
1640  * - NULL               - Error.
1641  *
1642  * \par Prospective clients:
1643  * External/Native Apps using Messaging Services.
1644  *
1645  * \par Related functions:
1646  * None
1647  *
1648  * \par Known issues/bugs:
1649  * None
1650  *
1651  * \par Sample code:
1652  * \code
1653  * ...
1654  *
1655  * MSG_HANDLE_T msgHandle = NULL;
1656  * MSG_ERROR_T err = MSG_SUCCESS;
1657  * msg_message_t msg;
1658  * const char *msg_body;
1659  *
1660  * ...
1661  *
1662  * err = msg_open_msg_handle(&msgHandle);
1663  *
1664  * ...
1665  *
1666  * msg_message_t msg = msg_new_message();
1667  * MSG_SENDINGOPT_S sendOpt = {0, };
1668  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
1669  * ...
1670  * msg_body = msg_sms_get_message_body(msg);
1671  * if (msg_body != NULL && strlen(msg_body) > 0)
1672  * {
1673  *      sprintf(str, "msg_sms_set_message_body() msg_body [%s]", msg_body);
1674  *      print(str);
1675  * }
1676  * ..
1677  * err = msg_release_message(&msg);
1678  * ...
1679  * \endcode
1680  */
1681  /*================================================================================================*/
1682 const char* msg_sms_get_message_body(msg_message_t msg);
1683
1684
1685 /**
1686
1687  * \par Description:
1688  * Return data field in message object. MMS data is used for text.
1689  *
1690  * \par Purpose:
1691  * This API is used for getting the data field of the message object.
1692  *
1693  * \par Typical use case:
1694  * Message Object needs to be filled with the data member, in case of SMS data can be text or binary and in case of MMS data is the MIME encoded buffer.
1695  *
1696  * \par Method of function operation:
1697  * Returns the storageId member of msg_message_t.
1698  *
1699  * \par Sync (or) Async:
1700  * This is a Synchronous API.
1701  *
1702  * \par Important notes:
1703  * - If msg is invalid, behavior is undefined
1704  *
1705  * \param msg_message_t    input - message object whose msgId is to be set.
1706  *
1707  * \return Return Type (const char* (message body)) \n
1708  * - char array - Message body data \n
1709  * - NULL               - Error.
1710  *
1711  * \par Prospective clients:
1712  * External/Native Apps using Messaging Services.
1713  *
1714  * \par Related functions:
1715  * None
1716  *
1717  * \par Known issues/bugs:
1718  * None
1719  *
1720  * \par Sample code:
1721  * \code
1722  * ...
1723  *
1724  * MSG_HANDLE_T msgHandle = NULL;
1725  * MSG_ERROR_T err = MSG_SUCCESS;
1726  * msg_message_t msg;
1727  * const char *msg_body;
1728  *
1729  * ...
1730  *
1731  * err = msg_open_msg_handle(&msgHandle);
1732  *
1733  * ...
1734  *
1735  * msg_message_t msg = msg_new_message();
1736  * MSG_SENDINGOPT_S sendOpt = {0, };
1737  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
1738  * ...
1739  * msg_body = msg_mms_get_text_contents(msg);
1740  * if (msg_body != NULL && strlen(msg_body) > 0)
1741  * {
1742  *      sprintf(str, "msg_mms_get_text_contents() msg_body [%s]", msg_body);
1743  *      print(str);
1744  * }
1745  * ..
1746  * err = msg_release_message(&msg);
1747  * ...
1748  * \endcode
1749  */
1750  /*================================================================================================*/
1751 const char* msg_mms_get_text_contents(msg_message_t msg);
1752
1753
1754 /**
1755
1756  * \par Description:
1757  * Gets the size of data field in message object.
1758  *
1759  * \par Purpose:
1760  * This API is used for getting the size of data field in message object.
1761  *
1762  * \par Typical use case:
1763  * Size of the Message data field can be useful in various scenarios such as restrict sending large MMS, display size to user, etc.
1764  *
1765  * \par Method of function operation:
1766  * Returns the dataSize member of msg_message_t.
1767  *
1768  * \par Sync (or) Async:
1769  * This is a Synchronous API.
1770  *
1771  * \par Important notes:
1772  * - If msg is invalid, behavior is undefined
1773  *
1774  * \param msg_message_t    input - message object.
1775  *
1776  * \return Return Type (int) \n
1777  * - int - Size of the data in the Message Object
1778  *
1779  * \par Prospective clients:
1780  * External/Native Apps using Messaging Services.
1781  *
1782  * \par Related functions:
1783  * None
1784  *
1785  * \par Known issues/bugs:
1786  * None
1787  *
1788  * \par Sample code:
1789  * \code
1790  * ...
1791  *
1792  * MSG_HANDLE_T msgHandle = NULL;
1793  * MSG_ERROR_T err = MSG_SUCCESS;
1794  * msg_message_t msg;
1795  * int msg_body_size;
1796  *
1797  * ...
1798  *
1799  * err = msg_open_msg_handle(&msgHandle);
1800  *
1801  * ...
1802  *
1803  * msg_message_t msg = msg_new_message();
1804  * MSG_SENDINGOPT_S sendOpt = {0, };
1805  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
1806  * ...
1807  * msg_body_size = msg_get_message_body_size(msg);
1808  * sprintf(str, "msg_sms_set_message_body() msg_body_size [%d]", msg_body_size);
1809  * print(str);
1810  * ..
1811  * err = msg_release_message(&msg);
1812  * ...
1813  * \endcode
1814  */
1815 /*================================================================================================*/
1816 int msg_get_message_body_size(msg_message_t msg);
1817
1818
1819 /**
1820
1821  * \par Description:
1822  * Sets subject field of the message object to subject. This API is used for MMS.
1823  *
1824  * \par Purpose:
1825  * This API is used for setting the subject field of the message object
1826  *
1827  * \par Typical use case:
1828  * MMS message object may contain subject field, this API enables to set the same.
1829  *
1830  * \par Method of function operation:
1831  * Set the subject member of msg_message_t to the passed subject.
1832  *
1833  * \par Sync (or) Async:
1834  * This is a Synchronous API.
1835  *
1836  * \par Important notes:
1837  * - If msg is NULL, no action is done
1838  * - If msg is invalid, behavior is undefined
1839  *
1840  * \param msg_message_t    input - message object whose msgId is to be set.
1841  * \param const char*    input - Subject to be set.
1842  *
1843  * \return Return Type (int(MSG_ERROR_T)) \n
1844  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
1845  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
1846  *
1847  * \par Prospective clients:
1848  * External/Native Apps using Messaging Services.
1849  *
1850  * \par Related functions:
1851  * None
1852  *
1853  * \par Known issues/bugs:
1854  * None
1855  *
1856  * \par Sample code:
1857  * \code
1858  * ...
1859  *
1860  * MSG_HANDLE_T msgHandle = NULL;
1861  * MSG_ERROR_T err = MSG_SUCCESS;
1862  * msg_message_t msg;
1863  * const char* subject = "Test Subject";
1864  *
1865  * ...
1866  *
1867  * err = msg_open_msg_handle(&msgHandle);
1868  *
1869  * ...
1870  *
1871  * err = msg_set_subject(msg, subject);
1872  * if (err != MSG_SUCCESS)
1873  * {
1874  *      sprintf(str, "msg_set_subject() Fail [%d]", err);
1875  *      print(str);
1876  *
1877  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
1878  * }
1879  * err = msg_release_message(&msg);
1880  * ...
1881  * \endcode
1882  */
1883 /*================================================================================================*/
1884 int msg_set_subject(msg_message_t msg, const char* subject);
1885
1886
1887 /**
1888
1889  * \par Description:
1890  * Returns the subject field of the message object. This API is used for MMS.
1891  *
1892  * \par Purpose:
1893  * This API is used for getting the subject field of the message object
1894  *
1895  * \par Typical use case:
1896  * MMS message object may contain subject field, this API enables to get the same.
1897  *
1898  * \par Method of function operation:
1899  * Returns the subject member of msg_message_t.
1900  *
1901  * \par Sync (or) Async:
1902  * This is a Synchronous API.
1903  *
1904  * \par Important notes:
1905  * - If msg is invalid, behavior is undefined
1906  *
1907  * \param msg_message_t    input - message object.
1908  *
1909  * \return Return Type (const char*) \n
1910  * - const char - MMS message subject \n
1911  * - NULL       -       Message object/Subject field is NULL.
1912  *
1913  * \par Prospective clients:
1914  * External/Native Apps using Messaging Services.
1915  *
1916  * \par Related functions:
1917  * None
1918  *
1919  * \par Known issues/bugs:
1920  * None
1921  *
1922  * \par Sample code:
1923  * \code
1924  * ...
1925  *
1926  * MSG_HANDLE_T msgHandle = NULL;
1927  * MSG_ERROR_T err = MSG_SUCCESS;
1928  * msg_message_t msg;
1929  * char* msg_subject;
1930  *
1931  * ...
1932  *
1933  * err = msg_open_msg_handle(&msgHandle);
1934  *
1935  * ...
1936  *
1937  * msg_message_t msg = msg_new_message();
1938  * MSG_SENDINGOPT_S sendOpt = {0, };
1939  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
1940  * ...
1941  * msg_subject = msg_get_subject(msg);
1942  * if(msg_subject != NULL && strlen(msg_subject) > 0)
1943  * {
1944  *      sprintf(str, "msg_get_subject() msg_subject [%s]", msg_subject);
1945  *      print(str);
1946  * }
1947  * ..
1948  * err = msg_release_message(&msg);
1949  * ...
1950  * \endcode
1951  */
1952 /*================================================================================================*/
1953 const char* msg_get_subject(msg_message_t msg);
1954
1955
1956 /**
1957
1958  * \par Description:
1959  * Set time field to msg_time of the message object. \n
1960  * If you need to update time in message object, use this API with passing time() in time.h.
1961  *
1962  * \par Purpose:
1963  * This API is used for setting the message time of the message object
1964  *
1965  * \par Typical use case:
1966  * Message object should contain the time field before it is sent over the network.
1967  *
1968  * \par Method of function operation:
1969  * Set the msg_time member of msg_message_t to the passed msg_time.
1970  *
1971  * \par Sync (or) Async:
1972  * This is a Synchronous API.
1973  *
1974  * \par Important notes:
1975  * - If msg is NULL, no action is done
1976  * - If msg is invalid, behavior is undefined
1977  *
1978  * \param msg_message_t    input - message object whose msgId is to be set.
1979  * \param const char*    input - Subject to be set.
1980  *
1981  * \return Return Type (int(MSG_ERROR_T)) \n
1982  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
1983  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
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  * MSG_HANDLE_T msgHandle = NULL;
1999  * MSG_ERROR_T err = MSG_SUCCESS;
2000  * msg_message_t msg;
2001  * time_t curTime = time(NULL);
2002  *
2003  * ...
2004  *
2005  * err = msg_open_msg_handle(&msgHandle);
2006  *
2007  * ...
2008 * msg = msg_new_message();
2009 * err = msg_set_time(msgInfo, curTime);
2010  * if (err != MSG_SUCCESS)
2011  * {
2012  *      sprintf(str, "msg_set_time() Fail [%d]", err);
2013  *      print(str);
2014  *
2015  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
2016  * }
2017  * err = msg_release_message(&msg);
2018  * ...
2019  * \endcode
2020  */
2021 /*================================================================================================*/
2022 int msg_set_time(msg_message_t msg, time_t msg_time);
2023
2024
2025 /**
2026
2027  * \par Description:
2028  * Return the time field in message object.
2029  *
2030  * \par Purpose:
2031  * This API is used for getting the time field of the message object
2032  *
2033  * \par Typical use case:
2034  * Message object should contain the time field before it is sent over the network.
2035  *
2036  * \par Method of function operation:
2037  * Returns the msg_time member of msg_message_t.
2038  *
2039  * \par Sync (or) Async:
2040  * This is a Synchronous API.
2041  *
2042  * \par Important notes:
2043  * - If msg is invalid, behavior is undefined
2044  *
2045  * \param msg_message_t    input - message object.
2046  *
2047  * \return Return Type (time_t) \n
2048  * - time_t - Message time value \n
2049  * - NULL        - Message object is NULL.
2050  *
2051  * \par Prospective clients:
2052  * External/Native Apps using Messaging Services.
2053  *
2054  * \par Related functions:
2055  * None
2056  *
2057  * \par Known issues/bugs:
2058  * None
2059  *
2060  * \par Sample code:
2061  * \code
2062  * ...
2063  *
2064  * MSG_HANDLE_T msgHandle = NULL;
2065  * MSG_ERROR_T err = MSG_SUCCESS;
2066  * msg_message_t msg;
2067  * time_t msg_time;
2068  *
2069  * ...
2070  *
2071  * err = msg_open_msg_handle(&msgHandle);
2072  *
2073  * ...
2074  *
2075  * msg_message_t msg = msg_new_message();
2076  * MSG_SENDINGOPT_S sendOpt = {0, };
2077  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
2078  * ...
2079  * msg_time = msg_get_time(msg);
2080  * sprintf(str, "msg_get_time() msg_time [%s]", ctime(msg_time));
2081  * print(str);
2082  * ..
2083  * err = msg_release_message(&msg);
2084  * ...
2085  * \endcode
2086  */
2087 /*================================================================================================*/
2088 time_t* msg_get_time(msg_message_t msg);
2089
2090
2091 /**
2092
2093  * \par Description:
2094  * Set network status to status. Network status represents the status result when you send/receive the message.
2095  *
2096  * \par Purpose:
2097  * This API is used for setting the network status field of the message object
2098  *
2099  * \par Typical use case:
2100  *  Network status represents the status result when you send/receive the message.
2101  *
2102  * \par Method of function operation:
2103  * Set the networkStatus member of msg_message_t to the passed status.
2104  *
2105  * \par Sync (or) Async:
2106  * This is a Synchronous API.
2107  *
2108  * \par Important notes:
2109  * - If msg is NULL, no action is done
2110  * - If msg is invalid, behavior is undefined
2111  *
2112  * \param msg_message_t    input - message object whose msgId is to be set.
2113  * \param int    input - status is one of enum _MSG_NETWORK_STATUS_E.
2114  *
2115  * \return Return Type (int(MSG_ERROR_T)) \n
2116  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
2117  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
2118  *
2119  * \par Prospective clients:
2120  * External/Native Apps using Messaging Services.
2121  *
2122  * \par Related functions:
2123  * None
2124  *
2125  * \par Known issues/bugs:
2126  * None
2127  *
2128  * \par Sample code:
2129  * \code
2130  * ...
2131  *
2132  * MSG_HANDLE_T msgHandle = NULL;
2133  * MSG_ERROR_T err = MSG_SUCCESS;
2134  * msg_message_t msg;
2135  *
2136  * ...
2137  *
2138  * err = msg_open_msg_handle(&msgHandle);
2139  *
2140  * ...
2141  *
2142  * err= msg_set_network_status(msg, MSG_NETWORK_SEND_SUCCESS);
2143  * if (err != MSG_SUCCESS)
2144  * {
2145  *      sprintf(str, "msg_set_network_status() Fail [%d]", err);
2146  *      print(str);
2147  *
2148  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
2149  * }
2150  * err = msg_release_message(&msg);
2151  * ...
2152  * \endcode
2153  */
2154 /*================================================================================================*/
2155 int msg_set_network_status(msg_message_t msg, MSG_NETWORK_STATUS_T status);
2156
2157
2158 /**
2159
2160  * \par Description:
2161  * Returns the network status of message object. Network status represents the status result when you send/receive the message.
2162  *
2163  * \par Purpose:
2164  * This API is used for getting the networkStatus field of the message object
2165  *
2166  * \par Typical use case:
2167  *  Network status represents the status result when you send/receive the message.
2168  *
2169  * \par Method of function operation:
2170  * Returns the networkStatus member of msg_message_t.
2171  *
2172  * \par Sync (or) Async:
2173  * This is a Synchronous API.
2174  *
2175  * \par Important notes:
2176  * - If msg is invalid, behavior is undefined
2177  *
2178  * \param msg_message_t    input - message object.
2179  *
2180  * \return Return Type (int (MSG_ERROR_T when negative, enum _MSG_NETWORK_STATUS_E when positive)) \n
2181  * - positive int                                               enum _MSG_NETWORK_STATUS_E.
2182  * - MSG_ERR_NULL_POINTER                               msg is NULL.
2183  *
2184  * \par Prospective clients:
2185  * External/Native Apps using Messaging Services.
2186  *
2187  * \par Related functions:
2188  * None
2189  *
2190  * \par Known issues/bugs:
2191  * None
2192  *
2193  * \par Sample code:
2194  * \code
2195  * ...
2196  *
2197  * MSG_HANDLE_T msgHandle = NULL;
2198  * MSG_ERROR_T err = MSG_SUCCESS;
2199  * msg_message_t msg;
2200  * int network_status;
2201  *
2202  * ...
2203  *
2204  * err = msg_open_msg_handle(&msgHandle);
2205  *
2206  * ...
2207  *
2208  * msg_message_t msg = msg_new_message();
2209  * MSG_SENDINGOPT_S sendOpt = {0, };
2210  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
2211  * ...
2212  * network_status = msg_get_network_status(msg);
2213  *sprintf(str, "msg_get_network_status() network_status [%d]", network_status);
2214  * print(str);
2215  * ..
2216  * err = msg_release_message(&msg);
2217  * ...
2218  * \endcode
2219  */
2220 /*================================================================================================*/
2221 int msg_get_network_status(msg_message_t msg);
2222
2223
2224 /**
2225
2226  * \par Description:
2227  * Set message data encode type to encoding_type. The message data is encoded with one of GSM-7, ascii, ucs2, or auto.
2228  *
2229  * \par Purpose:
2230  * This API is used for setting the encode type field of the message object
2231  *
2232  * \par Typical use case:
2233  * The message data is encoded with one of GSM-7, ascii, ucs2, or auto.
2234  *
2235  * \par Method of function operation:
2236  * Set the encodeType member of msg_message_t to the passed encoding_type.
2237  *
2238  * \par Sync (or) Async:
2239  * This is a Synchronous API.
2240  *
2241  * \par Important notes:
2242  * - If msg is NULL, no action is done
2243  * - If msg is invalid, behavior is undefined
2244  *
2245  * \param msg_message_t    input - message object.
2246  * \param MSG_ENCODE_TYPE_T    input - encode type to be set.
2247  *
2248  * \return Return Type (int(MSG_ERROR_T)) \n
2249  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
2250  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
2251  *
2252  * \par Prospective clients:
2253  * External/Native Apps using Messaging Services.
2254  *
2255  * \par Related functions:
2256  * None
2257  *
2258  * \par Known issues/bugs:
2259  * None
2260  *
2261  * \par Sample code:
2262  * \code
2263  * ...
2264  *
2265  * MSG_HANDLE_T msgHandle = NULL;
2266  * MSG_ERROR_T err = MSG_SUCCESS;
2267  * msg_message_t msg;
2268  *
2269  * ...
2270  *
2271  * err = msg_open_msg_handle(&msgHandle);
2272  *
2273  * ...
2274  *
2275  * err = msg_set_encode_type(msgInfo, MSG_ENCODE_GSM7BIT);
2276  * if (err != MSG_SUCCESS)
2277  * {
2278  *      sprintf(str, "msg_set_encode_type() Fail [%d]", err);
2279  *      print(str);
2280  *
2281  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
2282  * }
2283  * err = msg_release_message(&msg);
2284  * ...
2285  * \endcode
2286  */
2287 /*================================================================================================*/
2288 int msg_set_encode_type(msg_message_t msg, MSG_ENCODE_TYPE_T encoding_type);
2289
2290
2291 /**
2292
2293  * \par Description:
2294  * Return message data encode type. The message data is encoded with one of GSM-7, ascii, ucs2, or auto.
2295  *
2296  * \par Purpose:
2297  * This API is used for getting the encode type field of the message object
2298  *
2299  * \par Typical use case:
2300  *  The message data is encoded with one of GSM-7, ascii, ucs2, or auto.
2301  *
2302  * \par Method of function operation:
2303  * Returns the encodeType member of msg_message_t.
2304  *
2305  * \par Sync (or) Async:
2306  * This is a Synchronous API.
2307  *
2308  * \par Important notes:
2309  * - If msg is invalid, behavior is undefined
2310  *
2311  * \param msg_message_t    input - message object.
2312  *
2313  * \return Return Type (int) \n
2314  * - positive int                                               enum MSG_ENCODE_TYPE_T.
2315  * - MSG_ERR_NULL_POINTER                               msg is NULL.
2316  *
2317  * \par Prospective clients:
2318  * External/Native Apps using Messaging Services.
2319  *
2320  * \par Related functions:
2321  * None
2322  *
2323  * \par Known issues/bugs:
2324  * None
2325  *
2326  * \par Sample code:
2327  * \code
2328  * ...
2329  *
2330  * MSG_HANDLE_T msgHandle = NULL;
2331  * MSG_ERROR_T err = MSG_SUCCESS;
2332  * msg_message_t msg;
2333  * int encode_type;
2334  *
2335  * ...
2336  *
2337  * err = msg_open_msg_handle(&msgHandle);
2338  *
2339  * ...
2340  *
2341  * msg_message_t msg = msg_new_message();
2342  * MSG_SENDINGOPT_S sendOpt = {0, };
2343  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
2344  * ...
2345  * encode_type = msg_get_encode_type(msg);
2346  * sprintf(str, "msg_get_network_status() encode_type [%d]", encode_type);
2347  * print(str);
2348  * ..
2349  * err = msg_release_message(&msg);
2350  * ...
2351  * \endcode
2352  */
2353 /*================================================================================================*/
2354 int msg_get_encode_type(msg_message_t msg);
2355
2356
2357 /**
2358
2359  * \par Description:
2360  * Set message read status to read_flag.
2361  *
2362  * \par Purpose:
2363  * This API is used to set read status to bRead field of the message object
2364  *
2365  * \par Typical use case:
2366  * Read status can be set using this API.
2367  *
2368  * \par Method of function operation:
2369  * Set the bRead member of msg_message_t to the passed read_flag.
2370  *
2371  * \par Sync (or) Async:
2372  * This is a Synchronous API.
2373  *
2374  * \par Important notes:
2375  * - If msg is NULL, no action is done
2376  * - If msg is invalid, behavior is undefined
2377  *
2378  * \param msg_message_t    input - message object.
2379  * \param bool    input - read status to be set.
2380  *
2381  * \return Return Type (int(MSG_ERROR_T)) \n
2382  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
2383  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
2384  *
2385  * \par Prospective clients:
2386  * External/Native Apps using Messaging Services.
2387  *
2388  * \par Related functions:
2389  * None
2390  *
2391  * \par Known issues/bugs:
2392  * None
2393  *
2394  * \par Sample code:
2395  * \code
2396  * ...
2397  *
2398  * MSG_HANDLE_T msgHandle = NULL;
2399  * MSG_ERROR_T err = MSG_SUCCESS;
2400  * msg_message_t msg;
2401  *
2402  * ...
2403  *
2404  * err = msg_open_msg_handle(&msgHandle);
2405  *
2406  * ...
2407  *
2408  * err = msg_set_read_status(msg, true);
2409  * if (err != MSG_SUCCESS)
2410  * {
2411  *      sprintf(str, "msg_set_read_status() Fail [%d]", err);
2412  *      print(str);
2413  *
2414  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
2415  * }
2416  * ...
2417  * err = msg_release_message(&msg);
2418  * ...
2419  * \endcode
2420  */
2421 /*================================================================================================*/
2422 int msg_set_read_status(msg_message_t msg, bool read_flag);
2423
2424
2425 /**
2426
2427  * \par Description:
2428  * Return true if the message is read.
2429  *
2430  * \par Purpose:
2431  * This API is used to check if the message object is read.
2432  *
2433  * \par Typical use case:
2434  * Read status can be checked using this API.
2435  *
2436  * \par Method of function operation:
2437  * Checks if message object is read and returns bool.
2438  *
2439  * \par Sync (or) Async:
2440  * This is a Synchronous API.
2441  *
2442  * \par Important notes:
2443  * - None
2444  *
2445  * \param msg_message_t    input - message object.
2446  *
2447  * \return Return Type (bool) \n
2448  * - true       - If message object is read \n
2449  * - false - If message object is not read.
2450  *
2451  * \par Prospective clients:
2452  * External/Native Apps using Messaging Services.
2453  *
2454  * \par Related functions:
2455  * None
2456  *
2457  * \par Known issues/bugs:
2458  * None
2459  *
2460  * \par Sample code:
2461  * \code
2462  * ...
2463  *
2464  * MSG_HANDLE_T msgHandle = NULL;
2465  * MSG_ERROR_T err = MSG_SUCCESS;
2466  * msg_message_t msg;
2467  * int msgId;
2468  *
2469  * ...
2470  *
2471  * err = msg_open_msg_handle(&msgHandle);
2472  *
2473  * ...
2474  *
2475  * if( msg_is_read(msgInfo) )
2476  * {
2477  *      sprintf(str, "Message object is read");
2478  *      print(str);
2479  * }
2480  *...
2481  * err = msg_release_message(&msg);
2482  * ...
2483  * \endcode
2484  */
2485 /*================================================================================================*/
2486 bool msg_is_read(msg_message_t msg);
2487
2488
2489 /**
2490
2491  * \par Description:
2492  * Set message protect status to protect_flag.
2493  *
2494  * \par Purpose:
2495  * This API is used to set message protect status to protect_flag.
2496  *
2497  * \par Typical use case:
2498  * Message protect status can be set using this API.
2499  *
2500  * \par Method of function operation:
2501  * Set the bProtected member of msg_message_t to the passed protect_flag.
2502  *
2503  * \par Sync (or) Async:
2504  * This is a Synchronous API.
2505  *
2506  * \par Important notes:
2507  * - If msg is NULL, no action is done
2508  * - If msg is invalid, behavior is undefined
2509  *
2510  * \param msg_message_t    input - message object.
2511  * \param bool    input - protect status to be set.
2512  *
2513  * \return Return Type (int(MSG_ERROR_T)) \n
2514  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
2515  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
2516  *
2517  * \par Prospective clients:
2518  * External/Native Apps using Messaging Services.
2519  *
2520  * \par Related functions:
2521  * None
2522  *
2523  * \par Known issues/bugs:
2524  * None
2525  *
2526  * \par Sample code:
2527  * \code
2528  * ...
2529  *
2530  * MSG_HANDLE_T msgHandle = NULL;
2531  * MSG_ERROR_T err = MSG_SUCCESS;
2532  * msg_message_t msg;
2533  *
2534  * ...
2535  *
2536  * err = msg_open_msg_handle(&msgHandle);
2537  *
2538  * ...
2539  *
2540  * err = msg_set_protect_status(msg, true);
2541  * if (err != MSG_SUCCESS)
2542  * {
2543  *      sprintf(str, "msg_set_protect_status() Fail [%d]", err);
2544  *      print(str);
2545  *
2546  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
2547  * }
2548  * ...
2549  * err = msg_release_message(&msg);
2550  * ...
2551  * \endcode
2552  */
2553 /*================================================================================================*/
2554 int msg_set_protect_status(msg_message_t msg, bool protect_flag);
2555
2556
2557 /**
2558
2559  * \par Description:
2560  * Return true if the message is protected.
2561  *
2562  * \par Purpose:
2563  * This API is used to check if the message object is protected.
2564  *
2565  * \par Typical use case:
2566  * Protected status can be checked using this API.
2567  *
2568  * \par Method of function operation:
2569  * Checks if message object is protected and returns bool.
2570  *
2571  * \par Sync (or) Async:
2572  * This is a Synchronous API.
2573  *
2574  * \par Important notes:
2575  * - None
2576  *
2577  * \param msg_message_t    input - message object.
2578  *
2579  * \return Return Type (bool) \n
2580  * - true       - If message object is protected \n
2581  * - false - If message object is not protected.
2582  *
2583  * \par Prospective clients:
2584  * External/Native Apps using Messaging Services.
2585  *
2586  * \par Related functions:
2587  * None
2588  *
2589  * \par Known issues/bugs:
2590  * None
2591  *
2592  * \par Sample code:
2593  * \code
2594  * ...
2595  *
2596  * MSG_HANDLE_T msgHandle = NULL;
2597  * MSG_ERROR_T err = MSG_SUCCESS;
2598  * msg_message_t msg;
2599  * int msgId;
2600  *
2601  * ...
2602  *
2603  * err = msg_open_msg_handle(&msgHandle);
2604  *
2605  * ...
2606  *
2607  * if( msg_is_protected(msgInfo) )
2608  * {
2609  *      sprintf(str, "Message object is protected");
2610  *      print(str);
2611  * }
2612  *...
2613  * err = msg_release_message(&msg);
2614  * ...
2615  * \endcode
2616  */
2617 /*================================================================================================*/
2618 bool msg_is_protected(msg_message_t msg);
2619
2620
2621 /**
2622
2623  * \par Description:
2624  * Set message backup status to backup_flag.
2625  *
2626  * \par Purpose:
2627  * This API is used to set message backup status to backup_flag.
2628  *
2629  * \par Typical use case:
2630  * Message backup status can be set using this API.
2631  *
2632  * \par Method of function operation:
2633  * Set the bBackup member of msg_message_t to the passed backup_flag.
2634  *
2635  * \par Sync (or) Async:
2636  * This is a Synchronous API.
2637  *
2638  * \par Important notes:
2639  * - If msg is NULL, no action is done
2640  * - If msg is invalid, behavior is undefined
2641  *
2642  * \param msg_message_t    input - message object.
2643  * \param bool    input - backup status to be set.
2644  *
2645  * \return Return Type (int(MSG_ERROR_T)) \n
2646  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
2647  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
2648  *
2649  * \par Prospective clients:
2650  * External/Native Apps using Messaging Services.
2651  *
2652  * \par Related functions:
2653  * None
2654  *
2655  * \par Known issues/bugs:
2656  * None
2657  *
2658  * \par Sample code:
2659  * \code
2660  * ...
2661  *
2662  * MSG_HANDLE_T msgHandle = NULL;
2663  * MSG_ERROR_T err = MSG_SUCCESS;
2664  * msg_message_t msg;
2665  *
2666  * ...
2667  *
2668  * err = msg_open_msg_handle(&msgHandle);
2669  *
2670  * ...
2671  *
2672  * err = msg_set_backup_status(msg, true);
2673  * if (err != MSG_SUCCESS)
2674  * {
2675  *      sprintf(str, "msg_set_backup_status() Fail [%d]", err);
2676  *      print(str);
2677  *
2678  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
2679  * }
2680  * ...
2681  * err = msg_release_message(&msg);
2682  * ...
2683  * \endcode
2684  */
2685 /*================================================================================================*/
2686 int msg_set_backup_status(msg_message_t opq_msg, bool backup_flag);
2687
2688
2689 /**
2690
2691  * \par Description:
2692  * Return true if the message is a backup.
2693  *
2694  * \par Purpose:
2695  * This API is used to check if the message object is a backup.
2696  *
2697  * \par Typical use case:
2698  * Backup status can be checked using this API.
2699  *
2700  * \par Method of function operation:
2701  * Checks if message object is a backup and returns bool.
2702  *
2703  * \par Sync (or) Async:
2704  * This is a Synchronous API.
2705  *
2706  * \par Important notes:
2707  * - None
2708  *
2709  * \param msg_message_t    input - message object.
2710  *
2711  * \return Return Type (bool) \n
2712  * - true       - If message object is a backup \n
2713  * - false - If message object is not a backup.
2714  *
2715  * \par Prospective clients:
2716  * External/Native Apps using Messaging Services.
2717  *
2718  * \par Related functions:
2719  * None
2720  *
2721  * \par Known issues/bugs:
2722  * None
2723  *
2724  * \par Sample code:
2725  * \code
2726  * ...
2727  *
2728  * MSG_HANDLE_T msgHandle = NULL;
2729  * MSG_ERROR_T err = MSG_SUCCESS;
2730  * msg_message_t msg;
2731  * int msgId;
2732  *
2733  * ...
2734  *
2735  * err = msg_open_msg_handle(&msgHandle);
2736  *
2737  * ...
2738  *
2739  * if( msg_is_backup(msgInfo) )
2740  * {
2741  *      sprintf(str, "Message object is a backup");
2742  *      print(str);
2743  * }
2744  *...
2745  * err = msg_release_message(&msg);
2746  * ...
2747  * \endcode
2748  */
2749 /*================================================================================================*/
2750 bool msg_is_backup(msg_message_t opq_msg);
2751
2752
2753 /**
2754
2755  * \par Description:
2756  * Set message priority to priority.
2757  *
2758  * \par Purpose:
2759  * This API is used to set message priority to priority.
2760  *
2761  * \par Typical use case:
2762  * Message priority can be set using this API.
2763  *
2764  * \par Method of function operation:
2765  * Set the priority member of msg_message_t to the passed priority.
2766  *
2767  * \par Sync (or) Async:
2768  * This is a Synchronous API.
2769  *
2770  * \par Important notes:
2771  * - If msg is NULL, no action is done
2772  * - If msg is invalid, behavior is undefined
2773  *
2774  * \param msg_message_t    input - message object.
2775  * \param bool    input - priority status to be set.
2776  *
2777  * \return Return Type (int(MSG_ERROR_T)) \n
2778  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
2779  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
2780  *
2781  * \par Prospective clients:
2782  * External/Native Apps using Messaging Services.
2783  *
2784  * \par Related functions:
2785  * None
2786  *
2787  * \par Known issues/bugs:
2788  * None
2789  *
2790  * \par Sample code:
2791  * \code
2792  * ...
2793  *
2794  * MSG_HANDLE_T msgHandle = NULL;
2795  * MSG_ERROR_T err = MSG_SUCCESS;
2796  * msg_message_t msg;
2797  *
2798  * ...
2799  *
2800  * err = msg_open_msg_handle(&msgHandle);
2801  *
2802  * ...
2803  *
2804  * err = msg_set_priority_info(msgInfo, MSG_MESSAGE_PRIORITY_NORMAL);
2805  * if (err != MSG_SUCCESS)
2806  * {
2807  *      sprintf(str, "msg_set_priority_info() Fail [%d]", err);
2808  *      print(str);
2809  *
2810  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
2811  * }
2812  * ...
2813  * err = msg_release_message(&msg);
2814  * ...
2815  * \endcode
2816  */
2817 /*================================================================================================*/
2818 int msg_set_priority_info(msg_message_t msg, MSG_PRIORITY_TYPE_T priority);
2819
2820
2821 /**
2822
2823  * \par Description:
2824  * Return priority value in message object.
2825  *
2826  * \par Purpose:
2827  * This API is used for getting the priority field of the message object
2828  *
2829  * \par Typical use case:
2830  * Message priority can be got using this API.
2831  *
2832  * \par Method of function operation:
2833  * Returns the priority member of msg_message_t.
2834  *
2835  * \par Sync (or) Async:
2836  * This is a Synchronous API.
2837  *
2838  * \par Important notes:
2839  * - If msg is invalid, behavior is undefined
2840  *
2841  * \param msg_message_t    input - message object.
2842  *
2843  * \return Return Type int (MSG_ERROR_T when negative, enum _MSG_PRIORITY_TYPE_E) \n
2844  * - positive int                                               enum _MSG_PRIORITY_TYPE_E.
2845  * - MSG_ERR_NULL_POINTER                               msg is NULL.
2846  *
2847  * \par Prospective clients:
2848  * External/Native Apps using Messaging Services.
2849  *
2850  * \par Related functions:
2851  * None
2852  *
2853  * \par Known issues/bugs:
2854  * None
2855  *
2856  * \par Sample code:
2857  * \code
2858  * ...
2859  *
2860  * MSG_HANDLE_T msgHandle = NULL;
2861  * MSG_ERROR_T err = MSG_SUCCESS;
2862  * msg_message_t msg;
2863  * int priority;
2864  *
2865  * ...
2866  *
2867  * err = msg_open_msg_handle(&msgHandle);
2868  *
2869  * ...
2870  *
2871  * msg_message_t msg = msg_new_message();
2872  * MSG_SENDINGOPT_S sendOpt = {0, };
2873  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
2874  * ...
2875  * priority = msg_get_priority_info(msg);
2876  * sprintf(str, "msg_get_priority_info() priority [%d]", priority);
2877  * print(str);
2878  * ..
2879  * err = msg_release_message(&msg);
2880  * ...
2881  * \endcode
2882  */
2883 /*================================================================================================*/
2884 int msg_get_priority_info(msg_message_t msg);
2885
2886
2887 /**
2888
2889  * \par Description:
2890  * Set message direction to direction.
2891  *
2892  * \par Purpose:
2893  * This API is used to set message direction to direction.
2894  *
2895  * \par Typical use case:
2896  * Message direction can be set using this API.
2897  *
2898  * \par Method of function operation:
2899  * Set the direction member of msg_message_t to the passed direction.
2900  *
2901  * \par Sync (or) Async:
2902  * This is a Synchronous API.
2903  *
2904  * \par Important notes:
2905  * - If msg is NULL, no action is done
2906  * - If msg is invalid, behavior is undefined
2907  *
2908  * \param msg_message_t    input - message object.
2909  * \param int    input - defined in enum _MSG_DIRECTION_TYPE_E.
2910  *
2911  * \return Return Type (int(MSG_ERROR_T)) \n
2912  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
2913  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
2914  *
2915  * \par Prospective clients:
2916  * External/Native Apps using Messaging Services.
2917  *
2918  * \par Related functions:
2919  * None
2920  *
2921  * \par Known issues/bugs:
2922  * None
2923  *
2924  * \par Sample code:
2925  * \code
2926  * ...
2927  *
2928  * MSG_HANDLE_T msgHandle = NULL;
2929  * MSG_ERROR_T err = MSG_SUCCESS;
2930  * msg_message_t msg;
2931  *
2932  * ...
2933  *
2934  * err = msg_open_msg_handle(&msgHandle);
2935  *
2936  * ...
2937  *
2938  * err = msg_set_direction_info(msgInfo, MSG_DIRECTION_TYPE_MT);
2939  * if (err != MSG_SUCCESS)
2940  * {
2941  *      sprintf(str, "msg_set_direction_info() Fail [%d]", err);
2942  *      print(str);
2943  *
2944  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
2945  * }
2946  * ...
2947  * err = msg_release_message(&msg);
2948  * ...
2949  * \endcode
2950  */
2951 /*================================================================================================*/
2952 int msg_set_direction_info(msg_message_t msg, MSG_DIRECTION_TYPE_T direction);
2953
2954
2955 /**
2956
2957  * \par Description:
2958  * Return direction information in message object.
2959  *
2960  * \par Purpose:
2961  * This API is used for getting the direction information in message object.
2962  *
2963  * \par Typical use case:
2964  * Message direction can be got using this API.
2965  *
2966  * \par Method of function operation:
2967  * Returns the direction member of msg_message_t.
2968  *
2969  * \par Sync (or) Async:
2970  * This is a Synchronous API.
2971  *
2972  * \par Important notes:
2973  * - If msg is invalid, behavior is undefined
2974  *
2975  * \param msg_message_t    input - message object.
2976  *
2977  * \return Return Type int (MSG_ERROR_T when negative, enum _MSG_DIRECTION_TYPE_E when positive) \n
2978  * - positive int                                               enum _MSG_DIRECTION_TYPE_E.
2979  * - MSG_ERR_NULL_POINTER                               msg is NULL.
2980  *
2981  * \par Prospective clients:
2982  * External/Native Apps using Messaging Services.
2983  *
2984  * \par Related functions:
2985  * None
2986  *
2987  * \par Known issues/bugs:
2988  * None
2989  *
2990  * \par Sample code:
2991  * \code
2992  * ...
2993  *
2994  * MSG_HANDLE_T msgHandle = NULL;
2995  * MSG_ERROR_T err = MSG_SUCCESS;
2996  * msg_message_t msg;
2997  * int direction;
2998  *
2999  * ...
3000  *
3001  * err = msg_open_msg_handle(&msgHandle);
3002  *
3003  * ...
3004  *
3005  * msg_message_t msg = msg_new_message();
3006  * MSG_SENDINGOPT_S sendOpt = {0, };
3007  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
3008  * ...
3009  * direction = msg_get_direction_info(msg);
3010  * sprintf(str, "msg_get_direction_info() direction [%d]", direction);
3011  * print(str);
3012  * ..
3013  * err = msg_release_message(&msg);
3014  * ...
3015  * \endcode
3016  */
3017 /*================================================================================================*/
3018 int msg_get_direction_info(msg_message_t msg);
3019
3020
3021 /**
3022
3023  * \par Description:
3024  * Set message port to dst_prt and src_port.
3025  *
3026  * \par Purpose:
3027  * This API is used to set message port to dst_prt and src_port.
3028  *
3029  * \par Typical use case:
3030  * Message source and destinatin ports are used in case of Push message.
3031  *
3032  * \par Method of function operation:
3033  * Set the msgPort member of msg_message_t to the passed source and destination port.
3034  *
3035  * \par Sync (or) Async:
3036  * This is a Synchronous API.
3037  *
3038  * \par Important notes:
3039  * - If msg is NULL, no action is done
3040  * - If msg is invalid, behavior is undefined
3041  *
3042  * \param msg_message_t    input - message object.
3043  * \param src_port is the port of origin.
3044  * \param dst_port is the destination port for recipient.
3045  *
3046  * \return Return Type (int(MSG_ERROR_T)) \n
3047  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
3048  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
3049  *
3050  * \par Prospective clients:
3051  * External/Native Apps using Messaging Services.
3052  *
3053  * \par Related functions:
3054  * None
3055  *
3056  * \par Known issues/bugs:
3057  * None
3058  *
3059  * \par Sample code:
3060  * \code
3061  * ...
3062  *
3063  * MSG_HANDLE_T msgHandle = NULL;
3064  * MSG_ERROR_T err = MSG_SUCCESS;
3065  * msg_message_t msg;
3066  *
3067  * ...
3068  *
3069  * err = msg_open_msg_handle(&msgHandle);
3070  *
3071  * ...
3072  *
3073  * err = msg_set_port(msg, 656, 656);
3074  * if (err != MSG_SUCCESS)
3075  * {
3076  *      sprintf(str, "msg_set_port() Fail [%d]", err);
3077  *      print(str);
3078  *
3079  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
3080  * }
3081  * ...
3082  * err = msg_release_message(&msg);
3083  * ...
3084  * \endcode
3085  */
3086 /*================================================================================================*/
3087 int msg_set_port(msg_message_t msg, unsigned short dst_port, unsigned short src_port);
3088
3089
3090 /**
3091
3092  * \par Description:
3093  * Return destination port number in message object.
3094  *
3095  * \par Purpose:
3096  * This API is used for getting destination port number in message object.
3097  *
3098  * \par Typical use case:
3099  * Recipient destinatin port be got using this API.
3100  *
3101  * \par Method of function operation:
3102  * Returns the destination port  from msgPort member of msg_message_t.
3103  *
3104  * \par Sync (or) Async:
3105  * This is a Synchronous API.
3106  *
3107  * \par Important notes:
3108  * - If msg is invalid, behavior is undefined
3109  *
3110  * \param msg_message_t    input - message object.
3111  *
3112  * \return Return Type (int (MSG_ERROR_T when negative, destination port number when positive)) \n
3113  * - positive int                                               Destination port
3114  * - MSG_ERR_NULL_POINTER                               msg is NULL.
3115  *
3116  * \par Prospective clients:
3117  * External/Native Apps using Messaging Services.
3118  *
3119  * \par Related functions:
3120  * None
3121  *
3122  * \par Known issues/bugs:
3123  * None
3124  *
3125  * \par Sample code:
3126  * \code
3127  * ...
3128  *
3129  * MSG_HANDLE_T msgHandle = NULL;
3130  * MSG_ERROR_T err = MSG_SUCCESS;
3131  * msg_message_t msg;
3132  * int dest_port;
3133  *
3134  * ...
3135  *
3136  * err = msg_open_msg_handle(&msgHandle);
3137  *
3138  * ...
3139  *
3140  * msg_message_t msg = msg_new_message();
3141  * MSG_SENDINGOPT_S sendOpt = {0, };
3142  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
3143  * ...
3144  * dest_port = msg_get_dest_port(msg);
3145  * sprintf(str, "msg_get_dest_port() dest_port [%d]", dest_port);
3146  * print(str);
3147  * ..
3148  * err = msg_release_message(&msg);
3149  * ...
3150  * \endcode
3151  */
3152 /*================================================================================================*/
3153 int msg_get_dest_port(msg_message_t msg);
3154
3155
3156 /**
3157
3158  * \par Description:
3159  * Return source port number in message object.
3160  *
3161  * \par Purpose:
3162  * This API is used for getting source port number in message object.
3163  *
3164  * \par Typical use case:
3165  * Recipient source port be got using this API.
3166  *
3167  * \par Method of function operation:
3168  * Returns the source port  from msgPort member of msg_message_t.
3169  *
3170  * \par Sync (or) Async:
3171  * This is a Synchronous API.
3172  *
3173  * \par Important notes:
3174  * - If msg is invalid, behavior is undefined
3175  *
3176  * \param msg_message_t    input - message object.
3177  *
3178  * \return Return Type int (MSG_ERROR_T when negative, destination port number when positive) \n
3179  * - positive int                                               source port.
3180  * - MSG_ERR_NULL_POINTER                               msg is NULL.
3181  *
3182  * \par Prospective clients:
3183  * External/Native Apps using Messaging Services.
3184  *
3185  * \par Related functions:
3186  * None
3187  *
3188  * \par Known issues/bugs:
3189  * None
3190  *
3191  * \par Sample code:
3192  * \code
3193  * ...
3194  *
3195  * MSG_HANDLE_T msgHandle = NULL;
3196  * MSG_ERROR_T err = MSG_SUCCESS;
3197  * msg_message_t msg;
3198  * int source_port;
3199  *
3200  * ...
3201  *
3202  * err = msg_open_msg_handle(&msgHandle);
3203  *
3204  * ...
3205  *
3206  * msg_message_t msg = msg_new_message();
3207  * MSG_SENDINGOPT_S sendOpt = {0, };
3208  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
3209  * ...
3210  * source_port = msg_get_src_port(msg);
3211  * sprintf(str, "msg_get_src_port() source_port [%d]", source_port);
3212  * print(str);
3213  * ..
3214  * err = msg_release_message(&msg);
3215  * ...
3216  * \endcode
3217  */
3218 /*================================================================================================*/
3219 int msg_get_src_port(msg_message_t msg);
3220
3221
3222 /**
3223
3224  * \par Description:
3225  * Set scheduled time to time_to_send, which is used for scheduled send.
3226  *
3227  * \par Purpose:
3228  * This API is used to set scheduled time to time_to_send, which is used for scheduled send.
3229  *
3230  * \par Typical use case:
3231  * Used to set Schedule Message feature on Message object
3232  *
3233  * \par Method of function operation:
3234  * Set the scheduledTime member of msg_message_t to the passed time_to_send.
3235  *
3236  * \par Sync (or) Async:
3237  * This is a Synchronous API.
3238  *
3239  * \par Important notes:
3240  * - If msg is NULL, no action is done
3241  * - If msg is invalid, behavior is undefined
3242  *
3243  * \param msg_message_t    input - message object.
3244  * \param int    input - defined in enum _MSG_DIRECTION_TYPE_E.
3245  *
3246  * \return Return Type (int(MSG_ERROR_T)) \n
3247  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
3248  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
3249  *
3250  * \par Prospective clients:
3251  * External/Native Apps using Messaging Services.
3252  *
3253  * \par Related functions:
3254  * None
3255  *
3256  * \par Known issues/bugs:
3257  * None
3258  *
3259  * \par Sample code:
3260  * \code
3261  * ...
3262  *
3263  * MSG_HANDLE_T msgHandle = NULL;
3264  * MSG_ERROR_T err = MSG_SUCCESS;
3265  * msg_message_t msg;
3266  * time_t scheduledTime;
3267  *
3268  * ...
3269  *
3270  * err = msg_open_msg_handle(&msgHandle);
3271  *
3272  * ...
3273  *
3274  * time(&scheduledTime);
3275  *
3276  * err = msg_set_scheduled_time(msgInfo, scheduledTime);
3277  * if (err != MSG_SUCCESS)
3278  * {
3279  *      sprintf(str, "msg_set_scheduled_time() Fail [%d]", err);
3280  *      print(str);
3281  *
3282  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
3283  * }
3284  * ...
3285  * err = msg_release_message(&msg);
3286  * ...
3287  * \endcode
3288  */
3289 /*================================================================================================*/
3290 int msg_set_scheduled_time(msg_message_t msg, time_t time_to_send);
3291
3292
3293
3294 /**
3295
3296  * \par Description:
3297  * Return pointer to scheduled time in message object, which can be used for ctime(time_t*) parameter
3298  *
3299  * \par Purpose:
3300  * This API is used for getting the scheduled time in message object.
3301  *
3302  * \par Typical use case:
3303  * Used to get Schedule Message feature on Message object
3304  *
3305  * \par Method of function operation:
3306  * Returns the scheduledTime member of msg_message_t.
3307  *
3308  * \par Sync (or) Async:
3309  * This is a Synchronous API.
3310  *
3311  * \par Important notes:
3312  * - If msg is invalid, behavior is undefined
3313  *
3314  * \param msg_message_t    input - message object.
3315  *
3316  * \return Return Type time_t \n
3317  * - time_t                                             Message scheduled time.
3318  *
3319  * \par Prospective clients:
3320  * External/Native Apps using Messaging Services.
3321  *
3322  * \par Related functions:
3323  * None
3324  *
3325  * \par Known issues/bugs:
3326  * None
3327  *
3328  * \par Sample code:
3329  * \code
3330  * ...
3331  *
3332  * MSG_HANDLE_T msgHandle = NULL;
3333  * MSG_ERROR_T err = MSG_SUCCESS;
3334  * msg_message_t msg;
3335  * time_t time_to_send;
3336  *
3337  * ...
3338  *
3339  * err = msg_open_msg_handle(&msgHandle);
3340  *
3341  * ...
3342  *
3343  * msg_message_t msg = msg_new_message();
3344  * MSG_SENDINGOPT_S sendOpt = {0, };
3345  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
3346  * ...
3347  * time_to_send = msg_get_scheduled_time(msg);
3348  * sprintf(str, "msg_get_scheduled_time() time_to_send [%d]", time_to_send);
3349  * print(str);
3350  * ..
3351  * err = msg_release_message(&msg);
3352  * ...
3353  * \endcode
3354  */
3355 /*================================================================================================*/
3356 time_t* msg_get_scheduled_time(msg_message_t msg);
3357
3358
3359
3360 /**
3361
3362  * \par Description:
3363  * Get attachment count from MMS message.
3364  *
3365  * \par Purpose:
3366  * This API is used for getting the attachment count in message object.
3367  *
3368  * \par Typical use case:
3369  * Used to get attachment count feature on Message object
3370  *
3371  * \par Method of function operation:
3372  * Returns the attachCount member of msg_message_t.
3373  *
3374  * \par Sync (or) Async:
3375  * This is a Synchronous API.
3376  *
3377  * \par Important notes:
3378  * - If msg is invalid, behavior is undefined
3379  *
3380  * \param msg_message_t    input - message object.
3381  *
3382  * \return Return Type int \n
3383  * - int                                                Message attachment count.
3384  *
3385  * \par Prospective clients:
3386  * External/Native Apps using Messaging Services.
3387  *
3388  * \par Related functions:
3389  * None
3390  *
3391  * \par Known issues/bugs:
3392  * None
3393  *
3394  * \par Sample code:
3395  * \code
3396  * ...
3397  *
3398  * MSG_HANDLE_T msgHandle = NULL;
3399  * MSG_ERROR_T err = MSG_SUCCESS;
3400  * msg_message_t msg;
3401  * int attach_count;
3402  *
3403  * ...
3404  *
3405  * err = msg_open_msg_handle(&msgHandle);
3406  *
3407  * ...
3408  *
3409  * msg_message_t msg = msg_new_message();
3410  * MSG_SENDINGOPT_S sendOpt = {0, };
3411  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
3412  * ...
3413  * attach_count = msg_get_attachment_count(msg);
3414  * sprintf(str, "msg_get_attachment_count() attach_count [%d]", attach_count);
3415  * print(str);
3416  * ..
3417  * err = msg_release_message(&msg);
3418  * ...
3419  * \endcode
3420  */
3421 /*================================================================================================*/
3422 int msg_get_attachment_count(msg_message_t opq_msg);
3423
3424
3425 /**
3426
3427  * \par Description:
3428  * Returns the thumbnail path field of the message object. This API is used for MMS.
3429  *
3430  * \par Purpose:
3431  * This API is used for getting the thumbnail path field of the message object
3432  *
3433  * \par Typical use case:
3434  * MMS message object may contain thumbnail path field, this API enables to get the same.
3435  *
3436  * \par Method of function operation:
3437  * Returns the thumbnail path member of msg_message_t.
3438  *
3439  * \par Sync (or) Async:
3440  * This is a Synchronous API.
3441  *
3442  * \par Important notes:
3443  * - If msg is invalid, behavior is undefined
3444  *
3445  * \param msg_message_t    input - message object.
3446  *
3447  * \return Return Type (const char*) \n
3448  * - const char - MMS message thumbnail path \n
3449  * - NULL       -       Message object/thumbnail path field is NULL.
3450  *
3451  * \par Prospective clients:
3452  * External/Native Apps using Messaging Services.
3453  *
3454  * \par Related functions:
3455  * None
3456  *
3457  * \par Known issues/bugs:
3458  * None
3459  *
3460  * \par Sample code:
3461  * \code
3462  * ...
3463  *
3464  * MSG_HANDLE_T msgHandle = NULL;
3465  * MSG_ERROR_T err = MSG_SUCCESS;
3466  * msg_message_t msg;
3467  * char* msg_thumbnail_path;
3468  *
3469  * ...
3470  *
3471  * err = msg_open_msg_handle(&msgHandle);
3472  *
3473  * ...
3474  *
3475  * msg_message_t msg = msg_new_message();
3476  * MSG_SENDINGOPT_S sendOpt = {0, };
3477  * msg_get_message(hMsgHandle, 1, msg, &sendOpt);
3478  * ...
3479  * msg_thumbnail_path = msg_get_thumbnail_path(msg);
3480  * if(msg_subject != NULL && strlen(msg_subject) > 0)
3481  * {
3482  *      sprintf(str, "msg_get_thumbnail_path() msg_thumbnail_path [%s]", msg_thumbnail_path);
3483  *      print(str);
3484  * }
3485  * ..
3486  * err = msg_release_message(&msg);
3487  * ...
3488  * \endcode
3489  */
3490 /*================================================================================================*/
3491 const char* msg_get_thumbnail_path(msg_message_t opq_msg);
3492
3493
3494
3495 /**
3496
3497  * \par Description:
3498  * Set message data to MMS msg_data. This API is used for constructing MMS data.
3499  *
3500  * \par Purpose:
3501  * This API is used to set the Message data field of the message object to the passed MMS message data.
3502  *
3503  * \par Typical use case:
3504  * Compose the MMS_MESSAGE_DATA_S structure using msg_mms_* API and then this API can be called to set the MMS body.
3505  *
3506  * \par Method of function operation:
3507  * Serialized "size" bytes of mdata to the pData member of the message object.
3508  *
3509  * \par Sync (or) Async:
3510  * This is a Synchronous API.
3511  *
3512  * \par Important notes:
3513  * - If msg is NULL, no action is done
3514  * - If msg is invalid, behavior is undefined
3515  *
3516  * \param msg_message_t         input - message object whose msgId is to be set.
3517  * \param const char*                   input - data to be set.
3518  * \param int                           input - size of mdata to be set to message object
3519  *
3520  * \return Return Type (int(MSG_ERROR_T)) \n
3521  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
3522  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
3523  * - MSG_ERR_INVALID_PARAMETER                  class_type is not one of enum _MSG_CLASS_TYPE_E.
3524  *
3525  * \par Prospective clients:
3526  * External/Native Apps using Messaging Services.
3527  *
3528  * \par Related functions:
3529  * Refer to msg_mms_* APIs.
3530  *
3531  * \par Known issues/bugs:
3532  * None
3533  *
3534  * \par Sample code:
3535  * \code
3536  * ...
3537  *
3538  * MSG_HANDLE_T msgHandle = NULL;
3539  * MSG_ERROR_T err = MSG_SUCCESS;
3540  * MMS_MESSAGE_DATA_S*   mms_data;
3541  *
3542  * ...
3543  *
3544  * err = msg_open_msg_handle(&msgHandle);
3545  * ...
3546  * mms_data = msg_mms_create_message();
3547  * ...
3548  * ...
3549  * err = msg_mms_set_message_body(msgInfo, mms_data);
3550  * if (err != MSG_SUCCESS)
3551  * {
3552  *      sprintf(str, "msg_mms_set_message_body() Fail [%d]", err);
3553  *      print(str);
3554  *
3555  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
3556  * }
3557  * err = msg_mms_destroy_message(mms_data);
3558  * ...
3559  * \endcode
3560  */
3561 /*================================================================================================*/
3562 int msg_mms_set_message_body(msg_message_t msg, const MMS_MESSAGE_DATA_S *msg_data);
3563
3564
3565 /**
3566
3567  * \par Description:
3568  * Return pointer to MMS data in message object.
3569  *
3570  * \par Purpose:
3571  * This API is used for getting pointer to MMS data in message object.
3572  *
3573  * \par Typical use case:
3574  * Get the filled MMS data fromthe Message Object.
3575  *
3576  * \par Method of function operation:
3577  * Returns the storageId member of msg_message_t.
3578  *
3579  * \par Sync (or) Async:
3580  * This is a Synchronous API.
3581  *
3582  * \par Important notes:
3583  * - If msg is invalid, behavior is undefined
3584  *
3585  * \param msg_message_t    input - message object whose msgId is to be set.
3586  * \param MMS_MESSAGE_DATA_S - body is passed by pointer, which contains MMS message data.
3587  *
3588  * \return Return Type (int(MSG_ERROR_T)) \n
3589  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
3590  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
3591  * - MSG_ERR_INVALID_PARAMETER                  class_type is not one of enum _MSG_CLASS_TYPE_E.
3592  *
3593  * \par Prospective clients:
3594  * External/Native Apps using Messaging Services.
3595  *
3596  * \par Related functions:
3597  * None
3598  *
3599  * \par Known issues/bugs:
3600  * None
3601  *
3602  * \par Sample code:
3603  * \code
3604  * ...
3605  *
3606  * MSG_HANDLE_T msgHandle = NULL;
3607  * MSG_ERROR_T err = MSG_SUCCESS;
3608  * msg_message_t msg;
3609  * MMS_MESSAGE_DATA_S   msgBody = {0};
3610  *
3611  * ...
3612  *
3613  * err = msg_open_msg_handle(&msgHandle);
3614  *
3615  * ...
3616  *
3617  * msg_message_t msg = msg_new_message();
3618  * MSG_SENDINGOPT_S sendOpt = {0, };
3619  * msg_get_message(msgHandle, 1, msg, &sendOpt);
3620  *
3621  * ...
3622  * err = msg_mms_get_message_body(msg, &msgBody);
3623  * // access msgBody members using msg_mms_get_* APIs
3624  *
3625  * ..
3626  * err = msg_release_message(&msg);
3627  * ...
3628  * \endcode
3629  */
3630  /*================================================================================================*/
3631 int msg_mms_get_message_body(msg_message_t msg, MMS_MESSAGE_DATA_S *body );
3632
3633
3634 /**
3635
3636  * \par Description:
3637  * Adds a SMIL page to MMS message data.
3638  *
3639  * \par Purpose:
3640  * This API is used for adding a SMIL page to MMS message data.
3641  *
3642  * \par Typical use case:
3643  * Add SMIL Page information to the MMS Message Object.
3644  *
3645  * \par Method of function operation:
3646  * Returns the storageId member of msg_message_t.
3647  *
3648  * \par Sync (or) Async:
3649  * This is a Synchronous API.
3650  *
3651  * \par Important notes:
3652  * The memory for a SMIL page will be allocated and copied in this function. \n
3653  * Applications need to call msg_mms_release_page_list to free the memory. \n
3654  * However, if this function is failed, the memory for a SMIL page is NOT allocated in this function.
3655  *
3656  * \param MMS_MESSAGE_DATA_S    - msg_data is a pointer to MMS message data.
3657  * \param int                                   - duration is time interval to play MMS SMIL page.
3658  *
3659  * \return Return Type (int(MSG_ERROR_T)) \n
3660  * - MMS_PAGE_S*        - Newly added MMS_PAGE_S object is returned \n
3661  *
3662  * \par Prospective clients:
3663  * External/Native Apps using Messaging Services.
3664  *
3665  * \par Related functions:
3666  * None
3667  *
3668  * \par Known issues/bugs:
3669  * None
3670  *
3671  * \par Sample code:
3672  * \code
3673  * ...
3674  *
3675  * MSG_HANDLE_T msgHandle = NULL;
3676  * MSG_ERROR_T err = MSG_SUCCESS;
3677  * MMS_PAGE_S*  page[2];
3678  * MMS_MESSAGE_DATA_S*   mms_data;
3679  *
3680  * ...
3681  *
3682  * err = msg_open_msg_handle(&msgHandle);
3683  *
3684  * ...
3685  *
3686  * mms_data = msg_mms_create_message();
3687  *
3688  * ...
3689  * page[0] = msg_mms_add_page(mms_data, 5440);
3690  *
3691  * ...
3692  * msg_mms_destroy_message(mms_data);
3693  * ...
3694  * \endcode
3695  */
3696  /*================================================================================================*/
3697 MMS_PAGE_S* msg_mms_add_page(MMS_MESSAGE_DATA_S *msg_data, const int duration);
3698
3699
3700 /**
3701
3702  * \par Description:
3703  * Adds a SMIL region to MMS message data.
3704  *
3705  * \par Purpose:
3706  * This API is used for adding a SMIL page to MMS message data.
3707  *
3708  * \par Typical use case:
3709  * Add SMIL Page information to the MMS Message Object.
3710  *
3711  * \par Method of function operation:
3712  * Allocates and assigns MMS_SMIL_REGION to region list member of MMS Message data object.
3713  *
3714  * \par Sync (or) Async:
3715  * This is a Synchronous API.
3716  *
3717  * \par Important notes:
3718  * The memory for a SMIL page will be allocated and copied in this function. \n
3719  * Applications need to call msg_mms_release_page_list to free the memory. \n
3720  * However, if this function is failed, the memory for a SMIL page is NOT allocated in this function.
3721  *
3722  * \param MMS_MESSAGE_DATA_S    - msg_data is a pointer to MMS message data.
3723  * \param const char*                   - szID is a pointer to SMIL region.
3724  * \param const int                             - x coordinate of SMIL region.
3725  * \param const int                             - y coordinate of SMIL region.
3726  * \param const int                             - width of SMIL region.
3727  * \param const int                             - height of SMIL region.
3728  * \param int                                   - background color of SMIL region.
3729  *
3730  * \return Return Type (int(MSG_ERROR_T)) \n
3731  * - MMS_SMIL_REGION*   - Newly added MMS_SMIL_REGION object is returned \n
3732  *
3733  * \par Prospective clients:
3734  * External/Native Apps using Messaging Services.
3735  *
3736  * \par Related functions:
3737  * None
3738  *
3739  * \par Known issues/bugs:
3740  * None
3741  *
3742  * \par Sample code:
3743  * \code
3744  * ...
3745  *
3746  * MSG_HANDLE_T msgHandle = NULL;
3747  * MSG_ERROR_T err = MSG_SUCCESS;
3748  * MMS_PAGE_S*  page[2];
3749  * MMS_MESSAGE_DATA_S*   mms_data;
3750  * MMS_SMIL_REGION *mms_region;
3751  *
3752  * ...
3753  *
3754  * err = msg_open_msg_handle(&msgHandle);
3755  *
3756  * ...
3757  *
3758  * mms_data = msg_mms_create_message();
3759  * ...
3760  * msg_mms_set_rootlayout(mms_data, 100, 100, 0xffffff);
3761  * mms_region = msg_mms_add_region(mms_data, "Image", 0, 50, 100, 50, 0xffffff);
3762  * page[0] = msg_mms_add_page(mms_data, 5440);
3763  *
3764  * ..
3765  * msg_mms_destroy_message(mms_data);
3766  * ...
3767  * \endcode
3768  */
3769  /*================================================================================================*/
3770 MMS_SMIL_REGION* msg_mms_add_region(MMS_MESSAGE_DATA_S *msg_data, const char* szID, const int x, const int y, const int width, const int height, int bgcolor);
3771
3772
3773 /**
3774
3775  * \par Description:
3776  * Adds a media to SMIL page.
3777  *
3778  * \par Purpose:
3779  * This API is used for adding media to SMIL page of the MMS Message Data object.
3780  *
3781  * \par Typical use case:
3782  * Add media to SMIL Page information of the MMS Message Object.
3783  *
3784  * \par Method of function operation:
3785  * Allocates and assigns MMS_MEDIA_S to media list member of MMS Message data object.
3786  *
3787  * \par Sync (or) Async:
3788  * This is a Synchronous API.
3789  *
3790  * \par Important notes:
3791  * The memory for a SMIL page will be allocated and copied in this function. \n
3792  * Applications need to call msg_mms_release_page_list to free the memory. \n
3793  * However, if this function is failed, the memory for a SMIL page is NOT allocated in this function.
3794  *
3795  * \param MMS_PAGE_S*                           - page is a pointer to SMIL page.
3796  * \param const MmsSmilMediaType        - mediatype is a value to point the media category.
3797  * \param const char*                           - regionid is a pointer of region, media to be displayed.
3798  * \param char*                                         - filepath is a pointer of media file location.
3799  *
3800  * \return Return Type (int(MSG_ERROR_T)) \n
3801  * - MMS_MEDIA_S*       - Newly added MMS_MEDIA_S object is returned \n
3802  *
3803  * \par Prospective clients:
3804  * External/Native Apps using Messaging Services.
3805  *
3806  * \par Related functions:
3807  * None
3808  *
3809  * \par Known issues/bugs:
3810  * None
3811  *
3812  * \par Sample code:
3813  * \code
3814  * ...
3815  *
3816  * MSG_HANDLE_T msgHandle = NULL;
3817  * MSG_ERROR_T err = MSG_SUCCESS;
3818  * MMS_PAGE_S*  page[2];
3819  * MMS_MESSAGE_DATA_S*   mms_data;
3820  * MMS_SMIL_REGION *mms_region;
3821  * MMS_MEDIA_S* media[5];
3822  *
3823  * ...
3824  *
3825  * err = msg_open_msg_handle(&msgHandle);
3826  *
3827  * ...
3828  *
3829  * mms_data = msg_mms_create_message();
3830  *
3831  * ...
3832  * page[0] = msg_mms_add_page(mms_data, 5440);
3833  * media [0] = msg_mms_add_media(page[0], MMS_SMIL_MEDIA_IMG, "Image", (char*)"/opt/abc/xyz.jpg");
3834  *
3835  * ..
3836  * msg_mms_destroy_message(mms_data);
3837  * ...
3838  * \endcode
3839  */
3840  /*================================================================================================*/
3841 MMS_MEDIA_S* msg_mms_add_media(MMS_PAGE_S *page, const MmsSmilMediaType mediatype, const char* regionid, char* filepath);
3842
3843
3844 /**
3845
3846  * \par Description:
3847  * Adds an attachment to MMS message data.
3848  *
3849  * \par Purpose:
3850  * This API is used for adding an attachment to MMS message data.
3851  *
3852  * \par Typical use case:
3853  * Adds attachment to SMIL Page information of the MMS Message Object.
3854  *
3855  * \par Method of function operation:
3856  * Adds the filepath to attach list member of MMS Message data object.
3857  *
3858  * \par Sync (or) Async:
3859  * This is a Synchronous API.
3860  *
3861  * \par Important notes:
3862  * The memory for a SMIL page will be allocated and copied in this function. \n
3863  * Applications need to call msg_mms_release_page_list to free the memory. \n
3864  * However, if this function is failed, the memory for a SMIL page is NOT allocated in this function.
3865  *
3866  * \param MMS_PAGE_S*                           - page is a pointer to SMIL page.
3867  * \param const MmsSmilMediaType        - mediatype is a value to point the media category.
3868  * \param const char*                           - regionid is a pointer of region, media to be displayed.
3869  * \param char*                                         - filepath is a pointer of media file location.
3870  *
3871  * \return Return Type (int(MSG_ERROR_T)) \n
3872  * - MMS_MEDIA_S*       - Newly added MMS_MEDIA_S object is returned \n
3873  *
3874  * \par Prospective clients:
3875  * External/Native Apps using Messaging Services.
3876  *
3877  * \par Related functions:
3878  * None
3879  *
3880  * \par Known issues/bugs:
3881  * None
3882  *
3883  * \par Sample code:
3884  * \code
3885  * ...
3886  *
3887  * MSG_HANDLE_T msgHandle = NULL;
3888  * MSG_ERROR_T err = MSG_SUCCESS;
3889  * MMS_MESSAGE_DATA_S*   mms_data;
3890  * MMS_ATTACH_S*                attachment[1];
3891  *
3892  * ...
3893  *
3894  * err = msg_open_msg_handle(&msgHandle);
3895  *
3896  * ...
3897  *
3898  * mms_data = msg_mms_create_message();
3899  *
3900  * ...
3901  * attachment[0] = msg_mms_add_attachment(mms_data, (char*)"/opt/abc/xyz.jpg");
3902  *
3903  * ..
3904  * msg_mms_destroy_message(mms_data);
3905  * ...
3906  * \endcode
3907  */
3908  /*================================================================================================*/
3909 MMS_ATTACH_S* msg_mms_add_attachment(MMS_MESSAGE_DATA_S *msg_data, char *filepath);
3910
3911
3912 /**
3913
3914  * \par Description:
3915  * Adds a SMIL transition information  to MMS message data.
3916  *
3917  * \par Purpose:
3918  * This API is used for adding a SMIL transition information  to MMS message data.
3919  *
3920  * \par Typical use case:
3921  * Adds SMIL transition information of the MMS Message data.
3922  *
3923  * \par Method of function operation:
3924  * Allocates and assigns MMS_SMIL_TRANSITION to transition list member of MMS Message data object.
3925  *
3926  * \par Sync (or) Async:
3927  * This is a Synchronous API.
3928  *
3929  * \par Important notes:
3930  * The memory for a SMIL page will be allocated and copied in this function. \n
3931  * Applications need to call msg_mms_release_page_list to free the memory. \n
3932  * However, if this function is failed, the memory for a SMIL page is NOT allocated in this function.
3933  *
3934  * \param MMS_MESSAGE_DATA_S - msg_data is a pointer to MMS message data.
3935  * \param MMS_SMIL_TRANSITION * - transition is a pointer to SMIL transition information.
3936  *
3937  * \return Return Type (int(MSG_ERROR_T)) \n
3938  * MSG_SUCCESS                  Success in operation.
3939  * MSG_ERR_INVALID_PARAMETER    Parameter is invalid.
3940  *
3941  * \par Prospective clients:
3942  * External/Native Apps using Messaging Services.
3943  *
3944  * \par Related functions:
3945  * None
3946  *
3947  * \par Known issues/bugs:
3948  * None
3949  *
3950  * \par Sample code:
3951  * \code
3952  * ...
3953  *
3954  * MSG_HANDLE_T msgHandle = NULL;
3955  * MSG_ERROR_T err = MSG_SUCCESS;
3956  * MMS_MESSAGE_DATA_S*   mms_data;
3957  *
3958  * ...
3959  *
3960  * err = msg_open_msg_handle(&msgHandle);
3961  *
3962  * ...
3963  *
3964  * mms_data = msg_mms_create_message();
3965  *
3966  * ...
3967  * MMS_SMIL_TRANSITION transition;
3968  * err = msg_mms_add_transition(mms_data, &transition);
3969  * ..
3970  * msg_mms_destroy_message(mms_data);
3971  * ...
3972  * \endcode
3973  */
3974  /*================================================================================================*/
3975 int msg_mms_add_transition(MMS_MESSAGE_DATA_S *msg_data, MMS_SMIL_TRANSITION *transition);
3976
3977
3978 /**
3979
3980  * \par Description:
3981  * Adds SMIL meta information  to MMS message data.
3982  *
3983  * \par Purpose:
3984  * This API is used for adding SMIL meta information  to MMS message data.
3985  *
3986  * \par Typical use case:
3987  * Adds SMIL meta information of the MMS Message data.
3988  *
3989  * \par Method of function operation:
3990  * Allocates and assigns MMS_SMIL_META to meta list member of MMS Message data object.
3991  *
3992  * \par Sync (or) Async:
3993  * This is a Synchronous API.
3994  *
3995  * \par Important notes:
3996  * The memory for a SMIL page will be allocated and copied in this function. \n
3997  * Applications need to call msg_mms_release_page_list to free the memory. \n
3998  * However, if this function is failed, the memory for a SMIL page is NOT allocated in this function.
3999  *
4000  * \param MMS_MESSAGE_DATA_S - msg_data is a pointer to MMS message data.
4001  * \param MMS_SMIL_META * - meta is a pointer to SMIL meta information.
4002  *
4003  * \return Return Type (int(MSG_ERROR_T)) \n
4004  * MSG_SUCCESS                  Success in operation.
4005  * MSG_ERR_INVALID_PARAMETER    Parameter is invalid.
4006  *
4007  * \par Prospective clients:
4008  * External/Native Apps using Messaging Services.
4009  *
4010  * \par Related functions:
4011  * None
4012  *
4013  * \par Known issues/bugs:
4014  * None
4015  *
4016  * \par Sample code:
4017  * \code
4018  * ...
4019  *
4020  * MSG_HANDLE_T msgHandle = NULL;
4021  * MSG_ERROR_T err = MSG_SUCCESS;
4022  * MMS_MESSAGE_DATA_S*   mms_data;
4023  * MMS_SMIL_META meta;
4024  *
4025  * ...
4026  *
4027  * err = msg_open_msg_handle(&msgHandle);
4028  *
4029  * ...
4030  *
4031  * mms_data = msg_mms_create_message();
4032  *
4033  * ...
4034  * MMS_MEDIA_S* media = NULL;
4035  * media = msg_mms_add_meta(mms_data, &meta);
4036  * ...
4037  * msg_mms_destroy_message(mms_data);
4038  * ...
4039  * \endcode
4040  */
4041  /*================================================================================================*/
4042 int msg_mms_add_meta(MMS_MESSAGE_DATA_S *msg_data, MMS_SMIL_META *meta);
4043
4044
4045 /* MMS-1.3-con-601 */
4046 /**
4047
4048  * \par Description:
4049  * Gets a SMIL page information of the current MMS message.
4050  *
4051  * \par Purpose:
4052  * This API is used to get a SMIL page information
4053  *
4054  * \par Typical use case:
4055  * Gets SMIL Page information of the MMS Message Object.
4056  *
4057  * \par Method of function operation:
4058  * Returns the page_idx page from the pagelist member of msg_message_t.
4059  *
4060  * \par Sync (or) Async:
4061  * This is a Synchronous API.
4062  *
4063  * \par Important notes:
4064  * This function MUST be called only after SMIL page is added. \n
4065  *
4066  * \param MMS_MESSAGE_DATA_S - msg_data is a pointer to MMS message data.
4067  * \param int page_idx - page_idx is the index of the SMIL page to be returned.
4068  *
4069  * \return Return Type (MMS_PAGE_S*) \n
4070  * - MMS_PAGE_S*        - page_idx MMS_PAGE_S object is returned \n
4071  *
4072  * \par Prospective clients:
4073  * External/Native Apps using Messaging Services.
4074  *
4075  * \par Related functions:
4076  * None
4077  *
4078  * \par Known issues/bugs:
4079  * None
4080  *
4081  * \par Sample code:
4082  * \code
4083  * ...
4084  *
4085  * MSG_HANDLE_T msgHandle = NULL;
4086  * MSG_ERROR_T err = MSG_SUCCESS;
4087  * MMS_PAGE_S*  page[2];
4088  * MMS_MESSAGE_DATA_S*   mms_data;
4089  *
4090  * ...
4091  *
4092  * err = msg_open_msg_handle(&msgHandle);
4093  *
4094  * ...
4095  *
4096  * mms_data = msg_mms_create_message();
4097  *
4098  * ...
4099  * page[0] = msg_mms_get_page(mms_data, 0);
4100  *
4101  * ...
4102  * msg_mms_destroy_message(mms_data);
4103  * ...
4104  * \endcode
4105  */
4106  /*================================================================================================*/
4107 MMS_PAGE_S*     msg_mms_get_page(MMS_MESSAGE_DATA_S *msg_data, int page_idx);
4108
4109
4110 /**
4111
4112  * \par Description:
4113  * Gets a SMIL region information of the current MMS message.
4114  *
4115  * \par Purpose:
4116  * This API is used to gets a SMIL region information.
4117  *
4118  * \par Typical use case:
4119  * Gets SMIL region information of the current MMS Message Object.
4120  *
4121  * \par Method of function operation:
4122  * Returns the media_idx media from the current media list.
4123  *
4124  * \par Sync (or) Async:
4125  * This is a Synchronous API.
4126  *
4127  * \par Important notes:
4128  * This function MUST be called only after SMIL region is added.
4129  *
4130  * \param MMS_MESSAGE_DATA_S - msg_data is a pointer to MMS message data.
4131  * \param int input - region_idx is the index of the SMIL region to be returned.
4132  *
4133  * \return Return Type (MMS_SMIL_REGION*) \n
4134  * - MMS_SMIL_REGION*   - pointer to MMS_SMIL_REGION structure.
4135  *
4136  * \par Prospective clients:
4137  * External/Native Apps using Messaging Services.
4138  *
4139  * \par Related functions:
4140  * None
4141  *
4142  * \par Known issues/bugs:
4143  * None
4144  *
4145  * \par Sample code:
4146  * \code
4147  * ...
4148  *
4149  * MSG_HANDLE_T msgHandle = NULL;
4150  * MSG_ERROR_T err = MSG_SUCCESS;
4151  * MMS_SMIL_REGION*     region[2];
4152  * MMS_MESSAGE_DATA_S*   mms_data;
4153  *
4154  * ...
4155  *
4156  * err = msg_open_msg_handle(&msgHandle);
4157  *
4158  * ...
4159  *
4160  * mms_data = msg_mms_create_message();
4161  *
4162  * ...
4163  * region[0] = msg_mms_get_smil_region(mms_data, 0);
4164  *
4165  * ...
4166  * msg_mms_destroy_message(mms_data);
4167  * ...
4168  * \endcode
4169  */
4170  /*================================================================================================*/
4171 MMS_SMIL_REGION* msg_mms_get_smil_region(MMS_MESSAGE_DATA_S *msg_data, int region_idx);
4172
4173
4174 /**
4175
4176  * \par Description:
4177  * Gets a media information in a SMIL page of the current MMS message.
4178  *
4179  * \par Purpose:
4180  * This API is used to get a media information in a SMIL page
4181  *
4182  * \par Typical use case:
4183  * Gets media information of the current MMS Message Object.
4184  *
4185  * \par Method of function operation:
4186  * Returns the media_idx media from the current media list.
4187  *
4188  * \par Sync (or) Async:
4189  * This is a Synchronous API.
4190  *
4191  * \par Important notes:
4192  * This function MUST be called only after media is added. \n
4193  *
4194  * \param int input - media_idx is the index of the media to be returned. \n
4195  * \param MMS_PAGE_S* - page  is a pointer to SMIL page.
4196  *
4197  * \return Return Type (MMS_MEDIA_S*) \n
4198  * - MMS_MEDIA_S*       - pointer to MMS_MEDIA_S structure.
4199  *
4200  * \par Prospective clients:
4201  * External/Native Apps using Messaging Services.
4202  *
4203  * \par Related functions:
4204  * None
4205  *
4206  * \par Known issues/bugs:
4207  * None
4208  *
4209  * \par Sample code:
4210  * \code
4211  * ...
4212  *
4213  * MSG_HANDLE_T msgHandle = NULL;
4214  * MSG_ERROR_T err = MSG_SUCCESS;
4215  * MMS_MEDIA_S*         media[2];
4216  * MMS_PAGE_S *page[2];
4217  * MMS_MESSAGE_DATA_S*   mms_data;
4218  *
4219  * ...
4220  *
4221  * err = msg_open_msg_handle(&msgHandle);
4222  *
4223  * ...
4224  *
4225  * mms_data = msg_mms_create_message();
4226  *
4227  * ...
4228  * media[0] = msg_mms_get_media(page, 0);
4229  *
4230  * ...
4231  * msg_mms_destroy_message(mms_data);
4232  * ...
4233  * \endcode
4234  */
4235  /*================================================================================================*/
4236 MMS_MEDIA_S* msg_mms_get_media(MMS_PAGE_S *page, int media_idx);
4237
4238 /**
4239
4240  * \par Description:
4241  * Gets a attachment information of the current MMS message.
4242  *
4243  * \par Purpose:
4244  * This API is used to get a attachment information
4245  *
4246  * \par Typical use case:
4247  * Gets attachment information of the MMS Message Object.
4248  *
4249  * \par Method of function operation:
4250  * Returns the attach_idx attachment from the attachlist member of msg_message_t.
4251  *
4252  * \par Sync (or) Async:
4253  * This is a Synchronous API.
4254  *
4255  * \par Important notes:
4256  * This function MUST be called only after attachment is added. \n
4257  *
4258  * \param MMS_MESSAGE_DATA_S - msg_data is a pointer to MMS message data.
4259  * \param int input - attach_idx is the index of the attachment to be returned.
4260  *
4261  * \return Return Type (MMS_ATTACH_S*) \n
4262  * - MMS_ATTACH_S*      - pointer to MMS_ATTACH_S structure.
4263  *
4264  * \par Prospective clients:
4265  * External/Native Apps using Messaging Services.
4266  *
4267  * \par Related functions:
4268  * None
4269  *
4270  * \par Known issues/bugs:
4271  * None
4272  *
4273  * \par Sample code:
4274  * \code
4275  * ...
4276  *
4277  * MSG_HANDLE_T msgHandle = NULL;
4278  * MSG_ERROR_T err = MSG_SUCCESS;
4279  * MMS_ATTACH_S*        attachment[2];
4280  * MMS_MESSAGE_DATA_S*   mms_data;
4281  *
4282  * ...
4283  *
4284  * err = msg_open_msg_handle(&msgHandle);
4285  *
4286  * ...
4287  *
4288  * mms_data = msg_mms_create_message();
4289  *
4290  * ...
4291  * attachment[0] = msg_mms_get_attachment(mms_data, 0);
4292  *
4293  * ...
4294  * msg_mms_destroy_message(mms_data);
4295  * ...
4296  * \endcode
4297  */
4298  /*================================================================================================*/
4299 MMS_ATTACH_S* msg_mms_get_attachment(MMS_MESSAGE_DATA_S *msg_data, int attach_idx);
4300
4301
4302 /**
4303
4304  * \par Description:
4305  * Gets a SMIL transition information of the current MMS message.
4306  *
4307  * \par Purpose:
4308  * This API is used to get a SMIL transition information.
4309  *
4310  * \par Typical use case:
4311  * Gets SMIL transition information of the current MMS Message Object.
4312  *
4313  * \par Method of function operation:
4314  * Returns the transition_idx transition from the current transition list.
4315  *
4316  * \par Sync (or) Async:
4317  * This is a Synchronous API.
4318  *
4319  * \par Important notes:
4320  *      This function MUST be called only after SMIL transition is added.
4321  *
4322  * \param MMS_MESSAGE_DATA_S - msg_data is a pointer to MMS message data.
4323  * \param int input - transition_idx is the index of the SMIL transition to be returned.
4324  *
4325  * \return Return Type (MMS_SMIL_TRANSITION*) \n
4326  * - MMS_SMIL_TRANSITION*       - pointer to MMS_SMIL_TRANSITION structure.
4327  *
4328  * \par Prospective clients:
4329  * External/Native Apps using Messaging Services.
4330  *
4331  * \par Related functions:
4332  * None
4333  *
4334  * \par Known issues/bugs:
4335  * None
4336  *
4337  * \par Sample code:
4338  * \code
4339  * ...
4340  *
4341  * MSG_HANDLE_T msgHandle = NULL;
4342  * MSG_ERROR_T err = MSG_SUCCESS;
4343  * MMS_MESSAGE_DATA_S*   mms_data;
4344  * ...
4345  *
4346  * err = msg_open_msg_handle(&msgHandle);
4347  *
4348  * ...
4349  *
4350  * mms_data = msg_mms_create_message();
4351  *
4352  * ...
4353  * MMS_SMIL_TRANSITION* pTrans = msg_mms_get_transition(mms_data, 0);
4354  *
4355  * ...
4356  * msg_mms_destroy_message(mms_data);
4357  * ...
4358  * \endcode
4359  */
4360  /*================================================================================================*/
4361 MMS_SMIL_TRANSITION* msg_mms_get_transition(MMS_MESSAGE_DATA_S *msg_data, int transition_idx);
4362
4363
4364 /**
4365
4366  * \par Description:
4367  * Gets a SMIL meta information of the current MMS message.
4368  *
4369  * \par Purpose:
4370  * This API is used to get a SMIL meta information.
4371  *
4372  * \par Typical use case:
4373  * Gets SMIL meta information of the current MMS Message Object.
4374  *
4375  * \par Method of function operation:
4376  * Returns the meta_idx meta from the current meta list.
4377  *
4378  * \par Sync (or) Async:
4379  * This is a Synchronous API.
4380  *
4381  * \par Important notes:
4382  * This function MUST be called only after SMIL meta is added.
4383  *
4384  * \param MMS_MESSAGE_DATA_S - msg_data is a pointer to MMS message data.
4385  * \param int input - meta_idx is the index of the SMIL meta to be returned.
4386  *
4387  * \return Return Type (MMS_SMIL_META*) \n
4388  * - MMS_SMIL_META*     - pointer to MMS_SMIL_META structure.
4389  *
4390  * \par Prospective clients:
4391  * External/Native Apps using Messaging Services.
4392  *
4393  * \par Related functions:
4394  * None
4395  *
4396  * \par Known issues/bugs:
4397  * None
4398  *
4399  * \par Sample code:
4400  * \code
4401  * ...
4402  *
4403  * MSG_HANDLE_T msgHandle = NULL;
4404  * MSG_ERROR_T err = MSG_SUCCESS;
4405  * MMS_MESSAGE_DATA_S*   mms_data;
4406  *
4407  * ...
4408  *
4409  * err = msg_open_msg_handle(&msgHandle);
4410  *
4411  * ...
4412  *
4413  * mms_data = msg_mms_create_message();
4414  *
4415  * ...
4416  * MMS_SMIL_META* pMeta = msg_mms_get_meta(mms_data, 0);
4417  *
4418  * ...
4419  * msg_mms_destroy_message(mms_data);
4420  * ...
4421  * \endcode
4422  */
4423  /*================================================================================================*/
4424 MMS_SMIL_META* msg_mms_get_meta(MMS_MESSAGE_DATA_S *msg_data, int meta_idx);
4425
4426
4427 /**
4428
4429  * \par Description:
4430  * Release a SMIL page list of the current MMS message.
4431  *
4432  * \par Purpose:
4433  * This API is used to release a SMIL page list
4434  *
4435  * \par Typical use case:
4436  * Release SMIL page list of the MMS message object
4437  *
4438  * \par Method of function operation:
4439  * Release SMIL page list of MMS_MESSAGE_DATA_S object
4440  *
4441  * \par Sync (or) Async:
4442  * This is a Synchronous API.
4443  *
4444  * \par Important notes:
4445  * This function MUST be called only after SMIL page is added. \n
4446  *
4447  * \param MMS_MESSAGE_DATA_S    - msg_data is a pointer to MMS message data.
4448  *
4449  * \return Return Type (int(MSG_ERROR_T)) \n
4450  * MSG_SUCCESS                  Success in operation.
4451  * MSG_ERR_NULL_POINTER Parameter is NULL.
4452  *
4453  * \par Prospective clients:
4454  * External/Native Apps using Messaging Services.
4455  *
4456  * \par Related functions:
4457  * None
4458  *
4459  * \par Known issues/bugs:
4460  * None
4461  *
4462  * \par Sample code:
4463  * \code
4464  * ...
4465  *
4466  * MSG_HANDLE_T msgHandle = NULL;
4467  * MSG_ERROR_T err = MSG_SUCCESS;
4468  * MMS_PAGE_S*  page[2];
4469  * MMS_MESSAGE_DATA_S*   mms_data;
4470  *
4471  * ...
4472  *
4473  * err = msg_open_msg_handle(&msgHandle);
4474  *
4475  * ...
4476  *
4477  * mms_data = msg_mms_create_message();
4478  * ...
4479  * page[0] = msg_mms_add_page(mms_data, 5440);
4480  * ...
4481  * page[0] = msg_mms_get_page(0);
4482  *
4483  * msg_mms_release_page_list(mms_data);
4484  * ...
4485  * \endcode
4486  */
4487  /*================================================================================================*/
4488 int msg_mms_release_page_list(MMS_MESSAGE_DATA_S *msg_data);
4489
4490
4491 /**
4492
4493  * \par Description:
4494  * Release a SMIL region list of the current MMS message.
4495  *
4496  * \par Purpose:
4497  * This API is used to release a SMIL region list
4498  *
4499  * \par Typical use case:
4500  * Release SMIL region list of the MMS message object
4501  *
4502  * \par Method of function operation:
4503  * Release SMIL region list of MMS_MESSAGE_DATA_S object
4504  *
4505  * \par Sync (or) Async:
4506  * This is a Synchronous API.
4507  *
4508  * \par Important notes:
4509  * This function MUST be called only after SMIL region is added. \n
4510  *
4511  * \param MMS_MESSAGE_DATA_S    - msg_data is a pointer to MMS message data.
4512  *
4513  * \return Return Type (int(MSG_ERROR_T)) \n
4514  * MSG_SUCCESS                  Success in operation.
4515  * MSG_ERR_NULL_POINTER Parameter is NULL.
4516  *
4517  * \par Prospective clients:
4518  * External/Native Apps using Messaging Services.
4519  *
4520  * \par Related functions:
4521  * None
4522  *
4523  * \par Known issues/bugs:
4524  * None
4525  *
4526  * \par Sample code:
4527  * \code
4528  * ...
4529  *
4530  * MSG_HANDLE_T msgHandle = NULL;
4531  * MSG_ERROR_T err = MSG_SUCCESS;
4532  * MMS_PAGE_S*  page[2];
4533  * MMS_MESSAGE_DATA_S*   mms_data;
4534  * MMS_SMIL_REGION *mms_region;
4535  *
4536  * ...
4537  *
4538  * err = msg_open_msg_handle(&msgHandle);
4539  *
4540  * ...
4541  *
4542  * mms_data = msg_mms_create_message();
4543  * ...
4544  * msg_mms_set_rootlayout(mms_data, 100, 100, 0xffffff);
4545  * mms_region = msg_mms_add_region(mms_data, "Image", 0, 50, 100, 50, 0xffffff);
4546  * page[0] = msg_mms_add_page(mms_data, 5440);
4547  * ...
4548  * msg_mms_release_region_list(mms_data);
4549  * ...
4550  * \endcode
4551  */
4552  /*================================================================================================*/
4553 int msg_mms_release_region_list(MMS_MESSAGE_DATA_S *msg_data);
4554
4555
4556 /**
4557
4558  * \par Description:
4559  * Release an attachment list of the current MMS message.
4560  *
4561  * \par Purpose:
4562  * This API is used to release an attachment list
4563  *
4564  * \par Typical use case:
4565  * Release an attachment list of the MMS message object
4566  *
4567  * \par Method of function operation:
4568  * Release an attachment list of MMS_MESSAGE_DATA_S object
4569  *
4570  * \par Sync (or) Async:
4571  * This is a Synchronous API.
4572  *
4573  * \par Important notes:
4574  * This function MUST be called only after attachment is added. \n
4575  *
4576  * \param MMS_MESSAGE_DATA_S    - msg_data is a pointer to MMS message data.
4577  *
4578  * \return Return Type (int(MSG_ERROR_T)) \n
4579  * MSG_SUCCESS                  Success in operation.
4580  * MSG_ERR_NULL_POINTER Parameter is NULL.
4581  *
4582  * \par Prospective clients:
4583  * External/Native Apps using Messaging Services.
4584  *
4585  * \par Related functions:
4586  * None
4587  *
4588  * \par Known issues/bugs:
4589  * None
4590  *
4591  * \par Sample code:
4592  * \code
4593  * ...
4594  *
4595  * MSG_HANDLE_T msgHandle = NULL;
4596  * MSG_ERROR_T err = MSG_SUCCESS;
4597  * MMS_MESSAGE_DATA_S*   mms_data;
4598  * MMS_ATTACH_S*                attachment[1];
4599  *
4600  * ...
4601  *
4602  * err = msg_open_msg_handle(&msgHandle);
4603  *
4604  * ...
4605  *
4606  * mms_data = msg_mms_create_message();
4607  *
4608  * ...
4609  * attachment[0] = msg_mms_add_attachment(mms_data, (char*)"/opt/abc/xyz.jpg");
4610  *
4611  * ..
4612  * msg_mms_release_attachment_list(mms_data);
4613  * ...
4614  * \endcode
4615  */
4616  /*================================================================================================*/
4617 int msg_mms_release_attachment_list(MMS_MESSAGE_DATA_S *msg_data);
4618
4619
4620 /**
4621
4622  * \par Description:
4623  * Release a SMIL transition list of the current MMS message.
4624  *
4625  * \par Purpose:
4626  * This API is used to release a SMIL transition list
4627  *
4628  * \par Typical use case:
4629  * Release a SMIL transition list of the MMS message object
4630  *
4631  * \par Method of function operation:
4632  * Release a SMIL transition list of MMS_MESSAGE_DATA_S object
4633  *
4634  * \par Sync (or) Async:
4635  * This is a Synchronous API.
4636  *
4637  * \par Important notes:
4638  * This function MUST be called only after SMIL transition is added. \n
4639  *
4640  * \param MMS_MESSAGE_DATA_S    - msg_data is a pointer to MMS message data.
4641  *
4642  * \return Return Type (int(MSG_ERROR_T)) \n
4643  * MSG_SUCCESS                  Success in operation.
4644  * MSG_ERR_NULL_POINTER Parameter is NULL.
4645  *
4646  * \par Prospective clients:
4647  * External/Native Apps using Messaging Services.
4648  *
4649  * \par Related functions:
4650  * None
4651  *
4652  * \par Known issues/bugs:
4653  * None
4654  *
4655  * \par Sample code:
4656  * \code
4657  * ...
4658  *
4659  * MSG_HANDLE_T msgHandle = NULL;
4660  * MSG_ERROR_T err = MSG_SUCCESS;
4661  * MMS_MESSAGE_DATA_S*   mms_data;
4662  * MMS_ATTACH_S*                attachment[1];
4663  *
4664  * ...
4665  *
4666  * err = msg_open_msg_handle(&msgHandle);
4667  *
4668  * ...
4669  *
4670  * mms_data = msg_mms_create_message();
4671  *
4672  * ...
4673  * MMS_SMIL_TRANSITION transition;
4674  * err = msg_mms_add_transition(mms_data, &transition);
4675  * ..
4676  * msg_mms_release_transition_list(mms_data);
4677  * ...
4678  * \endcode
4679  */
4680  /*================================================================================================*/
4681 int msg_mms_release_transition_list(MMS_MESSAGE_DATA_S *msg_data);
4682
4683
4684 /**
4685
4686  * \par Description:
4687  * Release a SMIL meta list of the current MMS message.
4688  *
4689  * \par Purpose:
4690  * This API is used to release a SMIL meta list
4691  *
4692  * \par Typical use case:
4693  * Release a SMIL meta list of the MMS message object
4694  *
4695  * \par Method of function operation:
4696  * Release a SMIL meta list of MMS_MESSAGE_DATA_S object
4697  *
4698  * \par Sync (or) Async:
4699  * This is a Synchronous API.
4700  *
4701  * \par Important notes:
4702  * This function MUST be called only after SMIL meta is added. \n
4703  *
4704  * \param MMS_MESSAGE_DATA_S    - msg_data is a pointer to MMS message data.
4705  *
4706  * \return Return Type (int(MSG_ERROR_T)) \n
4707  * MSG_SUCCESS                  Success in operation.
4708  * MSG_ERR_NULL_POINTER Parameter is NULL.
4709  *
4710  * \par Prospective clients:
4711  * External/Native Apps using Messaging Services.
4712  *
4713  * \par Related functions:
4714  * None
4715  *
4716  * \par Known issues/bugs:
4717  * None
4718  *
4719  * \par Sample code:
4720  * \code
4721  * ...
4722  *
4723  * MSG_HANDLE_T msgHandle = NULL;
4724  * MSG_ERROR_T err = MSG_SUCCESS;
4725  * MMS_MESSAGE_DATA_S*   mms_data;
4726  * MMS_SMIL_META meta;
4727  *
4728  * ...
4729  *
4730  * err = msg_open_msg_handle(&msgHandle);
4731  *
4732  * ...
4733  *
4734  * mms_data = msg_mms_create_message();
4735  *
4736  * ...
4737  * MMS_MEDIA_S* media = NULL;
4738  * media = msg_mms_add_meta(mms_data, &meta);
4739  * ...
4740  * msg_mms_release_meta_list(mms_data);
4741  * ...
4742  * \endcode
4743  */
4744  /*================================================================================================*/
4745 int msg_mms_release_meta_list(MMS_MESSAGE_DATA_S *msg_data);
4746
4747
4748 /**
4749
4750  * \par Description:
4751  * Creates a MMS message data
4752  *
4753  * \par Purpose:
4754  * This API creates a MMS message data
4755  *
4756  * \par Typical use case:
4757  * MMS Message object should be created before adding Page, SMIL, attachment information.
4758  *
4759  * \par Method of function operation:
4760  * Allocates and returns a pointer to MMS_MESSAGE_DATA_S.
4761  *
4762  * \par Sync (or) Async:
4763  * This is a Synchronous API.
4764  *
4765  * \par Important notes:
4766  * The created MMS_MESSAGE_DATA_S object should be explicitly destroyed using msg_mms_destroy_message()
4767  *
4768  * \param None input
4769  *
4770  * \return Return Type (MMS_MESSAGE_DATA_S*) \n
4771  * - MMS_MESSAGE_DATA_S*        - pointer to newly created MMS_MESSAGE_DATA_S structure.
4772  *
4773  * \par Prospective clients:
4774  * External/Native Apps using Messaging Services.
4775  *
4776  * \par Related functions:
4777  * None
4778  *
4779  * \par Known issues/bugs:
4780  * None
4781  *
4782  * \par Sample code:
4783  * \code
4784  * ...
4785  *
4786  * MSG_HANDLE_T msgHandle = NULL;
4787  * MSG_ERROR_T err = MSG_SUCCESS;
4788  *
4789  * ...
4790  *
4791  * err = msg_open_msg_handle(&msgHandle);
4792  *
4793  * ...
4794  *
4795  * mms_data = msg_mms_create_message();
4796  *
4797  * ...
4798  * msg_mms_destroy_message(mms_data);
4799  * ...
4800  * \endcode
4801  */
4802  /*================================================================================================*/
4803 MMS_MESSAGE_DATA_S* msg_mms_create_message(void);
4804
4805
4806 /**
4807
4808  * \par Description:
4809  * Set the MMS root-layout
4810  *
4811  * \par Purpose:
4812  * This API is used for adding a SMIL page to MMS message data.
4813  *
4814  * \par Typical use case:
4815  * Add SMIL Page information to the MMS Message Object.
4816  *
4817  * \par Method of function operation:
4818  * Sets the rootlayout member to the passed root layout.
4819  *
4820  * \par Sync (or) Async:
4821  * This is a Synchronous API.
4822  *
4823  * \par Important notes:
4824  * None
4825  *
4826  * \param MMS_MESSAGE_DATA_S*   - msg is a pointer to mms message data.
4827  * \param const int                             - width of root-layout
4828  * \param const int                             - height of root-layout
4829  * \param int                                   - background color of root-layout
4830  *
4831  * \return Return Type (MMS_SMIL_ROOTLAYOUT*) \n
4832  * - MMS_SMIL_ROOTLAYOUT*       - pointer to MMS_SMIL_ROOTLAYOUT object is returned \n
4833  *
4834  * \par Prospective clients:
4835  * External/Native Apps using Messaging Services.
4836  *
4837  * \par Related functions:
4838  * None
4839  *
4840  * \par Known issues/bugs:
4841  * None
4842  *
4843  * \par Sample code:
4844  * \code
4845  * ...
4846  *
4847  * MSG_HANDLE_T msgHandle = NULL;
4848  * MSG_ERROR_T err = MSG_SUCCESS;
4849  * MMS_MESSAGE_DATA_S*   mms_data;
4850  *
4851  * ...
4852  *
4853  * err = msg_open_msg_handle(&msgHandle);
4854  *
4855  * ...
4856  *
4857  * mms_data = msg_mms_create_message();
4858  * ...
4859  * msg_mms_set_rootlayout(mms_data, 100, 100, 0xffffff);
4860  * ..
4861  * msg_mms_destroy_message(mms_data);
4862  * ...
4863  * \endcode
4864  */
4865  /*================================================================================================*/
4866 MMS_SMIL_ROOTLAYOUT* msg_mms_set_rootlayout(MMS_MESSAGE_DATA_S* msg, const int width, const int height, const int bgcolor);
4867
4868
4869 /**
4870
4871  * \par Description:
4872  * Destroy the created MMS message data.
4873  *
4874  * \par Purpose:
4875  * This API destroys the created MMS message data.
4876  *
4877  * \par Typical use case:
4878  * To free memory allocated with create message API.
4879  *
4880  * \par Method of function operation:
4881  * Frees the memory associated with MMS_MESSAGE_DATA_S object .
4882  *
4883  * \par Sync (or) Async:
4884  * This is a Synchronous API.
4885  *
4886  * \par Important notes:
4887  *This function MUST be called only after MMS message is created by msg_mms_create_message.
4888  *
4889  * \param
4890  * MMS_MESSAGE_DATA_S input - msg is a pointer to MMS message data.
4891  *
4892  * \return Return Type (int(MSG_ERROR_T)) \n
4893  * MSG_SUCCESS                  Success in operation.
4894  * MSG_ERR_NULL_POINTER Parameter is NULL.
4895  *
4896  * \par Prospective clients:
4897  * External/Native Apps using Messaging Services.
4898  *
4899  * \par Related functions:
4900  * None
4901  *
4902  * \par Known issues/bugs:
4903  * None
4904  *
4905  * \par Sample code:
4906  * \code
4907  * ...
4908  *
4909  * MSG_HANDLE_T msgHandle = NULL;
4910  * MSG_ERROR_T err = MSG_SUCCESS;
4911  *
4912  * ...
4913  *
4914  * err = msg_open_msg_handle(&msgHandle);
4915  *
4916  * ...
4917  *
4918  * mms_data = msg_mms_create_message();
4919  *
4920  * ...
4921  * msg_mms_destroy_message(mms_data);
4922  * ...
4923  * \endcode
4924  */
4925  /*================================================================================================*/
4926 int msg_mms_destroy_message(MMS_MESSAGE_DATA_S* msg);
4927
4928 /**
4929  *      @}
4930  */
4931
4932 #ifdef __cplusplus
4933 }
4934 #endif
4935
4936 #endif
4937