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.\n
  30       It contains a sample set of function prototypes that would be required by applications.
  31
  32 */
  33
  34 #ifndef _ITAPI_SIM_H_
  35 #define _ITAPI_SIM_H_
  36
  37 #include <tapi_common.h>
  38 #include <TelErr.h>
  39 #include <TelSim.h>
  40 #include <TelDefines.h>
  41
  42 #ifdef __cplusplus
  43 extern "C"
  44 {
  45 #endif
  46
  47 /**
  48 * @brief  This API is used to get SIM Card Initialization status and SIM Card Identification.
  49 * Most of modules which require SIM data should check SIM status before using it definitely.
  50  *
  51 * @par Sync (or) Async:
  52 * This is a Synchronous API.
  53 *
  54 * @par Important Notes:
  55 * - Card Identification value is available in TAPI_SIM_STATUS_SIM_INIT_COMPLETED case only.
  56 *
  57 * @warning
  58 * - None.
  59 *
  60  * @param [in] handle
  61  * - handle from tel_init().
  62  *
  63 * @param [out] sim_status
  64 * - This parameter returns SIM initialization status from Telephony server boot up time.
  65 * First, You can find sim existance if returned value are not in TAPI_SIM_STATUS_CARD_NOT_PRESENT and TAPI_SIM_STATUS_CARD_REMOVED.
  66 *
  67 * @param [out] card_changed
  68 * - This parameter returns sim card identification value when sim_status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED.
  69 * - card_changed value just present whether current inserted SIM card differs with previous SIM or not.
  70 *
  71 * @par Async Response Message:
  72 * - None
  73 *
  74 * @pre
  75 *  - None.
  76 *
  77 * @post
  78 *  - None.
  79 *
  80 * @return Return Type (int)
  81 * - Integer '0' ( same with TAPI_API_SUCCESS ) - indicating that the operation has completed successfully. \n
  82 * - Negative integer : it provides an error code (Refer #TapiResult_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 *
  96 * // GET SIM INIT INFORMATION
  97 * err_code = tel_get_sim_init_info(&status, &b_card_changed);
  98 *
  99 * @endcode
 100 *
 101 * @remarks None
 102 *
 103 */
 104 /*================================================================================================*/
 105 int tel_get_sim_init_info(TapiHandle *handle, TelSimCardStatus_t *sim_status, int *card_changed);
 106
 107 /**
 108  * @brief  This function is a synchronous API which gets the Card Type whether Card is a SIM or a USIM.
 109  *
 110  * @par Sync (or) Async:
 111  * This is a synchronous function.
 112  *
 113  * @par Important Notes:
 114  * - None
 115  *
 116  * @warning
 117  * - None.
 118  *
 119  * @param [in] handle
 120  * - handle from tel_init().
 121  *
 122  * @param [out] card_type
 123  * This parameter returns the SIM card type information like whether it is GSM SIM card or USIM or it is of unknown type.
 124  *
 125  *  - TAPI_SIM_CARD_TYPE_UNKNOWN
 126  *  - TAPI_SIM_CARD_TYPE_GSM
 127  *  - TAPI_SIM_CARD_TYPE_USIM
 128  *
 129  * @par Async Response Message:
 130  * - None
 131  *
 132  * @pre
 133  *  - None.
 134  *
 135  * @post
 136  *  - None.
 137  *
 138  * @return Return Type (int) \n
 139  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 140  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 141  *
 142  * @par Prospective Clients:
 143  * External Apps.
 144  *
 145  * @see None
 146  *
 147  * @code
 148  * #include <ITapiSim.h>
 149  * int err_code = 0;
 150  * TelSimCardType_t cardInfo; //unkwon, sim(normally gsm), usim(normally umts)
 151  * err_code = tel_get_sim_type(&cardInfo);
 152  *
 153  * @endcode
 154  *
 155  * @remarks None
 156  *
 157  */
 158 /*================================================================================================*/
 159 int tel_get_sim_type(TapiHandle *handle, TelSimCardType_t *card_type);
 160
 161 /**
 162  * @brief  This function is a synchronous API gets the IMSI information.
 163  *
 164  * @par Sync (or) Async:
 165  * This is a synchronous function.
 166  *
 167  * @par Important Notes:
 168  * - IMSI value is the value that security needs.
 169  *
 170  * @warning
 171  * - None.
 172  *
 173  * @param [in] handle
 174  * - handle from tel_init().
 175  *
 176  * @param [out] imsi
 177  * This parameter returns the IMSI information. Refer #TelSimImsiInfo_t
 178  *
 179  * @par Async Response Message:
 180  * - None
 181  *
 182  * @pre
 183  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 184  *  - None.
 185  *
 186  * @post
 187  *  - None.
 188  *
 189  * @return Return Type (int) \n
 190  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 191  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 192  *
 193  * @par Prospective Clients:
 194  * External Apps.
 195  *
 196  * @see None
 197  *
 198  * @code
 199  * #include <ITapiSim.h>
 200  * int err_code = 0;
 201  * TelSimImsiInfo_t sim_imsi_info; // mcc, mnc, msisdn
 202  * err_code = tel_get_sim_imsi(&sim_imsi_info);
 203  * @endcode
 204  *
 205  * @remarks None
 206  *
 207  */
 208 /*================================================================================================*/
 209 int tel_get_sim_imsi(TapiHandle *handle, TelSimImsiInfo_t *imsi);
 210
 211 /**
 212  * @brief  This function is a synchronous API used to get ECC(SIM) or UECC(USIM) data.
 213  *
 214  * @par Sync (or) Async:
 215  * This is a synchronous function.
 216  *
 217  * @par Important Notes:
 218  * - None
 219  *
 220  * @warning
 221  * - None.
 222  *
 223  * @param [in] handle
 224  * - handle from tel_init().
 225  *
 226  * @param [out] ecc
 227  * - This parameter returns
 228  *              the SIM emergency call code information like ecc length, service type etc
 229  *              and number of ECC records.
 230  *
 231  * @par Async Response Message:
 232  * - None
 233  *
 234  * @pre
 235  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 236  *  - None.
 237  *
 238  * @post
 239  *  - None.
 240  *
 241  * @return Return Type (int) \n
 242  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 243  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 244  *
 245  * @par Prospective Clients:
 246  * External Apps.
 247  *
 248  * @see None
 249  *
 250  * @code
 251  * #include <ITapiSim.h>
 252  * int ecc_rec_count = 0; // count in sim card
 253  * int err_code = 0;
 254  * TelSimEccData_t ecc_info = {{{0,}}};
 255  * err_code = tel_get_sim_ecc(&ecc_info, &ecc_rec_count);
 256  * @endcode
 257  *
 258  * @remarks None
 259  *
 260  */
 261 /*================================================================================================*/
 262 int tel_get_sim_ecc(TapiHandle *handle, TelSimEccList_t *ecc);
 263
 264 /**
 265  * @brief  This function is a synchronous API gets a Unique identification number of the (U)ICC.
 266  * ICC means Integrated Circuit Card.
 267  *
 268  * @par Sync (or) Async:
 269  * This is a synchronous function.
 270  *
 271  * @par Important Notes:
 272  * - IC Card number value is the value that security needs.
 273  *
 274  * @warning
 275  * - None.
 276  *
 277  * @param [in] handle
 278  * - handle from tel_init().
 279  *
 280  * @param [in] callback
 281  * - To register callback function for result.
 282  *
 283  * @param [in] user_data
 284  * - user_data for user specification.
 285  *
 286  * @par Async Response Message:
 287  * - None
 288  *
 289  * @pre
 290  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 291  *  - None.
 292  *
 293  * @post
 294  *  - None.
 295  *
 296  * @return Return Type (int) \n
 297  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 298  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 299  *
 300  * @par Prospective Clients:
 301  * External Apps.
 302  *
 303  * @see None
 304  *
 305  * @code
 306  * #include <ITapiSim.h>
 307  * int err_code = 0;
 308  * TelSimIccIdInfo_t icc_data; // this struct consists of number length and number.
 309  * err_code = tel_get_sim_iccid(&icc_data);
 310  * @endcode
 311  *
 312  * @remarks None
 313  *
 314  */
 315 /*================================================================================================*/
 316 int tel_get_sim_iccid(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 317
 318 /**
 319  * @brief  This API is used to get the language preference(indication) information.
 320  *
 321  * @par Sync (or) Async:
 322  * This is a synchronous function.
 323  *
 324  * @par Important Notes:
 325  * - None
 326  *
 327  * @warning
 328  * - None.
 329  *
 330  * @param [in] handle
 331  * - handle from tel_init().
 332  *
 333  * @param [in] callback
 334  * - To register callback function for result.
 335  *
 336  * @param [in] user_data
 337  * - user_data for user specification.
 338  *
 339  * @par Async Response Message:
 340  * - None
 341  *
 342  * @pre
 343  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 344  *  - None.
 345  *
 346  * @post
 347  *  - None.
 348  *
 349  * @return Return Type (int) \n
 350  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 351  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 352  *
 353  * @par Prospective Clients:
 354  * External Apps.
 355  *
 356  * @see None
 357  *
 358  * @code
 359  * #include <ITapiSim.h>
 360  * int err_code = 0;
 361  * TelSimLanguageInfo_t li_info = {0,};
 362  * err_code = tel_get_sim_language(&li_info); // you can find language info with li_info variable
 363  * @endcode
 364  *
 365  * @remarks None
 366  *
 367  */
 368 /*================================================================================================*/
 369 int tel_get_sim_language(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 370
 371
 372 /**
 373  * @brief  This API is used to update the language preference information to SIM card.
 374  *
 375  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 376  * However it just means that the API request has been transfered to the CP successfully.
 377  * The actual operation result is being delivered in the corresponding event asynchronously.
 378  *
 379  * @par Sync (or) Async:
 380  * This is a Asynchronous function.
 381  *
 382  * @par Important Notes:
 383  * - This function update SIM Language information directly and can effect device language setting. Use carefully.
 384  *
 385  * @warning
 386  * - None.
 387  *
 388  * @param [in] handle
 389  * - handle from tel_init().
 390  *
 391  * @param [in] language
 392  * This parameter returns the language preference information.
 393  *
 394  * @param [in] callback
 395  * - To register callback function for result.
 396  *
 397  * @param [in] user_data
 398  * - user_data for user specification.
 399  *
 400  * @par Async Response Message:
 401  * The event associated is TAPI_EVENT_SIM_SET_LANGUAGE_CNF.
 402  * Asynchronous return status is indicated by #TelSimAccessResult_t.
 403  *
 404  * @pre
 405  *  - A dbus connection is established with #tel_init
 406  *  - The application name is registered with #tel_register_app_name
 407  *  - The application is registered events to listen asynchronous response with #tel_register_event
 408  *  - A event loop is running to listen events
 409  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 410  *  - None.
 411  *
 412  * @post
 413  *  - None.
 414  *
 415  * @return Return Type (int) \n
 416  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 417  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 418  *
 419  * @par Prospective Clients:
 420  * External Apps.
 421  *
 422  * @see None
 423  *
 424  * @code
 425  * #include <ITapiSim.h>
 426  * int err_code = 0;
 427  * int request_id = 0;
 428  * TelSimLanguagePreferenceCode_t language = 0x00; //init
 429  * language = TAPI_SIM_LP_ENGLISH; //language value
 430  * err_code = tel_set_sim_language(language, &request_id);
 431  * @endcode
 432  *
 433  * @remarks None
 434  *
 435  */
 436 /*================================================================================================*/
 437 int tel_set_sim_language(TapiHandle *handle, TelSimLanguagePreferenceCode_t language, tapi_response_cb callback, void *user_data);
 438
 439 /**
 440  * @brief  This API is used to get the SIM Call forwarding indication related data(EF-CFIS and CPHS case).
 441  * this data is required for Call forwarding related functionality in handset.
 442  *
 443  * @par Sync (or) Async:
 444  * This is a synchronous function.
 445  *
 446  * @par Important Notes:
 447  * - None
 448  *
 449  * @warning
 450  * - None
 451  *
 452  * @param [in] handle
 453  * - handle from tel_init().
 454  *
 455  * @param [in] callback
 456  * - To register callback function for result.
 457  *
 458  * @param [in] user_data
 459  * - user_data for user specification.
 460  *
 461  * @par Async Response Message:
 462  * - None
 463  *
 464  * @pre
 465  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 466  *  - None
 467  *
 468  * @post
 469  *  - None
 470  *
 471  * @return Return Type (int) \n
 472  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 473  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 474  *
 475  * @par Prospective Clients:
 476  * External Apps
 477  *
 478  * @see None
 479  *
 480  * @code
 481  * #include <ITapiSim.h>
 482  * TelSimCallForwarding_s cf_data;
 483  * TapiResult_t err_code = 0;
 484  * err_code = tel_get_sim_callforwarding_info(&cf_data);
 485  * if(err_code == TAPI_API_SUCCESS) {
 486  *   if(cf_data.b_cphs) { //b_cphs means current SIM is for CPHS or not.
 487  *     printf("Current SIM is CPHS");
 488  *   } else {
 489  *     printf("Current SIM is not CPHS but 3GPP");
 490  *   }
 491  * } else {
 492  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
 493  * }
 494  * @endcode
 495  *
 496  * @remarks None
 497  *
 498  */
 499 /*================================================================================================*/
 500 int tel_get_sim_callforwarding_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 501
 502 int tel_set_sim_callforwarding_info(TapiHandle *handle, TelSimCallForwardingReq_t *req_cf, tapi_response_cb callback, void *user_data);
 503
 504 /**
 505  * @brief  This API is used to get the SIM message waiting indication related data(EF-MWIS and CPHS case).
 506  * this data is required for Message waiting related functionality in handset.
 507  *
 508  * @par Sync (or) Async:
 509  * This is a synchronous function.
 510  *
 511  * @par Important Notes:
 512  * - None
 513  *
 514  * @warning
 515  * - None
 516  *
 517  * @param [in] handle
 518  * - handle from tel_init().
 519  *
 520  * @param [in] callback
 521  * - To register callback function for result.
 522  *
 523  * @param [in] user_data
 524  * - user_data for user specification.
 525  *
 526  * @par Async Response Message:
 527  * - None
 528  *
 529  * @pre
 530  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 531  *  - None
 532  *
 533  * @post
 534  *  - None
 535  *
 536  * @return Return Type (int) \n
 537  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 538  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 539  *
 540  * @par Prospective Clients:
 541  * External Apps
 542  *
 543  * @see None
 544  *
 545  * @code
 546  * #include <ITapiSim.h>
 547  * TelSimMessageWaiting_s mw_data;
 548  * TapiResult_t err_code = 0;
 549  * err_code = tel_get_sim_messagewaiting_info(&mw_data);
 550  * if(err_code == TAPI_API_SUCCESS) {
 551  *   if(mw_data.b_cphs) { //b_cphs means current SIM is for CPHS or not.
 552  *     printf("Current SIM is CPHS");
 553  *   } else {
 554  *     printf("Current SIM is not CPHS but 3GPP");
 555  *   }
 556  * } else {
 557  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
 558  * }
 559  * @endcode
 560  *
 561  * @remarks None
 562  *
 563  */
 564 /*================================================================================================*/
 565 int tel_get_sim_messagewaiting_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 566
 567 int tel_set_sim_messagewaiting_info(TapiHandle *handle, TelSimMessageWaitingReq_t *req_mw, tapi_response_cb callback, void *user_data);
 568
 569 /**
 570  * @brief  This API is used to get the SIM mailbox related data(EF-MBDN, MBDI and CPHS case).
 571  * this data is required for Mailbox related functionality in handset.
 572  *
 573  * @par Sync (or) Async:
 574  * This is a synchronous function.
 575  *
 576  * @par Important Notes:
 577  * - None
 578  *
 579  * @warning
 580  * - None.
 581  *
 582  * @param [in] handle
 583  * - handle from tel_init().
 584  *
 585  * @param [in] callback
 586  * - To register callback function for result.
 587  *
 588  * @param [in] user_data
 589  * - user_data for user specification.
 590  *
 591  * @par Async Response Message:
 592  * - None
 593  *
 594  * @pre
 595  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 596  *  - None.
 597  *
 598  * @post
 599  *  - None.
 600  *
 601  * @return Return Type (int) \n
 602  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 603  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 604  *
 605  * @par Prospective Clients:
 606  * External Apps.
 607  *
 608  * @see None
 609  *
 610  * @code
 611  * #include <ITapiSim.h>
 612  * TelSimMailboxNumbers_s mbox;
 613  * TapiResult_t err_code = 0;
 614  * err_code = tel_get_sim_mailbox_info(&mbox);
 615  * if(err_code == TAPI_API_SUCCESS) {
 616  *   if(mbox.b_cphs) { //b_cphs means current SIM is for CPHS or not.
 617  *     printf("Current SIM is CPHS");
 618  *   } else {
 619  *     printf("Current SIM is not CPHS but 3GPP");
 620  *   }
 621  * } else {
 622  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
 623  * }
 624  * @endcode
 625  *
 626  * @remarks None
 627  *
 628  */
 629 /*================================================================================================*/
 630 int tel_get_sim_mailbox_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 631
 632 int tel_set_sim_mailbox_info(TapiHandle *handle, TelSimMailBoxNumber_t *req_mb, tapi_response_cb callback, void *user_data);
 633
 634 /**
 635  * @brief  This API is used to get the SIM CPHS specific data.
 636  * this data is required for CPHS related functionality in handset.
 637  *
 638  * @par Sync (or) Async:
 639  * This is an Synchronous API.
 640  *
 641  * @par Important Notes:
 642  * - None
 643  *
 644  * @warning
 645  * - None
 646  *
 647  * @param [in] handle
 648  * - handle from tel_init().
 649  *
 650  * @param [in] callback
 651  * - To register callback function for result.
 652  *
 653  * @param [in] user_data
 654  * - user_data for user specification.
 655  *
 656  * @par Async Response Message:
 657  * - None
 658  *
 659  * @pre
 660  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 661  *
 662  * @post
 663  *  - None
 664  *
 665  * @return Return Type (int) \n
 666  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 667  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 668  *
 669  * @par Prospective Clients:
 670  * External Apps
 671  *
 672  * @see None
 673  *
 674  * @code
 675  * #include <ITapiSim.h>
 676  * TelSimCphsLocalInfo_t cphs_data;
 677  * TapiResult_t err_code = 0;
 678  * err_code = tel_get_sim_cphs_info(&cphs_data);
 679  * if(err_code == TAPI_API_SUCCESS) {
 680  *   if(cphs_data.b_used) { //b_used means current SIM is for CPHS or not.
 681  *     printf("Current SIM is CPHS");
 682  *   } else {
 683  *     printf("Current SIM is not CPHS but 3GPP");
 684  *   }
 685  * } else {
 686  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
 687  * }
 688  * @endcode
 689  *
 690  * @remarks None
 691  *
 692  */
 693 /*================================================================================================*/
 694 int tel_get_sim_cphs_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 695
 696 /**
 697  * @brief  This API is used to get the SIM MSISDN data. Regarding 3GPP specification, Current value is optional.
 698  *
 699  * @par Sync (or) Async:
 700  * This is an Synchronous API.
 701  *
 702  * @par Important Notes:
 703  * - None
 704  *
 705  * @warning
 706  * - None
 707  *
 708  * @param [in] handle
 709  * - handle from tel_init().
 710  *
 711  * @param [in] callback
 712  * - To register callback function for result.
 713  *
 714  * @param [in] user_data
 715  * - user_data for user specification.
 716  *
 717  * @par Async Response Message:
 718  * - None
 719  *
 720  * @pre
 721  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 722  *
 723  * @post
 724  *  - None
 725  *
 726  * @return Return Type (int) \n
 727  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 728  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 729  *
 730  * @par Prospective Clients:
 731  * External Apps
 732  *
 733  * @see None
 734  *
 735  * @code
 736  * #include <ITapiSim.h>
 737  * TelSimSubscriberInfo_t msisdn;
 738  * TapiResult_t err_code = 0;
 739  * err_code = tel_get_sim_msisdn(&msisdn);
 740  * if(err_code == TAPI_API_SUCCESS)
 741  * {
 742  *       printf(" ============================================");
 743  *       printf("name[%s]",msisdn.name);
 744  *       printf("num[%s]",msisdn.num);
 745  *       if(msisdn.name == '\0';) //If current SIM does not have, Null string will be returned.
 746  *               printf("name is null string");
 747  *
 748  *       if(msisdn.num == '\0';) //If current SIM does not have, Null string will be returned.
 749  *               printf("number is null string");
 750  * }
 751  * else
 752  * {
 753  *       printf("TAPI API FAIL: Error Code [0x%x]",err_code);
 754  * }
 755  *
 756  * @endcode
 757  *
 758  * @remarks None
 759  *
 760  */
 761 /*================================================================================================*/
 762 int tel_get_sim_msisdn(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 763
 764 /**
 765  * @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.
 766  *
 767  * @par Sync (or) Async:
 768  * This is an Synchronous API.
 769  *
 770  * @par Important Notes:
 771  * - None
 772  *
 773  * @warning
 774  * - None
 775  *
 776  * @param [in] handle
 777  * - handle from tel_init().
 778  *
 779  * @param [in] callback
 780  * - To register callback function for result.
 781  *
 782  * @param [in] user_data
 783  * - user_data for user specification.
 784  *
 785  * @par Async Response Message:
 786  * - None
 787  *
 788  * @pre
 789  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 790  *
 791  * @post
 792  *  - None
 793  *
 794  * @return Return Type (int) \n
 795  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 796  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 797  *
 798  * @par Prospective Clients:
 799  * External Apps
 800  *
 801  * @see None
 802  *
 803  * @code
 804  *
 805  * @endcode
 806  *
 807  * @remarks None
 808  *
 809  */
 810 /*================================================================================================*/
 811 int tel_get_sim_oplmnwact(TapiHandle *handle, tapi_response_cb callback, void *user_data);
 812
 813 /**
 814  * @brief  This API is used to get the SIM SPN data. Regarding 3GPP specification, Current value is optional.
 815  *
 816  * @par Sync (or) Async:
 817  * This is an Synchronous API.
 818  *
 819  * @par Important Notes:
 820  * - None
 821  *
 822  * @warning
 823  * - None
 824  *
 825  * @param [in] handle
 826  * - handle from tel_init().
 827  *
 828  * @param [in] callback
 829  * - To register callback function for result.
 830  *
 831  * @param [in] user_data
 832  * - user_data for user specification.
 833  *
 834  * @par Async Response Message:
 835  * - None
 836  *
 837  * @pre
 838  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 839  *
 840  * @post
 841  *  - None
 842  *
 843  * @return Return Type (int) \n
 844  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 845  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 846  *
 847  * @par Prospective Clients:
 848  * External Apps
 849  *
 850  * @see None
 851  *
 852  * @code
 853  *
 854  * @endcode
 855  *
 856  * @remarks None
 857  *
 858  */
 859 /*================================================================================================*/
 860 int tel_get_sim_spn(TapiHandle *handle, tapi_response_cb callback,      void *user_data);
 861
 862 /**
 863  * @brief  This API is used to get the SIM CPHS NETNAME data.
 864  *
 865  * @par Sync (or) Async:
 866  * This is an Synchronous API.
 867  *
 868  * @par Important Notes:
 869  * - None
 870  *
 871  * @warning
 872  * - None
 873  *
 874  * @param [in] handle
 875  * - handle from tel_init().
 876  *
 877  * @param [in] callback
 878  * - To register callback function for result.
 879  *
 880  * @param [in] user_data
 881  * - user_data for user specification.
 882  *
 883  * @par Async Response Message:
 884  * - None
 885  *
 886  * @pre
 887  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 888  *
 889  * @post
 890  *  - None
 891  *
 892  * @return Return Type (int) \n
 893  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 894  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 895  *
 896  * @par Prospective Clients:
 897  * External Apps
 898  *
 899  * @see None
 900  *
 901  * @code
 902  *
 903  * @endcode
 904  *
 905  * @remarks None
 906  *
 907  */
 908 /*================================================================================================*/
 909 int tel_get_sim_cphs_netname(TapiHandle *handle, tapi_response_cb callback,     void *user_data);
 910
 911 /**
 912  * @brief  This API is used to execute the authentication procedure by using SIM.
 913  *
 914  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 915  * However it just means that the API request has been transfered to the CP successfully.
 916  * The actual operation result is being delivered in the corresponding event asynchronously.
 917  * This function supports IMS, 3G and GSM authentication.
 918  *
 919  * @par Sync (or) Async:
 920  * This is an Asynchronous API.
 921  *
 922  * @par Important Notes:
 923  * -NONE
 924  *
 925  * @warning
 926  * - None.
 927  *
 928  * @param [in] handle
 929  * - handle from tel_init().
 930  *
 931  * @param[in] authentication_data
 932  * - This input has the authentication code to be validated by ISIM,3G and GSM application in the SIM card. #TelSimAuthenticationData_t
 933  *
 934  * @param [in] callback
 935  * - To register callback function for result.
 936  *
 937  * @param [in] user_data
 938  * - user_data for user specification.
 939  *
 940  * @par Async Response Message:
 941  * -The event associated is TAPI_SIM_EVENT_AUTHENTICATION_CNF  and the event data is #TelSimAuthenticationResponse_t.
 942  * Asynchronous return status is indicated by #TelSimAccessResult_t.
 943  *
 944  * @pre
 945  *  - A dbus connection is established with #tel_init
 946  *  - The application name is registered with #tel_register_app_name
 947  *  - The application is registered events to listen asynchronous response with #tel_register_event
 948  *  - A event loop is running to listen events
 949  *
 950  * @post
 951  *  - None.
 952  *
 953  * @return Return Type (int) \n
 954  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 955  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 956  *
 957  * @par Prospective Clients:
 958  * External Apps.
 959  *
 960  * @see None
 961  *
 962  * @code
 963  * #include <ITapiSim.h>
 964  * int err_code = 0;
 965  * int request_id = 0;
 966  * TelSimAuthenticationData_t pAuthenticationData;
 967  * strcpy((char*)pAuthenticationData.rand_data, "username@operator.com"); //access data
 968  * pAuthenticationData.rand_length= strlen("username@operator.com");
 969  * strcpy((char*)pAuthenticationData.autn_data,  "+1-212-555-12345"); // auth data
 970  * pAuthenticationData.autn_length = strlen("+1-212-555-12345");
 971  * err_code = tel_req_sim_authentication(&pAuthenticationData,&request_id);
 972  * @endcode
 973  *
 974  * @remarks None
 975  *
 976  */
 977 /*================================================================================================*/
 978 int tel_req_sim_authentication(TapiHandle *handle, TelSimAuthenticationData_t *authentication_data, tapi_response_cb callback, void *user_data);
 979
 980
 981
 982 /**
 983  * @brief  This function performs PIN1/PIN2/SIM LOCK verification. This function performs PIN verification based on the pin type passed along with pin data.
 984  * PIN1 code : The SIM card has its own password is to check access permissions
 985  * SIM Lock code : Between Device and the SIM card using a SIM password is only available on certain handsets to be used to authorize.
 986  *
 987  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 988  * However it just means that the API request has been transfered to the CP successfully.
 989  * The actual operation result is being delivered in the corresponding event asynchronously.
 990  *
 991  * @par Sync (or) Async:
 992  * This is an Asynchronous API.
 993  *
 994  * @par Important Notes:
 995  * - 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.
 996  * - if pin status is PUK, you should use #tel_verify_sim_puks instead of this API.
 997  *
 998  * @warning
 999  * - None.
1000  *
1001  * @param [in] handle
1002  * - handle from tel_init().
1003  *
1004  * @param[in] pin_data
1005  * -PIN code, entered by the user. you should make all parameters.
1006  *
1007  * @param [in] callback
1008  * - To register callback function for result.
1009  *
1010  * @param [in] user_data
1011  * - user_data for user specification.
1012  *
1013  * @par Async Response Message:
1014  * The event associated is TAPI_EVENT_SIM_VERIFY_SEC_CNF  and the event data is #TelSimSecResult_t.
1015  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
1016  * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Verification successes.
1017  * If returned status is TAPI_SIM_PIN_INCORRECT_PASSWORD, Verification fails and you can check retry count by using event data  #TelSimSecResult_t.
1018  *
1019  * @pre
1020  *  - Initialize Dbus connection with #tel_init
1021  *  - Register caller's application name with #tel_register_app_name
1022  *  - Register telephony events to listen
1023  *  - A event loop is running to listen events
1024  * - This API is used when #TelSimCardStatus_t is TAPI_SIM_STATUS_SIM_PIN_REQUIRED or TAPI_SIM_STATUS_SIM_LOCK_REQUIRED on boot time.
1025  * - Currently there`s no proper scenario for PIN2 verification by using this API.
1026  *
1027  * @post
1028  *  - None.
1029  *
1030  * @return Return Type (int) \n
1031  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1032  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1033  *
1034  * @par Prospective Clients:
1035  * External Apps.
1036  *
1037  * @see None
1038  *
1039  * @code
1040  * #include <ITapiSim.h>
1041  *
1042  * int request_id = 0;
1043  * err_code = TAPI_API_SUCCESS; // 0
1044  * int length = TAPI_SIM_PIN_LENGTH+1;
1045  * char init_pin_val[length] ;
1046  *
1047  * strcpy(init_pin_val, PIN1_NORMAL);
1048  *
1049  * TelSimSecPw_t pin_data = {0,};
1050  *
1051  * pin_data.type = TAPI_SIM_PTYPE_PIN1;
1052  * pin_data.pw_len = strlen(init_pin_val);
1053  *
1054  * printf("pw_len[%d]", pin_data.pw_len);
1055  *
1056  * pin_data.pw = (char*)malloc(length);
1057  * memcpy(pin_data.pw,init_pin_val,length);
1058  *
1059  * err_code = tel_verifiy_sim_pins(&pin_data, &request_id);
1060  *
1061  * @endcode
1062  *
1063  * @remarks None
1064  *
1065  */
1066 /*================================================================================================*/
1067 int tel_verifiy_sim_pins(TapiHandle *handle, const TelSimSecPw_t *pin_data, tapi_response_cb callback, void *user_data);
1068
1069
1070 /**
1071  * @brief  This function performs unblock PIN1/PIN2 operation based on PUK information passed along with
1072  * unblock information entered by the user.
1073  * If you get sim card status(TAPI_SIM_STATUS_SIM_PUK_REQUIRED) by using #tel_get_sim_init_info on boot time
1074  * or (TAPI_SIM_PIN_STATUS_BLOCKED) by using #tel_get_sim_security_status after normal initialization for specific operation,
1075  * you may unblock PIN1/PIN2.
1076  *
1077  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1078  * However it just means that the API request has been transfered to the CP successfully.
1079  * The actual operation result is being delivered in the corresponding event asynchronously.
1080  *
1081  * @par Sync (or) Async:
1082  * This is an Asynchronous API.
1083  *
1084  * @par Important Notes:
1085  * - Based on Pin status (PIN1/PIN2) is blocked, an unsolicited event TAPI_EVENT_SIM_STATUS_IND
1086  * is published to Applications on boot time also.
1087  *
1088  * @warning
1089  * - If you fail to unblock PIN til given retry count, Your SIM card be permanent block status.
1090  *
1091  * @param [in] handle
1092  * - handle from tel_init().
1093  *
1094  * @param[in] puk_data
1095  * -Specifies unblocking PIN password #TelSimSecPw_t
1096  *
1097  * @param[in] new_pin_data
1098  * -Specifies PIN password which you want to use after unblocking operation #TelSimSecPw_t
1099  *
1100  * @param [in] callback
1101  * - To register callback function for result.
1102  *
1103  * @param [in] user_data
1104  * - user_data for user specification.
1105  *
1106  * @par Async Response Message:
1107  * The event associated is TAPI_EVENT_SIM_VERIFY_PUK_CNF  and the event data is #TelSimSecResult_t.
1108  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
1109  * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Verification successes.
1110  * If returned status is TAPI_SIM_PUK_INCORRECT_PASSWORD, Verification fails and you can check retry count by using event data  #TelSimSecResult_t.
1111  *
1112  * @pre
1113  *  - Initialize Dbus connection with #tel_init
1114  *  - Register caller's application name with #tel_register_app_name
1115  *  - Register telephony events to listen
1116  *  - A event loop is running to listen events
1117  *  - 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.
1118  *
1119  * @post
1120  *  - After Success on unblocking for PIN1 or PIN2, each pin check facility is enabled even if previous facility is disabled.
1121  *
1122  * @return Return Type (int) \n
1123  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1124  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1125  *
1126  * @par Prospective Clients:
1127  * External Apps.
1128  *
1129  * @see None
1130  *
1131  * @code
1132  * #include <ITapiSim.h>
1133  *
1134  * int request_id = 0;
1135  * err_code = TAPI_API_SUCCESS; // 0
1136  * int length = TAPI_SIM_PIN_LENGTH+1;
1137  *
1138  * char init_pin_val[length];
1139  * char init_puk_val[length];
1140  *
1141  * strcpy(init_pin_val, PIN1_NORMAL);
1142  * strcpy(init_puk_val, PUK1_NORMAL);
1143  *
1144  * TelSimSecPw_t puk_data = {0,};
1145  * TelSimSecPw_t new_pin_data = {0,};
1146  *
1147  * puk_data.type = TAPI_SIM_PTYPE_PUK1;   // 0x00
1148  * puk_data.pw_len = length;
1149  * puk_data.pw_len = strlen(init_puk_val);
1150  * printf("pw_len[%d]", puk_data.pw_len);
1151  * memcpy(puk_data.pw,init_pin_val,length);
1152  *
1153  * new_pin_data.type = TAPI_SIM_PTYPE_PIN1;   // 0x00
1154  * new_pin_data.pw_len = strlen(init_pin_val);
1155  * printf("pw_len[%d]", new_pin_data.pw_len);
1156  * new_pin_data.pw = (char*)malloc(length);
1157  * memcpy(new_pin_data.pw,init_pin_val,length);
1158  *
1159  * err_code = tel_verify_sim_puks(&puk_data, &new_pin_data, &request_id);
1160  *
1161  * @endcode
1162  *
1163  * @remarks None
1164  *
1165  */
1166 /*================================================================================================*/
1167 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);
1168
1169
1170 /**
1171  * @brief  This function changes PIN1/PIN2 code based on the pin type passed along with old pin data and new pin data.
1172  *
1173  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1174  * However it just means that the API request has been transfered to the CP successfully.
1175  * The actual operation result is being delivered in the corresponding event asynchronously.
1176  *
1177  * @par Sync (or) Async:
1178  * This is an Asynchronous API.
1179  *
1180  * @par Important Notes:
1181  * - User should fill up pin type equally both old_pin and new_pin.
1182  *
1183  * @warning
1184  * - None.
1185  *
1186  * @param [in] handle
1187  * - handle from tel_init().
1188  *
1189  * @param[in] old_pin
1190  * -Old pin code, entered by the user. #TelSimSecPw_t
1191  *
1192  * @param[in] new_pin
1193  * -New pin code, entered by the user. #TelSimSecPw_t
1194  *
1195  * @param [in] callback
1196  * - To register callback function for result.
1197  *
1198  * @param [in] user_data
1199  * - user_data for user specification.
1200  *
1201  * @par Async Response Message:
1202  * The event associated is TAPI_EVENT_SIM_CHANGE_PINS_CNF  and the event data is #TelSimSecResult_t.
1203  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
1204  * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Change operation finish successfully.
1205  * If returned status is TAPI_SIM_PIN_INCORRECT_PASSWORD, Change operation fails and you can check retry count by using event data  #TelSimSecResult_t.
1206  *
1207  * @pre
1208  *  - Initialize Dbus connection with #tel_init
1209  *  - Register caller's application name with #tel_register_app_name
1210  *  - Register telephony events to listen
1211  *  - A event loop is running to listen events
1212  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1213  *  - PIN which user want to change check facility should be enabled.
1214  *
1215  * @post
1216  *  - None.
1217  *
1218  * @return Return Type (int) \n
1219  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1220  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1221  *
1222  * @par Prospective Clients:
1223  * External Apps.
1224  *
1225  * @see None
1226  *
1227  * @code
1228  * #include <ITapiSim.h>
1229  *
1230  * int request_id = 0;
1231  * err_code = TAPI_API_SUCCESS; // 0
1232  * int length = TAPI_SIM_PIN_LENGTH+1;
1233  * char init_old_pin_val[length] ;
1234  * char init_new_pin_val[length];
1235  *
1236  * memset(&init_old_pin_val, 0 , length);
1237  * memset(&init_new_pin_val, 0 , length);
1238  *
1239  * TelSimSecPw_t old_pin = {0,};
1240  * TelSimSecPw_t new_pin = {0,};
1241  *
1242  * strcpy(init_old_pin_val, PIN1_ORG);
1243  *
1244  * old_pin.type = TAPI_SIM_PTYPE_PIN1;
1245  * old_pin.pw_len = strlen(init_old_pin_val);
1246  * printf("pw_len[%d]", old_pin.pw_len);
1247  * old_pin.pw = (char*)malloc(length);
1248  * memcpy(old_pin.pw,init_old_pin_val,length);
1249  *
1250  * strcpy(init_new_pin_val, PIN1_NEW);
1251  *
1252  * new_pin.type = TAPI_SIM_PTYPE_PIN1;
1253  * new_pin.pw_len = strlen(init_new_pin_val);
1254  * printf("pw_len[%d]", new_pin.pw_len);
1255  * new_pin.pw = (char*)malloc(length);
1256  * memcpy(new_pin.pw,init_new_pin_val,length);
1257  *
1258  * err_code = tel_change_sim_pins(&old_pin, &new_pin, &request_id);
1259  *
1260  * @endcode
1261  *
1262  * @remarks None
1263  *
1264  */
1265 /*================================================================================================*/
1266 int tel_change_sim_pins(TapiHandle *handle, const TelSimSecPw_t *old_pin, const TelSimSecPw_t *new_pin, tapi_response_cb callback, void *user_data);
1267
1268 /**
1269  * @brief  This API is used to disable the SIM facility.
1270  *
1271  * @par Sync (or) Async:
1272  * This is an Asynchronous API.
1273  *
1274  * @par Important Notes:
1275  * - None
1276  *
1277  * @warning
1278  * - None.
1279  *
1280  * @param [in] handle
1281  * - handle from tel_init().
1282  *
1283  * @param[in] pw
1284  *  - a structure which contains facility type and password.
1285  *
1286  * @param [in] callback
1287  * - To register callback function for result.
1288  *
1289  * @param [in] user_data
1290  * - user_data for user specification.
1291  *
1292  * @par
1293  *
1294  * @pre
1295  *
1296  * @post
1297  *
1298  * @return Return Type (int) \n
1299  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1300  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1301  *
1302  * @par Prospective Clients:
1303  * External Apps.
1304  *
1305  * @see None
1306  *
1307  * @code
1308  *
1309  * @endcode
1310  *
1311  * @remarks None
1312  *
1313  */
1314 /*================================================================================================*/
1315 int tel_disable_sim_facility(TapiHandle *handle, TelSimFacilityPw_t *pw, tapi_response_cb callback, void *user_data);
1316
1317 /**
1318  * @brief  This API is used to enable the SIM facility.
1319  *
1320  * @par Sync (or) Async:
1321  * This is an Asynchronous API.
1322  *
1323  * @par Important Notes:
1324  * - None
1325  *
1326  * @warning
1327  * - None.
1328  *
1329  * @param [in] handle
1330  * - handle from tel_init().
1331  *
1332  * @param[in] pw
1333  *  - a structure which contains facility type and password.
1334  *
1335  * @param [in] callback
1336  * - To register callback function for result.
1337  *
1338  * @param [in] user_data
1339  * - user_data for user specification.
1340  *
1341  * @par
1342  *
1343  * @pre
1344  *
1345  * @post
1346  *
1347  * @return Return Type (int) \n
1348  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1349  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1350  *
1351  * @par Prospective Clients:
1352  * External Apps.
1353  *
1354  * @see None
1355  *
1356  * @code
1357  *
1358  * @endcode
1359  *
1360  * @remarks None
1361  *
1362  */
1363 /*================================================================================================*/
1364 int tel_enable_sim_facility(TapiHandle *handle, TelSimFacilityPw_t *pw, tapi_response_cb callback, void *user_data);
1365
1366
1367 /**
1368  * @brief  This API is used to get the SIM facility.
1369  *
1370  * @par Sync (or) Async:
1371  * This is an Asynchronous API.
1372  *
1373  * @par Important Notes:
1374  * - None
1375  *
1376  * @warning
1377  * - None.
1378  *
1379  * @param [in] handle
1380  * - handle from tel_init().
1381  *
1382  * @param[in] type
1383  *  - type of security lock type enum values.
1384  *
1385  * @param [in] callback
1386  * - To register callback function for result.
1387  *
1388  * @param [in] user_data
1389  * - user_data for user specification.
1390  *
1391  * @par
1392  *
1393  * @pre
1394  *
1395  * @post
1396  *
1397  * @return Return Type (int) \n
1398  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1399  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1400  *
1401  * @par Prospective Clients:
1402  * External Apps.
1403  *
1404  * @see None
1405  *
1406  * @code
1407  *
1408  * @endcode
1409  *
1410  * @remarks None
1411  *
1412  */
1413 /*================================================================================================*/
1414 int tel_get_sim_facility(TapiHandle *handle, TelSimLockType_t type, tapi_response_cb callback, void *user_data);
1415
1416 /**
1417  * @brief  This API is used to get the SIM LOCK TYPE info.
1418  *
1419  * @par Sync (or) Async:
1420  * This is an Asynchronous API.
1421  *
1422  * @par Important Notes:
1423  * - None
1424  *
1425  * @warning
1426  * - None.
1427  *
1428  * @param [in] handle
1429  * - handle from tel_init().
1430  *
1431  * @param[in] type
1432  *  - type of security lock type enum values.
1433  *
1434  * @param [in] callback
1435  * - To register callback function for result.
1436  *
1437  * @param [in] user_data
1438  * - user_data for user specification.
1439  *
1440  * @par
1441  *
1442  * @pre
1443  *
1444  * @post
1445  *
1446  * @return Return Type (int) \n
1447  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1448  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1449  *
1450  * @par Prospective Clients:
1451  * External Apps.
1452  *
1453  * @see None
1454  *
1455  * @code
1456  *
1457  * @endcode
1458  *
1459  * @remarks None
1460  *
1461  */
1462 /*================================================================================================*/
1463 int tel_get_sim_lock_info(TapiHandle *handle, TelSimLockType_t type, tapi_response_cb callback, void *user_data);
1464
1465
1466 /**
1467  * @brief  This function provides common interface for accessing SIM data based on USIM generic command in ETSI TS 102 221
1468  * and 3GPP TS 31.102 Characteristics of the Universal Subscriber Identity Module (USIM) application.
1469  * This API provides only interface to send APDU. User should know well APDU usage.
1470  *
1471  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1472  * However it just means that the API request has been transfered to the CP successfully.
1473  * The actual operation result is being delivered in the corresponding event asynchronously.
1474  *
1475  * @par Sync (or) Async:
1476  * This is an Asynchronous API.
1477  *
1478  * @par Important Notes:
1479  * - None
1480  *
1481  * @warning
1482  * - None.
1483  *
1484  * @param [in] handle
1485  * - handle from tel_init().
1486  *
1487  * @param[in] apdu_data
1488  *
1489  * @param [in] callback
1490  * - To register callback function for result.
1491  *
1492  * @param [in] user_data
1493  * - user_data for user specification.
1494  *
1495  * @par Async Response Message:
1496  * The event associated is TAPI_EVENT_SIM_APDU_CNF  and the event data is #TelSimApduResp_t.
1497  * Asynchronous return status is indicated by #TelSimAccessResult_t.
1498  *
1499  * @pre
1500  *  - A dbus connection is established with #tel_init
1501  *  - The application name is registered with #tel_register_app_name
1502  *  - The application is registered events to listen asynchronous response with #tel_register_event
1503  *  - A event loop is running to listen events
1504  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1505  *  - None.
1506  *
1507  * @post
1508  *  - None.
1509  *
1510  * @return Return Type (int) \n
1511  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1512  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1513  *
1514  * @par Prospective Clients:
1515  * External Apps.
1516  *
1517  * @see None
1518  *
1519  * @code
1520  * #include <ITapiSim.h>
1521  * int err_code =0;
1522  * int request_id = 0;
1523  * TelSimApdu_t apdu = {0,};
1524  * int tmp_apdu[5] = {0xa,5,6,7,8};
1525  * apdu.apdu_len = 5; //user should check
1526  * apdu.apdu = apdu;
1527  *
1528  * // REQUEST SIM ACCESS
1529  * err_code = tel_req_sim_apdu((const TelSimRSimReq_t*)&rsim, &request_id);
1530  * @endcode
1531  *
1532  * @remarks None
1533  *
1534  */
1535 /*================================================================================================*/
1536 int tel_req_sim_apdu(TapiHandle *handle, TelSimApdu_t* apdu_data, tapi_response_cb callback, void *user_data);
1537
1538
1539 /**
1540  * @brief  This function provides common interface to get SIM ATR(Answer To Reset) value.
1541  *
1542  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1543  * However it just means that the API request has been transfered to the CP successfully.
1544  * The actual operation result is being delivered in the corresponding event asynchronously.
1545  *
1546  * @par Sync (or) Async:
1547  * This is an Asynchronous API.
1548  *
1549  * @par Important Notes:
1550  * - None
1551  *
1552  * @warning
1553  * - None.
1554  *
1555  * @param [in] handle
1556  * - handle from tel_init().
1557  *
1558  * @param [in] callback
1559  * - To register callback function for result.
1560  *
1561  * @param [in] user_data
1562  * - user_data for user specification.
1563  *
1564  * @par Async Response Message:
1565  * The event associated is TAPI_EVENT_SIM_ATR_CNF  and the event data is #TelSimAtrResp_t.
1566  * Asynchronous return status is indicated by #TelSimAccessResult_t.
1567  *
1568  * @pre
1569  *  - A dbus connection is established with #tel_init
1570  *  - The application name is registered with #tel_register_app_name
1571  *  - The application is registered events to listen asynchronous response with #tel_register_event
1572  *  - A event loop is running to listen events
1573  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1574  *  - None.
1575  *
1576  * @post
1577  *  - None.
1578  *
1579  * @return Return Type (int) \n
1580  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1581  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1582  *
1583  * @par Prospective Clients:
1584  * External Apps.
1585  *
1586  * @see None
1587  *
1588  * @code
1589  * #include <ITapiSim.h>
1590  * int err_code =0;
1591  * int request_id = 0;
1592  *
1593  * // REQUEST SIM ATR
1594  * err_code = tel_req_sim_atr(&request_id);
1595  * @endcode
1596  *
1597  * @remarks None
1598  *
1599  */
1600 /*================================================================================================*/
1601 int tel_req_sim_atr(TapiHandle *handle, tapi_response_cb callback, void *user_data);
1602
1603 #ifdef __cplusplus
1604 }
1605 #endif
1606
1607 #endif  /* _ITAPI_SIM_H_ */
1608
1609 /**
1610 * @}
1611 */