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