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