include/mapi/msg.h

   1 /*
   2 * Copyright 2012  Samsung Electronics Co., Ltd
   3 *
   4 * Licensed under the Flora License, Version 1.0 (the "License");
   5 * you may not use this file except in compliance with the License.
   6 * You may obtain a copy of the License at
   7 *
   8 *    http://www.tizenopensource.org/license
   9 *
  10 * Unless required by applicable law or agreed to in writing, software
  11 * distributed under the License is distributed on an "AS IS" BASIS,
  12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 * See the License for the specific language governing permissions and
  14 * limitations under the License.
  15 */
  16
  17 #ifndef MSG_H_
  18 #define MSG_H_
  19
  20 /*==================================================================================================
  21                                          INCLUDE FILES
  22 ==================================================================================================*/
  23 #include <stdbool.h>
  24
  25 #include "msg_types.h"
  26
  27 #ifdef __cplusplus
  28 extern "C"
  29 {
  30 #endif
  31
  32 /**
  33  *      @ingroup                MESSAGING_FRAMEWORK
  34  *      @defgroup       MESSAGING_CONTROL_API   Messaging Control API
  35  *      @{
  36  */
  37
  38 /*==================================================================================================
  39                                      FUNCTION PROTOTYPES
  40 ==================================================================================================*/
  41
  42 /**
  43
  44  * \par Description:
  45  * Opens a channel between an application and messaging framework.
  46  *
  47  * \par Purpose:
  48  * For application to utilize the services of Messaging Framework, this API should be called to establish connection between the application and Messaging Framework.
  49  *
  50  * \par Typical use case:
  51  * Any application which utilizes the services of Messaging Framework needs to call this API.
  52  *
  53  * \par Method of function operation:
  54  * Check for Message Server ready status. If ready connect to the Messaging Server socket and pass the handle application.
  55  *
  56  * \par Sync (or) Async:
  57  * This is a Synchronous API.
  58  *
  59  * \par Important notes:
  60  * - The handle parameter returned must be used by application for further API calls to Messaging Service \n
  61  * - memory for the handle need not be allocated by the application \n
  62  * - An error will be returned in case Messaging Service is not running.
  63  *
  64  * \param msg_handle_t    input - handle to be passed for all Messaging Services .
  65  *
  66  * \return Return Type (int) \n
  67  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
  68  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
  69  * - MSG_ERR_MEMORY_ERROR -     Memory error.
  70  * - MSG_ERR_COMMUNICATION_ERROR        - Communication error between client and server \n
  71  *
  72  * \par Prospective clients:
  73  * External/Native Apps using Messaging Services.
  74  *
  75  * \par Related functions:
  76  * None
  77  *
  78  * \par Known issues/bugs:
  79  * None
  80  *
  81  * \par Sample code:
  82  * \code
  83  * ...
  84  *
  85  * msg_handle_t msgHandle = NULL;
  86  * msg_error_t err = MSG_SUCCESS;
  87  *
  88  * err = msg_open_msg_handle(&msgHandle);
  89  *
  90  * if (err != MSG_SUCCESS)
  91  * {
  92  *      sprintf(str, "msg_open_msg_handle() Fail [%d]", err);
  93  *      print(str);
  94  *
  95  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
  96  * }
  97  *
  98  * ...
  99  * \endcode
 100  */
 101 /*================================================================================================*/
 102 int msg_open_msg_handle(msg_handle_t *handle);
 103
 104
 105 /**
 106
 107  * \par Description:
 108  * Closes the channel between application and messaging framework.
 109  *
 110  * \par Purpose:
 111  * Once application utilizes services of Messaging Service, this API needs to be invoked the close the channel between application and Messaging Service.
 112  *
 113  * \par Typical use case:
 114  * Any application which has completed using services of Messaging Framework needs to call this API.
 115  *
 116  * \par Method of function operation:
 117  * Closes the connection to Messaging Service and deleted the reference to the handle object
 118  *
 119  * \par Sync (or) Async:
 120  * This is a Synchronous API.
 121  *
 122  * \par Important notes:
 123  * - The handle parameter returned must be used by application for further API calls to Messaging Service \n
 124  * - memory for the handle need not be allocated by the application \n
 125  * - An error will be returned in case Messaging Service is not running.
 126  *
 127  * \param msg_handle_t    input - handle to be passed for all Messaging Services .
 128  *
 129  * \return Return Type (int) \n
 130  * - MSG_SUCCESS        - Successfully connected to Messaging Service \n
 131  * - MSG_ERR_NULL_POINTER       -       Input parameter is NULL.
 132  * - MSG_ERR_COMMUNICATION_ERROR        - Communication error between client and server \n
 133  *
 134  * \par Prospective clients:
 135  * External/Native Apps using Messaging Services.
 136  *
 137  * \par Related functions:
 138  * None
 139  *
 140  * \par Known issues/bugs:
 141  * None
 142  *
 143  * \par Sample code:
 144  * \code
 145  * ...
 146  *
 147  * msg_handle_t msgHandle = NULL;
 148  * msg_error_t err = MSG_SUCCESS;
 149  *
 150  * ...
 151  *
 152  * err = msg_open_msg_handle(&msgHandle);
 153  *
 154  * ...
 155  *
 156  * err = msg_close_msg_handle(&msgHandle);
 157  *
 158  * if (err != MSG_SUCCESS)
 159  * {
 160  *      sprintf(str, "msg_close_msg_handle() Fail [%d]", err);
 161  *      print(str);
 162  *
 163  *      return err; // if success, return OPERATION_SUCCESS. Or if fail, return related error code.
 164  * }
 165  *
 166  * ...
 167  * \endcode
 168  */
 169 /*================================================================================================*/
 170 int msg_close_msg_handle(msg_handle_t *handle);
 171
 172
 173
 174 msg_struct_t msg_create_struct(int field);
 175 int msg_release_struct(msg_struct_t *msg_struct_handle);
 176 int msg_release_list_struct(msg_struct_list_s *msg_struct_list);
 177
 178 int msg_get_int_value(msg_struct_t msg_struct_handle, int field, int *value);
 179 int msg_get_str_value(msg_struct_t msg_struct_handle, int field, char *value, int size);
 180 int msg_get_bool_value(msg_struct_t msg_struct_handle, int field, bool *value);
 181 int msg_get_struct_handle(msg_struct_t msg_struct_handle, int field, msg_struct_t *value);
 182 int msg_get_list_handle(msg_struct_t msg_struct_handle, int field, void **value);
 183
 184 int msg_set_int_value(msg_struct_t msg_struct_handle, int field, int value);
 185 int msg_set_str_value(msg_struct_t msg_struct_handle, int field, char *value, int size);
 186 int msg_set_bool_value(msg_struct_t msg_struct_handle, int field, bool value);
 187 int msg_set_struct_handle(msg_struct_t msg_struct_handle, int field, msg_struct_t value);
 188 int msg_set_list_handle(msg_struct_t msg_struct_handle, int field, void *value);
 189
 190 int msg_mms_add_item(msg_struct_t msg_struct_handle, int field, msg_struct_t *item);
 191
 192 int msg_get_mms_struct(msg_struct_t msg_struct_handle, msg_struct_t mms_struct_handle);
 193 int msg_set_mms_struct(msg_struct_t msg_struct_handle, msg_struct_t mms_struct_handle);
 194
 195 //list
 196 msg_struct_t msg_list_nth_data(msg_list_handle_t list_handle, int index);
 197 int msg_list_length(msg_list_handle_t list_handle);
 198
 199 // filter
 200 int msg_add_filter(msg_handle_t handle, const msg_struct_t filter);
 201 int msg_update_filter(msg_handle_t handle, const msg_struct_t filter);
 202 int msg_delete_filter(msg_handle_t handle, msg_filter_id_t filter_id);
 203 int msg_get_filter_list(msg_handle_t handle, msg_struct_list_s *filter_list);
 204 int msg_set_filter_operation(msg_handle_t handle, bool set_flag);
 205 int msg_get_filter_operation(msg_handle_t handle, bool *set_flag);
 206 int msg_set_filter_active(msg_handle_t handle, msg_filter_id_t filter_id, bool active);
 207
 208 //setting
 209 int msg_get_smsc_opt(msg_handle_t handle, msg_struct_t msg_struct);
 210 int msg_set_smsc_opt(msg_handle_t handle, msg_struct_t msg_struct);
 211
 212 int msg_get_cb_opt(msg_handle_t handle, msg_struct_t msg_struct);
 213 int msg_set_cb_opt(msg_handle_t handle, msg_struct_t msg_struct);
 214
 215 int msg_get_sms_send_opt(msg_handle_t handle, msg_struct_t msg_struct);
 216 int msg_set_sms_send_opt(msg_handle_t handle, msg_struct_t msg_struct);
 217
 218 int msg_get_mms_send_opt(msg_handle_t handle, msg_struct_t msg_struct);
 219 int msg_set_mms_send_opt(msg_handle_t handle, msg_struct_t msg_struct);
 220
 221 int msg_get_mms_recv_opt(msg_handle_t handle, msg_struct_t msg_struct);
 222 int msg_set_mms_recv_opt(msg_handle_t handle, msg_struct_t msg_struct);
 223
 224 int msg_get_push_msg_opt(msg_handle_t handle, msg_struct_t msg_struct);
 225 int msg_set_push_msg_opt(msg_handle_t handle, msg_struct_t msg_struct);
 226
 227 int msg_get_voice_msg_opt(msg_handle_t handle, msg_struct_t msg_struct);
 228 int msg_set_voice_msg_opt(msg_handle_t handle, msg_struct_t msg_struct);
 229
 230 int msg_get_general_opt(msg_handle_t handle, msg_struct_t msg_struct);
 231 int msg_set_general_opt(msg_handle_t handle, msg_struct_t msg_struct);
 232
 233 int msg_get_msgsize_opt(msg_handle_t handle, msg_struct_t msg_struct);
 234 int msg_set_msgsize_opt(msg_handle_t handle, msg_struct_t msg_struct);
 235
 236 // text length calculate
 237 int msg_calculate_text_length(msg_handle_t handle, const char* msg_text, msg_encode_type_t msg_encode_type, unsigned int *text_size, unsigned int *segment_size);
 238 int msg_util_calculate_text_length(const char* msg_text, msg_encode_type_t msg_encode_type_to, unsigned int *text_size, unsigned int *segment_size, msg_encode_type_t *msg_encode_type_in);
 239
 240 #ifdef __cplusplus
 241 }
 242 #endif
 243
 244 #endif /* MSG_H_ */