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


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


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


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


le_sim_StkEvent_t
le_sim_StkEvent_t
Definition: le_sim_interface.h:686


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


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


LE_SIM_EMBEDDED
Embedded SIM. 
Definition: le_sim_interface.h:622


LE_SIM_OBERTHUR
Oberthur. 
Definition: le_sim_interface.h:644


le_sim_States_t
le_sim_States_t
Definition: le_sim_interface.h:596


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


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


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


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


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


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


le_sim_SetServerDisconnectHandler
void le_sim_SetServerDisconnectHandler(le_sim_DisconnectHandler_t disconnectHandler, void *contextPtr)


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


le_sim_AcceptSimToolkitCommand
le_result_t le_sim_AcceptSimToolkitCommand(le_sim_Id_t simId)


le_sim_ReadFPLMNList
le_sim_FPLMNListRef_t le_sim_ReadFPLMNList(le_sim_Id_t simId)


LE_SIM_COMMAND_MAX
Max value. 
Definition: le_sim_interface.h:675


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


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


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


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


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


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


le_sim_DeleteFPLMNList
void le_sim_DeleteFPLMNList(le_sim_FPLMNListRef_t FPLMNListRef)


le_sim_Reset
le_result_t le_sim_Reset(le_sim_Id_t simId)


le_sim_SendCommand
le_result_t le_sim_SendCommand(le_sim_Id_t simId, le_sim_Command_t command, const char *LE_NONNULL fileIdentifier, uint8_t p1, uint8_t p2, uint8_t p3, const uint8_t *dataPtr, size_t dataSize, const char *LE_NONNULL path, uint8_t *sw1Ptr, uint8_t *sw2Ptr, uint8_t *responsePtr, size_t *responseSizePtr)


le_sim_WriteFPLMNList
le_result_t le_sim_WriteFPLMNList(le_sim_Id_t simId, le_sim_FPLMNListRef_t FPLMNListRef)



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


le_sim_SelectCard
le_result_t le_sim_SelectCard(le_sim_Id_t simId)


le_sim_Manufacturer_t
le_sim_Manufacturer_t
Definition: le_sim_interface.h:642


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


LE_SIM_REMOTE
Remote SIM. 
Definition: le_sim_interface.h:628


LE_SIM_VALID
Valid. 
Definition: le_sim_interface.h:652


le_sim_GetRemainingPINTries
int32_t le_sim_GetRemainingPINTries(le_sim_Id_t simId)


le_sim_CreateFPLMNList
le_sim_FPLMNListRef_t le_sim_CreateFPLMNList(void)


le_sim_IsReady
bool le_sim_IsReady(le_sim_Id_t simId)


le_sim_AddSimToolkitEventHandler
le_sim_SimToolkitEventHandlerRef_t le_sim_AddSimToolkitEventHandler(le_sim_SimToolkitEventHandlerFunc_t handlerPtr, void *contextPtr)


le_sim_RemoveSimToolkitEventHandler
void le_sim_RemoveSimToolkitEventHandler(le_sim_SimToolkitEventHandlerRef_t handlerRef)


le_sim_RemoveNewStateHandler
void le_sim_RemoveNewStateHandler(le_sim_NewStateHandlerRef_t handlerRef)


le_sim_RejectSimToolkitCommand
le_result_t le_sim_RejectSimToolkitCommand(le_sim_Id_t simId)


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


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


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


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


le_sim_Command_t
le_sim_Command_t
Definition: le_sim_interface.h:665


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


le_sim_TryConnectService
le_result_t le_sim_TryConnectService(void)


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


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


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