interfaces/modemServices/c/le_sim.h File Reference

#include "legato.h"
#include "le_mdm_defs.h"

Go to the source code of this file.

Defines
#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   (20+1)
#define	LE_SIM_IMSI_LEN   (15+1)
Typedefs
typedef struct le_Sim *	le_sim_Ref_t
typedef struct le_sim_NewStateHandler *	le_sim_NewStateHandlerRef_t
typedef void(*	le_sim_NewStateHandlerFunc_t )(le_sim_Ref_t simRef, void *contextPtr)
Functions
uint32_t	le_sim_CountSlots (void)
uint32_t	le_sim_GetSelectedCard (void)
le_sim_Ref_t	le_sim_Create (uint32_t cardNum)
void	le_sim_Delete (le_sim_Ref_t simRef)
uint32_t	le_sim_GetSlotNumber (le_sim_Ref_t simRef)
le_result_t	le_sim_GetICCID (le_sim_Ref_t simRef, char *iccidPtr, size_t iccidLen)
le_result_t	le_sim_GetIMSI (le_sim_Ref_t simRef, char *imsiPtr, size_t imsiLen)
bool	le_sim_IsPresent (le_sim_Ref_t simRef)
bool	le_sim_IsReady (le_sim_Ref_t simRef)
le_result_t	le_sim_EnterPIN (le_sim_Ref_t simRef, const char *pinPtr)
le_result_t	le_sim_ChangePIN (le_sim_Ref_t simRef, const char *oldpinPtr, const char *newpinPtr)
int32_t	le_sim_GetRemainingPINTries (le_sim_Ref_t simRef)
le_result_t	le_sim_Unlock (le_sim_Ref_t simRef, const char *pinPtr)
le_result_t	le_sim_Lock (le_sim_Ref_t simRef, const char *pinPtr)
le_result_t	le_sim_Unblock (le_sim_Ref_t simRef, const char *pukPtr, const char *newpinPtr)
le_sim_States_t	le_sim_GetState (le_sim_Ref_t simRef)
le_sim_NewStateHandlerRef_t	le_sim_AddNewStateHandler (le_sim_NewStateHandlerFunc_t handlerFuncPtr, void *contextPtr)
void	le_sim_RemoveNewStateHandler (le_sim_NewStateHandlerRef_t handlerRef)
le_result_t	le_sim_GetSubscriberPhoneNumber (le_sim_Ref_t simRef, char *phoneNumberStr, size_t phoneNumberStrSize)

---

Detailed Description

Legato SIM Services include file.

Copyright (C) Sierra Wireless, Inc. 2013. All rights reserved. Use of this work is subject to license.

---

Define Documentation

#define LE_SIM_ICCID_LEN   (20+1)

ICCID length According to GSM Phase 1

#define LE_SIM_IMSI_LEN   (15+1)

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_Ref_t simRef, void *contextPtr)

Prototype for handler functions used to report SIM state notifications.

Parameters:

simRef	SIM reference.
contextPtr	Context information the event handler may require.

typedef struct le_sim_NewStateHandler* le_sim_NewStateHandlerRef_t

Reference to a "New State" event handler that was registered using le_sim_AddNewStateHandler().

typedef struct le_Sim* le_sim_Ref_t

Declare a reference type for referring to SIM objects.

---

Function Documentation

le_sim_NewStateHandlerRef_t le_sim_AddNewStateHandler	(	le_sim_NewStateHandlerFunc_t	handlerFuncPtr,
		void *	contextPtr
	)

Register a handler function for New State notification.

Returns:

A handler reference, only needed to remove the handler.

Note:

Doesn't return on failure, so there's no need to check the return value for errors.

Parameters:

[in]	handlerFuncPtr	Handler function for New State notification.
[in]	contextPtr	Handler's context.

le_result_t le_sim_ChangePIN	(	le_sim_Ref_t	simRef,
		const char *	oldpinPtr,
		const char *	newpinPtr
	)

Change the PIN code.

Returns:

LE_NOT_FOUND Function failed to select the SIM card for this operation.

LE_OVERFLOW PIN code is/are too long (max 8 digits).

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 the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters:

[in]	simRef	SIM object.
[in]	oldpinPtr	old PIN code.
[in]	newpinPtr	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_Ref_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_Ref_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

SIM object.

le_result_t le_sim_EnterPIN	(	le_sim_Ref_t	simRef,
		const char *	pinPtr
	)

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_OVERFLOW PIN code is too long (max 8 digits).

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 the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters:

[in]	simRef	SIM object.
[in]	pinPtr	PIN code.

le_result_t le_sim_GetICCID	(	le_sim_Ref_t	simRef,
		char *	iccidPtr,
		size_t	iccidLen
	)

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	SIM object.
[out]	iccidPtr	Buffer to hold the ICCID.
[in]	iccidLen	Buffer length

le_result_t le_sim_GetIMSI	(	le_sim_Ref_t	simRef,
		char *	imsiPtr,
		size_t	imsiLen
	)

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	SIM object.
[out]	imsiPtr	Buffer to hold the IMSI.
[in]	imsiLen	Buffer length

int32_t le_sim_GetRemainingPINTries

(

le_sim_Ref_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

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_Ref_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

SIM object.

le_sim_States_t le_sim_GetState

(

le_sim_Ref_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

SIM object.

le_result_t le_sim_GetSubscriberPhoneNumber	(	le_sim_Ref_t	simRef,
		char *	phoneNumberStr,
		size_t	phoneNumberStrSize
	)

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	SIM object.
[out]	phoneNumberStr	The phone Number
[in]	phoneNumberStrSize	Size of phoneNumberStr

bool le_sim_IsPresent

(

le_sim_Ref_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

SIM object.

bool le_sim_IsReady

(

le_sim_Ref_t

simRef

)

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

true PIN is correctly inserted or not required.

Returns:

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

SIM object.

le_result_t le_sim_Lock	(	le_sim_Ref_t	simRef,
		const char *	pinPtr
	)

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_OVERFLOW PIN code is too long (max 8 digits).

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 the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters:

[in]	simRef	SIM object.
[in]	pinPtr	PIN code.

void le_sim_RemoveNewStateHandler

(

le_sim_NewStateHandlerRef_t

handlerRef

)

Unregister a handler function

Note:

Doesn't return on failure, don't need to check the return value for errors.

Parameters:

[in]

handlerRef

Handler reference.

le_result_t le_sim_Unblock	(	le_sim_Ref_t	simRef,
		const char *	pukPtr,
		const char *	newpinPtr
	)

Unblock the SIM card.

Returns:

LE_NOT_FOUND Function failed to select the SIM card for this operation.

LE_OVERFLOW PIN code is too long (max 8 digits).

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 the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters:

[in]	simRef	SIM object.
[in]	pukPtr	PUK code.
[in]	newpinPtr	New PIN code.

le_result_t le_sim_Unlock	(	le_sim_Ref_t	simRef,
		const char *	pinPtr
	)

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_OVERFLOW PIN code is too long (max 8 digits).

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 the caller is passing a bad pointer into this function, it is a fatal error, the function will not return.

Parameters:

[in]	simRef	SIM object.
[in]	pinPtr	PIN code.