le_sim_interface.h File Reference
#include "legato.h"
#include "le_mdmDefs_interface.h"

Go to the source code of this file.

Macros

#define LE_SIM_PIN_MIN_LEN   4
 
#define LE_SIM_PIN_MAX_LEN   8
 
#define LE_SIM_PIN_MAX_BYTES   9
 
#define LE_SIM_PUK_MAX_LEN   8
 
#define LE_SIM_PUK_MAX_BYTES   9
 
#define LE_SIM_ICCID_LEN   20
 
#define LE_SIM_ICCID_BYTES   21
 
#define LE_SIM_IMSI_LEN   15
 
#define LE_SIM_IMSI_BYTES   16
 

Typedefs

typedef struct le_sim_NewStateHandler * le_sim_NewStateHandlerRef_t
 
typedef struct le_sim_SimToolkitEventHandler * le_sim_SimToolkitEventHandlerRef_t
 
typedef void(* le_sim_NewStateHandlerFunc_t) (le_sim_Id_t simId, le_sim_States_t simState, void *contextPtr)
 
typedef void(* le_sim_SimToolkitEventHandlerFunc_t) (le_sim_Id_t simId, le_sim_StkEvent_t stkEvent, void *contextPtr)
 

Enumerations

enum  le_sim_States_t {
  LE_SIM_INSERTED, LE_SIM_ABSENT, LE_SIM_READY, LE_SIM_BLOCKED,
  LE_SIM_BUSY, LE_SIM_STATE_UNKNOWN
}
 
enum  le_sim_Id_t {
  LE_SIM_EMBEDDED, LE_SIM_EXTERNAL_SLOT_1, LE_SIM_EXTERNAL_SLOT_2, LE_SIM_REMOTE,
  LE_SIM_ID_MAX
}
 
enum  le_sim_Manufacturer_t {
  LE_SIM_OBERTHUR, LE_SIM_GEMALTO, LE_SIM_G_AND_D, LE_SIM_MORPHO,
  LE_SIM_MANUFACTURER_MAX
}
 
enum  le_sim_StkEvent_t { LE_SIM_OPEN_CHANNEL, LE_SIM_REFRESH, LE_SIM_STK_EVENT_MAX }
 

Functions

void le_sim_ConnectService (void)
 
void le_sim_DisconnectService (void)
 
le_sim_NewStateHandlerRef_t le_sim_AddNewStateHandler (le_sim_NewStateHandlerFunc_t handlerPtr, void *contextPtr)
 
void le_sim_RemoveNewStateHandler (le_sim_NewStateHandlerRef_t addHandlerRef)
 
le_sim_SimToolkitEventHandlerRef_t le_sim_AddSimToolkitEventHandler (le_sim_SimToolkitEventHandlerFunc_t handlerPtr, void *contextPtr)
 
void le_sim_RemoveSimToolkitEventHandler (le_sim_SimToolkitEventHandlerRef_t addHandlerRef)
 
le_sim_Id_t le_sim_GetSelectedCard (void)
 
le_result_t le_sim_SelectCard (le_sim_Id_t simId)
 
le_result_t le_sim_GetICCID (le_sim_Id_t simId, char *iccid, size_t iccidNumElements)
 
le_result_t le_sim_GetIMSI (le_sim_Id_t simId, char *imsi, size_t imsiNumElements)
 
bool le_sim_IsPresent (le_sim_Id_t simId)
 
bool le_sim_IsReady (le_sim_Id_t simId)
 
le_result_t le_sim_EnterPIN (le_sim_Id_t simId, const char *pin)
 
le_result_t le_sim_ChangePIN (le_sim_Id_t simId, const char *oldpin, const char *newpin)
 
int32_t le_sim_GetRemainingPINTries (le_sim_Id_t simId)
 
le_result_t le_sim_Unlock (le_sim_Id_t simId, const char *pin)
 
le_result_t le_sim_Lock (le_sim_Id_t simId, const char *pin)
 
le_result_t le_sim_Unblock (le_sim_Id_t simId, const char *puk, const char *newpin)
 
le_sim_States_t le_sim_GetState (le_sim_Id_t simId)
 
le_result_t le_sim_GetSubscriberPhoneNumber (le_sim_Id_t simId, char *phoneNumberStr, size_t phoneNumberStrNumElements)
 
le_result_t le_sim_GetHomeNetworkOperator (le_sim_Id_t simId, char *nameStr, size_t nameStrNumElements)
 
le_result_t le_sim_GetHomeNetworkMccMnc (le_sim_Id_t simId, char *mccPtr, size_t mccPtrNumElements, char *mncPtr, size_t mncPtrNumElements)
 
le_result_t le_sim_LocalSwapToEmergencyCallSubscription (le_sim_Id_t simId, le_sim_Manufacturer_t manufacturer)
 
le_result_t le_sim_LocalSwapToCommercialSubscription (le_sim_Id_t simId, le_sim_Manufacturer_t manufacturer)
 
le_result_t le_sim_IsEmergencyCallSubscriptionSelected (le_sim_Id_t simId, bool *isEcsPtr)
 
le_result_t le_sim_AcceptSimToolkitCommand (le_sim_Id_t simId)
 
le_result_t le_sim_RejectSimToolkitCommand (le_sim_Id_t simId)
 

Detailed Description

Legato SIM include file.

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

Macro Definition Documentation

#define LE_SIM_ICCID_BYTES   21

ICCID length One extra byte is added for the null character.

#define LE_SIM_ICCID_LEN   20

ICCID length According to GSM Phase 1

#define LE_SIM_IMSI_BYTES   16

IMSI length One extra byte is added for the null character.

#define LE_SIM_IMSI_LEN   15

IMSI length

#define LE_SIM_PIN_MAX_BYTES   9

Maximum PIN length (8 digits) One extra byte is added for the null character.

#define LE_SIM_PIN_MAX_LEN   8

Maximum PIN length (8 digits)

#define LE_SIM_PIN_MIN_LEN   4

Minimum PIN length (4 digits)

#define LE_SIM_PUK_MAX_BYTES   9

PUK length (8 digits) One extra byte is added for the null character.

#define LE_SIM_PUK_MAX_LEN   8

PUK length (8 digits)

Typedef Documentation

typedef void(* le_sim_NewStateHandlerFunc_t) (le_sim_Id_t simId, le_sim_States_t simState, void *contextPtr)

Handler for sim state changes.

Parameters
simIdThe SIM identifier.
simStateThe SIM state.
contextPtr
typedef struct le_sim_NewStateHandler* le_sim_NewStateHandlerRef_t

Reference type used by Add/Remove functions for EVENT 'le_sim_NewState'

typedef void(* le_sim_SimToolkitEventHandlerFunc_t) (le_sim_Id_t simId, le_sim_StkEvent_t stkEvent, void *contextPtr)

Handler for Sim Toolkit Events.

Parameters
simIdThe SIM identifier.
stkEventThe SIM state.
contextPtr
typedef struct le_sim_SimToolkitEventHandler* le_sim_SimToolkitEventHandlerRef_t

Reference type used by Add/Remove functions for EVENT 'le_sim_SimToolkitEvent'

Enumeration Type Documentation

SIM identifiers.

Enumerator
LE_SIM_EMBEDDED 

Embedded SIM.

LE_SIM_EXTERNAL_SLOT_1 

SIM inserted in external slot 1.

LE_SIM_EXTERNAL_SLOT_2 

SIM inserted in external slot 2.

LE_SIM_REMOTE 

Remote SIM.

Card Manufacturer.

Enumerator
LE_SIM_OBERTHUR 

Oberthur.

LE_SIM_GEMALTO 

Gemalto.

LE_SIM_G_AND_D 

G&D.

LE_SIM_MORPHO 

Morpho.

SIM states.

Enumerator
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.

SIM Toolkit events.

Enumerator
LE_SIM_OPEN_CHANNEL 

SIM card ask to open a logical channel.

LE_SIM_REFRESH 

SIM card ask for a refresh.

LE_SIM_STK_EVENT_MAX 

Unknown SIM Toolkit event.

Function Documentation

le_result_t le_sim_AcceptSimToolkitCommand ( le_sim_Id_t  simId)

Accept the last SIM Toolkit command.

Returns
LE_FAULT Function failed.
LE_OK Function succeeded.
Parameters
[in]simIdThe SIM identifier.
le_sim_NewStateHandlerRef_t le_sim_AddNewStateHandler ( le_sim_NewStateHandlerFunc_t  handlerPtr,
void *  contextPtr 
)

Add handler function for EVENT 'le_sim_NewState'

This event provides information on sim state changes.

Parameters
[in]handlerPtr
[in]contextPtr
le_sim_SimToolkitEventHandlerRef_t le_sim_AddSimToolkitEventHandler ( le_sim_SimToolkitEventHandlerFunc_t  handlerPtr,
void *  contextPtr 
)

Add handler function for EVENT 'le_sim_SimToolkitEvent'

This event provides information on Sim Toolkit application.

Parameters
[in]handlerPtr
[in]contextPtr
le_result_t le_sim_ChangePIN ( le_sim_Id_t  simId,
const char *  oldpin,
const char *  newpin 
)

Change the PIN code.

Returns
LE_NOT_FOUND Function failed to select the SIM card for this operation.
LE_UNDERFLOW PIN code is/are not long enough (min 4 digits).
LE_FAULT Function failed to change the PIN code.
LE_OK Function succeeded.
Note
If PIN code is too long (max 8 digits), it is a fatal error, the function will not return.
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
[in]oldpinThe old PIN code.
[in]newpinThe new PIN code.
void le_sim_ConnectService ( void  )

Connect the client to the service

void le_sim_DisconnectService ( void  )

Disconnect the client from the service

le_result_t le_sim_EnterPIN ( le_sim_Id_t  simId,
const char *  pin 
)

This function must be called to enter the PIN code.

Returns
LE_BAD_PARAMETER The parameters are invalid.
LE_NOT_FOUND The function failed to select the SIM card for this operation.
LE_UNDERFLOW The PIN code is not long enough (min 4 digits).
LE_FAULT The function failed to enter the PIN code.
LE_OK The function succeeded.
Note
If PIN code is too long (max 8 digits), it is a fatal error, the function will not return.
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
[in]pinThe PIN code.
le_result_t le_sim_GetHomeNetworkMccMnc ( le_sim_Id_t  simId,
char *  mccPtr,
size_t  mccPtrNumElements,
char *  mncPtr,
size_t  mncPtrNumElements 
)

This function must be called to get the Home Network MCC MNC.

Returns
  • LE_OK on success
  • LE_NOT_FOUND if Home Network has not been provisioned
  • LE_FAULT for unexpected error
Note
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
[out]mccPtrMobile Country Code
[in]mccPtrNumElements
[out]mncPtrMobile Network Code
[in]mncPtrNumElements
le_result_t le_sim_GetHomeNetworkOperator ( le_sim_Id_t  simId,
char *  nameStr,
size_t  nameStrNumElements 
)

This function must be called to get the Home Network Name information.

Returns
  • LE_OK on success
  • LE_OVERFLOW if the Home Network Name can't fit in nameStr
  • LE_NOT_FOUND if the network is not found
  • LE_BAD_PARAMETER if a parameter is invalid
  • LE_FAULT on any other failure
Note
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
[out]nameStrthe home network Name
[in]nameStrNumElements
le_result_t le_sim_GetICCID ( le_sim_Id_t  simId,
char *  iccid,
size_t  iccidNumElements 
)

Retrieves the integrated circuit card identifier (ICCID) of the SIM card (20 digits)

Returns
LE_OK ICCID was successfully retrieved.
LE_OVERFLOW iccidPtr buffer was too small for the ICCID.
LE_BAD_PARAMETER if a parameter is invalid
LE_FAULT The ICCID could not be retrieved.
Note
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
[out]iccidICCID
[in]iccidNumElements
le_result_t le_sim_GetIMSI ( le_sim_Id_t  simId,
char *  imsi,
size_t  imsiNumElements 
)

Retrieves the identification number (IMSI) of the SIM card. (max 15 digits)

Returns
LE_OVERFLOW The imsiPtr buffer was too small for the IMSI.
LE_BAD_PARAMETER The parameters are invalid.
LE_FAULT The function failed.
LE_TIMEOUT No response was received.
LE_OK The function succeeded.
Note
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
[out]imsiIMSI
[in]imsiNumElements
int32_t le_sim_GetRemainingPINTries ( le_sim_Id_t  simId)

Get the number of remaining PIN insertion tries.

Returns
LE_NOT_FOUND The function failed to select the SIM card for this operation.
LE_FAULT The function failed to get the number of remaining PIN insertion tries.
A positive value The function succeeded. The number of remaining PIN insertion tries.
Note
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
le_sim_Id_t le_sim_GetSelectedCard ( void  )

Get the current selected card.

Returns
Number of the current selected SIM card.
le_sim_States_t le_sim_GetState ( le_sim_Id_t  simId)

Get the SIM state.

Returns
Current SIM state.
Note
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
le_result_t le_sim_GetSubscriberPhoneNumber ( le_sim_Id_t  simId,
char *  phoneNumberStr,
size_t  phoneNumberStrNumElements 
)

Get the SIM Phone Number.

Returns
  • LE_OK on success
  • LE_OVERFLOW if the Phone Number can't fit in phoneNumberStr
  • LE_BAD_PARAMETER if a parameter is invalid
  • LE_FAULT on any other failure
Note
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
[out]phoneNumberStrThe phone Number.
[in]phoneNumberStrNumElements
le_result_t le_sim_IsEmergencyCallSubscriptionSelected ( le_sim_Id_t  simId,
bool *  isEcsPtr 
)

This function must be called to get the current subscription.

Returns
  • LE_OK on success
  • LE_BAD_PARAMETER invalid SIM identifier
  • LE_NOT_FOUND cannot determine the current selected subscription
  • LE_FAULT for unexpected errors
Warning
There is no standard method to interrogate the current selected subscription. The returned value of this function is based on the last executed local swap command. This means that this function will always return LE_NOT_FOUND error at Legato startup.
Parameters
[in]simIdThe SIM identifier
[out]isEcsPtrtrue if Emergency Call Subscription (ECS) is selected, false if Commercial Subscription is selected
bool le_sim_IsPresent ( le_sim_Id_t  simId)

Verify if the SIM card is present or not.

Returns
true SIM card is present.
false SIM card is absent
Note
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
bool le_sim_IsReady ( le_sim_Id_t  simId)

Verify if the SIM is ready (PIN code correctly inserted or not required).

Returns
true PIN is correctly inserted or not required.
false PIN must be inserted
Note
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
le_result_t le_sim_LocalSwapToCommercialSubscription ( le_sim_Id_t  simId,
le_sim_Manufacturer_t  manufacturer 
)

This function must be called to request 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.

Returns
  • LE_OK on success
  • LE_BAD_PARAMETER invalid SIM identifier
  • LE_BUSY when a profile swap is already in progress
  • LE_FAULT for unexpected error
Parameters
[in]simIdThe SIM identifier.
[in]manufacturerThe card manufacturer.
le_result_t le_sim_LocalSwapToEmergencyCallSubscription ( le_sim_Id_t  simId,
le_sim_Manufacturer_t  manufacturer 
)

This function must be called to request 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.

Returns
  • LE_OK on success
  • LE_BAD_PARAMETER invalid SIM identifier
  • LE_BUSY when a profile swap is already in progress
  • LE_FAULT for unexpected error
Parameters
[in]simIdThe SIM identifier.
[in]manufacturerThe card manufacturer.
le_result_t le_sim_Lock ( le_sim_Id_t  simId,
const char *  pin 
)

Lock the SIM card: it enables the request of the PIN code.

Returns
LE_NOT_FOUND Function failed to select the SIM card for this operation.
LE_UNDERFLOW PIN code is not long enough (min 4 digits).
LE_FAULT The function failed to unlock the SIM card.
LE_OK Function succeeded.
Note
If PIN code is too long (max 8 digits), it is a fatal error, the function will not return.
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
[in]pinThe PIN code.
le_result_t le_sim_RejectSimToolkitCommand ( le_sim_Id_t  simId)

Reject the last SIM Toolkit command.

Returns
LE_FAULT Function failed.
LE_OK Function succeeded.
Parameters
[in]simIdThe SIM identifier.
void le_sim_RemoveNewStateHandler ( le_sim_NewStateHandlerRef_t  addHandlerRef)

Remove handler function for EVENT 'le_sim_NewState'

Parameters
[in]addHandlerRef
void le_sim_RemoveSimToolkitEventHandler ( le_sim_SimToolkitEventHandlerRef_t  addHandlerRef)

Remove handler function for EVENT 'le_sim_SimToolkitEvent'

Parameters
[in]addHandlerRef
le_result_t le_sim_SelectCard ( le_sim_Id_t  simId)

Select a SIM.

Returns
LE_FAULT Function failed to select the requested SIM
LE_OK Function succeeded.
Parameters
[in]simIdThe SIM identifier.
le_result_t le_sim_Unblock ( le_sim_Id_t  simId,
const char *  puk,
const char *  newpin 
)

Unblock the SIM card.

Returns
LE_NOT_FOUND Function failed to select the SIM card for this operation.
LE_UNDERFLOW PIN code is not long enough (min 4 digits).
LE_OUT_OF_RANGE PUK code length is not correct (8 digits).
LE_FAULT The function failed to unlock the SIM card.
LE_OK Function succeeded.
Note
If new PIN or puk code are too long (max 8 digits), it is a fatal error, the function will not return.
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
[in]pukThe PUK code.
[in]newpinThe PIN code.
le_result_t le_sim_Unlock ( le_sim_Id_t  simId,
const char *  pin 
)

Unlock the SIM card: it disables the request of the PIN code.

Returns
LE_NOT_FOUND Function failed to select the SIM card for this operation.
LE_UNDERFLOW PIN code is not long enough (min 4 digits).
LE_FAULT The function failed to unlock the SIM card.
LE_OK Function succeeded.
Note
If PIN code is too long (max 8 digits), it is a fatal error, the function will not return.
If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.
Parameters
[in]simIdThe SIM identifier.
[in]pinThe PIN code.