include/ITapiCall.h

   1 /*
   2  * libslp-tapi
   3  *
   4  * Copyright (c) 2014 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Ja-young Gu <jygu@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  */
  20
  21 /**
  22  * @file ITapiCall.h
  23  */
  24
  25 /**
  26  * @internal
  27  * @addtogroup CAPI_TELEPHONY_SERVICE_CALL
  28  * @{
  29  */
  30
  31 #ifndef _ITAPI_CALL_H_
  32 #define _ITAPI_CALL_H_
  33
  34 #include <tapi_common.h>
  35 #include <TelCall.h>
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #endif
  41
  42 /**
  43  * @brief Originates MO call setup.
  44  *
  45  * @details This is an asynchronous function. The function completes immediately and call setup proceeds in the background.\n
  46  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.\n
  47  *          However it just means that the API request has been transfered to the CP successfully.\n
  48  *          The actual operation result is being delivered in the corresponding event asynchronously.
  49  *
  50  * <b> Sync (or) Async: </b> This is an Asynchronous API.
  51  *
  52  * <b> Prospective Clients: </b> Embedded call application.
  53  *
  54  * @since_tizen 2.3
  55  * @privlevel platform
  56  * @privilege %http://tizen.org/privilege/telephony.admin
  57  *
  58  * @remarks MO call setup continues in the background. There are multiple states involved in the call setup procedure.\n
  59  *          Depending on whether request completion is successful or not, various event notifications are sent to the client along with data\n
  60  *          associated with the event(Successful data or error information) based on the indication or response received at the Telephony Server.\n
  61  *          Setting up an emergency call when #TelCallType_t is a voice_call, voice call is setup unless the @a dial_number parameter is\n
  62  *          an emergency number known to telephony FW(like 112 for all 2G and above, other numbers may be operator specific or device configuration specific,\n
  63  *          so Telephony FW will read relevant SIM files and refer to internal configuration records).\n
  64  *          If an emergency number is passed and #TelCallType_t is a voice_call, Telephony FW shall setup an emergency phone call.\n
  65  *          When #TelCallType_t is an emergency call, emergency call is always set up.
  66  *
  67  * @param[in] handle The handle from tel_init()
  68  *
  69  * @param[in] pParams #TelCallDial_t contains the CallType(whether it is a voice call or data call) and number
  70  *
  71  * @param[in] callback To register a callback function for result
  72  *
  73  * @param[in] user_data The user data for user specification
  74  *
  75  * @return The return type (int)
  76  *         @c 0 indicates that the operation is completed successfully,\n
  77  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t).
  78  *
  79  * @pre Initialize the Dbus connection with #tel_init.\n
  80  *      Register the telephony event to be listened with #tel_register_noti_event.\n
  81  *      An event loop runs to listen to events.
  82  *
  83  * @see #tel_answer_call #tel_end_call
  84  */
  85 int tel_dial_call(TapiHandle *handle, const TelCallDial_t *pParams, tapi_response_cb callback, void *user_data);
  86
  87 /**
  88  * @brief Supports answering the incoming call by accepting or rejecting the call.
  89  *
  90  * @details This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.\n
  91  *          However it just means that the API request has been transfered to the CP successfully.\n
  92  *          The actual operation result is being delivered in the corresponding event asynchronously.
  93  *
  94  * <b> Sync (or) Async: </b> This is an Asynchronous API.
  95  *
  96  * <b> Prospective Clients: </b> Embedded call application.
  97  *
  98  * @since_tizen 2.3
  99  * @privlevel platform
 100  * @privilege %http://tizen.org/privilege/telephony.admin
 101  *
 102  * @param[in] handle The handle from tel_init()
 103  *
 104  * @param[in] CallHandle The unique handle for referring the call \n
 105  *                       This call handle is available to the application through an incoming call
 106  *                       (TAPI_NOTI_VOICE_CALL_STATUS_INCOMING) event.
 107  *
 108  * @param[in] AnsType The answer type - accept / reject / replace / hold and accept is allowed
 109  *
 110  * @param[in] callback To register a callback function for result
 111  *
 112  * @param[in] user_data The user data for user specification
 113  *
 114  * @return The return type (int)
 115  *         @c 0 indicates that the operation is completed successfully,
 116  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 117  *
 118  * @pre Initialize the Dbus connection with #tel_init.\n
 119  *      Register the telephony event to be listened with #tel_register_noti_event.\n
 120  *      An event loop runs to listen to events.\n
 121  *      Call associated with the call handle should be in the #TAPI_CALL_STATE_INCOM state otherwise the API fails and there can be a
 122  *      a maximum of 1 existing call.
 123  *
 124  * @see tel_dial_call()
 125  * @see tel_end_call()
 126  */
 127 int tel_answer_call(TapiHandle *handle, unsigned int CallHandle, TelCallAnswerType_t AnsType, tapi_response_cb callback, void *user_data);
 128
 129 /**
 130  * @brief Releases the call identified by the call handle irrespective of whether the call is in the hold or active state.
 131  *
 132  * @details It is used when releasing a specific active call from a multiparty call.
 133  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 134  *          However it just means that the API request has been transfered to the CP successfully.
 135  *          The actual operation result is being delivered in the corresponding event asynchronously.
 136  *
 137  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 138  *
 139  * <b> Prospective Clients: </b> Embedded call application.
 140  *
 141  * @since_tizen 2.3
 142  * @privlevel platform
 143  * @privilege %http://tizen.org/privilege/telephony.admin
 144  *
 145  * @remarks In case of the MPTY Call handle, the call end event is returned for each call in MPTY.
 146  *
 147  * @param[in] handle The handle from tel_init()
 148  *
 149  * @param[in] CallHandle A unique handle that refers to the call
 150  *
 151  * @param[in] callback To register a callback function for result
 152  *
 153  * @param[in] EndType The end call type (end specific call/end all calls/end all held calls/end all active calls)
 154  *
 155  * @param[in] user_data The user data for user specification
 156  *
 157  * @return The return type (int)
 158  *         @c 0 indicates that the operation is completed successfully,
 159  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 160  *
 161  * @pre Initialize the Dbus connection with #tel_init.\n
 162  *      Register the telephony event to be listened with #tel_register_noti_event.\n
 163  *      An event loop runs to listen to events.\n
 164  *      The call handle should be valid and there should be an existing call in the active/hold state.
 165  *
 166  * @see tel_dial_call()
 167  * @see tel_answer_call()
 168  */
 169 int tel_end_call(TapiHandle *handle, unsigned int CallHandle, TelCallEndType_t EndType, tapi_response_cb callback, void *user_data);
 170
 171 /**
 172  * @brief Puts the given call on hold.
 173  *
 174  * @details The call identified by the call handle should be in the active state.
 175  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 176  *          However it just means that the API request has been transfered to the CP successfully.
 177  *          The actual operation result is being delivered in the corresponding event asynchronously.
 178  *
 179  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 180  *
 181  * <b> Prospective Clients: </b> Embedded call application.
 182  *
 183  * @since_tizen 2.3
 184  * @privlevel platform
 185  * @privilege %http://tizen.org/privilege/telephony.admin
 186  *
 187  * @param[in] handle The handle from tel_init()
 188  *
 189  * @param[in] CallHandle A unique handle for referring the call
 190  *
 191  * @param[in] callback To register a callback function for result
 192  *
 193  * @param[in] user_data The user data for user specification
 194  *
 195  * @return The return type (int)
 196  *         @c 0 indicates that the operation is completed successfully,
 197  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 198  *
 199  * @pre Initialize the Dbus connection with #tel_init.\n
 200  *      Register the telephony event to be listened with #tel_register_noti_event.\n
 201  *      An event loop runs to listen to events.\n
 202  *      The call identified by the call handle should be in the active state.
 203  *
 204  * @see tel_retrieve_call()
 205  */
 206 int tel_hold_call(TapiHandle *handle, unsigned int CallHandle, tapi_response_cb callback, void *user_data);
 207
 208 /**
 209  * @brief Retrieves the call being held.
 210  *
 211  * @details The call identified by the call handle must be in the held state.
 212  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 213  *          However it just means that the API request has been transfered to the CP successfully.
 214  *          The actual operation result is being delivered in the corresponding event asynchronously.
 215  *
 216  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 217  *
 218  * <b> Prospective Clients: </b> Embedded call application.
 219  *
 220  * @since_tizen 2.3
 221  * @privlevel platform
 222  * @privilege %http://tizen.org/privilege/telephony.admin
 223  *
 224  * @remarks The call duration for the call will be calculated from the moment the call has been connected until the call is released.
 225  *
 226  * @param[in] handle The handle from tel_init()
 227  *
 228  * @param[in] CallHandle A unique handle for referring the call
 229  *
 230  * @param[in] callback To register a callback function for result
 231  *
 232  * @param[in] user_data The user data for user specification
 233  *
 234  * @return The return type (int)
 235  *         @c 0 indicates that the operation is completed successfully,
 236  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 237  *
 238  * @pre Initialize the Dbus connection with #tel_init.\n
 239  *      Register the telephony event to be listened with #tel_register_noti_event.\n
 240  *      An event loop runs to listen to events.\n
 241  *      Call should be in the held state in order to retrieve it into the active state unless no active call is present.
 242  */
 243 int tel_active_call(TapiHandle *handle, unsigned int CallHandle, tapi_response_cb callback, void *user_data);
 244
 245 /**
 246  * @brief Swaps calls. This is only for calls dialed or answered with Telephony.
 247  *
 248  * @details Swap is only available for voice calls.
 249  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 250  *          However it just means that the API request has been transfered to the CP successfully.
 251  *          The actual operation result is delivered in the corresponding event asynchronously.
 252  *
 253  * <b> Notes: </b>
 254  * During a call, a user can place all active calls and accept other held calls with this function.
 255  * If the terminal is not within a call, it will fail.
 256  *
 257  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 258  *
 259  * <b> Prospective Clients: </b> Embedded call application.
 260  *
 261  * @since_tizen 2.3
 262  * @privlevel platform
 263  * @privilege %http://tizen.org/privilege/telephony.admin
 264  *
 265  * @param[in] handle The handle from tel_init()
 266  *
 267  * @param[in] CallHandle1 This is an active call
 268  *
 269  * @param[in] CallHandle2 This is a held call
 270  *
 271  * @param[in] callback To register a callback function for result
 272  *
 273  * @param[in] user_data The user data for user specification
 274  *
 275  * @return The return type (int)
 276  *         @c 0 indicates that the operation has completed successfully,
 277  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 278  *
 279  * @pre Initialize the Dbus connection with #tel_init.\n
 280  *      Register the telephony event to be listened with #tel_register_noti_event.\n
 281  *      An event loop runs to listen to events.
 282  */
 283 int tel_swap_call(TapiHandle *handle, unsigned int CallHandle1, unsigned int CallHandle2, tapi_response_cb callback, void *user_data);
 284
 285 /**
 286  * @brief Starts continuous DTMF by sending a single digit during the call.
 287  *
 288  * @details DTMF is an abbreviation for Dual-tone-multi-frequency. It is used for telecommunication signaling\n
 289  *          over telephone lines in the voice-frequency band between UE and other communication devices.\n
 290  *          For example UE sends a DTMF tone to the server to choose from options which the server provides.\n
 291  *          If the UE is not within a call, this function will fail with an error code.
 292  *
 293  *          This function makes a Dbus method call to the Telephony Sever and gets an immediate feedback.\n
 294  *          However it just means that the API request has been transfered to the CP successfully.\n
 295  *          The actual operation result is being delivered in the corresponding event asynchronously.
 296  *
 297  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 298  *
 299  * <b> Prospective Clients: </b> Embedded call application.
 300  *
 301  * @since_tizen 2.3
 302  * @privlevel platform
 303  * @privilege %http://tizen.org/privilege/telephony.admin
 304  *
 305  * @remarks There will be a single asynchronous notification for all the DTMF digits sent.
 306  *          If the users of this API need an asynchronous\n
 307  *          response for each DTMF digit then the user has to call this API multiple times passing each single DTMF digit in @a pDtmfString.
 308  *
 309  * @remarks To be invoked in the following cases:
 310  *
 311  *          i. Key Press during On-going call
 312  *          ii. DTMF digits passed with PAUSE (,) or WAIT (;)
 313  *
 314  *          In either of the above cases, the application can ONLY send a single DTMF Digit to Telephony.\n
 315  *          In case of PAUSE and WAIT, the application needs to invoke tel_stop_call_cont_dtmf() sequentially (for every digit) without waiting for response from tel_start_call_cont_dtmf().
 316  *
 317  * @param[in] handle The handle from tel_init()
 318  *
 319  * @param[in] dtmf_digit The DTMF digit to be sent from MS
 320  *
 321  * @param[in] callback To register a callback function for result
 322  *
 323  * @param[in] user_data The user data for user specification
 324  *
 325  * @return The return type (TapiHandle *handle, int) \n
 326  *         @c 0 indicates that the operation has completed successfully, \n
 327  *         else it will return failure and an error code (TapiHandle *handle, Refer Doxygen doc or #TapiResult_t)
 328  *
 329  * @pre Initialize the Dbus connection with #tel_init.\n
 330  *      An active call should be present.
 331  */
 332 int tel_start_call_cont_dtmf(TapiHandle *handle, unsigned char dtmf_digit, tapi_response_cb callback, void *user_data);
 333
 334 /**
 335  * @brief Stops continuous DTMF during the call.
 336  *
 337  * @details DTMF is an abbreviation for Dual-tone-multi-frequency. It is used for telecommunication signaling\n
 338  *          over telephone lines in the voice-frequency band between UE and other communication devices.\n
 339  *          For example UE sends a DTMF tone to the server to choose from options which the server provides.\n
 340  *          If the UE is not within a call, this function will fail with an error code.
 341  *
 342  *          This function makes a Dbus method call to the Telephony Sever and gets an immediate feedback.\n
 343  *          However it just means that the API request has been transfered to the CP successfully.\n
 344  *          The actual operation result is being delivered in the corresponding event asynchronously.
 345  *
 346  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 347  *
 348  * <b> Prospective Clients: </b> Embedded call application.
 349  *
 350  * @since_tizen 2.3
 351  * @privlevel platform
 352  * @privilege %http://tizen.org/privilege/telephony.admin
 353  *
 354  * @remarks There will be a single asynchronous notification for all the DTMF digits sent.
 355  *          If the users of this API need an asynchronous
 356  *          response for each DTMF digit then the user has to call this API multiple times passing each single DTMF digit in @a pDtmfString.
 357  *
 358  * @remarks To be invoked in the following cases:
 359  *
 360  *          i. Key Release (post key press) during On-going call
 361  *          ii. DTMF digits passed with PAUSE (,) or WAIT (;)
 362  *
 363  *          Every tel_start_call_cont_dtmf() call needs to be followed by tel_stop_call_cont_dtmf() sequentially.
 364  *
 365  * @param[in] handle The handle from tel_init()
 366  *
 367  * @param[in] callback To register a callback function for result
 368  *
 369  * @param[in] user_data The user data for user specification
 370  *
 371  * @return The return type (int)\n
 372  *         @c 0 indicates that the operation has completed successfully,\n
 373  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 374  *
 375  * @pre Initialize the Dbus connection with #tel_init.\n
 376  *      An active call should be present.\n
 377  *      Start a continuous DTMF request should be sent already.
 378  */
 379 int tel_stop_call_cont_dtmf(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 380
 381 /**
 382  * @brief Sends one or more DTMF digits during the call. (3GPP2 specific)
 383  *
 384  * @details DTMF is an abbreviation for Dual-tone-multi-frequency. It is used for telecommunication signaling\n
 385  *          over telephone lines in the voice-frequency band between UE and other communication devices.\n
 386  *          For example UE sends a DTMF tone to the server to choose from options which the server provides.\n
 387  *          If the UE is not within a call, this function will fail with an error code.
 388  *
 389  *          This function makes a Dbus method call to the Telephony Sever and gets an immediate feedback.\n
 390  *          However it just means that the API request has been transfered to the CP successfully.\n
 391  *          The actual operation result is being delivered in the corresponding event asynchronously.
 392  *
 393  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 394  *
 395  * <b> Prospective Clients: </b> Embedded call application.
 396  *
 397  * @since_tizen 2.3
 398  * @privlevel platform
 399  * @privilege %http://tizen.org/privilege/telephony.admin
 400  *
 401  * @remarks There will be a single asynchronous notification for all the DTMF digits sent.
 402  *          If the users of this API need an asynchronous\n
 403  *          response for each DTMF digit then the user has to call this API multiple times passing each single DTMF digit in @a pDtmfString.
 404  *
 405  * @param[in] handle The handle from tel_init()
 406  *
 407  * @param[in] info A Burst DTMF info structure containing DTMF string, pulse width, and inter digit interval MS
 408  *
 409  * @param[in] callback To register a callback function for result
 410  *
 411  * @param[in] user_data The user data for user specification
 412  *
 413  * @return The return type (int)\n
 414  *         @c 0 indicates that the operation has completed successfully,\n
 415  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 416  *
 417  * @pre Initialize the Dbus connection with #tel_init.\n
 418  *      An active call should be present.
 419  */
 420 int tel_send_call_burst_dtmf(TapiHandle *handle, const TelCallBurstDtmf_t *info, tapi_response_cb callback, void *user_data);
 421
 422 /**
 423  * @brief Joins the given two calls (one call in the active conversation state and the other call in the held state) into conference.
 424  *
 425  * @details This function makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 426  *          However it just means that the API request has been transfered to the CP successfully.
 427  *          The actual operation result is being delivered in the corresponding event asynchronously.
 428  *
 429  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 430  *
 431  * <b> Prospective Clients: </b> Embedded call application.
 432  *
 433  * @since_tizen 2.3
 434  * @privlevel platform
 435  * @privilege %http://tizen.org/privilege/telephony.admin
 436  *
 437  * @remarks The call handle of an active call or held call will be made as MPTY-id, and the other call handle will join in a conference.
 438  *
 439  * @param[in] handle The handle from tel_init()
 440  *
 441  * @param[in] CallHandle1 A unique handle which is either an active call or a held call
 442  *
 443  * @param[in] CallHandle2 A unique call handle
 444  *
 445  * @param[in] callback To register a callback function for result
 446  *
 447  * @param[in] user_data The user data for user specification
 448  *
 449  * @return The return type (int)
 450  *         @c 0 indicates that the operation is completed successfully,
 451  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 452  *
 453  * @pre Initialize the Dbus connection with #tel_init.\n
 454  *      Register the telephony event to be listened with #tel_register_noti_event.\n
 455  *      An event loop runs to listen to events.\n
 456  *      For a Multiparty call or for joining two calls into conference, there should be one call in the active state and another call
 457  *      in the held state.
 458  *
 459  * @see tel_split_call()
 460  */
 461 int tel_join_call(TapiHandle *handle, unsigned int CallHandle1, unsigned int CallHandle2, tapi_response_cb callback, void *user_data);
 462
 463 /**
 464  * @brief Triggers splitting a private call from a multiparty call.
 465  *
 466  * @details This API allows creating a private communication with one of the remote parties in a
 467  *          multiparty session. TAPI client application has to pass the call handle which needs
 468  *          to be split from the multiparty call.
 469  *
 470  *          This function makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 471  *          However it just means that the API request has been transfered to the CP successfully.
 472  *          The actual operation result is being delivered in the corresponding event asynchronously.
 473  *
 474  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 475  *
 476  * <b> Prospective Clients: </b> Embedded call application.
 477  *
 478  * @since_tizen 2.3
 479  * @privlevel platform
 480  * @privilege %http://tizen.org/privilege/telephony.admin
 481  *
 482  * @param[in] handle The handle from tel_init()
 483  *
 484  * @param[in] CallHandle The handle of the call to be made private \n
 485  *                       The call handle referring to the call that is to be split from the conference
 486  *                       (call to be made private)
 487  *
 488  * @param[in] callback To register a callback function for result
 489  *
 490  * @param[in] user_data The user data for user specification
 491  *
 492  * @return The return type (int)
 493  *         @c 0 indicates that the operation is completed successfully,
 494  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 495  *
 496  * @pre Initialize the Dbus connection with #tel_init.\n
 497  *      Register the telephony event to be listened with #tel_register_noti_event.\n
 498  *      An event loop runs to listen to events.\n
 499  *      The call should be in a multiparty conference call.
 500  *
 501  * @post The split call will be the active call and the conference call will be the held call.
 502  *
 503  * @see tel_join_call()
 504  */
 505 int tel_split_call(TapiHandle *handle, unsigned int CallHandle, tapi_response_cb callback, void *user_data);
 506
 507 /**
 508  * @brief Triggers making an explicit call transfer by connecting the two parties where one party is being
 509  *        active (active state) and another party is being held (held state).
 510  *
 511  * @details This function makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 512  *          However it just means that the API request has been transfered to the CP successfully.
 513  *          The actual operation result is being delivered in the corresponding event asynchronously.
 514  *
 515  * <b> Notes: </b>
 516  * The ECT supplementary service enables the served mobile subscriber (subscriber A) who has two calls,
 517  * each of which can be an incoming or outgoing call, to connect the other parties in the two calls
 518  * and release the served mobile subscriber's own connection.
 519  * Prior to transfer, the connection shall have been established on the call
 520  * between subscriber A and subscriber B. On the call between subscriber A and subscriber C,
 521  * either the connection shall have been established prior to transfer, or, as a network option,
 522  * or the transfer can occur while subscriber C is being informed of the call
 523  * (i.e. the connection has not yet been established.).
 524  *
 525  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 526  *
 527  * <b> Prospective Clients: </b> Embedded call application.
 528  *
 529  * @since_tizen 2.3
 530  * @privlevel platform
 531  * @privilege %http://tizen.org/privilege/telephony.admin
 532  *
 533  * @param[in] handle The handle from tel_init()
 534  *
 535  * @param[in] CallHandle The call handle of an active call
 536  *
 537  * @param[in] callback To register the callback function for result
 538  *
 539  * @param[in] user_data The user data for user specification
 540  *
 541  * @return The return type (int)
 542  *         @c 0 indicates that the operation is completed successfully,
 543  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 544  *
 545  * @pre Initialize the Dbus connection with #tel_init.\n
 546  *      Register the telephony event to be listend with #tel_register_noti_event.\n
 547  *      An event loop runs to listen to events.\n
 548  *      In order to call transfer, served mobile subscriber should have 2 calls, one in the active state and another one
 549  *      in the held state.
 550  *
 551  * @post When the request has been completed successfully, a call end indication will be sent to both the calls (active and held).
 552  */
 553 int tel_transfer_call(TapiHandle *handle, unsigned int CallHandle, tapi_response_cb callback, void *user_data);
 554
 555 /**
 556  * @brief Gets the status of the current call identified by the call handle whenever the application wants the call status, call handle must be valid.
 557  *
 558  * @details This function makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 559  *          However it just means that the API request has been transfered to the CP successfully.
 560  *          The actual operation result is being delivered in the corresponding event asynchronously.
 561  *
 562  * <b> Sync (or) Async: </b> This is a Synchronous API.
 563  *
 564  * <b> Prospective Clients: </b> Embedded call application.
 565  *
 566  * @since_tizen 2.3
 567  * @privlevel public
 568  * @privilege %http://tizen.org/privilege/telephony
 569  *
 570  * @param[in] handle The handle from tel_init()
 571  *
 572  * @param[in] call_id A unique handle for referring the call
 573  *
 574  * @param[out] out The call status information like destination number, call direction (MO or MT), call type (voice or data), whether
 575  *                 the call is in the conference state or not \n
 576  *                 The present call state is returned through this parameter
 577  *
 578  * @return The return type (int)
 579  *         @c 0 indicates that the operation is completed successfully,
 580  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 581  *
 582  * @pre Initialize the Dbus connection with #tel_init.
 583  */
 584 int tel_get_call_status(TapiHandle *handle, int call_id, TelCallStatus_t *out );
 585
 586 /**
 587  * @brief Gets the status all of the current call
 588  *
 589  * <b> Sync (or) Async: </b> This is a Synchronous API.
 590  *
 591  * <b> Prospective Clients: </b> Embedded call application.
 592  *
 593  * @since_tizen 2.3
 594  * @privlevel public
 595  * @privilege %http://tizen.org/privilege/telephony
 596  *
 597  * @see tel_get_call_status()
 598  */
 599 int tel_get_call_status_all(TapiHandle *handle, TelCallStatusCallback cb, void *user_data);
 600
 601 /**
 602  * @brief Redirects the incoming call to another subscriber.
 603  *
 604  * @details If informed about an incoming call this call may be redirected to another destination by
 605  *          entering the destination number. The destination number to which the current
 606  *          incoming call needs to be redirected is specified via the info argument.
 607  *
 608  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 609  *
 610  * <b> Prospective Clients: </b> Embedded call application.
 611  *
 612  * @since_tizen 2.3
 613  * @privlevel platform
 614  * @privilege %http://tizen.org/privilege/telephony.admin
 615  *
 616  * @param[in] handle The handle from tel_init()
 617  *
 618  * @param[in] CallHandle An incoming call handle
 619  *
 620  * @param[out] deflect_info The destination number
 621  *
 622  * @param[in] callback To register a callback function for result
 623  *
 624  * @param[in] user_data The user data for user specification
 625  *
 626  * @return The return type (int)
 627  *         @c 0 indicates that the operation is completed successfully,
 628  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 629  *
 630  * @pre Initialize the Dbus connection with #tel_init.\n
 631  *      Register the telephony event to be listened with #tel_register_noti_event.\n
 632  *      An event loop runs to listen to events.
 633  */
 634 int tel_deflect_call(TapiHandle *handle, unsigned int CallHandle, const TelCallDeflectDstInfo_t *deflect_info, tapi_response_cb callback, void *user_data);
 635
 636 /**
 637  * @brief Gets the call volume.
 638  *
 639  * @details This function makes a Dbus method call to the Telephony Server and returns an immediate value.
 640  *          However it just means that the API request has been transfered to the CP successfully.
 641  *          The actual operation result is being delivered in the corresponding event asynchronously.
 642  *
 643  * <b> Sync (or) Async: </b> This is a Asynchronous API.
 644  *
 645  * <b> Prospective Clients: </b> Embedded call application.
 646  *
 647  * @since_tizen 2.3
 648  * @privlevel public
 649  * @privilege %http://tizen.org/privilege/telephony
 650  *
 651  * @param[in] handle The handle from tel_init()
 652  *
 653  * @param[in] device The sound device
 654  *
 655  * @param[in] type The sound type
 656  *
 657  * @param[in] callback To register a callback function for result
 658  *
 659  * @param[in] user_data The user data for user specification
 660  *
 661  * @return The return type (int)
 662  *         @c 0 indicates that the operation is completed successfully,
 663  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 664  */
 665 int tel_get_call_volume_info(TapiHandle *handle, TelSoundDevice_t device, TelSoundType_t type, tapi_response_cb callback, void *user_data );
 666
 667 /**
 668  * @brief Sets the call volume.
 669  *
 670  * @details This function makes a Dbus method call to the Telephony Server and returns an immediate value.
 671  *          However it just means that the API request has been transfered to the CP successfully.
 672  *          The actual operation result is being delivered in the corresponding event asynchronously.
 673  *
 674  * <b> Sync (or) Async: </b> This is a Asynchronous API.
 675  *
 676  * <b> Prospective Clients: </b> Embedded call application.
 677  *
 678  * @since_tizen 2.3
 679  * @privlevel platform
 680  * @privilege %http://tizen.org/privilege/telephony.admin
 681  *
 682  * @param[in] handle The handle from tel_init()
 683  *
 684  * @param[in] info The call volume information
 685  *
 686  * @param[in] callback To register a callback function for result
 687  *
 688  * @param[in] user_data The user data for user specification
 689  *
 690  * @return The return type (int)
 691  *         @c 0 indicates that the operation has completed successfully,
 692  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 693  */
 694 int tel_set_call_volume_info(TapiHandle *handle, TelCallVolumeInfo_t *info, tapi_response_cb callback, void *user_data );
 695
 696 /**
 697  * @brief Sets the call sound path.
 698  *
 699  * @details This function makes a Dbus method call to the Telephony Server and returns an immediate value.
 700  *          However it just means that the API request has been transfered to the CP successfully.
 701  *          The actual operation result is being delivered in the corresponding event asynchronously.
 702  *
 703  * <b> Sync (or) Async: </b> This is a Asynchronous API.
 704  *
 705  * <b> Prospective Clients: </b> Embedded call application.
 706  *
 707  * @since_tizen 2.3
 708  * @privlevel platform
 709  * @privilege %http://tizen.org/privilege/telephony.admin
 710  *
 711  * @param[in] handle The handle from tel_init()
 712  *
 713  * @param[in] path The call sound path information
 714  *
 715  * @param[in] callback To register a callback function for result
 716  *
 717  * @param[in] user_data The user data for user specification
 718  *
 719  * @return The return type (int)
 720  *         @c 0 indicates that the operation is completed successfully,
 721  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 722  */
 723 int tel_set_call_sound_path(TapiHandle *handle, TelCallSoundPathInfo_t *path, tapi_response_cb callback, void *user_data );
 724
 725 /**
 726  * @brief Sets the call mute state.
 727  *
 728  * @details This function makes a Dbus method call to the Telephony Server and returns an immediate value.
 729  *          However it just means that the API request has been transfered to the CP successfully.
 730  *          The actual operation result is being delivered in the corresponding event asynchronously.
 731  *
 732  * <b> Sync (or) Async: </b> This is a Asynchronous API.
 733  *
 734  * <b> Prospective Clients: </b> Embedded call application.
 735  *
 736  * @since_tizen 2.3
 737  * @privlevel platform
 738  * @privilege %http://tizen.org/privilege/telephony.admin
 739  *
 740  * @param[in] handle The handle from tel_init()
 741  *
 742  * @param[in] mute The sound mute status
 743  *
 744  * @param[in] callback To register a callback function for result
 745  *
 746  * @param[in] user_data The user data for user specification
 747  *
 748  * @return The return type (int)
 749  *         @c 0 indicating that the operation has completed successfully,
 750  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 751  */
 752 int tel_set_call_mute_status(TapiHandle *handle, TelSoundMuteStatus_t mute, TelSoundMutePath_t path, tapi_response_cb callback, void *user_data );
 753
 754 /**
 755  * @brief Gets the call mute state.
 756  *
 757  * @details This function makes a Dbus method call to the Telephony Server and returns an immediate value.
 758  *          However it just means that the API request has been transfered to the CP successfully.
 759  *          The actual operation result is delivered in the corresponding event asynchronously.
 760  *
 761  * <b> Sync (or) Async: </b> This is a Asynchronous API.
 762  *
 763  * <b> Prospective Clients: </b> Embedded call application.
 764  *
 765  * @since_tizen 2.3
 766  * @privlevel public
 767  * @privilege %http://tizen.org/privilege/telephony
 768  *
 769  * @param[in] handle The handle from tel_init()
 770  *
 771  * @param[in] callback To register a callback function for result
 772  *
 773  * @param[in] user_data The user data for user specification
 774  *
 775  * @return The return type (int)
 776  *         @c 0 indicates that the operation is completed successfully,
 777  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 778  */
 779 int tel_get_call_mute_status(TapiHandle *handle, tapi_response_cb callback, void *user_data );
 780
 781 /**
 782  * @brief Gets the voice privacy option mode in the phone. (3GPP2 specific)
 783  *
 784  * @details This function makes a Dbus method call to the Telephony Sever and gets an immediate feedback.\n
 785  *          However it just means that the API request has been transfered to the CP successfully.\n
 786  *          The actual operation result is being delivered in the corresponding event asynchronously.
 787  *
 788  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 789  *
 790  * <b> Prospective Clients: </b> Embedded call application.
 791  *
 792  * @since_tizen 2.3
 793  * @privlevel public
 794  * @privilege %http://tizen.org/privilege/telephony
 795  *
 796  * @param[in] handle The handle from tel_init()
 797  *
 798  * @param[in] callback To register a callback function for result
 799  *
 800  * @param[in] user_data The user data for user specification
 801  *
 802  * @return The return type (int)\n
 803  *         @c 0 indicates that the operation has completed successfully,\n
 804  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 805  *
 806  * @pre Initialize the Dbus connection with #tel_init.\n
 807  *      Register the telephony event to be listened with #tel_register_noti_event.\n
 808  *      An event loop runs to listen to events.
 809  */
 810 int tel_get_call_privacy_mode(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 811
 812 /**
 813  * @brief Sets the voice privacy option mode in the phone. It is available only where a call exists. (3GPP2 specific)
 814  *
 815  * @details This function makes a Dbus method call to the Telephony Sever and gets an immediate feedback.\n
 816  *          However it just means that the API request has been transfered to the CP successfully.\n
 817  *          The actual operation result is being delivered in the corresponding event asynchronously.
 818  *
 819  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 820  *
 821  * <b> Prospective Clients: </b> Embedded call application.
 822  *
 823  * @since_tizen 2.3
 824  * @privlevel platform
 825  * @privilege %http://tizen.org/privilege/telephony.admin
 826  *
 827  * @param[in] handle The handle from tel_init()
 828  *
 829  * @param[in] PrivacyMode The voice privacy option mode(TapiHandle *handle, ENHANCED or STANDARD)
 830  *
 831  * @param[in] callback To register a callback function for result
 832  *
 833  * @param[in] user_data The user data for user specification
 834  *
 835  * @return The return type (int)\n
 836  *         @c 0 indicates that the operation has completed successfully,\n
 837  *         else it will return failure and an error code (Refer Doxygen doc or #TapiResult_t)
 838  *
 839  * @pre Initialize the Dbus connection with #tel_init.\n
 840  *      Register the telephony event to be listened with #tel_register_noti_event.\n
 841  *      An event loop runs to listen to events.
 842  */
 843 int tel_set_call_privacy_mode(TapiHandle *handle, TelCallPrivacyMode_t PrivacyMode, tapi_response_cb callback, void *user_data);
 844
 845 /**
 846  * @brief This function is called to set 'preferred' Voice Subscription.
 847  *
 848  * @since_tizen 2.3
 849  * @privlevel platform
 850  * @privilege %http://tizen.org/privilege/telephony.admin
 851  *
 852  * @param [in] handle
 853  * - handle from tel_init().
 854  *
 855  * @param [in] preferred_subscription
 856  * - 'preferred' Voice Subscription.
 857  * - Refer #TelCallPreferredVoiceSubs_t for Subscription details
 858  *
 859  * @param [in] callback
 860  * - To register callback function for result.
 861  *
 862  * @param [in] user_data
 863  * - user_data for user specification.
 864  *
 865  * @post
 866  *  - None.
 867  *
 868  * @return Return Type (int) \n
 869  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 870  * - Refer #TapiResult_t for failure and error code
 871  *
 872  * @par Prospective Clients:
 873  * External Apps.
 874  */
 875 int tel_set_call_preferred_voice_subscription(TapiHandle *handle, TelCallPreferredVoiceSubs_t preferred_subscription,
 876         tapi_response_cb callback, void *user_data);
 877
 878 /**
 879  * @brief This function is called to get the 'preferred' Voice Subscription.
 880  *
 881  * @since_tizen 2.3
 882  * @privlevel public
 883  * @privilege %http://tizen.org/privilege/telephony
 884  *
 885  * @param [in] handle
 886  * - handle from tel_init().
 887  *
 888  * @param [out] preferred_subscription
 889  * - 'preferred' Voice Subscription.
 890  * - Refer #TelCallPreferredVoiceSubs_t for Subscription details
 891  *
 892  * @post
 893  *  - None.
 894  *
 895  * @return Return Type (int) \n
 896  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 897  * - Refer #TapiResult_t for failure and error code
 898  *
 899  * @par Prospective Clients:
 900  * External Apps.
 901  */
 902 int tel_get_call_preferred_voice_subscription(TapiHandle *handle, TelCallPreferredVoiceSubs_t *preferred_subscription);
 903
 904 #ifdef __cplusplus
 905 }
 906 #endif
 907
 908 #endif  /* _ITAPI_CALL_H_ */
 909
 910 /**
 911  * @}
 912  */