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

simId	The SIM identifier.
simState	The 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

simId	The SIM identifier.
stkEvent	The 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

enum le_sim_Id_t

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.

enum le_sim_Manufacturer_t

Card Manufacturer.

Enumerator
LE_SIM_OBERTHUR	Oberthur.
LE_SIM_GEMALTO	Gemalto.
LE_SIM_G_AND_D	G&D.
LE_SIM_MORPHO	Morpho.

enum le_sim_States_t

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.

enum le_sim_StkEvent_t

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]

simId

The 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]	simId	The SIM identifier.
[in]	oldpin	The old PIN code.
[in]	newpin	The new PIN code.

void le_sim_ConnectService

(

void

)

Connect the current client thread to the service providing this API.

This function must be called before any other functions in this API. Normally, it's automatically called for the main thread, but must be explicitly called for other threads. For details, see Client-specific Functions.

This function is created automatically.

void le_sim_DisconnectService

(

void

)

Disconnect the current client thread from the service providing this API.

Normally, this function doesn't need to be called. After this function is called, there's no longer a connection to the service, and the functions in this API can't be used. For details, see Client-specific Functions.

This function is created automatically.

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]	simId	The SIM identifier.
[in]	pin	The 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]	simId	The SIM identifier.
[out]	mccPtr	Mobile Country Code
[in]	mccPtrNumElements
[out]	mncPtr	Mobile 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]	simId	The SIM identifier.
[out]	nameStr	the 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]	simId	The SIM identifier.
[out]	iccid	ICCID
[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]	simId	The SIM identifier.
[out]	imsi	IMSI
[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]

simId

The 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]

simId

The 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]	simId	The SIM identifier.
[out]	phoneNumberStr	The 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]	simId	The SIM identifier
[out]	isEcsPtr	true 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]

simId

The 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]

simId

The 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

Warning

If you use a Morpho or Oberthur card, the SIM_REFRESH PRO-ACTIVE command must be accepted with le_sim_AcceptSimToolkitCommand() in order to complete the profile swap procedure.

Parameters

[in]	simId	The SIM identifier.
[in]	manufacturer	The 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

Warning

If you use a Morpho or Oberthur card, the SIM_REFRESH PRO-ACTIVE command must be accepted with le_sim_AcceptSimToolkitCommand() in order to complete the profile swap procedure.

Parameters

[in]	simId	The SIM identifier.
[in]	manufacturer	The 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]	simId	The SIM identifier.
[in]	pin	The 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]

simId

The 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]

simId

The 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]	simId	The SIM identifier.
[in]	puk	The PUK code.
[in]	newpin	The 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]	simId	The SIM identifier.
[in]	pin	The PIN code.