le_sim_interface.h File Reference
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 |
#define | LE_SIM_APDU_MAX_BYTES 255 |
#define | LE_SIM_RESPONSE_MAX_BYTES 256 |
#define | LE_SIM_FILE_ID_LEN 4 |
#define | LE_SIM_FILE_ID_BYTES 5 |
#define | LE_SIM_DATA_MAX_BYTES 100 |
#define | LE_SIM_PATH_MAX_LEN 100 |
#define | LE_SIM_PATH_MAX_BYTES 101 |
Typedefs | |
typedef void(* | le_sim_DisconnectHandler_t) (void *) |
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 = 0, LE_SIM_ABSENT = 1, LE_SIM_READY = 2, LE_SIM_BLOCKED = 3, LE_SIM_BUSY = 4, LE_SIM_STATE_UNKNOWN = 5 } |
enum | le_sim_Id_t { LE_SIM_EMBEDDED = 0, LE_SIM_EXTERNAL_SLOT_1 = 1, LE_SIM_EXTERNAL_SLOT_2 = 2, LE_SIM_REMOTE = 3, LE_SIM_ID_MAX = 4 } |
enum | le_sim_Manufacturer_t { LE_SIM_OBERTHUR = 0, LE_SIM_GEMALTO = 1, LE_SIM_G_AND_D = 2, LE_SIM_MORPHO = 3, LE_SIM_VALID = 4, LE_SIM_MANUFACTURER_MAX = 5 } |
enum | le_sim_Command_t { LE_SIM_READ_RECORD = 0, LE_SIM_READ_BINARY = 1, LE_SIM_UPDATE_RECORD = 2, LE_SIM_UPDATE_BINARY = 3, LE_SIM_COMMAND_MAX = 4 } |
enum | le_sim_StkEvent_t { LE_SIM_OPEN_CHANNEL = 0, LE_SIM_REFRESH = 1, LE_SIM_STK_EVENT_MAX = 2 } |
Detailed Description
Legato SIM include file.
Copyright (C) Sierra Wireless Inc.
Macro Definition Documentation
#define LE_SIM_APDU_MAX_BYTES 255 |
APDU length
#define LE_SIM_DATA_MAX_BYTES 100 |
SIM data command length
#define LE_SIM_FILE_ID_BYTES 5 |
SIM file identifier length One extra byte is added for the null character.
#define LE_SIM_FILE_ID_LEN 4 |
SIM file identifier length
#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_PATH_MAX_BYTES 101 |
SIM file path length One extra byte is added for the null character.
#define LE_SIM_PATH_MAX_LEN 100 |
SIM file path 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)
#define LE_SIM_RESPONSE_MAX_BYTES 256 |
SIM response length
Typedef Documentation
typedef void(* le_sim_DisconnectHandler_t) (void *) |
Type for handler called when a server disconnects.
typedef void(* le_sim_NewStateHandlerFunc_t) (le_sim_Id_t simId,le_sim_States_t simState,void *contextPtr) |
Handler for sim state changes.
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.
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_Command_t |
enum le_sim_Id_t |
enum le_sim_States_t |
enum le_sim_StkEvent_t |
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 *LE_NONNULL | oldpin, | ||
const char *LE_NONNULL | 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. Block until the service is available.
For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. 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 *LE_NONNULL | 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 | mccPtrSize, | ||
char * | mncPtr, | ||
size_t | mncPtrSize | ||
) |
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] mccPtrSize [out] mncPtr Mobile Network Code [in] mncPtrSize
le_result_t le_sim_GetHomeNetworkOperator | ( | le_sim_Id_t | simId, |
char * | nameStr, | ||
size_t | nameStrSize | ||
) |
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] nameStrSize
le_result_t le_sim_GetICCID | ( | le_sim_Id_t | simId, |
char * | iccid, | ||
size_t | iccidSize | ||
) |
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] iccidSize
le_result_t le_sim_GetIMSI | ( | le_sim_Id_t | simId, |
char * | imsi, | ||
size_t | imsiSize | ||
) |
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] imsiSize
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_BAD_PARAMETER Invalid SIM identifier.
- 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.
- Parameters
-
[in] simId The SIM identifier.
le_result_t le_sim_GetRemainingPUKTries | ( | le_sim_Id_t | simId, |
uint32_t * | remainingPukTriesPtrPtr | ||
) |
Get the number of remaining PUK insertion tries.
- Returns
- LE_OK On success.
- LE_NOT_FOUND The function failed to select the SIM card for this operation.
- LE_BAD_PARAMETER Invalid SIM identifier.
- LE_FAULT The function failed to get the number of remaining PUK insertion tries.
- Note
- If the caller is passing an null pointer to this function, it is a fatal error and the function will not return.
- Parameters
-
[in] simId The SIM identifier. [out] remainingPukTriesPtrPtr The number of remaining PUK insertion tries.
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 | phoneNumberStrSize | ||
) |
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] phoneNumberStrSize
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 or null ECS pointer is passed
- 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 *LE_NONNULL | 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 | handlerRef | ) |
Remove handler function for EVENT 'le_sim_NewState'
- Parameters
-
[in] handlerRef
void le_sim_RemoveSimToolkitEventHandler | ( | le_sim_SimToolkitEventHandlerRef_t | handlerRef | ) |
Remove handler function for EVENT 'le_sim_SimToolkitEvent'
- Parameters
-
[in] handlerRef
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_SendApdu | ( | le_sim_Id_t | simId, |
const uint8_t * | commandApduPtr, | ||
size_t | commandApduSize, | ||
uint8_t * | responseApduPtr, | ||
size_t * | responseApduSizePtr | ||
) |
Send APDU command to the SIM.
- Returns
- LE_OK Function succeeded.
- LE_FAULT The function failed.
- LE_BAD_PARAMETER A parameter is invalid.
- LE_NOT_FOUND The function failed to select the SIM card for this operation.
- Parameters
-
[in] simId The SIM identifier. [in] commandApduPtr APDU command. [in] commandApduSize [out] responseApduPtr SIM response. [in,out] responseApduSizePtr
le_result_t le_sim_SendCommand | ( | le_sim_Id_t | simId, |
le_sim_Command_t | command, | ||
const char *LE_NONNULL | fileIdentifier, | ||
uint8_t | p1, | ||
uint8_t | p2, | ||
uint8_t | p3, | ||
const uint8_t * | dataPtr, | ||
size_t | dataSize, | ||
const char *LE_NONNULL | path, | ||
uint8_t * | sw1Ptr, | ||
uint8_t * | sw2Ptr, | ||
uint8_t * | responsePtr, | ||
size_t * | responseSizePtr | ||
) |
Send a command to the SIM.
- Returns
- LE_OK Function succeeded.
- LE_FAULT The function failed.
- LE_BAD_PARAMETER A parameter is invalid.
- LE_NOT_FOUND - The function failed to select the SIM card for this operation
- The requested SIM file is not found
- LE_OVERFLOW Response buffer is too small to copy the SIM answer.
- LE_UNSUPPORTED The platform does not support this operation.
- Parameters
-
[in] simId The SIM identifier. [in] command The SIM command. [in] fileIdentifier File identifier [in] p1 Parameter P1 passed to the SIM [in] p2 Parameter P2 passed to the SIM [in] p3 Parameter P3 passed to the SIM [in] dataPtr data command. [in] dataSize [in] path path of the elementary file [out] sw1Ptr Status Word 1 received from the SIM [out] sw2Ptr Status Word 2 received from the SIM [out] responsePtr SIM response. [in,out] responseSizePtr
void le_sim_SetServerDisconnectHandler | ( | le_sim_DisconnectHandler_t | disconnectHandler, |
void * | contextPtr | ||
) |
Set handler called when server disconnection is detected.
When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants to continue without exiting, it should call longjmp() from inside the handler.
le_result_t le_sim_TryConnectService | ( | void | ) |
Try to connect the current client thread to the service providing this API. Return with an error if the service is not available.
For each thread that wants to use this API, either ConnectService or TryConnectService must be called before any other functions in this API. Normally, ConnectService is automatically called for the main thread, but not for any other thread. For details, see Client-specific Functions.
This function is created automatically.
- Returns
- LE_OK if the client connected successfully to the service.
- LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
- LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
- LE_COMM_ERROR if the Service Directory cannot be reached.
le_result_t le_sim_Unblock | ( | le_sim_Id_t | simId, |
const char *LE_NONNULL | puk, | ||
const char *LE_NONNULL | 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_BAD_PARAMETER Invalid SIM identifier.
- 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 *LE_NONNULL | 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.