include/ITapiSs.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 ITapiSs.h
  23  */
  24
  25 /**
  26  * @internal
  27  * @addtogroup CAPI_TELEPHONY_SERVICE_SS
  28  * @{
  29  */
  30
  31 #ifndef _ITAPI_SS_H_
  32 #define _ITAPI_SS_H_
  33
  34 #include <tapi_common.h>
  35 #include <TelSs.h>
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #endif
  41
  42 /**
  43  * @brief Sends a request to activate/deactivate call barring.
  44  *
  45  * @details This service allows a mobile subscriber to activate barring of certain categories
  46  *          of outgoing or incoming calls according to a barring program which is selected from a set
  47  *          of one or more barring programs chosen at provision time and is valid for all outgoing or incoming calls, or just those associated
  48  *          with a specific basic service group. Also this API allows deactivating call barring based on categories set.
  49  *          If the user calls this function with a wrong password 3 times subsequently, the barring service can be blocked.
  50  *          If this function is called normally, the asynchronous response comes in a few seconds from the network. The response indicates
  51  *          whether the service request has been granted or not.
  52  *
  53  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
  54  *          However it just means that the API request has been transfered to the CP successfully.
  55  *          The actual operation result is delivered with the async response as below.
  56  *
  57  * <b> Sync (or) Async: </b> This is an Asynchronous API.
  58  *
  59  * <b> Prospective Clients: </b> External Apps.
  60  *
  61  * @since_tizen 2.3
  62  * @privlevel platform
  63  * @privilege %http://tizen.org/privilege/telephony.admin
  64  *
  65  * @param[in] handle The handle from tel_init()
  66  *
  67  * @param[in] info The information about call barring
  68  *
  69  * @param[in] callback To register a callback function for result
  70  *
  71  * @param[in] user_data The user data for user specification
  72  *
  73  * @return The return type (int) \n
  74  *         #TAPI_API_SUCCESS - indicates that the operation is completed successfully. \n
  75  *         Refer #TapiResult_t for failure and error code.
  76  *
  77  * @pre Initialize the Dbus connection with #tel_init.
  78  *
  79  * @see tel_get_ss_barring_status()
  80  * @see tel_change_ss_barring_password()
  81  */
  82 int tel_set_ss_barring(TapiHandle *handle, TelSsBarringInfo_t *info, tapi_response_cb callback, void *user_data);
  83
  84 /**
  85  * @brief Gets a call barring status.
  86  *
  87  * @details The mobile subscriber may determine which outgoing or incoming call should be barred
  88  *          by subscribing a set of one or more unique barring programs.
  89  *          If this function is called normally, the asynchronous response comes in a few seconds from the network.
  90  *          The response indicates the service status.
  91  *
  92  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
  93  *          However it just means that the API request has been transfered to the CP successfully.
  94  *          The actual operation result is delivered with the async response as below.
  95  *
  96  * <b> Sync (or) Async: </b> This is an Asynchronous API.
  97  *
  98  * <b> Prospective Clients: </b> External Apps.
  99  *
 100  * @since_tizen 2.3
 101  * @privlevel public
 102  * @privilege %http://tizen.org/privilege/telephony
 103  *
 104  * @param[in] handle The handle from tel_init()
 105  *
 106  * @param[in] ss_class The type of call i.e. Voice call, Video Call, and so on
 107  *
 108  * @param[in] type The barring type i.e. Outgoing international, outgoing all, Incoming all, and so on
 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 (#TapiResult_t) \n
 115  *         #TAPI_API_SUCCESS - indicates that the operation is completed successfully. \n
 116  *         Refer #TapiResult_t for failure and error code.
 117  *
 118  * @pre Initialize the Dbus connection with #tel_init.
 119  *
 120  * @see tel_set_ss_barring()
 121  * @asee tel_change_ss_barring_password()
 122  */
 123 int tel_get_ss_barring_status(TapiHandle *handle, TelSsClass_t ss_class, TelSsBarringType_t type, tapi_response_cb callback, void *user_data);
 124
 125 /**
 126  * @brief Allows changing of the barring password in the network.
 127  *
 128  * @details The user can request the network to change his own barring password. If the old password is not same as
 129  *          what the network knows, the request will be rejected by the network. New password should be entered separately twice
 130  *          to confirm the correctness of the user input. Otherwise, the request must be rejected by the Telephony Server.
 131  *          If the user calls this function with a wrong old password 3 times subsequently, the barring service can be blocked.
 132  *          If this function is called normally, the asynchronous response comes in a few seconds from the network.
 133  *          The response indicates whether the service request has been granted or not.
 134  *
 135  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 136  *          However it just means that the API request has been transfered to the CP successfully.
 137  *          The actual operation result is delivered with the async response as below.
 138  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 139  *
 140  * <b> Prospective Clients: </b> External Apps.
 141  *
 142  * @since_tizen 2.3
 143  * @privlevel platform
 144  * @privilege %http://tizen.org/privilege/telephony.admin
 145  *
 146  * @remarks Based on 3GPP TS 22.030 section 6.5.4 Registration of New Password. Only one Change Barring Password request is allowed
 147  *          at a time and TS might return #TAPI_API_REQUEST_MAX_IN_PROGRESS if another request is received.
 148  *
 149  * @param[in] handle The handle from tel_init()
 150  *
 151  * @param[in] old_password The old password set for Barring in the Network \n
 152  *                         This is a Null terminated string.
 153  *
 154  * @param[in] new_password The new password set for Barring in the Network \n
 155  *                         This is a Null terminated string
 156  *
 157  * @param[in] new_password_again A new password again \n
 158  *                               This is a Null terminated string
 159  *
 160  * @param[in] callback To register a callback function for result
 161  *
 162  * @param[in] user_data The user data for user specification
 163  *
 164  * @return The return type (int) \n
 165  *         #TAPI_API_SUCCESS - indicates that the operation is completed successfully. \n
 166  *         Refer #TapiResult_t for failure and error code.
 167  *
 168  * @pre Initialize the Dbus connection with #tel_init.
 169  *      An event loop runs to listen to events.
 170  */
 171 int tel_change_ss_barring_password(TapiHandle *handle,
 172                 const char *old_password,
 173                 const char *new_password,
 174                 const char *new_password_again,
 175                 tapi_response_cb callback, void *user_data);
 176
 177 /**
 178  *
 179  * @brief Allows to set the (register/erase/activate/deactivate) call forwarding option at the network.
 180  *
 181  * @details This enables to forward the calls to another party. This service permits a called mobile subscriber
 182  *          to have the network send all incoming calls, or just those associated with a specific Basic service group,
 183  *          addressed to the called mobile subscriber's directory number and which meets
 184  *          various call FORWARD conditions, to another directory number.
 185  *          The ability of the served mobile subscriber to originate calls is unaffected.
 186  *          If the service is activated, a call is forwarded only if this call forward condition occurs.
 187  *          An application has to call this API in order to explicitly register/erase/activate/deactivate
 188  *          call forwarding. Request will be passed irrespective of whether
 189  *          another SS call forward is already ongoing or not.
 190  *
 191  *          If this function is called normally, the asynchronous response comes in a few seconds from the network. The response indicates
 192  *          whether the service request has been granted or not.
 193  *
 194  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 195  *          However it just means that the API request has been transfered to the CP successfully.
 196  *          The actual operation result is delivered with the async response as below.
 197  *
 198  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 199  *
 200  * <b> Prospective Clients: </b> External Apps.
 201  *
 202  * @since_tizen 2.3
 203  * @privlevel platform
 204  * @privilege %http://tizen.org/privilege/telephony.admin
 205  *
 206  * @param[in] handle The handle from tel_init()
 207  *
 208  * @param[in] info The Call forward information such as a forward mode, a forward type, and so on
 209  *
 210  * @param[in] callback To register a callback function for result
 211  *
 212  * @param[in] user_data The user data for user specification
 213  *
 214  * @return The return type (int) \n
 215  *         #TAPI_API_SUCCESS - indicates that the operation is completed successfully. \n
 216  *         Refer #TapiResult_t for failure and error code.
 217  *
 218  * @pre Initialize the Dbus connection with #tel_init.
 219  *
 220  * @see tel_get_ss_forward_status()
 221  */
 222 int tel_set_ss_forward(TapiHandle *handle, const TelSsForwardInfo_t *info, tapi_response_cb callback, void *user_data);
 223
 224 /**
 225  * @brief Provides an option to get the call forwarding status of different calls from the Network.
 226  *
 227  * @details The data request procedure enables the mobile subscriber to obtain information about the data stored in the PLMN.
 228  *          After having requested this procedure the network shall return the following information:\n
 229  *          - In response to a general data request the served mobile subscriber should be given a list of all Basic service groups
 230  *                to which call forwarding unconditional is registered, including information on whether or not it is active and operative,
 231  *                and the associated forwarded-to numbers\n
 232  *          - In response to a specific request concerning one particular Basic service group,
 233  *                the served mobile subscriber should be informed whether or not call forwarding unconditional is registered,
 234  *                including information on whether or not it is active and operative for that Basic service group.\n
 235  *                If CFU is registered, the associated forwarded-to number shall be given.
 236  *
 237  *            If this function is called normally, the asynchronous response comes in a few seconds from the network.
 238  *            The response indicates the service status.
 239  *
 240  *            This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 241  *            However it just means that the API request has been transfered to the CP successfully.
 242  *            The actual operation result is delivered with the async response as below.
 243  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 244  *
 245  * <b> Prospective Clients: </b> External Apps.
 246  *
 247  * @since_tizen 2.3
 248  * @privlevel public
 249  * @privilege %http://tizen.org/privilege/telephony
 250  *
 251  * @param[in] handle The handle from tel_init()
 252  *
 253  * @param[in] ss_class The Forward call type i.e. voice call, Video Call, Data Calls, and so on
 254  *
 255  * @param[in] condition The forward condition i.e. unconditional, when no reply, when busy, when not reachable, and so on
 256  *
 257  * @param[in] callback To register a callback function for result
 258  *
 259  * @param[in] user_data The user data for user specification
 260  *
 261  * @return The return type (int) \n
 262  *         #TAPI_API_SUCCESS - indicates that the operation is completed successfully. \n
 263  *         Refer #TapiResult_t for failure and error code.
 264  *
 265  * @pre Initialize the Dbus connection with #tel_init.
 266  *
 267  * @see tel_set_ss_forward()
 268  */
 269 int tel_get_ss_forward_status(TapiHandle *handle, TelSsClass_t ss_class, TelSsForwardWhen_t condition, tapi_response_cb callback, void *user_data);
 270
 271 /**
 272  *
 273  * @brief Activates/deactivates the call waiting service.
 274  *
 275  * @details The call waiting service permits a mobile to be notified of an incoming
 276  *          call (as per basic call procedures) while the traffic channel (BM or LM) is not available for the incoming call and the mobile subscriber
 277  *          is engaged in an active or held call. Subsequently, the subscriber can accept, reject, or ignore the incoming call.
 278  *          If this function is called normally, the asynchronous response comes in a few seconds from the network. The response indicates
 279  *          whether the service request has been granted or not.
 280  *
 281  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 282  *          However it just means that the API request has been transfered to the CP successfully.
 283  *          The actual operation result is delivered with the async response as below.
 284  *
 285  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 286  *
 287  * <b> Prospective Clients: </b> External Apps.
 288  *
 289  * @since_tizen 2.3
 290  * @privlevel platform
 291  * @privilege %http://tizen.org/privilege/telephony.admin
 292  *
 293  * @param[in] handle The handle from tel_init()
 294  *
 295  * @param[in] info The status of call-waiting service i.e. On (TRUE) or off (FALSE)
 296  *
 297  * @param[in] callback To register a callback function for result
 298  *
 299  * @param[in] user_data The user data for user specification
 300  *
 301  * @return The return type (int) \n
 302  *         #TAPI_API_SUCCESS - indicates that the operation is completed successfully. \n
 303  *         Refer #TapiResult_t for failure and error code
 304  *
 305  * @pre Initialize the Dbus connection with #tel_init.
 306  *
 307  * @see tel_get_ss_waiting_status()
 308  */
 309 int tel_set_ss_waiting(TapiHandle *handle, const TelSsWaitingInfo_t *info, tapi_response_cb callback, void *user_data);
 310
 311 /**
 312  * @brief Gets the status of the call waiting service.
 313  *
 314  * @details The call waiting service permits a mobile to be notified of an incoming call
 315  *          (as per basic call procedures) while the traffic channel (BM or LM) is not available for the incoming call and the mobile subscriber
 316  *          is engaged in an active or held call. Subsequently, the subscriber can accept, reject, or ignore the incoming call.
 317  *          If this function is called normally, the asynchronous response comes in a few seconds from the network.
 318  *          The response indicates the service status.
 319  *
 320  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 321  *          However it just means that the API request has been transfered to the CP successfully.
 322  *          The actual operation result is delivered with the async response as below.
 323  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 324  *
 325  * <b> Prospective Clients: </b> External Apps.
 326  *
 327  * @since_tizen 2.3
 328  * @privlevel public
 329  * @privilege %http://tizen.org/privilege/telephony
 330  *
 331  * @param[in] handle The handle from tel_init()
 332  *
 333  * @param[in] ss_class The call types
 334  *
 335  * @param[in] callback To register a callback function for result
 336  *
 337  * @param[in] user_data The user data for user specification
 338  *
 339  * @return The return type (int) \n
 340  *         #TAPI_API_SUCCESS - indicates that the operation is completed successfully. \n
 341  *         Refer #TapiResult_t for failure and error code
 342  *
 343  * @pre Initialize the Dbus connection with #tel_init.
 344  *
 345  * @see tel_set_ss_waiting()
 346  */
 347 int tel_get_ss_waiting_status(TapiHandle *handle, const TelSsClass_t ss_class, tapi_response_cb callback, void *user_data);
 348
 349 /**
 350  * @brief Activates/deactivates the status of the calling line identity service.
 351  *
 352  * @details The group of Line Identification Supplementary Services is divided into the following six Supplementary Services:\n
 353  *          CLIP - Calling line identification presentation\n
 354  *                 This Supplementary Service provides the ability to indicate the line identity of the calling party to the called party.
 355  *                 The network shall deliver the calling line identity to the called party at call set-up time,
 356  *                 regardless of the terminal capability to handle the information.\n
 357  *          CLIR - Calling line identification restriction\n
 358  *                     The CLIR Supplementary Service is a Supplementary Service offered to the calling party
 359  *                     to prevent presentation of the calling party's line identity, to the called party.\n
 360  *          COLP - Connected line identification presentation\n
 361  *                 This Supplementary Service is not a dialing check but an indication to the calling subscriber
 362  *                 of the connected line identity in a full ISDN/PLMN environment,
 363  *                 the connected line identity shall include all the information necessary to unambiguously identify the connected party.
 364  *                 The network shall deliver the connected line identity to the calling party
 365  *                 regardless of the terminal capability to handle the information.\n
 366  *          COLR - Connected line identification restriction\n
 367  *                 The COLR Supplementary Service is a Supplementary Service offered
 368  *                 to the connected party to prevent presentation of the connected line identity, to the calling party.
 369  *                 In the case where the calling party has an override category.\n
 370  *          CDIP - Called line identification presentation\n
 371  *          CNAP - Calling name presentation\n
 372  *                This function queries the service status with #TelSsCliType_t.
 373  *
 374  *          If this function is called normally, the asynchronous response comes in a few seconds from the network.
 375  *          The response indicates the service status.
 376  *
 377  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 378  *          However it just means that the API request has been transfered to the CP successfully.
 379  *          The actual operation result is delivered with the async response as below:
 380  *
 381  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 382  *
 383  * <b> Prospective Clients: </b> External Apps.
 384  *
 385  * @since_tizen 2.3
 386  * @privlevel platform
 387  * @privilege %http://tizen.org/privilege/telephony.admin
 388  *
 389  * @param[in] handle The handle from tel_init()
 390  *
 391  * @param[in] type The Cli service type
 392  *
 393  * @param[in] status The Cli Status
 394  *
 395  * @param[in] callback To register a callback function for result
 396  *
 397  * @param[in] user_data The user data for user specification
 398  *
 399  * @return The return type (int) \n
 400  *         #TAPI_API_SUCCESS - indicates that the operation is completed successfully. \n
 401  *         Refer #TapiResult_t for failure and error code
 402  *
 403  * @pre Initialize the Dbus connection with #tel_init.
 404  */
 405 int tel_set_ss_cli_status(TapiHandle *handle, TelSsCliType_t type, TelSsCliStatus_t status, tapi_response_cb callback, void *user_data);
 406
 407 /**
 408  * @brief Gets the status of the calling line identity service.
 409  *
 410  * @details The group of Line Identification Supplementary Services is divided into the following six Supplementary Services:\n
 411  *          CLIP - Calling line identification presentation\n
 412  *                 This Supplementary Service provides the ability to indicate the line identity of the calling party to the called party.
 413  *                 The network shall deliver the calling line identity to the called party at call set-up time,
 414  *                 regardless of the terminal capability to handle the information.\n
 415  *          CLIR - Calling line identification restriction\n
 416  *                     The CLIR Supplementary Service is a Supplementary Service offered to the calling party
 417  *                     to prevent presentation of the calling party's line identity, to the called party.\n
 418  *          COLP - Connected line identification presentation\n
 419  *                 This Supplementary Service is not a dialing check but an indication to the calling subscriber
 420  *                 of the connected line identity in a full ISDN/PLMN environment,
 421  *                 the connected line identity shall include all the information necessary to unambiguously identify the connected party.
 422  *                 The network shall deliver the connected line identity to the calling party
 423  *                 regardless of the terminal capability to handle the information.\n
 424  *          COLR - Connected line identification restriction\n
 425  *                 The COLR Supplementary Service is a Supplementary Service offered
 426  *                 to the connected party to prevent presentation of the connected line identity, to the calling party.
 427  *                 In the case where the calling party has an override category.\n
 428  *          CDIP - Called line identification presentation\n
 429  *          CNAP - Calling name presentation\n
 430  *                 This function queries the service status with #TelSsCliType_t.
 431  *
 432  *          If this function is called normally, the asynchronous response comes in a few seconds from the network.
 433  *          The response indicates the service status.
 434  *
 435  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 436  *          However it just means that the API request has been transfered to the CP successfully.
 437  *          The actual operation result is delivered with the async response as below:
 438  *
 439  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 440  *
 441  * <b> Prospective Clients: </b> External Apps.
 442  *
 443  * @since_tizen 2.3
 444  * @privlevel public
 445  * @privilege %http://tizen.org/privilege/telephony
 446  *
 447  * @param[in] handle The handle from tel_init()
 448  *
 449  * @param[in] type The Cli service type
 450  *
 451  * @param[in] callback To register a callback function for result
 452  *
 453  * @param[in] user_data The user data for user specification
 454  *
 455  * @return The return type (int) \n
 456  *         #TAPI_API_SUCCESS - indicates that the operation is completed successfully. \n
 457  *         Refer #TapiResult_t for failure and error code
 458  *
 459  * @pre Initialize the Dbus connection with #tel_init.
 460  */
 461 int tel_get_ss_cli_status(TapiHandle *handle, TelSsCliType_t type, tapi_response_cb callback, void *user_data);
 462
 463 /**
 464  * @brief Sends a USSD string or User response to the Network.
 465  *
 466  * @details The unstructured supplementary service data (USSD) mechanism allows the Mobile Station (MS) user and
 467  *          a PLMN operator defined application to communicate in a way which is transparent
 468  *          to the MS and the intermediate network entities.
 469  *          The mechanism allows development of PLMN specific supplementary services.
 470  *          A USSD string is like *109, *109*72348937857623#.
 471  *          There are two modes of USSD: The MMI-mode and the application mode.
 472  *          The MMI-mode USSD is for the transparent transport of MMI strings entered by the user to the network using this function
 473  *          and for the transparent transport of text strings from the network that are displayed
 474  *          by the mobile for user information.
 475  *          The application mode USSD is for the transparent transport of data between the network and the UE.
 476  *          The application mode USSD is intended to be used by applications in the network and their peer applications in the UE.
 477  *
 478  *          If this function is called normally, the asynchronous response comes in a few seconds from the telephony server.
 479  *          The response indicates whether the sending request is successfully delivered or not.
 480  *
 481  *          This API makes a Dbus method call to the Telephony Server and gets an immediate feedback.
 482  *          However it just means that the API request has been transfered to the CP successfully.
 483  *          The actual operation result is delivered with the async response as below:
 484  *
 485  * <b> Sync (or) Async: </b> This is an Asynchronous API.
 486  *
 487  * <b> Prospective Clients: </b> External Apps.
 488  *
 489  * @since_tizen 2.3
 490  * @privlevel platform
 491  * @privilege %http://tizen.org/privilege/telephony.admin
 492  *
 493  * @param[in] handle The handle from tel_init()
 494  *
 495  * @param[in] info The data coding scheme used (GSM 7bit or 8bit default alphabet etc, defined  as 3GPP TS 23.038), USSD String data length, ANSI string passed by the client
 496  *
 497  * @param[in] callback To register a callback function for result
 498  *
 499  * @param[in] user_data The user data for user specification
 500  *
 501  * @return The return type (int) \n
 502  *         #TAPI_API_SUCCESS - indicates that the operation is completed successfully. \n
 503  *         Refer #TapiResult_t for failure and error code
 504  *
 505  * @pre Initialize the Dbus connection with #tel_init.\n
 506  *      Register the telephony event to be listend with #tel_register_noti_event.\n
 507  *      An event loop runs to listen to events.
 508  *      No SS and USSD transaction should be ongoing. If there is an ongoing transaction, a new USSD request will be returned to the application with an error (USSD_BUSY).
 509  *
 510  */
 511 int tel_send_ss_ussd_request(TapiHandle *handle, const TelSsUssdMsgInfo_t *info, tapi_response_cb callback, void *user_data);
 512
 513 #ifdef __cplusplus
 514 }
 515 #endif
 516
 517 #endif /* _ITAPI_SS_H_ */
 518
 519 /**
 520  * @}
 521  */