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