diff options
Diffstat (limited to 'include/mapi/msg_transport.h')
| -rwxr-xr-x | include/mapi/msg_transport.h | 1130 |
1 files changed, 349 insertions, 781 deletions
diff --git a/include/mapi/msg_transport.h b/include/mapi/msg_transport.h index 9766bed..6dd003c 100755 --- a/include/mapi/msg_transport.h +++ b/include/mapi/msg_transport.h @@ -1,38 +1,22 @@ /* - * msg-service - * - * Copyright (c) 2000 - 2014 Samsung Electronics Co., Ltd. All rights reserved + * Copyright (c) 2014 Samsung Electronics Co., Ltd. All rights reserved * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * - * http://www.apache.org/licenses/LICENSE-2.0 + * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. - * */ -/** - * @file MapiTransport.h - * @brief Defines transport API of messaging framework - * @version 1.0 - */ - #ifndef MAPI_TRANSPORT_H #define MAPI_TRANSPORT_H -/** - * @section Introduction - * - Introduction : Overview on Messaging Transport API - * @section Program - * - Program : Messaging Transport API Reference - */ - /*================================================================================================== INCLUDE FILES ==================================================================================================*/ @@ -45,937 +29,521 @@ extern "C" #endif /** - * @ingroup MESSAGING_FRAMEWORK - * @defgroup MESSAGING_TRANSPORT_API Messaging Transport API - * @{ - */ - -/*================================================================================================== - FUNCTION PROTOTYPES -==================================================================================================*/ - -/** - - * \par Description: - * Submits a request to the Messaging Framework. - * - * \par Purpose: - * This API is used to submit a request to the Messaging Framework. - * - * \par Typical use case: - * Submit a request to Messaging Service such as Send Message, Forward etc. + * @internal + * @ingroup MSG_SERVICE_FRAMEWORK + * @defgroup MSG_SERVICE_FRAMEWORK_TRANSPORT_MODULE Transport API + * @brief The Transport API provides functions to send SMS/MMS and register incoming/sending/syncML/report callback. * - * \par Method of function operation: - * Sets up the database connection and inserts the message to message table. + * @internal + * @addtogroup MSG_SERVICE_FRAMEWORK_TRANSPORT_MODULE + * @{ * - * \par Sync (or) Async: - * This is a Synchronous API. + * @section MSG_SERVICE_FRAMEWORK_TRANSPORT_MODULE_HEADER Required Header + * \#include <msg_transport.h> * - * \par Important notes: - * - The result information will be sent back by using the callback function, msg_sent_status_cb. - * - Applications MUST fill in the valid message type. - * - reqId will be filled in the framework. + * @section MSG_SERVICE_FRAMEWORK_TRANSPORT_MODULE_OVERVIEW Overview * - * \param input - handle is Message handle. - * \param input - req is a pointer to an MSG_REQUEST_S structure. + * The Transport API provides the following functionalities: * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_INVALID_MSGHANDLE Message handle is invalid. - * - MSG_ERR_NULL_POINTER Pointer is NULL. - * - * \par Prospective clients: - * External/Native Apps using Messaging Services. + * - Sending SMS/MMS messages + * - Register incoming message callback + * - Register sent status callback + * - Register push message application + * - Register syncML message callback + * - Managing the registration * - * \par Related functions: - * None + * @section MSG_SERVICE_FRAMEWORK_TRANSPORT_MODULE_FEATURE Related Features + * This API is related with the following features:\n + * - http://tizen.org/feature/network.telephony\n + * - http://tizen.org/feature/network.telephony.mms\n * - * \par Known issues/bugs: - * None + * It is recommended to design feature related codes in your application for reliability.\n * - * \par Sample code: - * \code - * ... + * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n * - * int err = MSG_SUCCESS; - * MSG_REQUEST_S req; + * To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.\n * - * req.msg = msg; - * req.sendOpt = sendOpt; - - * err = msg_submit_req(msgHandle, &req); - * if (err != MSG_SUCCESS) - * { - * ... - * } + * More details on featuring your application can be found from <a href="../org.tizen.mobile.native.appprogramming/html/ide_sdk_tools/feature_element.htm"><b>Feature Element</b>.</a> * - * ... - * \endcode */ -/*================================================================================================*/ -int msg_submit_req(msg_handle_t handle, msg_struct_t req); +/*================================================================================================== + FUNCTION PROTOTYPES +==================================================================================================*/ /** - - * \par Description: - * Registers sent status callback function to Message handle. - * - * \par Purpose: - * This API is used to register sent status callback function "msg_sent_status_cb" to Message handle. + * @brief Submits a request to the Messaging Framework. * - * \par Typical use case: - * Register for sent status callback. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.write * - * \par Method of function operation: - * Adds the msg_sent_status_cb API to sent status callback list. + * @remarks The result information will be sent back by using the callback function, msg_sent_status_cb(). + * @remarks Applications MUST fill in the valid message type. + * @remarks reqId will be filled in the framework. * - * \par Sync (or) Async: - * This is a Synchronous API. + * @param[in] handle The message handle + * @param[in] req The pointer to an #MSG_REQUEST_S structure * - * \par Important notes: - * This function MUST be called after Message handle is opened. + * @return @c 0 on success, + * otherwise a negative error value * - * \param input - handle is Message handle. - * \param input - cb is a function to be called. - * \param input - user_param is a pointer to user data. - * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_INVALID_MSGHANDLE Message handle is invalid. - * - * \par Prospective clients: - * External/Native Apps using Messaging Services. + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_TRANSPORT_ERROR Transport error + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported + */ + +int msg_submit_req(msg_handle_t handle, msg_struct_t req); + + +/** + * @brief Registers sent status callback function to Message handle. + * @details This API is used to register sent status callback function msg_sent_status_cb() to Message handle. * - * \par Related functions: - * None + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.read * - * \par Known issues/bugs: - * None + * @remarks This function MUST be called after Message handle is opened. * - * \par Sample code: - * \code - * ... + * @param[in] handle The message handle + * @param[in] cb The function to be called + * @param[in] user_param A pointer to user data * - * int err = MSG_SUCCESS; - * MSG_REQUEST_S req; + * @return @c 0 on success, + * otherwise a negative error value * - * req.msg = msg; - * req.sendOpt = sendOpt; - - * err = msg_reg_sent_status_callback(msgHandle, &sentStatusCB, (void*)"sent status callback"); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * return; - * } - - * void sentStatusCB(msg_handle_t Handle, MSG_SENT_STATUS_S *pStatus, void *pUserParam) - * { - * ... - * } - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_CALLBACK_ERROR Callback registration error + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_reg_sent_status_callback(msg_handle_t handle, msg_sent_status_cb cb, void *user_param); /** - - * \par Description: - * Registers incoming SMS callback to Message handle. + * @brief Registers incoming SMS callback to Message handle. + * @details This API is used to Registers incoming SMS callback function msg_sms_incoming_cb() to Message handle. * - * \par Purpose: - * This API is used to Registers incoming SMS callback function "msg_sms_incoming_cb" to Message handle. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.read * - * \par Typical use case: - * Register incoming SMS message callback. + * @remarks This function MUST be called after Message handle is opened. * - * \par Method of function operation: - * Adds the msg_sms_incoming_cb API to incoming SMS callback list. + * @param[in] handle The message handle + * @param[in] cb The function to be called + * @param[in] port The port used for listening \n + * If port is not used, set to @c 0. + * @param[in] user_param A pointer to user data * - * \par Sync (or) Async: - * This is a Synchronous API. + * @return @c 0 on success, + * otherwise a negative error value * - * \par Important notes: - * This function MUST be called after Message handle is opened. - * - * \param input - handle is Message handle. - * \param input - cb is a function to be called. - * \param input - port is used for listening. If port is not used, please assign 0 to it. - * \param input - user_param is a pointer to user data. - * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_INVALID_MSGHANDLE Message handle is invalid. - * - * \par Prospective clients: - * External/Native Apps using Messaging Services. - * - * \par Related functions: - * None - * - * \par Known issues/bugs: - * None - * - * \par Sample code: - * \code - * ... - * - * int err = MSG_SUCCESS; - * MSG_REQUEST_S req; - * - * req.msg = msg; - * req.sendOpt = sendOpt; - - * err = msg_reg_sms_message_callback(msgHandle, &incomingSmsCB, 0, (void*)"sms message callback"); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * return; - * } - * - * void incomingSmsCB(msg_handle_t Handle, msg_message_t msg, void *pUserParam) - * { - * ... - * } - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_CALLBACK_ERROR Callback registration error + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_reg_sms_message_callback(msg_handle_t handle, msg_sms_incoming_cb cb, unsigned short port, void *user_param); /** - - * \par Description: - * Registers incoming MMS callback to Message handle. + * @brief Registers incoming MMS conf callback to Message handle. + * @details This API is used to Registers incoming MMS conf callback function msg_mms_conf_msg_incoming_cb() to Message handle. * - * \par Purpose: - * This API is used to Registers incoming MMS callback function "msg_mms_conf_msg_incoming_cb" to Message handle. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.read * - * \par Typical use case: - * Register incoming SMS message callback. + * @remarks This function MUST be called after Message handle is opened. * - * \par Method of function operation: - * Adds the msg_mms_conf_msg_incoming_cb API to incoming MMS callback list. + * @param[in] handle The message handle + * @param[in] cb The function to be called + * @param[in] app_id The app ID used for listening \n + * If appId is not used, set to @c NULL. + * @param[in] user_param A pointer to user data * - * \par Sync (or) Async: - * This is a Synchronous API. + * @return @c 0 on success, + * otherwise a negative error value * - * \par Important notes: - * This function MUST be called after Message handle is opened. - * - * \param input - handle is Message handle. - * \param input - handle is Message handle. - * \param input - cb is a function to be called. - * \param input - app_id is used for listening. If appId is not used, please assign NULL to it. - * \param input - user_param is a pointer to user data. - * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_INVALID_MSGHANDLE Message handle is invalid. - * - * \par Prospective clients: - * External/Native Apps using Messaging Services. - * - * \par Related functions: - * None - * - * \par Known issues/bugs: - * None - * - * \par Sample code: - * \code - * ... - * - * int err = MSG_SUCCESS; - * MSG_REQUEST_S req; - * - * req.msg = msg; - * req.sendOpt = sendOpt; - - * err = msg_reg_mms_conf_message_callback(msgHandle, &incomingMmsConfCB, NULL, NULL); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * return; - * } - * - * void incomingMmsConfCB(msg_handle_t Handle, msg_message_t msg, void *pUserParam) - * { - * ... - * } - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_CALLBACK_ERROR Callback registration error + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_reg_mms_conf_message_callback(msg_handle_t handle, msg_mms_conf_msg_incoming_cb cb, const char *app_id, void *user_param); /** - - * \par Description: - * Registers incoming SyncML Message callback to Message handle. + * @brief Registers incoming SyncML Message callback to Message handle. + * @details This API is used to register incoming SyncML Message callback function msg_syncml_msg_incoming_cb() to Message handle. * - * \par Purpose: - * This API is used to Registers incoming SyncML Message callback function "msg_syncml_msg_incoming_cb" to Message handle. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.read * - * \par Typical use case: - * Register incoming SMS message callback. + * @remarks This function MUST be called after Message handle is opened. * - * \par Method of function operation: - * Adds the msg_syncml_msg_incoming_cb API to incoming SyncML callback list. + * @param[in] handle The message handle + * @param[in] cb The function to be called + * @param[in] user_param A pointer to user data * - * \par Sync (or) Async: - * This is a Synchronous API. + * @return @c 0 on success, + * otherwise a negative error value * - * \par Important notes: - * This function MUST be called after Message handle is opened. - * - * \param input - handle is Message handle. - * \param input - cb is a function to be called. - * \param input - user_param is a pointer to user data. - * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_MSGHANDLE_NOT_CONNECTED Message handle is not connected. - * - MSG_ERR_MEMORY_ERROR Memory is error. - * - * \par Prospective clients: - * External/Native Apps using Messaging Services. - * - * \par Related functions: - * None - * - * \par Known issues/bugs: - * None - * - * \par Sample code: - * \code - * ... - * - * int err = MSG_SUCCESS; - * - * err = err = msg_reg_syncml_message_callback(msgHandle, &syncMLCB, NULL); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * return; - * } - * - * void syncMLCB(msg_handle_t hMsgHandle, msg_syncml_message_type_t msgType, const char* pPushHeader, int PushHeaderLen, const char* pPushBody, int PushBodyLen, void *pUserParam) - * { - * ... - * } - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_CALLBACK_ERROR Callback registration error + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_reg_syncml_message_callback(msg_handle_t handle, msg_syncml_msg_incoming_cb cb, void *user_param); /** - - * \par Description: - * Registers incoming LBS Message callback to Message handle. - * - * \par Purpose: - * This API is used to Registers incoming LBS Message callback function "msg_lbs_msg_incoming_cb" to Message handle. + * @brief Registers incoming LBS Message callback to Message handle. + * @details This API is used to register incoming LBS Message callback function msg_lbs_msg_incoming_cb() to Message handle. * - * \par Typical use case: - * Register incoming SMS message callback. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.read * - * \par Method of function operation: - * Adds the msg_lbs_msg_incoming_cb API to incoming LBS Message callback list. + * @remarks This function MUST be called after Message handle is opened. * - * \par Sync (or) Async: - * This is a Synchronous API. + * @param[in] handle The message handle + * @param[in] cb The function to be called + * @param[in] user_param A pointer to user data * - * \par Important notes: - * This function MUST be called after Message handle is opened. + * @return @c 0 on success, + * otherwise a negative error value * - * \param input - handle is Message handle. - * \param input - cb is a function to be called. - * \param input - user_param is a pointer to user data. - * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_MSGHANDLE_NOT_CONNECTED Message handle is not connected. - * - MSG_ERR_MEMORY_ERROR Memory is error. - * - * \par Prospective clients: - * External/Native Apps using Messaging Services. - * - * \par Related functions: - * None - * - * \par Known issues/bugs: - * None - * - * \par Sample code: - * \code - * ... - * - * int err = MSG_SUCCESS; - * - * err = msg_reg_lbs_message_callback(msgHandle, &lbsCB, NULL); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * return; - * } - * - * void lbsCB(msg_handle_t hMsgHandle, const char* pPushHeader, const char* pPushBody, int pushBodyLen, void *pUserParam) - * { - * ... - * } - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_CALLBACK_ERROR Callback registration error + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_reg_lbs_message_callback(msg_handle_t handle, msg_lbs_msg_incoming_cb cb, void *user_param); /** - - * \par Description: - * Registers incoming LBS Message callback to Message handle. - * - * \par Purpose: - * This API is used to Registers incoming LBS Message callback function "msg_lbs_msg_incoming_cb" to Message handle. - * - * \par Typical use case: - * Register incoming SMS message callback. + * @brief Registers SyncML operation callback to Message handle. + * @details This API is used to register SyncML operation callback function msg_syncml_msg_operation_cb() to Message handle. * - * \par Method of function operation: - * Adds the msg_lbs_msg_incoming_cb API to incoming LBS Message callback list. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.read * - * \par Sync (or) Async: - * This is a Synchronous API. + * @remarks This function MUST be called after Message handle is opened. * - * \par Important notes: - * This function MUST be called after Message handle is opened. + * @param[in] handle The message handle + * @param[in] cb The function to be called + * @param[in] user_param A pointer to user data * - * \param input - handle is Message handle. - * \param input - cb is a function to be called. - * \param input - user_param is a pointer to user data. + * @return @c 0 on success, + * otherwise a negative error value * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_MSGHANDLE_NOT_CONNECTED Message handle is not connected. - * - MSG_ERR_MEMORY_ERROR Memory is error. - * - * \par Prospective clients: - * External/Native Apps using Messaging Services. - * - * \par Related functions: - * None + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_CALLBACK_ERROR Callback registration error + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported + */ + +int msg_reg_syncml_message_operation_callback(msg_handle_t handle, msg_syncml_msg_operation_cb cb, void *user_param); + + +/** + * @brief Registers incoming push Message callback to Message handle. + * @details This API is used to register incoming push Message callback function msg_push_msg_incoming_cb() to Message handle. * - * \par Known issues/bugs: - * None + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.read * - * \par Sample code: - * \code - * ... + * @remarks This function MUST be called after Message handle is opened. * - * int err = MSG_SUCCESS; + * @param[in] handle The message handle + * @param[in] cb The function to be called + * @param[in] app_id The app ID for listening \n + * If appId is not used, set to @c NULL. + * @param[in] user_param A pointer to user data * - * err = msg_reg_lbs_message_callback(msgHandle, &lbsCB, NULL); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * return; - * } + * @return @c 0 on success, + * otherwise a negative error value * - * void lbsCB(msg_handle_t hMsgHandle, const char* pPushHeader, const char* pPushBody, int pushBodyLen, void *pUserParam) - * { - * ... - * } - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_CALLBACK_ERROR Callback registration error + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ -int msg_reg_syncml_message_operation_callback(msg_handle_t handle, msg_syncml_msg_operation_cb cb, void *user_param); - int msg_reg_push_message_callback(msg_handle_t handle, msg_push_msg_incoming_cb cb, const char *app_id, void *user_param); -int msg_reg_cb_message_callback(msg_handle_t handle, msg_cb_incoming_cb cb, bool bsave, void *user_param); /** - - * \par Description: - * Registers incoming LBS Message callback to Message handle. + * @brief Registers incoming CB Message callback to Message handle. + * @details This API is used to register incoming CB Message callback function msg_cb_incoming_cb() to Message handle. * - * \par Purpose: - * This API is used to Registers incoming LBS Message callback function "msg_lbs_msg_incoming_cb" to Message handle. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.read * - * \par Typical use case: - * Register incoming SMS message callback. + * @remarks This function MUST be called after Message handle is opened. * - * \par Method of function operation: - * Adds the msg_lbs_msg_incoming_cb API to incoming LBS Message callback list. + * @param[in] handle The message handle + * @param[in] cb The function to be called + * @param[in] bsave A bool flag to indicate whether CB message is to be saved or not \n + * CB message will be saved if this flag is true + * @param[in] user_param A pointer to user data * - * \par Sync (or) Async: - * This is a Synchronous API. + * @return @c 0 on success, + * otherwise a negative error value * - * \par Important notes: - * This function MUST be called after Message handle is opened. + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_CALLBACK_ERROR Callback registration error + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported + */ + +int msg_reg_cb_message_callback(msg_handle_t handle, msg_cb_incoming_cb cb, bool bsave, void *user_param); + + + +/** + * @brief Registers incoming Report Message callback to Message handle. + * @details This API is used to register incoming Report Message callback function msg_report_msg_incoming_cb() to Message handle. * - * \param input - handle is Message handle. - * \param input - cb is a function to be called. - * \param input - user_param is a pointer to user data. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.read * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_MSGHANDLE_NOT_CONNECTED Message handle is not connected. - * - MSG_ERR_MEMORY_ERROR Memory is error. + * @remarks This function MUST be called after Message handle is opened. * - * \par Prospective clients: - * External/Native Apps using Messaging Services. + * @param[in] handle The message handle + * @param[in] cb The function to be called + * @param[in] user_param A pointer to user data * - * \par Related functions: - * None + * @return @c 0 on success, + * otherwise a negative error value + * + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_CALLBACK_ERROR Callback registration error + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported + */ + +int msg_reg_report_message_callback(msg_handle_t handle, msg_report_msg_incoming_cb cb, void *user_param); + + +/** + * @brief Operates SyncML message. + * @details This API is used to run SyncML operation. * - * \par Known issues/bugs: - * None + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.read * - * \par Sample code: - * \code - * ... + * @remarks This function MUST be called after Message handle is opened. * - * int err = MSG_SUCCESS; + * @param[in] handle The message handle + * @param[in] msgId The message ID to run SycnML operation * - * err = msg_reg_lbs_message_callback(msgHandle, &lbsCB, NULL); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * return; - * } + * @return @c 0 on success, + * otherwise a negative error value * - * void lbsCB(msg_handle_t hMsgHandle, const char* pPushHeader, const char* pPushBody, int pushBodyLen, void *pUserParam) - * { - * ... - * } - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_TRANSPORT_ERROR Transport error + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_syncml_message_operation(msg_handle_t handle, msg_message_id_t msgId); /** - - * \par Description: - * Sends SMS. It is a synchronous API which has been blocked until sent status arrives. - * - * \par Purpose: - * This API is used to sends SMS. + * @brief Sends SMS. + * @details This API is used to send SMS. It is a synchronous API which has been blocked until sent status arrives. * - * \par Typical use case: - * Sends a SMS Message + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.write * - * \par Method of function operation: - * It is a synchronous API which has been blocked until sent status arrives. + * @param[in] phone_num The list of phone numbers \n + * It is separated by ",". + * @param[in] sms_text The SMS text + * @param[in] cb The function to be called + * @param[in] user_param The user data * - * \par Sync (or) Async: - * This is a Synchronous API. + * @return @c 0 on success, + * otherwise a negative error value * - * \par Important notes: - * - None - * - * \param input - phone_num is the list of phone numbers. It is separated by ",". - * \param input - sms_text is a SMS text. - * \param input - cb is a function to be called. - * \param input - user_param is for user data. - * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_NULL_POINTER Invalid parameter. - * - MSG_ERR_MEMORY_ERROR Memory is error. + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported * * \par Prospective clients: * External/Native Apps using Messaging Services. * - * \par Related functions: - * None - * - * \par Known issues/bugs: - * None - * - * \par Sample code: - * \code - * ... - * - * int err = MSG_SUCCESS; - * - * err = msg_sms_send("01000000000,01000000000", "1234567890", sentStatusCB, NULL); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * - * ... - * \endcode */ -/*================================================================================================*/ + int msg_sms_send(const char *phone_num, const char *sms_text, msg_simple_sent_status_cb cb, void *user_param); /** - - * \par Description: - * Submits request to send SMS message. - * - * \par Purpose: - * This API is used to submit request to send SMS message. + * @brief Submits request to send SMS message. + * @details This API is used to submit request to send SMS message. * - * \par Typical use case: - * Submits request to send SMS message. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.write * - * \par Method of function operation: - * Submits a request to send SMS. + * @param[in] handle The message handle + * @param[in] req A pointer to #msg_struct_t structure for SMS request information * - * \par Sync (or) Async: - * This is a Synchronous API. + * @return @c 0 on success, + * otherwise a negative error value * - * \par Important notes: - * - None - * - * \param input - phone_num is the list of phone numbers. It is separated by ",". - * \param input - sms_text is a SMS text. - * \param input - cb is a function to be called. - * \param input - user_param is for user data. - * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_NULL_POINTER Invalid parameter. - * - MSG_ERR_MEMORY_ERROR Memory is error. - * - * \par Prospective clients: - * External/Native Apps using Messaging Services. - * - * \par Related functions: - * None - * - * \par Known issues/bugs: - * None - * - * \par Sample code: - * \code - * ... - * - * int err = MSG_SUCCESS; - * MSG_REQUEST_S req; - * - * req.msg = msg; - * req.sendOpt = sendOpt; - * - * err = msg_sms_send_message(msgHandle, &req); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_NULL_POINTER Null parameter + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_sms_send_message(msg_handle_t handle, msg_struct_t req); /** - - * \par Description: - * Submits request to send MMS message. + * @brief Submits request to send MMS message. + * @details This API is used to submit request to send MMS message. * - * \par Purpose: - * This API is used to submit request to send MMS message. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.write * - * \par Typical use case: - * Submits request to send MMS message. + * @param[in] handle The message handle + * @param[in] req A pointer to #msg_struct_t structure for MMS request information * - * \par Method of function operation: - * Submits a request to send MMS. + * @return @c 0 on success, + * otherwise a negative error value * - * \par Sync (or) Async: - * This is a Synchronous API. - * - * \par Important notes: - * - None - * - * \param input - handle is Message handle. - * \param input - req is a pointer to an MSG_REQUEST_S structure. - * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_NULL_POINTER Invalid parameter. - * - MSG_ERR_MEMORY_ERROR Memory is error. - * - * \par Prospective clients: - * External/Native Apps using Messaging Services. - * - * \par Related functions: - * None - * - * \par Known issues/bugs: - * None - * - * \par Sample code: - * \code - * ... - * - * int err = MSG_SUCCESS; - * MSG_REQUEST_S req; - * - * req.msg = msg; - * req.sendOpt = sendOpt; - * - * err = msg_mms_send_message(msgHandle, &req); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_mms_send_message(msg_handle_t handle, msg_struct_t req); /** - - * \par Description: - * Submits request to send MMS read report request. - * - * \par Purpose: - * This API is used to submit request to send MMS read report request. - * - * \par Typical use case: - * Submits request to send MMS read report request. - * - * \par Method of function operation: - * Submits a request to send MMS read report request. - * - * \par Sync (or) Async: - * This is a Synchronous API. - * - * \par Important notes: - * - None - * - * \param input - handle is Message handle. - * \param input - msg_id is a message id, which is a positive integer. - * \param input - mms_read_status is status whether message was read or not. + * @brief Submits request to send MMS read report request. + * @details This API is used to submit request to send MMS read report request. * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_NULL_POINTER Invalid parameter. - * - MSG_ERR_MEMORY_ERROR Memory is error. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.write * - * \par Prospective clients: - * External/Native Apps using Messaging Services. - * - * \par Related functions: - * None - * - * \par Known issues/bugs: - * None + * @param[in] handle The message handle + * @param[in] msg_id The message ID \n + * This is a positive integer. + * @param[in] mms_read_status This is status whether message was read or not * - * \par Sample code: - * \code - * ... + * @return @c 0 on success, + * otherwise a negative error value * - * int err = MSG_SUCCESS; - * - * err = err = msg_mms_send_read_report(NULL, 0, MSG_READ_REPORT_IS_READ); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_mms_send_read_report(msg_handle_t handle, msg_message_id_t msgId, msg_read_report_status_t mms_read_status); /** - - * \par Description: - * Submits request to send forward MMS request. - * - * \par Purpose: - * This API is used to submit request to send forward MMS request. - * - * \par Typical use case: - * Submits request to send forward MMS request. - * - * \par Method of function operation: - * Submits a request to send forward MMS request. - * - * \par Sync (or) Async: - * This is a Synchronous API. - * - * \par Important notes: - * - None - * - * \param input - handle is Message handle. - * \param input - req is a pointer to an MSG_REQUEST_S structure. + * @brief Submits request to send forward MMS request. + * @details This API is used to submit request to send forward MMS request. * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_INVALID_MSGHANDLE Message handle is invalid. - * - MSG_ERR_NULL_POINTER Pointer is NULL. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.write * - * \par Prospective clients: - * External/Native Apps using Messaging Services. - * - * \par Related functions: - * None - * - * \par Known issues/bugs: - * None + * @param[in] handle The message handle + * @param[in] req A pointer to #msg_struct_t structure for MMS * - * \par Sample code: - * \code - * ... + * @return @c 0 on success, + * otherwise a negative error value * - * int err = MSG_SUCCESS; - * - * err = err = msg_mms_send_read_report(NULL, 0, MSG_READ_REPORT_IS_READ); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_mms_forward_message(msg_handle_t handle, msg_struct_t req); /** - - * \par Description: - * Submits request to retrieve MMS request. - * - * \par Purpose: - * This API is used to submit request to retrieve MMS request. - * - * \par Typical use case: - * Submits request to retrieve MMS request. - * - * \par Method of function operation: - * Submits a request to send forward MMS request. - * - * \par Sync (or) Async: - * This is a Synchronous API. - * - * \par Important notes: - * - None - * - * \param input - handle is Message handle. - * \param input - req is a pointer to an MSG_REQUEST_S structure. + * @brief Submits request to retrieve MMS request. + * @details This API is used to submit request to retrieve MMS request. * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_INVALID_MSGHANDLE Message handle is invalid. - * - MSG_ERR_NULL_POINTER Pointer is NULL. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.write * - * \par Prospective clients: - * External/Native Apps using Messaging Services. - * - * \par Related functions: - * None - * - * \par Known issues/bugs: - * None + * @param[in] handle The message handle + * @param[in] req A pointer to #msg_struct_t structure for MMS * - * \par Sample code: - * \code - * ... + * @return @c 0 on success, + * otherwise a negative error value * - * int err = MSG_SUCCESS; - * - * err = msg_mms_retrieve_message(handle, &req); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_mms_retrieve_message(msg_handle_t handle, msg_struct_t req); -/* reject_msg_support */ /** - - * \par Description: - * Submits request to reject MMS message. - * - * \par Purpose: - * This API is used to submit request to reject MMS message. - * - * \par Typical use case: - * Submits request to reject MMS message. - * - * \par Method of function operation: - * Submits a request to send forward reject MMS message. - * - * \par Sync (or) Async: - * This is a Synchronous API. - * - * \par Important notes: - * - None - * - * \param input - handle is Message handle. - * \param input - req is a pointer to an MSG_REQUEST_S structure. + * @brief Submits request to reject MMS message. + * @details This API is used to submit request to reject MMS message. * - * \return Return Type (int(msg_error_t)) \n - * - MSG_SUCCESS Success in operation. - * - MSG_ERR_INVALID_MSGHANDLE Message handle is invalid. - * - MSG_ERR_NULL_POINTER Pointer is NULL. + * @since_tizen 2.3 + * @privlevel public + * @privilege %http://tizen.org/privilege/message.write * - * \par Prospective clients: - * External/Native Apps using Messaging Services. - * - * \par Related functions: - * None - * - * \par Known issues/bugs: - * None + * @param[in] handle The message handle + * @param[in] req A pointer to #msg_struct_t structure for MMS * - * \par Sample code: - * \code - * ... + * @return @c 0 on success, + * otherwise a negative error value * - * int err = MSG_SUCCESS; - * - * err = msg_mms_reject_message(handle, &req); - * if (err != MSG_SUCCESS) - * { - * ... - * } - * - * ... - * \endcode + * @retval MSG_SUCCESS Success in operation + * @retval MSG_ERR_INVALID_PARAMETER Input parameter is invalid + * @retval MSG_ERR_PERMISSION_DENIED The application does not have the privilege to call this method + * @retval MSG_ERR_NOT_SUPPORTED Not supported */ -/*================================================================================================*/ + int msg_mms_reject_message(msg_handle_t handle, msg_struct_t req); /** |