Click here for the API reference documentation.

This file contains prototype definitions for high level SIM APIs.

Counting the SIM card slots
Creating a SIM object
Deleting a SIM object
SIM identification information
SIM Authentication
SIM states

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.

Counting the SIM card slots

le_sim_CountSlots() returns the number of SIM card sockets mounted on the device.

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 card socket number must be specified with a parameter. This passes the card socket number to create the required corresponding object to the selected SIM card. 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.

Deleting 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).

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.

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

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.

SIM Authentication

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

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

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

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

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

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.

SIM states

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

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

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.

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.

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