4 * Copyright (c) 2012 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: Ja-young Gu <jygu@samsung.com>
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
23 * @ingroup TelephonyAPI
24 * @addtogroup SIM_TAPI SIM
29 * @brief This file serves as a "C" header file defines functions for Tapi SIM Services.
30 * It contains a sample set of function prototypes that would be required by applications.
36 #include <tapi_common.h>
39 #include <TelDefines.h>
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.
50 * @par Sync (or) Async:
51 * This is a Synchronous API.
53 * @par Important Notes:
54 * - Card Identification value is available in TAPI_SIM_STATUS_SIM_INIT_COMPLETED case only.
60 * - handle from tel_init().
62 * @param [out] sim_status
63 * - This parameter returns SIM initialization status from Telephony server boot up time.
64 * First, You can find sim existance if returned value are not in TAPI_SIM_STATUS_CARD_NOT_PRESENT and TAPI_SIM_STATUS_CARD_REMOVED.
66 * @param [out] card_changed
67 * - This parameter returns sim card identification value when sim_status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED.
68 * - card_changed value just present whether current inserted SIM card differs with previous SIM or not.
70 * @par Async Response Message:
79 * @return Return Type (int)
80 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
81 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
82 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
84 * @par Prospective Clients:
90 * #include <ITapiSim.h>
92 * int err_code = TAPI_API_SUCCESS;
93 * TelSimCardStatus_t status = 0x00;
94 * int b_card_changed = 0;
95 * TapiHandle *handle; // Handle given by tel_init()
97 * // GET SIM INIT INFORMATION
98 * err_code = tel_get_sim_init_info(handle, &status, &b_card_changed);
105 /*================================================================================================*/
106 int tel_get_sim_init_info(TapiHandle *handle, TelSimCardStatus_t *sim_status, int *card_changed);
109 * @brief This API is used to get the Card Type whether Card is a SIM or a USIM.
111 * @par Sync (or) Async:
112 * This is a Synchronous API.
114 * @par Important Notes:
121 * - handle from tel_init().
123 * @param [out] card_type
124 * This parameter returns the SIM card type information like whether it is GSM SIM card or USIM or it is of unknown type.
126 * - TAPI_SIM_CARD_TYPE_UNKNOWN
127 * - TAPI_SIM_CARD_TYPE_GSM
128 * - TAPI_SIM_CARD_TYPE_USIM
130 * @par Async Response Message:
139 * @return Return Type (int)
140 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
141 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
142 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
144 * @par Prospective Clients:
150 * #include <ITapiSim.h>
152 * TelSimCardType_t cardInfo; //unkwon, sim(normally gsm), usim(normally umts)
153 * TapiHandle *handle; // Handle given by tel_init()
155 * err_code = tel_get_sim_type(handle, &cardInfo);
162 /*================================================================================================*/
163 int tel_get_sim_type(TapiHandle *handle, TelSimCardType_t *card_type);
166 * @brief This API is used to get the IMSI information.
168 * @par Sync (or) Async:
169 * This is a Synchronous API.
171 * @par Important Notes:
172 * - IMSI value is the value that security needs.
178 * - handle from tel_init().
181 * This parameter returns the IMSI information. Refer #TelSimImsiInfo_t
183 * @par Async Response Message:
187 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
193 * @return Return Type (int)
194 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
195 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
196 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
198 * @par Prospective Clients:
204 * #include <ITapiSim.h>
206 * TelSimImsiInfo_t sim_imsi_info; // mcc, mnc, msisdn
207 * err_code = tel_get_sim_imsi(handle, &sim_imsi_info);
213 /*================================================================================================*/
214 int tel_get_sim_imsi(TapiHandle *handle, TelSimImsiInfo_t *imsi);
217 * @brief This API is used to get ECC(SIM) or UECC(USIM) data.
219 * @par Sync (or) Async:
220 * This is a Synchronous API.
222 * @par Important Notes:
229 * - handle from tel_init().
232 * - This parameter returns
233 * * * the SIM emergency call code information like ecc length, service type etc
234 * * * and number of ECC records.
236 * @par Async Response Message:
240 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
246 * @return Return Type (int)
247 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
248 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
249 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
251 * @par Prospective Clients:
257 * #include <ITapiSim.h>
259 * TelSimEccList_t ecc_info = {0}; // Get ECC list info and ecc_count
260 * err_code = tel_get_sim_ecc(handle, &ecc_info);
266 /*================================================================================================*/
267 int tel_get_sim_ecc(TapiHandle *handle, TelSimEccList_t *ecc);
270 * @brief This API is used to get Unique identification number of the (U)ICC.
271 * ICC means Integrated Circuit Card.
273 * @par Sync (or) Async:
274 * This is a Asynchronous API.
276 * @par Important Notes:
277 * - IC Card number value is the value that security needs.
283 * - handle from tel_init().
285 * @param [in] callback
286 * - To register callback function for result.
288 * @param [in] user_data
289 * - user_data for user specification.
291 * @par Async Response Message:
295 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
301 * @return Return Type (int)
302 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
303 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
304 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
306 * @par Prospective Clients:
312 * #include <ITapiSim.h>
314 * TapiHandle *handle; // Handle given by tel_init()
315 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
316 * void *user_data; // Set User data
317 * err_code = tel_get_sim_iccid(handle, callback, user_data);
323 /*================================================================================================*/
324 int tel_get_sim_iccid(TapiHandle *handle, tapi_response_cb callback, void *user_data);
327 * @brief This API is used to get the language preference(indication) information.
329 * @par Sync (or) Async:
330 * This is a Asynchronous API.
332 * @par Important Notes:
339 * - handle from tel_init().
341 * @param [in] callback
342 * - To register callback function for result.
344 * @param [in] user_data
345 * - user_data for user specification.
347 * @par Async Response Message:
351 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
357 * @return Return Type (int)
358 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
359 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
360 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
362 * @par Prospective Clients:
368 * #include <ITapiSim.h>
370 * TapiHandle *handle; // Handle given by tel_init()
371 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
372 * void *user_data; // Set User data
373 * err_code = tel_get_sim_language(handle, callback, user_data);
379 /*================================================================================================*/
380 int tel_get_sim_language(TapiHandle *handle, tapi_response_cb callback, void *user_data);
383 * @brief This API is used to update the language preference information to SIM card.
385 * This function makes Dbus method call to Telephony Sever and returns immediate value.
386 * However it just means that the API request has been transfered to the CP successfully.
387 * The actual operation result is being delivered in the corresponding event asynchronously.
389 * @par Sync (or) Async:
390 * This is a Asynchronous API.
392 * @par Important Notes:
393 * - This function update SIM Language information directly and can effect device language setting. Use carefully.
399 * - handle from tel_init().
401 * @param [in] language
402 * This parameter returns the language preference information.
404 * @param [in] callback
405 * - To register callback function for result.
407 * @param [in] user_data
408 * - user_data for user specification.
410 * @par Async Response Message:
411 * The event associated is TAPI_EVENT_SIM_SET_LANGUAGE_CNF.
412 * Asynchronous return status is indicated by #TelSimAccessResult_t.
415 * - A dbus connection is established with #tel_init
416 * - The application name is registered with #tel_register_app_name
417 * - The application is registered events to listen asynchronous response with #tel_register_event
418 * - A event loop is running to listen events
419 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
425 * @return Return Type (int)
426 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
427 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
428 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
430 * @par Prospective Clients:
436 * #include <ITapiSim.h>
438 * TelSimLanguagePreferenceCode_t language = 0x00; //init
439 * language = TAPI_SIM_LP_ENGLISH; //language value
440 * TapiHandle *handle; // Handle given by tel_init()
441 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
442 * void *user_data; // Set User data
443 * err_code = tel_set_sim_language(handle, language, callback, user_data);
449 /*================================================================================================*/
450 int tel_set_sim_language(TapiHandle *handle, TelSimLanguagePreferenceCode_t language, tapi_response_cb callback, void *user_data);
453 * @brief This API is used to get the SIM Call forwarding indication related data(EF-CFIS and CPHS case).
454 * this data is required for Call forwarding related functionality in handset.
456 * @par Sync (or) Async:
457 * This is a Asynchronous API.
459 * @par Important Notes:
466 * - handle from tel_init().
468 * @param [in] callback
469 * - To register callback function for result.
471 * @param [in] user_data
472 * - user_data for user specification.
474 * @par Async Response Message:
478 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
484 * @return Return Type (int)
485 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
486 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
487 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
489 * @par Prospective Clients:
495 * #include <ITapiSim.h>
497 * TapiHandle *handle; // Handle given by tel_init()
498 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
499 * void *user_data; // Set User data
500 * err_code = tel_get_sim_callforwarding_info(handle, callback, user_data);
501 * if(err_code == TAPI_API_SUCCESS) {
502 * if(cf_data.b_cphs) { //b_cphs means current SIM is for CPHS or not.
503 * printf("Current SIM is CPHS");
505 * printf("Current SIM is not CPHS but 3GPP");
508 * printf("TAPI API FAIL: Error Code [0x%x]",err_code);
515 /*================================================================================================*/
516 int tel_get_sim_callforwarding_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
519 * @brief This API is used to set the SIM Call forwarding indication related data(EF-CFIS and CPHS case).
520 * this data is required for Call forwarding related functionality in handset.
522 * @par Sync (or) Async:
523 * This is a Asynchronous API.
525 * @par Important Notes:
532 * - handle from tel_init().
534 * @param [in] callback
535 * - To register callback function for result.
537 * @param [in] user_data
538 * - user_data for user specification.
540 * @par Async Response Message:
544 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
550 * @return Return Type (int)
551 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
552 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
553 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
555 * @par Prospective Clients:
561 * #include <ITapiSim.h>
563 * TelSimCallForwardingReq_t *req_cf;
564 * TapiHandle *handle; // Handle given by tel_init()
565 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
566 * void *user_data; // Set User data
567 * err_code = tel_set_sim_callforwarding_info(handle, &req_cf, callback, user_data);
573 /*================================================================================================*/
574 int tel_set_sim_callforwarding_info(TapiHandle *handle, TelSimCallForwardingReq_t *req_cf, tapi_response_cb callback, void *user_data);
577 * @brief This API is used to get the SIM message waiting indication related data(EF-MWIS and CPHS case).
578 * this data is required for Message waiting related functionality in handset.
580 * @par Sync (or) Async:
581 * This is a Asynchronous API.
583 * @par Important Notes:
590 * - handle from tel_init().
592 * @param [in] callback
593 * - To register callback function for result.
595 * @param [in] user_data
596 * - user_data for user specification.
598 * @par Async Response Message:
602 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
608 * @return Return Type (int)
609 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
610 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
611 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
613 * @par Prospective Clients:
619 * #include <ITapiSim.h>
620 * TelSimMessageWaiting_s mw_data;
622 * TapiHandle *handle; // Handle given by tel_init()
623 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
624 * void *user_data; // Set User data
625 * err_code = tel_get_sim_messagewaiting_info(handle, callback, user_data);
626 * if(err_code == TAPI_API_SUCCESS) {
627 * if(mw_data.b_cphs) { //b_cphs means current SIM is for CPHS or not.
628 * printf("Current SIM is CPHS");
630 * printf("Current SIM is not CPHS but 3GPP");
633 * printf("TAPI API FAIL: Error Code [0x%x]",err_code);
640 /*================================================================================================*/
641 int tel_get_sim_messagewaiting_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
644 * @brief This API is used to set the SIM message waiting indication related data(EF-MWIS and CPHS case).
645 * this data is required for Message waiting related functionality in handset.
647 * @par Sync (or) Async:
648 * This is a Asynchronous API.
650 * @par Important Notes:
657 * - handle from tel_init().
659 * @param [in] callback
660 * - To register callback function for result.
662 * @param [in] user_data
663 * - user_data for user specification.
665 * @par Async Response Message:
669 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
675 * @return Return Type (int)
676 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
677 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
678 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
680 * @par Prospective Clients:
686 * #include <ITapiSim.h>
687 * TelSimMessageWaiting_s mw_data;
689 * TelSimMessageWaitingReq_t *req_mw; // Get message waiting info
690 * TapiHandle *handle; // Handle given by tel_init()
691 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
692 * void *user_data; // Set User data
693 * err_code = tel_set_sim_messagewaiting_info(handle, &req_mw, callback, user_data);
699 /*================================================================================================*/
700 int tel_set_sim_messagewaiting_info(TapiHandle *handle, TelSimMessageWaitingReq_t *req_mw, tapi_response_cb callback, void *user_data);
703 * @brief This API is used to get the SIM mailbox related data(EF-MBDN, MBDI and CPHS case).
704 * this data is required for Mailbox related functionality in handset.
706 * @par Sync (or) Async:
707 * This is a Asynchronous API.
709 * @par Important Notes:
716 * - handle from tel_init().
718 * @param [in] callback
719 * - To register callback function for result.
721 * @param [in] user_data
722 * - user_data for user specification.
724 * @par Async Response Message:
728 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
734 * @return Return Type (int)
735 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
736 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
737 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
739 * @par Prospective Clients:
745 * #include <ITapiSim.h>
747 * TapiHandle *handle; // Handle given by tel_init()
748 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
749 * void *user_data; // Set User data
750 * err_code = tel_get_sim_mailbox_info(handle, callback, user_data);
751 * if(err_code == TAPI_API_SUCCESS) {
752 * if(mbox.b_cphs) { //b_cphs means current SIM is for CPHS or not.
753 * printf("Current SIM is CPHS");
755 * printf("Current SIM is not CPHS but 3GPP");
758 * printf("TAPI API FAIL: Error Code [0x%x]",err_code);
765 /*================================================================================================*/
766 int tel_get_sim_mailbox_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
769 * @brief This API is used to set the SIM mailbox related data(EF-MBDN, MBDI and CPHS case).
770 * this data is required for Mailbox related functionality in handset.
772 * @par Sync (or) Async:
773 * This is a Asynchronous API.
775 * @par Important Notes:
782 * - handle from tel_init().
784 * @param [in] callback
785 * - To register callback function for result.
787 * @param [in] user_data
788 * - user_data for user specification.
790 * @par Async Response Message:
794 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
800 * @return Return Type (int)
801 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
802 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
803 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
805 * @par Prospective Clients:
811 * #include <ITapiSim.h>
813 * TelSimMailBoxNumber_t *req_mb; // Get SIM mail box number info
814 * TapiHandle *handle; // Handle given by tel_init()
815 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
816 * void *user_data; // Set User data
817 * err_code = tel_set_sim_mailbox_info(handle, &req_mb, callback, user_data);
823 /*================================================================================================*/
824 int tel_set_sim_mailbox_info(TapiHandle *handle, TelSimMailBoxNumber_t *req_mb, tapi_response_cb callback, void *user_data);
827 * @brief This API is used to get the SIM CPHS specific data.
828 * this data is required for CPHS related functionality in handset.
830 * @par Sync (or) Async:
831 * This is an Asynchronous API.
833 * @par Important Notes:
840 * - handle from tel_init().
842 * @param [in] callback
843 * - To register callback function for result.
845 * @param [in] user_data
846 * - user_data for user specification.
848 * @par Async Response Message:
852 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
857 * @return Return Type (int)
858 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
859 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
860 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
862 * @par Prospective Clients:
868 * #include <ITapiSim.h>
870 * TapiHandle *handle; // Handle given by tel_init()
871 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
872 * void *user_data; // Set User data
873 * err_code = tel_get_sim_cphs_info(handle, callback, user_data);
874 * if(err_code == TAPI_API_SUCCESS) {
875 * if(cphs_data.b_used) { //b_used means current SIM is for CPHS or not.
876 * printf("Current SIM is CPHS");
878 * printf("Current SIM is not CPHS but 3GPP");
881 * printf("TAPI API FAIL: Error Code [0x%x]",err_code);
888 /*================================================================================================*/
889 int tel_get_sim_cphs_info(TapiHandle *handle, tapi_response_cb callback, void *user_data);
892 * @brief This API is used to get the SIM Service Table.
893 * this data is required to know which SIM services are enabled or disabled.
895 * @par Sync (or) Async:
896 * This is an Asynchronous API.
898 * @par Important Notes:
905 * - handle from tel_init().
907 * @param [in] callback
908 * - To register callback function for result.
910 * @param [in] user_data
911 * - user_data for user specification.
913 * @par Async Response Message:
917 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
922 * @return Return Type (int)
923 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
924 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
925 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
927 * @par Prospective Clients:
933 * #include <ITapiSim.h>
935 * TapiHandle *handle; // Handle given by tel_init()
936 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
937 * void *user_data; // Set User data
938 * err_code = tel_get_sim_service_table(handle, callback, user_data);
944 /*================================================================================================*/
945 int tel_get_sim_service_table(TapiHandle *handle, tapi_response_cb callback, void *user_data);
948 * @brief This API is used to get the SIM MSISDN data. Regarding 3GPP specification, Current value is optional.
950 * @par Sync (or) Async:
951 * This is an Asynchronous API.
953 * @par Important Notes:
960 * - handle from tel_init().
962 * @param [in] callback
963 * - To register callback function for result.
965 * @param [in] user_data
966 * - user_data for user specification.
968 * @par Async Response Message:
972 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
977 * @return Return Type (int)
978 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
979 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
980 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
982 * @par Prospective Clients:
988 * #include <ITapiSim.h>
990 * TapiHandle *handle; // Handle given by tel_init()
991 * err_code = tel_get_sim_msisdn(handle, callback, user_data);
992 * if(err_code == TAPI_API_SUCCESS)
994 * * printf(" ============================================");
995 * * printf("name[%s]",msisdn.name);
996 * * printf("num[%s]",msisdn.num);
997 * * if(msisdn.name == '\0';) //If current SIM does not have, Null string will be returned.
998 * * * printf("name is null string");
1000 * * if(msisdn.num == '\0';) //If current SIM does not have, Null string will be returned.
1001 * * * printf("number is null string");
1005 * * printf("TAPI API FAIL: Error Code [0x%x]",err_code);
1013 /*================================================================================================*/
1014 int tel_get_sim_msisdn(TapiHandle *handle, tapi_response_cb callback, void *user_data);
1017 * @brief This API is used to get the SIM OPLMNWACT(Operator controlled PLMN Selector with Access Technology) data. Regarding 3GPP specification, Current value is optional.
1019 * @par Sync (or) Async:
1020 * This is an Asynchronous API.
1022 * @par Important Notes:
1028 * @param [in] handle
1029 * - handle from tel_init().
1031 * @param [in] callback
1032 * - To register callback function for result.
1034 * @param [in] user_data
1035 * - user_data for user specification.
1037 * @par Async Response Message:
1041 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1046 * @return Return Type (int)
1047 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1048 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1049 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1051 * @par Prospective Clients:
1058 * TapiHandle *handle; // Handle given by tel_init()
1059 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1060 * void *user_data; // Set User data
1061 * err_code = tel_get_sim_oplmnwact(handle, callback, user_data);
1068 /*================================================================================================*/
1069 int tel_get_sim_oplmnwact(TapiHandle *handle, tapi_response_cb callback, void *user_data);
1072 * @brief This API is used to get the SIM SPN data. Regarding 3GPP specification, Current value is optional.
1074 * @par Sync (or) Async:
1075 * This is an Asynchronous API.
1077 * @par Important Notes:
1083 * @param [in] handle
1084 * - handle from tel_init().
1086 * @param [in] callback
1087 * - To register callback function for result.
1089 * @param [in] user_data
1090 * - user_data for user specification.
1092 * @par Async Response Message:
1096 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1101 * @return Return Type (int)
1102 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1103 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1104 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1106 * @par Prospective Clients:
1113 * TapiHandle *handle; // Handle given by tel_init()
1114 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1115 * void *user_data; // Set User data
1116 * err_code = tel_get_sim_spn(handle, callback, user_data);
1123 /*================================================================================================*/
1124 int tel_get_sim_spn(TapiHandle *handle, tapi_response_cb callback, void *user_data);
1127 * @brief This API is used to get the SIM CPHS NETNAME data.
1129 * @par Sync (or) Async:
1130 * This is an Asynchronous API.
1132 * @par Important Notes:
1138 * @param [in] handle
1139 * - handle from tel_init().
1141 * @param [in] callback
1142 * - To register callback function for result.
1144 * @param [in] user_data
1145 * - user_data for user specification.
1147 * @par Async Response Message:
1151 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1156 * @return Return Type (int)
1157 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1158 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1159 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1161 * @par Prospective Clients:
1168 * TapiHandle *handle; // Handle given by tel_init()
1169 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1170 * void *user_data; // Set User data
1171 * err_code = tel_get_sim_cphs_netname(handle, callback, user_data);
1178 /*================================================================================================*/
1179 int tel_get_sim_cphs_netname(TapiHandle *handle, tapi_response_cb callback, void *user_data);
1182 * @brief This API is used to execute the authentication procedure by using SIM.
1184 * This function makes Dbus method call to Telephony Sever and returns immediate value.
1185 * However it just means that the API request has been transfered to the CP successfully.
1186 * The actual operation result is being delivered in the corresponding event asynchronously.
1187 * This function supports IMS, 3G and GSM authentication.
1189 * @par Sync (or) Async:
1190 * This is an Asynchronous API.
1192 * @par Important Notes:
1198 * @param [in] handle
1199 * - handle from tel_init().
1201 * @param[in] authentication_data
1202 * - This input has the authentication code to be validated by ISIM,3G and GSM application in the SIM card. #TelSimAuthenticationData_t
1204 * @param [in] callback
1205 * - To register callback function for result.
1207 * @param [in] user_data
1208 * - user_data for user specification.
1210 * @par Async Response Message:
1211 * -The event associated is TAPI_SIM_EVENT_AUTHENTICATION_CNF and the event data is #TelSimAuthenticationResponse_t.
1212 * Asynchronous return status is indicated by #TelSimAccessResult_t.
1215 * - A dbus connection is established with #tel_init
1216 * - The application name is registered with #tel_register_app_name
1217 * - The application is registered events to listen asynchronous response with #tel_register_event
1218 * - A event loop is running to listen events
1223 * @return Return Type (int)
1224 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1225 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1226 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1228 * @par Prospective Clients:
1234 * #include <ITapiSim.h>
1236 * TapiHandle *handle; // Handle given by tel_init()
1237 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1238 * void *user_data; // Set User data
1239 * TelSimAuthenticationData_t pAuthenticationData;
1240 * strcpy((char*)pAuthenticationData.rand_data, "username@operator.com"); //access data
1241 * pAuthenticationData.rand_length= strlen("username@operator.com");
1242 * strcpy((char*)pAuthenticationData.autn_data, "+1-212-555-12345"); // auth data
1243 * pAuthenticationData.autn_length = strlen("+1-212-555-12345");
1244 * err_code = tel_req_sim_authentication(handle, &pAuthenticationData, callback, user_data);
1250 /*================================================================================================*/
1251 int tel_req_sim_authentication(TapiHandle *handle, TelSimAuthenticationData_t *authentication_data, tapi_response_cb callback, void *user_data);
1256 * @brief This API performs PIN1/PIN2/SIM LOCK verification. This function performs PIN verification based on the pin type passed along with pin data.
1257 * PIN1 code : The SIM card has its own password is to check access permissions
1258 * SIM Lock code : Between Device and the SIM card using a SIM password is only available on certain handsets to be used to authorize.
1260 * This function makes Dbus method call to Telephony Sever and returns immediate value.
1261 * However it just means that the API request has been transfered to the CP successfully.
1262 * The actual operation result is being delivered in the corresponding event asynchronously.
1264 * @par Sync (or) Async:
1265 * This is an Asynchronous API.
1267 * @par Important Notes:
1268 * - Based on Pin status (PIN/PUK/SIM LOCK) is blocked, an unsolicited event TAPI_EVENT_SIM_STATUS_IND is published to Applications on Device boot time.
1269 * - if pin status is PUK, you should use #tel_verify_sim_puks instead of this API.
1274 * @param [in] handle
1275 * - handle from tel_init().
1277 * @param[in] pin_data
1278 * -PIN code, entered by the user. you should make all parameters.
1280 * @param [in] callback
1281 * - To register callback function for result.
1283 * @param [in] user_data
1284 * - user_data for user specification.
1286 * @par Async Response Message:
1287 * The event associated is TAPI_EVENT_SIM_VERIFY_SEC_CNF and the event data is #TelSimSecResult_t.
1288 * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
1289 * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Verification successes.
1290 * If returned status is TAPI_SIM_PIN_INCORRECT_PASSWORD, Verification fails and you can check retry count by using event data #TelSimSecResult_t.
1293 * - Initialize Dbus connection with #tel_init
1294 * - Register caller's application name with #tel_register_app_name
1295 * - Register telephony events to listen
1296 * - A event loop is running to listen events
1297 * - This API is used when #TelSimCardStatus_t is TAPI_SIM_STATUS_SIM_PIN_REQUIRED or TAPI_SIM_STATUS_SIM_LOCK_REQUIRED on boot time.
1298 * - Currently there`s no proper scenario for PIN2 verification by using this API.
1303 * @return Return Type (int)
1304 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1305 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1306 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1308 * @par Prospective Clients:
1314 * #include <ITapiSim.h>
1315 * TapiHandle *handle; // Handle given by tel_init()
1316 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1317 * void *user_data; // Set User data
1318 * err_code = TAPI_API_SUCCESS; // 0
1319 * int length = TAPI_SIM_PIN_LENGTH+1;
1320 * char init_pin_val[length] ;
1322 * strcpy(init_pin_val, PIN1_NORMAL);
1324 * TelSimSecPw_t pin_data = {0,};
1326 * pin_data.type = TAPI_SIM_PTYPE_PIN1;
1327 * pin_data.pw_len = strlen(init_pin_val);
1329 * printf("pw_len[%d]", pin_data.pw_len);
1331 * pin_data.pw = (char*)malloc(length);
1332 * memcpy(pin_data.pw,init_pin_val,length);
1334 * err_code = tel_verifiy_sim_pins(handle, &pin_data, callback, user_data);
1341 /*================================================================================================*/
1342 int tel_verifiy_sim_pins(TapiHandle *handle, const TelSimSecPw_t *pin_data, tapi_response_cb callback, void *user_data);
1345 * @brief This function performs unblock PIN1/PIN2 operation based on PUK information passed along with
1346 * unblock information entered by the user.
1347 * If you get sim card status(TAPI_SIM_STATUS_SIM_PUK_REQUIRED) by using #tel_get_sim_init_info on boot time
1348 * or (TAPI_SIM_PIN_STATUS_BLOCKED) by using #tel_get_sim_facility after normal initialization for specific operation,
1349 * you may unblock PIN1/PIN2.
1351 * This function makes Dbus method call to Telephony Sever and returns immediate value.
1352 * However it just means that the API request has been transfered to the CP successfully.
1353 * The actual operation result is being delivered in the corresponding event asynchronously.
1355 * @par Sync (or) Async:
1356 * This is an Asynchronous API.
1358 * @par Important Notes:
1359 * - Based on Pin status (PIN1/PIN2) is blocked, an unsolicited event TAPI_EVENT_SIM_STATUS_IND
1360 * is published to Applications on boot time also.
1363 * - If you fail to unblock PIN til given retry count, Your SIM card be permanent block status.
1365 * @param [in] handle
1366 * - handle from tel_init().
1368 * @param[in] puk_data
1369 * -Specifies unblocking PIN password #TelSimSecPw_t
1371 * @param[in] new_pin_data
1372 * -Specifies PIN password which you want to use after unblocking operation #TelSimSecPw_t
1374 * @param [in] callback
1375 * - To register callback function for result.
1377 * @param [in] user_data
1378 * - user_data for user specification.
1380 * @par Async Response Message:
1381 * The event associated is TAPI_EVENT_SIM_VERIFY_PUK_CNF and the event data is #TelSimSecResult_t.
1382 * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
1383 * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Verification successes.
1384 * If returned status is TAPI_SIM_PUK_INCORRECT_PASSWORD, Verification fails and you can check retry count by using event data #TelSimSecResult_t.
1387 * - Initialize Dbus connection with #tel_init
1388 * - Register caller's application name with #tel_register_app_name
1389 * - Register telephony events to listen
1390 * - A event loop is running to listen events
1391 * - PIN1 or PIN2 status should be TAPI_SIM_PIN_STATUS_BLOCKED and Card status should be TAPI_SIM_STATUS_SIM_PUK_REQUIRED on boot time.
1394 * - After Success on unblocking for PIN1 or PIN2, each pin check facility is enabled even if previous facility is disabled.
1396 * @return Return Type (int)
1397 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1398 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1399 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1401 * @par Prospective Clients:
1407 * #include <ITapiSim.h>
1409 * TapiHandle *handle; // Handle given by tel_init()
1410 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1411 * void *user_data; // Set User data
1412 * err_code = TAPI_API_SUCCESS; // 0
1413 * int length = TAPI_SIM_PIN_LENGTH+1;
1415 * char init_pin_val[length];
1416 * char init_puk_val[length];
1418 * strcpy(init_pin_val, PIN1_NORMAL);
1419 * strcpy(init_puk_val, PUK1_NORMAL);
1421 * TelSimSecPw_t puk_data = {0,};
1422 * TelSimSecPw_t new_pin_data = {0,};
1424 * puk_data.type = TAPI_SIM_PTYPE_PUK1; // 0x00
1425 * puk_data.pw_len = length;
1426 * puk_data.pw_len = strlen(init_puk_val);
1427 * printf("pw_len[%d]", puk_data.pw_len);
1428 * memcpy(puk_data.pw,init_pin_val,length);
1430 * new_pin_data.type = TAPI_SIM_PTYPE_PIN1; // 0x00
1431 * new_pin_data.pw_len = strlen(init_pin_val);
1432 * printf("pw_len[%d]", new_pin_data.pw_len);
1433 * new_pin_data.pw = (char*)malloc(length);
1434 * memcpy(new_pin_data.pw,init_pin_val,length);
1436 * err_code = tel_verify_sim_puks(handle, &puk_data, &new_pin_data, callback, user_data);
1443 /*================================================================================================*/
1444 int tel_verify_sim_puks(TapiHandle *handle, const TelSimSecPw_t *puk_data, const TelSimSecPw_t *new_pin_data, tapi_response_cb callback, void *user_data);
1448 * @brief This function changes PIN1/PIN2 code based on the pin type passed along with old pin data and new pin data.
1450 * This function makes Dbus method call to Telephony Sever and returns immediate value.
1451 * However it just means that the API request has been transfered to the CP successfully.
1452 * The actual operation result is being delivered in the corresponding event asynchronously.
1454 * @par Sync (or) Async:
1455 * This is an Asynchronous API.
1457 * @par Important Notes:
1458 * - User should fill up pin type equally both old_pin and new_pin.
1463 * @param [in] handle
1464 * - handle from tel_init().
1466 * @param[in] old_pin
1467 * -Old pin code, entered by the user. #TelSimSecPw_t
1469 * @param[in] new_pin
1470 * -New pin code, entered by the user. #TelSimSecPw_t
1472 * @param [in] callback
1473 * - To register callback function for result.
1475 * @param [in] user_data
1476 * - user_data for user specification.
1478 * @par Async Response Message:
1479 * The event associated is TAPI_EVENT_SIM_CHANGE_PINS_CNF and the event data is #TelSimSecResult_t.
1480 * Asynchronous return status is indicated by #TelSimPinOperationResult_t.
1481 * If returned status is TAPI_SIM_PIN_OPERATION_SUCCESS, Change operation finish successfully.
1482 * If returned status is TAPI_SIM_PIN_INCORRECT_PASSWORD, Change operation fails and you can check retry count by using event data #TelSimSecResult_t.
1485 * - Initialize Dbus connection with #tel_init
1486 * - Register caller's application name with #tel_register_app_name
1487 * - Register telephony events to listen
1488 * - A event loop is running to listen events
1489 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1490 * - PIN which user want to change check facility should be enabled.
1495 * @return Return Type (int)
1496 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1497 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1498 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1500 * @par Prospective Clients:
1506 * #include <ITapiSim.h>
1508 * TapiHandle *handle; // Handle given by tel_init()
1509 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1510 * void *user_data; // Set User data
1511 * err_code = TAPI_API_SUCCESS; // 0
1512 * int length = TAPI_SIM_PIN_LENGTH+1;
1513 * char init_old_pin_val[length] ;
1514 * char init_new_pin_val[length];
1516 * memset(&init_old_pin_val, 0 , length);
1517 * memset(&init_new_pin_val, 0 , length);
1519 * TelSimSecPw_t old_pin = {0,};
1520 * TelSimSecPw_t new_pin = {0,};
1522 * strcpy(init_old_pin_val, PIN1_ORG);
1524 * old_pin.type = TAPI_SIM_PTYPE_PIN1;
1525 * old_pin.pw_len = strlen(init_old_pin_val);
1526 * printf("pw_len[%d]", old_pin.pw_len);
1527 * old_pin.pw = (char*)malloc(length);
1528 * memcpy(old_pin.pw,init_old_pin_val,length);
1530 * strcpy(init_new_pin_val, PIN1_NEW);
1532 * new_pin.type = TAPI_SIM_PTYPE_PIN1;
1533 * new_pin.pw_len = strlen(init_new_pin_val);
1534 * printf("pw_len[%d]", new_pin.pw_len);
1535 * new_pin.pw = (char*)malloc(length);
1536 * memcpy(new_pin.pw,init_new_pin_val,length);
1538 * err_code = tel_change_sim_pins(handle, &old_pin, &new_pin, callback, user_data);
1545 /*================================================================================================*/
1546 int tel_change_sim_pins(TapiHandle *handle, const TelSimSecPw_t *old_pin, const TelSimSecPw_t *new_pin, tapi_response_cb callback, void *user_data);
1549 * @brief This API is used to disable the SIM facility.
1551 * @par Sync (or) Async:
1552 * This is an Asynchronous API.
1554 * @par Important Notes:
1560 * @param [in] handle
1561 * - handle from tel_init().
1564 * - a structure which contains facility type and password.
1566 * @param [in] callback
1567 * - To register callback function for result.
1569 * @param [in] user_data
1570 * - user_data for user specification.
1578 * @return Return Type (int)
1579 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1580 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1581 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1583 * @par Prospective Clients:
1590 * TapiHandle *handle; // Handle given by tel_init()
1591 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1592 * void *user_data; // Set User data
1593 * TelSimFacilityPw_t *fc_pw;
1594 * int length = TAPI_SIM_PIN_LENGTH+1;
1595 * char init_pin_val[length] ;
1597 * strcpy(init_pin_val, PIN1_NORMAL);
1599 * fc_pw.lock_type = TAPI_SIM_LOCK_SC; // Set locktype for which facility should be disabled;
1600 * fc_pw.pw_len = strlen(init_pin_val);
1602 * printf("pw_len[%d]", fc_pw.pw_len);
1604 * fc_pw.pw = (char*)malloc(length);
1605 * memcpy(fc_pw.pw,init_pin_val,length);
1606 * err_code = tel_disable_sim_facility(handle, fc_pw, callback, user_data);
1613 /*================================================================================================*/
1614 int tel_disable_sim_facility(TapiHandle *handle, TelSimFacilityPw_t *pw, tapi_response_cb callback, void *user_data);
1617 * @brief This API is used to enable the SIM facility.
1619 * @par Sync (or) Async:
1620 * This is an Asynchronous API.
1622 * @par Important Notes:
1628 * @param [in] handle
1629 * - handle from tel_init().
1632 * - a structure which contains facility type and password.
1634 * @param [in] callback
1635 * - To register callback function for result.
1637 * @param [in] user_data
1638 * - user_data for user specification.
1646 * @return Return Type (int)
1647 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1648 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1649 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1651 * @par Prospective Clients:
1658 * TapiHandle *handle; // Handle given by tel_init()
1659 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1660 * void *user_data; // Set User data
1661 * TelSimFacilityPw_t *fc_pw;
1662 * int length = TAPI_SIM_PIN_LENGTH+1;
1663 * char init_pin_val[length] ;
1665 * strcpy(init_pin_val, PIN1_NORMAL);
1667 * fc_pw.lock_type = TAPI_SIM_LOCK_SC; // Set locktype for which facility should be disabled;
1668 * fc_pw.pw_len = strlen(init_pin_val);
1670 * printf("pw_len[%d]", fc_pw.pw_len);
1672 * fc_pw.pw = (char*)malloc(length);
1673 * memcpy(fc_pw.pw,init_pin_val,length);
1674 * err_code = tel_enable_sim_facility(handle, fc_pw, callback, user_data);
1681 /*================================================================================================*/
1682 int tel_enable_sim_facility(TapiHandle *handle, TelSimFacilityPw_t *pw, tapi_response_cb callback, void *user_data);
1685 * @brief This API is used to get the SIM facility.
1687 * @par Sync (or) Async:
1688 * This is an Asynchronous API.
1690 * @par Important Notes:
1696 * @param [in] handle
1697 * - handle from tel_init().
1700 * - type of security lock type enum values.
1702 * @param [in] callback
1703 * - To register callback function for result.
1705 * @param [in] user_data
1706 * - user_data for user specification.
1714 * @return Return Type (int)
1715 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1716 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1717 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1719 * @par Prospective Clients:
1726 * TapiHandle *handle; // Handle given by tel_init()
1727 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1728 * void *user_data; // Set User data
1729 * TelSimLockType_t type = TAPI_SIM_LOCK_SC; // Set locktype for which facility should be disabled;
1730 * err_code = tel_get_sim_facility(handle, type, callback, user_data);
1737 /*================================================================================================*/
1738 int tel_get_sim_facility(TapiHandle *handle, TelSimLockType_t type, tapi_response_cb callback, void *user_data);
1741 * @brief This API is used to get the SIM LOCK TYPE info.
1743 * @par Sync (or) Async:
1744 * This is an Asynchronous API.
1746 * @par Important Notes:
1752 * @param [in] handle
1753 * - handle from tel_init().
1756 * - type of security lock type enum values.
1758 * @param [in] callback
1759 * - To register callback function for result.
1761 * @param [in] user_data
1762 * - user_data for user specification.
1770 * @return Return Type (int)
1771 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1772 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1773 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1775 * @par Prospective Clients:
1782 * TapiHandle *handle; // Handle given by tel_init()
1783 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1784 * void *user_data; // Set User data
1785 * TelSimLockType_t type = TAPI_SIM_LOCK_SC; // Set locktype for which facility should be disabled;
1786 * err_code = tel_get_sim_lock_info(handle, type, callback, user_data);
1793 /*================================================================================================*/
1794 int tel_get_sim_lock_info(TapiHandle *handle, TelSimLockType_t type, tapi_response_cb callback, void *user_data);
1797 * @brief This API provides common interface for accessing SIM data based on USIM generic command in ETSI TS 102 221
1798 * and 3GPP TS 31.102 Characteristics of the Universal Subscriber Identity Module (USIM) application.
1799 * This API provides only interface to send APDU. User should know well APDU usage.
1801 * This function makes Dbus method call to Telephony Sever and returns immediate value.
1802 * However it just means that the API request has been transfered to the CP successfully.
1803 * The actual operation result is being delivered in the corresponding event asynchronously.
1805 * @par Sync (or) Async:
1806 * This is an Asynchronous API.
1808 * @par Important Notes:
1814 * @param [in] handle
1815 * - handle from tel_init().
1817 * @param[in] apdu_data
1819 * @param [in] callback
1820 * - To register callback function for result.
1822 * @param [in] user_data
1823 * - user_data for user specification.
1825 * @par Async Response Message:
1826 * The event associated is TAPI_EVENT_SIM_APDU_CNF and the event data is #TelSimApduResp_t.
1827 * Asynchronous return status is indicated by #TelSimAccessResult_t.
1830 * - A dbus connection is established with #tel_init
1831 * - The application name is registered with #tel_register_app_name
1832 * - The application is registered events to listen asynchronous response with #tel_register_event
1833 * - A event loop is running to listen events
1834 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1840 * @return Return Type (int)
1841 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1842 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1843 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1845 * @par Prospective Clients:
1851 * #include <ITapiSim.h>
1853 * TapiHandle *handle; // Handle given by tel_init()
1854 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1855 * void *user_data; // Set User data
1856 * TelSimApdu_t apdu = {0,};
1857 * int tmp_apdu[5] = {0xa,5,6,7,8};
1858 * apdu.apdu_len = 5; //user should check
1861 * err_code = tel_req_sim_apdu(handle, apdu, callback, user_data);
1867 /*================================================================================================*/
1868 int tel_req_sim_apdu(TapiHandle *handle, TelSimApdu_t* apdu_data, tapi_response_cb callback, void *user_data);
1871 * @brief This API provides common interface to get SIM ATR(Answer To Reset) value.
1873 * This function makes Dbus method call to Telephony Sever and returns immediate value.
1874 * However it just means that the API request has been transfered to the CP successfully.
1875 * The actual operation result is being delivered in the corresponding event asynchronously.
1877 * @par Sync (or) Async:
1878 * This is an Asynchronous API.
1880 * @par Important Notes:
1886 * @param [in] handle
1887 * - handle from tel_init().
1889 * @param [in] callback
1890 * - To register callback function for result.
1892 * @param [in] user_data
1893 * - user_data for user specification.
1895 * @par Async Response Message:
1896 * The event associated is TAPI_EVENT_SIM_ATR_CNF and the event data is #TelSimAtrResp_t.
1897 * Asynchronous return status is indicated by #TelSimAccessResult_t.
1900 * - A dbus connection is established with #tel_init
1901 * - The application name is registered with #tel_register_app_name
1902 * - The application is registered events to listen asynchronous response with #tel_register_event
1903 * - A event loop is running to listen events
1904 * - User can get valid return value or make operations after SIM init complete(card status is TAPI_SIM_STATUS_SIM_INIT_COMPLETED).
1910 * @return Return Type (int)
1911 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
1912 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
1913 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
1915 * @par Prospective Clients:
1921 * #include <ITapiSim.h>
1923 * TapiHandle *handle; // Handle given by tel_init()
1924 * tapi_response_cb callback; //Initialized call-back function pointer in which response is returned
1925 * void *user_data; // Set User data
1927 * // REQUEST SIM ATR
1928 * err_code = tel_req_sim_atr(handle, callback, user_data);
1934 /*================================================================================================*/
1935 int tel_req_sim_atr(TapiHandle *handle, tapi_response_cb callback, void *user_data);
1938 * @brief This API provides synchronous call interface over some operations (refer to @param [in] op_type)
1940 * @par Sync (or) Async:
1941 * This is an Synchronous API.
1943 * @par Important Notes:
1949 * @param [in] handle
1950 * - handle from tel_init().
1952 * @param [in] op_type
1953 * operation type to do what caller want.
1954 * - TAPI_SIM_GET_INIT_STATUS
1955 * - TAPI_SIM_GET_CARD_TYPE
1956 * - TAPI_SIM_GET_IMSI
1957 * - TAPI_SIM_GET_ECC
1958 * - TAPI_SIM_GET_ICCID
1959 * - TAPI_SIM_GET_SPN
1960 * - TAPI_SIM_GET_CPHS_NET_NAME
1961 * - TAPI_SIM_TRANSFER_APDU
1962 * - TAPI_SIM_GET_ATR
1963 * - ( below are not supported. )
1964 * - TAPI_SIM_GET_LANGUAGE
1965 * - TAPI_SIM_SET_LANGUAGE
1966 * - TAPI_SIM_GET_CALL_FORWARDING
1967 * - TAPI_SIM_SET_CALL_FORWARDING
1968 * - TAPI_SIM_GET_MESSAGE_WAITING
1969 * - TAPI_SIM_SET_MESSAGE_WAITING
1970 * - TAPI_SIM_GET_MAILBOX
1971 * - TAPI_SIM_SET_MAILBOX
1972 * - TAPI_SIM_GET_CPHS_INFO
1973 * - TAPI_SIM_GET_SVCT
1974 * - TAPI_SIM_GET_MSISDN
1975 * - TAPI_SIM_GET_OPLMWACT
1976 * - TAPI_SIM_AUTHENTICATION
1977 * - TAPI_SIM_VERIFY_SEC
1978 * - TAPI_SIM_VERIFY_PUK
1979 * - TAPI_SIM_CHANGE_PIN
1980 * - TAPI_SIM_DISABLE_FACILITY
1981 * - TAPI_SIM_ENABLE_FACILITY
1982 * - TAPI_SIM_GET_FACILITY
1983 * - TAPI_SIM_GET_LOCK_INFO
1985 * @param [in] inparam
1986 * input parameter of union type. caller should fill when it is needed as below.
1987 * - TAPI_SIM_GET_INIT_STATUS : (not needed)
1988 * - TAPI_SIM_GET_CARD_TYPE : (not needed)
1989 * - TAPI_SIM_GET_IMSI : (not needed)
1990 * - TAPI_SIM_GET_ECC : (not needed)
1991 * - TAPI_SIM_GET_ICCID : (not needed)
1992 * - TAPI_SIM_GET_SPN : (not needed)
1993 * - TAPI_SIM_GET_CPHS_NET_NAME : (not needed)
1994 * - TAPI_SIM_TRANSFER_APDU : TelSimApdu_t
1995 * - TAPI_SIM_GET_ATR : (not needed)
1997 * @param [out] outparam
1998 * output parameter of union type. TAPI returns a value as caller want.
1999 * - TAPI_SIM_GET_INIT_STATUS : TelSimInitInfo_t
2000 * - TAPI_SIM_GET_CARD_TYPE : TelSimCardType_t
2001 * - TAPI_SIM_GET_IMSI : TelSimImsiInfo_t
2002 * - TAPI_SIM_GET_ECC : TelSimEccList_t
2003 * - TAPI_SIM_GET_ICCID : TelSimIccIdInfo_t
2004 * - TAPI_SIM_GET_SPN : TelSimSpn_t
2005 * - TAPI_SIM_GET_CPHS_NET_NAME : TelSimCphsNetName_t
2006 * - TAPI_SIM_TRANSFER_APDU : TelSimApduResp_t
2007 * - TAPI_SIM_GET_ATR : TelSimAtrResp_t
2009 * @par Async Response Message:
2018 * @return Return Type (int)
2019 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
2020 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
2021 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
2023 * @par Prospective Clients:
2028 * @code (for example, tel_req_sim_apdu())
2029 * #include <ITapiSim.h>
2031 * TelResponseData_t outparam;
2032 * TelRequestData_t inparam;
2033 * TapiHandle *handle; // Handle given by tel_init()
2034 * unsigned char apdu[5] = { 0x00, 0x70, 0x00, 0x00, 0x00};
2035 * memset (&outparam, 0, sizeof(TelResponseData_t));
2036 * memset (&inparam, 0, sizeof(TelRequestData_t));
2038 * inparam.apdu.apdu_len = strlen(apdu);
2039 * inparam.apdu.apdu = (unsigned char*)malloc(5);
2040 * memcpy (inparam.apdu.apdu, apdu, inparam.apdu.apdu_len);
2042 * rt = tel_request_sim_sync(handle, TAPI_SIM_TRANSFER_APDU, &inparam, &outparam);
2044 * if(inparam.apdu.apdu)
2045 * free(inparam.apdu.apdu);
2047 * msg("rt = [%d]", rt);
2049 * msg("outparam.apdu_resp.apdu_resp_len[%d]", outparam.apdu_resp.apdu_resp_len);
2050 * if (outparam.apdu_resp.apdu_resp_len) {
2051 * for (i = 0; i < outparam.apdu_resp.apdu_resp_len; i++)
2052 * msg("[%d]`s byte is [0x%x]", i, outparam.apdu_resp.apdu_resp[i]);
2060 /*================================================================================================*/
2061 int tel_request_sim_sync(TapiHandle *handle, TelSimTapiOperation_t op_type, TelSimRequestData_t *inparam, TelSimResponseData_t *outparam);
2064 * @brief This API provides asynchronous call interface over some operations (refer to @param [in] op_type)
2066 * @par Sync (or) Async:
2067 * This is an Asynchronous API.
2069 * @par Important Notes:
2075 * @param [in] handle
2076 * - handle from tel_init().
2078 * @param [in] op_type
2079 * operation type to do what caller want.
2080 * - TAPI_SIM_GET_INIT_STATUS
2081 * - TAPI_SIM_GET_CARD_TYPE
2082 * - TAPI_SIM_GET_IMSI
2083 * - TAPI_SIM_GET_ECC
2084 * - TAPI_SIM_GET_ICCID
2085 * - TAPI_SIM_GET_SPN
2086 * - TAPI_SIM_GET_CPHS_NET_NAME
2087 * - TAPI_SIM_TRANSFER_APDU
2088 * - TAPI_SIM_GET_ATR
2089 * - ( below are not supported. )
2090 * - TAPI_SIM_GET_LANGUAGE
2091 * - TAPI_SIM_SET_LANGUAGE
2092 * - TAPI_SIM_GET_CALL_FORWARDING
2093 * - TAPI_SIM_SET_CALL_FORWARDING
2094 * - TAPI_SIM_GET_MESSAGE_WAITING
2095 * - TAPI_SIM_SET_MESSAGE_WAITING
2096 * - TAPI_SIM_GET_MAILBOX
2097 * - TAPI_SIM_SET_MAILBOX
2098 * - TAPI_SIM_GET_CPHS_INFO
2099 * - TAPI_SIM_GET_SVCT
2100 * - TAPI_SIM_GET_MSISDN
2101 * - TAPI_SIM_GET_OPLMWACT
2102 * - TAPI_SIM_AUTHENTICATION
2103 * - TAPI_SIM_VERIFY_SEC
2104 * - TAPI_SIM_VERIFY_PUK
2105 * - TAPI_SIM_CHANGE_PIN
2106 * - TAPI_SIM_DISABLE_FACILITY
2107 * - TAPI_SIM_ENABLE_FACILITY
2108 * - TAPI_SIM_GET_FACILITY
2109 * - TAPI_SIM_GET_LOCK_INFO
2111 * @param [in] inparam
2112 * input parameter of union type. caller should fill when it is needed as below.
2113 * - TAPI_SIM_GET_INIT_STATUS : (not needed)
2114 * - TAPI_SIM_GET_CARD_TYPE : (not needed)
2115 * - TAPI_SIM_GET_IMSI : (not needed)
2116 * - TAPI_SIM_GET_ECC : (not needed)
2117 * - TAPI_SIM_GET_ICCID : (not needed)
2118 * - TAPI_SIM_GET_SPN : (not needed)
2119 * - TAPI_SIM_GET_CPHS_NET_NAME : (not needed)
2120 * - TAPI_SIM_TRANSFER_APDU : TelSimApdu_t
2121 * - TAPI_SIM_GET_ATR : (not needed)
2123 * @param [in] callback
2124 * - To register callback function for result.
2126 * @param [in] user_data
2127 * - user_data for user specification.
2129 * @par Async Response Message: *
2130 * Asynchronous return status is indicated by #TelSimAccessResult_t.
2131 * Asynchronous response data is #TelSimResponseData_t union type. TAPI returns what caller want.
2132 * - TAPI_SIM_GET_INIT_STATUS : TelSimInitInfo_t
2133 * - TAPI_SIM_GET_CARD_TYPE : TelSimCardType_t
2134 * - TAPI_SIM_GET_IMSI : TelSimImsiInfo_t
2135 * - TAPI_SIM_GET_ECC : TelSimEccList_t
2136 * - TAPI_SIM_GET_ICCID : TelSimIccIdInfo_t
2137 * - TAPI_SIM_GET_SPN : TelSimSpn_t
2138 * - TAPI_SIM_GET_CPHS_NET_NAME : TelSimCphsNetName_t
2139 * - TAPI_SIM_TRANSFER_APDU : TelSimApduResp_t
2140 * - TAPI_SIM_GET_ATR : TelSimAtrResp_t
2148 * @return Return Type (int)
2149 * - Integer '0' ( same with TAPI_API_SUCCESS & TAPI_SIM_ACCESS_SUCCESS ) - indicating that the operation has completed successfully.
2150 * - Negative integer : it provides an error code before actual operations. (Refer #TapiResult_t)
2151 * - Positive integer : it provides an error code while actual operations. (Refer to #TelSimAccessResult_t)
2153 * @par Prospective Clients:
2158 * @code (for example, tel_req_sim_apdu())
2159 * #include <ITapiSim.h>
2161 * TelRequestData_t inparam;
2162 * TapiHandle *handle; // Handle given by tel_init()
2163 * unsigned char apdu[5] = { 0x00, 0x70, 0x00, 0x00, 0x00};
2164 * memset (&inparam, 0, sizeof(TelRequestData_t));
2166 * inparam.apdu.apdu_len = 5;
2167 * inparam.apdu.apdu = (unsigned char*)malloc(5);
2168 * memcpy (inparam.apdu.apdu, apdu, inparam.apdu.apdu_len);
2170 * rt = tel_request_sim_async(handle, TAPI_SIM_TRANSFER_APDU, &inparam, on_sim_call_async, NULL);
2171 * if(inparam.apdu.apdu)
2172 * free(inparam.apdu.apdu);
2176 * void on_sim_call_async (TapiHandle *handle, int result, void *data,
2179 * TelSimAccessResult_t access_rt = result;
2180 * TelSimResponseData_t *resp = data;
2183 * msg("tel_request_sim_async() response received");
2184 * msg("access_rt[%d]", access_rt);
2186 * if (access_rt == 0) {
2187 * msg("apdu_resp_len[%d]", resp->apdu_resp.apdu_resp_len);
2188 * if (resp->apdu_resp.apdu_resp_len) {
2189 * for (i = 0; i < resp->apdu_resp.apdu_resp_len; i++)
2190 * msg("[%d]`s byte is [0x%x]", i, resp->apdu_resp.apdu_resp[i]);
2200 /*================================================================================================*/
2201 int tel_request_sim_async(TapiHandle *handle, TelSimTapiOperation_t op_type, TelSimRequestData_t *inparam, tapi_response_cb callback, void *user_data);
2207 #endif /* _ITAPI_SIM_H_ */