# SIM Service

- [API reference](https://docs.qualcomm.com/doc/80-41102-2/topic/_doxygen_rst_file__doxygen_sources_taf_sim_interface_h.html#file-taf-sim-interface-h)

The TelAF Subscriber Identity Module (SIM) service defines APIs related to SIM configuration.

SIM is an integrated circuit (IC) intended to securely store the international mobile subscriber identity (IMSI) number and some credentials to identify subscribers. SIM cards can also store a number of SMS messages and phone contacts.

## IPC interfaces binding

The functions of this service are provided by the **tafSimCard** service.

The following example illustrates how to bind to the SIM card service.

bindings:
    {
        clientExe.clientComponent.taf_sim -> tafSimCardSvc.taf_sim
    }
    Copy to clipboard

## Select a card to use

[taf\_sim\_SelectCard()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1add1022c1f3645d34053ee60cf214a7ab.html#Documentationa00680_1add1022c1f3645d34053ee60cf214a7ab) is used to select the SIM card available on the user device. By default, the SIM card in slot 1 is used for network camping. Additionally, if the SIM card identifier is passed in any TAF SIM API as a parameter, it will select that SIM and after this [taf\_sim\_GetSelectedCard()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a9d726117b1286775a8b19f880b9b0cfc.html#Documentationa00680_1a9d726117b1286775a8b19f880b9b0cfc) will return the newly selected card, not necessarily the one previously set by [taf\_sim\_SelectCard()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1add1022c1f3645d34053ee60cf214a7ab.html#Documentationa00680_1add1022c1f3645d34053ee60cf214a7ab).

**NOTE:** The SIM selection is not power off persistent. This function needs to be called at each start-up.

**NOTE:** It is highly recommended to wait for a TelAF SIM handler notification after selecting a new SIM before calling TelAF SIM API functions.

## SIM identification information

**ICCID:** The SIM card is internationally identified by integrated circuit card identifier (ICCID). ICCID is stored in the SIM card and engraved or printed on the body of the SIM card. The ICCID is defined by the ITU-T standard E.118 as the primary account number. According to section E.118, the ICCID is up to 19 digits. It includes a single check digit computed by applying the Luhn algorithm. However, GSM Phase 1 (ETSI Standard GSM 11.11) defined the ICCID length in 10 octets (i.e. 20 digits) with a network-specific structure.

- [taf\_sim\_GetICCID()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1abdf328bf8a43688032014a466d3ee36c.html#Documentationa00680_1abdf328bf8a43688032014a466d3ee36c) — Reads the identification number (ICCID).
- [taf\_sim\_AddNewStateHandler()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1ab6c8c27edc421a6ed3a95a4edf1b93fe.html#Documentationa00680_1ab6c8c27edc421a6ed3a95a4edf1b93fe) — Registers a handler to get notification when card state changes.
- [taf\_sim\_RemoveNewStateHandler()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1aa459f731498a43ff5fb2b72f0ce7deb6.html#Documentationa00680_1aa459f731498a43ff5fb2b72f0ce7deb6) — Unregisters the handler.

**NOTE:** During the initialization times of service, the new subscriptions of the ICCID change events are notified by the last changed events. This behavior exists only for 5 seconds and allows newly registered clients to get any ICCID changes that occured during the device power-on time.

**IMSI:** The International Mobile Subscriber Identity (IMSI) is a unique identity associated with the cellular networks. It is used in any mobile network that connects with other networks. The IMSI is provisioned inside the SIM card in case of GSM, UMTS and LTE networks.

The IMSI is generally a 15 digits long number, but it can be shorter also. The first 3 digits represent mobile country code (MCC) followed by the mobile network code (MNC), either 2 digits (European standard) or 3 digits (North American standard) long. The length of MNC depends on the value of MCC. The remaining digits are the mobile subscription identification number (MSIN) within the operator’s customer base.

**EID:** The EID (also called as eUICCID) is unique identifier for the embedded Universal Integrated Circuit Card (eUICC). The eUICC is a SIM card having remote provisioning function, and is designed to not be removed or replaced. It enables storing multiple communication profiles but only one is active (recognized by equipment and used for communication with network). With conventional SIM card, the ICCID is a unique key to distinguish the SIM card, but in case of eUICC, the ICCID is useful to identify a profile, and a new identifier is introduced, called eUICCID (EID), which is used as the primary key of the embedded SIM (eSIM) to identify.

[taf\_sim\_GetEID()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a0d3edf1bcc2377c5eb899fdbc01cc64a.html#Documentationa00680_1a0d3edf1bcc2377c5eb899fdbc01cc64a) retrieves the EID.

**International Mobile Subscriber Identity (IMSI)**

- [taf\_sim\_GetIMSI()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1abc446fe325772069f90cb48564d34cdb.html#Documentationa00680_1abc446fe325772069f90cb48564d34cdb) — Gets the IMSI.

**Phone Number**

[taf\_sim\_GetSubscriberPhoneNumber()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a0672919d1da60277e5e0c2b42e2cb863.html#Documentationa00680_1a0672919d1da60277e5e0c2b42e2cb863) — Reads the phone number of the SIM. If the phone number has not been assigned, it returns the empty string.

Using this API gets the subscriber phone number of the SIM.

**Home Network Information**

- [taf\_sim\_GetHomeNetworkOperator()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a3109d3832a25c135ec0458913b26d49c.html#Documentationa00680_1a3109d3832a25c135ec0458913b26d49c) — Retrieves the name of the carrier on which this subscription is made.
- [taf\_sim\_GetHomeNetworkMccMnc()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a08c97299f9c9f79a15aefa925874a1eb.html#Documentationa00680_1a08c97299f9c9f79a15aefa925874a1eb) — Retrieves the Mobile country code(MCC) and Mobile network code(MNC) of the carrier on which this subscription is made.

## SIM authentication

- [taf\_sim\_EnterPIN()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1af868ed7a3652a5b1651e38657c87c475.html#Documentationa00680_1af868ed7a3652a5b1651e38657c87c475) — Enters the Personal Identification Number (PIN) code which is required before any mobile device functionality can be used.
- [taf\_sim\_GetRemainingPINTries()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a41066d1293ed520dabd4042b0ca95219.html#Documentationa00680_1a41066d1293ed520dabd4042b0ca95219) — Returns the number of remaining PIN1/PIN2 entry attempts.
- [taf\_sim\_GetRemainingPUKTries()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1ac3b47fd92800d90dc7947bd406e242e7.html#Documentationa00680_1ac3b47fd92800d90dc7947bd406e242e7) — Returns the number of remaining PUK retry attempts left before the SIM get blocked.
- [taf\_sim\_ChangePIN()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a7f15defbccca44d54954e1f195782979.html#Documentationa00680_1a7f15defbccca44d54954e1f195782979) must be called to change the PIN code.
- [taf\_sim\_Lock()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a228e570bb1993cd49965c666c27797c9.html#Documentationa00680_1a228e570bb1993cd49965c666c27797c9) — Locks the SIM card and enables asking for the PIN1/PIN2 code.
- [taf\_sim\_Unlock()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a79a44edd73b7a2b655241e030446008c.html#Documentationa00680_1a79a44edd73b7a2b655241e030446008c) — Unlocks the SIM card and disables asking for the PIN code.
- [taf\_sim\_Unblock()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a77b9c9f6884408d0dca4f69fd65c0014.html#Documentationa00680_1a77b9c9f6884408d0dca4f69fd65c0014) unblocks the SIM card. If the SIM card is blocked after X unsuccessful attempts to enter the PIN then [taf\_sim\_Unblock()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a77b9c9f6884408d0dca4f69fd65c0014.html#Documentationa00680_1a77b9c9f6884408d0dca4f69fd65c0014) can be used with Personal Unblocking (PUK1/PUK2) code to set a new PIN1/PIN2 and unblock the SIM.

## SIM states

- [taf\_sim\_IsPresent()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a4aaed4f3a001043730ef536f7114c12d.html#Documentationa00680_1a4aaed4f3a001043730ef536f7114c12d) — Indicates whether the SIM is present (and locked) or if it’s removed. Using this API allows client apps to know whether a SIM is present in device’s slot.
- [taf\_sim\_IsReady()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1abcf3263afe3d6d8b81c728943715c804.html#Documentationa00680_1abcf3263afe3d6d8b81c728943715c804) — Indicates whether the SIM is ready (PIN code correctly entered or not required) to use.
- [taf\_sim\_GetState()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a198b8331abe209f8eb746a55b57322c9.html#Documentationa00680_1a198b8331abe209f8eb746a55b57322c9) — Retrieves the following SIM states.

    - [TAF\_SIM\_PRESENT](https://docs.qualcomm.com/doc/80-41102-2/topic/enum_a00677_1adef9d9658a967513b8d8616f43681bb0.html#Documentationa00677_1adef9d9658a967513b8d8616f43681bb0ac46f69b500118840dd1575bd2d462987) — SIM card is present and locked. This is same as TAF\_SIM\_INSERTED.
    - [TAF\_SIM\_ABSENT](https://docs.qualcomm.com/doc/80-41102-2/topic/enum_a00677_1adef9d9658a967513b8d8616f43681bb0.html#Documentationa00677_1adef9d9658a967513b8d8616f43681bb0a4e96aaaaec85320ebeb236577eef2761) — SIM card is not present, i.e., not inserted.
    - [TAF\_SIM\_READY](https://docs.qualcomm.com/doc/80-41102-2/topic/enum_a00677_1adef9d9658a967513b8d8616f43681bb0.html#Documentationa00677_1adef9d9658a967513b8d8616f43681bb0adb1e294d2188b9007697746abc046752) — SIM card is present and unlocked.
    - [TAF\_SIM\_BLOCKED](https://docs.qualcomm.com/doc/80-41102-2/topic/enum_a00677_1adef9d9658a967513b8d8616f43681bb0.html#Documentationa00677_1adef9d9658a967513b8d8616f43681bb0a6c2838b130008e96bf33fbcff0829d31) — SIM card is blocked and cannot be used unless it is unlocked it. Not supported.
    - [TAF\_SIM\_BUSY](https://docs.qualcomm.com/doc/80-41102-2/topic/enum_a00677_1adef9d9658a967513b8d8616f43681bb0.html#Documentationa00677_1adef9d9658a967513b8d8616f43681bb0a64adc6166417071c8b1b486aa3313bed) — SIM card is busy, i.e., it is getting activated, getting unlocked, etc. Not supported.
    - [TAF\_SIM\_POWER\_DOWN](https://docs.qualcomm.com/doc/80-41102-2/topic/enum_a00677_1adef9d9658a967513b8d8616f43681bb0.html#Documentationa00677_1adef9d9658a967513b8d8616f43681bb0a9779ee7183720c2d307ee671bd81702c) — SIM card is powered OFF. Not supported.
    - [TAF\_SIM\_STATE\_UNKNOWN](https://docs.qualcomm.com/doc/80-41102-2/topic/enum_a00677_1adef9d9658a967513b8d8616f43681bb0.html#Documentationa00677_1adef9d9658a967513b8d8616f43681bb0ab9ad1d8496a9baed839dc1594402f5c3) — Unknown SIM state; can occur when the state is not determined.
    - [TAF\_SIM\_RESTRICTED](https://docs.qualcomm.com/doc/80-41102-2/topic/enum_a00677_1adef9d9658a967513b8d8616f43681bb0.html#Documentationa00677_1adef9d9658a967513b8d8616f43681bb0a543a01a296f50aa0446ae9eb0c64f0e1) — SIM card is present but not usable due to carrier restrictions.
    - [TAF\_SIM\_ERROR](https://docs.qualcomm.com/doc/80-41102-2/topic/enum_a00677_1adef9d9658a967513b8d8616f43681bb0.html#Documentationa00677_1adef9d9658a967513b8d8616f43681bb0a0857763f204045455f8478985a8d113e) — SIM card has error; either card is removed or not readable or illegal.

A handler function should be registered to receive SIM state notifications. [taf\_sim\_AddNewStateHandler()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1ab6c8c27edc421a6ed3a95a4edf1b93fe.html#Documentationa00680_1ab6c8c27edc421a6ed3a95a4edf1b93fe) allows users to register a state change handler.

The handler must follow the below prototype: typedef void(\*taf\_sim\_NewStateHandlerFunc\_t)([taf\_sim\_Id\_t](https://docs.qualcomm.com/doc/80-41102-2/topic/enum_a00677_1a0d1bb2683809d68807f76340b8d69194.html#Documentationa00677_1a0d1bb2683809d68807f76340b8d69194) simId, [taf\_sim\_States\_t](https://docs.qualcomm.com/doc/80-41102-2/topic/enum_a00677_1adef9d9658a967513b8d8616f43681bb0.html#Documentationa00677_1adef9d9658a967513b8d8616f43681bb0) simState);

When the SIM’s state change is notified, the handler function is invoked.

**WARNING:** If the input \*taf\_sim\_NewStateHandlerFunc\_t is null then this function will kill the calling client.

Call [taf\_sim\_GetState()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a198b8331abe209f8eb746a55b57322c9.html#Documentationa00680_1a198b8331abe209f8eb746a55b57322c9) to retrieve the new state of the SIM.

**NOTE:** If many applications register handlers for notifications, they will all receive it.

An application may uninstall a state change handler by calling [taf\_sim\_RemoveNewStateHandler()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1aa459f731498a43ff5fb2b72f0ce7deb6.html#Documentationa00680_1aa459f731498a43ff5fb2b72f0ce7deb6).

- [taf\_sim\_SetPower()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a08f84ef06acb87d44ef9a10498d41a57.html#Documentationa00680_1a08f84ef06acb87d44ef9a10498d41a57) — Powers up or down the specified SIM card.
- [taf\_sim\_Reset()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a0a4b07e2e1262aafe22af258c04c0158.html#Documentationa00680_1a0a4b07e2e1262aafe22af258c04c0158) — Resets the specified SIM card.

**WARNING:** The device may need a reboot to detect a SIM insertion or removal. So it is recommended to restart the device or NAD.

Use [taf\_sim\_GetAppTypes()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1afb6f6973189be1ea2404e75c58bfab57.html#Documentationa00680_1afb6f6973189be1ea2404e75c58bfab57) to retrieve application types in the SIM card.

### Logical channels

Logical channel is specified by standard ETSI TS 102 221 in the section 8.7. If they are supported by the SIM card, the logical channels allow sending autonomous APDUs on the different channels. In this case the major points are:

- The basic channel 0 is available and opened all the time.
- The card assigns a number to open a new channel. This channel remains open until it is closed by the application or until the SIM is deactivated.

Use [taf\_sim\_OpenLogicalChannel()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a2e4c0d76ff3d8d25137a084cd0ebfefd.html#Documentationa00680_1a2e4c0d76ff3d8d25137a084cd0ebfefd) or [taf\_sim\_OpenLogicalChannelByAid()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a2ba646b51ed145f282866b3740eed688.html#Documentationa00680_1a2ba646b51ed145f282866b3740eed688) to open a logical channel in the SIM card. APDUs then can be sent to SIM card with [taf\_sim\_SendApduOnChannel()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a5d1f9dfd297c7ba34ed8b3949e546506.html#Documentationa00680_1a5d1f9dfd297c7ba34ed8b3949e546506). When the logical channel is no longer needed, it can be closed using [taf\_sim\_CloseLogicalChannel()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a81cf8403d729b3f7443b36ac27ad0482.html#Documentationa00680_1a81cf8403d729b3f7443b36ac27ad0482).

Use [taf\_sim\_IsEmergencyCallSubscriptionSelected()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1ab7664d0f39c107c476437d55d5c1606b.html#Documentationa00680_1ab7664d0f39c107c476437d55d5c1606b) to know if the EMERGENCY profile is activated for the specified sim slot.

**WARNING:** If no emergency profile is found, it returns LE\_FAULT.

Before the SIM sends a message, an application registers a callback handler using [taf\_sim\_AddNewStateHandler()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1ab6c8c27edc421a6ed3a95a4edf1b93fe.html#Documentationa00680_1ab6c8c27edc421a6ed3a95a4edf1b93fe). Once the message is sent, the handler will be called indicating the sending status of the message. If the message sending failed, then the handler will be called with the error code.

static void NewSimStateHandler(taf_sim_Id_t simId, taf_sim_States_t simState, void* contextPtr){
        LE_INFO("New SIM event for SIM card: %d SIM state: %d", simId, simState);
        exit(EXIT_SUCCESS);
    }
    taf_sim_NewStateHandlerRef_t msgHandlerRef = taf_sim_AddNewStateHandler(NewSimStateHandler, NULL);
    Copy to clipboard

Applications must use [taf\_sim\_RemoveNewStateHandler()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1aa459f731498a43ff5fb2b72f0ce7deb6.html#Documentationa00680_1aa459f731498a43ff5fb2b72f0ce7deb6) to release [taf\_sim\_NewStateHandlerRef\_t](https://docs.qualcomm.com/doc/80-41102-2/topic/typedef_a00677_1a0c39d41a33f7a52a6d8ce1a85314ee9d.html#Documentationa00677_1a0c39d41a33f7a52a6d8ce1a85314ee9d) message handler reference object when it is no longer used.

## SIM refresh

- [taf\_sim\_AddRefreshChangeHandler()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1aedcdb9ab0f3db3ed044e0fcfed502767.html#Documentationa00680_1aedcdb9ab0f3db3ed044e0fcfed502767) — Registers a handler to get notification when SIM refresh state changes.
- [taf\_sim\_RemoveRefreshChangeHandler()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1afed86cb408cf5467e7d236860417a02c.html#Documentationa00680_1afed86cb408cf5467e7d236860417a02c) — Unregisters the handler.
- [taf\_sim\_CreateSession()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a3dbf7be032e8138b7161254cd757c462.html#Documentationa00680_1a3dbf7be032e8138b7161254cd757c462) — Creates a refresh session.
- [taf\_sim\_SetRefreshRegisterFiles()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a0affe7d4fa948af8029562a6acc94822.html#Documentationa00680_1a0affe7d4fa948af8029562a6acc94822) — Sets refresh register files.
- [taf\_sim\_SetRefreshMode()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a1170216001143e8ce651c05b85020377.html#Documentationa00680_1a1170216001143e8ce651c05b85020377) — Sets refresh mode.
- [taf\_sim\_SetRefreshAllow()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1ab5504ec662f7fc61ec89ecc652f650a9.html#Documentationa00680_1ab5504ec662f7fc61ec89ecc652f650a9) — Sets refresh allow or disallow.

## SIM profile switch

If there are several subscriptions/profiles in the eUICC (multi-profile), and one of them is dedicated to emergency calls (e.g., eCall, ERA-Glonass), local swap is needed to swap as quickly as possible to the emergency profile.

“Local swap” means that the user’s application must be able to directly request the eUICC to swap to emergency call subscription (ECS).

Local swap puts the eUICC in a temporary state, meaning the commercial subscription is replaced by an emergency subscription for a limited time, event triggering the swap back to commercial subscription being controlled by the user’s application.

The [taf\_sim\_LocalSwapToEmergencyCallSubscription()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1ada360bf6e2dd44a4d973de60f78b4a57.html#Documentationa00680_1ada360bf6e2dd44a4d973de60f78b4a57) function requests the multi-profile eUICC to swap to ECS. The user’s application must wait for eUICC reboot to finish and a network connection to be available.

The [taf\_sim\_LocalSwapToCommercialSubscription()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a9d60a4787d55b4e45f2dc17948d0caff.html#Documentationa00680_1a9d60a4787d55b4e45f2dc17948d0caff) function requests the multi-profile eUICC to swap back to a commercial subscription. The user’s application must wait for eUICC reboot to finish and a network connection to be available.

Unsupported APIs: — [taf\_sim\_SetAutomaticSelection()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a6e72725c574a0ace54ae07fe0052eb68.html#Documentationa00680_1a6e72725c574a0ace54ae07fe0052eb68) — [taf\_sim\_GetAutomaticSelection()](https://docs.qualcomm.com/doc/80-41102-2/topic/function_a00680_1a753038bf47ef487bde62991b528f4c8c.html#Documentationa00680_1a753038bf47ef487bde62991b528f4c8c)

Last Published: Jun 09, 2026

[Previous Topic
SIM services](https://docs.qualcomm.com/bundle/publicresource/80-41102-2/topics/sim_services.md) [Next Topic
Remote SIM](https://docs.qualcomm.com/bundle/publicresource/80-41102-2/topics/page_c_tafsimRsim.md)