le_sim_interface.h

    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 to
   24  * 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  * @section le_sim_binding IPC interfaces binding
   29  *
   30  * All the functions of this API are provided by the @b modemService.
   31  *
   32  * Here's a code sample binding to modem services:
   33  * @verbatim
   34    bindings:
   35    {
   36       clientExe.clientComponent.le_sim -> modemService.le_sim
   37    }
   38    @endverbatim
   39  *
   40  *
   41  * @section le_sim_SelectCard Select a card to use
   42  * le_sim_SelectCard() function is used to select the SIM identifier. By default, the SIM in slot 1
   43  * is used unless the automatic SIM selection is enabled. See @ref le_sim_AutomaticSelection for
   44  * further details.
   45  * Additionally, any Legato SIM API with a SIM card identifier passed in parameter, selects that
   46  * SIM identifier. le_sim_GetSelectedCard() returns the current selected card, not necessarily the
   47  * one set previously by le_sim_SelectCard().
   48  *
   49  * @note The SIM selection is not reset persistent; this function has to be called at each start-up.
   50  *
   51  * @note It is recommended to wait for a SIM handler notification after a new SIM selection before
   52  * calling le_sim API functions.
   53  *
   54  * A sample code can be seen in the following page:
   55  * - @subpage c_simTestSelect
   56  *
   57  * @section le_sim_AutomaticSelection Automatic SIM selection
   58  * This feature is only relevant for modules with an internal SIM card. When enabled, the module
   59  * automatically selects a SIM slot according to the rule: "If an external SIM is inserted in slot 1
   60  * then select it. Otherwise, fall back to the internal SIM card".
   61  *
   62  * Use the following APIs to manage the feature:
   63  * - le_sim_SetAutomaticSelection(): Enable/Disable the automatic SIM selection.
   64  * - le_sim_GetAutomaticSelection(): Get the current automatic SIM selection state.
   65  *
   66  * @note Most of le_sim APIs require a SIM identifier in their arguments. If a client application
   67  * uses a SIM identifier different from the one selected by automatic SIM selection, the feature
   68  * will be immediately disabled.
   69  * Thus, in order to use le_sim APIs in automatic SIM selection, client application must use
   70  * LE_SIM_UNSPECIFIED as a SIM identifier (@ref le_sim_Id_t).
   71  *
   72  *
   73  * @section le_sim_id SIM identification information
   74  * \b ICCID:
   75  * Each SIM is internationally identified by its integrated circuit card identifier (ICCID). ICCIDs
   76  * are stored in the SIM cards and engraved or printed on the SIM card body.
   77  * The ICCID is defined by the ITU-T recommendation E.118 as the
   78  * Primary Account Number. According to E.118, the number is up to 19 digits long, including a
   79  * single check digit calculated using the Luhn algorithm. However, the GSM Phase 1 (ETSI
   80  * Recommendation GSM 11.11) defined the ICCID length as 10 octets (20 digits) with
   81  * operator-specific structure.
   82  *
   83  * le_sim_GetICCID() API reads the identification number (ICCID).
   84  * le_sim_AddIccidChangeHandler() function registers a handler to be notified when ICCID changes.
   85  * le_sim_RemoveIccidChangeHandler() function unregisters the handler.
   86  *
   87  * @note During the initialization phase of the service, each new subscription to the ICCID change
   88  * event is notified by the last change event. This behavior lasts only for 5 seconds and allows
   89  * freshly registered clients to receive any ICCID changes that occured during the module start-up
   90  * phase.
   91  *
   92  * Using this API selects the requested SIM.
   93  *
   94  * \b IMSI:
   95  * The International Mobile Subscriber Identity or IMSI is a unique identification associated with
   96  * all cellular networks. The IMSI is used in any mobile network that connects with other
   97  * networks. For GSM, UMTS and LTE network, this number is provisioned in the SIM card.
   98  *
   99  * An IMSI is usually presented as a 15 digit long number, but can be shorter. The first 3 digits
  100  * are the mobile country code (MCC), are followed by the mobile network code (MNC), either 2
  101  * digits (European standard) or 3 digits (North American standard). The length of the MNC depends
  102  * on the value of the MCC. The remaining digits are the mobile subscription identification number
  103  * (MSIN) within the network's customer base.
  104  *
  105  * \b EID:
  106  * The EID (also called eUICCID) is the unique identifier for the embedded Universal Integrated
  107  * Circuit Card (eUICC).
  108  * A eUICC is a SIM card with a remote provisioning function, and is designed to not be removed or
  109  * changed. It is able to store multiple communication profiles but only one is enabled (recognized
  110  * by the device and used for communication). With conventional SIM cards, the ICCID is used as the
  111  * unique key to identify the SIM card, but with eUICC, the ICCID is the key used to identify a
  112  * profile, and a new identifier is defined, called the eUICCID (EID), which is used as the unique
  113  * key for the embedded SIM.
  114  * le_sim_GetEID() API reads the EID.
  115  *
  116  * \b Home \b Network \b Name:
  117  * le_sim_GetHomeNetworkOperator() retrieves the Home Network Name.
  118  *
  119  * le_sim_GetIMSI() API reads the international mobile subscriber identity (IMSI).
  120  *
  121  * Using this API selects the requested SIM.
  122  *
  123  * \b Phone \b Number:
  124  * le_sim_GetSubscriberPhoneNumber() API reads the Phone Number associated to the SIM.
  125  * If the phone number has not been provisioned, it will return the empty string.
  126  *
  127  * Using this API selects the requested SIM.
  128  *
  129  * \b Home \b Network \b Information:
  130  * - le_sim_GetHomeNetworkOperator()function retrieves the Home Network Name.
  131  * - le_sim_GetHomeNetworkMccMnc()function retrieves the Home Network MCC (Mobile Country Code)
  132  *      and MNC (Mobile Network Code).
  133  *
  134  * A sample code can be seen in the following page:
  135  * - @subpage c_simTestIdentification
  136  *
  137  * @section le_sim_auth SIM Authentication
  138  * le_sim_EnterPIN() enters the PIN (Personal Identification Number) code that's
  139  * required before any Mobile equipment functionality can be used.
  140  *
  141  * Using this API selects the requested SIM.
  142  *
  143  * le_sim_GetRemainingPINTries() returns the number of remaining PIN entry attempts
  144  * before the SIM will become blocked.
  145  *
  146  * Using this API selects the requested SIM.
  147  *
  148  * le_sim_GetRemainingPUKTries() returns the number of remaining PUK entry attempts
  149  * before the SIM will become blocked.
  150  *
  151  * Using this API selects the requested SIM.
  152  *
  153  * le_sim_ChangePIN() must be called to change the PIN code.
  154  *
  155  * Using this API selects the requested SIM.
  156  *
  157  *  le_sim_Lock() locks the SIM card: it enables requests for the PIN code.
  158  *
  159  * Using this API selects the requested SIM.
  160  *
  161  *  le_sim_Unlock() unlocks the SIM card: it disables requests for the PIN code.
  162  *
  163  * Using this API selects the requested SIM.
  164  *
  165  * le_sim_Unblock() unblocks the SIM card. The SIM card is blocked after X unsuccessful
  166  * attempts to enter the PIN. le_sim_Unblock() requires the PUK (Personal Unblocking) code
  167  * to set a new PIN code.
  168  *
  169  * A sample code can be seen in the following page:
  170  * - @subpage c_simTestAuthentication
  171  *
  172  * @section le_sim_state SIM states
  173  * le_sim_IsPresent() API advises the SIM is inserted (and locked) or removed.
  174  *
  175  * Using this API selects the requested SIM.
  176  *
  177  * le_sim_IsReady() API advises the SIM is ready (PIN code correctly entered
  178  * or not required).
  179  *
  180  * Using this API selects the requested SIM.
  181  *
  182  * The le_sim_GetState() API retrieves the SIM state:
  183  * - LE_SIM_INSERTED      : SIM card is inserted and locked.
  184  * - LE_SIM_ABSENT        : SIM card is absent.
  185  * - LE_SIM_READY         : SIM card is inserted and unlocked.
  186  * - LE_SIM_BLOCKED       : SIM card is blocked.
  187  * - LE_SIM_BUSY          : SIM card is busy.
  188  * - LE_SIM_POWER_DOWN    : SIM card is powered down.
  189  * - LE_SIM_STATE_UNKNOWN : Unknown SIM state.
  190  *
  191  * Using this API selects the requested SIM.
  192  *
  193  * A handler function must be registered to receive SIM's state notifications.
  194  * le_sim_AddNewStateHandler() API allows the User to register that handler.
  195  *
  196  * The handler must satisfy the following prototype:
  197  * typedef void(*le_sim_NewStateHandlerFunc_t)(@ref le_sim_Id_t simId, @c le_sim_States_t simState);
  198  *
  199  * When a new SIM's state is notified, the handler is called.
  200  *
  201  * Call le_sim_GetState() to retrieve the new state of the SIM.
  202  *
  203  * @note If two (or more) applications have registered a handler function for notifications, they
  204  * will all receive it and will be passed the same SIM.
  205  *
  206  * The application can uninstall the handler function by calling le_sim_RemoveNewStateHandler() API.
  207  *
  208  * @warning Your platform might need a reboot to detect a SIM insertion or removal.
  209  * Please refer to the @ref platformConstraintsSim "SIM constraints" page or your platform
  210  * documentation for further details.
  211  *
  212  * A sample code can be seen in the following page:
  213  * - @subpage c_simTestStates
  214  *
  215  * le_sim_SetPower() powers up or down the current SIM card.
  216  *
  217  * @section le_sim_profile_switch SIM profile switch
  218  *
  219  * As soon as there are several subscriptions/profiles in the eUICC (multi-profile), and one of
  220  * them is dedicated to emergency calls (ex: eCall, ERA-Glonass), local swap is needed to swap as
  221  * quickly as possible to the emergency profile in case of need.
  222  *
  223  * “Local swap” means that the User's application must be able to directly request the eUICC to
  224  * swap to Emergency Call Subscription (ECS).
  225  *
  226  * Local swap puts the eUICC in a temporary state, meaning the commercial subscription is replaced
  227  * by emergency subscription for a limited time, event triggering the swap back to commercial
  228  * subscription being controlled by the User's application.
  229  *
  230  * The le_sim_LocalSwapToEmergencyCallSubscription() function requests the multi-profile eUICC to
  231  * swap to ECS and to refresh. The User's application must wait for eUICC reboot to be finished and
  232  * network connection available.
  233  *
  234  * The le_sim_LocalSwapToCommercialSubscription() function requests the multi-profile eUICC to swap
  235  * back to commercial subscription and to refresh. The User's application must wait for eUICC reboot
  236  * to be finished and network connection available.
  237  *
  238  * eUICC allows support of multiple SIM profiles. These profiles can also be managed remotely from
  239  * a Subscription Manager Server. Changing the SIM profile remotely may impact the customer
  240  * application especially if there is an ongoing data transmission. To prevent any data loss,
  241  * switching SIM profiles is subject to a user agreement. This way, the customer application will
  242  * be able to properly finalize its current procedure (emergency call for instance) before accepting
  243  * the SIM swap.
  244  *
  245  * The application can subscribe a handler using le_sim_AddProfileUpdateHandler() to monitor SIM
  246  * profile change requests. Thus, the application can choose to accept or reject the SIM profile
  247  * swap procedure using le_sim_AcceptSimToolkitCommand() or le_sim_RejectSimToolkitCommand().
  248  *
  249  * @warning
  250  * If there is no subscribed handler, the SIM service automatically accepts any SIM profile swap
  251  * request.
  252  *
  253  * The User's application can install a handler with le_sim_AddNewStateHandler() to receive eUICC's
  254  * state notifications.
  255  *
  256  * @warning
  257  * - If you use a Morpho or Oberthur card, the SIM_REFRESH PRO-ACTIVE command must be accepted with
  258  *   le_sim_AcceptSimToolkitCommand() in order to complete the profile swap procedure.
  259  * - If you use a Giesecke & Devrient (G&D) card, be sure that your platform has disabled
  260  *   security restrictions for channel management APDU commands, otherwise local SIM profile switch
  261  *   could not work.
  262  *
  263  * The le_sim_IsEmergencyCallSubscriptionSelected() function must be called to get the current
  264  * subscription.
  265  *
  266  * @warning There is no standard method to interrogate the current selected subscription. The
  267  * returned value of this function is based on the last executed local swap command. This means
  268  * that this function will always return LE_NOT_FOUND error at Legato startup.
  269  *
  270  * A sample code can be seen in the following page:
  271  * - @subpage c_simTestProfileSwitch
  272  *
  273  * @section le_sim_Reset SIM Reset
  274  *
  275  * The le_sim_Reset() function resets the SIM card.
  276  *
  277  * @section le_sim_FPLMNList Read / Write FPLMN List from SIM
  278  *
  279  * The le_sim_CreateFPLMNList() function creates the empty FPLMN list.
  280  *
  281  * The le_sim_AddFPLMNOperator() function adds the FPLMN network into FPLMN list.
  282  *
  283  * The le_sim_WriteFPLMNList() function writes FPLMN list into the SIM.
  284  *
  285  * The le_sim_ReadFPLMNList() function reads the FPLMN list from the SIM card.
  286  *
  287  * The le_sim_GetFirstFPLMNOperator() function fetches the first FPLMN operator from FPLMN list.
  288  *
  289  * The le_sim_GetNextFPLMNOperator() function fetches the next FPLMN operator from FPLMN list.
  290  *
  291  * The le_sim_DeleteFPLMNList() function releases all allocated resources associated with the
  292  * List object.
  293  *
  294  * @note Some platforms do not support FPLMN APIs. Please refer to the @ref platformConstraintsSim
  295  * "SIM constraints" page or your platform documentation for further details.
  296  *
  297  * @section le_sim_stk SIM Toolkit
  298  *
  299  * The SIM application Toolkit allows the SIM card to initiate commands or asking input from the
  300  * modem to accept/reject SIM operations.
  301  *
  302  * One of the use case is the remote provisioning of an embedded UICC (eUICC): the eUICC format
  303  * supports multiple subscription profiles, which can be remotely provisioned, updated or selected
  304  * through SIM Toolkit procedures (Bearer Independent Protocol @em BIP, SIM refresh).
  305  *
  306  * It is mainly used for in-vehicle emergency call service (eCall).
  307  *
  308  * An eUICC can be remotely managed to change the Mobile Network Operator subscription.
  309  *
  310  * The le_sim_AddSimToolkitEventHandler() API registers a handler to be notified of SIM
  311  * Toolkit events. The le_sim_RemoveSimToolkitEventHandler() API unregisters the handler.
  312  *
  313  * The last received SIM Toolkit command can:
  314  * - Either be accepted by the device with the le_sim_AcceptSimToolkitCommand() API
  315  * - Or be rejected by the device with the le_sim_RejectSimToolkitCommand() API.
  316  * Note that if no handler is registered, refresh requests are automatically accepted.
  317  *
  318  * In case the last SIM Toolkit command is a Refresh command (@ref LE_SIM_REFRESH), additional
  319  * information can be retrieved:
  320  * - The le_sim_GetSimToolkitRefreshStage() API gets the stage of the Refresh command.
  321  * - The le_sim_GetSimToolkitRefreshMode() API gets the mode of the Refresh command, as defined in
  322  *   ETSI TS 102 223 sections 6.4.7 and 8.6.
  323  *
  324  * A sample code using the SIM Toolkit APIs can be seen in the following page:
  325  * - @subpage c_simTestSimToolkit
  326  *
  327  * Information related to SIM Toolkit platform constraints can be found in the
  328  * @ref platformConstraintsStk "SIM Toolkit platform constraints" page.
  329  *
  330  * @section le_sim_access SIM access
  331  *
  332  * The SIM card content can be accessed and/or modified by several methods.
  333  *
  334  * @subsection le_sim_accessApdu APDU
  335  *
  336  * The application can send an APDU (Application Protocol Data Unit) to the SIM using
  337  * le_sim_SendApdu() API. The user must encode the APDU as specified by in recommendation 3GPP
  338  * 11.11, 3GPP 51.011, 3GPP 31.102, 3GPP 31.103 or ETSI TS 102 221.
  339  * @note Between two successive calls to le_sim_SendApdu() API, there is no locking
  340  * protection. In this situation, some command types and parameters can modify SIM files
  341  * incorrectly.
  342  *
  343  * @subsection le_sim_accessCommand Commands
  344  *
  345  * Using le_sim_SendCommand(), the application has easier but more limited access to the
  346  * SIM database. The command is transmitted to the SIM, which gives information through swi1 and
  347  * swi2 about the execution of the command (see 3GPP recommendation previously mentioned for
  348  * their coding).
  349  * Some parameters are platform dependent, see @subpage platformConstraintsSim "SIM constraints" for
  350  * their coding.
  351  *
  352  * @subsection le_sim_accessLogicalChannel Logical channels
  353  *
  354  * Logical channels are specified by the standard ETSI TS 102 221 in the section 8.7. If they are
  355  * supported by the SIM card, logical channels allow to send independent APDUs on the different
  356  * channels. In this case:
  357  * - the basic channel 0 is always available and opened.
  358  * - upon request, the card assigns a number to open a new channel. This channel remains open until
  359  *   it is explicitly closed or the SIM card is deactivated.
  360  *
  361  * Use le_sim_OpenLogicalChannel() API to open a logical channel on the SIM card. APDUs can then
  362  * be sent to the SIM card with le_sim_SendApduOnChannel(). When the logical channel is not
  363  * needed anymore, it can be closed using le_sim_CloseLogicalChannel().
  364  *
  365  * @subsection le_sim_accessSampleCode Sample code
  366  *
  367  * A sample code can be seen in the following page:
  368  * - @subpage c_simTestApdu
  369  *
  370  * <HR>
  371  *
  372  * Copyright (C) Sierra Wireless Inc.
  373  */
  374 /**
  375  * @file le_sim_interface.h
  376  *
  377  * Legato @ref c_sim include file.
  378  *
  379  * Copyright (C) Sierra Wireless Inc.
  380  */
  381 /**
  382  * @page c_simTestProfileSwitch Sample code for Local SIM profile switch
  383  *
  384  * @include "apps/test/modemServices/sim/simProfileSwap/simTestComp/simTest.c"
  385  */
  386 /**
  387  * @page c_simTestSimToolkit Sample code for Local SIM Toolkit
  388  *
  389  * @include "apps/test/modemServices/sim/simToolkit/simToolkitComp/simToolkitTest.c"
  390  */
  391 /**
  392  * @page c_simTestAuthentication Sample code for SIM Authentication
  393  *
  394  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Define
  395  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/main.c" Print
  396  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Authentication
  397  */
  398 /**
  399  * @page c_simTestIdentification Sample code for SIM Identification
  400  *
  401  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/main.c" Print
  402  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Identification
  403  */
  404 /**
  405  * @page c_simTestSelect Sample code for SIM Select
  406  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Select
  407  */
  408 /**
  409  * @page c_simTestStates Sample code for SIM States
  410  *
  411  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/main.c" Print
  412  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Display
  413  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" State handler
  414  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" State
  415  */
  416 /**
  417  * @page c_simTestApdu Sample code for SIM access
  418  * @snippet "apps/test/modemServices/sim/simIntegrationTest/simTestComp/simTest.c" Apdu
  419  */
  420 
  421 #ifndef LE_SIM_INTERFACE_H_INCLUDE_GUARD
  422 #define LE_SIM_INTERFACE_H_INCLUDE_GUARD
  423 
  424 
  425 #include "legato.h"
  426 
  427 // Interface specific includes
  428 #include "le_mdmDefs_interface.h"
  429 
  430 
  431 //--------------------------------------------------------------------------------------------------
  432 /**
  433  * Type for handler called when a server disconnects.
  434  */
  435 //--------------------------------------------------------------------------------------------------
  436 typedef void (*le_sim_DisconnectHandler_t)(void *);
  437 
  438 //--------------------------------------------------------------------------------------------------
  439 /**
  440  *
  441  * Connect the current client thread to the service providing this API. Block until the service is
  442  * available.
  443  *
  444  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  445  * called before any other functions in this API.  Normally, ConnectService is automatically called
  446  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  447  *
  448  * This function is created automatically.
  449  */
  450 //--------------------------------------------------------------------------------------------------
  451 void le_sim_ConnectService
  452 (
  453     void
  454 );
  455 
  456 //--------------------------------------------------------------------------------------------------
  457 /**
  458  *
  459  * Try to connect the current client thread to the service providing this API. Return with an error
  460  * if the service is not available.
  461  *
  462  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  463  * called before any other functions in this API.  Normally, ConnectService is automatically called
  464  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  465  *
  466  * This function is created automatically.
  467  *
  468  * @return
  469  *  - LE_OK if the client connected successfully to the service.
  470  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  471  *    bound.
  472  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  473  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  474  */
  475 //--------------------------------------------------------------------------------------------------
  476 le_result_t le_sim_TryConnectService
  477 (
  478     void
  479 );
  480 
  481 //--------------------------------------------------------------------------------------------------
  482 /**
  483  * Set handler called when server disconnection is detected.
  484  *
  485  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  486  * to continue without exiting, it should call longjmp() from inside the handler.
  487  */
  488 //--------------------------------------------------------------------------------------------------
  489 void le_sim_SetServerDisconnectHandler
  490 (
  491     le_sim_DisconnectHandler_t disconnectHandler,
  492     void *contextPtr
  493 );
  494 
  495 //--------------------------------------------------------------------------------------------------
  496 /**
  497  *
  498  * Disconnect the current client thread from the service providing this API.
  499  *
  500  * Normally, this function doesn't need to be called. After this function is called, there's no
  501  * longer a connection to the service, and the functions in this API can't be used. For details, see
  502  * @ref apiFilesC_client.
  503  *
  504  * This function is created automatically.
  505  */
  506 //--------------------------------------------------------------------------------------------------
  507 void le_sim_DisconnectService
  508 (
  509     void
  510 );
  511 
  512 
  513 //--------------------------------------------------------------------------------------------------
  514 /**
  515  * Minimum PIN length (4 digits)
  516  */
  517 //--------------------------------------------------------------------------------------------------
  518 #define LE_SIM_PIN_MIN_LEN 4
  519 
  520 //--------------------------------------------------------------------------------------------------
  521 /**
  522  * Maximum PIN length (8 digits)
  523  */
  524 //--------------------------------------------------------------------------------------------------
  525 #define LE_SIM_PIN_MAX_LEN 8
  526 
  527 //--------------------------------------------------------------------------------------------------
  528 /**
  529  * Maximum PIN length (8 digits)
  530  * One extra byte is added for the null character.
  531  */
  532 //--------------------------------------------------------------------------------------------------
  533 #define LE_SIM_PIN_MAX_BYTES 9
  534 
  535 //--------------------------------------------------------------------------------------------------
  536 /**
  537  * PUK length (8 digits)
  538  */
  539 //--------------------------------------------------------------------------------------------------
  540 #define LE_SIM_PUK_MAX_LEN 8
  541 
  542 //--------------------------------------------------------------------------------------------------
  543 /**
  544  * PUK length (8 digits)
  545  * One extra byte is added for the null character.
  546  */
  547 //--------------------------------------------------------------------------------------------------
  548 #define LE_SIM_PUK_MAX_BYTES 9
  549 
  550 //--------------------------------------------------------------------------------------------------
  551 /**
  552  * ICCID length
  553  * According to GSM Phase 1
  554  */
  555 //--------------------------------------------------------------------------------------------------
  556 #define LE_SIM_ICCID_LEN 20
  557 
  558 //--------------------------------------------------------------------------------------------------
  559 /**
  560  * ICCID length
  561  * One extra byte is added for the null character.
  562  */
  563 //--------------------------------------------------------------------------------------------------
  564 #define LE_SIM_ICCID_BYTES 21
  565 
  566 //--------------------------------------------------------------------------------------------------
  567 /**
  568  * IMSI length
  569  */
  570 //--------------------------------------------------------------------------------------------------
  571 #define LE_SIM_IMSI_LEN 15
  572 
  573 //--------------------------------------------------------------------------------------------------
  574 /**
  575  * IMSI length
  576  * One extra byte is added for the null character.
  577  */
  578 //--------------------------------------------------------------------------------------------------
  579 #define LE_SIM_IMSI_BYTES 16
  580 
  581 //--------------------------------------------------------------------------------------------------
  582 /**
  583  * APDU length
  584  */
  585 //--------------------------------------------------------------------------------------------------
  586 #define LE_SIM_APDU_MAX_BYTES 255
  587 
  588 //--------------------------------------------------------------------------------------------------
  589 /**
  590  * SIM response length
  591  */
  592 //--------------------------------------------------------------------------------------------------
  593 #define LE_SIM_RESPONSE_MAX_BYTES 256
  594 
  595 //--------------------------------------------------------------------------------------------------
  596 /**
  597  * SIM file identifier length
  598  */
  599 //--------------------------------------------------------------------------------------------------
  600 #define LE_SIM_FILE_ID_LEN 4
  601 
  602 //--------------------------------------------------------------------------------------------------
  603 /**
  604  * SIM file identifier length
  605  * One extra byte is added for the null character.
  606  */
  607 //--------------------------------------------------------------------------------------------------
  608 #define LE_SIM_FILE_ID_BYTES 5
  609 
  610 //--------------------------------------------------------------------------------------------------
  611 /**
  612  * SIM data command length
  613  *
  614  */
  615 //--------------------------------------------------------------------------------------------------
  616 #define LE_SIM_DATA_MAX_BYTES 100
  617 
  618 //--------------------------------------------------------------------------------------------------
  619 /**
  620  * SIM file path length
  621  */
  622 //--------------------------------------------------------------------------------------------------
  623 #define LE_SIM_PATH_MAX_LEN 100
  624 
  625 //--------------------------------------------------------------------------------------------------
  626 /**
  627  * SIM file path length
  628  * One extra byte is added for the null character.
  629  */
  630 //--------------------------------------------------------------------------------------------------
  631 #define LE_SIM_PATH_MAX_BYTES 101
  632 
  633 //--------------------------------------------------------------------------------------------------
  634 /**
  635  * eUICC identifier (EID) length
  636  */
  637 //--------------------------------------------------------------------------------------------------
  638 #define LE_SIM_EID_LEN 32
  639 
  640 //--------------------------------------------------------------------------------------------------
  641 /**
  642  * eUICC identifier (EID) length
  643  * One extra byte is added for the null character.
  644  */
  645 //--------------------------------------------------------------------------------------------------
  646 #define LE_SIM_EID_BYTES 33
  647 
  648 //--------------------------------------------------------------------------------------------------
  649 /**
  650  * Reference type for FPLMN list.
  651  */
  652 //--------------------------------------------------------------------------------------------------
  653 typedef struct le_sim_FPLMNList* le_sim_FPLMNListRef_t;
  654 
  655 
  656 //--------------------------------------------------------------------------------------------------
  657 /**
  658  * SIM states.
  659  *
  660  */
  661 //--------------------------------------------------------------------------------------------------
  662 typedef enum
  663 {
  664     LE_SIM_INSERTED = 0,
  665         ///< SIM card is inserted and locked.
  666     LE_SIM_ABSENT = 1,
  667         ///< SIM card is absent.
  668     LE_SIM_READY = 2,
  669         ///< SIM card is inserted and unlocked.
  670     LE_SIM_BLOCKED = 3,
  671         ///< SIM card is blocked.
  672     LE_SIM_BUSY = 4,
  673         ///< SIM card is busy.
  674     LE_SIM_POWER_DOWN = 5,
  675         ///< SIM card is powered down.
  676     LE_SIM_STATE_UNKNOWN = 6
  677         ///< Unknown SIM state.
  678 }
  679 le_sim_States_t;
  680 
  681 
  682 //--------------------------------------------------------------------------------------------------
  683 /**
  684  * SIM identifiers.
  685  *
  686  */
  687 //--------------------------------------------------------------------------------------------------
  688 typedef enum
  689 {
  690     LE_SIM_EMBEDDED = 0,
  691         ///< Embedded SIM.
  692     LE_SIM_EXTERNAL_SLOT_1 = 1,
  693         ///< SIM inserted in external slot 1.
  694     LE_SIM_EXTERNAL_SLOT_2 = 2,
  695         ///< SIM inserted in external slot 2.
  696     LE_SIM_REMOTE = 3,
  697         ///< Remote SIM.
  698     LE_SIM_UNSPECIFIED = 4,
  699         ///< le_sim APIs are executed on the currently selected SIM. Use this
  700         ///< identifier when automatic SIM selection is enabled.
  701     LE_SIM_ID_MAX = 5
  702         ///<
  703 }
  704 le_sim_Id_t;
  705 
  706 
  707 //--------------------------------------------------------------------------------------------------
  708 /**
  709  * Card Manufacturer.
  710  *
  711  */
  712 //--------------------------------------------------------------------------------------------------
  713 typedef enum
  714 {
  715     LE_SIM_OBERTHUR = 0,
  716         ///< Oberthur.
  717     LE_SIM_GEMALTO = 1,
  718         ///< Gemalto.
  719     LE_SIM_G_AND_D = 2,
  720         ///< G&D.
  721     LE_SIM_MORPHO = 3,
  722         ///< Morpho.
  723     LE_SIM_VALID = 4,
  724         ///< Valid.
  725     LE_SIM_MANUFACTURER_MAX = 5
  726         ///<
  727 }
  728 le_sim_Manufacturer_t;
  729 
  730 
  731 //--------------------------------------------------------------------------------------------------
  732 /**
  733  * SIM commands.
  734  */
  735 //--------------------------------------------------------------------------------------------------
  736 typedef enum
  737 {
  738     LE_SIM_READ_RECORD = 0,
  739         ///< Read a file record.
  740     LE_SIM_READ_BINARY = 1,
  741         ///< Read a transparent elementary file.
  742     LE_SIM_UPDATE_RECORD = 2,
  743         ///< Update a file record.
  744     LE_SIM_UPDATE_BINARY = 3,
  745         ///< Update a transparent elementary file.
  746     LE_SIM_COMMAND_MAX = 4
  747         ///< Max value
  748 }
  749 le_sim_Command_t;
  750 
  751 
  752 //--------------------------------------------------------------------------------------------------
  753 /**
  754  * SIM Toolkit events.
  755  */
  756 //--------------------------------------------------------------------------------------------------
  757 typedef enum
  758 {
  759     LE_SIM_OPEN_CHANNEL = 0,
  760         ///< SIM card asks to open a logical channel.
  761     LE_SIM_REFRESH = 1,
  762         ///< SIM card asks for a refresh.
  763     LE_SIM_STK_EVENT_MAX = 2
  764         ///< Unknown SIM Toolkit event.
  765 }
  766 le_sim_StkEvent_t;
  767 
  768 
  769 //--------------------------------------------------------------------------------------------------
  770 /**
  771  * SIM Toolkit Refresh modes, defined in ETSI TS 102 223 sections 6.4.7 and 8.6.
  772  */
  773 //--------------------------------------------------------------------------------------------------
  774 typedef enum
  775 {
  776     LE_SIM_REFRESH_INIT_FULL_FCN = 0,
  777         ///< Initialization and Full File Change Notification.
  778     LE_SIM_REFRESH_FCN = 1,
  779         ///< File Change Notification.
  780     LE_SIM_REFRESH_INIT_FCN = 2,
  781         ///< Initialization and File Change Notification.
  782     LE_SIM_REFRESH_INIT = 3,
  783         ///< Initialization.
  784     LE_SIM_REFRESH_RESET = 4,
  785         ///< SIM reset.
  786     LE_SIM_REFRESH_APP_RESET = 5,
  787         ///< Application reset.
  788     LE_SIM_REFRESH_SESSION_RESET = 6,
  789         ///< Session reset.
  790     LE_SIM_REFRESH_STEERING_OF_ROAMING = 7,
  791         ///< Steering of Roaming as defined in 3GPP TS 23.122.
  792     LE_SIM_REFRESH_STEERING_OF_ROAMING_IWLAN = 8,
  793         ///< Steering of Roaming for I-WLAN
  794         ///< as defined in 3GPP TS 24.234.
  795     LE_SIM_REFRESH_EUICC_PROFILE_CHANGE = 9,
  796         ///< eUICC Profile State Change.
  797     LE_SIM_REFRESH_MODE_MAX = 10
  798         ///< Invalid SIM Toolkit Refresh mode.
  799 }
  800 le_sim_StkRefreshMode_t;
  801 
  802 
  803 //--------------------------------------------------------------------------------------------------
  804 /**
  805  * SIM Toolkit Refresh stages.
  806  */
  807 //--------------------------------------------------------------------------------------------------
  808 typedef enum
  809 {
  810     LE_SIM_STAGE_WAITING_FOR_OK = 0,
  811         ///< Waiting for OK to refresh.
  812     LE_SIM_STAGE_END_WITH_SUCCESS = 1,
  813         ///< Refresh succeeded.
  814     LE_SIM_STAGE_END_WITH_FAILURE = 2,
  815         ///< Refresh failed.
  816     LE_SIM_STAGE_MAX = 3
  817         ///< Invalid SIM Toolkit Refresh stage.
  818 }
  819 le_sim_StkRefreshStage_t;
  820 
  821 
  822 //--------------------------------------------------------------------------------------------------
  823 /**
  824  * Reference type used by Add/Remove functions for EVENT 'le_sim_NewState'
  825  */
  826 //--------------------------------------------------------------------------------------------------
  827 typedef struct le_sim_NewStateHandler* le_sim_NewStateHandlerRef_t;
  828 
  829 
  830 //--------------------------------------------------------------------------------------------------
  831 /**
  832  * Reference type used by Add/Remove functions for EVENT 'le_sim_ProfileUpdate'
  833  */
  834 //--------------------------------------------------------------------------------------------------
  835 typedef struct le_sim_ProfileUpdateHandler* le_sim_ProfileUpdateHandlerRef_t;
  836 
  837 
  838 //--------------------------------------------------------------------------------------------------
  839 /**
  840  * Reference type used by Add/Remove functions for EVENT 'le_sim_SimToolkitEvent'
  841  */
  842 //--------------------------------------------------------------------------------------------------
  843 typedef struct le_sim_SimToolkitEventHandler* le_sim_SimToolkitEventHandlerRef_t;
  844 
  845 
  846 //--------------------------------------------------------------------------------------------------
  847 /**
  848  * Reference type used by Add/Remove functions for EVENT 'le_sim_IccidChange'
  849  */
  850 //--------------------------------------------------------------------------------------------------
  851 typedef struct le_sim_IccidChangeHandler* le_sim_IccidChangeHandlerRef_t;
  852 
  853 
  854 //--------------------------------------------------------------------------------------------------
  855 /**
  856  * Handler for sim state changes.
  857  *
  858  */
  859 //--------------------------------------------------------------------------------------------------
  860 typedef void (*le_sim_NewStateHandlerFunc_t)
  861 (
  862     le_sim_Id_t simId,
  863         ///< The SIM identifier.
  864     le_sim_States_t simState,
  865         ///< The SIM state.
  866     void* contextPtr
  867         ///<
  868 );
  869 
  870 //--------------------------------------------------------------------------------------------------
  871 /**
  872  * Handler for profile update events.
  873  *
  874  */
  875 //--------------------------------------------------------------------------------------------------
  876 typedef void (*le_sim_ProfileUpdateHandlerFunc_t)
  877 (
  878     le_sim_Id_t simId,
  879         ///< The SIM identifier.
  880     le_sim_StkEvent_t stkEvent,
  881         ///< The SIM state.
  882     void* contextPtr
  883         ///<
  884 );
  885 
  886 //--------------------------------------------------------------------------------------------------
  887 /**
  888  * Handler for Sim Toolkit Events.
  889  *
  890  */
  891 //--------------------------------------------------------------------------------------------------
  892 typedef void (*le_sim_SimToolkitEventHandlerFunc_t)
  893 (
  894     le_sim_Id_t simId,
  895         ///< The SIM identifier.
  896     le_sim_StkEvent_t stkEvent,
  897         ///< The SIM state.
  898     void* contextPtr
  899         ///<
  900 );
  901 
  902 //--------------------------------------------------------------------------------------------------
  903 /**
  904  * Handler for ICCID change events.
  905  *
  906  */
  907 //--------------------------------------------------------------------------------------------------
  908 typedef void (*le_sim_IccidChangeHandlerFunc_t)
  909 (
  910     le_sim_Id_t simId,
  911         ///< The SIM identifier.
  912     const char* LE_NONNULL iccid,
  913         ///< ICCID
  914     void* contextPtr
  915         ///<
  916 );
  917 
  918 //--------------------------------------------------------------------------------------------------
  919 /**
  920  * Add handler function for EVENT 'le_sim_NewState'
  921  *
  922  * This event provides information on sim state changes.
  923  *
  924  */
  925 //--------------------------------------------------------------------------------------------------
  926 le_sim_NewStateHandlerRef_t le_sim_AddNewStateHandler
  927 (
  928     le_sim_NewStateHandlerFunc_t handlerPtr,
  929         ///< [IN]
  930     void* contextPtr
  931         ///< [IN]
  932 );
  933 
  934 //--------------------------------------------------------------------------------------------------
  935 /**
  936  * Remove handler function for EVENT 'le_sim_NewState'
  937  */
  938 //--------------------------------------------------------------------------------------------------
  939 void le_sim_RemoveNewStateHandler
  940 (
  941     le_sim_NewStateHandlerRef_t handlerRef
  942         ///< [IN]
  943 );
  944 
  945 //--------------------------------------------------------------------------------------------------
  946 /**
  947  * Add handler function for EVENT 'le_sim_ProfileUpdate'
  948  *
  949  * This event provides information on profile update
  950  *
  951  */
  952 //--------------------------------------------------------------------------------------------------
  953 le_sim_ProfileUpdateHandlerRef_t le_sim_AddProfileUpdateHandler
  954 (
  955     le_sim_ProfileUpdateHandlerFunc_t handlerPtr,
  956         ///< [IN]
  957     void* contextPtr
  958         ///< [IN]
  959 );
  960 
  961 //--------------------------------------------------------------------------------------------------
  962 /**
  963  * Remove handler function for EVENT 'le_sim_ProfileUpdate'
  964  */
  965 //--------------------------------------------------------------------------------------------------
  966 void le_sim_RemoveProfileUpdateHandler
  967 (
  968     le_sim_ProfileUpdateHandlerRef_t handlerRef
  969         ///< [IN]
  970 );
  971 
  972 //--------------------------------------------------------------------------------------------------
  973 /**
  974  * Add handler function for EVENT 'le_sim_SimToolkitEvent'
  975  *
  976  * This event provides information on Sim Toolkit application.
  977  *
  978  */
  979 //--------------------------------------------------------------------------------------------------
  980 le_sim_SimToolkitEventHandlerRef_t le_sim_AddSimToolkitEventHandler
  981 (
  982     le_sim_SimToolkitEventHandlerFunc_t handlerPtr,
  983         ///< [IN]
  984     void* contextPtr
  985         ///< [IN]
  986 );
  987 
  988 //--------------------------------------------------------------------------------------------------
  989 /**
  990  * Remove handler function for EVENT 'le_sim_SimToolkitEvent'
  991  */
  992 //--------------------------------------------------------------------------------------------------
  993 void le_sim_RemoveSimToolkitEventHandler
  994 (
  995     le_sim_SimToolkitEventHandlerRef_t handlerRef
  996         ///< [IN]
  997 );
  998 
  999 //--------------------------------------------------------------------------------------------------
 1000 /**
 1001  * Add handler function for EVENT 'le_sim_IccidChange'
 1002  *
 1003  * This event provides information on ICCID
 1004  *
 1005  */
 1006 //--------------------------------------------------------------------------------------------------
 1007 le_sim_IccidChangeHandlerRef_t le_sim_AddIccidChangeHandler
 1008 (
 1009     le_sim_IccidChangeHandlerFunc_t handlerPtr,
 1010         ///< [IN]
 1011     void* contextPtr
 1012         ///< [IN]
 1013 );
 1014 
 1015 //--------------------------------------------------------------------------------------------------
 1016 /**
 1017  * Remove handler function for EVENT 'le_sim_IccidChange'
 1018  */
 1019 //--------------------------------------------------------------------------------------------------
 1020 void le_sim_RemoveIccidChangeHandler
 1021 (
 1022     le_sim_IccidChangeHandlerRef_t handlerRef
 1023         ///< [IN]
 1024 );
 1025 
 1026 //--------------------------------------------------------------------------------------------------
 1027 /**
 1028  * Get the current selected card.
 1029  *
 1030  * @return Number of the current selected SIM card.
 1031  */
 1032 //--------------------------------------------------------------------------------------------------
 1033 le_sim_Id_t le_sim_GetSelectedCard
 1034 (
 1035     void
 1036 );
 1037 
 1038 //--------------------------------------------------------------------------------------------------
 1039 /**
 1040  * Select a SIM.
 1041  *
 1042  * @return LE_FAULT         Function failed to select the requested SIM
 1043  * @return LE_OK            Function succeeded.
 1044  *
 1045  */
 1046 //--------------------------------------------------------------------------------------------------
 1047 le_result_t le_sim_SelectCard
 1048 (
 1049     le_sim_Id_t simId
 1050         ///< [IN] The SIM identifier.
 1051 );
 1052 
 1053 //--------------------------------------------------------------------------------------------------
 1054 /**
 1055  * Retrieves the integrated circuit card identifier (ICCID) of the SIM card (20 digits)
 1056  *
 1057  * @return LE_OK             ICCID was successfully retrieved.
 1058  * @return LE_OVERFLOW       iccidPtr buffer was too small for the ICCID.
 1059  * @return LE_BAD_PARAMETER  Invalid parameters.
 1060  * @return LE_FAULT          The ICCID could not be retrieved.
 1061  *
 1062  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1063  *       function will not return.
 1064  */
 1065 //--------------------------------------------------------------------------------------------------
 1066 le_result_t le_sim_GetICCID
 1067 (
 1068     le_sim_Id_t simId,
 1069         ///< [IN] The SIM identifier.
 1070     char* iccid,
 1071         ///< [OUT] ICCID
 1072     size_t iccidSize
 1073         ///< [IN]
 1074 );
 1075 
 1076 //--------------------------------------------------------------------------------------------------
 1077 /**
 1078  * Retrieves the identifier for the embedded Universal Integrated Circuit Card identifier (EID)
 1079  * (32 digits)
 1080  *
 1081  * @return LE_OK             EID was successfully retrieved.
 1082  * @return LE_OVERFLOW       eidPtr buffer was too small for the EID.
 1083  * @return LE_BAD_PARAMETER  Invalid parameters.
 1084  * @return LE_FAULT          The EID could not be retrieved.
 1085  *
 1086  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1087  *       function will not return.
 1088  *
 1089  * @warning le_sim_GetEID() function is platform dependent. Please refer to the
 1090  *          @ref platformConstraintsSim_EID section for full details.
 1091  */
 1092 //--------------------------------------------------------------------------------------------------
 1093 le_result_t le_sim_GetEID
 1094 (
 1095     le_sim_Id_t simId,
 1096         ///< [IN] The SIM identifier.
 1097     char* eid,
 1098         ///< [OUT] EID
 1099     size_t eidSize
 1100         ///< [IN]
 1101 );
 1102 
 1103 //--------------------------------------------------------------------------------------------------
 1104 /**
 1105  * Retrieves the identification number (IMSI) of the SIM card. (max 15 digits)
 1106  *
 1107  * @return LE_OVERFLOW      The imsiPtr buffer was too small for the IMSI.
 1108  * @return LE_BAD_PARAMETER The parameters are invalid.
 1109  * @return LE_FAULT         The function failed.
 1110  * @return LE_TIMEOUT       No response was received.
 1111  * @return LE_OK            The function succeeded.
 1112  *
 1113  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1114  *       function will not return.
 1115  */
 1116 //--------------------------------------------------------------------------------------------------
 1117 le_result_t le_sim_GetIMSI
 1118 (
 1119     le_sim_Id_t simId,
 1120         ///< [IN] The SIM identifier.
 1121     char* imsi,
 1122         ///< [OUT] IMSI
 1123     size_t imsiSize
 1124         ///< [IN]
 1125 );
 1126 
 1127 //--------------------------------------------------------------------------------------------------
 1128 /**
 1129  * Verify if the SIM card is present or not.
 1130  *
 1131  * @return true   SIM card is present.
 1132  * @return false  SIM card is absent
 1133  *
 1134  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1135  *       function will not return.
 1136  */
 1137 //--------------------------------------------------------------------------------------------------
 1138 bool le_sim_IsPresent
 1139 (
 1140     le_sim_Id_t simId
 1141         ///< [IN] The SIM identifier.
 1142 );
 1143 
 1144 //--------------------------------------------------------------------------------------------------
 1145 /**
 1146  * Verify if the SIM is ready (PIN code correctly inserted or not
 1147  * required).
 1148  *
 1149  * @return true   PIN is correctly inserted or not required.
 1150  * @return false  PIN must be inserted
 1151  *
 1152  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1153  *       function will not return.
 1154  */
 1155 //--------------------------------------------------------------------------------------------------
 1156 bool le_sim_IsReady
 1157 (
 1158     le_sim_Id_t simId
 1159         ///< [IN] The SIM identifier.
 1160 );
 1161 
 1162 //--------------------------------------------------------------------------------------------------
 1163 /**
 1164  * This function must be called to enter the PIN code.
 1165  *
 1166  * @return LE_BAD_PARAMETER The parameters are invalid.
 1167  * @return LE_NOT_FOUND     The function failed to select the SIM card for this operation.
 1168  * @return LE_UNDERFLOW     The PIN code is not long enough (min 4 digits).
 1169  * @return LE_FAULT         The function failed to enter the PIN code.
 1170  * @return LE_OK            The function succeeded.
 1171  *
 1172  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
 1173  *       function will not return.
 1174  *
 1175  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1176  *       function will not return.
 1177  */
 1178 //--------------------------------------------------------------------------------------------------
 1179 le_result_t le_sim_EnterPIN
 1180 (
 1181     le_sim_Id_t simId,
 1182         ///< [IN] The SIM identifier.
 1183     const char* LE_NONNULL pin
 1184         ///< [IN] The PIN code.
 1185 );
 1186 
 1187 //--------------------------------------------------------------------------------------------------
 1188 /**
 1189  * Change the PIN code.
 1190  *
 1191  * @return LE_NOT_FOUND     Function failed to select the SIM card for this operation.
 1192  * @return LE_UNDERFLOW     PIN code is/are not long enough (min 4 digits).
 1193  * @return LE_FAULT         Function failed to change the PIN code.
 1194  * @return LE_OK            Function succeeded.
 1195  *
 1196  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
 1197  *       function will not return.
 1198  *
 1199  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1200  *       function will not return.
 1201  */
 1202 //--------------------------------------------------------------------------------------------------
 1203 le_result_t le_sim_ChangePIN
 1204 (
 1205     le_sim_Id_t simId,
 1206         ///< [IN] The SIM identifier.
 1207     const char* LE_NONNULL oldpin,
 1208         ///< [IN] The old PIN code.
 1209     const char* LE_NONNULL newpin
 1210         ///< [IN] The new PIN code.
 1211 );
 1212 
 1213 //--------------------------------------------------------------------------------------------------
 1214 /**
 1215  * Get the number of remaining PIN insertion tries.
 1216  *
 1217  * @return LE_NOT_FOUND     The function failed to select the SIM card for this operation.
 1218  * @return LE_BAD_PARAMETER Invalid SIM identifier.
 1219  * @return LE_FAULT         The function failed to get the number of remaining PIN insertion tries.
 1220  * @return A positive value The function succeeded. The number of remaining PIN insertion tries.
 1221  *
 1222  */
 1223 //--------------------------------------------------------------------------------------------------
 1224 int32_t le_sim_GetRemainingPINTries
 1225 (
 1226     le_sim_Id_t simId
 1227         ///< [IN] The SIM identifier.
 1228 );
 1229 
 1230 //--------------------------------------------------------------------------------------------------
 1231 /**
 1232  * Get the number of remaining PUK insertion tries.
 1233  *
 1234  * @return LE_OK            On success.
 1235  * @return LE_NOT_FOUND     The function failed to select the SIM card for this operation.
 1236  * @return LE_BAD_PARAMETER Invalid SIM identifier.
 1237  * @return LE_FAULT         The function failed to get the number of remaining PUK insertion tries.
 1238  *
 1239  * @note If the caller is passing an null pointer to this function, it is a fatal error
 1240  *       and the function will not return.
 1241  *
 1242  */
 1243 //--------------------------------------------------------------------------------------------------
 1244 le_result_t le_sim_GetRemainingPUKTries
 1245 (
 1246     le_sim_Id_t simId,
 1247         ///< [IN] The SIM identifier.
 1248     uint32_t* remainingPukTriesPtrPtr
 1249         ///< [OUT] The number of remaining PUK insertion tries.
 1250 );
 1251 
 1252 //--------------------------------------------------------------------------------------------------
 1253 /**
 1254  * Unlock the SIM card: it disables the request of the PIN code.
 1255  *
 1256  * @return LE_NOT_FOUND     Function failed to select the SIM card for this operation.
 1257  * @return LE_UNDERFLOW     PIN code is not long enough (min 4 digits).
 1258  * @return LE_FAULT         The function failed to unlock the SIM card.
 1259  * @return LE_OK            Function succeeded.
 1260  *
 1261  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
 1262  *       function will not return.
 1263  *
 1264  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1265  *       function will not return.
 1266  */
 1267 //--------------------------------------------------------------------------------------------------
 1268 le_result_t le_sim_Unlock
 1269 (
 1270     le_sim_Id_t simId,
 1271         ///< [IN] The SIM identifier.
 1272     const char* LE_NONNULL pin
 1273         ///< [IN] The PIN code.
 1274 );
 1275 
 1276 //--------------------------------------------------------------------------------------------------
 1277 /**
 1278  * Lock the SIM card: it enables the request of the PIN code.
 1279  *
 1280  * @return LE_NOT_FOUND     Function failed to select the SIM card for this operation.
 1281  * @return LE_UNDERFLOW     PIN code is not long enough (min 4 digits).
 1282  * @return LE_FAULT         The function failed to unlock the SIM card.
 1283  * @return LE_OK            Function succeeded.
 1284  *
 1285  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
 1286  *       function will not return.
 1287  *
 1288  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1289  *       function will not return.
 1290  */
 1291 //--------------------------------------------------------------------------------------------------
 1292 le_result_t le_sim_Lock
 1293 (
 1294     le_sim_Id_t simId,
 1295         ///< [IN] The SIM identifier.
 1296     const char* LE_NONNULL pin
 1297         ///< [IN] The PIN code.
 1298 );
 1299 
 1300 //--------------------------------------------------------------------------------------------------
 1301 /**
 1302  * Unblock the SIM card.
 1303  *
 1304  * @return LE_NOT_FOUND     Function failed to select the SIM card for this operation.
 1305  * @return LE_UNDERFLOW     PIN code is not long enough (min 4 digits).
 1306  * @return LE_BAD_PARAMETER Invalid SIM identifier.
 1307  * @return LE_OUT_OF_RANGE  PUK code length is not correct (8 digits).
 1308  * @return LE_FAULT         The function failed to unlock the SIM card.
 1309  * @return LE_OK            Function succeeded.
 1310  *
 1311  * @note If new PIN or puk code are too long (max 8 digits), it is a fatal error, the
 1312  *       function will not return.
 1313  *
 1314  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1315  *       function will not return.
 1316  */
 1317 //--------------------------------------------------------------------------------------------------
 1318 le_result_t le_sim_Unblock
 1319 (
 1320     le_sim_Id_t simId,
 1321         ///< [IN] The SIM identifier.
 1322     const char* LE_NONNULL puk,
 1323         ///< [IN] The PUK code.
 1324     const char* LE_NONNULL newpin
 1325         ///< [IN] The PIN code.
 1326 );
 1327 
 1328 //--------------------------------------------------------------------------------------------------
 1329 /**
 1330  * Get the SIM state.
 1331  *
 1332  * @return Current SIM state.
 1333  *
 1334  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1335  *       function will not return.
 1336  */
 1337 //--------------------------------------------------------------------------------------------------
 1338 le_sim_States_t le_sim_GetState
 1339 (
 1340     le_sim_Id_t simId
 1341         ///< [IN] The SIM identifier.
 1342 );
 1343 
 1344 //--------------------------------------------------------------------------------------------------
 1345 /**
 1346  * Get the SIM Phone Number.
 1347  *
 1348  * @return
 1349  *      - LE_OK on success
 1350  *      - LE_OVERFLOW if the Phone Number can't fit in phoneNumberStr
 1351  *      - LE_BAD_PARAMETER if a parameter is invalid
 1352  *      - LE_FAULT on any other failure
 1353  *
 1354  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1355  *       function will not return.
 1356  */
 1357 //--------------------------------------------------------------------------------------------------
 1358 le_result_t le_sim_GetSubscriberPhoneNumber
 1359 (
 1360     le_sim_Id_t simId,
 1361         ///< [IN] The SIM identifier.
 1362     char* phoneNumberStr,
 1363         ///< [OUT] The phone Number.
 1364     size_t phoneNumberStrSize
 1365         ///< [IN]
 1366 );
 1367 
 1368 //--------------------------------------------------------------------------------------------------
 1369 /**
 1370  * This function must be called to get the Home Network Name information.
 1371  *
 1372  * @return
 1373  *      - LE_OK on success
 1374  *      - LE_OVERFLOW if the Home Network Name can't fit in nameStr
 1375  *      - LE_BAD_PARAMETER if a parameter is invalid
 1376  *      - LE_FAULT on any other failure
 1377  *
 1378  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1379  *       function will not return.
 1380  *
 1381  * @note The home network name can be given even if the device is not registered on the network.
 1382  */
 1383 //--------------------------------------------------------------------------------------------------
 1384 le_result_t le_sim_GetHomeNetworkOperator
 1385 (
 1386     le_sim_Id_t simId,
 1387         ///< [IN] The SIM identifier.
 1388     char* nameStr,
 1389         ///< [OUT] the home network Name
 1390     size_t nameStrSize
 1391         ///< [IN]
 1392 );
 1393 
 1394 //--------------------------------------------------------------------------------------------------
 1395 /**
 1396  * This function must be called to get the Home Network MCC MNC.
 1397  *
 1398  * @return
 1399  *      - LE_OK on success
 1400  *      - LE_NOT_FOUND if Home Network has not been provisioned
 1401  *      - LE_FAULT for unexpected error
 1402  *
 1403  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
 1404  *       function will not return.
 1405  */
 1406 //--------------------------------------------------------------------------------------------------
 1407 le_result_t le_sim_GetHomeNetworkMccMnc
 1408 (
 1409     le_sim_Id_t simId,
 1410         ///< [IN] The SIM identifier.
 1411     char* mccPtr,
 1412         ///< [OUT] Mobile Country Code
 1413     size_t mccPtrSize,
 1414         ///< [IN]
 1415     char* mncPtr,
 1416         ///< [OUT] Mobile Network Code
 1417     size_t mncPtrSize
 1418         ///< [IN]
 1419 );
 1420 
 1421 //--------------------------------------------------------------------------------------------------
 1422 /**
 1423  * This function must be called to request the multi-profile eUICC to swap to ECS and to refresh.
 1424  * The User's application must wait for eUICC reboot to be finished and network connection
 1425  * available.
 1426  *
 1427  * @return
 1428  *      - LE_OK on success
 1429  *      - LE_BAD_PARAMETER invalid SIM identifier
 1430  *      - LE_BUSY when a profile swap is already in progress
 1431  *      - LE_FAULT for unexpected error
 1432  *      - LE_DUPLICATE for duplicate operation
 1433  *
 1434  * @note Please ensure that the eUICC is selected using le_sim_SelectCard() and in a ready state
 1435  *       before attempting a profile swap.
 1436  *
 1437  * @warning If you use a Morpho or Oberthur card, the SIM_REFRESH PRO-ACTIVE command must be
 1438  *          accepted with le_sim_AcceptSimToolkitCommand() in order to complete the profile swap
 1439  *          procedure.
 1440  */
 1441 //--------------------------------------------------------------------------------------------------
 1442 le_result_t le_sim_LocalSwapToEmergencyCallSubscription
 1443 (
 1444     le_sim_Id_t simId,
 1445         ///< [IN] The SIM identifier.
 1446     le_sim_Manufacturer_t manufacturer
 1447         ///< [IN] The card manufacturer.
 1448 );
 1449 
 1450 //--------------------------------------------------------------------------------------------------
 1451 /**
 1452  * This function must be called to request the multi-profile eUICC to swap back to commercial
 1453  * subscription and to refresh.
 1454  * The User's application must wait for eUICC reboot to be finished and network connection
 1455  * available.
 1456  *
 1457  * @return
 1458  *      - LE_OK on success
 1459  *      - LE_BAD_PARAMETER invalid SIM identifier
 1460  *      - LE_BUSY when a profile swap is already in progress
 1461  *      - LE_FAULT for unexpected error
 1462  *      - LE_DUPLICATE for duplicate operation
 1463  *
 1464  * @note Please ensure that the eUICC is selected using le_sim_SelectCard() and in a ready state
 1465  *       before attempting a profile swap.
 1466  *
 1467  * @warning If you use a Morpho or Oberthur card, the SIM_REFRESH PRO-ACTIVE command must be
 1468  *          accepted with le_sim_AcceptSimToolkitCommand() in order to complete the profile swap
 1469  *          procedure.
 1470  */
 1471 //--------------------------------------------------------------------------------------------------
 1472 le_result_t le_sim_LocalSwapToCommercialSubscription
 1473 (
 1474     le_sim_Id_t simId,
 1475         ///< [IN] The SIM identifier.
 1476     le_sim_Manufacturer_t manufacturer
 1477         ///< [IN] The card manufacturer.
 1478 );
 1479 
 1480 //--------------------------------------------------------------------------------------------------
 1481 /**
 1482  * This function must be called to get the current subscription.
 1483  *
 1484  * @return
 1485  *      - LE_OK on success
 1486  *      - LE_BAD_PARAMETER invalid SIM identifier or null ECS pointer is passed
 1487  *      - LE_NOT_FOUND cannot determine the current selected subscription
 1488  *      - LE_FAULT for unexpected errors
 1489  *
 1490  * @warning There is no standard method to interrogate the current selected subscription. The
 1491  * returned value of this function is based on the last executed local swap command. This means
 1492  * that this function will always return LE_NOT_FOUND error at Legato startup.
 1493  */
 1494 //--------------------------------------------------------------------------------------------------
 1495 le_result_t le_sim_IsEmergencyCallSubscriptionSelected
 1496 (
 1497     le_sim_Id_t simId,
 1498         ///< [IN] The SIM identifier
 1499     bool* isEcsPtr
 1500         ///< [OUT] true if Emergency Call Subscription (ECS) is selected,
 1501         ///<       false if Commercial Subscription is selected
 1502 );
 1503 
 1504 //--------------------------------------------------------------------------------------------------
 1505 /**
 1506  * Accept the last SIM Toolkit command.
 1507  *
 1508  * @return
 1509  *  - LE_OK       The function succeeded.
 1510  *  - LE_FAULT    The function failed.
 1511  */
 1512 //--------------------------------------------------------------------------------------------------
 1513 le_result_t le_sim_AcceptSimToolkitCommand
 1514 (
 1515     le_sim_Id_t simId
 1516         ///< [IN] The SIM identifier.
 1517 );
 1518 
 1519 //--------------------------------------------------------------------------------------------------
 1520 /**
 1521  * Reject the last SIM Toolkit command.
 1522  *
 1523  * @return
 1524  *  - LE_OK       The function succeeded.
 1525  *  - LE_FAULT    The function failed.
 1526  */
 1527 //--------------------------------------------------------------------------------------------------
 1528 le_result_t le_sim_RejectSimToolkitCommand
 1529 (
 1530     le_sim_Id_t simId
 1531         ///< [IN] The SIM identifier.
 1532 );
 1533 
 1534 //--------------------------------------------------------------------------------------------------
 1535 /**
 1536  * Retrieve the mode of the last SIM Toolkit Refresh command.
 1537  * The modes are defined in ETSI TS 102 223 sections 6.4.7 and 8.6.
 1538  *
 1539  * @return
 1540  *  - LE_OK             The function succeeded.
 1541  *  - LE_BAD_PARAMETER  A parameter is invalid.
 1542  *  - LE_UNAVAILABLE    The last SIM Toolkit command is not a Refresh command.
 1543  *  - LE_FAULT          The function failed.
 1544  *  - LE_UNSUPPORTED    The platform does not support this operation.
 1545  */
 1546 //--------------------------------------------------------------------------------------------------
 1547 le_result_t le_sim_GetSimToolkitRefreshMode
 1548 (
 1549     le_sim_Id_t simId,
 1550         ///< [IN] The SIM identifier.
 1551     le_sim_StkRefreshMode_t* refreshModePtr
 1552         ///< [OUT] The Refresh mode.
 1553 );
 1554 
 1555 //--------------------------------------------------------------------------------------------------
 1556 /**
 1557  * Retrieve the stage of the last SIM Toolkit Refresh command.
 1558  *
 1559  * @return
 1560  *  - LE_OK             The function succeeded.
 1561  *  - LE_BAD_PARAMETER  A parameter is invalid.
 1562  *  - LE_UNAVAILABLE    The last SIM Toolkit command is not a Refresh command.
 1563  *  - LE_FAULT          The function failed.
 1564  */
 1565 //--------------------------------------------------------------------------------------------------
 1566 le_result_t le_sim_GetSimToolkitRefreshStage
 1567 (
 1568     le_sim_Id_t simId,
 1569         ///< [IN] The SIM identifier.
 1570     le_sim_StkRefreshStage_t* refreshStagePtr
 1571         ///< [OUT] The Refresh stage.
 1572 );
 1573 
 1574 //--------------------------------------------------------------------------------------------------
 1575 /**
 1576  * Send APDU command to the SIM.
 1577  *
 1578  * @return
 1579  *      - LE_OK             Function succeeded.
 1580  *      - LE_FAULT          The function failed.
 1581  *      - LE_BAD_PARAMETER  A parameter is invalid.
 1582  *      - LE_NOT_FOUND      The function failed to select the SIM card for this operation.
 1583  */
 1584 //--------------------------------------------------------------------------------------------------
 1585 le_result_t le_sim_SendApdu
 1586 (
 1587     le_sim_Id_t simId,
 1588         ///< [IN] The SIM identifier.
 1589     const uint8_t* commandApduPtr,
 1590         ///< [IN] APDU command.
 1591     size_t commandApduSize,
 1592         ///< [IN]
 1593     uint8_t* responseApduPtr,
 1594         ///< [OUT] SIM response.
 1595     size_t* responseApduSizePtr
 1596         ///< [INOUT]
 1597 );
 1598 
 1599 //--------------------------------------------------------------------------------------------------
 1600 /**
 1601  * Send a command to the SIM.
 1602  *
 1603  * @return
 1604  *      - LE_OK             Function succeeded.
 1605  *      - LE_FAULT          The function failed.
 1606  *      - LE_BAD_PARAMETER  A parameter is invalid.
 1607  *      - LE_NOT_FOUND      - The function failed to select the SIM card for this operation
 1608  *                          - The requested SIM file is not found
 1609  *      - LE_OVERFLOW       Response buffer is too small to copy the SIM answer.
 1610  *      - LE_UNSUPPORTED    The platform does not support this operation.
 1611  */
 1612 //--------------------------------------------------------------------------------------------------
 1613 le_result_t le_sim_SendCommand
 1614 (
 1615     le_sim_Id_t simId,
 1616         ///< [IN] The SIM identifier.
 1617     le_sim_Command_t command,
 1618         ///< [IN] The SIM command.
 1619     const char* LE_NONNULL fileIdentifier,
 1620         ///< [IN] File identifier
 1621     uint8_t p1,
 1622         ///< [IN] Parameter P1 passed to the SIM
 1623     uint8_t p2,
 1624         ///< [IN] Parameter P2 passed to the SIM
 1625     uint8_t p3,
 1626         ///< [IN] Parameter P3 passed to the SIM
 1627     const uint8_t* dataPtr,
 1628         ///< [IN] data command.
 1629     size_t dataSize,
 1630         ///< [IN]
 1631     const char* LE_NONNULL path,
 1632         ///< [IN] path of the elementary file
 1633     uint8_t* sw1Ptr,
 1634         ///< [OUT] Status Word 1 received from the SIM
 1635     uint8_t* sw2Ptr,
 1636         ///< [OUT] Status Word 2 received from the SIM
 1637     uint8_t* responsePtr,
 1638         ///< [OUT] SIM response.
 1639     size_t* responseSizePtr
 1640         ///< [INOUT]
 1641 );
 1642 
 1643 //--------------------------------------------------------------------------------------------------
 1644 /**
 1645  * Enable or disable the automatic SIM selection
 1646  *
 1647  * @note Automatic SIM selection uses the following rule: If an external SIM is inserted in
 1648  *       slot 1 then select it. Otherwise, fall back to the internal SIM card.
 1649  *
 1650  * @return
 1651  *      - LE_OK            Function succeeded.
 1652  *      - LE_FAULT         Function failed to execute.
 1653  *
 1654  */
 1655 //--------------------------------------------------------------------------------------------------
 1656 le_result_t le_sim_SetAutomaticSelection
 1657 (
 1658     bool enable
 1659         ///< [IN] True if the feature needs to be enabled. False otherwise.
 1660 );
 1661 
 1662 //--------------------------------------------------------------------------------------------------
 1663 /**
 1664  * Get the automatic SIM selection
 1665  *
 1666  * @note When enabled, automatic SIM selection uses the following rule: If an external SIM is
 1667  *       inserted in slot 1 then select it. Otherwise, fall back to the internal SIM card.
 1668  *
 1669  * @return
 1670  *      - LE_OK             Function succeeded.
 1671  *      - LE_FAULT          Function failed to execute.
 1672  *      - LE_BAD_PARAMETER  Invalid parameter.
 1673  *      - LE_UNSUPPORTED    The platform does not support this operation.
 1674  *
 1675  */
 1676 //--------------------------------------------------------------------------------------------------
 1677 le_result_t le_sim_GetAutomaticSelection
 1678 (
 1679     bool* enablePtr
 1680         ///< [OUT] True if the feature is enabled. False otherwise.
 1681 );
 1682 
 1683 //--------------------------------------------------------------------------------------------------
 1684 /**
 1685  * Reset the SIM.
 1686  *
 1687  * @return
 1688  *      - LE_FAULT         Function failed.
 1689  *      - LE_OK            Function succeeded.
 1690  */
 1691 //--------------------------------------------------------------------------------------------------
 1692 le_result_t le_sim_Reset
 1693 (
 1694     le_sim_Id_t simId
 1695         ///< [IN] The SIM identifier.
 1696 );
 1697 
 1698 //--------------------------------------------------------------------------------------------------
 1699 /**
 1700  * Create empty FPLMN list to insert FPLMN operators.
 1701  *
 1702  * @return
 1703  *      - Reference to the List object.
 1704  *      - Null pointer if not able to create list reference.
 1705  */
 1706 //--------------------------------------------------------------------------------------------------
 1707 le_sim_FPLMNListRef_t le_sim_CreateFPLMNList
 1708 (
 1709     void
 1710 );
 1711 
 1712 //--------------------------------------------------------------------------------------------------
 1713 /**
 1714  * Add FPLMN network into the newly created FPLMN list.
 1715  * If the FPLMNListRef, mcc or mnc is not valid then this function will kill the calling client.
 1716  *
 1717  * @return
 1718  *      - LE_FAULT         Function failed.
 1719  *      - LE_OK            Function succeeded.
 1720  *      - LE_OVERFLOW      If FPLMN operator can not be inserted into FPLMN list.
 1721  */
 1722 //--------------------------------------------------------------------------------------------------
 1723 le_result_t le_sim_AddFPLMNOperator
 1724 (
 1725     le_sim_FPLMNListRef_t FPLMNListRef,
 1726         ///< [IN] FPLMN list reference.
 1727     const char* LE_NONNULL mcc,
 1728         ///< [IN] Mobile Country Code.
 1729     const char* LE_NONNULL mnc
 1730         ///< [IN] Mobile Network Code.
 1731 );
 1732 
 1733 //--------------------------------------------------------------------------------------------------
 1734 /**
 1735  * Write FPLMN list into the SIM.
 1736  * If the FPLMNListRef is not valid then this function will kill the calling client.
 1737  *
 1738  * @return
 1739  *      - LE_FAULT         Function failed.
 1740  *      - LE_OK            Function succeeded.
 1741  *
 1742  */
 1743 //--------------------------------------------------------------------------------------------------
 1744 le_result_t le_sim_WriteFPLMNList
 1745 (
 1746     le_sim_Id_t simId,
 1747         ///< [IN] The SIM identifier.
 1748     le_sim_FPLMNListRef_t FPLMNListRef
 1749         ///< [IN] FPLMN list reference.
 1750 );
 1751 
 1752 //--------------------------------------------------------------------------------------------------
 1753 /**
 1754  * Read FPLMN list from the SIM.
 1755  *
 1756  * @return
 1757  *      - Reference to the List object.
 1758  *      - Null pointer if FPLMN list is not able to read from the SIM.
 1759  */
 1760 //--------------------------------------------------------------------------------------------------
 1761 le_sim_FPLMNListRef_t le_sim_ReadFPLMNList
 1762 (
 1763     le_sim_Id_t simId
 1764         ///< [IN] The SIM identifier.
 1765 );
 1766 
 1767 //--------------------------------------------------------------------------------------------------
 1768 /**
 1769  * Read the first FPLMN network from the list of FPLMN objects retrieved with
 1770  * le_sim_ReadFPLMNList().
 1771  * If the FPLMNListRef, mccPtr or mncPtr is not valid then this function will kill the calling
 1772  * client.
 1773  *
 1774  * @return
 1775  *      - LE_FAULT         Function failed.
 1776  *      - LE_OK            Function succeeded.
 1777  *      - LE_OVERFLOW      MCC/MNC string size is greater than string length parameter which has
 1778  *                         been given into this function.
 1779  */
 1780 //--------------------------------------------------------------------------------------------------
 1781 le_result_t le_sim_GetFirstFPLMNOperator
 1782 (
 1783     le_sim_FPLMNListRef_t FPLMNListRef,
 1784         ///< [IN] FPLMN list reference.
 1785     char* mccPtr,
 1786         ///< [OUT] Mobile Country Code.
 1787     size_t mccPtrSize,
 1788         ///< [IN]
 1789     char* mncPtr,
 1790         ///< [OUT] Mobile Network Code.
 1791     size_t mncPtrSize
 1792         ///< [IN]
 1793 );
 1794 
 1795 //--------------------------------------------------------------------------------------------------
 1796 /**
 1797  * Read the next FPLMN network from the list of FPLMN objects retrieved with le_sim_ReadFPLMNList().
 1798  * If the FPLMNListRef, mccPtr or mncPtr is not valid then this function will kill the calling
 1799  * client.
 1800  *
 1801  * @return
 1802  *      - LE_FAULT         Function failed.
 1803  *      - LE_OK            Function succeeded.
 1804  *      - LE_OVERFLOW      MCC/MNC string size is greater than string length parameter which has
 1805  *                         been given into this function.
 1806  */
 1807 //--------------------------------------------------------------------------------------------------
 1808 le_result_t le_sim_GetNextFPLMNOperator
 1809 (
 1810     le_sim_FPLMNListRef_t FPLMNListRef,
 1811         ///< [IN] FPLMN list reference.
 1812     char* mccPtr,
 1813         ///< [OUT] Mobile Country Code.
 1814     size_t mccPtrSize,
 1815         ///< [IN]
 1816     char* mncPtr,
 1817         ///< [OUT] Mobile Network Code.
 1818     size_t mncPtrSize
 1819         ///< [IN]
 1820 );
 1821 
 1822 //--------------------------------------------------------------------------------------------------
 1823 /**
 1824  * Delete the FPLMN list created by le_sim_ReadFPLMNList() or le_sim_CreateFPLMNList().
 1825  * If the FPLMNListRef is not valid then this function will kill the calling client.
 1826  *
 1827  * @note
 1828  *      On failure, the process exits, so you don't have to worry about checking the returned
 1829  *      reference for validity.
 1830  */
 1831 //--------------------------------------------------------------------------------------------------
 1832 void le_sim_DeleteFPLMNList
 1833 (
 1834     le_sim_FPLMNListRef_t FPLMNListRef
 1835         ///< [IN] FPLMN list reference.
 1836 );
 1837 
 1838 //--------------------------------------------------------------------------------------------------
 1839 /**
 1840  * Open a logical channel on the SIM card.
 1841  *
 1842  * @return
 1843  *      - LE_OK            Function succeeded.
 1844  *      - LE_BAD_PARAMETER Invalid parameter.
 1845  *      - LE_FAULT         Function failed.
 1846  */
 1847 //--------------------------------------------------------------------------------------------------
 1848 le_result_t le_sim_OpenLogicalChannel
 1849 (
 1850     uint8_t* channelPtrPtr
 1851         ///< [OUT] The number of the opened logical channel.
 1852 );
 1853 
 1854 //--------------------------------------------------------------------------------------------------
 1855 /**
 1856  * Close a logical channel on the SIM card.
 1857  *
 1858  * @return
 1859  *      - LE_OK            Function succeeded.
 1860  *      - LE_FAULT         Function failed.
 1861  */
 1862 //--------------------------------------------------------------------------------------------------
 1863 le_result_t le_sim_CloseLogicalChannel
 1864 (
 1865     uint8_t channel
 1866         ///< [IN] The number of the logical channel to close.
 1867 );
 1868 
 1869 //--------------------------------------------------------------------------------------------------
 1870 /**
 1871  * Send APDU command on a dedicated logical channel.
 1872  *
 1873  * @return
 1874  *      - LE_OK             Function succeeded.
 1875  *      - LE_BAD_PARAMETER  A parameter is invalid.
 1876  *      - LE_NOT_FOUND      The function failed to select the SIM card for this operation.
 1877  *      - LE_FAULT          The function failed.
 1878  */
 1879 //--------------------------------------------------------------------------------------------------
 1880 le_result_t le_sim_SendApduOnChannel
 1881 (
 1882     le_sim_Id_t simId,
 1883         ///< [IN] The SIM identifier.
 1884     uint8_t channel,
 1885         ///< [IN] The logical channel number.
 1886     const uint8_t* commandApduPtr,
 1887         ///< [IN] APDU command.
 1888     size_t commandApduSize,
 1889         ///< [IN]
 1890     uint8_t* responseApduPtr,
 1891         ///< [OUT] SIM response.
 1892     size_t* responseApduSizePtr
 1893         ///< [INOUT]
 1894 );
 1895 
 1896 //--------------------------------------------------------------------------------------------------
 1897 /**
 1898  * Power up or down the current SIM.
 1899  *
 1900  * @return LE_OK        Function succeeded.
 1901  * @return LE_FAULT     Function failed.
 1902  *
 1903  * @note For SIM power cycle operation, it must wait until SIM state is LE_SIM_POWER_DOWN
 1904  *       before powering on the SIM, otherwise power up SIM will fail.
 1905  */
 1906 //--------------------------------------------------------------------------------------------------
 1907 le_result_t le_sim_SetPower
 1908 (
 1909     le_sim_Id_t simId,
 1910         ///< [IN] The SIM identifier.
 1911     le_onoff_t power
 1912         ///< [IN] The power state.
 1913 );
 1914 
 1915 #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:740
le_mdmDefs_interface.h
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:688
le_sim_GetRemainingPUKTries
le_result_t le_sim_GetRemainingPUKTries(le_sim_Id_t simId, uint32_t *remainingPukTriesPtrPtr)
LE_SIM_REFRESH_INIT_FULL_FCN
Initialization and Full File Change Notification. 
Definition: le_sim_interface.h:776
LE_SIM_REFRESH_MODE_MAX
Invalid SIM Toolkit Refresh mode. 
Definition: le_sim_interface.h:797
le_result_t
le_result_t
Definition: le_basics.h:35
LE_SIM_REFRESH_FCN
File Change Notification. 
Definition: le_sim_interface.h:778
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_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:672
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:893
le_sim_StkEvent_t
le_sim_StkEvent_t
Definition: le_sim_interface.h:757
LE_SIM_UNSPECIFIED
Definition: le_sim_interface.h:698
le_sim_RemoveProfileUpdateHandler
void le_sim_RemoveProfileUpdateHandler(le_sim_ProfileUpdateHandlerRef_t handlerRef)
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_IccidChangeHandlerRef_t
struct le_sim_IccidChangeHandler * le_sim_IccidChangeHandlerRef_t
Definition: le_sim_interface.h:851
LE_SIM_UPDATE_BINARY
Update a transparent elementary file. 
Definition: le_sim_interface.h:744
LE_SIM_STAGE_END_WITH_SUCCESS
Refresh succeeded. 
Definition: le_sim_interface.h:812
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_REFRESH_INIT
Initialization. 
Definition: le_sim_interface.h:782
le_sim_OpenLogicalChannel
le_result_t le_sim_OpenLogicalChannel(uint8_t *channelPtrPtr)
le_sim_GetSimToolkitRefreshMode
le_result_t le_sim_GetSimToolkitRefreshMode(le_sim_Id_t simId, le_sim_StkRefreshMode_t *refreshModePtr)
LE_SIM_EMBEDDED
Embedded SIM. 
Definition: le_sim_interface.h:690
le_sim_IccidChangeHandlerFunc_t
void(* le_sim_IccidChangeHandlerFunc_t)(le_sim_Id_t simId, const char *LE_NONNULL iccid, void *contextPtr)
Definition: le_sim_interface.h:909
LE_SIM_OBERTHUR
Oberthur. 
Definition: le_sim_interface.h:715
le_sim_States_t
le_sim_States_t
Definition: le_sim_interface.h:662
le_sim_AddProfileUpdateHandler
le_sim_ProfileUpdateHandlerRef_t le_sim_AddProfileUpdateHandler(le_sim_ProfileUpdateHandlerFunc_t handlerPtr, void *contextPtr)
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:861
le_sim_SimToolkitEventHandlerRef_t
struct le_sim_SimToolkitEventHandler * le_sim_SimToolkitEventHandlerRef_t
Definition: le_sim_interface.h:843
LE_SIM_REFRESH_STEERING_OF_ROAMING
Steering of Roaming as defined in 3GPP TS 23.122. 
Definition: le_sim_interface.h:790
LE_SIM_ABSENT
SIM card is absent. 
Definition: le_sim_interface.h:666
LE_SIM_INSERTED
SIM card is inserted and locked. 
Definition: le_sim_interface.h:664
LE_SIM_READ_RECORD
Read a file record. 
Definition: le_sim_interface.h:738
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_REFRESH_SESSION_RESET
Session reset. 
Definition: le_sim_interface.h:788
le_sim_SendApduOnChannel
le_result_t le_sim_SendApduOnChannel(le_sim_Id_t simId, uint8_t channel, const uint8_t *commandApduPtr, size_t commandApduSize, uint8_t *responseApduPtr, size_t *responseApduSizePtr)
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:746
LE_SIM_STAGE_WAITING_FOR_OK
Waiting for OK to refresh. 
Definition: le_sim_interface.h:810
LE_SIM_STK_EVENT_MAX
Unknown SIM Toolkit event. 
Definition: le_sim_interface.h:763
le_sim_ConnectService
void le_sim_ConnectService(void)
LE_SIM_STAGE_END_WITH_FAILURE
Refresh failed. 
Definition: le_sim_interface.h:814
LE_SIM_OPEN_CHANNEL
SIM card asks to open a logical channel. 
Definition: le_sim_interface.h:759
le_sim_GetIMSI
le_result_t le_sim_GetIMSI(le_sim_Id_t simId, char *imsi, size_t imsiSize)
LE_SIM_POWER_DOWN
SIM card is powered down. 
Definition: le_sim_interface.h:674
LE_SIM_REFRESH_STEERING_OF_ROAMING_IWLAN
Definition: le_sim_interface.h:792
le_sim_SetAutomaticSelection
le_result_t le_sim_SetAutomaticSelection(bool enable)
LE_SIM_GEMALTO
Gemalto. 
Definition: le_sim_interface.h:717
LE_SIM_STAGE_MAX
Invalid SIM Toolkit Refresh stage. 
Definition: le_sim_interface.h:816
LE_SIM_REFRESH
SIM card asks for a refresh. 
Definition: le_sim_interface.h:761
le_sim_CloseLogicalChannel
le_result_t le_sim_CloseLogicalChannel(uint8_t channel)
le_sim_AddIccidChangeHandler
le_sim_IccidChangeHandlerRef_t le_sim_AddIccidChangeHandler(le_sim_IccidChangeHandlerFunc_t handlerPtr, void *contextPtr)
LE_SIM_EXTERNAL_SLOT_1
SIM inserted in external slot 1. 
Definition: le_sim_interface.h:692
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:827
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)
legato.h
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:713
le_sim_GetEID
le_result_t le_sim_GetEID(le_sim_Id_t simId, char *eid, size_t eidSize)
le_sim_DisconnectHandler_t
void(* le_sim_DisconnectHandler_t)(void *)
Definition: le_sim_interface.h:436
le_sim_StkRefreshStage_t
le_sim_StkRefreshStage_t
Definition: le_sim_interface.h:808
LE_SIM_REMOTE
Remote SIM. 
Definition: le_sim_interface.h:696
LE_SIM_VALID
Valid. 
Definition: le_sim_interface.h:723
le_sim_GetSimToolkitRefreshStage
le_result_t le_sim_GetSimToolkitRefreshStage(le_sim_Id_t simId, le_sim_StkRefreshStage_t *refreshStagePtr)
le_sim_GetAutomaticSelection
le_result_t le_sim_GetAutomaticSelection(bool *enablePtr)
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_REFRESH_EUICC_PROFILE_CHANGE
eUICC Profile State Change. 
Definition: le_sim_interface.h:795
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_StkRefreshMode_t
le_sim_StkRefreshMode_t
Definition: le_sim_interface.h:774
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:653
le_sim_SetPower
le_result_t le_sim_SetPower(le_sim_Id_t simId, le_onoff_t power)
le_sim_GetSubscriberPhoneNumber
le_result_t le_sim_GetSubscriberPhoneNumber(le_sim_Id_t simId, char *phoneNumberStr, size_t phoneNumberStrSize)
le_sim_RemoveIccidChangeHandler
void le_sim_RemoveIccidChangeHandler(le_sim_IccidChangeHandlerRef_t handlerRef)
LE_SIM_BLOCKED
SIM card is blocked. 
Definition: le_sim_interface.h:670
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_REFRESH_RESET
SIM reset. 
Definition: le_sim_interface.h:784
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:719
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_REFRESH_APP_RESET
Application reset. 
Definition: le_sim_interface.h:786
LE_SIM_REFRESH_INIT_FCN
Initialization and File Change Notification. 
Definition: le_sim_interface.h:780
LE_SIM_MORPHO
Morpho. 
Definition: le_sim_interface.h:721
le_sim_Command_t
le_sim_Command_t
Definition: le_sim_interface.h:736
le_sim_ProfileUpdateHandlerFunc_t
void(* le_sim_ProfileUpdateHandlerFunc_t)(le_sim_Id_t simId, le_sim_StkEvent_t stkEvent, void *contextPtr)
Definition: le_sim_interface.h:877
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:694
le_sim_TryConnectService
le_result_t le_sim_TryConnectService(void)
LE_SIM_STATE_UNKNOWN
Unknown SIM state. 
Definition: le_sim_interface.h:676
LE_SIM_READY
SIM card is inserted and unlocked. 
Definition: le_sim_interface.h:668
le_onoff_t
le_onoff_t
Definition: le_basics.h:70
le_sim_ProfileUpdateHandlerRef_t
struct le_sim_ProfileUpdateHandler * le_sim_ProfileUpdateHandlerRef_t
Definition: le_sim_interface.h:835
LE_SIM_UPDATE_RECORD
Update a file record. 
Definition: le_sim_interface.h:742