le_sim_interface.h

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


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:565


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:682


le_result_t
le_result_t
Definition: le_basics.h:35


le_sim_LocalSwapToEmergencyCallSubscription
le_result_t le_sim_LocalSwapToEmergencyCallSubscription(le_sim_Id_t simId, le_sim_Manufacturer_t manufacturer)


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


le_mdmDefs_interface.h


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


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


le_sim_StkEvent_t
le_sim_StkEvent_t
Definition: le_sim_interface.h:631


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


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


LE_SIM_EMBEDDED
Embedded SIM. 
Definition: le_sim_interface.h:567


LE_SIM_OBERTHUR
Oberthur. 
Definition: le_sim_interface.h:589


le_sim_States_t
le_sim_States_t
Definition: le_sim_interface.h:541


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


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


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


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


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:666


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_AcceptSimToolkitCommand
le_result_t le_sim_AcceptSimToolkitCommand(le_sim_Id_t simId)


LE_SIM_COMMAND_MAX
Max value. 
Definition: le_sim_interface.h:620


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


le_sim_ConnectService
void le_sim_ConnectService(void)


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


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


LE_SIM_GEMALTO
Gemalto. 
Definition: le_sim_interface.h:591


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


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


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:648


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_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:587


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


LE_SIM_REMOTE
Remote SIM. 
Definition: le_sim_interface.h:573


LE_SIM_VALID
Valid. 
Definition: le_sim_interface.h:597


le_sim_GetRemainingPINTries
int32_t le_sim_GetRemainingPINTries(le_sim_Id_t simId)


le_sim_IsReady
bool le_sim_IsReady(le_sim_Id_t simId)


le_sim_AddSimToolkitEventHandler
le_sim_SimToolkitEventHandlerRef_t le_sim_AddSimToolkitEventHandler(le_sim_SimToolkitEventHandlerFunc_t handlerPtr, void *contextPtr)


le_sim_RemoveSimToolkitEventHandler
void le_sim_RemoveSimToolkitEventHandler(le_sim_SimToolkitEventHandlerRef_t handlerRef)


le_sim_RemoveNewStateHandler
void le_sim_RemoveNewStateHandler(le_sim_NewStateHandlerRef_t handlerRef)


le_sim_RejectSimToolkitCommand
le_result_t le_sim_RejectSimToolkitCommand(le_sim_Id_t simId)


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


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


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


le_sim_IsEmergencyCallSubscriptionSelected
le_result_t le_sim_IsEmergencyCallSubscriptionSelected(le_sim_Id_t simId, bool *isEcsPtr)


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


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


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


LE_SIM_MORPHO
Morpho. 
Definition: le_sim_interface.h:595


le_sim_Command_t
le_sim_Command_t
Definition: le_sim_interface.h:610


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:571


le_sim_TryConnectService
le_result_t le_sim_TryConnectService(void)


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


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


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