All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
SIM

API Reference

This file contains prototype definitions for SIM API.

A subscriber identity module or subscriber identification module (SIM) is an integrated circuit that securely stores the international mobile subscriber identity (IMSI) and related key used to identify and authenticate subscribers on M2M devices.

Most SIM cards can store a number of SMS messages and phone book contacts.

le_sim_GetSelectedCard() returns the selected SIM card number.

Creating a SIM object

You must create a SIM object by calling le_sim_Create() first; the requested SIM type must be specified with a parameter. Please refer to the target documentation for the supported SIM type list. This function passes the SIM type to create the required corresponding object. Resources are automatically allocated for the SIM object, which is referenced by le_sim_ObjRef_t type.

When the SIM object is no longer needed, you must call le_sim_Delete() to free all allocated ressources associated with the object.

Select a card to use

le_sim_SelectCard() function is used to select the SIM. By default, the SIM in slot 1 is used.

Note
The SIM selection is not reset persistent; this function has to be called at each start-up.

Delete a SIM object

To delete a SIM object, call le_sim_Delete(). This frees all the resources allocated for the SIM object. If several users own the SIM object (e.g., several handler functions registered for new state notifications), the SIM object will only be actually deleted after the last user deletes the SIM object.

SIM identification information

ICCID: Each SIM is internationally identified by its integrated circuit card identifier (ICCID). ICCIDs are stored in the SIM cards and engraved or printed on the SIM card body. The ICCID is defined by the ITU-T recommendation E.118 as the Primary Account Number. According to E.118, the number is up to 19 digits long, including a single check digit calculated using the Luhn algorithm. However, the GSM Phase 1 (ETSI Recommendation GSM 11.11) defined the ICCID length as 10 octets (20 digits) with operator-specific structure.

le_sim_GetICCID() API reads the identification number (ICCID).

Using this API selects the requested SIM.

IMSI: The International Mobile Subscriber Identity or IMSI is a unique identification associated with all cellular networks. The IMSI is used in any mobile network that connects with other networks. For GSM, UMTS and LTE network, this number is provisioned in the SIM card.

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

Home Network Name: le_sim_GetHomeNetworkOperator() retrieves the Home Network Name.

le_sim_GetIMSI() API reads the international mobile subscriber identity (IMSI).

Using this API selects the requested SIM.

Phone Number: le_sim_GetSubscriberPhoneNumber() API reads the Phone Number associated to the SIM. If the phone number has not been provisioned, it will return the empty string.

Using this API selects the requested SIM.

Home Network Information:

SIM Authentication

le_sim_EnterPIN() enters the PIN (Personal Identification Number) code that's required before any Mobile equipment functionality can be used.

Using this API selects the requested SIM.

le_sim_GetRemainingPINTries() returns the number of remaining PIN entry attempts before the SIM will become blocked.

Using this API selects the requested SIM.

le_sim_ChangePIN() must be called to change the PIN code.

Using this API selects the requested SIM.

le_sim_Lock() locks the SIM card: it enables requests for the PIN code.

Using this API selects the requested SIM.

le_sim_Unlock() unlocks the SIM card: it disables requests for the PIN code.

Using this API selects the requested SIM.

le_sim_Unblock() unblocks the SIM card. The SIM card is blocked after X unsuccessful attempts to enter the PIN. le_sim_Unblock() requires the PUK (Personal Unblocking) code to set a new PIN code.

Using this API selects the requested SIM.

SIM states

le_sim_IsPresent() API advises the SIM is inserted (and locked) or removed.

Using this API selects the requested SIM.

le_sim_IsReady() API advises the SIM is ready (PIN code correctly entered or not required).

Using this API selects the requested SIM.

The le_sim_GetState() API retrieves the SIM state:

  • LE_SIM_INSERTED : SIM card is inserted and locked.
  • LE_SIM_ABSENT : SIM card is absent.
  • LE_SIM_READY : SIM card is inserted and unlocked.
  • LE_SIM_BLOCKED : SIM card is blocked.
  • LE_SIM_BUSY : SIM card is busy.
  • LE_SIM_STATE_UNKNOWN : Unknown SIM state.

Using this API selects the requested SIM.

A handler function must be registered to receive SIM's state notifications. le_sim_AddNewStateHandler() API allows the User to register that handler.

The handler must satisfy the following prototype: typedef void(*le_sim_NewStateHandlerFunc_t)(le_sim_ObjRef_t sim);

When a new SIM's state is notified, a SIM object is automatically created and the handler is called.

Call le_sim_GetState() to retrieve the new state of the SIM.

Note
If two (or more) applications have registered a handler function for notifications, they will all receive it and will be passed the same SIM object reference.

The application can uninstall the handler function by calling le_sim_RemoveNewStateHandler() API.

Note
le_sim_RemoveNewStateHandler() API does not delete the SIM Object. The caller has to delete it.

Local SIM profile switch

As soon as there are several subscriptions/profiles in the eUICC (multi-profile), and one of them is dedicated to emergency calls (ex: eCall, ERA-Glonass), local swap is needed to swap as quickly as possible to the emergency profile in case of need.

“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 emergency subscription for a limited time, event triggering the swap back to commercial subscription being controlled by the User's application.

The le_sim_LocalSwapToEmergencyCallSubscription() function requests the multi-profile eUICC to swap to ECS and to refresh. The User's application must wait for eUICC reboot to be finished and network connection available.

The le_sim_LocalSwapToCommercialSubscription() function requests the multi-profile eUICC to swap back to commercial subscription and to refresh. The User's application must wait for eUICC reboot to be finished and network connection available.

The User's application can install an handler with le_sim_AddNewStateHandler() to receive eUICC's state notifications.

Warning
If you use a G&D card, be sure that your platform has disabled security restrictions for channel management APDU commands, otherwise local SIM profile switch could not work.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.

 Sierra Wireless  -  Generated by Doxygen 1.8.6