le_sim_interface.h

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