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