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
}

Select a card to use

taf_sim_SelectCard() is used to select the SIM card available on the user device. By default, the SIM card in slot1 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() will return the newly selected card, not necessarily the one previously set by taf_sim_SelectCard().

Note: The SIM selection is not power off persistent. This function needs to be called at each start-up.; 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() – Reads the identification number (ICCID).
taf_sim_AddNewStateHandler() – Registers a handler to get notification when card state changes.
taf_sim_RemoveNewStateHandler() – 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() retrieves the EID.

Home Network Name

taf_sim_GetHomeNetworkOperator() – Retrieves the name of the home network.
taf_sim_GetIMSI() – Gets the IMSI.

Phone Number

taf_sim_GetSubscriberPhoneNumber() – 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() – Retrieves the name of the home network.
taf_sim_GetHomeNetworkMccMnc() – Retrieves the MCC and MNC of the home network.

SIM Authentication

taf_sim_EnterPIN() – Enters the Personal Identification Number (PIN) code which is required before any mobile device functionality can be used.
taf_sim_GetRemainingPINTries() – Returns the number of remaining PIN entry attempts left before the SIM will be blocked.
taf_sim_GetRemainingPUKTries() – Returns the number of remaining PUK retry attempts left before the SIM get blocked.
taf_sim_ChangePIN() must be called to change the PIN code.
taf_sim_Lock() – Locks the SIM card and enables asking for the PIN code.
taf_sim_Unlock() – Unlocks the SIM card and disables asking for the PIN code.
taf_sim_Unblock() unblocks the SIM card. If the SIM card is blocked after X unsuccessful attempts to enter the PIN then taf_sim_Unblock() can be used with Personal Unblocking (PUK) code to set a new PIN code and unblock the SIM.

SIM states

taf_sim_IsPresent() – 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() – Indicates whether the SIM is ready (PIN code correctly entered or not required) to use.
taf_sim_GetState() – Retrieves the following SIM states.
- TAF_SIM_INSERTED – SIM card is inserted and locked.
- TAF_SIM_ABSENT – SIM card is not present, i.e., not inserted.
- TAF_SIM_READY – SIM card is present and unlocked.
- TAF_SIM_BLOCKED – SIM card is blocked and cannot be used unless it is unlocked it.
- TAF_SIM_BUSY – SIM card is busy, i.e., it is getting activated, getting unlocked, etc.
- TAF_SIM_POWER_DOWN – SIM card is powered OFF.
- TAF_SIM_STATE_UNKNOWN – Unknown SIM state; can occur when the state is not determined.

A handler function should be registered to receive SIM state notifications. taf_sim_AddNewStateHandler() 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 simId, taf_sim_States_t simState);

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

Call taf_sim_GetState() 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().

taf_sim_SetPower() – Powers up or down the current SIM card.
taf_sim_Reset() – Resets the specified card using the SIM-slot.

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

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() to open a logical channel in the SIM card. APDUs then can be sent to SIM card with taf_sim_SendApduOnChannel(). When the logical channel is no longer needed, it can be closed using taf_sim_CloseLogicalChannel().

Use taf_sim_IsEmergencyCallSubscriptionSelected() to know if the EMERGENCY profile is activated for the specified sim slot.

Warning: If no profile is active, it returns LE_NOT_FOUND.

Before the SIM sends a message, an application registers a callback handler using taf_sim_AddNewStateHandler(). 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);

Applications must use taf_sim_RemoveNewStateHandler() to release taf_sim_NewStateHandlerRef_t message handler reference object when it is no longer used.

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() function requests the multi-profile eUICC to swap to ECS and reboot. The user's application must wait for eUICC reboot to finish and a network connection to be available.

The taf_sim_LocalSwapToCommercialSubscription() function requests the multi-profile eUICC to swap back to a commercial subscription and reboot. The user's application must wait for eUICC reboot to finish and a network connection to be available.