#include "legato.h"
#include "le_mdmDefs_interface.h"

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_Obj *	le_sim_ObjRef_t

typedef struct le_sim_NewStateHandler *	le_sim_NewStateHandlerRef_t

typedef void(*	le_sim_NewStateHandlerFunc_t )(le_sim_ObjRef_t simRef, 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_Type_t { LE_SIM_EMBEDDED, LE_SIM_EXTERNAL_SLOT_1, LE_SIM_EXTERNAL_SLOT_2, LE_SIM_REMOTE, LE_SIM_TYPE_MAX }

enum	le_sim_Manufacturer_t { LE_SIM_OBERTHUR, LE_SIM_GEMALTO, LE_SIM_G_AND_D, LE_SIM_MORPHO, LE_SIM_MANUFACTURER_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_Type_t	le_sim_GetSelectedCard (void)

le_sim_ObjRef_t	le_sim_Create (le_sim_Type_t simType)

le_result_t	le_sim_SelectCard (le_sim_ObjRef_t simRef)

void	le_sim_Delete (le_sim_ObjRef_t simRef)

uint32_t	le_sim_GetSlotNumber (le_sim_ObjRef_t simRef)

le_result_t	le_sim_GetICCID (le_sim_ObjRef_t simRef, char *iccid, size_t iccidNumElements)

le_result_t	le_sim_GetIMSI (le_sim_ObjRef_t simRef, char *imsi, size_t imsiNumElements)

bool	le_sim_IsPresent (le_sim_ObjRef_t simRef)

bool	le_sim_IsReady (le_sim_ObjRef_t simRef)

le_result_t	le_sim_EnterPIN (le_sim_ObjRef_t simRef, const char *pin)

le_result_t	le_sim_ChangePIN (le_sim_ObjRef_t simRef, const char oldpin, const char newpin)

int32_t	le_sim_GetRemainingPINTries (le_sim_ObjRef_t simRef)

le_result_t	le_sim_Unlock (le_sim_ObjRef_t simRef, const char *pin)

le_result_t	le_sim_Lock (le_sim_ObjRef_t simRef, const char *pin)

le_result_t	le_sim_Unblock (le_sim_ObjRef_t simRef, const char puk, const char newpin)

le_sim_States_t	le_sim_GetState (le_sim_ObjRef_t simRef)

le_result_t	le_sim_GetSubscriberPhoneNumber (le_sim_ObjRef_t simRef, char *phoneNumberStr, size_t phoneNumberStrNumElements)

le_result_t	le_sim_GetHomeNetworkOperator (le_sim_ObjRef_t simRef, char *nameStr, size_t nameStrNumElements)

le_result_t	le_sim_GetHomeNetworkMccMnc (le_sim_ObjRef_t simRef, char mccPtr, size_t mccPtrNumElements, char mncPtr, size_t mncPtrNumElements)

le_result_t	le_sim_LocalSwapToEmergencyCallSubscription (le_sim_ObjRef_t simRef, le_sim_Manufacturer_t manufacturer)

le_result_t	le_sim_LocalSwapToCommercialSubscription (le_sim_ObjRef_t simRef, le_sim_Manufacturer_t manufacturer)

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_LEN 20

ICCID length According to GSM Phase 1

#define LE_SIM_IMSI_LEN 15

IMSI length

#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_LEN 8

PUK length (8 digits)

Typedef Documentation

typedef void(* le_sim_NewStateHandlerFunc_t)(le_sim_ObjRef_t simRef, void *contextPtr)

Handler for sim state changes.

Parameters

simRef	SIM reference.
contextPtr

typedef struct le_sim_NewStateHandler* le_sim_NewStateHandlerRef_t

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

typedef struct le_sim_Obj* le_sim_ObjRef_t

Reference type for referring to SIM objects.

Enumeration Type Documentation

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_Type_t

SIM type.

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.

Function Documentation

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_result_t le_sim_ChangePIN	(	le_sim_ObjRef_t	simRef,
		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]	simRef	The SIM object reference.
[in]	oldpin	The old PIN code.
[in]	newpin	The new PIN code.

void le_sim_ConnectService ( void )

Connect the client to the service

le_sim_ObjRef_t le_sim_Create ( le_sim_Type_t simType )

Create a SIM object.

Returns: Reference to the SIM object.

Note: On failure, the process exits, so no need to check the return value for validity

Parameters

[in] simType The SIM type.

void le_sim_Delete ( le_sim_ObjRef_t simRef )

Delete a SIM object.

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.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] simRef The SIM object reference.

void le_sim_DisconnectService ( void )

Disconnect the client from the service

le_result_t le_sim_EnterPIN	(	le_sim_ObjRef_t	simRef,
		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]	simRef	The SIM object reference.
[in]	pin	The PIN code.

le_result_t le_sim_GetHomeNetworkMccMnc	(	le_sim_ObjRef_t	simRef,
		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]	simRef	The SIM object reference.
[out]	mccPtr	Mobile Country Code
[in]	mccPtrNumElements
[out]	mncPtr	Mobile Network Code
[in]	mncPtrNumElements

le_result_t le_sim_GetHomeNetworkOperator	(	le_sim_ObjRef_t	simRef,
		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]	simRef	The SIM object reference.
[out]	nameStr	the home network Name
[in]	nameStrNumElements

le_result_t le_sim_GetICCID	(	le_sim_ObjRef_t	simRef,
		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]	simRef	The SIM object reference.
[out]	iccid	ICCID
[in]	iccidNumElements

le_result_t le_sim_GetIMSI	(	le_sim_ObjRef_t	simRef,
		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]	simRef	The SIM object reference.
[out]	imsi	IMSI
[in]	imsiNumElements

int32_t le_sim_GetRemainingPINTries ( le_sim_ObjRef_t simRef )

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] simRef The SIM object reference.

le_sim_Type_t le_sim_GetSelectedCard ( void )

Get the current selected card.

Returns: Number of the current selected SIM card.

uint32_t le_sim_GetSlotNumber ( le_sim_ObjRef_t simRef )

Retrieve the slot number of the SIM card.

Returns: Slot number of the SIM card.

Note: If the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters

[in] simRef The SIM object reference.

le_sim_States_t le_sim_GetState ( le_sim_ObjRef_t simRef )

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] simRef The SIM object reference.

le_result_t le_sim_GetSubscriberPhoneNumber	(	le_sim_ObjRef_t	simRef,
		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]	simRef	The SIM object reference.
[out]	phoneNumberStr	The phone Number.
[in]	phoneNumberStrNumElements

bool le_sim_IsPresent ( le_sim_ObjRef_t simRef )

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] simRef The SIM object reference.

bool le_sim_IsReady ( le_sim_ObjRef_t simRef )

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] simRef The SIM object reference.

le_result_t le_sim_LocalSwapToCommercialSubscription	(	le_sim_ObjRef_t	simRef,
		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_BUSY when a profile swap is already in progress
LE_FAULT for unexpected error

Parameters

[in]	simRef	The SIM object reference.
[in]	manufacturer	The card manufacturer.

le_result_t le_sim_LocalSwapToEmergencyCallSubscription	(	le_sim_ObjRef_t	simRef,
		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_BUSY when a profile swap is already in progress
LE_FAULT for unexpected error

Parameters

[in]	simRef	The SIM object reference.
[in]	manufacturer	The card manufacturer.

le_result_t le_sim_Lock	(	le_sim_ObjRef_t	simRef,
		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]	simRef	The SIM object reference.
[in]	pin	The PIN code.

void le_sim_RemoveNewStateHandler ( le_sim_NewStateHandlerRef_t addHandlerRef )

Remove handler function for EVENT 'le_sim_NewState'

Parameters

[in] addHandlerRef

le_result_t le_sim_SelectCard ( le_sim_ObjRef_t simRef )

Select a SIM.

Returns: LE_FAULT Function failed to select the requested SIM; LE_OK Function succeeded.

Parameters

[in] simRef The SIM object reference.

le_result_t le_sim_Unblock	(	le_sim_ObjRef_t	simRef,
		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]	simRef	The SIM object reference.
[in]	puk	The PUK code.
[in]	newpin	The PIN code.

le_result_t le_sim_Unlock	(	le_sim_ObjRef_t	simRef,
		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]	simRef	The SIM object reference.
[in]	pin	The PIN code.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation