include/tapi/ITapiSs.h

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