wearable/include/ITapiSim.h

   1 /*
   2  * libslp-tapi
   3  *
   4  * Copyright (c) 2012 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  SIM_TAPI        SIM
  25  * @{
  26  *
  27  * @file ITapiSim.h
  28  *
  29  * @brief This file serves as a "C" header file defines functions for Tapi SIM Services.
  30  * It contains a sample set of function prototypes that would be required by applications.
  31  */
  32
  33 #ifndef _ITAPI_SIM_H_
  34 #define _ITAPI_SIM_H_
  35
  36 #include <tapi_common.h>
  37 #include <TelErr.h>
  38 #include <TelSim.h>
  39 #include <TelDefines.h>
  40
  41 #ifdef __cplusplus
  42 extern "C"
  43 {
  44 #endif
  45
  46 /*
  47  * @brief  This API is used to get SIM Card Initialization status and SIM Card Identification.
  48  * Most of modules which require SIM data should check SIM status before using it definitely.
  49  *
  50  * @par Sync (or) Async:
  51  * This is a Synchronous API.
  52  *
  53  * @par Important Notes:
  54  * - Card Identification value is available in TAPI_SIM_STATUS_SIM_INIT_COMPLETED case only.
  55  *
  56  * @warning
  57  * - None.
  58  *
  59  * @param [in] handle
  60  * - handle from tel_init().
  61  *
  62  * @param [out] sim_status
  63  * - This parameter returns SIM initialization status from Telephony server boot up time.
  64  * First, You can find sim existance if returned value are not in TAPI_SIM_STATUS_CARD_NOT_PRESENT and TAPI_SIM_STATUS_CARD_REMOVED.
  65  *
  66  * @param [out] card_changed
  67  * - This parameter returns sim card identification value when sim_status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED.
  68  * - card_changed value just present whether current inserted SIM card differs with previous SIM or not.
  69  *
  70  * @par Async Response Message:
  71  * - None
  72  *
  73  * @pre
  74  * - None.
  75  *
  76  * @post
  77  * - None.
  78  *
  79  * @return Return Type (int)
  80  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
  81  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
  82  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
  83  *
  84  * @par Prospective Clients:
  85  * External Apps.
  86  *
  87  * @see None
  88  *
  89  * @code
  90  * #include <ITapiSim.h>
  91  *
  92  * int err_code = TAPI_API_SUCCESS;
  93  * TelSimCardStatus_t status = 0x00;
  94  * int b_card_changed = 0;
  95  * TapiHandle *handle;  // Handle given by tel_init()
  96  *
  97  * // GET SIM INIT INFORMATION
  98  * err_code = tel_get_sim_init_info(handle, &status, &b_card_changed);
  99  *
 100  * @endcode
 101  *
 102  * @remarks None
 103  *
 104  */
 105 /*================================================================================================*/
 106 int tel_get_sim_init_info(TapiHandle *handle, TelSimCardStatus_t *sim_status, int *card_changed);
 107
 108 /**
 109  * @brief  This API is used to get the Card Type whether Card is a SIM or a USIM.
 110  *
 111  * @par Sync (or) Async:
 112  * This is a Synchronous API.
 113  *
 114  * @par Important Notes:
 115  * - None
 116  *
 117  * @warning
 118  * - None.
 119  *
 120  * @param [in] handle
 121  * - handle from tel_init().
 122  *
 123  * @param [out] card_type
 124  * This parameter returns the SIM card type information like whether it is GSM SIM card or USIM or it is of unknown type.
 125  *
 126  * - TAPI_SIM_CARD_TYPE_UNKNOWN
 127  * - TAPI_SIM_CARD_TYPE_GSM
 128  * - TAPI_SIM_CARD_TYPE_USIM
 129  *
 130  * @par Async Response Message:
 131  * - None
 132  *
 133  * @pre
 134  *  - None.
 135  *
 136  * @post
 137  *  - None.
 138  *
 139  * @return Return Type (int)
 140  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 141  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 142  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 143  *
 144  * @par Prospective Clients:
 145  * External Apps.
 146  *
 147  * @see None
 148  *
 149  * @code
 150  * #include <ITapiSim.h>
 151  * int err_code = 0;
 152  * TelSimCardType_t cardInfo; //unkwon, sim(normally gsm), usim(normally umts)
 153  * TapiHandle *handle;  // Handle given by tel_init()
 154  *
 155  * err_code = tel_get_sim_type(handle, &cardInfo);
 156  *
 157  * @endcode
 158  *
 159  * @remarks None
 160  *
 161  */
 162 /*================================================================================================*/
 163 int tel_get_sim_type(TapiHandle *handle, TelSimCardType_t *card_type);
 164
 165 /**
 166  * @brief  This API is used to get the IMSI information.
 167  *
 168  * @par Sync (or) Async:
 169  * This is a Synchronous API.
 170  *
 171  * @par Important Notes:
 172  * - IMSI value is the value that security needs.
 173  *
 174  * @warning
 175  * - None.
 176  *
 177  * @param [in] handle
 178  * - handle from tel_init().
 179  *
 180  * @param [out] imsi
 181  * This parameter returns the IMSI information. Refer #TelSimImsiInfo_t
 182  *
 183  * @par Async Response Message:
 184  * - None
 185  *
 186  * @pre
 187  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 188  *  - None.
 189  *
 190  * @post
 191  *  - None.
 192  *
 193  * @return Return Type (int)
 194  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 195  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 196  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 197  *
 198  * @par Prospective Clients:
 199  * External Apps.
 200  *
 201  * @see None
 202  *
 203  * @code
 204  * #include <ITapiSim.h>
 205  * int err_code = 0;
 206  * TelSimImsiInfo_t sim_imsi_info; // mcc, mnc, msisdn
 207  * err_code = tel_get_sim_imsi(handle, &sim_imsi_info);
 208  * @endcode
 209  *
 210  * @remarks None
 211  *
 212  */
 213 /*================================================================================================*/
 214 int tel_get_sim_imsi(TapiHandle *handle, TelSimImsiInfo_t *imsi);
 215
 216 /**
 217  * @brief  This API is used to get ECC(SIM) or UECC(USIM) data.
 218  *
 219  * @par Sync (or) Async:
 220  * This is a Synchronous API.
 221  *
 222  * @par Important Notes:
 223  * - None
 224  *
 225  * @warning
 226  * - None.
 227  *
 228  * @param [in] handle
 229  * - handle from tel_init().
 230  *
 231  * @param [out] ecc
 232  * - This parameter returns
 233  *  *  * the SIM emergency call code information like ecc length, service type etc
 234  * *  * and number of ECC records.
 235  *
 236  * @par Async Response Message:
 237  * - None
 238  *
 239  * @pre
 240  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 241  *  - None.
 242  *
 243  * @post
 244  *  - None.
 245  *
 246  * @return Return Type (int)
 247  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 248  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 249  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 250  *
 251  * @par Prospective Clients:
 252  * External Apps.
 253  *
 254  * @see None
 255  *
 256  * @code
 257  * #include <ITapiSim.h>
 258  * int err_code = 0;
 259  * TelSimEccList_t ecc_info = {0}; // Get ECC list info and ecc_count
 260  * err_code = tel_get_sim_ecc(handle, &ecc_info);
 261  * @endcode
 262  *
 263  * @remarks None
 264  *
 265  */
 266 /*================================================================================================*/
 267 int tel_get_sim_ecc(TapiHandle *handle, TelSimEccList_t *ecc);
 268
 269 /**
 270  * @brief  This API is used to get Unique identification number of the (U)ICC.
 271  * ICC means Integrated Circuit Card.
 272  *
 273  * @par Sync (or) Async:
 274  * This is a Asynchronous API.
 275  *
 276  * @par Important Notes:
 277  * - IC Card number value is the value that security needs.
 278  *
 279  * @warning
 280  * - None.
 281  *
 282  * @param [in] handle
 283  * - handle from tel_init().
 284  *
 285  * @param [in] callback
 286  * - To register callback function for result.
 287  *
 288  * @param [in] user_data
 289  * - user_data for user specification.
 290  *
 291  * @par Async Response Message:
 292  * - None
 293  *
 294  * @pre
 295  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 296  *  - None.
 297  *
 298  * @post
 299  *  - None.
 300  *
 301  * @return Return Type (int)
 302  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 303  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 304  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 305  *
 306  * @par Prospective Clients:
 307  * External Apps.
 308  *
 309  * @see None
 310  *
 311  * @code
 312  * #include <ITapiSim.h>
 313  * int err_code = 0;
 314  * TapiHandle *handle;  // Handle given by tel_init()
 315  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 316  * void *user_data; // Set User data
 317  * err_code = tel_get_sim_iccid(handle, callback, user_data);
 318  * @endcode
 319  *
 320  * @remarks None
 321  *
 322  */
 323 /*================================================================================================*/
 324 int tel_get_sim_iccid(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 325
 326 /**
 327  * @brief  This API is used to get the language preference(indication) information.
 328  *
 329  * @par Sync (or) Async:
 330  * This is a Asynchronous API.
 331  *
 332  * @par Important Notes:
 333  * - None
 334  *
 335  * @warning
 336  * - None.
 337  *
 338  * @param [in] handle
 339  * - handle from tel_init().
 340  *
 341  * @param [in] callback
 342  * - To register callback function for result.
 343  *
 344  * @param [in] user_data
 345  * - user_data for user specification.
 346  *
 347  * @par Async Response Message:
 348  * - None
 349  *
 350  * @pre
 351  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 352  *  - None.
 353  *
 354  * @post
 355  *  - None.
 356  *
 357  * @return Return Type (int)
 358  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 359  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 360  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 361  *
 362  * @par Prospective Clients:
 363  * External Apps.
 364  *
 365  * @see None
 366  *
 367  * @code
 368  * #include <ITapiSim.h>
 369  * int err_code = 0;
 370  * TapiHandle *handle;  // Handle given by tel_init()
 371  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 372  * void *user_data; // Set User data
 373  * err_code = tel_get_sim_language(handle, callback, user_data);
 374  * @endcode
 375  *
 376  * @remarks None
 377  *
 378  */
 379 /*================================================================================================*/
 380 int tel_get_sim_language(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 381
 382 /**
 383  * @brief  This API is used to update the language preference information to SIM card.
 384  *
 385  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 386  * However it just means that the API request has been transfered to the CP successfully.
 387  * The actual operation result is being delivered in the corresponding event asynchronously.
 388  *
 389  * @par Sync (or) Async:
 390  * This is a Asynchronous API.
 391  *
 392  * @par Important Notes:
 393  * - This function update SIM Language information directly and can effect device language setting. Use carefully.
 394  *
 395  * @warning
 396  * - None.
 397  *
 398  * @param [in] handle
 399  * - handle from tel_init().
 400  *
 401  * @param [in] language
 402  * This parameter returns the language preference information.
 403  *
 404  * @param [in] callback
 405  * - To register callback function for result.
 406  *
 407  * @param [in] user_data
 408  * - user_data for user specification.
 409  *
 410  * @par Async Response Message:
 411  * The event associated is TAPI_EVENT_SIM_SET_LANGUAGE_CNF.
 412  * Asynchronous return status is indicated by #TelSimAccessResult_t.
 413  *
 414  * @pre
 415  *  - A dbus connection is established with #tel_init
 416  *  - The application name is registered with #tel_register_app_name
 417  *  - The application is registered events to listen asynchronous response with #tel_register_event
 418  *  - A event loop is running to listen events
 419  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 420  *  - None.
 421  *
 422  * @post
 423  *  - None.
 424  *
 425  * @return Return Type (int)
 426  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 427  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 428  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 429  *
 430  * @par Prospective Clients:
 431  * External Apps.
 432  *
 433  * @see None
 434  *
 435  * @code
 436  * #include <ITapiSim.h>
 437  * int err_code = 0;
 438  * TelSimLanguagePreferenceCode_t language = 0x00; //init
 439  * language = TAPI_SIM_LP_ENGLISH; //language value
 440  * TapiHandle *handle;  // Handle given by tel_init()
 441  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 442  * void *user_data; // Set User data
 443  * err_code = tel_set_sim_language(handle, language, callback, user_data);
 444  * @endcode
 445  *
 446  * @remarks None
 447  *
 448  */
 449 /*================================================================================================*/
 450 int tel_set_sim_language(TapiHandle *handle, TelSimLanguagePreferenceCode_t language, tapi_response_cb callback, void *user_data);
 451
 452 /**
 453  * @brief  This API is used to get the SIM Call forwarding indication related data(EF-CFIS and CPHS case).
 454  * this data is required for Call forwarding related functionality in handset.
 455  *
 456  * @par Sync (or) Async:
 457  * This is a Asynchronous API.
 458  *
 459  * @par Important Notes:
 460  * - None
 461  *
 462  * @warning
 463  * - None
 464  *
 465  * @param [in] handle
 466  * - handle from tel_init().
 467  *
 468  * @param [in] callback
 469  * - To register callback function for result.
 470  *
 471  * @param [in] user_data
 472  * - user_data for user specification.
 473  *
 474  * @par Async Response Message:
 475  * - None
 476  *
 477  * @pre
 478  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 479  *  - None
 480  *
 481  * @post
 482  *  - None
 483  *
 484  * @return Return Type (int)
 485  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 486  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 487  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 488  *
 489  * @par Prospective Clients:
 490  * External Apps
 491  *
 492  * @see None
 493  *
 494  * @code
 495  * #include <ITapiSim.h>
 496   * int err_code = 0;
 497  * TapiHandle *handle;  // Handle given by tel_init()
 498  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 499  * void *user_data; // Set User data
 500  * err_code = tel_get_sim_callforwarding_info(handle, callback, user_data);
 501  * if(err_code == TAPI_API_SUCCESS) {
 502  *   if(cf_data.b_cphs) { //b_cphs means current SIM is for CPHS or not.
 503  *     printf("Current SIM is CPHS");
 504  *   } else {
 505  *     printf("Current SIM is not CPHS but 3GPP");
 506  *   }
 507  * } else {
 508  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
 509  * }
 510  * @endcode
 511  *
 512  * @remarks None
 513  *
 514  */
 515 /*================================================================================================*/
 516 int tel_get_sim_callforwarding_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 517
 518 /**
 519  * @brief  This API is used to set the SIM Call forwarding indication related data(EF-CFIS and CPHS case).
 520  * this data is required for Call forwarding related functionality in handset.
 521  *
 522  * @par Sync (or) Async:
 523  * This is a Asynchronous API.
 524  *
 525  * @par Important Notes:
 526  * - None
 527  *
 528  * @warning
 529  * - None
 530  *
 531  * @param [in] handle
 532  * - handle from tel_init().
 533  *
 534  * @param [in] callback
 535  * - To register callback function for result.
 536  *
 537  * @param [in] user_data
 538  * - user_data for user specification.
 539  *
 540  * @par Async Response Message:
 541  * - None
 542  *
 543  * @pre
 544  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 545  *  - None
 546  *
 547  * @post
 548  *  - None
 549  *
 550  * @return Return Type (int)
 551  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 552  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 553  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 554  *
 555  * @par Prospective Clients:
 556  * External Apps
 557  *
 558  * @see None
 559  *
 560  * @code
 561  * #include <ITapiSim.h>
 562  * int err_code = 0;
 563  * TelSimCallForwardingReq_t *req_cf;
 564  * TapiHandle *handle;  // Handle given by tel_init()
 565  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 566  * void *user_data; // Set User data
 567  * err_code = tel_set_sim_callforwarding_info(handle, &req_cf, callback, user_data);
 568  * @endcode
 569  *
 570  * @remarks None
 571  *
 572  */
 573 /*================================================================================================*/
 574 int tel_set_sim_callforwarding_info(TapiHandle *handle, TelSimCallForwardingReq_t *req_cf, tapi_response_cb callback, void *user_data);
 575
 576 /**
 577  * @brief  This API is used to get the SIM message waiting indication related data(EF-MWIS and CPHS case).
 578  * this data is required for Message waiting related functionality in handset.
 579  *
 580  * @par Sync (or) Async:
 581  * This is a Asynchronous API.
 582  *
 583  * @par Important Notes:
 584  * - None
 585  *
 586  * @warning
 587  * - None
 588  *
 589  * @param [in] handle
 590  * - handle from tel_init().
 591  *
 592  * @param [in] callback
 593  * - To register callback function for result.
 594  *
 595  * @param [in] user_data
 596  * - user_data for user specification.
 597  *
 598  * @par Async Response Message:
 599  * - None
 600  *
 601  * @pre
 602  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 603  *  - None
 604  *
 605  * @post
 606  *  - None
 607  *
 608  * @return Return Type (int)
 609  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 610  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 611  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 612  *
 613  * @par Prospective Clients:
 614  * External Apps
 615  *
 616  * @see None
 617  *
 618  * @code
 619  * #include <ITapiSim.h>
 620  * TelSimMessageWaiting_s mw_data;
 621  * int err_code = 0;
 622  * TapiHandle *handle;  // Handle given by tel_init()
 623  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 624  * void *user_data; // Set User data
 625  * err_code = tel_get_sim_messagewaiting_info(handle, callback, user_data);
 626  * if(err_code == TAPI_API_SUCCESS) {
 627  *   if(mw_data.b_cphs) { //b_cphs means current SIM is for CPHS or not.
 628  *     printf("Current SIM is CPHS");
 629  *   } else {
 630  *     printf("Current SIM is not CPHS but 3GPP");
 631  *   }
 632  * } else {
 633  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
 634  * }
 635  * @endcode
 636  *
 637  * @remarks None
 638  *
 639  */
 640 /*================================================================================================*/
 641 int tel_get_sim_messagewaiting_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 642
 643 /**
 644  * @brief  This API is used to set the SIM message waiting indication related data(EF-MWIS and CPHS case).
 645  * this data is required for Message waiting related functionality in handset.
 646  *
 647  * @par Sync (or) Async:
 648  * This is a Asynchronous API.
 649  *
 650  * @par Important Notes:
 651  * - None
 652  *
 653  * @warning
 654  * - None
 655  *
 656  * @param [in] handle
 657  * - handle from tel_init().
 658  *
 659  * @param [in] callback
 660  * - To register callback function for result.
 661  *
 662  * @param [in] user_data
 663  * - user_data for user specification.
 664  *
 665  * @par Async Response Message:
 666  * - None
 667  *
 668  * @pre
 669  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 670  *  - None
 671  *
 672  * @post
 673  *  - None
 674  *
 675  * @return Return Type (int)
 676  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 677  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 678  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 679  *
 680  * @par Prospective Clients:
 681  * External Apps
 682  *
 683  * @see None
 684  *
 685  * @code
 686  * #include <ITapiSim.h>
 687  * TelSimMessageWaiting_s mw_data;
 688  * int err_code = 0;
 689  * TelSimMessageWaitingReq_t *req_mw; // Get message waiting info
 690  * TapiHandle *handle;  // Handle given by tel_init()
 691  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 692  * void *user_data; // Set User data
 693  * err_code = tel_set_sim_messagewaiting_info(handle, &req_mw, callback, user_data);
 694  * @endcode
 695  *
 696  * @remarks None
 697  *
 698  */
 699 /*================================================================================================*/
 700 int tel_set_sim_messagewaiting_info(TapiHandle *handle, TelSimMessageWaitingReq_t *req_mw, tapi_response_cb callback, void *user_data);
 701
 702 /**
 703  * @brief  This API is used to get the SIM mailbox related data(EF-MBDN, MBDI and CPHS case).
 704  * this data is required for Mailbox related functionality in handset.
 705  *
 706  * @par Sync (or) Async:
 707  * This is a Asynchronous API.
 708  *
 709  * @par Important Notes:
 710  * - None
 711  *
 712  * @warning
 713  * - None.
 714  *
 715  * @param [in] handle
 716  * - handle from tel_init().
 717  *
 718  * @param [in] callback
 719  * - To register callback function for result.
 720  *
 721  * @param [in] user_data
 722  * - user_data for user specification.
 723  *
 724  * @par Async Response Message:
 725  * - None
 726  *
 727  * @pre
 728  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 729  *  - None.
 730  *
 731  * @post
 732  *  - None.
 733  *
 734  * @return Return Type (int)
 735  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 736  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 737  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 738  *
 739  * @par Prospective Clients:
 740  * External Apps.
 741  *
 742  * @see None
 743  *
 744  * @code
 745  * #include <ITapiSim.h>
 746  * int err_code = 0;
 747  * TapiHandle *handle;  // Handle given by tel_init()
 748  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 749  * void *user_data; // Set User data
 750  * err_code = tel_get_sim_mailbox_info(handle, callback, user_data);
 751  * if(err_code == TAPI_API_SUCCESS) {
 752  *   if(mbox.b_cphs) { //b_cphs means current SIM is for CPHS or not.
 753  *     printf("Current SIM is CPHS");
 754  *   } else {
 755  *     printf("Current SIM is not CPHS but 3GPP");
 756  *   }
 757  * } else {
 758  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
 759  * }
 760  * @endcode
 761  *
 762  * @remarks None
 763  *
 764  */
 765 /*================================================================================================*/
 766 int tel_get_sim_mailbox_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 767
 768 /**
 769  * @brief  This API is used to set the SIM mailbox related data(EF-MBDN, MBDI and CPHS case).
 770  * this data is required for Mailbox related functionality in handset.
 771  *
 772  * @par Sync (or) Async:
 773  * This is a Asynchronous API.
 774  *
 775  * @par Important Notes:
 776  * - None
 777  *
 778  * @warning
 779  * - None.
 780  *
 781  * @param [in] handle
 782  * - handle from tel_init().
 783  *
 784  * @param [in] callback
 785  * - To register callback function for result.
 786  *
 787  * @param [in] user_data
 788  * - user_data for user specification.
 789  *
 790  * @par Async Response Message:
 791  * - None
 792  *
 793  * @pre
 794  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 795  *  - None.
 796  *
 797  * @post
 798  *  - None.
 799  *
 800  * @return Return Type (int)
 801  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 802  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 803  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 804  *
 805  * @par Prospective Clients:
 806  * External Apps.
 807  *
 808  * @see None
 809  *
 810  * @code
 811  * #include <ITapiSim.h>
 812  * int err_code = 0;
 813  * TelSimMailBoxNumber_t *req_mb; // Get SIM mail box number info
 814  * TapiHandle *handle;  // Handle given by tel_init()
 815  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 816  * void *user_data; // Set User data
 817  * err_code = tel_set_sim_mailbox_info(handle, &req_mb, callback, user_data);
 818  * @endcode
 819  *
 820  * @remarks None
 821  *
 822  */
 823 /*================================================================================================*/
 824 int tel_set_sim_mailbox_info(TapiHandle *handle, TelSimMailBoxNumber_t *req_mb, tapi_response_cb callback, void *user_data);
 825
 826 /**
 827  * @brief  This API is used to get the SIM CPHS specific data.
 828  * this data is required for CPHS related functionality in handset.
 829  *
 830  * @par Sync (or) Async:
 831  * This is an Asynchronous API.
 832  *
 833  * @par Important Notes:
 834  * - None
 835  *
 836  * @warning
 837  * - None
 838  *
 839  * @param [in] handle
 840  * - handle from tel_init().
 841  *
 842  * @param [in] callback
 843  * - To register callback function for result.
 844  *
 845  * @param [in] user_data
 846  * - user_data for user specification.
 847  *
 848  * @par Async Response Message:
 849  * - None
 850  *
 851  * @pre
 852  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 853  *
 854  * @post
 855  *  - None
 856  *
 857  * @return Return Type (int)
 858  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 859  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 860  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 861  *
 862  * @par Prospective Clients:
 863  * External Apps
 864  *
 865  * @see None
 866  *
 867  * @code
 868  * #include <ITapiSim.h>
 869  * int err_code = 0;
 870  * TapiHandle *handle;  // Handle given by tel_init()
 871  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 872  * void *user_data; // Set User data
 873  * err_code = tel_get_sim_cphs_info(handle, callback, user_data);
 874  * if(err_code == TAPI_API_SUCCESS) {
 875  *   if(cphs_data.b_used) { //b_used means current SIM is for CPHS or not.
 876  *     printf("Current SIM is CPHS");
 877  *   } else {
 878  *     printf("Current SIM is not CPHS but 3GPP");
 879  *   }
 880  * } else {
 881  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
 882  * }
 883  * @endcode
 884  *
 885  * @remarks None
 886  *
 887  */
 888 /*================================================================================================*/
 889 int tel_get_sim_cphs_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 890
 891 /**
 892  * @brief  This API is used to get the SIM Service Table.
 893  * this data is required to know which SIM services are enabled or disabled.
 894  *
 895  * @par Sync (or) Async:
 896  * This is an Asynchronous API.
 897  *
 898  * @par Important Notes:
 899  * - None
 900  *
 901  * @warning
 902  * - None
 903  *
 904  * @param [in] handle
 905  * - handle from tel_init().
 906  *
 907  * @param [in] callback
 908  * - To register callback function for result.
 909  *
 910  * @param [in] user_data
 911  * - user_data for user specification.
 912  *
 913  * @par Async Response Message:
 914  * - None
 915  *
 916  * @pre
 917  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 918  *
 919  * @post
 920  *  - None
 921  *
 922  * @return Return Type (int)
 923  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 924  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 925  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 926  *
 927  * @par Prospective Clients:
 928  * External Apps
 929  *
 930  * @see None
 931  *
 932  * @code
 933  * #include <ITapiSim.h>
 934  * int err_code = 0;
 935  * TapiHandle *handle;  // Handle given by tel_init()
 936  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
 937  * void *user_data; // Set User data
 938  * err_code = tel_get_sim_service_table(handle, callback, user_data);
 939  * @endcode
 940  *
 941  * @remarks None
 942  *
 943  */
 944 /*================================================================================================*/
 945 int tel_get_sim_service_table(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 946
 947 /**
 948  * @brief  This API is used to get the SIM MSISDN data. Regarding 3GPP specification, Current value is optional.
 949  *
 950  * @par Sync (or) Async:
 951  * This is an Asynchronous API.
 952  *
 953  * @par Important Notes:
 954  * - None
 955  *
 956  * @warning
 957  * - None
 958  *
 959  * @param [in] handle
 960  * - handle from tel_init().
 961  *
 962  * @param [in] callback
 963  * - To register callback function for result.
 964  *
 965  * @param [in] user_data
 966  * - user_data for user specification.
 967  *
 968  * @par Async Response Message:
 969  * - None
 970  *
 971  * @pre
 972  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 973  *
 974  * @post
 975  *  - None
 976  *
 977  * @return Return Type (int)
 978  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
 979  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
 980  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
 981  *
 982  * @par Prospective Clients:
 983  * External Apps
 984  *
 985  * @see None
 986  *
 987  * @code
 988  * #include <ITapiSim.h>
 989  * int err_code = 0;
 990  * TapiHandle *handle;  // Handle given by tel_init()
 991  * err_code = tel_get_sim_msisdn(handle, callback, user_data);
 992  * if(err_code == TAPI_API_SUCCESS)
 993  * {
 994  * *  printf(" ============================================");
 995  * *  printf("name[%s]",msisdn.name);
 996  * *  printf("num[%s]",msisdn.num);
 997  * *  if(msisdn.name == '\0';) //If current SIM does not have, Null string will be returned.
 998  * *  *  printf("name is null string");
 999  *
1000  * *  if(msisdn.num == '\0';) //If current SIM does not have, Null string will be returned.
1001  * *  *  printf("number is null string");
1002  * }
1003  * else
1004  * {
1005  * *  printf("TAPI API FAIL: Error Code [0x%x]",err_code);
1006  * }
1007  *
1008  * @endcode
1009  *
1010  * @remarks None
1011  *
1012  */
1013 /*================================================================================================*/
1014 int tel_get_sim_msisdn(TapiHandle *handle, tapi_response_cb callback, void *user_data);
1015
1016 /**
1017  * @brief  This API is used to get the SIM OPLMNWACT(Operator controlled PLMN Selector with Access Technology) data. Regarding 3GPP specification, Current value is optional.
1018  *
1019  * @par Sync (or) Async:
1020  * This is an Asynchronous API.
1021  *
1022  * @par Important Notes:
1023  * - None
1024  *
1025  * @warning
1026  * - None
1027  *
1028  * @param [in] handle
1029  * - handle from tel_init().
1030  *
1031  * @param [in] callback
1032  * - To register callback function for result.
1033  *
1034  * @param [in] user_data
1035  * - user_data for user specification.
1036  *
1037  * @par Async Response Message:
1038  * - None
1039  *
1040  * @pre
1041  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1042  *
1043  * @post
1044  *  - None
1045  *
1046  * @return Return Type (int)
1047  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1048  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1049  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1050  *
1051  * @par Prospective Clients:
1052  * External Apps
1053  *
1054  * @see None
1055  *
1056  * @code
1057  * int err_code = 0;
1058  * TapiHandle *handle;  // Handle given by tel_init()
1059  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1060  * void *user_data; // Set User data
1061  * err_code = tel_get_sim_oplmnwact(handle, callback, user_data);
1062  *
1063  * @endcode
1064  *
1065  * @remarks None
1066  *
1067  */
1068 /*================================================================================================*/
1069 int tel_get_sim_oplmnwact(TapiHandle *handle, tapi_response_cb callback, void *user_data);
1070
1071 /**
1072  * @brief  This API is used to get the SIM SPN data. Regarding 3GPP specification, Current value is optional.
1073  *
1074  * @par Sync (or) Async:
1075  * This is an Asynchronous API.
1076  *
1077  * @par Important Notes:
1078  * - None
1079  *
1080  * @warning
1081  * - None
1082  *
1083  * @param [in] handle
1084  * - handle from tel_init().
1085  *
1086  * @param [in] callback
1087  * - To register callback function for result.
1088  *
1089  * @param [in] user_data
1090  * - user_data for user specification.
1091  *
1092  * @par Async Response Message:
1093  * - None
1094  *
1095  * @pre
1096  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1097  *
1098  * @post
1099  *  - None
1100  *
1101  * @return Return Type (int)
1102  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1103  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1104  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1105  *
1106  * @par Prospective Clients:
1107  * External Apps
1108  *
1109  * @see None
1110  *
1111  * @code
1112  * int err_code = 0;
1113  * TapiHandle *handle;  // Handle given by tel_init()
1114  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1115  * void *user_data; // Set User data
1116  * err_code = tel_get_sim_spn(handle, callback, user_data);
1117  *
1118  * @endcode
1119  *
1120  * @remarks None
1121  *
1122  */
1123 /*================================================================================================*/
1124 int tel_get_sim_spn(TapiHandle *handle, tapi_response_cb callback, void *user_data);
1125
1126 /**
1127  * @brief  This API is used to get the SIM CPHS NETNAME data.
1128  *
1129  * @par Sync (or) Async:
1130  * This is an Asynchronous API.
1131  *
1132  * @par Important Notes:
1133  * - None
1134  *
1135  * @warning
1136  * - None
1137  *
1138  * @param [in] handle
1139  * - handle from tel_init().
1140  *
1141  * @param [in] callback
1142  * - To register callback function for result.
1143  *
1144  * @param [in] user_data
1145  * - user_data for user specification.
1146  *
1147  * @par Async Response Message:
1148  * - None
1149  *
1150  * @pre
1151  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1152  *
1153  * @post
1154  *  - None
1155  *
1156  * @return Return Type (int)
1157  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1158  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1159  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1160  *
1161  * @par Prospective Clients:
1162  * External Apps
1163  *
1164  * @see None
1165  *
1166  * @code
1167  * int err_code = 0;
1168  * TapiHandle *handle;  // Handle given by tel_init()
1169  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1170  * void *user_data; // Set User data
1171  * err_code = tel_get_sim_cphs_netname(handle, callback, user_data);
1172  *
1173  * @endcode
1174  *
1175  * @remarks None
1176  *
1177  */
1178 /*================================================================================================*/
1179 int tel_get_sim_cphs_netname(TapiHandle *handle, tapi_response_cb callback, void *user_data);
1180
1181 /**
1182  * @brief  This API is used to execute the authentication procedure by using SIM.
1183  *
1184  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1185  * However it just means that the API request has been transfered to the CP successfully.
1186  * The actual operation result is being delivered in the corresponding event asynchronously.
1187  * This function supports IMS, 3G and GSM authentication.
1188  *
1189  * @par Sync (or) Async:
1190  * This is an Asynchronous API.
1191  *
1192  * @par Important Notes:
1193  * -NONE
1194  *
1195  * @warning
1196  * - None.
1197  *
1198  * @param [in] handle
1199  * - handle from tel_init().
1200  *
1201  * @param[in] authentication_data
1202  * - This input has the authentication code to be validated by ISIM,3G and GSM application in the SIM card. #TelSimAuthenticationData_t
1203  *
1204  * @param [in] callback
1205  * - To register callback function for result.
1206  *
1207  * @param [in] user_data
1208  * - user_data for user specification.
1209  *
1210  * @par Async Response Message:
1211  * -The event associated is TAPI_SIM_EVENT_AUTHENTICATION_CNF  and the event data is #TelSimAuthenticationResponse_t.
1212  * Asynchronous return status is indicated by #TelSimAccessResult_t.
1213  *
1214  * @pre
1215  *  - A dbus connection is established with #tel_init
1216  *  - The application name is registered with #tel_register_app_name
1217  *  - The application is registered events to listen asynchronous response with #tel_register_event
1218  *  - A event loop is running to listen events
1219  *
1220  * @post
1221  *  - None.
1222  *
1223  * @return Return Type (int)
1224  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1225  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1226  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1227  *
1228  * @par Prospective Clients:
1229  * External Apps.
1230  *
1231  * @see None
1232  *
1233  * @code
1234  * #include <ITapiSim.h>
1235  * int err_code = 0;
1236  * TapiHandle *handle;  // Handle given by tel_init()
1237  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1238  * void *user_data; // Set User data
1239  * TelSimAuthenticationData_t pAuthenticationData;
1240  * strcpy((char*)pAuthenticationData.rand_data, "username@operator.com"); //access data
1241  * pAuthenticationData.rand_length= strlen("username@operator.com");
1242  * strcpy((char*)pAuthenticationData.autn_data,  "+1-212-555-12345"); // auth data
1243  * pAuthenticationData.autn_length = strlen("+1-212-555-12345");
1244  * err_code = tel_req_sim_authentication(handle, &pAuthenticationData, callback, user_data);
1245  * @endcode
1246  *
1247  * @remarks None
1248  *
1249  */
1250 /*================================================================================================*/
1251 int tel_req_sim_authentication(TapiHandle *handle, TelSimAuthenticationData_t *authentication_data, tapi_response_cb callback, void *user_data);
1252
1253
1254
1255 /**
1256  * @brief  This API performs PIN1/PIN2/SIM LOCK verification. This function performs PIN verification based on the pin type passed along with pin data.
1257  * PIN1 code : The SIM card has its own password is to check access permissions
1258  * SIM Lock code : Between Device and the SIM card using a SIM password is only available on certain handsets to be used to authorize.
1259  *
1260  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1261  * However it just means that the API request has been transfered to the CP successfully.
1262  * The actual operation result is being delivered in the corresponding event asynchronously.
1263  *
1264  * @par Sync (or) Async:
1265  * This is an Asynchronous API.
1266  *
1267  * @par Important Notes:
1268  * - Based on Pin status (PIN/PUK/SIM LOCK) is blocked, an unsolicited event TAPI_EVENT_SIM_STATUS_IND is published to Applications on Device boot time.
1269  * - if pin status is PUK, you should use #tel_verify_sim_puks instead of this API.
1270  *
1271  * @warning
1272  * - None.
1273  *
1274  * @param [in] handle
1275  * - handle from tel_init().
1276  *
1277  * @param[in] pin_data
1278  * -PIN code, entered by the user. you should make all parameters.
1279  *
1280  * @param [in] callback
1281  * - To register callback function for result.
1282  *
1283  * @param [in] user_data
1284  * - user_data for user specification.
1285  *
1286  * @par Async Response Message:
1287  * The event associated is TAPI_EVENT_SIM_VERIFY_SEC_CNF  and the event data is #TelSimSecResult_t.
1288  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
1289  * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Verification successes.
1290  * If returned status is TAPI_SIM_PIN_INCORRECT_PASSWORD, Verification fails and you can check retry count by using event data  #TelSimSecResult_t.
1291  *
1292  * @pre
1293  *  - Initialize Dbus connection with #tel_init
1294  *  - Register caller's application name with #tel_register_app_name
1295  *  - Register telephony events to listen
1296  *  - A event loop is running to listen events
1297  * - This API is used when #TelSimCardStatus_t is TAPI_SIM_STATUS_SIM_PIN_REQUIRED or TAPI_SIM_STATUS_SIM_LOCK_REQUIRED on boot time.
1298  * - Currently there`s no proper scenario for PIN2 verification by using this API.
1299  *
1300  * @post
1301  *  - None.
1302  *
1303  * @return Return Type (int)
1304  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1305  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1306  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1307  *
1308  * @par Prospective Clients:
1309  * External Apps.
1310  *
1311  * @see None
1312  *
1313  * @code
1314  * #include <ITapiSim.h>
1315  * TapiHandle *handle;  // Handle given by tel_init()
1316  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1317  * void *user_data; // Set User data
1318  * err_code = TAPI_API_SUCCESS; // 0
1319  * int length = TAPI_SIM_PIN_LENGTH+1;
1320  * char init_pin_val[length] ;
1321  *
1322  * strcpy(init_pin_val, PIN1_NORMAL);
1323  *
1324  * TelSimSecPw_t pin_data = {0,};
1325  *
1326  * pin_data.type = TAPI_SIM_PTYPE_PIN1;
1327  * pin_data.pw_len = strlen(init_pin_val);
1328  *
1329  * printf("pw_len[%d]", pin_data.pw_len);
1330  *
1331  * pin_data.pw = (char*)malloc(length);
1332  * memcpy(pin_data.pw,init_pin_val,length);
1333  *
1334  * err_code = tel_verifiy_sim_pins(handle, &pin_data, callback, user_data);
1335  *
1336  * @endcode
1337  *
1338  * @remarks None
1339  *
1340  */
1341 /*================================================================================================*/
1342 int tel_verifiy_sim_pins(TapiHandle *handle, const TelSimSecPw_t *pin_data, tapi_response_cb callback, void *user_data);
1343
1344 /**
1345  * @brief  This function performs unblock PIN1/PIN2 operation based on PUK information passed along with
1346  * unblock information entered by the user.
1347  * If you get sim card status(TAPI_SIM_STATUS_SIM_PUK_REQUIRED) by using #tel_get_sim_init_info on boot time
1348  * or (TAPI_SIM_PIN_STATUS_BLOCKED) by using #tel_get_sim_facility after normal initialization for specific operation,
1349  * you may unblock PIN1/PIN2.
1350  *
1351  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1352  * However it just means that the API request has been transfered to the CP successfully.
1353  * The actual operation result is being delivered in the corresponding event asynchronously.
1354  *
1355  * @par Sync (or) Async:
1356  * This is an Asynchronous API.
1357  *
1358  * @par Important Notes:
1359  * - Based on Pin status (PIN1/PIN2) is blocked, an unsolicited event TAPI_EVENT_SIM_STATUS_IND
1360  * is published to Applications on boot time also.
1361  *
1362  * @warning
1363  * - If you fail to unblock PIN til given retry count, Your SIM card be permanent block status.
1364  *
1365  * @param [in] handle
1366  * - handle from tel_init().
1367  *
1368  * @param[in] puk_data
1369  * -Specifies unblocking PIN password #TelSimSecPw_t
1370  *
1371  * @param[in] new_pin_data
1372  * -Specifies PIN password which you want to use after unblocking operation #TelSimSecPw_t
1373  *
1374  * @param [in] callback
1375  * - To register callback function for result.
1376  *
1377  * @param [in] user_data
1378  * - user_data for user specification.
1379  *
1380  * @par Async Response Message:
1381  * The event associated is TAPI_EVENT_SIM_VERIFY_PUK_CNF  and the event data is #TelSimSecResult_t.
1382  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
1383  * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Verification successes.
1384  * If returned status is TAPI_SIM_PUK_INCORRECT_PASSWORD, Verification fails and you can check retry count by using event data  #TelSimSecResult_t.
1385  *
1386  * @pre
1387  *  - Initialize Dbus connection with #tel_init
1388  *  - Register caller's application name with #tel_register_app_name
1389  *  - Register telephony events to listen
1390  *  - A event loop is running to listen events
1391  *  - PIN1 or PIN2 status should be TAPI_SIM_PIN_STATUS_BLOCKED and Card status should be TAPI_SIM_STATUS_SIM_PUK_REQUIRED on boot time.
1392  *
1393  * @post
1394  *  - After Success on unblocking for PIN1 or PIN2, each pin check facility is enabled even if previous facility is disabled.
1395  *
1396  * @return Return Type (int)
1397  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1398  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1399  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1400  *
1401  * @par Prospective Clients:
1402  * External Apps.
1403  *
1404  * @see None
1405  *
1406  * @code
1407  * #include <ITapiSim.h>
1408  *
1409  * TapiHandle *handle;  // Handle given by tel_init()
1410  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1411  * void *user_data; // Set User data
1412  * err_code = TAPI_API_SUCCESS; // 0
1413  * int length = TAPI_SIM_PIN_LENGTH+1;
1414  *
1415  * char init_pin_val[length];
1416  * char init_puk_val[length];
1417  *
1418  * strcpy(init_pin_val, PIN1_NORMAL);
1419  * strcpy(init_puk_val, PUK1_NORMAL);
1420  *
1421  * TelSimSecPw_t puk_data = {0,};
1422  * TelSimSecPw_t new_pin_data = {0,};
1423  *
1424  * puk_data.type = TAPI_SIM_PTYPE_PUK1;   // 0x00
1425  * puk_data.pw_len = length;
1426  * puk_data.pw_len = strlen(init_puk_val);
1427  * printf("pw_len[%d]", puk_data.pw_len);
1428  * memcpy(puk_data.pw,init_pin_val,length);
1429  *
1430  * new_pin_data.type = TAPI_SIM_PTYPE_PIN1;   // 0x00
1431  * new_pin_data.pw_len = strlen(init_pin_val);
1432  * printf("pw_len[%d]", new_pin_data.pw_len);
1433  * new_pin_data.pw = (char*)malloc(length);
1434  * memcpy(new_pin_data.pw,init_pin_val,length);
1435  *
1436  * err_code = tel_verify_sim_puks(handle, &puk_data, &new_pin_data, callback, user_data);
1437  *
1438  * @endcode
1439  *
1440  * @remarks None
1441  *
1442  */
1443 /*================================================================================================*/
1444 int tel_verify_sim_puks(TapiHandle *handle, const TelSimSecPw_t *puk_data, const TelSimSecPw_t *new_pin_data, tapi_response_cb callback, void *user_data);
1445
1446
1447 /**
1448  * @brief  This function changes PIN1/PIN2 code based on the pin type passed along with old pin data and new pin data.
1449  *
1450  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1451  * However it just means that the API request has been transfered to the CP successfully.
1452  * The actual operation result is being delivered in the corresponding event asynchronously.
1453  *
1454  * @par Sync (or) Async:
1455  * This is an Asynchronous API.
1456  *
1457  * @par Important Notes:
1458  * - User should fill up pin type equally both old_pin and new_pin.
1459  *
1460  * @warning
1461  * - None.
1462  *
1463  * @param [in] handle
1464  * - handle from tel_init().
1465  *
1466  * @param[in] old_pin
1467  * -Old pin code, entered by the user. #TelSimSecPw_t
1468  *
1469  * @param[in] new_pin
1470  * -New pin code, entered by the user. #TelSimSecPw_t
1471  *
1472  * @param [in] callback
1473  * - To register callback function for result.
1474  *
1475  * @param [in] user_data
1476  * - user_data for user specification.
1477  *
1478  * @par Async Response Message:
1479  * The event associated is TAPI_EVENT_SIM_CHANGE_PINS_CNF  and the event data is #TelSimSecResult_t.
1480  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
1481  * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Change operation finish successfully.
1482  * If returned status is TAPI_SIM_PIN_INCORRECT_PASSWORD, Change operation fails and you can check retry count by using event data  #TelSimSecResult_t.
1483  *
1484  * @pre
1485  *  - Initialize Dbus connection with #tel_init
1486  *  - Register caller's application name with #tel_register_app_name
1487  *  - Register telephony events to listen
1488  *  - A event loop is running to listen events
1489  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1490  *  - PIN which user want to change check facility should be enabled.
1491  *
1492  * @post
1493  *  - None.
1494  *
1495  * @return Return Type (int)
1496  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1497  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1498  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1499  *
1500  * @par Prospective Clients:
1501  * External Apps.
1502  *
1503  * @see None
1504  *
1505  * @code
1506  * #include <ITapiSim.h>
1507  *
1508  * TapiHandle *handle;  // Handle given by tel_init()
1509  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1510  * void *user_data; // Set User data
1511  * err_code = TAPI_API_SUCCESS; // 0
1512  * int length = TAPI_SIM_PIN_LENGTH+1;
1513  * char init_old_pin_val[length] ;
1514  * char init_new_pin_val[length];
1515  *
1516  * memset(&init_old_pin_val, 0 , length);
1517  * memset(&init_new_pin_val, 0 , length);
1518  *
1519  * TelSimSecPw_t old_pin = {0,};
1520  * TelSimSecPw_t new_pin = {0,};
1521  *
1522  * strcpy(init_old_pin_val, PIN1_ORG);
1523  *
1524  * old_pin.type = TAPI_SIM_PTYPE_PIN1;
1525  * old_pin.pw_len = strlen(init_old_pin_val);
1526  * printf("pw_len[%d]", old_pin.pw_len);
1527  * old_pin.pw = (char*)malloc(length);
1528  * memcpy(old_pin.pw,init_old_pin_val,length);
1529  *
1530  * strcpy(init_new_pin_val, PIN1_NEW);
1531  *
1532  * new_pin.type = TAPI_SIM_PTYPE_PIN1;
1533  * new_pin.pw_len = strlen(init_new_pin_val);
1534  * printf("pw_len[%d]", new_pin.pw_len);
1535  * new_pin.pw = (char*)malloc(length);
1536  * memcpy(new_pin.pw,init_new_pin_val,length);
1537  *
1538  * err_code = tel_change_sim_pins(handle, &old_pin, &new_pin, callback, user_data);
1539  *
1540  * @endcode
1541  *
1542  * @remarks None
1543  *
1544  */
1545 /*================================================================================================*/
1546 int tel_change_sim_pins(TapiHandle *handle, const TelSimSecPw_t *old_pin, const TelSimSecPw_t *new_pin, tapi_response_cb callback, void *user_data);
1547
1548 /**
1549  * @brief  This API is used to disable the SIM facility.
1550  *
1551  * @par Sync (or) Async:
1552  * This is an Asynchronous API.
1553  *
1554  * @par Important Notes:
1555  * - None
1556  *
1557  * @warning
1558  * - None.
1559  *
1560  * @param [in] handle
1561  * - handle from tel_init().
1562  *
1563  * @param[in] pw
1564  *  - a structure which contains facility type and password.
1565  *
1566  * @param [in] callback
1567  * - To register callback function for result.
1568  *
1569  * @param [in] user_data
1570  * - user_data for user specification.
1571  *
1572  * @par
1573  *
1574  * @pre
1575  *
1576  * @post
1577  *
1578  * @return Return Type (int)
1579  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1580  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1581  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1582  *
1583  * @par Prospective Clients:
1584  * External Apps.
1585  *
1586  * @see None
1587  *
1588  * @code
1589  * int err_code = 0;
1590  * TapiHandle *handle;  // Handle given by tel_init()
1591  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1592  * void *user_data; // Set User data
1593  * TelSimFacilityPw_t *fc_pw;
1594  * int length = TAPI_SIM_PIN_LENGTH+1;
1595  * char init_pin_val[length] ;
1596  *
1597  * strcpy(init_pin_val, PIN1_NORMAL);
1598  *
1599  * fc_pw.lock_type = TAPI_SIM_LOCK_SC; // Set locktype for which facility should be disabled;
1600  * fc_pw.pw_len = strlen(init_pin_val);
1601  *
1602  * printf("pw_len[%d]", fc_pw.pw_len);
1603  *
1604  * fc_pw.pw = (char*)malloc(length);
1605  * memcpy(fc_pw.pw,init_pin_val,length);
1606  * err_code = tel_disable_sim_facility(handle, fc_pw, callback, user_data);
1607  *
1608  * @endcode
1609  *
1610  * @remarks None
1611  *
1612  */
1613 /*================================================================================================*/
1614 int tel_disable_sim_facility(TapiHandle *handle, TelSimFacilityPw_t *pw, tapi_response_cb callback, void *user_data);
1615
1616 /**
1617  * @brief  This API is used to enable the SIM facility.
1618  *
1619  * @par Sync (or) Async:
1620  * This is an Asynchronous API.
1621  *
1622  * @par Important Notes:
1623  * - None
1624  *
1625  * @warning
1626  * - None.
1627  *
1628  * @param [in] handle
1629  * - handle from tel_init().
1630  *
1631  * @param[in] pw
1632  *  - a structure which contains facility type and password.
1633  *
1634  * @param [in] callback
1635  * - To register callback function for result.
1636  *
1637  * @param [in] user_data
1638  * - user_data for user specification.
1639  *
1640  * @par
1641  *
1642  * @pre
1643  *
1644  * @post
1645  *
1646  * @return Return Type (int)
1647  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1648  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1649  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1650  *
1651  * @par Prospective Clients:
1652  * External Apps.
1653  *
1654  * @see None
1655  *
1656  * @code
1657  * int err_code = 0;
1658  * TapiHandle *handle;  // Handle given by tel_init()
1659  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1660  * void *user_data; // Set User data
1661  * TelSimFacilityPw_t *fc_pw;
1662  * int length = TAPI_SIM_PIN_LENGTH+1;
1663  * char init_pin_val[length] ;
1664  *
1665  * strcpy(init_pin_val, PIN1_NORMAL);
1666  *
1667  * fc_pw.lock_type = TAPI_SIM_LOCK_SC; // Set locktype for which facility should be disabled;
1668  * fc_pw.pw_len = strlen(init_pin_val);
1669  *
1670  * printf("pw_len[%d]", fc_pw.pw_len);
1671  *
1672  * fc_pw.pw = (char*)malloc(length);
1673  * memcpy(fc_pw.pw,init_pin_val,length);
1674  * err_code = tel_enable_sim_facility(handle, fc_pw, callback, user_data);
1675  *
1676  * @endcode
1677  *
1678  * @remarks None
1679  *
1680  */
1681 /*================================================================================================*/
1682 int tel_enable_sim_facility(TapiHandle *handle, TelSimFacilityPw_t *pw, tapi_response_cb callback, void *user_data);
1683
1684 /**
1685  * @brief  This API is used to get the SIM facility.
1686  *
1687  * @par Sync (or) Async:
1688  * This is an Asynchronous API.
1689  *
1690  * @par Important Notes:
1691  * - None
1692  *
1693  * @warning
1694  * - None.
1695  *
1696  * @param [in] handle
1697  * - handle from tel_init().
1698  *
1699  * @param[in] type
1700  *  - type of security lock type enum values.
1701  *
1702  * @param [in] callback
1703  * - To register callback function for result.
1704  *
1705  * @param [in] user_data
1706  * - user_data for user specification.
1707  *
1708  * @par
1709  *
1710  * @pre
1711  *
1712  * @post
1713  *
1714  * @return Return Type (int)
1715  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1716  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1717  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1718  *
1719  * @par Prospective Clients:
1720  * External Apps.
1721  *
1722  * @see None
1723  *
1724  * @code
1725  * int err_code = 0;
1726  * TapiHandle *handle;  // Handle given by tel_init()
1727  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1728  * void *user_data; // Set User data
1729  * TelSimLockType_t type = TAPI_SIM_LOCK_SC; // Set locktype for which facility should be disabled;
1730  * err_code = tel_get_sim_facility(handle, type, callback, user_data);
1731  *
1732  * @endcode
1733  *
1734  * @remarks None
1735  *
1736  */
1737 /*================================================================================================*/
1738 int tel_get_sim_facility(TapiHandle *handle, TelSimLockType_t type, tapi_response_cb callback, void *user_data);
1739
1740 /**
1741  * @brief  This API is used to get the SIM LOCK TYPE info.
1742  *
1743  * @par Sync (or) Async:
1744  * This is an Asynchronous API.
1745  *
1746  * @par Important Notes:
1747  * - None
1748  *
1749  * @warning
1750  * - None.
1751  *
1752  * @param [in] handle
1753  * - handle from tel_init().
1754  *
1755  * @param[in] type
1756  *  - type of security lock type enum values.
1757  *
1758  * @param [in] callback
1759  * - To register callback function for result.
1760  *
1761  * @param [in] user_data
1762  * - user_data for user specification.
1763  *
1764  * @par
1765  *
1766  * @pre
1767  *
1768  * @post
1769  *
1770  * @return Return Type (int)
1771  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1772  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1773  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1774  *
1775  * @par Prospective Clients:
1776  * External Apps.
1777  *
1778  * @see None
1779  *
1780  * @code
1781  * int err_code = 0;
1782  * TapiHandle *handle;  // Handle given by tel_init()
1783  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1784  * void *user_data; // Set User data
1785  * TelSimLockType_t type = TAPI_SIM_LOCK_SC; // Set locktype for which facility should be disabled;
1786  * err_code = tel_get_sim_lock_info(handle, type, callback, user_data);
1787  *
1788  * @endcode
1789  *
1790  * @remarks None
1791  *
1792  */
1793 /*================================================================================================*/
1794 int tel_get_sim_lock_info(TapiHandle *handle, TelSimLockType_t type, tapi_response_cb callback, void *user_data);
1795
1796 /**
1797  * @brief  This API provides common interface for accessing SIM data based on USIM generic command in ETSI TS 102 221
1798  * and 3GPP TS 31.102 Characteristics of the Universal Subscriber Identity Module (USIM) application.
1799  * This API provides only interface to send APDU. User should know well APDU usage.
1800  *
1801  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1802  * However it just means that the API request has been transfered to the CP successfully.
1803  * The actual operation result is being delivered in the corresponding event asynchronously.
1804  *
1805  * @par Sync (or) Async:
1806  * This is an Asynchronous API.
1807  *
1808  * @par Important Notes:
1809  * - None
1810  *
1811  * @warning
1812  * - None.
1813  *
1814  * @param [in] handle
1815  * - handle from tel_init().
1816  *
1817  * @param[in] apdu_data
1818  *
1819  * @param [in] callback
1820  * - To register callback function for result.
1821  *
1822  * @param [in] user_data
1823  * - user_data for user specification.
1824  *
1825  * @par Async Response Message:
1826  * The event associated is TAPI_EVENT_SIM_APDU_CNF  and the event data is #TelSimApduResp_t.
1827  * Asynchronous return status is indicated by #TelSimAccessResult_t.
1828  *
1829  * @pre
1830  *  - A dbus connection is established with #tel_init
1831  *  - The application name is registered with #tel_register_app_name
1832  *  - The application is registered events to listen asynchronous response with #tel_register_event
1833  *  - A event loop is running to listen events
1834  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1835  *  - None.
1836  *
1837  * @post
1838  *  - None.
1839  *
1840  * @return Return Type (int)
1841  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1842  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1843  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1844  *
1845  * @par Prospective Clients:
1846  * External Apps.
1847  *
1848  * @see None
1849  *
1850  * @code
1851  * #include <ITapiSim.h>
1852  * int err_code =0;
1853  * TapiHandle *handle;  // Handle given by tel_init()
1854  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1855  * void *user_data; // Set User data
1856  * TelSimApdu_t apdu = {0,};
1857  * int tmp_apdu[5] = {0xa,5,6,7,8};
1858  * apdu.apdu_len = 5; //user should check
1859  * apdu.apdu = apdu;
1860  *
1861  * err_code = tel_req_sim_apdu(handle, apdu, callback, user_data);
1862  * @endcode
1863  *
1864  * @remarks None
1865  *
1866  */
1867 /*================================================================================================*/
1868 int tel_req_sim_apdu(TapiHandle *handle, TelSimApdu_t* apdu_data, tapi_response_cb callback, void *user_data);
1869
1870 /**
1871  * @brief  This API provides common interface to get SIM ATR(Answer To Reset) value.
1872  *
1873  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1874  * However it just means that the API request has been transfered to the CP successfully.
1875  * The actual operation result is being delivered in the corresponding event asynchronously.
1876  *
1877  * @par Sync (or) Async:
1878  * This is an Asynchronous API.
1879  *
1880  * @par Important Notes:
1881  * - None
1882  *
1883  * @warning
1884  * - None.
1885  *
1886  * @param [in] handle
1887  * - handle from tel_init().
1888  *
1889  * @param [in] callback
1890  * - To register callback function for result.
1891  *
1892  * @param [in] user_data
1893  * - user_data for user specification.
1894  *
1895  * @par Async Response Message:
1896  * The event associated is TAPI_EVENT_SIM_ATR_CNF  and the event data is #TelSimAtrResp_t.
1897  * Asynchronous return status is indicated by #TelSimAccessResult_t.
1898  *
1899  * @pre
1900  *  - A dbus connection is established with #tel_init
1901  *  - The application name is registered with #tel_register_app_name
1902  *  - The application is registered events to listen asynchronous response with #tel_register_event
1903  *  - A event loop is running to listen events
1904  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1905  *  - None.
1906  *
1907  * @post
1908  *  - None.
1909  *
1910  * @return Return Type (int)
1911  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
1912  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1913  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1914  *
1915  * @par Prospective Clients:
1916  * External Apps.
1917  *
1918  * @see None
1919  *
1920  * @code
1921  * #include <ITapiSim.h>
1922  * int err_code =0;
1923  * TapiHandle *handle;  // Handle given by tel_init()
1924  * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1925  * void *user_data; // Set User data
1926  *
1927  * // REQUEST SIM ATR
1928  * err_code = tel_req_sim_atr(handle, callback, user_data);
1929  * @endcode
1930  *
1931  * @remarks None
1932  *
1933  */
1934 /*================================================================================================*/
1935 int tel_req_sim_atr(TapiHandle *handle, tapi_response_cb callback, void *user_data);
1936
1937 /*
1938  * @brief  This API provides synchronous call interface over some operations (refer to @param [in] op_type)
1939  *
1940  * @par Sync (or) Async:
1941  * This is an Synchronous API.
1942  *
1943   * @par Important Notes:
1944  * - None
1945  *
1946  * @warning
1947  * - None.
1948  *
1949  * @param [in] handle
1950  * - handle from tel_init().
1951  *
1952  * @param [in] op_type
1953  * operation type to do what caller want.
1954  * - TAPI_SIM_GET_INIT_STATUS
1955  * - TAPI_SIM_GET_CARD_TYPE
1956  * - TAPI_SIM_GET_IMSI
1957  * - TAPI_SIM_GET_ECC
1958  * - TAPI_SIM_GET_ICCID
1959  * - TAPI_SIM_GET_SPN
1960  * - TAPI_SIM_GET_CPHS_NET_NAME
1961  * - TAPI_SIM_TRANSFER_APDU
1962  * - TAPI_SIM_GET_ATR
1963  * - ( below are not supported. )
1964  * - TAPI_SIM_GET_LANGUAGE
1965  * - TAPI_SIM_SET_LANGUAGE
1966  * - TAPI_SIM_GET_CALL_FORWARDING
1967  * - TAPI_SIM_SET_CALL_FORWARDING
1968  * - TAPI_SIM_GET_MESSAGE_WAITING
1969  * - TAPI_SIM_SET_MESSAGE_WAITING
1970  * - TAPI_SIM_GET_MAILBOX
1971  * - TAPI_SIM_SET_MAILBOX
1972  * - TAPI_SIM_GET_CPHS_INFO
1973  * - TAPI_SIM_GET_SVCT
1974  * - TAPI_SIM_GET_MSISDN
1975  * - TAPI_SIM_GET_OPLMWACT
1976  * - TAPI_SIM_AUTHENTICATION
1977  * - TAPI_SIM_VERIFY_SEC
1978  * - TAPI_SIM_VERIFY_PUK
1979  * - TAPI_SIM_CHANGE_PIN
1980  * - TAPI_SIM_DISABLE_FACILITY
1981  * - TAPI_SIM_ENABLE_FACILITY
1982  * - TAPI_SIM_GET_FACILITY
1983  * - TAPI_SIM_GET_LOCK_INFO
1984  *
1985  * @param [in] inparam
1986  * input parameter of union type. caller should fill when it is needed as below.
1987  * - TAPI_SIM_GET_INIT_STATUS   : (not needed)
1988  * - TAPI_SIM_GET_CARD_TYPE             : (not needed)
1989  * - TAPI_SIM_GET_IMSI                  : (not needed)
1990  * - TAPI_SIM_GET_ECC                   : (not needed)
1991  * - TAPI_SIM_GET_ICCID                 : (not needed)
1992  * - TAPI_SIM_GET_SPN                   : (not needed)
1993  * - TAPI_SIM_GET_CPHS_NET_NAME : (not needed)
1994  * - TAPI_SIM_TRANSFER_APDU             : TelSimApdu_t
1995  * - TAPI_SIM_GET_ATR                   : (not needed)
1996  *
1997  * @param [out] outparam
1998  * output parameter of union type. TAPI returns a value as caller want.
1999  * - TAPI_SIM_GET_INIT_STATUS   : TelSimInitInfo_t
2000  * - TAPI_SIM_GET_CARD_TYPE             : TelSimCardType_t
2001  * - TAPI_SIM_GET_IMSI                  : TelSimImsiInfo_t
2002  * - TAPI_SIM_GET_ECC                   : TelSimEccList_t
2003  * - TAPI_SIM_GET_ICCID                 : TelSimIccIdInfo_t
2004  * - TAPI_SIM_GET_SPN                   : TelSimSpn_t
2005  * - TAPI_SIM_GET_CPHS_NET_NAME : TelSimCphsNetName_t
2006  * - TAPI_SIM_TRANSFER_APDU             : TelSimApduResp_t
2007  * - TAPI_SIM_GET_ATR                   : TelSimAtrResp_t
2008  *
2009  * @par Async Response Message:
2010  * - None
2011  *
2012  * @pre
2013  *  - None.
2014  *
2015  * @post
2016  *  - None.
2017  *
2018  * @return Return Type (int)
2019  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
2020  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
2021  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
2022  *
2023  * @par Prospective Clients:
2024  * External Apps.
2025  *
2026  * @see None
2027  *
2028  * @code (for example, tel_req_sim_apdu())
2029  * #include <ITapiSim.h>
2030  * int rt = 0;
2031  * TelResponseData_t outparam;
2032  * TelRequestData_t inparam;
2033  * TapiHandle *handle;  // Handle given by tel_init()
2034  * unsigned char apdu[5] = { 0x00, 0x70, 0x00, 0x00, 0x00};
2035  * memset (&outparam, 0, sizeof(TelResponseData_t));
2036  * memset (&inparam, 0, sizeof(TelRequestData_t));
2037  *
2038  * inparam.apdu.apdu_len = strlen(apdu);
2039  * inparam.apdu.apdu = (unsigned char*)malloc(5);
2040  * memcpy (inparam.apdu.apdu, apdu, inparam.apdu.apdu_len);
2041  *
2042  * rt = tel_request_sim_sync(handle, TAPI_SIM_TRANSFER_APDU, &inparam, &outparam);
2043  *
2044  * if(inparam.apdu.apdu)
2045  *      free(inparam.apdu.apdu);
2046  *
2047  * msg("rt = [%d]", rt);
2048  * if (rt == 0) {
2049  *      msg("outparam.apdu_resp.apdu_resp_len[%d]", outparam.apdu_resp.apdu_resp_len);
2050  *      if (outparam.apdu_resp.apdu_resp_len) {
2051  *              for (i = 0; i < outparam.apdu_resp.apdu_resp_len; i++)
2052  *                      msg("[%d]`s byte is [0x%x]", i, outparam.apdu_resp.apdu_resp[i]);
2053  *      }
2054  * }
2055  * @endcode
2056  *
2057  * @remarks None
2058  *
2059  */
2060 /*================================================================================================*/
2061 int tel_request_sim_sync(TapiHandle *handle, TelSimTapiOperation_t op_type, TelSimRequestData_t *inparam, TelSimResponseData_t *outparam);
2062
2063 /*
2064  * @brief  This API provides asynchronous call interface over some operations (refer to @param [in] op_type)
2065  *
2066  * @par Sync (or) Async:
2067  * This is an Asynchronous API.
2068  *
2069  * @par Important Notes:
2070  * - None
2071  *
2072  * @warning
2073  * - None.
2074  *
2075  * @param [in] handle
2076  * - handle from tel_init().
2077  *
2078  * @param [in] op_type
2079  * operation type to do what caller want.
2080  * - TAPI_SIM_GET_INIT_STATUS
2081  * - TAPI_SIM_GET_CARD_TYPE
2082  * - TAPI_SIM_GET_IMSI
2083  * - TAPI_SIM_GET_ECC
2084  * - TAPI_SIM_GET_ICCID
2085  * - TAPI_SIM_GET_SPN
2086  * - TAPI_SIM_GET_CPHS_NET_NAME
2087  * - TAPI_SIM_TRANSFER_APDU
2088  * - TAPI_SIM_GET_ATR
2089  * - ( below are not supported. )
2090  * - TAPI_SIM_GET_LANGUAGE
2091  * - TAPI_SIM_SET_LANGUAGE
2092  * - TAPI_SIM_GET_CALL_FORWARDING
2093  * - TAPI_SIM_SET_CALL_FORWARDING
2094  * - TAPI_SIM_GET_MESSAGE_WAITING
2095  * - TAPI_SIM_SET_MESSAGE_WAITING
2096  * - TAPI_SIM_GET_MAILBOX
2097  * - TAPI_SIM_SET_MAILBOX
2098  * - TAPI_SIM_GET_CPHS_INFO
2099  * - TAPI_SIM_GET_SVCT
2100  * - TAPI_SIM_GET_MSISDN
2101  * - TAPI_SIM_GET_OPLMWACT
2102  * - TAPI_SIM_AUTHENTICATION
2103  * - TAPI_SIM_VERIFY_SEC
2104  * - TAPI_SIM_VERIFY_PUK
2105  * - TAPI_SIM_CHANGE_PIN
2106  * - TAPI_SIM_DISABLE_FACILITY
2107  * - TAPI_SIM_ENABLE_FACILITY
2108  * - TAPI_SIM_GET_FACILITY
2109  * - TAPI_SIM_GET_LOCK_INFO
2110  *
2111  * @param [in] inparam
2112  * input parameter of union type. caller should fill when it is needed as below.
2113  * - TAPI_SIM_GET_INIT_STATUS   : (not needed)
2114  * - TAPI_SIM_GET_CARD_TYPE             : (not needed)
2115  * - TAPI_SIM_GET_IMSI                  : (not needed)
2116  * - TAPI_SIM_GET_ECC                   : (not needed)
2117  * - TAPI_SIM_GET_ICCID                 : (not needed)
2118  * - TAPI_SIM_GET_SPN                   : (not needed)
2119  * - TAPI_SIM_GET_CPHS_NET_NAME : (not needed)
2120  * - TAPI_SIM_TRANSFER_APDU             : TelSimApdu_t
2121  * - TAPI_SIM_GET_ATR                   : (not needed)
2122
2123  * @param [in] callback
2124  * - To register callback function for result.
2125  *
2126  * @param [in] user_data
2127  * - user_data for user specification.
2128  *
2129  * @par Async Response Message: *
2130  * Asynchronous return status is indicated by #TelSimAccessResult_t.
2131  * Asynchronous response data is #TelSimResponseData_t union type. TAPI returns what caller want.
2132  * - TAPI_SIM_GET_INIT_STATUS   : TelSimInitInfo_t
2133  * - TAPI_SIM_GET_CARD_TYPE             : TelSimCardType_t
2134  * - TAPI_SIM_GET_IMSI                  : TelSimImsiInfo_t
2135  * - TAPI_SIM_GET_ECC                   : TelSimEccList_t
2136  * - TAPI_SIM_GET_ICCID                 : TelSimIccIdInfo_t
2137  * - TAPI_SIM_GET_SPN                   : TelSimSpn_t
2138  * - TAPI_SIM_GET_CPHS_NET_NAME : TelSimCphsNetName_t
2139  * - TAPI_SIM_TRANSFER_APDU             : TelSimApduResp_t
2140  * - TAPI_SIM_GET_ATR                   : TelSimAtrResp_t
2141  *
2142  * @pre
2143  *  - None.
2144  *
2145  * @post
2146  *  - None.
2147  *
2148  * @return Return Type (int)
2149  * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS )  - indicating that the operation has completed successfully.
2150  * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
2151  * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
2152  *
2153  * @par Prospective Clients:
2154  * External Apps.
2155  *
2156  * @see None
2157  *
2158  * @code (for example, tel_req_sim_apdu())
2159  * #include <ITapiSim.h>
2160  * int rt = 0;
2161  * TelRequestData_t inparam;
2162  * TapiHandle *handle;  // Handle given by tel_init()
2163  * unsigned char apdu[5] = { 0x00, 0x70, 0x00, 0x00, 0x00};
2164  * memset (&inparam, 0, sizeof(TelRequestData_t));
2165  *
2166  * inparam.apdu.apdu_len = 5;
2167  * inparam.apdu.apdu = (unsigned char*)malloc(5);
2168  * memcpy (inparam.apdu.apdu, apdu, inparam.apdu.apdu_len);
2169  *
2170  * rt = tel_request_sim_async(handle, TAPI_SIM_TRANSFER_APDU, &inparam, on_sim_call_async, NULL);
2171  * if(inparam.apdu.apdu)
2172  *      free(inparam.apdu.apdu);
2173  *      }
2174  * }
2175  *
2176  * void on_sim_call_async (TapiHandle *handle, int result, void *data,
2177  *              void *user_data)
2178  * {
2179  *              TelSimAccessResult_t access_rt = result;
2180  *              TelSimResponseData_t *resp = data;
2181  *              int i = 0;
2182  *
2183  *              msg("tel_request_sim_async() response received");
2184  *              msg("access_rt[%d]", access_rt);
2185  *
2186  *              if (access_rt == 0) {
2187  *                      msg("apdu_resp_len[%d]", resp->apdu_resp.apdu_resp_len);
2188  *                      if (resp->apdu_resp.apdu_resp_len) {
2189  *                              for (i = 0; i < resp->apdu_resp.apdu_resp_len; i++)
2190  *                                      msg("[%d]`s byte is [0x%x]", i, resp->apdu_resp.apdu_resp[i]);
2191  *                      }
2192  *              }
2193  * }
2194  *
2195  * @endcode
2196  *
2197  * @remarks None
2198  *
2199  */
2200 /*================================================================================================*/
2201 int tel_request_sim_async(TapiHandle *handle, TelSimTapiOperation_t op_type, TelSimRequestData_t *inparam, tapi_response_cb callback, void *user_data);
2202
2203 #ifdef __cplusplus
2204 }
2205 #endif
2206
2207 #endif /* _ITAPI_SIM_H_ */
2208
2209 /**
2210 * @}
2211 */