le_sim_interface.h

Go to the documentation of this file.
    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_sim SIM
   14  *
   15  * @ref le_sim_interface.h "API Reference" <br>
   16  * @ref platformConstraintsSim "SIM constraints"
   17  *
   18  * <HR>
   19  *
   20  * This file contains prototype definitions for SIM API.
   21  *
   22  * A subscriber identity module or subscriber identification module (SIM) is an integrated circuit
   23  * that securely stores the international mobile subscriber identity (IMSI) and related key used
   24  * to identify and authenticate subscribers on M2M devices.
   25  *
   26  * Most SIM cards can store a number of SMS messages and phone book contacts.
   27  *
   28  * le_sim_GetSelectedCard() returns the selected SIM card number.
   29  *
   30  * @section le_sim_binding IPC interfaces binding
   31  *
   32  * All the functions of this API are provided by the @b modemService.
   33  *
   34  * Here's a code sample binding to modem services:
   35  * @verbatim
   36    bindings:
   37    {
   38       clientExe.clientComponent.le_sim -> modemService.le_sim
   39    }
   40    @endverbatim
   41  *
   42  *
   43  * @section le_sim_SelectCard Select a card to use
   44  * le_sim_SelectCard() function is used to select the SIM identifier. By default, the SIM in slot 1
   45  * is used.
   46  * Additionally, any Legato SIM API with a SIM card identifier passed in parameter, selects that
   47  * SIM identifier. le_sim_GetSelectedCard() returns the current selected card, not necessarily the
   48  * one set previously by le_sim_SelectCard().
   49  *
   50  * @note The SIM selection is not reset persistent; this function has to be called at each start-up.
   51  *
   52  * @note It is recommended to wait for a SIM handler notification after a new SIM selection before
   53  * calling le_sim API functions.
   54  *
   55  *
   56  * A sample code can be seen in the following page:
   57  * - @subpage c_simTestSelect
   58  *
   59  * @section le_sim_id SIM identification information
   60  * \b ICCID:
   61  * Each SIM is internationally identified by its integrated circuit card identifier (ICCID). ICCIDs
   62  * are stored in the SIM cards and engraved or printed on the SIM card body.
   63  * The ICCID is defined by the ITU-T recommendation E.118 as the
   64  * Primary Account Number. According to E.118, the number is up to 19 digits long, including a
   65  * single check digit calculated using the Luhn algorithm. However, the GSM Phase 1 (ETSI
   66  * Recommendation GSM 11.11) defined the ICCID length as 10 octets (20 digits) with
   67  * operator-specific structure.
   68  *
   69  * le_sim_GetICCID() API reads the identification number (ICCID).
   70  *
   71  * Using this API selects the requested SIM.
   72  *
   73  * \b IMSI:
   74  * The International Mobile Subscriber Identity or IMSI is a unique identification associated with
   75  * all cellular networks. The IMSI is used in any mobile network that connects with other
   76  * networks. For GSM, UMTS and LTE network, this number is provisioned in the SIM card.
   77  *
   78  * An IMSI is usually presented as a 15 digit long number, but can be shorter. The first 3 digits
   79  * are the mobile country code (MCC), are followed by the mobile network code (MNC), either 2
   80  * digits (European standard) or 3 digits (North American standard). The length of the MNC depends
   81  * on the value of the MCC. The remaining digits are the mobile subscription identification number
   82  * (MSIN) within the network's customer base.
   83  *
   84  * \b Home \b Network \b Name:
   85  * le_sim_GetHomeNetworkOperator() retrieves the Home Network Name.
   86  *
   87  * le_sim_GetIMSI() API reads the international mobile subscriber identity (IMSI).
   88  *
   89  * Using this API selects the requested SIM.
   90  *
   91  * \b Phone \b Number:
   92  * le_sim_GetSubscriberPhoneNumber() API reads the Phone Number associated to the SIM.
   93  * If the phone number has not been provisioned, it will return the empty string.
   94  *
   95  * Using this API selects the requested SIM.
   96  *
   97  * \b Home \b Network \b Information:
   98  * - le_sim_GetHomeNetworkOperator()function retrieves the Home Network Name.
   99  * - le_sim_GetHomeNetworkMccMnc()function retrieves the Home Network MCC (Mobile Country Code)
  100  *      and MNC (Mobile Network Code).
  101  *
  102  * A sample code can be seen in the following page:
  103  * - @subpage c_simTestIdentification
  104  *
  105  * @section le_sim_auth SIM Authentication
  106  * le_sim_EnterPIN() enters the PIN (Personal Identification Number) code that's
  107  * required before any Mobile equipment functionality can be used.
  108  *
  109  * Using this API selects the requested SIM.
  110  *
  111  * le_sim_GetRemainingPINTries() returns the number of remaining PIN entry attempts
  112  * before the SIM will become blocked.
  113  *
  114  * Using this API selects the requested SIM.
  115  *
  116  * le_sim_GetRemainingPUKTries() returns the number of remaining PUK entry attempts
  117  * before the SIM will become blocked.
  118  *
  119  * Using this API selects the requested SIM.
  120  *
  121  * le_sim_ChangePIN() must be called to change the PIN code.
  122  *
  123  * Using this API selects the requested SIM.
  124  *
  125  *  le_sim_Lock() locks the SIM card: it enables requests for the PIN code.
  126  *
  127  * Using this API selects the requested SIM.
  128  *
  129  *  le_sim_Unlock() unlocks the SIM card: it disables requests for the PIN code.
  130  *
  131  * Using this API selects the requested SIM.
  132  *
  133  * le_sim_Unblock() unblocks the SIM card. The SIM card is blocked after X unsuccessful
  134  * attempts to enter the PIN. le_sim_Unblock() requires the PUK (Personal Unblocking) code
  135  * to set a new PIN code.
  136  *
  137  * A sample code can be seen in the following page:
  138  * - @subpage c_simTestAuthentication
  139  *
  140  * @section le_sim_state SIM states
  141  * le_sim_IsPresent() API advises the SIM is inserted (and locked) or removed.
  142  *
  143  * Using this API selects the requested SIM.
  144  *
  145  * le_sim_IsReady() API advises the SIM is ready (PIN code correctly entered
  146  * or not required).
  147  *
  148  * Using this API selects the requested SIM.
  149  *
  150  * The le_sim_GetState() API retrieves the SIM state:
  151  * - LE_SIM_INSERTED      : SIM card is inserted and locked.
  152  * - LE_SIM_ABSENT        : SIM card is absent.
  153  * - LE_SIM_READY         : SIM card is inserted and unlocked.
  154  * - LE_SIM_BLOCKED       : SIM card is blocked.
  155  * - LE_SIM_BUSY          : SIM card is busy.
  156  * - LE_SIM_STATE_UNKNOWN : Unknown SIM state.
  157  *
  158  * Using this API selects the requested SIM.
  159  *
  160  * A handler function must be registered to receive SIM's state notifications.
  161  * le_sim_AddNewStateHandler() API allows the User to register that handler.
  162  *
  163  * The handler must satisfy the following prototype:
  164  * typedef void(*le_sim_NewStateHandlerFunc_t)(@ref le_sim_Id_t simId, @c le_sim_States_t simState);
  165  *
  166  * When a new SIM's state is notified, the handler is called.
  167  *
  168  * Call le_sim_GetState() to retrieve the new state of the SIM.
  169  *
  170  * @note If two (or more) applications have registered a handler function for notifications, they
  171  * will all receive it and will be passed the same SIM.
  172  *
  173  * The application can uninstall the handler function by calling le_sim_RemoveNewStateHandler() API.
  174  *
  175  * @warning Your platform might need a reboot to detect a SIM insertion or removal.
  176  * Please refer to the @ref platformConstraintsSim "SIM constraints" page or your platform
  177  * documentation for further details.
  178  *
  179  * A sample code can be seen in the following page:
  180  * - @subpage c_simTestStates
  181  *
  182  * @section le_sim_profile_switch Local SIM profile switch
  183  *
  184  * As soon as there are several subscriptions/profiles in the eUICC (multi-profile), and one of
  185  * them is dedicated to emergency calls (ex: eCall, ERA-Glonass), local swap is needed to swap as
  186  * quickly as possible to the emergency profile in case of need.
  187  *
  188  * “Local swap” means that the User's application must be able to directly request the eUICC to
  189  * swap to Emergency Call Subscription (ECS).
  190  *
  191  * Local swap puts the eUICC in a temporary state, meaning the commercial subscription is replaced
  192  * by emergency subscription for a limited time, event triggering the swap back to commercial
  193  * subscription being controlled by the User's application.
  194  *
  195  * The le_sim_LocalSwapToEmergencyCallSubscription() function requests the multi-profile eUICC to
  196  * swap to ECS and to refresh. The User's application must wait for eUICC reboot to be finished and
  197  * network connection available.
  198  *
  199  * The le_sim_LocalSwapToCommercialSubscription() function requests the multi-profile eUICC to swap
  200  * back to commercial subscription and to refresh. The User's application must wait for eUICC reboot
  201  * to be finished and network connection available.
  202  *
  203  * The User's application can install an handler with le_sim_AddNewStateHandler() to receive eUICC's
  204  * state notifications.
  205  *
  206  * @warning
  207  * - If you use a Morpho or Oberthur card, the SIM_REFRESH PRO-ACTIVE command must be accepted with
  208  *   le_sim_AcceptSimToolkitCommand() in order to complete the profile swap procedure.
  209  * - If you use a Giesecke & Devrient (G&D) card, be sure that your platform has disabled
  210  *   security restrictions for channel management APDU commands, otherwise local SIM profile switch
  211  *   could not work.
  212  *
  213  * The le_sim_IsEmergencyCallSubscriptionSelected() function must be called to get the current
  214  * subscription.
  215  *
  216  * @warning There is no standard method to interrogate the current selected subscription. The
  217  * returned value of this function is based on the last executed local swap command. This means
  218  * that this function will always return LE_NOT_FOUND error at Legato startup.
  219  *
  220  * A sample code can be seen in the following page:
  221  * - @subpage c_simTestProfileSwitch
  222  *
  223  * @section le_sim_Reset SIM Reset
  224  *
  225  * The le_sim_Reset() function resets the SIM card.
  226  *
  227  * @section le_sim_FPLMNList Read / Write FPLMN List from SIM
  228  *
  229  * The le_sim_CreateFPLMNList() function creates the empty FPLMN list.
  230  *
  231  * The le_sim_AddFPLMNOperator() function adds the FPLMN network into FPLMN list.
  232  *
  233  * The le_sim_WriteFPLMNList() function writes FPLMN list into the SIM.
  234  *
  235  * The le_sim_ReadFPLMNList() function reads the FPLMN list from the SIM card.
  236  *
  237  * The le_sim_GetFirstFPLMNOperator() function fetches the first FPLMN operator from FPLMN list.
  238  *
  239  * The le_sim_GetNextFPLMNOperator() function fetches the next FPLMN operator from FPLMN list.
  240  *
  241  * The le_sim_DeleteFPLMNList() function releases all allocated resources associated with the
  242  * List object.
  243  *
  244  * @section le_sim_stk SIM Toolkit
  245  *
  246  * The SIM application Toolkit allows the SIM card to initiates commands or asking input from the
  247  * modem to accept/reject SIM operations.  See @ref platformConstraintsStk Constraints.
  248  *
  249  * One of the use case is the remote provisioning of an embedded UICC (eUICC).
  250  *
  251  * The embedded UICC (eUICC) format supports multiple subscription profiles, which can be remotely
  252  * provisioned, updated or selected through SIM tool kit procedures (Bearer Independent Protocol
  253  * -BIP-, SIM refresh).
  254  *
  255  * It is mainly used for in-vehicle emergency call service (eCall).
  256  *
  257  * An eUICC can be remotely managed to change the Mobile Network Operator subscription.
  258  *
  259  * The le_sim_AddSimToolkitEventHandler() function registers a handler to be notified of SIM
  260  * Toolkit events.
  261  *
  262  * The le_sim_RemoveSimToolkitEventHandler() function unregisters the handler.
  263  *
  264  * The le_sim_AcceptSimToolkitCommand() allows the device to accept the last SIM Toolkit command.
  265  *
  266  * The le_sim_RejectSimToolkitCommand() forbids the device to accept the last SIM Toolkit command.
  267  *
  268  * A sample code can be seen in the following page:
  269  * - @subpage c_simTestSimToolkit
  270  *
  271  * Information related to SIM Toolkit platform constraints can be seen in the
  272  * @subpage platformConstraintsStk page.
  273  *
  274  * @section le_sim_access SIM access
  275  *
  276  * The application can send an APDU (Application Protocol Data Unit) to the SIM using
  277  * le_sim_SendApdu() API. The user must encode the APDU as specified by in recommendation 3GPP
  278  * 11.11, 3GPP 51.011, 3GPP 31.102, 3GPP 31.103 or ETSI TS 102 221.
  279  * @note Between two successive call to le_sim_SendApdu() API, there is no locking
  280  * protection. In this situation, some command types and parameters can modify SIM files
  281  * incorrectly.
  282  *
  283  * Using le_sim_SendCommand(), the application has easier but more limited access to the
  284  * SIM database. The command is transmitted to the SIM, which gives information through swi1 and
  285  * swi2 about the execution of the command (see 3GPP recommendation previously mentioned for
  286  * their coding).
  287  * Some parameters are platform dependent, see @subpage platformConstraintsSim "SIM constraints" for
  288  * their coding.
  289  *
  290  * A sample code can be seen in the following page:
  291  * - @subpage c_simTestApdu
  292  *
  293  * <HR>
  294  *
  295  * Copyright (C) Sierra Wireless Inc.
  296  */
  297 /**
  298  * @file le_sim_interface.h
  299  *
  300  * Legato @ref c_sim include file.
  301  *
  302  * Copyright (C) Sierra Wireless Inc.
  303  */
  304 /**
  305  * @page c_simTestProfileSwitch Sample code for Local SIM profile switch
  306  *
  307  * @include "apps/test/modemServices/sim/simProfileSwap/simTestComp/simTest.c"
  308  */
  309 /**
  310  * @page c_simTestSimToolkit Sample code for Local SIM Toolkit
  311  *
  312  * @include "apps/test/modemServices/sim/simToolkit/simToolkitComp/simToolkitTest.c"
  313  */
  314 /**
  315  * @page c_simTestAuthentication Sample code for SIM Authentication
  316  *
  317  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Define
  318  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/main.c" Print
  319  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Authentication
  320  */
  321 /**
  322  * @page c_simTestIdentification Sample code for SIM Identification
  323  *
  324  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/main.c" Print
  325  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Identification
  326  */
  327 /**
  328  * @page c_simTestSelect Sample code for SIM Select
  329  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Select
  330  */
  331 /**
  332  * @page c_simTestStates Sample code for SIM States
  333  *
  334  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/main.c" Print
  335  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Display
  336  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" State handler
  337  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" State
  338  */
  339 /**
  340  * @page c_simTestApdu Sample code for SIM access
  341  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Apdu
  342  */
  343 
  344 #ifndef LE_SIM_INTERFACE_H_INCLUDE_GUARD
  345 #define LE_SIM_INTERFACE_H_INCLUDE_GUARD
  346 
  347 
  348 #include "legato.h"
  349 
  350 // Interface specific includes
  351 #include "le_mdmDefs_interface.h"
  352 
  353 
  354 //--------------------------------------------------------------------------------------------------
  355 /**
  356  * Type for handler called when a server disconnects.
  357  */
  358 //--------------------------------------------------------------------------------------------------
  359 typedef void (*le_sim_DisconnectHandler_t)(void *);
  360 
  361 //--------------------------------------------------------------------------------------------------
  362 /**
  363  *
  364  * Connect the current client thread to the service providing this API. Block until the service is
  365  * available.
  366  *
  367  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  368  * called before any other functions in this API.  Normally, ConnectService is automatically called
  369  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  370  *
  371  * This function is created automatically.
  372  */
  373 //--------------------------------------------------------------------------------------------------
  374 void le_sim_ConnectService
  375 (
  376     void
  377 );
  378 
  379 //--------------------------------------------------------------------------------------------------
  380 /**
  381  *
  382  * Try to connect the current client thread to the service providing this API. Return with an error
  383  * if the service is not available.
  384  *
  385  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  386  * called before any other functions in this API.  Normally, ConnectService is automatically called
  387  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  388  *
  389  * This function is created automatically.
  390  *
  391  * @return
  392  *  - LE_OK if the client connected successfully to the service.
  393  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  394  *    bound.
  395  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  396  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  397  */
  398 //--------------------------------------------------------------------------------------------------
  399 le_result_t le_sim_TryConnectService
  400 (
  401     void
  402 );
  403 
  404 //--------------------------------------------------------------------------------------------------
  405 /**
  406  * Set handler called when server disconnection is detected.
  407  *
  408  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  409  * to continue without exiting, it should call longjmp() from inside the handler.
  410  */
  411 //--------------------------------------------------------------------------------------------------
  412 void le_sim_SetServerDisconnectHandler
  413 (
  414     le_sim_DisconnectHandler_t disconnectHandler,
  415     void *contextPtr
  416 );
  417 
  418 //--------------------------------------------------------------------------------------------------
  419 /**
  420  *
  421  * Disconnect the current client thread from the service providing this API.
  422  *
  423  * Normally, this function doesn't need to be called. After this function is called, there's no
  424  * longer a connection to the service, and the functions in this API can't be used. For details, see
  425  * @ref apiFilesC_client.
  426  *
  427  * This function is created automatically.
  428  */
  429 //--------------------------------------------------------------------------------------------------
  430 void le_sim_DisconnectService
  431 (
  432     void
  433 );
  434 
  435 
  436 //--------------------------------------------------------------------------------------------------
  437 /**
  438  * Minimum PIN length (4 digits)
  439  */
  440 //--------------------------------------------------------------------------------------------------
  441 #define LE_SIM_PIN_MIN_LEN 4
  442 
  443 //--------------------------------------------------------------------------------------------------
  444 /**
  445  * Maximum PIN length (8 digits)
  446  */
  447 //--------------------------------------------------------------------------------------------------
  448 #define LE_SIM_PIN_MAX_LEN 8
  449 
  450 //--------------------------------------------------------------------------------------------------
  451 /**
  452  * Maximum PIN length (8 digits)
  453  * One extra byte is added for the null character.
  454  */
  455 //--------------------------------------------------------------------------------------------------
  456 #define LE_SIM_PIN_MAX_BYTES 9
  457 
  458 //--------------------------------------------------------------------------------------------------
  459 /**
  460  * PUK length (8 digits)
  461  */
  462 //--------------------------------------------------------------------------------------------------
  463 #define LE_SIM_PUK_MAX_LEN 8
  464 
  465 //--------------------------------------------------------------------------------------------------
  466 /**
  467  * PUK length (8 digits)
  468  * One extra byte is added for the null character.
  469  */
  470 //--------------------------------------------------------------------------------------------------
  471 #define LE_SIM_PUK_MAX_BYTES 9
  472 
  473 //--------------------------------------------------------------------------------------------------
  474 /**
  475  * ICCID length
  476  * According to GSM Phase 1
  477  */
  478 //--------------------------------------------------------------------------------------------------
  479 #define LE_SIM_ICCID_LEN 20
  480 
  481 //--------------------------------------------------------------------------------------------------
  482 /**
  483  * ICCID length
  484  * One extra byte is added for the null character.
  485  */
  486 //--------------------------------------------------------------------------------------------------
  487 #define LE_SIM_ICCID_BYTES 21
  488 
  489 //--------------------------------------------------------------------------------------------------
  490 /**
  491  * IMSI length
  492  */
  493 //--------------------------------------------------------------------------------------------------
  494 #define LE_SIM_IMSI_LEN 15
  495 
  496 //--------------------------------------------------------------------------------------------------
  497 /**
  498  * IMSI length
  499  * One extra byte is added for the null character.
  500  */
  501 //--------------------------------------------------------------------------------------------------
  502 #define LE_SIM_IMSI_BYTES 16
  503 
  504 //--------------------------------------------------------------------------------------------------
  505 /**
  506  * APDU length
  507  */
  508 //--------------------------------------------------------------------------------------------------
  509 #define LE_SIM_APDU_MAX_BYTES 255
  510 
  511 //--------------------------------------------------------------------------------------------------
  512 /**
  513  * SIM response length
  514  */
  515 //--------------------------------------------------------------------------------------------------
  516 #define LE_SIM_RESPONSE_MAX_BYTES 256
  517 
  518 //--------------------------------------------------------------------------------------------------
  519 /**
  520  * SIM file identifier length
  521  */
  522 //--------------------------------------------------------------------------------------------------
  523 #define LE_SIM_FILE_ID_LEN 4
  524 
  525 //--------------------------------------------------------------------------------------------------
  526 /**
  527  * SIM file identifier length
  528  * One extra byte is added for the null character.
  529  */
  530 //--------------------------------------------------------------------------------------------------
  531 #define LE_SIM_FILE_ID_BYTES 5
  532 
  533 //--------------------------------------------------------------------------------------------------
  534 /**
  535  * SIM data command length
  536  *
  537  */
  538 //--------------------------------------------------------------------------------------------------
  539 #define LE_SIM_DATA_MAX_BYTES 100
  540 
  541 //--------------------------------------------------------------------------------------------------
  542 /**
  543  * SIM file path length
  544  */
  545 //--------------------------------------------------------------------------------------------------
  546 #define LE_SIM_PATH_MAX_LEN 100
  547 
  548 //--------------------------------------------------------------------------------------------------
  549 /**
  550  * SIM file path length
  551  * One extra byte is added for the null character.
  552  */
  553 //--------------------------------------------------------------------------------------------------
  554 #define LE_SIM_PATH_MAX_BYTES 101
  555 
  556 //--------------------------------------------------------------------------------------------------
  557 /**
  558  * Reference type for FPLMN list.
  559  */
  560 //--------------------------------------------------------------------------------------------------
  561 typedef struct le_sim_FPLMNList* le_sim_FPLMNListRef_t;
  562 
  563 
  564 //--------------------------------------------------------------------------------------------------
  565 /**
  566  * SIM states.
  567  *
  568  */
  569 //--------------------------------------------------------------------------------------------------
  570 typedef enum
  571 {
  572     LE_SIM_INSERTED = 0,
  573         ///< SIM card is inserted and locked.
  574     LE_SIM_ABSENT = 1,
  575         ///< SIM card is absent.
  576     LE_SIM_READY = 2,
  577         ///< SIM card is inserted and unlocked.
  578     LE_SIM_BLOCKED = 3,
  579         ///< SIM card is blocked.
  580     LE_SIM_BUSY = 4,
  581         ///< SIM card is busy.
  582     LE_SIM_STATE_UNKNOWN = 5
  583         ///< Unknown SIM state.
  584 }
  585 le_sim_States_t;
  586 
  587 
  588 //--------------------------------------------------------------------------------------------------
  589 /**
  590  * SIM identifiers.
  591  *
  592  */
  593 //--------------------------------------------------------------------------------------------------
  594 typedef enum
  595 {
  596     LE_SIM_EMBEDDED = 0,
  597         ///< Embedded SIM
  598     LE_SIM_EXTERNAL_SLOT_1 = 1,
  599         ///< SIM inserted in external slot 1
  600     LE_SIM_EXTERNAL_SLOT_2 = 2,
  601         ///< SIM inserted in external slot 2
  602     LE_SIM_REMOTE = 3,
  603         ///< Remote SIM
  604     LE_SIM_ID_MAX = 4
  605         ///<
  606 }
  607 le_sim_Id_t;
  608 
  609 
  610 //--------------------------------------------------------------------------------------------------
  611 /**
  612  * Card Manufacturer.
  613  *
  614  */
  615 //--------------------------------------------------------------------------------------------------
  616 typedef enum
  617 {
  618     LE_SIM_OBERTHUR = 0,
  619         ///< Oberthur.
  620     LE_SIM_GEMALTO = 1,
  621         ///< Gemalto.
  622     LE_SIM_G_AND_D = 2,
  623         ///< G&D.
  624     LE_SIM_MORPHO = 3,
  625         ///< Morpho.
  626     LE_SIM_VALID = 4,
  627         ///< Valid.
  628     LE_SIM_MANUFACTURER_MAX = 5
  629         ///<
  630 }
  631 le_sim_Manufacturer_t;
  632 
  633 
  634 //--------------------------------------------------------------------------------------------------
  635 /**
  636  * SIM commands.
  637  */
  638 //--------------------------------------------------------------------------------------------------
  639 typedef enum
  640 {
  641     LE_SIM_READ_RECORD = 0,
  642         ///< Read a file record.
  643     LE_SIM_READ_BINARY = 1,
  644         ///< Read a transparent elementary file.
  645     LE_SIM_UPDATE_RECORD = 2,
  646         ///< Update a file record.
  647     LE_SIM_UPDATE_BINARY = 3,
  648         ///< Update a transparent elementary file.
  649     LE_SIM_COMMAND_MAX = 4
  650         ///< Max value
  651 }
  652 le_sim_Command_t;
  653 
  654 
  655 //--------------------------------------------------------------------------------------------------
  656 /**
  657  * SIM Toolkit events.
  658  */
  659 //--------------------------------------------------------------------------------------------------
  660 typedef enum
  661 {
  662     LE_SIM_OPEN_CHANNEL = 0,
  663         ///< SIM card ask to open a logical channel.
  664     LE_SIM_REFRESH = 1,
  665         ///< SIM card ask for a refresh.
  666     LE_SIM_STK_EVENT_MAX = 2
  667         ///< Unknown SIM Toolkit event.
  668 }
  669 le_sim_StkEvent_t;
  670 
  671 
  672 //--------------------------------------------------------------------------------------------------
  673 /**
  674  * Reference type used by Add/Remove functions for EVENT 'le_sim_NewState'
  675  */
  676 //--------------------------------------------------------------------------------------------------
  677 typedef struct le_sim_NewStateHandler* le_sim_NewStateHandlerRef_t;
  678 
  679 
  680 //--------------------------------------------------------------------------------------------------
  681 /**
  682  * Reference type used by Add/Remove functions for EVENT 'le_sim_SimToolkitEvent'
  683  */
  684 //--------------------------------------------------------------------------------------------------
  685 typedef struct le_sim_SimToolkitEventHandler* le_sim_SimToolkitEventHandlerRef_t;
  686 
  687 
  688 //--------------------------------------------------------------------------------------------------
  689 /**
  690  * Handler for sim state changes.
  691  *
  692  */
  693 //--------------------------------------------------------------------------------------------------
  694 typedef void (*le_sim_NewStateHandlerFunc_t)
  695 (
  696     le_sim_Id_t simId,
  697         ///< The SIM identifier.
  698     le_sim_States_t simState,
  699         ///< The SIM state.
  700     void* contextPtr
  701         ///<
  702 );
  703 
  704 //--------------------------------------------------------------------------------------------------
  705 /**
  706  * Handler for Sim Toolkit Events.
  707  *
  708  */
  709 //--------------------------------------------------------------------------------------------------
  710 typedef void (*le_sim_SimToolkitEventHandlerFunc_t)
  711 (
  712     le_sim_Id_t simId,
  713         ///< The SIM identifier.
  714     le_sim_StkEvent_t stkEvent,
  715         ///< The SIM state.
  716     void* contextPtr
  717         ///<
  718 );
  719 
  720 //--------------------------------------------------------------------------------------------------
  721 /**
  722  * Add handler function for EVENT 'le_sim_NewState'
  723  *
  724  * This event provides information on sim state changes.
  725  *
  726  */
  727 //--------------------------------------------------------------------------------------------------
  728 le_sim_NewStateHandlerRef_t le_sim_AddNewStateHandler
  729 (
  730     le_sim_NewStateHandlerFunc_t handlerPtr,
  731         ///< [IN]
  732     void* contextPtr
  733         ///< [IN]
  734 );
  735 
  736 //--------------------------------------------------------------------------------------------------
  737 /**
  738  * Remove handler function for EVENT 'le_sim_NewState'
  739  */
  740 //--------------------------------------------------------------------------------------------------
  741 void le_sim_RemoveNewStateHandler
  742 (
  743     le_sim_NewStateHandlerRef_t handlerRef
  744         ///< [IN]
  745 );
  746 
  747 //--------------------------------------------------------------------------------------------------
  748 /**
  749  * Add handler function for EVENT 'le_sim_SimToolkitEvent'
  750  *
  751  * This event provides information on Sim Toolkit application.
  752  *
  753  */
  754 //--------------------------------------------------------------------------------------------------
  755 le_sim_SimToolkitEventHandlerRef_t le_sim_AddSimToolkitEventHandler
  756 (
  757     le_sim_SimToolkitEventHandlerFunc_t handlerPtr,
  758         ///< [IN]
  759     void* contextPtr
  760         ///< [IN]
  761 );
  762 
  763 //--------------------------------------------------------------------------------------------------
  764 /**
  765  * Remove handler function for EVENT 'le_sim_SimToolkitEvent'
  766  */
  767 //--------------------------------------------------------------------------------------------------
  768 void le_sim_RemoveSimToolkitEventHandler
  769 (
  770     le_sim_SimToolkitEventHandlerRef_t handlerRef
  771         ///< [IN]
  772 );
  773 
  774 //--------------------------------------------------------------------------------------------------
  775 /**
  776  * Get the current selected card.
  777  *
  778  * @return Number of the current selected SIM card.
  779  */
  780 //--------------------------------------------------------------------------------------------------
  781 le_sim_Id_t le_sim_GetSelectedCard
  782 (
  783     void
  784 );
  785 
  786 //--------------------------------------------------------------------------------------------------
  787 /**
  788  * Select a SIM.
  789  *
  790  * @return LE_FAULT         Function failed to select the requested SIM
  791  * @return LE_OK            Function succeeded.
  792  *
  793  */
  794 //--------------------------------------------------------------------------------------------------
  795 le_result_t le_sim_SelectCard
  796 (
  797     le_sim_Id_t simId
  798         ///< [IN] The SIM identifier.
  799 );
  800 
  801 //--------------------------------------------------------------------------------------------------
  802 /**
  803  * Retrieves the integrated circuit card identifier (ICCID) of the SIM card (20 digits)
  804  *
  805  * @return LE_OK             ICCID was successfully retrieved.
  806  * @return LE_OVERFLOW       iccidPtr buffer was too small for the ICCID.
  807  * @return LE_BAD_PARAMETER if a parameter is invalid
  808  * @return LE_FAULT         The ICCID could not be retrieved.
  809  *
  810  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  811  *       function will not return.
  812  */
  813 //--------------------------------------------------------------------------------------------------
  814 le_result_t le_sim_GetICCID
  815 (
  816     le_sim_Id_t simId,
  817         ///< [IN] The SIM identifier.
  818     char* iccid,
  819         ///< [OUT] ICCID
  820     size_t iccidSize
  821         ///< [IN]
  822 );
  823 
  824 //--------------------------------------------------------------------------------------------------
  825 /**
  826  * Retrieves the identification number (IMSI) of the SIM card. (max 15 digits)
  827  *
  828  * @return LE_OVERFLOW      The imsiPtr buffer was too small for the IMSI.
  829  * @return LE_BAD_PARAMETER The parameters are invalid.
  830  * @return LE_FAULT         The function failed.
  831  * @return LE_TIMEOUT       No response was received.
  832  * @return LE_OK            The function succeeded.
  833  *
  834  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  835  *       function will not return.
  836  */
  837 //--------------------------------------------------------------------------------------------------
  838 le_result_t le_sim_GetIMSI
  839 (
  840     le_sim_Id_t simId,
  841         ///< [IN] The SIM identifier.
  842     char* imsi,
  843         ///< [OUT] IMSI
  844     size_t imsiSize
  845         ///< [IN]
  846 );
  847 
  848 //--------------------------------------------------------------------------------------------------
  849 /**
  850  * Verify if the SIM card is present or not.
  851  *
  852  * @return true   SIM card is present.
  853  * @return false  SIM card is absent
  854  *
  855  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  856  *       function will not return.
  857  */
  858 //--------------------------------------------------------------------------------------------------
  859 bool le_sim_IsPresent
  860 (
  861     le_sim_Id_t simId
  862         ///< [IN] The SIM identifier.
  863 );
  864 
  865 //--------------------------------------------------------------------------------------------------
  866 /**
  867  * Verify if the SIM is ready (PIN code correctly inserted or not
  868  * required).
  869  *
  870  * @return true   PIN is correctly inserted or not required.
  871  * @return false  PIN must be inserted
  872  *
  873  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  874  *       function will not return.
  875  */
  876 //--------------------------------------------------------------------------------------------------
  877 bool le_sim_IsReady
  878 (
  879     le_sim_Id_t simId
  880         ///< [IN] The SIM identifier.
  881 );
  882 
  883 //--------------------------------------------------------------------------------------------------
  884 /**
  885  * This function must be called to enter the PIN code.
  886  *
  887  * @return LE_BAD_PARAMETER The parameters are invalid.
  888  * @return LE_NOT_FOUND     The function failed to select the SIM card for this operation.
  889  * @return LE_UNDERFLOW     The PIN code is not long enough (min 4 digits).
  890  * @return LE_FAULT         The function failed to enter the PIN code.
  891  * @return LE_OK            The function succeeded.
  892  *
  893  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
  894  *       function will not return.
  895  *
  896  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  897  *       function will not return.
  898  */
  899 //--------------------------------------------------------------------------------------------------
  900 le_result_t le_sim_EnterPIN
  901 (
  902     le_sim_Id_t simId,
  903         ///< [IN] The SIM identifier.
  904     const char* LE_NONNULL pin
  905         ///< [IN] The PIN code.
  906 );
  907 
  908 //--------------------------------------------------------------------------------------------------
  909 /**
  910  * Change the PIN code.
  911  *
  912  * @return LE_NOT_FOUND     Function failed to select the SIM card for this operation.
  913  * @return LE_UNDERFLOW     PIN code is/are not long enough (min 4 digits).
  914  * @return LE_FAULT         Function failed to change the PIN code.
  915  * @return LE_OK            Function succeeded.
  916  *
  917  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
  918  *       function will not return.
  919  *
  920  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  921  *       function will not return.
  922  */
  923 //--------------------------------------------------------------------------------------------------
  924 le_result_t le_sim_ChangePIN
  925 (
  926     le_sim_Id_t simId,
  927         ///< [IN] The SIM identifier.
  928     const char* LE_NONNULL oldpin,
  929         ///< [IN] The old PIN code.
  930     const char* LE_NONNULL newpin
  931         ///< [IN] The new PIN code.
  932 );
  933 
  934 //--------------------------------------------------------------------------------------------------
  935 /**
  936  * Get the number of remaining PIN insertion tries.
  937  *
  938  * @return LE_NOT_FOUND     The function failed to select the SIM card for this operation.
  939  * @return LE_BAD_PARAMETER Invalid SIM identifier.
  940  * @return LE_FAULT         The function failed to get the number of remaining PIN insertion tries.
  941  * @return A positive value The function succeeded. The number of remaining PIN insertion tries.
  942  *
  943  */
  944 //--------------------------------------------------------------------------------------------------
  945 int32_t le_sim_GetRemainingPINTries
  946 (
  947     le_sim_Id_t simId
  948         ///< [IN] The SIM identifier.
  949 );
  950 
  951 //--------------------------------------------------------------------------------------------------
  952 /**
  953  * Get the number of remaining PUK insertion tries.
  954  *
  955  * @return LE_OK            On success.
  956  * @return LE_NOT_FOUND     The function failed to select the SIM card for this operation.
  957  * @return LE_BAD_PARAMETER Invalid SIM identifier.
  958  * @return LE_FAULT         The function failed to get the number of remaining PUK insertion tries.
  959  *
  960  * @note If the caller is passing an null pointer to this function, it is a fatal error
  961  *       and the function will not return.
  962  *
  963  */
  964 //--------------------------------------------------------------------------------------------------
  965 le_result_t le_sim_GetRemainingPUKTries
  966 (
  967     le_sim_Id_t simId,
  968         ///< [IN] The SIM identifier.
  969     uint32_t* remainingPukTriesPtrPtr
  970         ///< [OUT] The number of remaining PUK insertion tries.
  971 );
  972 
  973 //--------------------------------------------------------------------------------------------------
  974 /**
  975  * Unlock the SIM card: it disables the request of the PIN code.
  976  *
  977  * @return LE_NOT_FOUND     Function failed to select the SIM card for this operation.
  978  * @return LE_UNDERFLOW     PIN code is not long enough (min 4 digits).
  979  * @return LE_FAULT         The function failed to unlock the SIM card.
  980  * @return LE_OK            Function succeeded.
  981  *
  982  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
  983  *       function will not return.
  984  *
  985  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
  986  *       function will not return.
  987  */
  988 //--------------------------------------------------------------------------------------------------
  989 le_result_t le_sim_Unlock
  990 (
  991     le_sim_Id_t simId,
  992         ///< [IN] The SIM identifier.
  993     const char* LE_NONNULL pin
  994         ///< [IN] The PIN code.
  995 );
  996 
  997 //--------------------------------------------------------------------------------------------------
  998 /**
  999  * Lock the SIM card: it enables the request of the PIN code.
 1000  *
 1001  * @return LE_NOT_FOUND     Function failed to select the SIM card for this operation.
 1002  * @return LE_UNDERFLOW     PIN code is not long enough (min 4 digits).
 1003  * @return LE_FAULT         The function failed to unlock the SIM card.
 1004  * @return LE_OK            Function succeeded.
 1005  *
 1006  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
 1007  *       function will not return.
 1008  *
 1009  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1010  *       function will not return.
 1011  */
 1012 //--------------------------------------------------------------------------------------------------
 1013 le_result_t le_sim_Lock
 1014 (
 1015     le_sim_Id_t simId,
 1016         ///< [IN] The SIM identifier.
 1017     const char* LE_NONNULL pin
 1018         ///< [IN] The PIN code.
 1019 );
 1020 
 1021 //--------------------------------------------------------------------------------------------------
 1022 /**
 1023  * Unblock the SIM card.
 1024  *
 1025  * @return LE_NOT_FOUND     Function failed to select the SIM card for this operation.
 1026  * @return LE_UNDERFLOW     PIN code is not long enough (min 4 digits).
 1027  * @return LE_BAD_PARAMETER Invalid SIM identifier.
 1028  * @return LE_OUT_OF_RANGE  PUK code length is not correct (8 digits).
 1029  * @return LE_FAULT         The function failed to unlock the SIM card.
 1030  * @return LE_OK            Function succeeded.
 1031  *
 1032  * @note If new PIN or puk code are too long (max 8 digits), it is a fatal error, the
 1033  *       function will not return.
 1034  *
 1035  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1036  *       function will not return.
 1037  */
 1038 //--------------------------------------------------------------------------------------------------
 1039 le_result_t le_sim_Unblock
 1040 (
 1041     le_sim_Id_t simId,
 1042         ///< [IN] The SIM identifier.
 1043     const char* LE_NONNULL puk,
 1044         ///< [IN] The PUK code.
 1045     const char* LE_NONNULL newpin
 1046         ///< [IN] The PIN code.
 1047 );
 1048 
 1049 //--------------------------------------------------------------------------------------------------
 1050 /**
 1051  * Get the SIM state.
 1052  *
 1053  * @return Current SIM state.
 1054  *
 1055  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1056  *       function will not return.
 1057  */
 1058 //--------------------------------------------------------------------------------------------------
 1059 le_sim_States_t le_sim_GetState
 1060 (
 1061     le_sim_Id_t simId
 1062         ///< [IN] The SIM identifier.
 1063 );
 1064 
 1065 //--------------------------------------------------------------------------------------------------
 1066 /**
 1067  * Get the SIM Phone Number.
 1068  *
 1069  * @return
 1070  *      - LE_OK on success
 1071  *      - LE_OVERFLOW if the Phone Number can't fit in phoneNumberStr
 1072  *      - LE_BAD_PARAMETER if a parameter is invalid
 1073  *      - LE_FAULT on any other failure
 1074  *
 1075  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1076  *       function will not return.
 1077  */
 1078 //--------------------------------------------------------------------------------------------------
 1079 le_result_t le_sim_GetSubscriberPhoneNumber
 1080 (
 1081     le_sim_Id_t simId,
 1082         ///< [IN] The SIM identifier.
 1083     char* phoneNumberStr,
 1084         ///< [OUT] The phone Number.
 1085     size_t phoneNumberStrSize
 1086         ///< [IN]
 1087 );
 1088 
 1089 //--------------------------------------------------------------------------------------------------
 1090 /**
 1091  * This function must be called to get the Home Network Name information.
 1092  *
 1093  * @return
 1094  *      - LE_OK on success
 1095  *      - LE_OVERFLOW if the Home Network Name can't fit in nameStr
 1096  *      - LE_NOT_FOUND if the network is not found
 1097  *      - LE_BAD_PARAMETER if a parameter is invalid
 1098  *      - LE_FAULT on any other failure
 1099  *
 1100  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1101  *       function will not return.
 1102  */
 1103 //--------------------------------------------------------------------------------------------------
 1104 le_result_t le_sim_GetHomeNetworkOperator
 1105 (
 1106     le_sim_Id_t simId,
 1107         ///< [IN] The SIM identifier.
 1108     char* nameStr,
 1109         ///< [OUT] the home network Name
 1110     size_t nameStrSize
 1111         ///< [IN]
 1112 );
 1113 
 1114 //--------------------------------------------------------------------------------------------------
 1115 /**
 1116  * This function must be called to get the Home Network MCC MNC.
 1117  *
 1118  * @return
 1119  *      - LE_OK on success
 1120  *      - LE_NOT_FOUND if Home Network has not been provisioned
 1121  *      - LE_FAULT for unexpected error
 1122  *
 1123  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1124  *       function will not return.
 1125  */
 1126 //--------------------------------------------------------------------------------------------------
 1127 le_result_t le_sim_GetHomeNetworkMccMnc
 1128 (
 1129     le_sim_Id_t simId,
 1130         ///< [IN] The SIM identifier.
 1131     char* mccPtr,
 1132         ///< [OUT] Mobile Country Code
 1133     size_t mccPtrSize,
 1134         ///< [IN]
 1135     char* mncPtr,
 1136         ///< [OUT] Mobile Network Code
 1137     size_t mncPtrSize
 1138         ///< [IN]
 1139 );
 1140 
 1141 //--------------------------------------------------------------------------------------------------
 1142 /**
 1143  * This function must be called to request the multi-profile eUICC to swap to ECS and to refresh.
 1144  * The User's application must wait for eUICC reboot to be finished and network connection
 1145  * available.
 1146  *
 1147  * @return
 1148  *      - LE_OK on success
 1149  *      - LE_BAD_PARAMETER invalid SIM identifier
 1150  *      - LE_BUSY when a profile swap is already in progress
 1151  *      - LE_FAULT for unexpected error
 1152  *
 1153  * @warning If you use a Morpho or Oberthur card, the SIM_REFRESH PRO-ACTIVE command must be
 1154  *          accepted with le_sim_AcceptSimToolkitCommand() in order to complete the profile swap
 1155  *          procedure.
 1156  */
 1157 //--------------------------------------------------------------------------------------------------
 1158 le_result_t le_sim_LocalSwapToEmergencyCallSubscription
 1159 (
 1160     le_sim_Id_t simId,
 1161         ///< [IN] The SIM identifier.
 1162     le_sim_Manufacturer_t manufacturer
 1163         ///< [IN] The card manufacturer.
 1164 );
 1165 
 1166 //--------------------------------------------------------------------------------------------------
 1167 /**
 1168  * This function must be called to request the multi-profile eUICC to swap back to commercial
 1169  * subscription and to refresh.
 1170  * The User's application must wait for eUICC reboot to be finished and network connection
 1171  * available.
 1172  *
 1173  * @return
 1174  *      - LE_OK on success
 1175  *      - LE_BAD_PARAMETER invalid SIM identifier
 1176  *      - LE_BUSY when a profile swap is already in progress
 1177  *      - LE_FAULT for unexpected error
 1178  *
 1179  * @warning If you use a Morpho or Oberthur card, the SIM_REFRESH PRO-ACTIVE command must be
 1180  *          accepted with le_sim_AcceptSimToolkitCommand() in order to complete the profile swap
 1181  *          procedure.
 1182  */
 1183 //--------------------------------------------------------------------------------------------------
 1184 le_result_t le_sim_LocalSwapToCommercialSubscription
 1185 (
 1186     le_sim_Id_t simId,
 1187         ///< [IN] The SIM identifier.
 1188     le_sim_Manufacturer_t manufacturer
 1189         ///< [IN] The card manufacturer.
 1190 );
 1191 
 1192 //--------------------------------------------------------------------------------------------------
 1193 /**
 1194  * This function must be called to get the current subscription.
 1195  *
 1196  * @return
 1197  *      - LE_OK on success
 1198  *      - LE_BAD_PARAMETER invalid SIM identifier or null ECS pointer is passed
 1199  *      - LE_NOT_FOUND cannot determine the current selected subscription
 1200  *      - LE_FAULT for unexpected errors
 1201  *
 1202  * @warning There is no standard method to interrogate the current selected subscription. The
 1203  * returned value of this function is based on the last executed local swap command. This means
 1204  * that this function will always return LE_NOT_FOUND error at Legato startup.
 1205  */
 1206 //--------------------------------------------------------------------------------------------------
 1207 le_result_t le_sim_IsEmergencyCallSubscriptionSelected
 1208 (
 1209     le_sim_Id_t simId,
 1210         ///< [IN] The SIM identifier
 1211     bool* isEcsPtr
 1212         ///< [OUT] true if Emergency Call Subscription (ECS) is selected,
 1213         ///<       false if Commercial Subscription is selected
 1214 );
 1215 
 1216 //--------------------------------------------------------------------------------------------------
 1217 /**
 1218  * Accept the last SIM Toolkit command.
 1219  *
 1220  * @return LE_FAULT    Function failed.
 1221  * @return LE_OK       Function succeeded.
 1222  */
 1223 //--------------------------------------------------------------------------------------------------
 1224 le_result_t le_sim_AcceptSimToolkitCommand
 1225 (
 1226     le_sim_Id_t simId
 1227         ///< [IN] The SIM identifier.
 1228 );
 1229 
 1230 //--------------------------------------------------------------------------------------------------
 1231 /**
 1232  * Reject the last SIM Toolkit command.
 1233  *
 1234  * @return LE_FAULT     Function failed.
 1235  * @return LE_OK        Function succeeded.
 1236  */
 1237 //--------------------------------------------------------------------------------------------------
 1238 le_result_t le_sim_RejectSimToolkitCommand
 1239 (
 1240     le_sim_Id_t simId
 1241         ///< [IN] The SIM identifier.
 1242 );
 1243 
 1244 //--------------------------------------------------------------------------------------------------
 1245 /**
 1246  * Send APDU command to the SIM.
 1247  *
 1248  * @return
 1249  *      - LE_OK             Function succeeded.
 1250  *      - LE_FAULT          The function failed.
 1251  *      - LE_BAD_PARAMETER  A parameter is invalid.
 1252  *      - LE_NOT_FOUND      The function failed to select the SIM card for this operation.
 1253  */
 1254 //--------------------------------------------------------------------------------------------------
 1255 le_result_t le_sim_SendApdu
 1256 (
 1257     le_sim_Id_t simId,
 1258         ///< [IN] The SIM identifier.
 1259     const uint8_t* commandApduPtr,
 1260         ///< [IN] APDU command.
 1261     size_t commandApduSize,
 1262         ///< [IN]
 1263     uint8_t* responseApduPtr,
 1264         ///< [OUT] SIM response.
 1265     size_t* responseApduSizePtr
 1266         ///< [INOUT]
 1267 );
 1268 
 1269 //--------------------------------------------------------------------------------------------------
 1270 /**
 1271  * Send a command to the SIM.
 1272  *
 1273  * @return
 1274  *      - LE_OK             Function succeeded.
 1275  *      - LE_FAULT          The function failed.
 1276  *      - LE_BAD_PARAMETER  A parameter is invalid.
 1277  *      - LE_NOT_FOUND      - The function failed to select the SIM card for this operation
 1278  *                          - The requested SIM file is not found
 1279  *      - LE_OVERFLOW       Response buffer is too small to copy the SIM answer.
 1280  *      - LE_UNSUPPORTED    The platform does not support this operation.
 1281  */
 1282 //--------------------------------------------------------------------------------------------------
 1283 le_result_t le_sim_SendCommand
 1284 (
 1285     le_sim_Id_t simId,
 1286         ///< [IN] The SIM identifier.
 1287     le_sim_Command_t command,
 1288         ///< [IN] The SIM command.
 1289     const char* LE_NONNULL fileIdentifier,
 1290         ///< [IN] File identifier
 1291     uint8_t p1,
 1292         ///< [IN] Parameter P1 passed to the SIM
 1293     uint8_t p2,
 1294         ///< [IN] Parameter P2 passed to the SIM
 1295     uint8_t p3,
 1296         ///< [IN] Parameter P3 passed to the SIM
 1297     const uint8_t* dataPtr,
 1298         ///< [IN] data command.
 1299     size_t dataSize,
 1300         ///< [IN]
 1301     const char* LE_NONNULL path,
 1302         ///< [IN] path of the elementary file
 1303     uint8_t* sw1Ptr,
 1304         ///< [OUT] Status Word 1 received from the SIM
 1305     uint8_t* sw2Ptr,
 1306         ///< [OUT] Status Word 2 received from the SIM
 1307     uint8_t* responsePtr,
 1308         ///< [OUT] SIM response.
 1309     size_t* responseSizePtr
 1310         ///< [INOUT]
 1311 );
 1312 
 1313 //--------------------------------------------------------------------------------------------------
 1314 /**
 1315  * Reset the SIM.
 1316  *
 1317  * @return
 1318  *      - LE_FAULT         Function failed.
 1319  *      - LE_OK            Function succeeded.
 1320  */
 1321 //--------------------------------------------------------------------------------------------------
 1322 le_result_t le_sim_Reset
 1323 (
 1324     le_sim_Id_t simId
 1325         ///< [IN] The SIM identifier.
 1326 );
 1327 
 1328 //--------------------------------------------------------------------------------------------------
 1329 /**
 1330  * Create empty FPLMN list.
 1331  *
 1332  * @return
 1333  *      - Reference to the List object.
 1334  *      - Null pointer if not able to create list.
 1335  */
 1336 //--------------------------------------------------------------------------------------------------
 1337 le_sim_FPLMNListRef_t le_sim_CreateFPLMNList
 1338 (
 1339     void
 1340 );
 1341 
 1342 //--------------------------------------------------------------------------------------------------
 1343 /**
 1344  * Add FPLMN network into the newly created FPLMN list.
 1345  *
 1346  * @return
 1347  *      - LE_FAULT         Function failed.
 1348  *      - LE_OK            Function succeeded.
 1349  */
 1350 //--------------------------------------------------------------------------------------------------
 1351 le_result_t le_sim_AddFPLMNOperator
 1352 (
 1353     le_sim_FPLMNListRef_t FPLMNListRef,
 1354         ///< [IN] FPLMN list reference.
 1355     const char* LE_NONNULL mcc,
 1356         ///< [IN] Mobile Country Code.
 1357     const char* LE_NONNULL mnc
 1358         ///< [IN] Mobile Network Code.
 1359 );
 1360 
 1361 //--------------------------------------------------------------------------------------------------
 1362 /**
 1363  * Write FPLMN list into the SIM.
 1364  *
 1365  * @return
 1366  *      - LE_FAULT         Function failed.
 1367  *      - LE_OK            Function succeeded.
 1368  *
 1369  */
 1370 //--------------------------------------------------------------------------------------------------
 1371 le_result_t le_sim_WriteFPLMNList
 1372 (
 1373     le_sim_Id_t simId,
 1374         ///< [IN] The SIM identifier.
 1375     le_sim_FPLMNListRef_t FPLMNListRef
 1376         ///< [IN] FPLMN list reference.
 1377 );
 1378 
 1379 //--------------------------------------------------------------------------------------------------
 1380 /**
 1381  * Read FPLMN list from the SIM.
 1382  *
 1383  * @return
 1384  *      - Reference to the List object.
 1385  *      - Null pointer if there is no FPLMN list entry.
 1386  */
 1387 //--------------------------------------------------------------------------------------------------
 1388 le_sim_FPLMNListRef_t le_sim_ReadFPLMNList
 1389 (
 1390     le_sim_Id_t simId
 1391         ///< [IN] The SIM identifier.
 1392 );
 1393 
 1394 //--------------------------------------------------------------------------------------------------
 1395 /**
 1396  * Read the first FPLMN network from the list of FPLMN objects
 1397  * retrieved with le_sim_ReadFPLMNList().
 1398  *
 1399  * @return
 1400  *      - LE_FAULT         Function failed.
 1401  *      - LE_OK            Function succeeded.
 1402  */
 1403 //--------------------------------------------------------------------------------------------------
 1404 le_result_t le_sim_GetFirstFPLMNOperator
 1405 (
 1406     le_sim_FPLMNListRef_t FPLMNListRef,
 1407         ///< [IN] FPLMN list reference.
 1408     char* mccPtr,
 1409         ///< [OUT] Mobile Country Code.
 1410     size_t mccPtrSize,
 1411         ///< [IN]
 1412     char* mncPtr,
 1413         ///< [OUT] Mobile Network Code.
 1414     size_t mncPtrSize
 1415         ///< [IN]
 1416 );
 1417 
 1418 //--------------------------------------------------------------------------------------------------
 1419 /**
 1420  * Read the next FPLMN network from the list of FPLMN objects
 1421  * retrieved with le_sim_ReadFPLMNList().
 1422  *
 1423  * @return
 1424  *      - LE_FAULT         Function failed.
 1425  *      - LE_OK            Function succeeded.
 1426  */
 1427 //--------------------------------------------------------------------------------------------------
 1428 le_result_t le_sim_GetNextFPLMNOperator
 1429 (
 1430     le_sim_FPLMNListRef_t FPLMNListRef,
 1431         ///< [IN] FPLMN list reference.
 1432     char* mccPtr,
 1433         ///< [OUT] Mobile Country Code.
 1434     size_t mccPtrSize,
 1435         ///< [IN]
 1436     char* mncPtr,
 1437         ///< [OUT] Mobile Network Code.
 1438     size_t mncPtrSize
 1439         ///< [IN]
 1440 );
 1441 
 1442 //--------------------------------------------------------------------------------------------------
 1443 /**
 1444  * Delete the FPLMN list created by le_sim_ReadFPLMNList() or le_sim_CreateFPLMNList().
 1445  *
 1446  * @note
 1447  *      On failure, the process exits, so you don't have to worry about checking the returned
 1448  *      reference for validity.
 1449  */
 1450 //--------------------------------------------------------------------------------------------------
 1451 void le_sim_DeleteFPLMNList
 1452 (
 1453     le_sim_FPLMNListRef_t FPLMNListRef
 1454         ///< [IN] FPLMN list reference.
 1455 );
 1456 
 1457 #endif // LE_SIM_INTERFACE_H_INCLUDE_GUARD
le_sim_AddNewStateHandler
le_sim_NewStateHandlerRef_t le_sim_AddNewStateHandler(le_sim_NewStateHandlerFunc_t handlerPtr, void *contextPtr)


LE_SIM_READ_BINARY
Read a transparent elementary file. 
Definition: le_sim_interface.h:643


le_sim_IsPresent
bool le_sim_IsPresent(le_sim_Id_t simId)


le_sim_GetHomeNetworkOperator
le_result_t le_sim_GetHomeNetworkOperator(le_sim_Id_t simId, char *nameStr, size_t nameStrSize)


le_sim_Id_t
le_sim_Id_t
Definition: le_sim_interface.h:594


le_sim_GetRemainingPUKTries
le_result_t le_sim_GetRemainingPUKTries(le_sim_Id_t simId, uint32_t *remainingPukTriesPtrPtr)


le_sim_SimToolkitEventHandlerFunc_t
void(* le_sim_SimToolkitEventHandlerFunc_t)(le_sim_Id_t simId, le_sim_StkEvent_t stkEvent, void *contextPtr)
Definition: le_sim_interface.h:711


le_result_t
le_result_t
Definition: le_basics.h:35


le_sim_LocalSwapToEmergencyCallSubscription
le_result_t le_sim_LocalSwapToEmergencyCallSubscription(le_sim_Id_t simId, le_sim_Manufacturer_t manufacturer)


le_sim_ChangePIN
le_result_t le_sim_ChangePIN(le_sim_Id_t simId, const char *LE_NONNULL oldpin, const char *LE_NONNULL newpin)


le_mdmDefs_interface.h


le_sim_SendApdu
le_result_t le_sim_SendApdu(le_sim_Id_t simId, const uint8_t *commandApduPtr, size_t commandApduSize, uint8_t *responseApduPtr, size_t *responseApduSizePtr)


LE_SIM_BUSY
SIM card is busy. 
Definition: le_sim_interface.h:580


le_sim_StkEvent_t
le_sim_StkEvent_t
Definition: le_sim_interface.h:660


le_sim_GetHomeNetworkMccMnc
le_result_t le_sim_GetHomeNetworkMccMnc(le_sim_Id_t simId, char *mccPtr, size_t mccPtrSize, char *mncPtr, size_t mncPtrSize)


LE_SIM_UPDATE_BINARY
Update a transparent elementary file. 
Definition: le_sim_interface.h:647


le_sim_GetFirstFPLMNOperator
le_result_t le_sim_GetFirstFPLMNOperator(le_sim_FPLMNListRef_t FPLMNListRef, char *mccPtr, size_t mccPtrSize, char *mncPtr, size_t mncPtrSize)


LE_SIM_EMBEDDED
Embedded SIM. 
Definition: le_sim_interface.h:596


LE_SIM_OBERTHUR
Oberthur. 
Definition: le_sim_interface.h:618


le_sim_States_t
le_sim_States_t
Definition: le_sim_interface.h:570


le_sim_SimToolkitEventHandlerRef_t
struct le_sim_SimToolkitEventHandler * le_sim_SimToolkitEventHandlerRef_t
Definition: le_sim_interface.h:685


LE_SIM_ABSENT
SIM card is absent. 
Definition: le_sim_interface.h:574


LE_SIM_INSERTED
SIM card is inserted and locked. 
Definition: le_sim_interface.h:572


LE_SIM_READ_RECORD
Read a file record. 
Definition: le_sim_interface.h:641


le_sim_NewStateHandlerFunc_t
void(* le_sim_NewStateHandlerFunc_t)(le_sim_Id_t simId, le_sim_States_t simState, void *contextPtr)
Definition: le_sim_interface.h:695


le_sim_GetICCID
le_result_t le_sim_GetICCID(le_sim_Id_t simId, char *iccid, size_t iccidSize)


le_sim_SetServerDisconnectHandler
void le_sim_SetServerDisconnectHandler(le_sim_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_sim_GetNextFPLMNOperator
le_result_t le_sim_GetNextFPLMNOperator(le_sim_FPLMNListRef_t FPLMNListRef, char *mccPtr, size_t mccPtrSize, char *mncPtr, size_t mncPtrSize)


le_sim_AcceptSimToolkitCommand
le_result_t le_sim_AcceptSimToolkitCommand(le_sim_Id_t simId)


le_sim_ReadFPLMNList
le_sim_FPLMNListRef_t le_sim_ReadFPLMNList(le_sim_Id_t simId)


LE_SIM_COMMAND_MAX
Max value. 
Definition: le_sim_interface.h:649


LE_SIM_STK_EVENT_MAX
Unknown SIM Toolkit event. 
Definition: le_sim_interface.h:666


le_sim_ConnectService
void le_sim_ConnectService(void)


LE_SIM_OPEN_CHANNEL
SIM card ask to open a logical channel. 
Definition: le_sim_interface.h:662


le_sim_GetIMSI
le_result_t le_sim_GetIMSI(le_sim_Id_t simId, char *imsi, size_t imsiSize)


LE_SIM_GEMALTO
Gemalto. 
Definition: le_sim_interface.h:620


LE_SIM_REFRESH
SIM card ask for a refresh. 
Definition: le_sim_interface.h:664


LE_SIM_EXTERNAL_SLOT_1
SIM inserted in external slot 1. 
Definition: le_sim_interface.h:598


le_sim_DisconnectService
void le_sim_DisconnectService(void)


le_sim_NewStateHandlerRef_t
struct le_sim_NewStateHandler * le_sim_NewStateHandlerRef_t
Definition: le_sim_interface.h:677


le_sim_DeleteFPLMNList
void le_sim_DeleteFPLMNList(le_sim_FPLMNListRef_t FPLMNListRef)


le_sim_Reset
le_result_t le_sim_Reset(le_sim_Id_t simId)


le_sim_SendCommand
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)


le_sim_WriteFPLMNList
le_result_t le_sim_WriteFPLMNList(le_sim_Id_t simId, le_sim_FPLMNListRef_t FPLMNListRef)



le_sim_AddFPLMNOperator
le_result_t le_sim_AddFPLMNOperator(le_sim_FPLMNListRef_t FPLMNListRef, const char *LE_NONNULL mcc, const char *LE_NONNULL mnc)


le_sim_SelectCard
le_result_t le_sim_SelectCard(le_sim_Id_t simId)


le_sim_Manufacturer_t
le_sim_Manufacturer_t
Definition: le_sim_interface.h:616


le_sim_DisconnectHandler_t
void(* le_sim_DisconnectHandler_t)(void *)
Definition: le_sim_interface.h:359


LE_SIM_REMOTE
Remote SIM. 
Definition: le_sim_interface.h:602


LE_SIM_VALID
Valid. 
Definition: le_sim_interface.h:626


le_sim_GetRemainingPINTries
int32_t le_sim_GetRemainingPINTries(le_sim_Id_t simId)


le_sim_CreateFPLMNList
le_sim_FPLMNListRef_t le_sim_CreateFPLMNList(void)


le_sim_IsReady
bool le_sim_IsReady(le_sim_Id_t simId)


le_sim_AddSimToolkitEventHandler
le_sim_SimToolkitEventHandlerRef_t le_sim_AddSimToolkitEventHandler(le_sim_SimToolkitEventHandlerFunc_t handlerPtr, void *contextPtr)


le_sim_RemoveSimToolkitEventHandler
void le_sim_RemoveSimToolkitEventHandler(le_sim_SimToolkitEventHandlerRef_t handlerRef)


le_sim_RemoveNewStateHandler
void le_sim_RemoveNewStateHandler(le_sim_NewStateHandlerRef_t handlerRef)


le_sim_RejectSimToolkitCommand
le_result_t le_sim_RejectSimToolkitCommand(le_sim_Id_t simId)


le_sim_FPLMNListRef_t
struct le_sim_FPLMNList * le_sim_FPLMNListRef_t
Definition: le_sim_interface.h:561


le_sim_GetSubscriberPhoneNumber
le_result_t le_sim_GetSubscriberPhoneNumber(le_sim_Id_t simId, char *phoneNumberStr, size_t phoneNumberStrSize)


LE_SIM_BLOCKED
SIM card is blocked. 
Definition: le_sim_interface.h:578


le_sim_Unblock
le_result_t le_sim_Unblock(le_sim_Id_t simId, const char *LE_NONNULL puk, const char *LE_NONNULL newpin)


le_sim_IsEmergencyCallSubscriptionSelected
le_result_t le_sim_IsEmergencyCallSubscriptionSelected(le_sim_Id_t simId, bool *isEcsPtr)


LE_SIM_G_AND_D
G&D. 
Definition: le_sim_interface.h:622


le_sim_Unlock
le_result_t le_sim_Unlock(le_sim_Id_t simId, const char *LE_NONNULL pin)


le_sim_Lock
le_result_t le_sim_Lock(le_sim_Id_t simId, const char *LE_NONNULL pin)


LE_SIM_MORPHO
Morpho. 
Definition: le_sim_interface.h:624


le_sim_Command_t
le_sim_Command_t
Definition: le_sim_interface.h:639


le_sim_GetSelectedCard
le_sim_Id_t le_sim_GetSelectedCard(void)


le_sim_EnterPIN
le_result_t le_sim_EnterPIN(le_sim_Id_t simId, const char *LE_NONNULL pin)


le_sim_GetState
le_sim_States_t le_sim_GetState(le_sim_Id_t simId)


le_sim_LocalSwapToCommercialSubscription
le_result_t le_sim_LocalSwapToCommercialSubscription(le_sim_Id_t simId, le_sim_Manufacturer_t manufacturer)


LE_SIM_EXTERNAL_SLOT_2
SIM inserted in external slot 2. 
Definition: le_sim_interface.h:600


le_sim_TryConnectService
le_result_t le_sim_TryConnectService(void)


LE_SIM_STATE_UNKNOWN
Unknown SIM state. 
Definition: le_sim_interface.h:582


LE_SIM_READY
SIM card is inserted and unlocked. 
Definition: le_sim_interface.h:576


LE_SIM_UPDATE_RECORD
Update a file record. 
Definition: le_sim_interface.h:645