wearable/include/ITapiSs.h

   1 /*
   2  * libslp-tapi
   3  *
   4  * Copyright (c) 2011 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 * @open
  23 * @ingroup              TelephonyAPI
  24 * @addtogroup   SS_TAPI         SS(Supplementary services)
  25 * @{
  26 *
  27 * @file ITapiSs.h
  28
  29      @brief This file serves as a "C" header file defines functions for Tapi Supplementary services\n
  30       It contains a sample set of function prototypes that would be required by applications.
  31  */
  32
  33 #ifndef _ITAPI_SS_H_
  34 #define _ITAPI_SS_H_
  35
  36 #include <tapi_common.h>
  37 #include <TelSs.h>
  38 #include <TelDefines.h>
  39
  40 #ifdef __cplusplus
  41 extern "C"
  42 {
  43 #endif
  44
  45  /**
  46  * @brief  This function sends a request to activate/deactivate call barring.
  47  *
  48  *  This service makes it possible for a mobile subscriber
  49  *  to activate barring of certain categories of outgoing or incoming calls according to a barring program which is selected from a set
  50  *  of one or more barring programs chosen at provision time and is valid for all outgoing or incoming calls, or just those associated
  51  *   with a specific basic service group. Also this API allows deactivating call barring based on categories set.
  52  * If the user call this function with wrong password 3 times subsequently, the barring service can be blocked.
  53  * If this function is called normally, the asynchronous response comes in a few second from network. The response indicates
  54  * the service request has been granted or not.
  55  *
  56  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
  57  * However it just means that the API request has been transfered to the CP successfully.
  58  * The actual operation result is delivered with the async response as below.
  59  *
  60  * @par Sync (or) Async:
  61  * This is an Asynchronous API.
  62  *
  63  * @par Important Notes:
  64  * - None.
  65  *
  66  * @warning
  67  * - None.
  68  *
  69  * @param [in] handle
  70  * - handle from tel_init().
  71   *
  72  * @param [in] info
  73  *   - Contains the information about call barring
  74  *
  75  * @param [in] callback
  76  * - To register callback function for result.
  77  *
  78  * @param [in] user_data
  79  * - user_data for user specification.
  80  *
  81  * @par Async Response Message:
  82  * Asynchronous return status is indicated by #TelSsBarringResp_t.
  83  *
  84  * @pre
  85  *  - Initialize Dbus connection with #tel_init
  86  *  - Register caller's application name with #tel_register_app_name
  87  *  - Register telephony events to listen
  88  *  - A event loop is running to listen events
  89  *
  90  * @post
  91  *  - None.
  92  *
  93  * @return Return Type (int) \n
  94  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
  95  * - Refer #TapiResult_t for failure and error code
  96  *
  97  * @par Prospective Clients:
  98  * External Apps.
  99  *
 100  * \see tel_get_ss_barring_status, tel_change_ss_barring_password
 101  *
 102  * @code
 103  * #include<ITapiSS.h>
 104  *
 105  * int ret_status = -1;
 106  * TelSsCallBarringInfo_t  pBarringInfo;// = {0,};
 107  * void *user_data;
 108  * char bar_pwd[5]="0000";
 109  * TapiHandle *handle;  // Handle given by tel_init()
 110  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 111  *
 112  * pBarringInfo.Mode = TAPI_SS_CALL_BAR_ACTIVATE;
 113  * pBarringInfo.Type = TAPI_CALL_BARRING_ALL_OUTGOING_CALLS;
 114  * pBarringInfo.CallType = TAPI_CALL_TYPE_VOICE_EV;
 115  * strcpy(pBarringInfo.szPassword,bar_pwd);
 116  * ret_status = tel_set_ss_barring (handle,&pBarringInfo,callback,user_data);
 117  * @endcode
 118  *
 119  * @remarks
 120  * - None
 121  *
 122  *
 123  */
 124  /*================================================================================================*/
 125 int tel_set_ss_barring(TapiHandle *handle, TelSsBarringInfo_t *info, tapi_response_cb callback, void *user_data);
 126
 127 /**
 128  *
 129  * @brief  This function gets call barring status.
 130  *
 131  * The mobile subscriber may determine by subscription of a set of one or more unique barring
 132  * programs what kind of outgoing or incoming calls should be barred.
 133  * If this function is called normally, the asynchronous response comes in a few second from network.
 134  * The response indicates the service status.
 135  *
 136  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 137  * However it just means that the API request has been transfered to the CP successfully.
 138  * The actual operation result is delivered with the async response as below.
 139  *
 140  * @par Sync (or) Async:
 141  * This is an Asynchronous API.
 142  *
 143  * @par Important Notes:
 144  * - None.
 145  *
 146  * @warning
 147  * - None.
 148  *
 149  * @param [in] handle
 150  * - handle from tel_init().
 151  *
 152  * @param [in] ss_class
 153  *   - Specifies the type of call i.e. Voice call, Video Call etc.
 154  *
 155  * @param [in] type
 156  *   - Specifies barring type i.e. Outgoing international, outgoing all, Incoming all etc.
 157  *
 158  * @param [in] callback
 159  * - To register callback function for result.
 160  *
 161  * @param [in] user_data
 162  * - user_data for user specification.
 163  *
 164  * @par Async Response Message:
 165  *  Asynchronous return status is indicated by #TelSsBarringResp_t.
 166  *
 167  * @pre
 168  *  - Initialize Dbus connection with #tel_init
 169  *  - Register caller's application name with #tel_register_app_name
 170  *  - Register telephony events to listen
 171  *  - A event loop is running to listen events
 172  *
 173  * @post
 174  *  - None.
 175  *
 176  * @return Return Type (#TapiResult_t) \n
 177  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 178  * - Refer #TapiResult_t for failure and error code
 179  *
 180  * @par Prospective Clients:
 181  * External Apps.
 182  *
 183  * \see tel_set_ss_barring, tel_change_ss_barring_password
 184  *
 185  * @code
 186  * #include<ITapiSS.h>
 187  *
 188  * int ret_status;
 189  * TelSsCallBarType_t BarType =TAPI_CALL_BARRING_ALL_OUTGOING_INTERN_CALL;
 190  * TelSsCallType_t CallType = TAPI_CALL_TYPE_VOICE_EV;
 191  * void *user_data;
 192  * TapiHandle *handle;  // Handle given by tel_init()
 193  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 194  *
 195  * ret_status = tel_get_ss_barring_status(handle,CallType,BarType,callback,user_data); // get barring status
 196  * printf ("The return value is %d\n", ret_status);
 197  *
 198  * @endcode
 199  *
 200  *
 201  * @remarks
 202  * - None
 203  *
 204  *
 205  */
 206 /*================================================================================================*/
 207 int tel_get_ss_barring_status(TapiHandle *handle, TelSsClass_t ss_class, TelSsBarringType_t type, tapi_response_cb callback, void *user_data);
 208
 209  /**
 210  *
 211  * @brief  This function allows changing of the barring password in Network.
 212  *
 213  * User can request network to change his own barring password. If the old password is not same with
 214  * what network knows, it will be rejected by network. Also new password should be same with another new password
 215  * which is to confirm user input. Otherwise the request must be rejected by Telephony Sever.
 216  * If the user call this function with wrong old password 3 times subsequently, the barring service can be blocked.
 217  * If this function is called normally, the asynchronous response comes in a few second from network.
 218  * The response indicates the service request has been granted or not.
 219  *
 220  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 221  * However it just means that the API request has been transfered to the CP successfully.
 222  * The actual operation result is delivered with the async response as below.
 223  *
 224  *
 225  * @par Sync (or) Async:
 226  * This is an Asynchronous API.
 227  *
 228  * @par Important Notes:
 229  * - Based on 3GPP TS 22.030 section 6.5.4 Registration of New Password. Only one Change Barring Password request is allowed
 230  *   at a time and TS might return TAPI_API_REQUEST_MAX_IN_PROGRESS if another request is received.
 231  *
 232  * @warning
 233  * - None.
 234  *
 235  * @param [in] handle
 236  * - handle from tel_init().
 237  *
 238  * @param [in] old_password
 239  *   - Old password set for Barring in Network. This is Null terminated string
 240  *
 241  * @param [in] new_password
 242  *   - New password for Barring to be set in Network. This is Null terminated string.
 243  *
 244  * @param [in] new_password_again
 245  *   - New password again. This is Null terminated string.
 246  *
 247  * @param [in] callback
 248  * - To register callback function for result.
 249  *
 250  * @param [in] user_data
 251  * - user_data for user specification.
 252  *
 253  * @par Async Response Message:
 254  * Asynchronous return status will be succes or failure.
 255  *
 256  * @pre
 257  *  - Initialize Dbus connection with #tel_init
 258  *  - Register caller's application name with #tel_register_app_name
 259  *  - Register telephony events to listen
 260  *  - A event loop is running to listen events
 261  *
 262  * @post
 263  *  - None.
 264  *
 265  * @return Return Type (int) \n
 266  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 267  * - Refer #TapiResult_t for failure and error code
 268  * @par Prospective Clients:
 269  * External Apps.
 270  *
 271  * @see
 272  * - None
 273  *
 274  * @code
 275  * #include<ITapiSS.h>
 276  *
 277  * int ret_status;
 278  * void *user_data;
 279  * TapiHandle *handle;  // Handle given by tel_init()
 280  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 281  *
 282  * ret_status = tel_change_ss_barring_password (handle,"0000","1111","1111",callback,user_data); // change barring password
 283  *
 284  * @endcode
 285  *
 286  * @remarks
 287  * - None
 288  *
 289  *
 290  */
 291 /*================================================================================================*/
 292 int tel_change_ss_barring_password(TapiHandle *handle,
 293                 const char *old_password,
 294                 const char *new_password,
 295                 const char *new_password_again,
 296                 tapi_response_cb callback, void *user_data);
 297
 298  /**
 299  *
 300  * @brief  This function allows to set (register/erase/activate/deactivate) call forwarding option at the Network.
 301  *
 302  * This enables to forward the calls to another party. This service permits a called mobile subscriber
 303  * to have the network send all incoming calls, or just those associated with a specific Basic service group,
 304  * addressed to the called mobile subscriber's directory number and which meet
 305  * various call FORWARD condition to another directory number.
 306  * The ability of the served mobile subscriber to originate calls is unaffected.
 307  * If the service is activated, a call is forwarded only if under this call forward condition.
 308  * Application has to call this API in order to explicitly register/erase/activate/deactivate
 309  * the call forwarding. Request will be passed irrespective of whether already
 310  * another SS call forward is ongoing.
 311  *
 312  * If this function is called normally, the asynchronous response comes in a few second from network. The response indicates
 313  * the service request has been granted or not.
 314  *
 315  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 316  * However it just means that the API request has been transfered to the CP successfully.
 317  * The actual operation result is delivered with the async response as below.
 318  *
 319  *
 320  * @par Sync (or) Async:
 321  * This is an Asynchronous API.
 322  *
 323  * @par Important Notes:
 324  * - None.
 325  *
 326  * @warning
 327  * - None.
 328  *
 329  * @param [in] handle
 330  * - handle from tel_init().
 331  *
 332  * @param [in] info
 333  *   - Contains the Call forward information like forward mode, forward type, etc.
 334  *
 335  * @param [in] callback
 336  * - To register callback function for result.
 337  *
 338  * @param [in] user_data
 339  * - user_data for user specification.
 340  *
 341  * @par Async Response Message:
 342  *  Asynchronous return status is indicated by #TelSsForwardResp_t.
 343  *
 344  * @pre
 345  *  - Initialize Dbus connection with #tel_init
 346  *  - Register caller's application name with #tel_register_app_name
 347  *  - Register telephony events to listen
 348  *  - A event loop is running to listen events
 349  *
 350  * @post
 351  *  - None.
 352  *
 353  * @return Return Type (int) \n
 354  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 355  * - Refer #TapiResult_t for failure and error code
 356  * @par Prospective Clients:
 357  * External Apps.
 358  *
 359  *
 360  * \image html CallForward.jpg
 361  * \image latex CallForward.jpg
 362  *
 363  * \see tel_get_ss_forward_status
 364  *
 365  * @code
 366  * #include<ITapiSS.h>
 367  *
 368  * int ret_status =0;
 369  * void *user_data;
 370  * TelSsForwardInfo_t pForwardInfo;
 371  * pForwardInfo.Mode =TAPI_CALL_FORWARD_MODE_ENABLE_EV;
 372  * pForwardInfo.Type = TAPI_CS_FORWARD_TYPE_VOICE_EV;
 373  * pForwardInfo.Condition = TAPI_SS_FORWARD_WHEN_UNCONDITIONAL_EV;
 374  * pForwardInfo.NoReplyConditionTimer = 10;
 375  * int len;
 376  * char cf_number[20]= {"9986529874"};//number to which calles need to be forwarded.
 377  * TapiHandle *handle;  // Handle given by tel_init()
 378  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 379  *
 380  * len = strlen(cf_number);
 381  * printf("Length of CF number :%d \n",len);
 382  * memcpy(&(pForwardInfo.szPhoneNumber),cf_number,len);
 383  *
 384  * ret_status = tel_set_ss_forward (handle,&pForwardInfo,callback,user_data);
 385  *
 386  * @endcode
 387  * @remarks
 388  * - None
 389  *
 390  *
 391  */
 392 /*================================================================================================*/
 393 int tel_set_ss_forward(TapiHandle *handle, const TelSsForwardInfo_t *info, tapi_response_cb callback, void *user_data);
 394
 395  /**
 396  *
 397  * @brief  This function provides option to get the call forwarding status of different calls from Network.
 398  *
 399  * The data request procedure enables the mobile subscriber to obtain information about the data stored in the PLMN.
 400  * After having requested this procedure the network shall return the following information:
 401  * -    in response to a general data request the served mobile subscriber should be given a list of all Basic service groups
 402  *      to which call forwarding unconditional is registered, including information whether or not it is active and operative,
 403  *      and the associated forwarded-to numbers
 404  * -    in response to a specific request concerning one particular Basic service group,
 405  *      the served mobile subscriber should be informed whether or not call forwarding unconditional is registered,
 406  *      including information whether or not it is active and operative for that Basic service group.
 407  *      If CFU is registered, the associated forwarded-to number shall be given.
 408  *
 409  * If this function is called normally, the asynchronous response comes in a few second from network.
 410  * The response indicates the service status.
 411  *
 412  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 413  * However it just means that the API request has been transfered to the CP successfully.
 414  * The actual operation result is delivered with the async response as below.
 415  *
 416  *
 417  * @par Sync (or) Async:
 418  * This is an Asynchronous API.
 419  *
 420  * @par Important Notes:
 421  * - None.
 422  *
 423  * @warning
 424  * - None.
 425  *
 426  * @param [in] handle
 427  * - handle from tel_init().
 428  *
 429  * @param [in] ss_class
 430  *   - Specifying the Forward call type i.e. voice call, Video Call, Data Calls etc.
 431  *
 432  * @param [in] condition
 433  *   - Used to specify the forward condition i.e. unconditional, When no reply, when busy, when not reachable etc.
 434  *
 435  * @param [in] callback
 436  * - To register callback function for result.
 437  *
 438  * @param [in] user_data
 439  * - user_data for user specification.
 440  *
 441  * @par Async Response Message:
 442  *  Asynchronous return status is indicated by #TelSsForwardResp_t.
 443  *
 444  * @pre
 445  *  - Initialize Dbus connection with #tel_init
 446  *  - Register caller's application name with #tel_register_app_name
 447  *  - Register telephony events to listen
 448  *  - A event loop is running to listen events
 449  *
 450  * @post
 451  *  - None.
 452  *
 453  * @return Return Type (int) \n
 454  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 455  * - Refer #TapiResult_t for failure and error code
 456  *
 457  * @par Prospective Clients:
 458  * External Apps.
 459  *
 460  * \see tel_set_ss_forward
 461  *
 462  * @code
 463  * #include<ITapiSS.h>
 464  * int  ret_status = 0;
 465  * TelSsForwardType_t type =TAPI_CS_FORWARD_TYPE_VOICE_EV;
 466  * TelSsForwardWhen_t  condition = TAPI_SS_FORWARD_WHEN_UNCONDITIONAL_EV;
 467  * void *user_data;
 468  * TapiHandle *handle;  // Handle given by tel_init()
 469  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 470  *
 471  * ret_status = tel_get_ss_forward_status(handle,type,condition,callback,user_data); // get forward status
 472  *
 473  * @endcode
 474  * @remarks
 475  * - None
 476  *
 477  *
 478  */
 479 /*================================================================================================*/
 480 int tel_get_ss_forward_status(TapiHandle *handle, TelSsClass_t ss_class, TelSsForwardWhen_t condition, tapi_response_cb callback, void *user_data);
 481
 482  /**
 483  *
 484  * @brief  This function activates/deactivates the call waiting service.
 485  * The call waiting service permits a mobile to be notified of an incoming
 486  * call (as per basic call procedures) while the traffic channel (BM or LM) is not available for the incoming call and the mobile subscriber
 487  * is engaged in an active or held call. Subsequently, the subscriber can accept, reject, or ignore the incoming call.
 488  * If this function is called normally, the asynchronous response comes in a few second from network. The response indicates
 489  * the service request has been granted or not.
 490  *
 491  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 492  * However it just means that the API request has been transfered to the CP successfully.
 493  * The actual operation result is delivered with the async response as below.
 494  *
 495  *
 496  * @par Sync (or) Async:
 497  * This is an Asynchronous API.
 498  *
 499  * @par Important Notes:
 500  * - None.
 501  *
 502  * @warning
 503  * - None.
 504  *
 505  *
 506  * @param [in] handle
 507  * - handle from tel_init().
 508  *
 509  * @param [in] info
 510  *   - Specifies the status of call-waiting service i.e. On (TRUE) or off (FALSE)
 511  *
 512  * @param [in] callback
 513  * - To register callback function for result.
 514  *
 515  * @param [in] user_data
 516  * - user_data for user specification.
 517  *
 518  * @par Async Response Message:
 519  *  Asynchronous return status is indicated by #TelSsWaitingResp_t.
 520  *
 521  * @pre
 522  *  - Initialize Dbus connection with #tel_init
 523  *  - Register caller's application name with #tel_register_app_name
 524  *  - Register telephony events to listen
 525  *  - A event loop is running to listen events
 526  *
 527  * @post
 528  *  - None.
 529  *
 530  * @return Return Type (int) \n
 531  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 532  * - Refer #TapiResult_t for failure and error code
 533  *
 534  * @par Prospective Clients:
 535  * External Apps.
 536  *
 537  * \see tel_get_ss_waiting_status
 538  *
 539  * @code
 540  * #include<ITapiSS.h>
 541  *
 542  * int   ret_status;
 543  * TelSsWaitingInfo_t waitInfo;
 544  * waitInfo.Mode = TAPI_SS_CW_ACTIVATE;
 545  * waitInfo.CallType =TAPI_CALL_TYPE_VOICE_EV;
 546  * void *user_data;
 547  * TapiHandle *handle;  // Handle given by tel_init()
 548  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 549  *
 550  * ret_status = tel_set_ss_waiting (handle,&waitInfo,callback,user_data); // set call waiting
 551  * @endcode
 552  *
 553  * @remarks
 554  * - None
 555  *
 556  *
 557  */
 558 /*================================================================================================*/
 559 int tel_set_ss_waiting(TapiHandle *handle, const TelSsWaitingInfo_t *info, tapi_response_cb callback, void *user_data);
 560
 561  /**
 562  *
 563  * @brief  This function queries the status of call waiting service.
 564  *
 565  * @par Notes:
 566  * The call waiting service permits a mobile to be notified of an incoming call
 567  * (as per basic call procedures) while the traffic channel (BM or LM) is not available for the incoming call and the mobile subscriber
 568  * is engaged in an active or held call. Subsequently, the subscriber can accept, reject, or ignore the incoming call.
 569  * If this function is called normally, the asynchronous response comes in a few second from network.
 570  * The response indicates the service status.
 571  *
 572  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 573  * However it just means that the API request has been transfered to the CP successfully.
 574  * The actual operation result is delivered with the async response as below.
 575  *
 576  *
 577  * @par Sync (or) Async:
 578  * This is an Asynchronous API.
 579  *
 580  * @par Important Notes:
 581  * - None.
 582  *
 583  * @warning
 584  * - None.
 585  *
 586  *
 587  * @param [in] handle
 588  * - handle from tel_init().
 589  *
 590  * @param [in] ss_class
 591  *   - enum data defines call type
 592  *
 593  * @param [in] callback
 594  * - To register callback function for result.
 595  *
 596  * @param [in] user_data
 597  * - user_data for user specification.
 598  *
 599  * @par Async Response Message:
 600  *  Asynchronous return status is indicated by #TelSsWaitingResp_t.
 601  *
 602  * @pre
 603  *  - Initialize Dbus connection with #tel_init
 604  *  - Register caller's application name with #tel_register_app_name
 605  *  - Register telephony events to listen
 606  *  - A event loop is running to listen events
 607  *
 608  * @post
 609  *  - None.
 610  *
 611  * @return Return Type (int) \n
 612  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 613  * - Refer #TapiResult_t for failure and error code
 614  * @par Prospective Clients:
 615  * External Apps.
 616  *
 617  * \see tel_set_ss_waiting
 618  * @code
 619  * #include<ITapiSS.h>
 620  *
 621  * int   ret_status;
 622  * TelSsCallType_t CallType = TAPI_CALL_TYPE_VOICE_EV;
 623  * void *user_data;
 624  * TapiHandle *handle;  // Handle given by tel_init()
 625  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 626  *
 627  * ret_status = tel_get_ss_waiting_status (handle,CallType,callback,user_data); // get call waiting info
 628  * @endcode
 629  *
 630  * @remarks
 631  * - None
 632  *
 633  *
 634  */
 635 /*================================================================================================*/
 636 int tel_get_ss_waiting_status(TapiHandle *handle, const TelSsClass_t ss_class, tapi_response_cb callback, void *user_data);
 637
 638 /**
 639  *
 640  * @brief  This function activates/deactivates the status of calling line identity service.
 641  *
 642  * @par Notes:
 643  * The group of Line Identification Supplementary Services is divided into the following six Supplementary Services:
 644  * CLIP - Calling line identification presentation
 645  *        This Supplementary Service provides for the ability to indicate the line identity of the calling party to the called party.
 646  *        The network shall deliver the calling line identity to the called party at call set-up time,
 647  *        regardless of the terminal capability to handle the information.
 648  * CLIR - Calling line identification restriction
 649  *        the CLIR Supplementary Service is a Supplementary Service offered to the calling party
 650  *        to prevent presentation of the calling party's line identity, to the called party.
 651  * COLP - Connected line identification presentation
 652  *        This Supplementary Service is not a dialing check but an indication to the calling subscriber
 653  *        of the connected line identity in a full ISDN/PLMN environment,
 654  *        the connected line identity shall include all the information necessary to unambiguously identify the connected party.
 655  *        The network shall deliver the connected line identity to the calling party
 656  *        regardless of the terminal capability to handle the information.
 657  * COLR - Connected line identification restriction
 658  *        The COLR Supplementary Service is a Supplementary Service offered
 659  *        to the connected party to prevent presentation of the connected line identity, to the calling party.
 660  *        In the case where the calling party has an override category.
 661  * CDIP - Called line identification presentation
 662  * CNAP - Calling name presentation
 663  * This function queries the service status with #TelSsCliType_t
 664  *
 665  * If this function is called normally, the asynchronous response comes in a few second from network.
 666  * The response indicates the service status.
 667  *
 668  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 669  * However it just means that the API request has been transfered to the CP successfully.
 670  * The actual operation result is delivered with the async response as below.
 671  *
 672  *
 673  * @par Sync (or) Async:
 674  * This is an Asynchronous API.
 675  *
 676  * @par Important Notes:
 677  * - None.
 678  *
 679  * @warning
 680  * - None.
 681  *
 682  * @param [in] handle
 683  * - handle from tel_init().
 684  *
 685  * @param [in] type
 686  *   - enum data defines Cli service type
 687  *
 688  * @param [in] status
 689  *   - enum data defines Cli Status
 690  *
 691  * @param [in] callback
 692  * - To register callback function for result.
 693  *
 694  * @param [in] user_data
 695  * - user_data for user specification.
 696  *
 697  * @par Async Response Message:
 698  *  Asynchronous return status is indicated by #TelSsCliResp_t.
 699  *
 700  * @pre
 701  *  - Initialize Dbus connection with #tel_init
 702  *  - Register caller's application name with #tel_register_app_name
 703  *  - Register telephony events to listen
 704  *  - A event loop is running to listen events
 705  *
 706  * @post
 707  *  - None.
 708  *
 709  * @return Return Type (int) \n
 710  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 711  * - Refer #TapiResult_t for failure and error code
 712  *
 713  * @par Prospective Clients:
 714  * External Apps.
 715  *
 716  * @code
 717  * #include<ITapiSS.h>
 718  *
 719  * int  ret_status = 0;
 720  * TelSsCliType_t CliType =TAPI_SS_CLI_CDIP;
 721  * void *user_data;
 722  * TapiHandle *handle;  // Handle given by tel_init()
 723  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 724  *
 725  * ret_status = tel_set_ss_cli_status(handle,CliType,CliStatus,callback,user_data); // get cli info
 726  * @endcode
 727  *
 728  * @see
 729  * - None
 730  *
 731  * @remarks
 732  * - None
 733  *
 734  *
 735  */
 736 /*================================================================================================*/
 737 int tel_set_ss_cli_status(TapiHandle *handle, TelSsCliType_t type, TelSsCliStatus_t status, tapi_response_cb callback, void *user_data);
 738
 739 /**
 740  *
 741  * @brief  This function queries the status of calling line identity service.
 742  *
 743  * @par Notes:
 744  * The group of Line Identification Supplementary Services is divided into the following six Supplementary Services:
 745  * CLIP - Calling line identification presentation
 746  *        This Supplementary Service provides for the ability to indicate the line identity of the calling party to the called party.
 747  *        The network shall deliver the calling line identity to the called party at call set-up time,
 748  *        regardless of the terminal capability to handle the information.
 749  * CLIR - Calling line identification restriction
 750  *        the CLIR Supplementary Service is a Supplementary Service offered to the calling party
 751  *        to prevent presentation of the calling party's line identity, to the called party.
 752  * COLP - Connected line identification presentation
 753  *        This Supplementary Service is not a dialing check but an indication to the calling subscriber
 754  *        of the connected line identity in a full ISDN/PLMN environment,
 755  *        the connected line identity shall include all the information necessary to unambiguously identify the connected party.
 756  *        The network shall deliver the connected line identity to the calling party
 757  *        regardless of the terminal capability to handle the information.
 758  * COLR - Connected line identification restriction
 759  *        The COLR Supplementary Service is a Supplementary Service offered
 760  *        to the connected party to prevent presentation of the connected line identity, to the calling party.
 761  *        In the case where the calling party has an override category.
 762  * CDIP - Called line identification presentation
 763  * CNAP - Calling name presentation
 764  * This function queries the service status with #TelSsCliType_t
 765  *
 766  * If this function is called normally, the asynchronous response comes in a few second from network.
 767  * The response indicates the service status.
 768  *
 769  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 770  * However it just means that the API request has been transfered to the CP successfully.
 771  * The actual operation result is delivered with the async response as below.
 772  *
 773  *
 774  * @par Sync (or) Async:
 775  * This is an Asynchronous API.
 776  *
 777  * @par Important Notes:
 778  * - None.
 779  *
 780  * @warning
 781  * - None.
 782  *
 783  * @param [in] handle
 784  * - handle from tel_init().
 785  *
 786  * @param [in] type
 787  *   - enum data defines Cli service type
 788  *
 789  * @param [in] callback
 790  * - To register callback function for result.
 791  *
 792  * @param [in] user_data
 793  * - user_data for user specification.
 794  *
 795  * @par Async Response Message:
 796  *  Asynchronous return status is indicated by #TelSsCliResp_t.
 797  *
 798  * @pre
 799  *  - Initialize Dbus connection with #tel_init
 800  *  - Register caller's application name with #tel_register_app_name
 801  *  - Register telephony events to listen
 802  *  - A event loop is running to listen events
 803  *
 804  * @post
 805  *  - None.
 806  *
 807  * @return Return Type (int) \n
 808  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 809  * - Refer #TapiResult_t for failure and error code
 810  *
 811  * @par Prospective Clients:
 812  * External Apps.
 813  *
 814  * @code
 815  * #include<ITapiSS.h>
 816  *
 817  * int  ret_status = 0;
 818  * TelSsCliType_t CliType =TAPI_SS_CLI_CDIP;
 819  * void *user_data;
 820  * TapiHandle *handle;  // Handle given by tel_init()
 821  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 822  *
 823  * ret_status = tel_get_ss_cli_status(handle,CliType,callback,user_data); // get cli info
 824  * @endcode
 825  *
 826  * @see
 827  * - None
 828  *
 829  * @remarks
 830  * - None
 831  *
 832  *
 833  */
 834 /*================================================================================================*/
 835 int tel_get_ss_cli_status(TapiHandle *handle, TelSsCliType_t type, tapi_response_cb callback, void *user_data);
 836
 837  /**
 838  *
 839  * @brief  This function is used to send a USSD string or User response to the Network.
 840  *
 841  * The unstructured supplementary service data (USSD) mechanism allows the Mobile Station (MS) user and
 842  * a PLMN operator defined application to communicate in a way which is transparent
 843  * to the MS and to intermediate network entities.
 844  * The mechanism allows development of PLMN specific supplementary services.
 845  * USSD string is like *109, *109*72348937857623#.
 846  * There are two modes of USSD: MMI-mode and application mode.
 847  * MMI-mode USSD is for the transparent transport of MMI strings entered by the user to the network using this function
 848  * and for the transparent transport of text strings from the network that are displayed
 849  * by the mobile for user information.
 850  * Application mode USSD is for the transparent transport of data between the network and the UE.
 851  * Application mode USSD is intended to be used by applications in the network and their peer applications in the UE.
 852  * The peer application in the UE send response with #tel_send_ss_ussd_response
 853  *
 854  * If this function is called normally, the asynchronous response comes in a few second from the telephony server.
 855  * The response indicates whether the sending request is successfully delivered or not.
 856  *
 857  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 858  * However it just means that the API request has been transfered to the CP successfully.
 859  * The actual operation result is delivered with the async response as below.
 860  * @par Sync (or) Async:
 861  * This is an Asynchronous API.
 862  *
 863  * @par Important Notes:
 864  * - None.
 865  *
 866  * @warning
 867  * - None.
 868  *
 869  * @param [in] handle
 870  * - handle from tel_init().
 871  *
 872  * @param [in] info
 873  *   - Data coding scheme used (GSM 7bit or 8bit default alphabet etc, defined  as 3GPP TS 23.038)
 874  *   - USSD String data length
 875  *   - ANSI string passed by the client
 876  *
 877  * @param [in] callback
 878  * - To register callback function for result.
 879  *
 880  * @param [in] user_data
 881  * - user_data for user specification.
 882  *
 883  * @par Async Response Message:
 884  *  Asynchronous return status is indicated by #TelSsUssdResp_t.
 885  *
 886  * @pre
 887  *  - Initialize Dbus connection with #tel_init
 888  *  - Register caller's application name with #tel_register_app_name
 889  *  - Register telephony events to listen
 890  *  - A event loop is running to listen events
 891  *  - No SS and USSD Transaction should be ongoing. If there an ongoing transaction, new USSD request will be returned to the Application
 892  *   with an error (USSD_BUSY)
 893  *
 894  * @post
 895  *  - None.
 896  *
 897  * @return Return Type (int) \n
 898  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 899  * - Refer #TapiResult_t for failure and error code
 900  *
 901  * @par Prospective Clients:
 902  * External Apps.
 903  *
 904  * \see #tel_send_ss_ussd_response, #tel_send_ss_ussd_cancel
 905  *
 906  *\image html ussd.jpg
 907  *\image latex ussd.jpg
 908  *
 909  * @code
 910  * #include<ITapiSS.h>
 911  *
 912  * char ussdString[TAPI_SS_USSD_DATA_SIZE_MAX];
 913  * int  ret;
 914  * TapiHandle *handle;  // Handle given by tel_init()
 915  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 916  * void *user_data;
 917  *
 918  * memset(ussdString, 0, TAPI_SS_USSD_DATA_SIZE_MAX);
 919  * strcpy(ussdString , "*124#");
 920  *
 921  * ret = tel_send_ss_ussd_request(handle,ussdString,callback,user_data); // request ussd
 922  * @endcode
 923  *
 924  * @remarks
 925  * - None
 926  *
 927  *
 928  */
 929 /*================================================================================================*/
 930 int tel_send_ss_ussd_request(TapiHandle *handle, const TelSsUssdMsgInfo_t *info, tapi_response_cb callback, void *user_data);
 931
 932  /**
 933  *
 934  * @brief  This function is used to Read AOC parameter values on the SIM.
 935  *
 936  * @par Notes
 937  * This supplementary service provides the MS with the information to produce an estimate
 938  * of the cost of the service used. Charges are indicated for the call(s) in progress
 939  * when mobile originated or for the roaming leg only when mobile terminated.
 940  * Any charges for non-call related transactions, and for certain supplementary services,
 941  * such as Call Forwarding are not indicated.
 942  * The MS will receive at the beginning of each call (and as necessary during the call)
 943  * a message, the Charge Advice Information. This message contains the elements which together define
 944  * the rate at which the call is to be charged, time dependence,
 945  * data dependence and for unit increments - see TS 22.024 [3].
 946  * The MS shall still indicate appropriate charges even when roaming, based on Home PLMN units.
 947  * Where applicable, the volume charge for Packet data service,
 948  * in addition to the normal time dependent and incremental charges, shall be indicated.
 949  * To indicate the charge per call the Mobile station shall display the units consumed
 950  * so far during the present call(s) and maintain this value until the MS is switched off or a new call set-up is attempted.
 951  * Where required to indicate the total accumulated charge, the MS shall be able to display,
 952  * and the SIM/USIM shall store in the ACM, the running cumulative unit charge.
 953  * This value must be stored securely, and all reasonable steps shall be taken to ensure that
 954  * the written value cannot be interrupted, reset or corrupted (except resetting under control of the unblocking key).
 955  * This function get the AOC configuration information from PLMN
 956  *
 957  * If this function is called normally, the asynchronous response comes in a few second from Telephony Server.
 958  * The response indicates whether the query is delivered successfully to network or not.
 959  *
 960  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
 961  * However it just means that the API request has been transfered to the CP successfully.
 962  * The actual operation result is being delivered asynchronously.
 963  *
 964  * @par Sync (or) Async:
 965  * This is an Asynchronous API.
 966  *
 967  * @par Important Notes:
 968  * - None.
 969  *
 970  * @warning
 971  * - None.
 972  *
 973  *
 974  * @param [in] handle
 975  * - handle from tel_init().
 976  *
 977  * @param [in] AocType
 978  *   - Specifies which type of Advice of charge information to be read namely Maximum ACM,
 979  *     Price per unit currency, Current call meter and Accumulated call meter values.
 980  *
 981  * @param [in] callback
 982  * - To register callback function for result.
 983  *
 984  * @param [in] user_data
 985  * - user_data for user specification.
 986  *
 987  * @par Async Response Message:
 988  *  None
 989  *
 990  * @pre
 991  *  - Advice of charge depends on the SIM for setting or reading AOC parameters.
 992  *  - Setting of AOC needs PIN2 Verification
 993  *
 994  * @post
 995  *  - None.
 996  *
 997  * @return Return Type (int) \n
 998  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
 999  * - Refer #TapiResult_t for failure and error code
1000  *
1001  * @par Prospective Clients:
1002  * External Apps.
1003  *
1004  * \see tel_set_ss_aoc_info
1005  *
1006  *\image html ussd.jpg
1007  *\image latex ussd.jpg
1008  * @code
1009  * #include<ITapiSS.h>
1010  *
1011  * TelSsAocType_t AocType = TAPI_SS_AOC_TYPE_ACM;
1012  * TapiHandle *handle;  // Handle given by tel_init()
1013  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1014  * void *user_data;
1015  *
1016  * ret_status = tel_get_ss_aoc_info (handle,AocType,callback,user_data); // get AOC info
1017  * @endcode
1018  *
1019  * @remarks
1020  * - None
1021  *
1022  *
1023  */
1024 /*================================================================================================*/
1025 int tel_get_ss_aoc_info(TapiHandle *handle, TelSsAocType_t AocType, tapi_response_cb callback, void *user_data);
1026
1027  /**
1028  *
1029  * @brief  This function is used to Read AOC parameter values on the SIM.
1030  *
1031  * @par Notes:
1032  * Refer #tel_get_ss_aoc_info
1033  *
1034  * If this function is called normally, the asynchronous response comes in a few second from Telephony Server.
1035  * The response indicates whether the query is delivered successfully to network or not.
1036  *
1037  * This API makes Dbus method call to Telephony Sever and gets immediate feedback.
1038  * However it just means that the API request has been transfered to the CP successfully.
1039  * The actual operation result is being delivered asynchronously.
1040  *
1041  * @par Sync (or) Async:
1042  * This is an Asynchronous API.
1043  *
1044  * @par Important Notes:
1045  * - None.
1046  *
1047  * @warning
1048  * - None.
1049  *
1050  *
1051  * @param [in] handle
1052  * - handle from tel_init().
1053  *
1054  * @param [in] AocSetInfo
1055  *   - Specifies which type of Advice of charge information to be set namely Maximum ACM,
1056  *     Price per unit currency, Current call meter and Accumulated call meter values.
1057  *
1058  * @param [in] callback
1059  * - To register callback function for result.
1060  *
1061  * @param [in] user_data
1062  * - user_data for user specification.
1063  *
1064  * @par Async Response Message:
1065  *  None
1066  *
1067  * @pre
1068  *  - Advice of charge depends on the SIM for setting or reading AOC parameters.
1069  *  - Setting of AOC needs PIN2 Verification
1070  *
1071  * @post
1072  *  - None.
1073  *
1074  * @return Return Type (int) \n
1075  * - TAPI_API_SUCCESS - indicating that the operation has completed successfully. \n
1076  * - Refer #TapiResult_t for failure and error code
1077  *
1078  * @par Prospective Clients:
1079  * External Apps.
1080  *
1081  * \see tel_get_ss_aoc_info
1082  *
1083  *\image html ussd.jpg
1084  *\image latex ussd.jpg
1085  * @code
1086  * #include<ITapiSS.h>
1087  *
1088  * TelCallAocInfo_t  *pAocSetInfo;
1089  * void *user_data;
1090  * pAocSetInfo = (TelCallAocInfo_t *)calloc(1,sizeof(TelCallAocInfo_t));
1091  * pAocSetInfo->AocType = TAPI_SS_AOC_TYPE_RESET;
1092  * int ret_status =0;
1093  * TapiHandle *handle;  // Handle given by tel_init()
1094  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1095  *
1096  * ret = tel_set_ss_aoc_info (handle,pAocSetInfo,callback,user_data); // set aoc info
1097  * @endcode
1098  *
1099  *
1100  * @remarks
1101  * - None
1102  *
1103  *
1104  */
1105 /*================================================================================================*/
1106 int tel_set_ss_aoc_info(TapiHandle *handle, TelCallAocInfo_t *AocSetInfo, tapi_response_cb callback, void *user_data);
1107
1108 #ifdef __cplusplus
1109 }
1110 #endif
1111
1112 #endif /* _ITAPI_SS_H_ */
1113
1114 /**
1115 * @}
1116 */