include/tapi/ITapiSim.h

   1 /*
   2  * libslp-tapi
   3  *
   4  * Copyright (c) 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Ja-young Gu <jygu@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  */
  20
  21 /**
  22 * @open
  23 * @ingroup              TelephonyAPI
  24 * @addtogroup   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 <TelSim.h>
  38 #include <TelUtility.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 [out] sim_status
  60 * - This parameter returns SIM initialization status from Telephony server boot up time.
  61 * First, You can find sim existance if returned value are not in TAPI_SIM_STATUS_CARD_NOT_PRESENT and TAPI_SIM_STATUS_CARD_REMOVED.
  62 *
  63 * @param [out] card_changed
  64 * - This parameter returns sim card identification value when sim_status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED.
  65 * - card_changed value just present whether current inserted SIM card differs with previous SIM or not.
  66 *
  67 * @par Async Response Message:
  68 * - None
  69 *
  70 * @pre
  71 *  - None.
  72 *
  73 * @post
  74 *  - None.
  75 *
  76 * @return Return Type (int)
  77 * - Integer '0' ( same with TAPI_API_SUCCESS ) - indicating that the operation has completed successfully. \n
  78 * - Negative integer : it provides an error code (Refer #TapiResult_t)
  79 *
  80 * @par Prospective Clients:
  81 * External Apps.
  82 *
  83 * @see None
  84 *
  85 * @code
  86 * #include <ITapiSim.h>
  87 *
  88 * int err_code = TAPI_API_SUCCESS;
  89 * TelSimCardStatus_t status = 0x00;
  90 * int b_card_changed = 0;
  91 *
  92 * // GET SIM INIT INFORMATION
  93 * err_code = tel_get_sim_init_info(&status, &b_card_changed);
  94 *
  95 * @endcode
  96 *
  97 * @remarks None
  98 *
  99 */
 100 /*================================================================================================*/
 101 int tel_get_sim_init_info(TelSimCardStatus_t *sim_status, int *card_changed);
 102
 103
 104 /**
 105  * @brief  This function performs PIN1/PIN2/SIM LOCK verification. This function performs PIN verification based on the pin type passed along with pin data.
 106  * PIN1 code : The SIM card has its own password is to check access permissions
 107  * SIM Lock code : Between Device and the SIM card using a SIM password is only available on certain handsets to be used to authorize.
 108  *
 109  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 110  * However it just means that the API request has been transfered to the CP successfully.
 111  * The actual operation result is being delivered in the corresponding event asynchronously.
 112  *
 113  * @par Sync (or) Async:
 114  * This is an Asynchronous API.
 115  *
 116  * @par Important Notes:
 117  * - 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.
 118  * - if pin status is PUK, you should use #tel_verify_sim_puks instead of this API.
 119  *
 120  * @warning
 121  * - None.
 122  *
 123  * @param[in] pin_data
 124  * -PIN code, entered by the user. you should make all parameters.
 125  *
 126  * @param [out] req_id
 127  *   - Unique identifier for a particular request.
 128  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
 129  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
 130  *
 131  * @par Async Response Message:
 132  * The event associated is TAPI_EVENT_SIM_VERIFY_SEC_CNF  and the event data is #TelSimSecResult_t.
 133  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
 134  * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Verification successes.
 135  * If returned status is TAPI_SIM_PIN_INCORRECT_PASSWORD, Verification fails and you can check retry count by using event data  #TelSimSecResult_t.
 136  *
 137  * @pre
 138  *  - Initialize Dbus connection with #tel_init
 139  *  - Register caller's application name with #tel_register_app_name
 140  *  - Register telephony events to listen
 141  *  - A event loop is running to listen events
 142  * - This API is used when #TelSimCardStatus_t is TAPI_SIM_STATUS_SIM_PIN_REQUIRED or TAPI_SIM_STATUS_SIM_LOCK_REQUIRED on boot time.
 143  * - Currently there`s no proper scenario for PIN2 verification by using this API.
 144  *
 145  * @post
 146  *  - None.
 147  *
 148  * @return Return Type (int) \n
 149  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 150  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 151  *
 152  * @par Prospective Clients:
 153  * External Apps.
 154  *
 155  * @see None
 156  *
 157  * @code
 158  * #include <ITapiSim.h>
 159  *
 160  * int request_id = 0;
 161  * err_code = TAPI_API_SUCCESS; // 0
 162  * int length = TAPI_SIM_PIN_LENGTH+1;
 163  * char init_pin_val[length] ;
 164  *
 165  * strcpy(init_pin_val, PIN1_NORMAL);
 166  *
 167  * TelSimSecPw_t pin_data = {0,};
 168  *
 169  * pin_data.type = TAPI_SIM_PTYPE_PIN1;
 170  * pin_data.pw_len = strlen(init_pin_val);
 171  *
 172  * printf("pw_len[%d]", pin_data.pw_len);
 173  *
 174  * pin_data.pw = (char*)malloc(length);
 175  * memcpy(pin_data.pw,init_pin_val,length);
 176  *
 177  * err_code = tel_verifiy_sim_pins(&pin_data, &request_id);
 178  *
 179  * @endcode
 180  *
 181  * @remarks None
 182  *
 183  */
 184 /*================================================================================================*/
 185 int tel_verifiy_sim_pins(const TelSimSecPw_t *pin_data, int *req_id);
 186
 187
 188 /**
 189  * @brief  This function performs unblock PIN1/PIN2 operation based on PUK information passed along with
 190  * unblock information entered by the user.
 191  * If you get sim card status(TAPI_SIM_STATUS_SIM_PUK_REQUIRED) by using #tel_get_sim_init_info on boot time
 192  * or (TAPI_SIM_PIN_STATUS_BLOCKED) by using #tel_get_sim_security_status after normal initialization for specific operation,
 193  * you may unblock PIN1/PIN2.
 194  *
 195  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 196  * However it just means that the API request has been transfered to the CP successfully.
 197  * The actual operation result is being delivered in the corresponding event asynchronously.
 198  *
 199  * @par Sync (or) Async:
 200  * This is an Asynchronous API.
 201  *
 202  * @par Important Notes:
 203  * - Based on Pin status (PIN1/PIN2) is blocked, an unsolicited event TAPI_EVENT_SIM_STATUS_IND
 204  * is published to Applications on boot time also.
 205  *
 206  * @warning
 207  * - If you fail to unblock PIN til given retry count, Your SIM card be permanent block status.
 208  *
 209  * @param[in] puk_data
 210  * -Specifies unblocking PIN password #TelSimSecPw_t
 211  *
 212  * @param[in] new_pin_data
 213  * -Specifies PIN password which you want to use after unblocking operation #TelSimSecPw_t
 214  *
 215  * @param [out] req_id
 216  *   - Unique identifier for a particular request.
 217  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
 218  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
 219  *
 220  * @par Async Response Message:
 221  * The event associated is TAPI_EVENT_SIM_VERIFY_PUK_CNF  and the event data is #TelSimSecResult_t.
 222  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
 223  * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Verification successes.
 224  * If returned status is TAPI_SIM_PUK_INCORRECT_PASSWORD, Verification fails and you can check retry count by using event data  #TelSimSecResult_t.
 225  *
 226  * @pre
 227  *  - Initialize Dbus connection with #tel_init
 228  *  - Register caller's application name with #tel_register_app_name
 229  *  - Register telephony events to listen
 230  *  - A event loop is running to listen events
 231  *  - 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.
 232  *
 233  * @post
 234  *  - After Success on unblocking for PIN1 or PIN2, each pin check facility is enabled even if previous facility is disabled.
 235  *
 236  * @return Return Type (int) \n
 237  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 238  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 239  *
 240  * @par Prospective Clients:
 241  * External Apps.
 242  *
 243  * @see None
 244  *
 245  * @code
 246  * #include <ITapiSim.h>
 247  *
 248  * int request_id = 0;
 249  * err_code = TAPI_API_SUCCESS; // 0
 250  * int length = TAPI_SIM_PIN_LENGTH+1;
 251  *
 252  * char init_pin_val[length];
 253  * char init_puk_val[length];
 254  *
 255  * strcpy(init_pin_val, PIN1_NORMAL);
 256  * strcpy(init_puk_val, PUK1_NORMAL);
 257  *
 258  * TelSimSecPw_t puk_data = {0,};
 259  * TelSimSecPw_t new_pin_data = {0,};
 260  *
 261  * puk_data.type = TAPI_SIM_PTYPE_PUK1;   // 0x00
 262  * puk_data.pw_len = length;
 263  * puk_data.pw_len = strlen(init_puk_val);
 264  * printf("pw_len[%d]", puk_data.pw_len);
 265  * memcpy(puk_data.pw,init_pin_val,length);
 266  *
 267  * new_pin_data.type = TAPI_SIM_PTYPE_PIN1;   // 0x00
 268  * new_pin_data.pw_len = strlen(init_pin_val);
 269  * printf("pw_len[%d]", new_pin_data.pw_len);
 270  * new_pin_data.pw = (char*)malloc(length);
 271  * memcpy(new_pin_data.pw,init_pin_val,length);
 272  *
 273  * err_code = tel_verify_sim_puks(&puk_data, &new_pin_data, &request_id);
 274  *
 275  * @endcode
 276  *
 277  * @remarks None
 278  *
 279  */
 280 /*================================================================================================*/
 281 int tel_verify_sim_puks(const TelSimSecPw_t *puk_data, const TelSimSecPw_t *new_pin_data, int *req_id);
 282
 283
 284 /**
 285  * @brief  This function changes PIN1/PIN2 code based on the pin type passed along with old pin data and new pin data.
 286  *
 287  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 288  * However it just means that the API request has been transfered to the CP successfully.
 289  * The actual operation result is being delivered in the corresponding event asynchronously.
 290  *
 291  * @par Sync (or) Async:
 292  * This is an Asynchronous API.
 293  *
 294  * @par Important Notes:
 295  * - User should fill up pin type equally both old_pin and new_pin.
 296  *
 297  * @warning
 298  * - None.
 299  *
 300  * @param[in] old_pin
 301  * -Old pin code, entered by the user. #TelSimSecPw_t
 302  *
 303  * @param[in] new_pin
 304  * -New pin code, entered by the user. #TelSimSecPw_t
 305  *
 306  * @param [out] req_id
 307  *   - Unique identifier for a particular request.
 308  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
 309  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
 310  *
 311  * @par Async Response Message:
 312  * The event associated is TAPI_EVENT_SIM_CHANGE_PINS_CNF  and the event data is #TelSimSecResult_t.
 313  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
 314  * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Change operation finish successfully.
 315  * If returned status is TAPI_SIM_PIN_INCORRECT_PASSWORD, Change operation fails and you can check retry count by using event data  #TelSimSecResult_t.
 316  *
 317  * @pre
 318  *  - Initialize Dbus connection with #tel_init
 319  *  - Register caller's application name with #tel_register_app_name
 320  *  - Register telephony events to listen
 321  *  - A event loop is running to listen events
 322  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 323  *  - PIN which user want to change check facility should be enabled.
 324  *
 325  * @post
 326  *  - None.
 327  *
 328  * @return Return Type (int) \n
 329  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 330  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 331  *
 332  * @par Prospective Clients:
 333  * External Apps.
 334  *
 335  * @see None
 336  *
 337  * @code
 338  * #include <ITapiSim.h>
 339  *
 340  * int request_id = 0;
 341  * err_code = TAPI_API_SUCCESS; // 0
 342  * int length = TAPI_SIM_PIN_LENGTH+1;
 343  * char init_old_pin_val[length] ;
 344  * char init_new_pin_val[length];
 345  *
 346  * memset(&init_old_pin_val, 0 , length);
 347  * memset(&init_new_pin_val, 0 , length);
 348  *
 349  * TelSimSecPw_t old_pin = {0,};
 350  * TelSimSecPw_t new_pin = {0,};
 351  *
 352  * strcpy(init_old_pin_val, PIN1_ORG);
 353  *
 354  * old_pin.type = TAPI_SIM_PTYPE_PIN1;
 355  * old_pin.pw_len = strlen(init_old_pin_val);
 356  * printf("pw_len[%d]", old_pin.pw_len);
 357  * old_pin.pw = (char*)malloc(length);
 358  * memcpy(old_pin.pw,init_old_pin_val,length);
 359  *
 360  * strcpy(init_new_pin_val, PIN1_NEW);
 361  *
 362  * new_pin.type = TAPI_SIM_PTYPE_PIN1;
 363  * new_pin.pw_len = strlen(init_new_pin_val);
 364  * printf("pw_len[%d]", new_pin.pw_len);
 365  * new_pin.pw = (char*)malloc(length);
 366  * memcpy(new_pin.pw,init_new_pin_val,length);
 367  *
 368  * err_code = tel_change_sim_pins(&old_pin, &new_pin, &request_id);
 369  *
 370  * @endcode
 371  *
 372  * @remarks None
 373  *
 374  */
 375 /*================================================================================================*/
 376 int tel_change_sim_pins(const TelSimSecPw_t *old_pin , const TelSimSecPw_t *new_pin, int *req_id);
 377
 378
 379 /**
 380  * @brief  This function gets the current PIN1/PIN2/SIM LOCK status.
 381  *
 382  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 383  * However it just means that the API request has been transfered to the CP successfully.
 384  * The actual operation result is being delivered in the corresponding event asynchronously.
 385  *
 386  * @par Sync (or) Async:
 387  * This is a synchronous function.
 388  *
 389  * @par Important Notes:
 390  * - None
 391  *
 392  * @warning
 393  * - None.
 394  *
 395  * @param[in] type
 396  * - Security type user wants to get status #TelSimPinType_t
 397  *
 398  * @param [out] status
 399  * This parameter returns the current status about user wants. #TelSimPinStatus_t
 400  *
 401  * @par Async Response Message:
 402  * - None
 403  *
 404  * @pre
 405  *  - Initialize Dbus connection with #tel_init
 406  *  - Register caller's application name with #tel_register_app_name
 407  *  - Register telephony events to listen
 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  *
 411  * @post
 412  *  - None.
 413  *
 414  * @return Return Type (int) \n
 415  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 416  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 417  *
 418  * @par Prospective Clients:
 419  * External Apps.
 420  *
 421  * @see None
 422  *
 423  * @code
 424  * #include <ITapiSim.h>
 425  * int err_code = 0;
 426  * TelSimPinType_t type = TAPI_SIM_PTYPE_PIN1; //pin type
 427  * TelSimPinStatus_t status = -1;
 428  * err_code = tel_get_sim_security_status(type, &status);
 429  *
 430  * @endcode
 431  *
 432  * @remarks None
 433  *
 434  */
 435 /*================================================================================================*/
 436 int tel_get_sim_security_status(TelSimPinType_t type, TelSimPinStatus_t *status);
 437
 438
 439 /**
 440  * @brief  This function disables the PIN1/SIM Lock check facility based on the Pin type and pin data passed from Application.
 441  * PIN1 code : The SIM card has its own password is to check access permissions
 442  * SIM Lock code : Between Device and the SIM card using a SIM password is only available on certain handsets to be used to authorize.
 443  *
 444  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 445  * However it just means that the API request has been transfered to the CP successfully.
 446  * The actual operation result is being delivered in the corresponding event asynchronously.
 447  *
 448  * @par Sync (or) Async:
 449  * This is an Asynchronous API.
 450  *
 451  * @par Important Notes:
 452  * -For PIN2, disabling applies only for 3G USIMs and when PIN2 in NOT mapped to CHV2 of GSM application.
 453  * -PIN2 disabling operation is generally not used.
 454  *
 455  * @warning
 456  * - None.
 457  *
 458  * @param[in] sec_data
 459  * -User entered PIN disable data and pin type. #TelSimSecPw_t
 460  *
 461  * @param [out] req_id
 462  *   - Unique identifier for a particular request.
 463  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
 464  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
 465  *
 466  * @par Async Response Message:
 467  * The event associated is TAPI_EVENT_SIM_DISABLE_SEC_CNF  and the event data is #TelSimSecResult_t.
 468  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
 469  * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, disabling operation finish successfully.
 470  * If returned status is TAPI_SIM_PIN_INCORRECT_PASSWORD, disabling operation fails and you can check retry count by using event data  #TelSimSecResult_t.
 471  *
 472  * @pre
 473  *  - Initialize Dbus connection with #tel_init
 474  *  - Register caller's application name with #tel_register_app_name
 475  *  - Register telephony events to listen
 476  *  - A event loop is running to listen events
 477  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 478  *  - Checking Facility which user wants to disable should be enabled status.
 479  *
 480  * @post
 481  *  - None.
 482  *
 483  * @return Return Type (int) \n
 484  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 485  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 486  *
 487  * @par Prospective Clients:
 488  * External Apps.
 489  *
 490  * @see None
 491  *
 492  * @code
 493  * #include <ITapiSim.h>
 494  * int err_code = 0;
 495  * TelSimSecPw_t sec_data = {0,};
 496  * sec_data.type = TAPI_SIM_PTYPE_PIN1;   // 0x00
 497  * sec_data.pw_len = 4; // current pw is 4 digit
 498  * sec_data.pw = (char*)malloc(length);
 499  * memcpy(sec_data.pw,"1111",length);
 500  * err_code = tel_disable_sim_security(&sec_data, &request_id);
 501  * @endcode
 502  *
 503  * @remarks None
 504  *
 505  */
 506 /*================================================================================================*/
 507 int tel_disable_sim_security(TelSimSecPw_t *sec_data, int *req_id);
 508
 509
 510 /**
 511  * @brief  This function enables the PIN1/SIM Lock check facility based on the Pin type and pin data passed from Application.
 512  * PIN1 code : The SIM card has its own password is to check access permissions
 513  * SIM Lock code : Between Device and the SIM card using a SIM password is only available on certain handsets to be used to authorize.
 514  *
 515  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 516  * However it just means that the API request has been transfered to the CP successfully.
 517  * The actual operation result is being delivered in the corresponding event asynchronously.
 518  *
 519  * @par Sync (or) Async:
 520  * This is an Asynchronous API.
 521  *
 522  * @par Important Notes:
 523  * - None.
 524  *
 525  * @warning
 526  * - None.
 527  *
 528  * @param[in] sec_data
 529  * -User entered PIN enable data and pin type. #TelSimSecPw_t
 530  *
 531  * @param [out] req_id
 532  *   - Unique identifier for a particular request.
 533  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
 534  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
 535  *
 536  * @par Async Response Message:
 537  * The event associated is TAPI_EVENT_SIM_ENABLE_SEC_CNF  and the event data is #TelSimSecResult_t.
 538  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
 539  * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, enabling operation finish successfully.
 540  * If returned status is TAPI_SIM_PIN_INCORRECT_PASSWORD, enabling operation fails and you can check retry count by using event data  #TelSimSecResult_t.
 541  *
 542  * @pre
 543  *  - Initialize Dbus connection with #tel_init
 544  *  - Register caller's application name with #tel_register_app_name
 545  *  - Register telephony events to listen
 546  *  - A event loop is running to listen events
 547  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 548  *  - Checking Facility which user wants to enable should be disabled status.
 549  *
 550  * @post
 551  *  - None.
 552  *
 553  * @return Return Type (int) \n
 554  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 555  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 556  *
 557  * @par Prospective Clients:
 558  * External Apps.
 559  *
 560  * @see None
 561  *
 562  * @code
 563  * #include <ITapiSim.h>
 564  * int err_code = 0;
 565  * TelSimSecPw_t sec_data = {0,};
 566  * sec_data.type = TAPI_SIM_PTYPE_PIN1;   // 0x00
 567  * sec_data.pw_len = 4; // current pw is 4 digit
 568  * sec_data.pw = (char*)malloc(length);
 569  * memcpy(sec_data.pw,"1111",length);
 570  * err_code = tel_enable_sim_security(&sec_data, &request_id);
 571  * @endcode
 572  *
 573  * @remarks None
 574  *
 575  */
 576 /*================================================================================================*/
 577 int tel_enable_sim_security(TelSimSecPw_t *sec_data, int *req_id);
 578
 579
 580 /**
 581  *
 582  * @brief  This API is used to get lock personalisation information like current network lock status or network subset lock and so on.
 583  * Refer '3GPP TS 22.022 - Personalisation of Mobile Equipment (ME)' for more detail.
 584  *
 585  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 586  * However it just means that the API request has been transfered to the CP successfully.
 587  * The actual operation result is being delivered in the corresponding event asynchronously.
 588  *
 589  * @par Sync (or) Async:
 590  * This is an Asynchronous API.
 591  *
 592  * @par Important Notes:
 593  * - This functionality should be used only Administrator coverage.
 594  *
 595  * @warning
 596  * - None.
 597  *
 598  * @param[in] type
 599  * -personalisation type
 600  *
 601  * @param [out] req_id
 602  *   - Unique identifier for a particular request.
 603  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
 604  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
 605  *
 606  * @par Async Response Message:
 607  * - The event associated is TAPI_EVENT_SIM_PERS_STATUS_CNF  and the event data is #TelSimPersStatus_t.
 608  *
 609  * @pre
 610  *  - Initialize Dbus connection with #tel_init
 611  *  - Register caller's application name with #tel_register_app_name
 612  *  - Register telephony events to listen
 613  *  - A event loop is running to listen events
 614  *
 615  * @post
 616  *  - None.
 617  *
 618  * @return Return Type (int) \n
 619  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 620  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 621  *
 622  * @par Prospective Clients:
 623  * External Apps.
 624  *
 625  * @see None
 626  *
 627  * @code
 628  * #include <ITapiSim.h>
 629  * int err_code = 0;
 630  * int request_id = 0;
 631  * TelSimPersType_t type = 0;
 632  * type = TAPI_SIM_PERS_NET; //network lock
 633  * err_code = tel_get_sim_personalization_status(type, &request_id);
 634  * @endcode
 635  *
 636  * @remarks None
 637  *
 638  */
 639 /*================================================================================================*/
 640 int tel_get_sim_personalization_status(TelSimPersType_t type, int *req_id);
 641
 642
 643 /**
 644  * @brief  This API is used to disable personalisation of network, network subset, corporate, service provider personalisation.
 645  * Refer '3GPP TS 22.022 - Personalisation of Mobile Equipment (ME)' for more detail.
 646  *
 647  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 648  * However it just means that the API request has been transfered to the CP successfully.
 649  * The actual operation result is being delivered in the corresponding event asynchronously.
 650  *
 651  * @par Sync (or) Async:
 652  * This is an Asynchronous API.
 653  *
 654  * @par Important Notes:
 655  * - This functionality should be used only Administrator coverage.
 656  *
 657  * @warning
 658  * - None.
 659  *
 660  * @param[in] pers_data
 661  * -Personalisation information passed. #TelSimPersPw_t
 662  *
 663  *
 664  * @param [out] req_id
 665  *   - Unique identifier for a particular request.
 666  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
 667  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
 668  *
 669  * @par Async Response Message:
 670  * - The event associated is TAPI_EVENT_SIM_DISABLE_PERS_CNF.
 671  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
 672  *
 673  * @pre
 674  *  - Initialize Dbus connection with #tel_init
 675  *  - Register caller's application name with #tel_register_app_name
 676  *  - Register telephony events to listen
 677  *  - A event loop is running to listen events
 678  *  - Checking Facility which user wants to disable should be enabled status.
 679  *
 680  * @post
 681  *  - None.
 682  *
 683  * @return Return Type (int) \n
 684  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 685  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 686  *
 687  * @par Prospective Clients:
 688  * External Apps.
 689  *
 690  * @see None
 691  *
 692  * @code
 693  * #include <ITapiSim.h>
 694  * int err_code = 0;
 695  * int request_id = 0;
 696  * TelSimPersPw_t lock_pers = {0,};
 697  * lock_pers.type = TAPI_SIM_PERS_NET; //network lock case
 698  * lock_pers.pw_len =  8; //control key
 699  * lock_pers.pw = (char*)malloc(8);
 700  * memcpy(lock_pers.pw,"11111111",length);    //temp value
 701  * err_code = tel_disable_sim_personalization(&lock_pers, &request_id);
 702  * @endcode
 703  *
 704  * @remarks None
 705  *
 706  */
 707 /*================================================================================================*/
 708 int tel_disable_sim_personalization(TelSimPersPw_t *pers_data, int *req_id);
 709
 710
 711 /**
 712  * @brief  This API is used to enable personalisation of network, network subset, corporate, service provider personalisation.
 713  * Refer '3GPP TS 22.022 - Personalisation of Mobile Equipment (ME)' for more detail.
 714  *
 715  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 716  * However it just means that the API request has been transfered to the CP successfully.
 717  * The actual operation result is being delivered in the corresponding event asynchronously.
 718  *
 719  * @par Sync (or) Async:
 720  * This is an Asynchronous API.
 721  *
 722  * @par Important Notes:
 723  * - This functionality should be used only Administrator coverage.
 724  *
 725  * @warning
 726  * - None.
 727  *
 728  * @param[in] pers_data
 729  * -Personalisation information passed. #TelSimPersPw_t
 730  *
 731  *
 732  * @param [out] req_id
 733  *   - Unique identifier for a particular request.
 734  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
 735  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
 736  *
 737  * @par Async Response Message:
 738  * - The event associated is TAPI_EVENT_SIM_ENABLE_PERS_CNF.
 739  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
 740  *
 741  * @pre
 742  *  - A dbus connection is established with #tel_init
 743  *  - The application name is registered with #tel_register_app_name
 744  *  - The application is registered events to listen asynchronous response with #tel_register_event
 745  *  - A event loop is running to listen events
 746  *  - Checking Facility which user wants to enable should be disabled status.
 747  *
 748  * @post
 749  *  - None.
 750  *
 751  * @return Return Type (int) \n
 752  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 753  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 754  *
 755  * @par Prospective Clients:
 756  * External Apps.
 757  *
 758  * @see None
 759  *
 760  * @code
 761  * #include <ITapiSim.h>
 762  * int err_code = 0;
 763  * int request_id = 0;
 764  * TelSimPersPw_t lock_pers = {0,};
 765  * lock_pers.type = TAPI_SIM_PERS_NET; //network lock case
 766  * lock_pers.pw_len =  15; //control key
 767  * lock_pers.pw = (char*)malloc(15);
 768  * memcpy(lock_pers.pw,"111111111111111",length);    //temp value
 769  * err_code = tel_enable_sim_personalization(&lock_pers, &request_id);
 770  * @endcode
 771  *
 772  * @remarks None
 773  *
 774  */
 775 /*================================================================================================*/
 776 int tel_enable_sim_personalization(TelSimPersPw_t *pers_data, int *req_id);
 777
 778
 779 /**
 780  * @brief  This function is used to get current SIM Phonebook mode whether FDN or not(ADN).
 781  * SIM phonebook ADN(or 3G Phonebook) enabled by default and  the FDN can be used if the user selects FDN activation.
 782  * ADN and FDN also couldn`t activate the same time.
 783  *
 784  * @par Sync (or) Async:
 785  * This is a synchronous function.
 786  *
 787  * @par Important Notes:
 788  * - None
 789  *
 790  * @warning
 791  * - None.
 792  *
 793  * @param [out] fdn_status
 794  * This parameter returns the current FDN status whether enabled or disabled.
 795  *
 796  * @par Async Response Message:
 797  * - None
 798  *
 799  * @pre
 800  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 801  *
 802  * @post
 803  *  - None.
 804  *
 805  * @return Return Type (int) \n
 806  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 807  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 808  *
 809  * @par Prospective Clients:
 810  * External Apps.
 811  *
 812  * @see None
 813  *
 814  * @code
 815  * #include <ITapiSim.h>
 816  * int err_code = 0;
 817  * int fdn_status = 0 ;
 818  * err_code = tel_get_sim_fdn_status(&fdn_status); // you can find in fdn_status variable
 819  * @endcode
 820  *
 821  * @remarks None
 822  *
 823  */
 824 /*================================================================================================*/
 825 int tel_get_sim_fdn_status(int *fdn_status);
 826
 827
 828 /**
 829  * @brief  This function disables FDN phonebook mode.
 830  *
 831  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 832  * However it just means that the API request has been transfered to the CP successfully.
 833  * The actual operation result is being delivered in the corresponding event asynchronously.
 834  *
 835  * @par Sync (or) Async:
 836  * This is an Asynchronous API.
 837  *
 838  * @par Important Notes:
 839  *
 840  * @warning
 841  * - None.
 842  *
 843  * @param[in] pin2
 844  * -User entered pin2 data.
 845  *
 846  * @param[in] pin2_len
 847  * -User entered a length of pin2 data.
 848  *
 849  * @param [out] req_id
 850  *   - Unique identifier for a particular request.
 851  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
 852  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
 853  *
 854  * @par Async Response Message:
 855  * The event associated is TAPI_EVENT_SIM_DISABLE_FDNMODE_CNF  and event data associated with this event.#TelSimSecResult_t
 856  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
 857  *
 858  * @pre
 859  *  - A dbus connection is established with #tel_init
 860  *  - The application name is registered with #tel_register_app_name
 861  *  - The application is registered events to listen asynchronous response with #tel_register_event
 862  *  - A event loop is running to listen events
 863  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 864  *  - FDN mode sould be enabled.
 865  *
 866  * @post
 867  *  - None.
 868  *
 869  * @return Return Type (int) \n
 870  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 871  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 872  *
 873  * @par Prospective Clients:
 874  * External Apps.
 875  *
 876  * @see None
 877  *
 878  * @code
 879  * #include <ITapiSim.h>
 880  * int err_code = 0;
 881  * int request_id = 0;
 882  * TelSimSecPw_t sec_data = {0,};
 883  * sec_data.type = TAPI_SIM_PTYPE_PIN2; // pin2
 884  * sec_data.pw_len = 4;
 885  * sec_data.pw = (char*)malloc(4);
 886  * memcpy(sec_data.pw,"2222",length); //temp value
 887  * err_code = tel_disable_sim_fdn(sec_data.pw, &sec_data.pw_len, &request_id);
 888  * @endcode
 889  *
 890  * @remarks None
 891  *
 892  */
 893 /*================================================================================================*/
 894 int tel_disable_sim_fdn(const unsigned char *pin2, int *pin2_len, int *req_id);
 895
 896
 897 /**
 898  * @brief  This function enables FDN phonebook mode.
 899  *
 900  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 901  * However it just means that the API request has been transfered to the CP successfully.
 902  * The actual operation result is being delivered in the corresponding event asynchronously.
 903  *
 904  * @par Sync (or) Async:
 905  * This is an Asynchronous API.
 906  *
 907  * @par Important Notes:
 908  *
 909  * @warning
 910  * - None.
 911  *
 912  * @param[in] pin2
 913  * -User entered pin2 data.
 914  *
 915  * @param[in] pin2_len
 916  * -User entered a length of pin2 data.
 917  *
 918  * @param [out] req_id
 919  *   - Unique identifier for a particular request.
 920  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
 921  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
 922  *
 923  * @par Async Response Message:
 924  * The event associated is TAPI_EVENT_SIM_ENABLE_FDNMODE_CNF  and event data associated with this event.#TelSimSecResult_t
 925  * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
 926  *
 927  * @pre
 928  *  - A dbus connection is established with #tel_init
 929  *  - The application name is registered with #tel_register_app_name
 930  *  - The application is registered events to listen asynchronous response with #tel_register_event
 931  *  - A event loop is running to listen events
 932  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
 933  *  - FDN mode sould be disabled.
 934  *
 935  * @post
 936  *  - None.
 937  *
 938  * @return Return Type (int) \n
 939  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
 940  * - Negative integer : it provides an error code (Refer #TapiResult_t)
 941  *
 942  * @par Prospective Clients:
 943  * External Apps.
 944  *
 945  * @see None
 946  *
 947  * @code
 948  * #include <ITapiSim.h>
 949  * int err_code = 0;
 950  * int request_id = 0;
 951  * TelSimSecPw_t sec_data = {0,};
 952  * sec_data.type = TAPI_SIM_PTYPE_PIN2; // pin2
 953  * sec_data.pw_len = 4;
 954  * sec_data.pw = (char*)malloc(4);
 955  * memcpy(sec_data.pw,"2222",length); //temp value
 956  * err_code = tel_enable_sim_fdn(sec_data.pw, &sec_data.pw_len, &request_id);
 957  * @endcode
 958  *
 959  * @remarks None
 960  *
 961  */
 962 /*================================================================================================*/
 963 int tel_enable_sim_fdn(const unsigned char *pin2, int *pin2_len, int *req_id);
 964
 965
 966 /**
 967  * @brief  This function provides common interface for accessing SIM data based on USIM generic command in ETSI TS 102 221
 968  * and 3GPP TS 31.102 Characteristics of the Universal Subscriber Identity Module (USIM) application.
 969  * Required to operate the terminal by default, the application (call, sms, setting, network and so on) are using the SIM data
 970  * stored in the Telephony server to the user data, and easy to use their API to provide a separate,
 971  * but SIM and the user's data is enormous, with some data, the usage of any use to manage all the telephony server is difficult.
 972  * Therefore, handling the SIM data can provide a common one API.
 973  * Only this API be specified in the ETSI TS 102 221 of the generic command 'SELECT', 'READ BINARY', 'READ RECORD',
 974  * 'UPDATE BINARY', 'UPDATE RECORD' command support.
 975  *
 976  * This function makes Dbus method call to Telephony Sever and returns immediate value.
 977  * However it just means that the API request has been transfered to the CP successfully.
 978  * The actual operation result is being delivered in the corresponding event asynchronously.
 979  *
 980  * @par Sync (or) Async:
 981  * This is an Asynchronous API.
 982  *
 983  * @par Important Notes:
 984  * - If you want more generic access, please use #tel_req_sim_apdu
 985  *
 986  * @warning
 987  * - None.
 988  *
 989  * @param[in] rsim_data
 990  * -Different parameters should be filled up according to command type,
 991  * If user wants to run 'SELECT' command, Only file_id needed. And you can find file type with response data by asynchronous return.
 992  * If user wants to run 'READ BINARY' command, should fill up parameter like this(p1:offset, p2:offset low, p3:bytes to be read)
 993  * If user wants to run 'READ RECORD' command, should fill up parameter like this(p1:record num, p2:mode, p3:bytes to be read)
 994  * If user wants to run 'UPDATE BINARY' command, should fill up parameter like this(p1:offset, p2:offset low, p3:bytes to be updated, data:address of data which will be updated)
 995  * If user wants to run 'UPDATE RECORD' command, should fill up parameter like this(p1:record num, p2:mode, p3:bytes to be updated, data:address of data which will be updated)
 996  *
 997  * @param [out] req_id
 998  *   - Unique identifier for a particular request.
 999  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
1000  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
1001  *
1002  * @par Async Response Message:
1003  * The event associated is TAPI_EVENT_SIM_RSIM_ACCESS_CNF  and the event data is #TelSimReadFileRaw_t.
1004  * Asynchronous return status is indicated by #TelSimAccessResult_t.
1005  *
1006  * @pre
1007  *  - A dbus connection is established with #tel_init
1008  *  - The application name is registered with #tel_register_app_name
1009  *  - The application is registered events to listen asynchronous response with #tel_register_event
1010  *  - A event loop is running to listen events
1011  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1012  *  - None.
1013  *
1014  * @post
1015  *  - None.
1016  *
1017  * @return Return Type (int) \n
1018  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1019  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1020  *
1021  * @par Prospective Clients:
1022  * External Apps.
1023  *
1024  * @see None
1025  *
1026  * @code
1027  * #include <ITapiSim.h>
1028  * int err_code =0;
1029  * int request_id = 0;
1030  * TelSimRSimReq_t rsim = {0,};
1031  * rsim.file_id = 0x6F60;
1032  * rsim.rsim_cmd = TAPI_SIM_GET_RESPONSE;
1033  *
1034  * // REQUEST SIM ACCESS
1035  * err_code = tel_req_sim_access((const TelSimRSimReq_t*)&rsim, &request_id);
1036  * @endcode
1037  *
1038  * @remarks None
1039  *
1040  */
1041 /*================================================================================================*/
1042 int tel_req_sim_access(const TelSimRSimReq_t *rsim_data, int *req_id);
1043
1044
1045 /**
1046  * @brief  This function provides common interface for accessing SIM data based on USIM generic command in ETSI TS 102 221
1047  * and 3GPP TS 31.102 Characteristics of the Universal Subscriber Identity Module (USIM) application.
1048  * This API provides only interface to send APDU. User should know well APDU usage.
1049  *
1050  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1051  * However it just means that the API request has been transfered to the CP successfully.
1052  * The actual operation result is being delivered in the corresponding event asynchronously.
1053  *
1054  * @par Sync (or) Async:
1055  * This is an Asynchronous API.
1056  *
1057  * @par Important Notes:
1058  * - None
1059  *
1060  * @warning
1061  * - None.
1062  *
1063  * @param[in] rsim_data
1064  *
1065  * @param [out] req_id
1066  *   - Unique identifier for a particular request.
1067  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
1068  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
1069  *
1070  * @par Async Response Message:
1071  * The event associated is TAPI_EVENT_SIM_APDU_CNF  and the event data is #TelSimApduResp_t.
1072  * Asynchronous return status is indicated by #TelSimAccessResult_t.
1073  *
1074  * @pre
1075  *  - A dbus connection is established with #tel_init
1076  *  - The application name is registered with #tel_register_app_name
1077  *  - The application is registered events to listen asynchronous response with #tel_register_event
1078  *  - A event loop is running to listen events
1079  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1080  *  - None.
1081  *
1082  * @post
1083  *  - None.
1084  *
1085  * @return Return Type (int) \n
1086  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1087  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1088  *
1089  * @par Prospective Clients:
1090  * External Apps.
1091  *
1092  * @see None
1093  *
1094  * @code
1095  * #include <ITapiSim.h>
1096  * int err_code =0;
1097  * int request_id = 0;
1098  * TelSimApdu_t apdu = {0,};
1099  * int tmp_apdu[5] = {0xa,5,6,7,8};
1100  * apdu.apdu_len = 5; //user should check
1101  * apdu.apdu = apdu;
1102  *
1103  * // REQUEST SIM ACCESS
1104  * err_code = tel_req_sim_apdu((const TelSimRSimReq_t*)&rsim, &request_id);
1105  * @endcode
1106  *
1107  * @remarks None
1108  *
1109  */
1110 /*================================================================================================*/
1111 int tel_req_sim_apdu(TelSimApdu_t* apdu_data, int *req_id);
1112
1113
1114 /**
1115  * @brief  This function provides common interface to get SIM ATR(Answer To Reset) value.
1116  *
1117  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1118  * However it just means that the API request has been transfered to the CP successfully.
1119  * The actual operation result is being delivered in the corresponding event asynchronously.
1120  *
1121  * @par Sync (or) Async:
1122  * This is an Asynchronous API.
1123  *
1124  * @par Important Notes:
1125  * - None
1126  *
1127  * @warning
1128  * - None.
1129  *
1130  * @param [out] req_id
1131  *   - Unique identifier for a particular request.
1132  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
1133  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
1134  *
1135  * @par Async Response Message:
1136  * The event associated is TAPI_EVENT_SIM_ATR_CNF  and the event data is #TelSimAtrResp_t.
1137  * Asynchronous return status is indicated by #TelSimAccessResult_t.
1138  *
1139  * @pre
1140  *  - A dbus connection is established with #tel_init
1141  *  - The application name is registered with #tel_register_app_name
1142  *  - The application is registered events to listen asynchronous response with #tel_register_event
1143  *  - A event loop is running to listen events
1144  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1145  *  - None.
1146  *
1147  * @post
1148  *  - None.
1149  *
1150  * @return Return Type (int) \n
1151  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1152  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1153  *
1154  * @par Prospective Clients:
1155  * External Apps.
1156  *
1157  * @see None
1158  *
1159  * @code
1160  * #include <ITapiSim.h>
1161  * int err_code =0;
1162  * int request_id = 0;
1163  *
1164  * // REQUEST SIM ATR
1165  * err_code = tel_req_sim_atr(&request_id);
1166  * @endcode
1167  *
1168  * @remarks None
1169  *
1170  */
1171 /*================================================================================================*/
1172 int tel_req_sim_atr(int *req_id);
1173
1174
1175 /**
1176  * @brief  This function is a synchronous API used to get ECC(SIM) or UECC(USIM) data.
1177  *
1178  * @par Sync (or) Async:
1179  * This is a synchronous function.
1180  *
1181  * @par Important Notes:
1182  * - None
1183  *
1184  * @warning
1185  * - None.
1186  *
1187  * @param [out] ecc_data
1188  * This parameter returns the SIM emergency call code information like ecc length, service type etc.
1189  *
1190  * @param [out] ecc_count
1191  * Specifies number of ECC records.
1192  *
1193  * @par Async Response Message:
1194  * - None
1195  *
1196  * @pre
1197  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1198  *  - None.
1199  *
1200  * @post
1201  *  - None.
1202  *
1203  * @return Return Type (int) \n
1204  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1205  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1206  *
1207  * @par Prospective Clients:
1208  * External Apps.
1209  *
1210  * @see None
1211  *
1212  * @code
1213  * #include <ITapiSim.h>
1214  * int ecc_rec_count = 0; // count in sim card
1215  * int err_code = 0;
1216  * TelSimEccData_t ecc_info = {{{0,}}};
1217  * err_code = tel_get_sim_ecc(&ecc_info, &ecc_rec_count);
1218  * @endcode
1219  *
1220  * @remarks None
1221  *
1222  */
1223 /*================================================================================================*/
1224 int tel_get_sim_ecc(TelSimEccData_t *ecc_data, int *ecc_count);
1225
1226
1227 /**
1228  * @brief  This API is used to get the language preference(indication) information.
1229  *
1230  * @par Sync (or) Async:
1231  * This is a synchronous function.
1232  *
1233  * @par Important Notes:
1234  * - None
1235  *
1236  * @warning
1237  * - None.
1238  *
1239  * @param [out] sim_language
1240  * This parameter returns the language preference information.
1241  *
1242  * @par Async Response Message:
1243  * - None
1244  *
1245  * @pre
1246  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1247  *  - None.
1248  *
1249  * @post
1250  *  - None.
1251  *
1252  * @return Return Type (int) \n
1253  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1254  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1255  *
1256  * @par Prospective Clients:
1257  * External Apps.
1258  *
1259  * @see None
1260  *
1261  * @code
1262  * #include <ITapiSim.h>
1263  * int err_code = 0;
1264  * TelSimLanguageInfo_t li_info = {0,};
1265  * err_code = tel_get_sim_language(&li_info); // you can find language info with li_info variable
1266  * @endcode
1267  *
1268  * @remarks None
1269  *
1270  */
1271 /*================================================================================================*/
1272 int tel_get_sim_language(TelSimLanguageInfo_t *sim_language);
1273
1274
1275 /**
1276  * @brief  This API is used to update the language preference information to SIM card.
1277  *
1278  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1279  * However it just means that the API request has been transfered to the CP successfully.
1280  * The actual operation result is being delivered in the corresponding event asynchronously.
1281  *
1282  * @par Sync (or) Async:
1283  * This is a Asynchronous function.
1284  *
1285  * @par Important Notes:
1286  * - This function update SIM Language information directly and can effect device language setting. Use carefully.
1287  *
1288  * @warning
1289  * - None.
1290  *
1291  * @param[in] language
1292  * This parameter returns the language preference information.
1293  *
1294  * @param [out] req_id
1295  *   - Unique identifier for a particular request.
1296  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
1297  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
1298  *
1299  * @par Async Response Message:
1300  * The event associated is TAPI_EVENT_SIM_SET_LANGUAGE_CNF.
1301  * Asynchronous return status is indicated by #TelSimAccessResult_t.
1302  *
1303  * @pre
1304  *  - A dbus connection is established with #tel_init
1305  *  - The application name is registered with #tel_register_app_name
1306  *  - The application is registered events to listen asynchronous response with #tel_register_event
1307  *  - A event loop is running to listen events
1308  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1309  *  - None.
1310  *
1311  * @post
1312  *  - None.
1313  *
1314  * @return Return Type (int) \n
1315  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1316  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1317  *
1318  * @par Prospective Clients:
1319  * External Apps.
1320  *
1321  * @see None
1322  *
1323  * @code
1324  * #include <ITapiSim.h>
1325  * int err_code = 0;
1326  * int request_id = 0;
1327  * TelSimLanguagePreferenceCode_t language = 0x00; //init
1328  * language = TAPI_SIM_LP_ENGLISH; //language value
1329  * err_code = tel_set_sim_language(language, &request_id);
1330  * @endcode
1331  *
1332  * @remarks None
1333  *
1334  */
1335 /*================================================================================================*/
1336 int tel_set_sim_language(TelSimLanguagePreferenceCode_t language, int *req_id);
1337
1338
1339 /**
1340  * @brief  This function is a synchronous API which gets the Card Type whether Card is a SIM or a USIM.
1341  *
1342  * @par Sync (or) Async:
1343  * This is a synchronous function.
1344  *
1345  * @par Important Notes:
1346  * - None
1347  *
1348  * @warning
1349  * - None.
1350  *
1351  * @param [out] card_type
1352  * This parameter returns the SIM card type information like whether it is GSM SIM card or USIM or it is of unknown type.
1353  *
1354  *  - TAPI_SIM_CARD_TYPE_UNKNOWN
1355  *  - TAPI_SIM_CARD_TYPE_GSM
1356  *  - TAPI_SIM_CARD_TYPE_USIM
1357  *
1358  * @par Async Response Message:
1359  * - None
1360  *
1361  * @pre
1362  *  - None.
1363  *
1364  * @post
1365  *  - None.
1366  *
1367  * @return Return Type (int) \n
1368  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1369  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1370  *
1371  * @par Prospective Clients:
1372  * External Apps.
1373  *
1374  * @see None
1375  *
1376  * @code
1377  * #include <ITapiSim.h>
1378  * int err_code = 0;
1379  * TelSimCardType_t cardInfo; //unkwon, sim(normally gsm), usim(normally umts)
1380  * err_code = tel_get_sim_type(&cardInfo);
1381  *
1382  * @endcode
1383  *
1384  * @remarks None
1385  *
1386  */
1387 /*================================================================================================*/
1388 int tel_get_sim_type(TelSimCardType_t *card_type);
1389
1390
1391 /**
1392  * @brief  This function is a synchronous API gets the IMSI information.
1393  *
1394  * @par Sync (or) Async:
1395  * This is a synchronous function.
1396  *
1397  * @par Important Notes:
1398  * - IMSI value is the value that security needs.
1399  *
1400  * @warning
1401  * - None.
1402  *
1403  * @param [out] imsi
1404  * This parameter returns the IMSI information. Refer #TelSimImsiInfo_t
1405  *
1406  * @par Async Response Message:
1407  * - None
1408  *
1409  * @pre
1410  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1411  *  - None.
1412  *
1413  * @post
1414  *  - None.
1415  *
1416  * @return Return Type (int) \n
1417  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1418  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1419  *
1420  * @par Prospective Clients:
1421  * External Apps.
1422  *
1423  * @see None
1424  *
1425  * @code
1426  * #include <ITapiSim.h>
1427  * int err_code = 0;
1428  * TelSimImsiInfo_t sim_imsi_info; // mcc, mnc, msisdn
1429  * err_code = tel_get_sim_imsi(&sim_imsi_info);
1430  * @endcode
1431  *
1432  * @remarks None
1433  *
1434  */
1435 /*================================================================================================*/
1436 int tel_get_sim_imsi(TelSimImsiInfo_t* imsi);
1437
1438
1439 /**
1440  * @brief  This function is a synchronous API gets a Unique identification number of the (U)ICC.
1441  * ICC means Integrated Circuit Card.
1442  *
1443  * @par Sync (or) Async:
1444  * This is a synchronous function.
1445  *
1446  * @par Important Notes:
1447  * - IC Card number value is the value that security needs.
1448  *
1449  * @warning
1450  * - None.
1451  *
1452  * @param [out] iccid
1453  * This parameter returns the IC Card number. Refer #TelSimIccIdInfo_t
1454  *
1455  * @par Async Response Message:
1456  * - None
1457  *
1458  * @pre
1459  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1460  *  - None.
1461  *
1462  * @post
1463  *  - None.
1464  *
1465  * @return Return Type (int) \n
1466  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1467  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1468  *
1469  * @par Prospective Clients:
1470  * External Apps.
1471  *
1472  * @see None
1473  *
1474  * @code
1475  * #include <ITapiSim.h>
1476  * int err_code = 0;
1477  * TelSimIccIdInfo_t icc_data; // this struct consists of number length and number.
1478  * err_code = tel_get_sim_iccid(&icc_data);
1479  * @endcode
1480  *
1481  * @remarks None
1482  *
1483  */
1484 /*================================================================================================*/
1485 int tel_get_sim_iccid(TelSimIccIdInfo_t* iccid);
1486
1487
1488 /**
1489  * @brief  This API is used to get the SIM mailbox related data(EF-MBDN, MBDI and CPHS case).
1490  * this data is required for Mailbox related functionality in handset.
1491  *
1492  * @par Sync (or) Async:
1493  * This is a synchronous function.
1494  *
1495  * @par Important Notes:
1496  * - None
1497  *
1498  * @warning
1499  * - None.
1500  *
1501  * @param [out] mbox
1502  *   - mailbox number information in current inserted SIM card. Refer #TelSimMailboxNumbers_s
1503  *
1504  * @par Async Response Message:
1505  * - None
1506  *
1507  * @pre
1508  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1509  *  - None.
1510  *
1511  * @post
1512  *  - None.
1513  *
1514  * @return Return Type (int) \n
1515  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1516  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1517  *
1518  * @par Prospective Clients:
1519  * External Apps.
1520  *
1521  * @see None
1522  *
1523  * @code
1524  * #include <ITapiSim.h>
1525  * TelSimMailboxNumbers_s mbox;
1526  * TapiResult_t err_code = 0;
1527  * err_code = tel_get_sim_mailbox_info(&mbox);
1528  * if(err_code == TAPI_API_SUCCESS) {
1529  *   if(mbox.b_cphs) { //b_cphs means current SIM is for CPHS or not.
1530  *     printf("Current SIM is CPHS");
1531  *   } else {
1532  *     printf("Current SIM is not CPHS but 3GPP");
1533  *   }
1534  * } else {
1535  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
1536  * }
1537  * @endcode
1538  *
1539  * @remarks None
1540  *
1541  */
1542 /*================================================================================================*/
1543 int tel_get_sim_mailbox_info(TelSimMailboxNumbers_s *mbox);
1544
1545 /**
1546  * @brief  This API is used to get the SIM Call forwarding indication related data(EF-CFIS and CPHS case).
1547  * this data is required for Call forwarding related functionality in handset.
1548  *
1549  * @par Sync (or) Async:
1550  * This is a synchronous function.
1551  *
1552  * @par Important Notes:
1553  * - None
1554  *
1555  * @warning
1556  * - None
1557  *
1558  * @param [out] cf
1559  *  - Callforwarding number information in current inserted SIM card. Refer #TelSimCallForwarding_s
1560  *  - User should check 'b_cphs' value first before refer union data struct.
1561  *
1562  * @par Async Response Message:
1563  * - None
1564  *
1565  * @pre
1566  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1567  *  - None
1568  *
1569  * @post
1570  *  - None
1571  *
1572  * @return Return Type (int) \n
1573  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1574  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1575  *
1576  * @par Prospective Clients:
1577  * External Apps
1578  *
1579  * @see None
1580  *
1581  * @code
1582  * #include <ITapiSim.h>
1583  * TelSimCallForwarding_s cf_data;
1584  * TapiResult_t err_code = 0;
1585  * err_code = tel_get_sim_callforwarding_info(&cf_data);
1586  * if(err_code == TAPI_API_SUCCESS) {
1587  *   if(cf_data.b_cphs) { //b_cphs means current SIM is for CPHS or not.
1588  *     printf("Current SIM is CPHS");
1589  *   } else {
1590  *     printf("Current SIM is not CPHS but 3GPP");
1591  *   }
1592  * } else {
1593  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
1594  * }
1595  * @endcode
1596  *
1597  * @remarks None
1598  *
1599  */
1600 /*================================================================================================*/
1601 int tel_get_sim_callforwarding_info(TelSimCallForwarding_s *cf);
1602
1603 /**
1604  * @brief  This API is used to get the SIM message waiting indication related data(EF-MWIS and CPHS case).
1605  * this data is required for Message waiting related functionality in handset.
1606  *
1607  * @par Sync (or) Async:
1608  * This is a synchronous function.
1609  *
1610  * @par Important Notes:
1611  * - None
1612  *
1613  * @warning
1614  * - None
1615  *
1616  * @param [out] mw
1617  *  - Message waiting count and type information in current inserted SIM card. Refer #TelSimMessageWaiting_s
1618  *  - User should check 'b_cphs' value first before refer union data struct.
1619  *
1620  * @par Async Response Message:
1621  * - None
1622  *
1623  * @pre
1624  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1625  *  - None
1626  *
1627  * @post
1628  *  - None
1629  *
1630  * @return Return Type (int) \n
1631  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1632  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1633  *
1634  * @par Prospective Clients:
1635  * External Apps
1636  *
1637  * @see None
1638  *
1639  * @code
1640  * #include <ITapiSim.h>
1641  * TelSimMessageWaiting_s mw_data;
1642  * TapiResult_t err_code = 0;
1643  * err_code = tel_get_sim_messagewaiting_info(&mw_data);
1644  * if(err_code == TAPI_API_SUCCESS) {
1645  *   if(mw_data.b_cphs) { //b_cphs means current SIM is for CPHS or not.
1646  *     printf("Current SIM is CPHS");
1647  *   } else {
1648  *     printf("Current SIM is not CPHS but 3GPP");
1649  *   }
1650  * } else {
1651  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
1652  * }
1653  * @endcode
1654  *
1655  * @remarks None
1656  *
1657  */
1658 /*================================================================================================*/
1659 int tel_get_sim_messagewaiting_info(TelSimMessageWaiting_s *mw);
1660
1661 /**
1662  * @brief  This API is used to get the SIM CPHS specific data.
1663  * this data is required for CPHS related functionality in handset.
1664  *
1665  * @par Sync (or) Async:
1666  * This is an Synchronous API.
1667  *
1668  * @par Important Notes:
1669  * - None
1670  *
1671  * @warning
1672  * - None
1673  *
1674  * @param [out] cphs
1675  *   - CPHS specific data(CPHS info table, service number, operator name, etc). Refer #TelSimCphsLocalInfo_t
1676  *
1677  * @par Async Response Message:
1678  * - None
1679  *
1680  * @pre
1681  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1682  *
1683  * @post
1684  *  - None
1685  *
1686  * @return Return Type (int) \n
1687  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1688  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1689  *
1690  * @par Prospective Clients:
1691  * External Apps
1692  *
1693  * @see None
1694  *
1695  * @code
1696  * #include <ITapiSim.h>
1697  * TelSimCphsLocalInfo_t cphs_data;
1698  * TapiResult_t err_code = 0;
1699  * err_code = tel_get_sim_cphs_info(&cphs_data);
1700  * if(err_code == TAPI_API_SUCCESS) {
1701  *   if(cphs_data.b_used) { //b_used means current SIM is for CPHS or not.
1702  *     printf("Current SIM is CPHS");
1703  *   } else {
1704  *     printf("Current SIM is not CPHS but 3GPP");
1705  *   }
1706  * } else {
1707  *   printf("TAPI API FAIL: Error Code [0x%x]",err_code);
1708  * }
1709  * @endcode
1710  *
1711  * @remarks None
1712  *
1713  */
1714 /*================================================================================================*/
1715 int tel_get_sim_cphs_info(TelSimCphsLocalInfo_t *cphs);
1716
1717
1718 /**
1719  * @brief  This API is used to get the SIM MSISDN data. Regarding 3GPP specification, Current value is optional.
1720  *
1721  * @par Sync (or) Async:
1722  * This is an Synchronous API.
1723  *
1724  * @par Important Notes:
1725  * - None
1726  *
1727  * @warning
1728  * - None
1729  *
1730  * @param [out] subscriber
1731  *   - subscriber information. if current SIM card does not have, null string will be returned. Refer #TelSimSubscriberInfo_t
1732  *
1733  * @par Async Response Message:
1734  * - None
1735  *
1736  * @pre
1737  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1738  *
1739  * @post
1740  *  - None
1741  *
1742  * @return Return Type (int) \n
1743  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1744  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1745  *
1746  * @par Prospective Clients:
1747  * External Apps
1748  *
1749  * @see None
1750  *
1751  * @code
1752  * #include <ITapiSim.h>
1753  * TelSimSubscriberInfo_t msisdn;
1754  * TapiResult_t err_code = 0;
1755  * err_code = tel_get_sim_msisdn(&msisdn);
1756  * if(err_code == TAPI_API_SUCCESS)
1757  * {
1758  *       printf(" ============================================");
1759  *       printf("name[%s]",msisdn.name);
1760  *       printf("num[%s]",msisdn.num);
1761  *       if(msisdn.name == '\0';) //If current SIM does not have, Null string will be returned.
1762  *               printf("name is null string");
1763  *
1764  *       if(msisdn.num == '\0';) //If current SIM does not have, Null string will be returned.
1765  *               printf("number is null string");
1766  * }
1767  * else
1768  * {
1769  *       printf("TAPI API FAIL: Error Code [0x%x]",err_code);
1770  * }
1771  *
1772  * @endcode
1773  *
1774  * @remarks None
1775  *
1776  */
1777 /*================================================================================================*/
1778 int tel_get_sim_msisdn(TelSimSubscriberInfo_t *subscriber);
1779
1780 /**
1781  * @brief  This function is used to get current inserted SIM phonebook init status, available phonebook list and first valid index in case of FDN, ADN, 3G phonebook.
1782  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
1783  *
1784  * @par Sync (or) Async:
1785  * This is an synchronous API.
1786  *
1787  * @par Important Notes:
1788  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
1789  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
1790  * pb_list and first_index value are available at init_completed status is '1' only.
1791  *
1792  * @warning
1793  * - None.
1794  *
1795  * @param [out] init_completed
1796  *   - phonebook init status. '0' is not init, '1' is init complete to use.
1797  *
1798  * @param [out] pb_list
1799  *   - available SIM phonebook list. This value is valid in phonebook init complete case.
1800  *
1801  * @param [out] first_index
1802  *   - first valid index to use.  only ADN, 3G phonebook and FDN case. This value is valid in phonebook init complete case.
1803  *
1804  * @par Async Response Message:
1805  * - None.
1806  *
1807  * @pre
1808  *  - None.
1809  *
1810  * @post
1811  *  - None.
1812  *
1813  * @return Return Type (int) \n
1814  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1815  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1816  *
1817  * @par Prospective Clients:
1818  * External Apps.
1819  *
1820  * @see None
1821  *
1822  * @code
1823  * #include <ITapiSim.h>
1824  * int err_code = 0;
1825  * int valid_index = 0; // usim or sim adn first valid index
1826  * TelSimPbList_t pb_list = {0,};
1827  * int pPbInitCompleted = 0; // init or not
1828  *
1829  * // GET SIM PHONEBOOK INIT INFORMATION
1830  * err_code = tel_get_sim_pb_init_info(&pPbInitCompleted, &pb_list, &valid_index);
1831  * @endcode
1832  *
1833  * @remarks None
1834  *
1835  */
1836 /*================================================================================================*/
1837 int tel_get_sim_pb_init_info(int *init_completed, TelSimPbList_t *pb_list, int *first_index);
1838
1839
1840 /**
1841  * @brief  This API is used to get number of used records and total records in specific SIM phonebook type.
1842  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
1843  *
1844  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1845  * However it just means that the API request has been transfered to the CP successfully.
1846  * The actual operation result is being delivered in the corresponding event asynchronously.
1847  *
1848  * @par Sync (or) Async:
1849  * This is an Asynchronous API.
1850  *
1851  * @par Important Notes:
1852  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
1853  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
1854  *
1855  * @warning
1856  * - None.
1857  *
1858  *
1859  * @param[in] pb_type
1860  * -Different storage types to be selected in SIM. #TelSimPbFileType_t
1861  *
1862  * @param [out] req_id
1863  *   - Unique identifier for a particular request.
1864  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
1865  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
1866  *
1867  * @par Async Response Message:
1868  * The event associated is TAPI_EVENT_SIM_PB_STORAGE_COUNT_CNF  and the event data is #TelSimPbStorageInfo_t.
1869  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
1870  *
1871  * @pre
1872  *  - A dbus connection is established with #tel_init
1873  *  - The application name is registered with #tel_register_app_name
1874  *  - The application is registered events to listen asynchronous response with #tel_register_event
1875  *  - A event loop is running to listen events
1876  *
1877  * @post
1878  *  - None.
1879  *
1880  * @return Return Type (int) \n
1881  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1882  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1883  *
1884  * @par Prospective Clients:
1885  * External Apps.
1886  *
1887  * @see None
1888  *
1889  * @code
1890  * #include <ITapiSim.h>
1891  * int err_code = 0;
1892  * int request_id = 0;
1893  * TelSimPbFileType_t storage_type = 0x00;
1894  * storage_type = TAPI_SIM_PB_3GSIM; // usim phonebook
1895  * err_code = tel_get_sim_pb_count(storage_type, &request_id);
1896  * @endcode
1897  *
1898  * @remarks None
1899  *
1900  */
1901 /*================================================================================================*/
1902 int tel_get_sim_pb_count(TelSimPbFileType_t pb_type, int* req_id);
1903
1904
1905 /**
1906  * @brief  This API is used to get max text length and max number length supported by SIM phone book elementary file.
1907  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
1908  *
1909  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1910  * However it just means that the API request has been transfered to the CP successfully.
1911  * The actual operation result is being delivered in the corresponding event asynchronously.
1912  *
1913  * @par Sync (or) Async:
1914  * This is an Asynchronous API.
1915  *
1916  * @par Important Notes:
1917  * - The max number length includes the storage space provided by the corresponding EXT file for a given Dialling Number file.
1918  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
1919  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
1920  *
1921  * @warning
1922  * - None.
1923  *
1924  * @param[in] pb_type
1925  * -Different storage types to be selected in SIM. #TelSimPbFileType_t
1926  *
1927  * @param [out] req_id
1928  *   - Unique identifier for a particular request.
1929  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
1930  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
1931  *
1932  * @par Async Response Message:
1933  * The event associated is TAPI_EVENT_SIM_PB_ENTRY_INFO_CNF  and the event data is #TelSimPbEntryInfo_t.
1934  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
1935  *
1936  * @pre
1937  *  - A dbus connection is established with #tel_init
1938  *  - The application name is registered with #tel_register_app_name
1939  *  - The application is registered events to listen asynchronous response with #tel_register_event
1940  *  - A event loop is running to listen events
1941  *
1942  * @post
1943  *  - None.
1944  *
1945  * @return Return Type (int) \n
1946  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
1947  * - Negative integer : it provides an error code (Refer #TapiResult_t)
1948  *
1949  * @par Prospective Clients:
1950  * External Apps.
1951  *
1952  * @see None
1953  *
1954  * @code
1955  * #include <ITapiSim.h>
1956  * int err_code = 0;
1957  * int request_id = 0;
1958  * TelSimPbFileType_t storage_type = 0x00;
1959  * storage_type = TAPI_SIM_PB_3GSIM; // usim phonebook
1960  * err_code = tel_get_sim_pb_meta_info(storage_type, &request_id);
1961  * @endcode
1962  *
1963  * @remarks None
1964  *
1965  */
1966 /*================================================================================================*/
1967 int tel_get_sim_pb_meta_info(TelSimPbFileType_t pb_type, int* req_id);
1968
1969
1970 /**
1971  * @brief  This API is used to get SIM 3G phonebook supported EFs like ANR, SNE, GRP, EMAIL etc and corresponding EFs max text length, number length and size.
1972  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
1973  *
1974  * This function makes Dbus method call to Telephony Sever and returns immediate value.
1975  * However it just means that the API request has been transfered to the CP successfully.
1976  * The actual operation result is being delivered in the corresponding event asynchronously.
1977  *
1978  * @par Sync (or) Async:
1979  * This is an Asynchronous API.
1980  *
1981  * @par Important Notes:
1982  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
1983  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
1984  *
1985  * @warning
1986  * - None.
1987  *
1988  * @param [out] req_id
1989  *   - Unique identifier for a particular request.
1990  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
1991  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
1992  *
1993  * @par Async Response Message:
1994  * - The event associated is TAPI_SIM_EVENT_PB_3G_CAPABILITY_INFO_CNF  and the event data is #TelSimPbCapabilityInfo_t.
1995  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
1996  *
1997  * @pre
1998  *  - A dbus connection is established with #tel_init
1999  *  - The application name is registered with #tel_register_app_name
2000  *  - The application is registered events to listen asynchronous response with #tel_register_event
2001  *  - A event loop is running to listen events
2002  *
2003  * @post
2004  *  - None.
2005  *
2006  * @return Return Type (int) \n
2007  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2008  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2009  *
2010  * @par Prospective Clients:
2011  * External Apps.
2012  *
2013  * @see None
2014  *
2015  * @code
2016  * #include <ITapiSim.h>
2017  * int err_code = 0;
2018  * int request_id = 0;
2019  * err_code = tel_get_sim_pb_3g_meta_info(&request_id); // you can find result by receiving asynch event response
2020  * @endcode
2021  *
2022  * @remarks None
2023  *
2024  */
2025 /*================================================================================================*/
2026 int tel_get_sim_pb_3g_meta_info(int *req_id);
2027
2028
2029 /**
2030  * @brief  This API is used to read SIM phone book entry information from given storage type.
2031  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
2032  *
2033  * This function makes Dbus method call to Telephony Sever and returns immediate value.
2034  * However it just means that the API request has been transfered to the CP successfully.
2035  * The actual operation result is being delivered in the corresponding event asynchronously.
2036  *
2037  * @par Sync (or) Async:
2038  * This is an Asynchronous API.
2039  *
2040  * @par Important Notes:
2041  * - The index ranges from 1 through to a maximum of 254 for a Linear fixed file and 255 for a cyclic file.
2042  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
2043  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
2044  *
2045  * @warning
2046  * - None.
2047  *
2048  * @param[in] pb_type
2049  * -Different storage types to be selected in SIM. ##TelSimPbFileType_t
2050  *
2051  * @param[in] index
2052  * -Index for accessing the SIM data.
2053  *
2054  * @param [out] req_id
2055  *   - Unique identifier for a particular request.
2056  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
2057  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
2058  *
2059  * @par Async Response Message:
2060  * The event associated is TAPI_EVENT_SIM_PB_ACCESS_READ_CNF  and the event data is #TelSimPbRecordData_t.
2061  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
2062  *
2063  * @pre
2064  *  - A dbus connection is established with #tel_init
2065  *  - The application name is registered with #tel_register_app_name
2066  *  - The application is registered events to listen asynchronous response with #tel_register_event
2067  *  - A event loop is running to listen events
2068  *
2069  * @post
2070  *  - None.
2071  *
2072  * @return Return Type (int) \n
2073  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2074  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2075  *
2076  * @par Prospective Clients:
2077  * External Apps.
2078  *
2079  * @see None
2080  *
2081  * @code
2082  * #include <ITapiSim.h>
2083  * int err_code = 0;
2084  * int request_id = 0;
2085  * unsigned short index = 1;
2086  * TelSimPbFileType_t storage_type = 0x00;
2087  * storage_type = TAPI_SIM_PB_3GSIM; // usim phonebook
2088  * err_code = tel_read_sim_pb_record(storage_type, index, &request_id);
2089  * @endcode
2090  *
2091  * @remarks None
2092  *
2093  */
2094 /*================================================================================================*/
2095 int tel_read_sim_pb_record(TelSimPbFileType_t pb_type, unsigned short index, int *req_id );
2096
2097
2098 /**
2099  * @brief  This API is used to add or edit SIM phone book record entry information.
2100  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
2101  *
2102  * This function makes Dbus method call to Telephony Sever and returns immediate value.
2103  * However it just means that the API request has been transfered to the CP successfully.
2104  * The actual operation result is being delivered in the corresponding event asynchronously.
2105  *
2106  * @par Sync (or) Async:
2107  * This is an Asynchronous API.
2108  *
2109  * @par Important Notes:
2110  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
2111  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
2112  *
2113  * @warning
2114  * - None.
2115  *
2116  * @param[in] req_data
2117  * -phonebook data which will be updated or added. #TelSimPbRecordData_t
2118  *
2119  * @param [out] req_id
2120  *   - Unique identifier for a particular request.
2121  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
2122  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
2123  *
2124  * @par Async Response Message:
2125  * The event associated is TAPI_EVENT_SIM_PB_UPDATE_CNF  and the event data is #TelSimPbUpdateResp_t.
2126  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
2127  *
2128  * @pre
2129  *  - A dbus connection is established with #tel_init
2130  *  - The application name is registered with #tel_register_app_name
2131  *  - The application is registered events to listen asynchronous response with #tel_register_event
2132  *  - A event loop is running to listen events
2133  *
2134  * @post
2135  *  - None.
2136  *
2137  * @return Return Type (int) \n
2138  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2139  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2140  *
2141  * @par Prospective Clients:
2142  * External Apps.
2143  *
2144  * @see None
2145  *
2146  * @code
2147  * #include <ITapiSim.h>
2148  * int err_code = 0;
2149  * int request_id = 0;
2150  * unsigned short index = 1;
2151  * TelSimPbRecordData_t data;
2152  * data.StorageFileType  = TAPI_SIM_PB_3GSIM; // usim phonebook
2153  * data.Index  = 1; // index which will be updated
2154  * data.NextIndex  = 0;
2155  * //data.ContactInfo will be added
2156  * err_code = tel_update_sim_pb_record(&data, &request_id);
2157  * @endcode
2158  *
2159  * @remarks None
2160  *
2161  */
2162 /*================================================================================================*/
2163 int tel_update_sim_pb_record(const TelSimPbRecordData_t *req_data, int *req_id );
2164
2165
2166 /**
2167  * @brief  This API is used to delete a SIM phonebook record.
2168  *      Access to this API is limited to in-house application and we recommend you use phonebook-engine APIs.
2169  *
2170  * This function makes Dbus method call to Telephony Sever and returns immediate value.
2171  * However it just means that the API request has been transfered to the CP successfully.
2172  * The actual operation result is being delivered in the corresponding event asynchronously.
2173  *
2174  * @par Sync (or) Async:
2175  * This is an Asynchronous API.
2176  *
2177  * @par Important Notes:
2178  * - The index ranges from 1 through to a maximum of 254 for a Linear fixed file and 255 for a cyclic file.
2179  * - We recommend to use phonebook-engine APIs for handling phonebook(including SIM phonebook).
2180  * If user uses SIM phonebook related APIs directly, it can break device phonebook consistency because all phonebook information managed in phonebook-engine.
2181  *
2182  * @warning
2183  * - None.
2184  *
2185  * @param[in] pb_type
2186  * -Different storage types to be selected in SIM. #TelSimPbFileType_t
2187  *
2188  * @param[in] index
2189  * -Index of the record to be deleted.
2190  *
2191  * @param [out] req_id
2192  *   - Unique identifier for a particular request.
2193  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
2194  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
2195  *
2196  * @par Async Response Message:
2197  * The event associated is TAPI_EVENT_SIM_PB_DELETE_CNF  and the event data is #TelSimPbUpdateResp_t.
2198  * Asynchronous return status is indicated by #TelSimPbAccessResult_t.
2199  *
2200  * @pre
2201  *  - A dbus connection is established with #tel_init
2202  *  - The application name is registered with #tel_register_app_name
2203  *  - The application is registered events to listen asynchronous response with #tel_register_event
2204  *  - A event loop is running to listen events
2205  *
2206  * @post
2207  *  - None.
2208  *
2209  * @return Return Type (int) \n
2210  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2211  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2212  *
2213  * @par Prospective Clients:
2214  * External Apps.
2215  *
2216  * @see None
2217  *
2218  * @code
2219  * #include <ITapiSim.h>
2220  * int err_code = 0;
2221  * int request_id = 0;
2222  * unsigned short index = 1;
2223  * TelSimPbFileType_t storage_type = 0x00;
2224  * storage_type = TAPI_SIM_PB_3GSIM; // usim phonebook
2225  * err_code = tel_delete_sim_pb_record(storage_type, index, &request_id);
2226  * @endcode
2227  *
2228  * @remarks None
2229  *
2230  */
2231 /*================================================================================================*/
2232 int tel_delete_sim_pb_record(TelSimPbFileType_t pb_type, unsigned short index, int *req_id );
2233
2234
2235 /**
2236  * @brief  This function is used to make a connection request to SIM
2237  *      Access to this API is limited to in-house application and we recommend you use bluetooth-engine APIs.
2238  *
2239  * This function makes Dbus method call to Telephony Sever and returns immediate value.
2240  * However it just means that the API request has been transfered to the CP successfully.
2241  * The actual operation result is being delivered in the corresponding event asynchronously.
2242  *
2243  * @par Sync (or) Async:
2244  * This is an Asynchronous API.
2245  *
2246  * @par Important Notes:
2247  * - We recommend user does not use SAP related APIs directly. Our SAP APIs are provided as interface between BT-engine and Modem Plugin.
2248  * So without BT-engine, you may not get proper operation with these SAP APIs.
2249  *
2250  * @warning
2251  * - None.
2252  *
2253  * @param[in] req_data
2254  * - This input has the SAP message request to connect. #TelSimSapConnect_t
2255  *
2256  * @param [out] req_id
2257  *   - Unique identifier for a particular request.
2258  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
2259  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
2260  *
2261  * @par Async Response Message:
2262  * -The event associated is TAPI_SIM_EVENT_SAP_CONNECT_CNF  and the event data is #TelSimSapConnect_t.
2263  * Asynchronous return status is indicated by #TelSimAccessResult_t.
2264  *
2265  * @pre
2266  *  - A dbus connection is established with #tel_init
2267  *  - The application name is registered with #tel_register_app_name
2268  *  - The application is registered events to listen asynchronous response with #tel_register_event
2269  *  - A event loop is running to listen events
2270  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
2271  *
2272  * @post
2273  *  - None.
2274  *
2275  * @return Return Type (int) \n
2276  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2277  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2278  *
2279  * @par Prospective Clients:
2280  * External Apps.
2281  *
2282  * @see None
2283  *
2284  * @code
2285  * #include <ITapiSim.h>
2286  * int err_code = 0;
2287  * int request_id = 0;
2288  * TelSimSapConnect_t con_req = {0,};
2289  * con_req.MsgId = TAPI_SIM_SAP_CONNECT_REQ;    // connection req id
2290  * con_req.MaxMsgSize = 10; //temp for testing only - not clear
2291  * err_code = tel_req_sap_connection(&con_req, &request_id);
2292  * @endcode
2293  *
2294  * @remarks None
2295  *
2296  */
2297 /*================================================================================================*/
2298 int tel_req_sap_connection( TelSimSapConnect_t *req_data, int *req_id);
2299
2300
2301 /**
2302  * @brief  This function is used to get connection status information
2303  *      Access to this API is limited to in-house application and we recommend you use bluetooth-engine APIs.
2304  *
2305  * This function makes Dbus method call to Telephony Sever and returns immediate value.
2306  * However it just means that the API request has been transfered to the CP successfully.
2307  * The actual operation result is being delivered in the corresponding event asynchronously.
2308  *
2309  * @par Sync (or) Async:
2310  * This is an Asynchronous API.
2311  *
2312  * @par Important Notes:
2313  * - We recommend user does not use SAP related APIs directly. Our SAP APIs are provided as interface between BT-engine and Modem Plugin.
2314  * So without BT-engine, you may not get proper operation with these SAP APIs.
2315  *
2316  * @warning
2317  * - None.
2318  *
2319  * @param [out] req_id
2320  *   - Unique identifier for a particular request.
2321  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
2322  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
2323  *
2324  * @par Async Response Message:
2325  * -The event associated is TAPI_SIM_EVENT_SAP_CONNECT_STATUS_CNF  and the event data is #TelSimSapConnectionStatus_t.
2326  * Asynchronous return status is indicated by #TelSimAccessResult_t.
2327  *
2328  *
2329  * @pre
2330  *  - A dbus connection is established with #tel_init
2331  *  - The application name is registered with #tel_register_app_name
2332  *  - The application is registered events to listen asynchronous response with #tel_register_event
2333  *  - A event loop is running to listen events
2334  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
2335  *
2336  * @post
2337  *  - None.
2338  *
2339  * @return Return Type (int) \n
2340  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2341  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2342  *
2343  * @par Prospective Clients:
2344  * External Apps.
2345  *
2346  * @see None
2347  *
2348  * @code
2349  * #include <ITapiSim.h>
2350  * int err_code = 0;
2351  * int request_id = 0;
2352  * err_code = tel_req_sap_connection_status(&request_id);       //you can find status value by receiving async event value
2353  * @endcode
2354  *
2355  * @remarks None
2356  *
2357  */
2358 /*================================================================================================*/
2359 int tel_req_sap_connection_status( int *req_id);
2360
2361
2362 /**
2363  * @brief  This function is used to get ATR request from SIM
2364  *      Access to this API is limited to in-house application and we recommend you use bluetooth-engine APIs.
2365  *
2366  * This function makes Dbus method call to Telephony Sever and returns immediate value.
2367  * However it just means that the API request has been transfered to the CP successfully.
2368  * The actual operation result is being delivered in the corresponding event asynchronously.
2369  *
2370  * @par Sync (or) Async:
2371  * This is an Asynchronous API.
2372  *
2373  * @par Important Notes:
2374  * - We recommend user does not use SAP related APIs directly. Our SAP APIs are provided as interface between BT-engine and Modem Plugin.
2375  * So without BT-engine, you may not get proper operation with these SAP APIs.
2376  *
2377  * @warning
2378  * - None.
2379  *
2380  * @param [out] req_id
2381  *   - Unique identifier for a particular request.
2382  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
2383  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
2384  *
2385  * @par Async Response Message:
2386  * -The event associated is TAPI_SIM_EVENT_SAP_TRANSFER_ATR_CNF  and the event data is #TelSimSapAtrInfo_t.
2387  * Asynchronous return status is indicated by #TelSimAccessResult_t.
2388  *
2389  *
2390  * @pre
2391  *  - A dbus connection is established with #tel_init
2392  *  - The application name is registered with #tel_register_app_name
2393  *  - The application is registered events to listen asynchronous response with #tel_register_event
2394  *  - A event loop is running to listen events
2395  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
2396  *
2397  * @post
2398  *  - None.
2399  *
2400  * @return Return Type (int) \n
2401  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2402  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2403  *
2404  * @par Prospective Clients:
2405  * External Apps.
2406  *
2407  * @see None
2408  *
2409  * @code
2410  * #include <ITapiSim.h>
2411  * int err_code = 0;
2412  * int request_id = 0;
2413  * err_code = tel_req_sap_transfer_atr(&request_id);    //you can find transfer atr request resut with async event
2414  * @endcode
2415  *
2416  * @remarks None
2417  *
2418  */
2419 /*================================================================================================*/
2420 int tel_req_sap_transfer_atr( int *req_id);
2421
2422
2423 /**
2424  * @brief  This function is used to transfer APDU to SIM
2425  *      Access to this API is limited to in-house application and we recommend you use bluetooth-engine APIs.
2426  *
2427  * This function makes Dbus method call to Telephony Sever and returns immediate value.
2428  * However it just means that the API request has been transfered to the CP successfully.
2429  * The actual operation result is being delivered in the corresponding event asynchronously.
2430  *
2431  * @par Sync (or) Async:
2432  * This is an Asynchronous API.
2433  *
2434  * @par Important Notes:
2435  * - We recommend user does not use SAP related APIs directly. Our SAP APIs are provided as interface between BT-engine and Modem Plugin.
2436  * So without BT-engine, you may not get proper operation with these SAP APIs.
2437  *
2438  * @warning
2439  * - None.
2440  *
2441  * @param[in] apdu_data
2442  * - This input has the APDU data to be passed to SIM card. #TelSimSapApduData_t
2443  *
2444  * @param [out] req_id
2445  *   - Unique identifier for a particular request.
2446  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
2447  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
2448  *
2449  * @par Async Response Message:
2450  * -The event associated is TAPI_SIM_EVENT_SAP_TRANSFER_APDU_CNF  and the event data is #TelSimSapApduData_t.
2451  * Asynchronous return status is indicated by #TelSimAccessResult_t.
2452  *
2453  *
2454  * @pre
2455  *  - A dbus connection is established with #tel_init
2456  *  - The application name is registered with #tel_register_app_name
2457  *  - The application is registered events to listen asynchronous response with #tel_register_event
2458  *  - A event loop is running to listen events
2459  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
2460  *
2461  * @post
2462  *  - None.
2463  *
2464  * @return Return Type (int) \n
2465  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2466  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2467  *
2468  * @par Prospective Clients:
2469  * External Apps.
2470  *
2471  * @see None
2472  *
2473  * @code
2474  * #include <ITapiSim.h>
2475  * int err_code = 0;
2476  * int request_id = 0;
2477  * int file_id = TAPI_SIM_EFILE_ICCID;
2478  * TelSimSapApduData_t apdu_data;       // for selecting EF ICCID
2479  * apdu_data.ApduLength = 7;
2480  * apdu_data.Apdu[0] = 0xA0; // class
2481  * apdu_data.Apdu[1] = 0xA4; // instruction
2482  * apdu_data.Apdu[2] = 0; // p1 = parameter 1
2483  * apdu_data.Apdu[3] = 0; // p2 = parameter 2
2484  * apdu_data.Apdu[4] = 2; // p3 - parameter 3
2485  * memcpy(&apdu_data.Apdu[5], &file_id, sizeof(unsigned short));
2486  * err_code = tel_req_sap_transfer_apdu(&apdu_data, &request_id);
2487  * @endcode
2488  *
2489  * @remarks None
2490  *
2491  */
2492 /*================================================================================================*/
2493 int tel_req_sap_transfer_apdu(TelSimSapApduData_t *apdu_data, int *req_id);
2494
2495
2496 /**
2497  * @brief       This function is used to select either of the protocols.
2498  *      Access to this API is limited to in-house application and we recommend you use bluetooth-engine APIs.
2499  *
2500  * This function makes Dbus method call to Telephony Sever and returns immediate value.
2501  * However it just means that the API request has been transfered to the CP successfully.
2502  * The actual operation result is being delivered in the corresponding event asynchronously.
2503  *
2504  * @par Sync (or) Async:
2505  * This is an Asynchronous API.
2506  *
2507  * @par Important Notes:
2508  * - We recommend user does not use SAP related APIs directly. Our SAP APIs are provided as interface between BT-engine and Modem Plugin.
2509  * So without BT-engine, you may not get proper operation with these SAP APIs.
2510  *
2511  * @warning
2512  * - None.
2513  *
2514  * @param[in] protocol
2515  * - This input is the protocol to set in SIM for SAP. #TelSimSapProtocol_t
2516  *
2517  * @param [out] req_id
2518  *   - Unique identifier for a particular request.
2519  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
2520  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
2521  *
2522  * @par Async Response Message:
2523  * -The event associated is TAPI_SIM_EVENT_SAP_SET_PROTOCOL_CNF  and the event data is #TelSimSapResultCode_t.
2524  * Asynchronous return status is indicated by #TelSimAccessResult_t.
2525  *
2526  *
2527  * @pre
2528  *  - A dbus connection is established with #tel_init
2529  *  - The application name is registered with #tel_register_app_name
2530  *  - The application is registered events to listen asynchronous response with #tel_register_event
2531  *  - A event loop is running to listen events
2532  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
2533  *
2534  * @post
2535  *  - None.
2536  *
2537  * @return Return Type (int) \n
2538  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2539  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2540  *
2541  * @par Prospective Clients:
2542  * External Apps.
2543  *
2544  * @see None
2545  *
2546  * @code
2547  * #include <ITapiSim.h>
2548  * int err_code = 0;
2549  * int request_id = 0;
2550  * TelSimSapProtocol_t protocol = TAPI_SIM_SAP_PROTOCOL_T0; // protocol set
2551  * err_code = tel_req_sap_transport_protocol(protocol, &request_id);
2552  * @endcode
2553  *
2554  * @remarks None
2555  *
2556  */
2557 /*================================================================================================*/
2558 int tel_req_sap_transport_protocol(TelSimSapProtocol_t protocol, int *req_id);
2559
2560
2561 /**
2562  * @brief  This function is used to set the power ON/OFF/RESET the SIM card
2563  *      Access to this API is limited to in-house application and we recommend you use bluetooth-engine APIs.
2564  *
2565  * This function makes Dbus method call to Telephony Sever and returns immediate value.
2566  * However it just means that the API request has been transfered to the CP successfully.
2567  * The actual operation result is being delivered in the corresponding event asynchronously.
2568  *
2569  * @par Sync (or) Async:
2570  * This is an Asynchronous API.
2571  *
2572  * @par Important Notes:
2573  * - We recommend user does not use SAP related APIs directly. Our SAP APIs are provided as interface between BT-engine and Modem Plugin.
2574  * So without BT-engine, you may not get proper operation with these SAP APIs.
2575  *
2576  * @warning
2577  * - None.
2578  *
2579  * @param[in] req_data
2580  * - This input is to power on or off the SIM card.#TelSimSapMsgId_t
2581  *
2582  * @param [out] req_id
2583  *   - Unique identifier for a particular request.
2584  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
2585  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
2586  *
2587  * @par Async Response Message:
2588  * -The event associated is TAPI_SIM_EVENT_SAP_SET_SIM_POWER_CNF  and the event data is #TelSimSapPower_t.
2589  * Asynchronous return status is indicated by #TelSimAccessResult_t.
2590  *
2591  *
2592  * @pre
2593  *  - A dbus connection is established with #tel_init
2594  *  - The application name is registered with #tel_register_app_name
2595  *  - The application is registered events to listen asynchronous response with #tel_register_event
2596  *  - A event loop is running to listen events
2597  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
2598  *
2599  * @post
2600  *  - None.
2601  *
2602  * @return Return Type (int) \n
2603  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2604  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2605  *
2606  * @par Prospective Clients:
2607  * External Apps.
2608  *
2609  * @see None
2610  *
2611  * @code
2612  * #include <ITapiSim.h>
2613  * int err_code = 0;
2614  * int request_id = 0;
2615  * TelSimSapMsgId_t     msdId = 0;
2616  * msdId = TAPI_SIM_SAP_POWER_SIM_ON_REQ; //power on operation
2617  * err_code = tel_req_sap_power_operation(msdId, &request_id);// only for testing
2618  * @endcode
2619  *
2620  * @remarks None
2621  *
2622  */
2623 /*================================================================================================*/
2624 int tel_req_sap_power_operation(TelSimSapMsgId_t req_data, int *req_id );
2625
2626
2627 /**
2628  * @brief  This function is used to transfer card reader status
2629  *      Access to this API is limited to in-house application and we recommend you use bluetooth-engine APIs.
2630  *
2631  * This function makes Dbus method call to Telephony Sever and returns immediate value.
2632  * However it just means that the API request has been transfered to the CP successfully.
2633  * The actual operation result is being delivered in the corresponding event asynchronously.
2634  *
2635  * @par Sync (or) Async:
2636  * This is an Asynchronous API.
2637  *
2638  * @par Important Notes:
2639  * - We recommend user does not use SAP related APIs directly. Our SAP APIs are provided as interface between BT-engine and Modem Plugin.
2640  * So without BT-engine, you may not get proper operation with these SAP APIs.
2641  *
2642  * @warning
2643  * - None.
2644  *
2645  * @param [out] req_id
2646  *   - Unique identifier for a particular request.
2647  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
2648  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
2649  *
2650  * @par Async Response Message:
2651  * -The event associated is TAPI_SIM_EVENT_SAP_CARD_READER_STATUS_CNF  and the event data is #TelSimCardReaderStatus_t.
2652  * Asynchronous return status is indicated by #TelSimAccessResult_t.
2653  *
2654  *
2655  * @pre
2656  *  - A dbus connection is established with #tel_init
2657  *  - The application name is registered with #tel_register_app_name
2658  *  - The application is registered events to listen asynchronous response with #tel_register_event
2659  *  - A event loop is running to listen events
2660  *  - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
2661  *
2662  * @post
2663  *  - None.
2664  *
2665  * @return Return Type (int) \n
2666  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2667  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2668  *
2669  * @par Prospective Clients:
2670  * External Apps.
2671  *
2672  * @see None
2673  *
2674  * @code
2675  * #include <ITapiSim.h>
2676  * int err_code = 0;
2677  * int request_id = 0;
2678  * err_code = tel_req_sap_cardreader_status(&request_id);       //you can find card reader status with async event
2679  * @endcode
2680  *
2681  * @remarks None
2682  *
2683  */
2684 /*================================================================================================*/
2685 int tel_req_sap_cardreader_status(int *req_id);
2686
2687
2688 /**
2689  * @brief  This API is used to execute the authentication procedure by using SIM.
2690  *
2691  * This function makes Dbus method call to Telephony Sever and returns immediate value.
2692  * However it just means that the API request has been transfered to the CP successfully.
2693  * The actual operation result is being delivered in the corresponding event asynchronously.
2694  * This function supports IMS, 3G and GSM authentication.
2695  *
2696  * @par Sync (or) Async:
2697  * This is an Asynchronous API.
2698  *
2699  * @par Important Notes:
2700  * -NONE
2701  *
2702  * @warning
2703  * - None.
2704  *
2705  * @param[in] authentication_data
2706  * - This input has the authentication code to be validated by ISIM,3G and GSM application in the SIM card. #TelSimAuthenticationData_t
2707  *
2708  * @param [out] req_id
2709  *   - Unique identifier for a particular request.
2710  *   - request_id value can be any value from 0 to 255 if the API is returned successfully
2711  *   - -1 (INVALID_REQUEST_ID) will be sent in case of failure.
2712  *
2713  * @par Async Response Message:
2714  * -The event associated is TAPI_SIM_EVENT_AUTHENTICATION_CNF  and the event data is #TelSimAuthenticationResponse_t.
2715  * Asynchronous return status is indicated by #TelSimAccessResult_t.
2716  *
2717  *
2718  * @pre
2719  *  - A dbus connection is established with #tel_init
2720  *  - The application name is registered with #tel_register_app_name
2721  *  - The application is registered events to listen asynchronous response with #tel_register_event
2722  *  - A event loop is running to listen events
2723  *
2724  * @post
2725  *  - None.
2726  *
2727  * @return Return Type (int) \n
2728  * - Integer '0' ( same with TAPI_API_SUCCESS )  - indicating that the operation has completed successfully. \n
2729  * - Negative integer : it provides an error code (Refer #TapiResult_t)
2730  *
2731  * @par Prospective Clients:
2732  * External Apps.
2733  *
2734  * @see None
2735  *
2736  * @code
2737  * #include <ITapiSim.h>
2738  * int err_code = 0;
2739  * int request_id = 0;
2740  * TelSimAuthenticationData_t pAuthenticationData;
2741  * strcpy((char*)pAuthenticationData.rand_data, "username@operator.com"); //access data
2742  * pAuthenticationData.rand_length= strlen("username@operator.com");
2743  * strcpy((char*)pAuthenticationData.autn_data,  "+1-212-555-12345"); // auth data
2744  * pAuthenticationData.autn_length = strlen("+1-212-555-12345");
2745  * err_code = tel_req_sim_authentication(&pAuthenticationData,&request_id);
2746  * @endcode
2747  *
2748  * @remarks None
2749  *
2750  */
2751 /*================================================================================================*/
2752 int tel_req_sim_authentication( TelSimAuthenticationData_t *authentication_data, int *req_id);
2753
2754
2755 #ifdef __cplusplus
2756 }
2757 #endif
2758
2759 #endif  /* _ITAPI_SIM_H_ */
2760
2761 /**
2762 * @}
2763 */