include/call-manager.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Contact: Sung Joon Won <sungjoon.won@samsung.com>
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the License);
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an AS IS BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18
  19 #ifndef __TIZEN_CALL_MANAGER_H__
  20 #define __TIZEN_CALL_MANAGER_H__
  21
  22 /**
  23  * @file call_manager.h
  24  * @brief This file contains Call Manager APIs and related enumerations.
  25  */
  26
  27 #include <tizen.h>
  28
  29 #ifdef __cplusplus
  30  extern "C" {
  31 #endif
  32
  33 /**
  34  * @file call_manager.h
  35  * @brief This file contains the Call Manager API.
  36  */
  37
  38 /**
  39  * @addtogroup CAPI_CALL_MANAGER_MODULE
  40  * @{
  41  */
  42
  43 /**
  44  * @brief The Call Manager API handle.
  45  * @since_tizen 2.4
  46  */
  47 typedef struct __cm_client *cm_client_h;
  48
  49 // TODO:
  50 // Below define will be removed when Call Manager error included in tizen_error.h during ACR
  51 #ifndef TIZEN_ERROR_CALL_MANAGER
  52 #define TIZEN_ERROR_CALL_MANAGER       -0x00000000
  53 #endif
  54
  55 /**
  56  * @brief Enumeration for Call Manager error.
  57  * @since_tizen 2.4
  58  */
  59 typedef enum {
  60  CM_ERROR_NONE = TIZEN_ERROR_NONE,                            /**< Successful */
  61  CM_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,          /**< Out of memory */
  62  CM_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER,  /**< Invalid parameter */
  63  CM_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED,  /**< Permission denied */
  64  CM_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED,          /**< Not supported */
  65  CM_ERROR_NOT_REGISTERED = TIZEN_ERROR_CALL_MANAGER | 0x01,  /**< Callback not registered */
  66  CM_ERROR_ALREADY_REGISTERED = TIZEN_ERROR_CALL_MANAGER | 0x02,  /**< Callback already registered */
  67  CM_ERROR_OPERATION_FAILED = TIZEN_ERROR_CALL_MANAGER | 0x03,  /**< Operation failed */
  68 } cm_error_e;
  69
  70 /**
  71  * @brief Enumeration for Call status.
  72  * @since_tizen 2.4
  73  */
  74 typedef enum {
  75         CM_CALL_STATUS_IDLE,        /**< Call is in idle state */
  76         CM_CALL_STATUS_RINGING,         /**< A new call arrived and is ringing or waiting */
  77         CM_CALL_STATUS_OFFHOOK,         /**< At least one call exist that is in dialing, alerting, active, on hold state */
  78         CM_CALL_STATUS_MAX
  79 } cm_call_status_e;
  80
  81 /**
  82  * @brief Enumeration for Mute status.
  83  * @since_tizen 2.4
  84  */
  85 typedef enum {
  86         CM_MUTE_STATUS_OFF,              /**< Mute state is off */
  87         CM_MUTE_STATUS_ON,              /**<Mute state is on */
  88         CM_MUTE_STATUS_MAX
  89 } cm_mute_status_e;
  90
  91
  92 /**
  93  * @brief Called when the call status changes.
  94  * @since_tizen 2.4
  95  * @param[in]   call_status     The changed call status
  96  * @param[in]   call_num        The call number with changed call status
  97  * @param[in]   user_data       The user data passed from the callback registration function
  98  * @pre You should register this callback using cm_set_call_status_cb().
  99  * @see cm_set_call_status_cb()
 100  * @see cm_unset_call_status_cb()
 101  */
 102 typedef void (*cm_call_status_cb) (cm_call_status_e call_status, const char *call_num, void *user_data);
 103
 104
 105 /**
 106  * @brief Called when the mute status changes.
 107  * @since_tizen 2.4
 108  * @param[in]   mute_status     The changed mute status
 109  * @param[in]   user_data       The user data passed from the callback registration function
 110  * @pre You should register this callback using cm_set_mute_status_cb().
 111  * @see cm_set_mute_status_cb()
 112  * @see cm_unset_mute_status_cb()
 113  */
 114 typedef void (*cm_mute_status_cb) (cm_mute_status_e mute_status, void *user_data);
 115
 116
 117 /**
 118  * @brief Acquires the handle to use the Call Manager API.
 119  *
 120  * @since_tizen 2.4
 121  *
 122  * @param[out] handle The handle to use the Call Manager API
 123  *
 124  * @return @c 0 on success,
 125  *         otherwise a negative error value
 126  *
 127  * @retval #CM_ERROR_NONE              Successful
 128  * @retval #CM_ERROR_INVALID_PARAMETER Invalid parameter
 129  * @retval #CM_ERROR_NOT_SUPPORTED     Not supported
 130  * @retval #CM_ERROR_OPERATION_FAILED  Operation failed
 131  *
 132  * @see cm_deinit()
 133  */
 134 int cm_init (cm_client_h *handle);
 135
 136 /**
 137  * @brief Deinitializes the Call Manager handle.
 138  *
 139  * @since_tizen 2.4
 140  *
 141  * @param[in] handle The handle to be deinitialized
 142  *
 143  * @return @c 0 on success,
 144  *         otherwise a negative error value
 145  *
 146  * @retval #CM_ERROR_NONE              Successful
 147  * @retval #CM_ERROR_INVALID_PARAMETER Invalid parameter
 148  * @retval #CM_ERROR_NOT_SUPPORTED     Not supported
 149  * @retval #CM_ERROR_OPERATION_FAILED  Operation failed
 150  *
 151  * @see cm_init()
 152  */
 153 int cm_deinit (cm_client_h handle);
 154
 155 /**
 156  * @brief Rejects the incoming call.
 157  *
 158  * @since_tizen 2.4
 159  * @privlevel platform
 160  * @privilege TBD
 161  *
 162  * @param[in] handle The handle from cm_init()
 163  *
 164  * @return @c 0 on success,
 165  * otherwise a negative error value
 166  *
 167  * @retval #CM_ERROR_NONE Successful
 168  * @retval #CM_ERROR_INVALID_PARAMETER Out of memory
 169  * @retval #CM_ERROR_PERMISSION_DENIED Permission denied
 170  * @retval #CM_ERROR_NOT_SUPPORTED Not supported
 171  * @retval #CM_ERROR_OPERATION_FAILED Invalid parameter
 172  *
 173  */
 174 int cm_reject_call(cm_client_h handle);
 175
 176 /**
 177  * @brief Stops incoming call alert ringtone.
 178  *
 179  * @since_tizen 2.4
 180  * @privlevel platform
 181  * @privilege TBD
 182  *
 183  * @param[in] handle The handle from cm_init()
 184  *
 185  * @return @c 0 on success,
 186  * otherwise a negative error value
 187  *
 188  * @retval #CM_ERROR_NONE Successful
 189  * @retval #CM_ERROR_INVALID_PARAMETER Out of memory
 190  * @retval #CM_ERROR_PERMISSION_DENIED Permission denied
 191  * @retval #CM_ERROR_NOT_SUPPORTED Not supported
 192  * @retval #CM_ERROR_OPERATION_FAILED Invalid parameter
 193  *
 194  */
 195 int cm_stop_alert(cm_client_h handle);
 196
 197 /**
 198  * @brief Gets the call status.
 199  *
 200  * @since_tizen 2.4
 201  * @privlevel public
 202  * @privilege TBD
 203  *
 204  * @param[in] handle The handle from #cm_init()
 205  * @param[out] call_status The status of the call (#cm_call_status_e)
 206  *
 207  * @return @c 0 on success,
 208  *         otherwise a negative error value
 209  *
 210  * @retval #CM_ERROR_NONE              Successful
 211  * @retval #CM_ERROR_INVALID_PARAMETER Invalid parameter
 212  * @retval #CM_ERROR_PERMISSION_DENIED Permission denied
 213  * @retval #CM_ERROR_NOT_SUPPORTED     Not supported
 214  * @retval #CM_ERROR_OPERATION_FAILED  Operation failed
 215  *
 216  * @pre The handle should be obtained from #cm_init()
 217  * @post The should be released by using #cm_deinit()
 218  */
 219 int cm_get_call_status (cm_client_h handle, cm_call_status_e *call_status);
 220
 221 /**
 222  * @brief Sets a callback function to be invoked when the call status changes.
 223  *
 224  * @since_tizen 2.4
 225  * @privlevel public
 226  * @privilege TBD
 227  *
 228  * @param[in] handle  The handle to use the Call Manager API
 229  * @param[in] cb The callback to be invoked when the call status changes
 230  * @param[in] user_data The user data passed to the callback function
 231  *
 232  * @return @c 0 on success,
 233  *         otherwise a negative error value
 234  *
 235  * @retval #CM_ERROR_NONE              Successful
 236  * @retval #CM_ERROR_INVALID_PARAMETER Invalid parameter
 237  * @retval #CM_ERROR_PERMISSION_DENIED Permission denied
 238  * @retval #CM_ERROR_NOT_SUPPORTED     Not supported
 239  * @retval #CM_ERROR_ALREADY_REGISTERED Callback already registered
 240  * @retval #CM_ERROR_OPERATION_FAILED  Operation failed
 241  *
 242  * @post cm_call_status_cb() will be invoked.
 243  *
 244  * @see cm_unset_call_status_cb()
 245  */
 246 int cm_set_call_status_cb (cm_client_h handle, cm_call_status_cb cb, void *user_data);
 247
 248 /**
 249  * @brief Unsets a callback function.
 250  *
 251  * @since_tizen 2.4
 252  * @privlevel public
 253  * @privilege TBD
 254  *
 255  * @param[in] handle  The handle to use the Call Manager API
 256  *
 257  * @return @c 0 on success,
 258  *         otherwise a negative error value
 259  *
 260  * @retval #CM_ERROR_NONE              Successful
 261  * @retval #CM_ERROR_INVALID_PARAMETER Invalid parameter
 262  * @retval #CM_ERROR_PERMISSION_DENIED Permission denied
 263  * @retval #CM_ERROR_NOT_SUPPORTED     Not supported
 264  * @retval #CM_ERROR_NOT_REGISTERED Callback not registered
 265  * @retval #CM_ERROR_OPERATION_FAILED  Operation failed
 266  *
 267  * @see cm_set_call_status_cb()
 268  */
 269 int cm_unset_call_status_cb (cm_client_h handle);
 270
 271 /**
 272  * @brief Gets the mute status.
 273  *
 274  * @since_tizen 2.4
 275  * @privlevel public
 276  * @privilege %http://tizen.org/privilege/telephony
 277  *
 278  * @param[in] handle The handle from #cm_init()
 279  * @param[out] mutel_status The status of the call (#cm_mute_status_e)
 280  *
 281  * @return @c 0 on success,
 282  *         otherwise a negative error value
 283  *
 284  * @retval #CM_ERROR_NONE              Successful
 285  * @retval #CM_ERROR_INVALID_PARAMETER Invalid parameter
 286  * @retval #CM_ERROR_PERMISSION_DENIED Permission denied
 287  * @retval #CM_ERROR_OPERATION_FAILED  Operation failed
 288  *
 289  * @pre The handle should be obtained from #cm_init()
 290  * @post The should be released by using #cm_deinit()
 291  */
 292 int cm_get_mute_status (cm_client_h handle, cm_mute_status_e *mutel_status);
 293
 294 /**
 295  * @brief Sets a callback function to be invoked when the mute status changes.
 296  *
 297  * @since_tizen 2.4
 298  * @privlevel public
 299  * @privilege %http://tizen.org/privilege/telephony
 300  *
 301  * @param[in] handle  The handle to use the Call Manager API
 302  * @param[in] cb The callback to be invoked when the mute status changes
 303  * @param[in] user_data The user data passed to the callback function
 304  *
 305  * @return @c 0 on success,
 306  *         otherwise a negative error value
 307  *
 308  * @retval #CM_ERROR_NONE              Successful
 309  * @retval #CM_ERROR_INVALID_PARAMETER Invalid parameter
 310  * @retval #CM_ERROR_PERMISSION_DENIED Permission denied
 311  * @retval #CM_ERROR_ALREADY_REGISTERED Callback already registered
 312  * @retval #CM_ERROR_OPERATION_FAILED  Operation failed
 313  *
 314  * @post cm_mute_status_cb() will be invoked.
 315  *
 316  * @see cm_unset_mute_status_cb()
 317  */
 318 int cm_set_mute_status_cb (cm_client_h handle, cm_mute_status_cb cb, void *user_data);
 319
 320 /**
 321  * @brief Unsets a callback function.
 322  *
 323  * @since_tizen 2.4
 324  * @privlevel public
 325  * @privilege %http://tizen.org/privilege/telephony
 326  *
 327  * @param[in] handle  The handle to use the Call Manager API
 328  *
 329  * @return @c 0 on success,
 330  *         otherwise a negative error value
 331  *
 332  * @retval #CM_ERROR_NONE              Successful
 333  * @retval #CM_ERROR_INVALID_PARAMETER Invalid parameter
 334  * @retval #CM_ERROR_PERMISSION_DENIED Permission denied
 335  * @retval #CM_ERROR_NOT_REGISTERED Callback not registered
 336  * @retval #CM_ERROR_OPERATION_FAILED  Operation failed
 337  *
 338  * @see cm_set_mute_status_cb()
 339  */
 340 int cm_unset_mute_status_cb (cm_client_h handle);
 341
 342
 343 /**
 344  * @}
 345  */
 346
 347 #ifdef __cplusplus
 348  }
 349 #endif
 350
 351 #endif /* __TIZEN_CALL_MANAGER_H__ */