#include "legato.h"

Macros
#define	LE_SIM_PIN_MIN_LEN 4

#define	LE_SIM_PIN_MAX_LEN 8

#define	LE_SIM_PUK_LEN 8

#define	LE_SIM_ICCID_LEN 21

#define	LE_SIM_IMSI_LEN 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 }

Functions
void	le_sim_StartClient (const char *serviceInstanceName)

void	le_sim_StopClient (void)

le_sim_NewStateHandlerRef_t	le_sim_AddNewStateHandler (le_sim_NewStateHandlerFunc_t handlerPtr, void *contextPtr)

void	le_sim_RemoveNewStateHandler (le_sim_NewStateHandlerRef_t addHandlerRef)

uint32_t	le_sim_CountSlots (void)

uint32_t	le_sim_GetSelectedCard (void)

le_sim_ObjRef_t	le_sim_Create (uint32_t cardNum)

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)

Detailed Description

Legato SIM Services include file.

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

Macro Definition Documentation

#define LE_SIM_ICCID_LEN 21

ICCID length According to GSM Phase 1

#define LE_SIM_IMSI_LEN 16

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_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 for le_sim_NewStateHandler handler ADD/REMOVE functions

typedef struct le_sim_Obj* le_sim_ObjRef_t

Reference type for referring to SIM objects.

Enumeration Type Documentation

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.

Function Documentation

le_sim_NewStateHandlerRef_t le_sim_AddNewStateHandler	(	le_sim_NewStateHandlerFunc_t	handlerPtr,
		void *	contextPtr
	)

le_sim_NewStateHandler handler ADD function

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

uint32_t le_sim_CountSlots ( void )

Count the number of SIM card slots.

Returns: Number of the SIM card slots mounted on the device.

le_sim_ObjRef_t le_sim_Create ( uint32_t cardNum )

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] cardNum The SIM card number. (1 or 2, it depends on the platform).

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.

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_NOT_FOUND Function failed to select the SIM card for this operation.; LE_UNDERFLOW PIN code is not long enough (min 4 digits).; LE_NOT_POSSIBLE Function failed to enter 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.
[in]	pin	The PIN code.

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_NOT_POSSIBLE 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.
[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_OK IMSI was successfully retrieved.; LE_OVERFLOW imsiPtr buffer was too small for the IMSI.; LE_NOT_POSSIBLE IMSI 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.
[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 Function failed to select the SIM card for this operation.; LE_NOT_POSSIBLE Function failed to get the number of remaining PIN insertion tries.; A positive value 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.

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

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.

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_NOT_POSSIBLE 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.
[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.

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.

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_NOT_POSSIBLE 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.
[in]	pin	The PIN code.

void le_sim_RemoveNewStateHandler ( le_sim_NewStateHandlerRef_t addHandlerRef )

le_sim_NewStateHandler handler REMOVE function

Parameters

[in] addHandlerRef

void le_sim_StartClient ( const char * serviceInstanceName )

Start the service for the client main thread

Parameters

[in] serviceInstanceName

void le_sim_StopClient ( void )

Stop the service for the current client thread

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_NOT_POSSIBLE Function failed to unblock 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.
[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_NOT_POSSIBLE 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.
[in]	pin	The PIN code.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation