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 //--------------------------------------------------------------------------------------------------
433 /**
434  * Type for handler called when a server disconnects.
435  */
436 //--------------------------------------------------------------------------------------------------
437 typedef void (*le_sim_DisconnectHandler_t)(void *);
438 
439 //--------------------------------------------------------------------------------------------------
440 /**
441  *
442  * Connect the current client thread to the service providing this API. Block until the service is
443  * available.
444  *
445  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
446  * called before any other functions in this API. Normally, ConnectService is automatically called
447  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
448  *
449  * This function is created automatically.
450  */
451 //--------------------------------------------------------------------------------------------------
453 (
454  void
455 );
456 
457 //--------------------------------------------------------------------------------------------------
458 /**
459  *
460  * Try to connect the current client thread to the service providing this API. Return with an error
461  * if the service is not available.
462  *
463  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
464  * called before any other functions in this API. Normally, ConnectService is automatically called
465  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
466  *
467  * This function is created automatically.
468  *
469  * @return
470  * - LE_OK if the client connected successfully to the service.
471  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
472  * bound.
473  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
474  * - LE_COMM_ERROR if the Service Directory cannot be reached.
475  */
476 //--------------------------------------------------------------------------------------------------
478 (
479  void
480 );
481 
482 //--------------------------------------------------------------------------------------------------
483 /**
484  * Set handler called when server disconnection is detected.
485  *
486  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
487  * to continue without exiting, it should call longjmp() from inside the handler.
488  */
489 //--------------------------------------------------------------------------------------------------
491 (
492  le_sim_DisconnectHandler_t disconnectHandler,
493  void *contextPtr
494 );
495 
496 //--------------------------------------------------------------------------------------------------
497 /**
498  *
499  * Disconnect the current client thread from the service providing this API.
500  *
501  * Normally, this function doesn't need to be called. After this function is called, there's no
502  * longer a connection to the service, and the functions in this API can't be used. For details, see
503  * @ref apiFilesC_client.
504  *
505  * This function is created automatically.
506  */
507 //--------------------------------------------------------------------------------------------------
509 (
510  void
511 );
512 
513 
514 //--------------------------------------------------------------------------------------------------
515 /**
516  * Reference type for FPLMN list.
517  */
518 //--------------------------------------------------------------------------------------------------
519 
520 
521 //--------------------------------------------------------------------------------------------------
522 /**
523  * SIM states.
524  *
525  */
526 //--------------------------------------------------------------------------------------------------
527 
528 
529 //--------------------------------------------------------------------------------------------------
530 /**
531  * SIM identifiers.
532  *
533  */
534 //--------------------------------------------------------------------------------------------------
535 
536 
537 //--------------------------------------------------------------------------------------------------
538 /**
539  * Card Manufacturer.
540  *
541  */
542 //--------------------------------------------------------------------------------------------------
543 
544 
545 //--------------------------------------------------------------------------------------------------
546 /**
547  * SIM commands.
548  */
549 //--------------------------------------------------------------------------------------------------
550 
551 
552 //--------------------------------------------------------------------------------------------------
553 /**
554  * SIM Toolkit events.
555  */
556 //--------------------------------------------------------------------------------------------------
557 
558 
559 //--------------------------------------------------------------------------------------------------
560 /**
561  * SIM Toolkit Refresh modes, defined in ETSI TS 102 223 sections 6.4.7 and 8.6.
562  */
563 //--------------------------------------------------------------------------------------------------
564 
565 
566 //--------------------------------------------------------------------------------------------------
567 /**
568  * SIM Toolkit Refresh stages.
569  */
570 //--------------------------------------------------------------------------------------------------
571 
572 
573 //--------------------------------------------------------------------------------------------------
574 /**
575  * Handler for sim state changes.
576  *
577  */
578 //--------------------------------------------------------------------------------------------------
579 
580 
581 //--------------------------------------------------------------------------------------------------
582 /**
583  * Reference type used by Add/Remove functions for EVENT 'le_sim_NewState'
584  */
585 //--------------------------------------------------------------------------------------------------
586 
587 
588 //--------------------------------------------------------------------------------------------------
589 /**
590  * Handler for profile update events.
591  *
592  */
593 //--------------------------------------------------------------------------------------------------
594 
595 
596 //--------------------------------------------------------------------------------------------------
597 /**
598  * Reference type used by Add/Remove functions for EVENT 'le_sim_ProfileUpdate'
599  */
600 //--------------------------------------------------------------------------------------------------
601 
602 
603 //--------------------------------------------------------------------------------------------------
604 /**
605  * Handler for Sim Toolkit Events.
606  *
607  */
608 //--------------------------------------------------------------------------------------------------
609 
610 
611 //--------------------------------------------------------------------------------------------------
612 /**
613  * Reference type used by Add/Remove functions for EVENT 'le_sim_SimToolkitEvent'
614  */
615 //--------------------------------------------------------------------------------------------------
616 
617 
618 //--------------------------------------------------------------------------------------------------
619 /**
620  * Handler for ICCID change events.
621  *
622  */
623 //--------------------------------------------------------------------------------------------------
624 
625 
626 //--------------------------------------------------------------------------------------------------
627 /**
628  * Reference type used by Add/Remove functions for EVENT 'le_sim_IccidChange'
629  */
630 //--------------------------------------------------------------------------------------------------
631 
632 
633 //--------------------------------------------------------------------------------------------------
634 /**
635  * Add handler function for EVENT 'le_sim_NewState'
636  *
637  * This event provides information on sim state changes.
638  *
639  */
640 //--------------------------------------------------------------------------------------------------
641 le_sim_NewStateHandlerRef_t le_sim_AddNewStateHandler
642 (
643  le_sim_NewStateHandlerFunc_t handlerPtr,
644  ///< [IN]
645  void* contextPtr
646  ///< [IN]
647 );
648 
649 //--------------------------------------------------------------------------------------------------
650 /**
651  * Remove handler function for EVENT 'le_sim_NewState'
652  */
653 //--------------------------------------------------------------------------------------------------
655 (
656  le_sim_NewStateHandlerRef_t handlerRef
657  ///< [IN]
658 );
659 
660 //--------------------------------------------------------------------------------------------------
661 /**
662  * Add handler function for EVENT 'le_sim_ProfileUpdate'
663  *
664  * This event provides information on profile update
665  *
666  */
667 //--------------------------------------------------------------------------------------------------
668 le_sim_ProfileUpdateHandlerRef_t le_sim_AddProfileUpdateHandler
669 (
670  le_sim_ProfileUpdateHandlerFunc_t handlerPtr,
671  ///< [IN]
672  void* contextPtr
673  ///< [IN]
674 );
675 
676 //--------------------------------------------------------------------------------------------------
677 /**
678  * Remove handler function for EVENT 'le_sim_ProfileUpdate'
679  */
680 //--------------------------------------------------------------------------------------------------
682 (
683  le_sim_ProfileUpdateHandlerRef_t handlerRef
684  ///< [IN]
685 );
686 
687 //--------------------------------------------------------------------------------------------------
688 /**
689  * Add handler function for EVENT 'le_sim_SimToolkitEvent'
690  *
691  * This event provides information on Sim Toolkit application.
692  *
693  */
694 //--------------------------------------------------------------------------------------------------
695 le_sim_SimToolkitEventHandlerRef_t le_sim_AddSimToolkitEventHandler
696 (
697  le_sim_SimToolkitEventHandlerFunc_t handlerPtr,
698  ///< [IN]
699  void* contextPtr
700  ///< [IN]
701 );
702 
703 //--------------------------------------------------------------------------------------------------
704 /**
705  * Remove handler function for EVENT 'le_sim_SimToolkitEvent'
706  */
707 //--------------------------------------------------------------------------------------------------
709 (
710  le_sim_SimToolkitEventHandlerRef_t handlerRef
711  ///< [IN]
712 );
713 
714 //--------------------------------------------------------------------------------------------------
715 /**
716  * Add handler function for EVENT 'le_sim_IccidChange'
717  *
718  * This event provides information on ICCID
719  *
720  */
721 //--------------------------------------------------------------------------------------------------
722 le_sim_IccidChangeHandlerRef_t le_sim_AddIccidChangeHandler
723 (
724  le_sim_IccidChangeHandlerFunc_t handlerPtr,
725  ///< [IN]
726  void* contextPtr
727  ///< [IN]
728 );
729 
730 //--------------------------------------------------------------------------------------------------
731 /**
732  * Remove handler function for EVENT 'le_sim_IccidChange'
733  */
734 //--------------------------------------------------------------------------------------------------
736 (
737  le_sim_IccidChangeHandlerRef_t handlerRef
738  ///< [IN]
739 );
740 
741 //--------------------------------------------------------------------------------------------------
742 /**
743  * Get the current selected card.
744  *
745  * @return Number of the current selected SIM card.
746  */
747 //--------------------------------------------------------------------------------------------------
748 le_sim_Id_t le_sim_GetSelectedCard
749 (
750  void
751 );
752 
753 //--------------------------------------------------------------------------------------------------
754 /**
755  * Select a SIM.
756  *
757  * @return LE_FAULT Function failed to select the requested SIM
758  * @return LE_OK Function succeeded.
759  *
760  */
761 //--------------------------------------------------------------------------------------------------
763 (
764  le_sim_Id_t simId
765  ///< [IN] The SIM identifier.
766 );
767 
768 //--------------------------------------------------------------------------------------------------
769 /**
770  * Retrieves the integrated circuit card identifier (ICCID) of the SIM card (20 digits)
771  *
772  * @return LE_OK ICCID was successfully retrieved.
773  * @return LE_OVERFLOW iccidPtr buffer was too small for the ICCID.
774  * @return LE_BAD_PARAMETER Invalid parameters.
775  * @return LE_FAULT The ICCID could not be retrieved.
776  *
777  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
778  * function will not return.
779  */
780 //--------------------------------------------------------------------------------------------------
782 (
783  le_sim_Id_t simId,
784  ///< [IN] The SIM identifier.
785  char* iccid,
786  ///< [OUT] ICCID
787  size_t iccidSize
788  ///< [IN]
789 );
790 
791 //--------------------------------------------------------------------------------------------------
792 /**
793  * Retrieves the identifier for the embedded Universal Integrated Circuit Card identifier (EID)
794  * (32 digits)
795  *
796  * @return LE_OK EID was successfully retrieved.
797  * @return LE_OVERFLOW eidPtr buffer was too small for the EID.
798  * @return LE_BAD_PARAMETER Invalid parameters.
799  * @return LE_FAULT The EID 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  * @warning le_sim_GetEID() function is platform dependent. Please refer to the
805  * @ref platformConstraintsSim_EID section for full details.
806  */
807 //--------------------------------------------------------------------------------------------------
809 (
810  le_sim_Id_t simId,
811  ///< [IN] The SIM identifier.
812  char* eid,
813  ///< [OUT] EID
814  size_t eidSize
815  ///< [IN]
816 );
817 
818 //--------------------------------------------------------------------------------------------------
819 /**
820  * Retrieves the identification number (IMSI) of the SIM card. (max 15 digits)
821  *
822  * @return LE_OVERFLOW The imsiPtr buffer was too small for the IMSI.
823  * @return LE_BAD_PARAMETER The parameters are invalid.
824  * @return LE_FAULT The function failed.
825  * @return LE_TIMEOUT No response was received.
826  * @return LE_OK The function succeeded.
827  *
828  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
829  * function will not return.
830  */
831 //--------------------------------------------------------------------------------------------------
833 (
834  le_sim_Id_t simId,
835  ///< [IN] The SIM identifier.
836  char* imsi,
837  ///< [OUT] IMSI
838  size_t imsiSize
839  ///< [IN]
840 );
841 
842 //--------------------------------------------------------------------------------------------------
843 /**
844  * Verify if the SIM card is present or not.
845  *
846  * @return true SIM card is present.
847  * @return false SIM card is absent
848  *
849  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
850  * function will not return.
851  */
852 //--------------------------------------------------------------------------------------------------
853 bool le_sim_IsPresent
854 (
855  le_sim_Id_t simId
856  ///< [IN] The SIM identifier.
857 );
858 
859 //--------------------------------------------------------------------------------------------------
860 /**
861  * Verify if the SIM is ready (PIN code correctly inserted or not
862  * required).
863  *
864  * @return true PIN is correctly inserted or not required.
865  * @return false PIN must be inserted
866  *
867  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
868  * function will not return.
869  */
870 //--------------------------------------------------------------------------------------------------
871 bool le_sim_IsReady
872 (
873  le_sim_Id_t simId
874  ///< [IN] The SIM identifier.
875 );
876 
877 //--------------------------------------------------------------------------------------------------
878 /**
879  * This function must be called to enter the PIN code.
880  *
881  * @return LE_BAD_PARAMETER The parameters are invalid.
882  * @return LE_NOT_FOUND The function failed to select the SIM card for this operation.
883  * @return LE_UNDERFLOW The PIN code is not long enough (min 4 digits).
884  * @return LE_FAULT The function failed to enter the PIN code.
885  * @return LE_OK The function succeeded.
886  *
887  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
888  * function will not return.
889  *
890  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
891  * function will not return.
892  */
893 //--------------------------------------------------------------------------------------------------
895 (
896  le_sim_Id_t simId,
897  ///< [IN] The SIM identifier.
898  const char* LE_NONNULL pin
899  ///< [IN] The PIN code.
900 );
901 
902 //--------------------------------------------------------------------------------------------------
903 /**
904  * Change the PIN code.
905  *
906  * @return LE_NOT_FOUND Function failed to select the SIM card for this operation.
907  * @return LE_UNDERFLOW PIN code is/are not long enough (min 4 digits).
908  * @return LE_FAULT Function failed to change the PIN code.
909  * @return LE_OK 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 oldpin,
923  ///< [IN] The old PIN code.
924  const char* LE_NONNULL newpin
925  ///< [IN] The new PIN code.
926 );
927 
928 //--------------------------------------------------------------------------------------------------
929 /**
930  * Get the number of remaining PIN insertion tries.
931  *
932  * @return LE_NOT_FOUND The function failed to select the SIM card for this operation.
933  * @return LE_BAD_PARAMETER Invalid SIM identifier.
934  * @return LE_FAULT The function failed to get the number of remaining PIN insertion tries.
935  * @return A positive value The function succeeded. The number of remaining PIN insertion tries.
936  *
937  */
938 //--------------------------------------------------------------------------------------------------
940 (
941  le_sim_Id_t simId
942  ///< [IN] The SIM identifier.
943 );
944 
945 //--------------------------------------------------------------------------------------------------
946 /**
947  * Get the number of remaining PUK insertion tries.
948  *
949  * @return LE_OK On success.
950  * @return LE_NOT_FOUND The function failed to select the SIM card for this operation.
951  * @return LE_BAD_PARAMETER Invalid SIM identifier.
952  * @return LE_FAULT The function failed to get the number of remaining PUK insertion tries.
953  *
954  * @note If the caller is passing an null pointer to this function, it is a fatal error
955  * and the function will not return.
956  *
957  */
958 //--------------------------------------------------------------------------------------------------
960 (
961  le_sim_Id_t simId,
962  ///< [IN] The SIM identifier.
963  uint32_t* remainingPukTriesPtrPtr
964  ///< [OUT] The number of remaining PUK insertion tries.
965 );
966 
967 //--------------------------------------------------------------------------------------------------
968 /**
969  * Unlock the SIM card: it disables the request of the PIN code.
970  *
971  * @return LE_NOT_FOUND Function failed to select the SIM card for this operation.
972  * @return LE_UNDERFLOW PIN code is not long enough (min 4 digits).
973  * @return LE_FAULT The function failed to unlock the SIM card.
974  * @return LE_OK Function succeeded.
975  *
976  * @note If PIN code is too long (max 8 digits), it is a fatal error, the
977  * function will not return.
978  *
979  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
980  * function will not return.
981  */
982 //--------------------------------------------------------------------------------------------------
984 (
985  le_sim_Id_t simId,
986  ///< [IN] The SIM identifier.
987  const char* LE_NONNULL pin
988  ///< [IN] The PIN code.
989 );
990 
991 //--------------------------------------------------------------------------------------------------
992 /**
993  * Lock the SIM card: it enables 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  * Unblock the SIM card.
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_BAD_PARAMETER Invalid SIM identifier.
1022  * @return LE_OUT_OF_RANGE PUK code length is not correct (8 digits).
1023  * @return LE_FAULT The function failed to unlock the SIM card.
1024  * @return LE_OK Function succeeded.
1025  *
1026  * @note If new PIN or puk code are too long (max 8 digits), it is a fatal error, the
1027  * function will not return.
1028  *
1029  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1030  * function will not return.
1031  */
1032 //--------------------------------------------------------------------------------------------------
1034 (
1035  le_sim_Id_t simId,
1036  ///< [IN] The SIM identifier.
1037  const char* LE_NONNULL puk,
1038  ///< [IN] The PUK code.
1039  const char* LE_NONNULL newpin
1040  ///< [IN] The PIN code.
1041 );
1042 
1043 //--------------------------------------------------------------------------------------------------
1044 /**
1045  * Get the SIM state.
1046  *
1047  * @return Current SIM state.
1048  *
1049  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1050  * function will not return.
1051  */
1052 //--------------------------------------------------------------------------------------------------
1053 le_sim_States_t le_sim_GetState
1054 (
1055  le_sim_Id_t simId
1056  ///< [IN] The SIM identifier.
1057 );
1058 
1059 //--------------------------------------------------------------------------------------------------
1060 /**
1061  * Get the SIM Phone Number.
1062  *
1063  * @return
1064  * - LE_OK on success
1065  * - LE_OVERFLOW if the Phone Number can't fit in phoneNumberStr
1066  * - LE_BAD_PARAMETER if a parameter is invalid
1067  * - LE_FAULT on any other failure
1068  *
1069  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1070  * function will not return.
1071  */
1072 //--------------------------------------------------------------------------------------------------
1074 (
1075  le_sim_Id_t simId,
1076  ///< [IN] The SIM identifier.
1077  char* phoneNumberStr,
1078  ///< [OUT] The phone Number.
1079  size_t phoneNumberStrSize
1080  ///< [IN]
1081 );
1082 
1083 //--------------------------------------------------------------------------------------------------
1084 /**
1085  * This function must be called to get the Home Network Name information.
1086  *
1087  * @return
1088  * - LE_OK on success
1089  * - LE_OVERFLOW if the Home Network Name can't fit in nameStr
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  * @note The home network name can be given even if the device is not registered on the network.
1097  */
1098 //--------------------------------------------------------------------------------------------------
1100 (
1101  le_sim_Id_t simId,
1102  ///< [IN] The SIM identifier.
1103  char* nameStr,
1104  ///< [OUT] the home network Name
1105  size_t nameStrSize
1106  ///< [IN]
1107 );
1108 
1109 //--------------------------------------------------------------------------------------------------
1110 /**
1111  * This function must be called to get the Home Network MCC MNC.
1112  *
1113  * @return
1114  * - LE_OK on success
1115  * - LE_NOT_FOUND if Home Network has not been provisioned
1116  * - LE_FAULT for unexpected error
1117  *
1118  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1119  * function will not return.
1120  */
1121 //--------------------------------------------------------------------------------------------------
1123 (
1124  le_sim_Id_t simId,
1125  ///< [IN] The SIM identifier.
1126  char* mccPtr,
1127  ///< [OUT] Mobile Country Code
1128  size_t mccPtrSize,
1129  ///< [IN]
1130  char* mncPtr,
1131  ///< [OUT] Mobile Network Code
1132  size_t mncPtrSize
1133  ///< [IN]
1134 );
1135 
1136 //--------------------------------------------------------------------------------------------------
1137 /**
1138  * This function must be called to request the multi-profile eUICC to swap to ECS and to refresh.
1139  * The User's application must wait for eUICC reboot to be finished and network connection
1140  * available.
1141  *
1142  * @return
1143  * - LE_OK on success
1144  * - LE_BAD_PARAMETER invalid SIM identifier
1145  * - LE_BUSY when a profile swap is already in progress
1146  * - LE_FAULT for unexpected error
1147  * - LE_DUPLICATE for duplicate operation
1148  *
1149  * @note Please ensure that the eUICC is selected using le_sim_SelectCard() and in a ready state
1150  * before attempting a profile swap.
1151  *
1152  * @warning If you use a Morpho or Oberthur card, the SIM_REFRESH PRO-ACTIVE command must be
1153  * accepted with le_sim_AcceptSimToolkitCommand() in order to complete the profile swap
1154  * procedure.
1155  */
1156 //--------------------------------------------------------------------------------------------------
1158 (
1159  le_sim_Id_t simId,
1160  ///< [IN] The SIM identifier.
1161  le_sim_Manufacturer_t manufacturer
1162  ///< [IN] The card manufacturer.
1163 );
1164 
1165 //--------------------------------------------------------------------------------------------------
1166 /**
1167  * This function must be called to request the multi-profile eUICC to swap back to commercial
1168  * subscription and to refresh.
1169  * The User's application must wait for eUICC reboot to be finished and network connection
1170  * available.
1171  *
1172  * @return
1173  * - LE_OK on success
1174  * - LE_BAD_PARAMETER invalid SIM identifier
1175  * - LE_BUSY when a profile swap is already in progress
1176  * - LE_FAULT for unexpected error
1177  * - LE_DUPLICATE for duplicate operation
1178  *
1179  * @note Please ensure that the eUICC is selected using le_sim_SelectCard() and in a ready state
1180  * before attempting a profile swap.
1181  *
1182  * @warning If you use a Morpho or Oberthur card, the SIM_REFRESH PRO-ACTIVE command must be
1183  * accepted with le_sim_AcceptSimToolkitCommand() in order to complete the profile swap
1184  * procedure.
1185  */
1186 //--------------------------------------------------------------------------------------------------
1188 (
1189  le_sim_Id_t simId,
1190  ///< [IN] The SIM identifier.
1191  le_sim_Manufacturer_t manufacturer
1192  ///< [IN] The card manufacturer.
1193 );
1194 
1195 //--------------------------------------------------------------------------------------------------
1196 /**
1197  * This function must be called to get the current subscription.
1198  *
1199  * @return
1200  * - LE_OK on success
1201  * - LE_BAD_PARAMETER invalid SIM identifier or null ECS pointer is passed
1202  * - LE_NOT_FOUND cannot determine the current selected subscription
1203  * - LE_FAULT for unexpected errors
1204  *
1205  * @warning There is no standard method to interrogate the current selected subscription. The
1206  * returned value of this function is based on the last executed local swap command. This means
1207  * that this function will always return LE_NOT_FOUND error at Legato startup.
1208  */
1209 //--------------------------------------------------------------------------------------------------
1211 (
1212  le_sim_Id_t simId,
1213  ///< [IN] The SIM identifier
1214  bool* isEcsPtr
1215  ///< [OUT] true if Emergency Call Subscription (ECS) is selected,
1216  ///< false if Commercial Subscription is selected
1217 );
1218 
1219 //--------------------------------------------------------------------------------------------------
1220 /**
1221  * Accept the last SIM Toolkit command.
1222  *
1223  * @return
1224  * - LE_OK The function succeeded.
1225  * - LE_FAULT The function failed.
1226  */
1227 //--------------------------------------------------------------------------------------------------
1229 (
1230  le_sim_Id_t simId
1231  ///< [IN] The SIM identifier.
1232 );
1233 
1234 //--------------------------------------------------------------------------------------------------
1235 /**
1236  * Reject the last SIM Toolkit command.
1237  *
1238  * @return
1239  * - LE_OK The function succeeded.
1240  * - LE_FAULT The function failed.
1241  */
1242 //--------------------------------------------------------------------------------------------------
1244 (
1245  le_sim_Id_t simId
1246  ///< [IN] The SIM identifier.
1247 );
1248 
1249 //--------------------------------------------------------------------------------------------------
1250 /**
1251  * Retrieve the mode of the last SIM Toolkit Refresh command.
1252  * The modes are defined in ETSI TS 102 223 sections 6.4.7 and 8.6.
1253  *
1254  * @return
1255  * - LE_OK The function succeeded.
1256  * - LE_BAD_PARAMETER A parameter is invalid.
1257  * - LE_UNAVAILABLE The last SIM Toolkit command is not a Refresh command.
1258  * - LE_FAULT The function failed.
1259  * - LE_UNSUPPORTED The platform does not support this operation.
1260  */
1261 //--------------------------------------------------------------------------------------------------
1263 (
1264  le_sim_Id_t simId,
1265  ///< [IN] The SIM identifier.
1266  le_sim_StkRefreshMode_t* refreshModePtr
1267  ///< [OUT] The Refresh mode.
1268 );
1269 
1270 //--------------------------------------------------------------------------------------------------
1271 /**
1272  * Retrieve the stage of the last SIM Toolkit Refresh command.
1273  *
1274  * @return
1275  * - LE_OK The function succeeded.
1276  * - LE_BAD_PARAMETER A parameter is invalid.
1277  * - LE_UNAVAILABLE The last SIM Toolkit command is not a Refresh command.
1278  * - LE_FAULT The function failed.
1279  */
1280 //--------------------------------------------------------------------------------------------------
1282 (
1283  le_sim_Id_t simId,
1284  ///< [IN] The SIM identifier.
1285  le_sim_StkRefreshStage_t* refreshStagePtr
1286  ///< [OUT] The Refresh stage.
1287 );
1288 
1289 //--------------------------------------------------------------------------------------------------
1290 /**
1291  * Send APDU command to the SIM.
1292  *
1293  * @return
1294  * - LE_OK Function succeeded.
1295  * - LE_FAULT The function failed.
1296  * - LE_BAD_PARAMETER A parameter is invalid.
1297  * - LE_NOT_FOUND The function failed to select the SIM card for this operation.
1298  */
1299 //--------------------------------------------------------------------------------------------------
1301 (
1302  le_sim_Id_t simId,
1303  ///< [IN] The SIM identifier.
1304  const uint8_t* commandApduPtr,
1305  ///< [IN] APDU command.
1306  size_t commandApduSize,
1307  ///< [IN]
1308  uint8_t* responseApduPtr,
1309  ///< [OUT] SIM response.
1310  size_t* responseApduSizePtr
1311  ///< [INOUT]
1312 );
1313 
1314 //--------------------------------------------------------------------------------------------------
1315 /**
1316  * Send a command to the SIM.
1317  *
1318  * @return
1319  * - LE_OK Function succeeded.
1320  * - LE_FAULT The function failed.
1321  * - LE_BAD_PARAMETER A parameter is invalid.
1322  * - LE_NOT_FOUND - The function failed to select the SIM card for this operation
1323  * - The requested SIM file is not found
1324  * - LE_OVERFLOW Response buffer is too small to copy the SIM answer.
1325  * - LE_UNSUPPORTED The platform does not support this operation.
1326  */
1327 //--------------------------------------------------------------------------------------------------
1329 (
1330  le_sim_Id_t simId,
1331  ///< [IN] The SIM identifier.
1332  le_sim_Command_t command,
1333  ///< [IN] The SIM command.
1334  const char* LE_NONNULL fileIdentifier,
1335  ///< [IN] File identifier
1336  uint8_t p1,
1337  ///< [IN] Parameter P1 passed to the SIM
1338  uint8_t p2,
1339  ///< [IN] Parameter P2 passed to the SIM
1340  uint8_t p3,
1341  ///< [IN] Parameter P3 passed to the SIM
1342  const uint8_t* dataPtr,
1343  ///< [IN] data command.
1344  size_t dataSize,
1345  ///< [IN]
1346  const char* LE_NONNULL path,
1347  ///< [IN] path of the elementary file
1348  uint8_t* sw1Ptr,
1349  ///< [OUT] Status Word 1 received from the SIM
1350  uint8_t* sw2Ptr,
1351  ///< [OUT] Status Word 2 received from the SIM
1352  uint8_t* responsePtr,
1353  ///< [OUT] SIM response.
1354  size_t* responseSizePtr
1355  ///< [INOUT]
1356 );
1357 
1358 //--------------------------------------------------------------------------------------------------
1359 /**
1360  * Enable or disable the automatic SIM selection
1361  *
1362  * @note Automatic SIM selection uses the following rule: If an external SIM is inserted in
1363  * slot 1 then select it. Otherwise, fall back to the internal SIM card.
1364  *
1365  * @return
1366  * - LE_OK Function succeeded.
1367  * - LE_FAULT Function failed to execute.
1368  *
1369  */
1370 //--------------------------------------------------------------------------------------------------
1372 (
1373  bool enable
1374  ///< [IN] True if the feature needs to be enabled. False otherwise.
1375 );
1376 
1377 //--------------------------------------------------------------------------------------------------
1378 /**
1379  * Get the automatic SIM selection
1380  *
1381  * @note When enabled, automatic SIM selection uses the following rule: If an external SIM is
1382  * inserted in slot 1 then select it. Otherwise, fall back to the internal SIM card.
1383  *
1384  * @return
1385  * - LE_OK Function succeeded.
1386  * - LE_FAULT Function failed to execute.
1387  * - LE_BAD_PARAMETER Invalid parameter.
1388  * - LE_UNSUPPORTED The platform does not support this operation.
1389  *
1390  */
1391 //--------------------------------------------------------------------------------------------------
1393 (
1394  bool* enablePtr
1395  ///< [OUT] True if the feature is enabled. False otherwise.
1396 );
1397 
1398 //--------------------------------------------------------------------------------------------------
1399 /**
1400  * Reset the SIM.
1401  *
1402  * @return
1403  * - LE_FAULT Function failed.
1404  * - LE_OK Function succeeded.
1405  */
1406 //--------------------------------------------------------------------------------------------------
1408 (
1409  le_sim_Id_t simId
1410  ///< [IN] The SIM identifier.
1411 );
1412 
1413 //--------------------------------------------------------------------------------------------------
1414 /**
1415  * Create empty FPLMN list to insert FPLMN operators.
1416  *
1417  * @return
1418  * - Reference to the List object.
1419  * - Null pointer if not able to create list reference.
1420  */
1421 //--------------------------------------------------------------------------------------------------
1422 le_sim_FPLMNListRef_t le_sim_CreateFPLMNList
1423 (
1424  void
1425 );
1426 
1427 //--------------------------------------------------------------------------------------------------
1428 /**
1429  * Add FPLMN network into the newly created FPLMN list.
1430  * If the FPLMNListRef, mcc or mnc is not valid then this function will kill the calling client.
1431  *
1432  * @return
1433  * - LE_FAULT Function failed.
1434  * - LE_OK Function succeeded.
1435  * - LE_OVERFLOW If FPLMN operator can not be inserted into FPLMN list.
1436  */
1437 //--------------------------------------------------------------------------------------------------
1439 (
1440  le_sim_FPLMNListRef_t FPLMNListRef,
1441  ///< [IN] FPLMN list reference.
1442  const char* LE_NONNULL mcc,
1443  ///< [IN] Mobile Country Code.
1444  const char* LE_NONNULL mnc
1445  ///< [IN] Mobile Network Code.
1446 );
1447 
1448 //--------------------------------------------------------------------------------------------------
1449 /**
1450  * Write FPLMN list into the SIM.
1451  * If the FPLMNListRef is not valid then this function will kill the calling client.
1452  *
1453  * @return
1454  * - LE_FAULT Function failed.
1455  * - LE_OK Function succeeded.
1456  *
1457  */
1458 //--------------------------------------------------------------------------------------------------
1460 (
1461  le_sim_Id_t simId,
1462  ///< [IN] The SIM identifier.
1463  le_sim_FPLMNListRef_t FPLMNListRef
1464  ///< [IN] FPLMN list reference.
1465 );
1466 
1467 //--------------------------------------------------------------------------------------------------
1468 /**
1469  * Read FPLMN list from the SIM.
1470  *
1471  * @return
1472  * - Reference to the List object.
1473  * - Null pointer if FPLMN list is not able to read from the SIM.
1474  */
1475 //--------------------------------------------------------------------------------------------------
1476 le_sim_FPLMNListRef_t le_sim_ReadFPLMNList
1477 (
1478  le_sim_Id_t simId
1479  ///< [IN] The SIM identifier.
1480 );
1481 
1482 //--------------------------------------------------------------------------------------------------
1483 /**
1484  * Read the first FPLMN network from the list of FPLMN objects retrieved with
1485  * le_sim_ReadFPLMNList().
1486  * If the FPLMNListRef, mccPtr or mncPtr is not valid then this function will kill the calling
1487  * client.
1488  *
1489  * @return
1490  * - LE_FAULT Function failed.
1491  * - LE_OK Function succeeded.
1492  * - LE_OVERFLOW MCC/MNC string size is greater than string length parameter which has
1493  * been given into this function.
1494  */
1495 //--------------------------------------------------------------------------------------------------
1497 (
1498  le_sim_FPLMNListRef_t FPLMNListRef,
1499  ///< [IN] FPLMN list reference.
1500  char* mccPtr,
1501  ///< [OUT] Mobile Country Code.
1502  size_t mccPtrSize,
1503  ///< [IN]
1504  char* mncPtr,
1505  ///< [OUT] Mobile Network Code.
1506  size_t mncPtrSize
1507  ///< [IN]
1508 );
1509 
1510 //--------------------------------------------------------------------------------------------------
1511 /**
1512  * Read the next FPLMN network from the list of FPLMN objects retrieved with le_sim_ReadFPLMNList().
1513  * If the FPLMNListRef, mccPtr or mncPtr is not valid then this function will kill the calling
1514  * client.
1515  *
1516  * @return
1517  * - LE_FAULT Function failed.
1518  * - LE_OK Function succeeded.
1519  * - LE_OVERFLOW MCC/MNC string size is greater than string length parameter which has
1520  * been given into this function.
1521  */
1522 //--------------------------------------------------------------------------------------------------
1524 (
1525  le_sim_FPLMNListRef_t FPLMNListRef,
1526  ///< [IN] FPLMN list reference.
1527  char* mccPtr,
1528  ///< [OUT] Mobile Country Code.
1529  size_t mccPtrSize,
1530  ///< [IN]
1531  char* mncPtr,
1532  ///< [OUT] Mobile Network Code.
1533  size_t mncPtrSize
1534  ///< [IN]
1535 );
1536 
1537 //--------------------------------------------------------------------------------------------------
1538 /**
1539  * Delete the FPLMN list created by le_sim_ReadFPLMNList() or le_sim_CreateFPLMNList().
1540  * If the FPLMNListRef is not valid then this function will kill the calling client.
1541  *
1542  * @note
1543  * On failure, the process exits, so you don't have to worry about checking the returned
1544  * reference for validity.
1545  */
1546 //--------------------------------------------------------------------------------------------------
1548 (
1549  le_sim_FPLMNListRef_t FPLMNListRef
1550  ///< [IN] FPLMN list reference.
1551 );
1552 
1553 //--------------------------------------------------------------------------------------------------
1554 /**
1555  * Open a logical channel on the SIM card.
1556  *
1557  * @return
1558  * - LE_OK Function succeeded.
1559  * - LE_BAD_PARAMETER Invalid parameter.
1560  * - LE_FAULT Function failed.
1561  */
1562 //--------------------------------------------------------------------------------------------------
1564 (
1565  uint8_t* channelPtrPtr
1566  ///< [OUT] The number of the opened logical channel.
1567 );
1568 
1569 //--------------------------------------------------------------------------------------------------
1570 /**
1571  * Close a logical channel on the SIM card.
1572  *
1573  * @return
1574  * - LE_OK Function succeeded.
1575  * - LE_FAULT Function failed.
1576  */
1577 //--------------------------------------------------------------------------------------------------
1579 (
1580  uint8_t channel
1581  ///< [IN] The number of the logical channel to close.
1582 );
1583 
1584 //--------------------------------------------------------------------------------------------------
1585 /**
1586  * Send APDU command on a dedicated logical channel.
1587  *
1588  * @return
1589  * - LE_OK Function succeeded.
1590  * - LE_BAD_PARAMETER A parameter is invalid.
1591  * - LE_NOT_FOUND The function failed to select the SIM card for this operation.
1592  * - LE_FAULT The function failed.
1593  */
1594 //--------------------------------------------------------------------------------------------------
1596 (
1597  le_sim_Id_t simId,
1598  ///< [IN] The SIM identifier.
1599  uint8_t channel,
1600  ///< [IN] The logical channel number.
1601  const uint8_t* commandApduPtr,
1602  ///< [IN] APDU command.
1603  size_t commandApduSize,
1604  ///< [IN]
1605  uint8_t* responseApduPtr,
1606  ///< [OUT] SIM response.
1607  size_t* responseApduSizePtr
1608  ///< [INOUT]
1609 );
1610 
1611 //--------------------------------------------------------------------------------------------------
1612 /**
1613  * Power up or down the current SIM.
1614  *
1615  * @return LE_OK Function succeeded.
1616  * @return LE_FAULT Function failed.
1617  *
1618  * @note For SIM power cycle operation, it must wait until SIM state is LE_SIM_POWER_DOWN
1619  * before powering on the SIM, otherwise power up SIM will fail.
1620  */
1621 //--------------------------------------------------------------------------------------------------
1623 (
1624  le_sim_Id_t simId,
1625  ///< [IN] The SIM identifier.
1626  le_onoff_t power
1627  ///< [IN] The power state.
1628 );
1629 
1630 #endif // LE_SIM_INTERFACE_H_INCLUDE_GUARD
le_sim_NewStateHandlerRef_t le_sim_AddNewStateHandler(le_sim_NewStateHandlerFunc_t handlerPtr, void *contextPtr)
bool le_sim_IsPresent(le_sim_Id_t simId)
le_result_t le_sim_GetHomeNetworkOperator(le_sim_Id_t simId, char *nameStr, size_t nameStrSize)
le_result_t le_sim_GetRemainingPUKTries(le_sim_Id_t simId, uint32_t *remainingPukTriesPtrPtr)
le_result_t
Definition: le_basics.h:35
le_result_t le_sim_LocalSwapToEmergencyCallSubscription(le_sim_Id_t simId, le_sim_Manufacturer_t manufacturer)
LE_FULL_API void le_sim_SetServerDisconnectHandler(le_sim_DisconnectHandler_t disconnectHandler, void *contextPtr)
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_SendApdu(le_sim_Id_t simId, const uint8_t *commandApduPtr, size_t commandApduSize, uint8_t *responseApduPtr, size_t *responseApduSizePtr)
void le_sim_RemoveProfileUpdateHandler(le_sim_ProfileUpdateHandlerRef_t handlerRef)
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_GetFirstFPLMNOperator(le_sim_FPLMNListRef_t FPLMNListRef, char *mccPtr, size_t mccPtrSize, char *mncPtr, size_t mncPtrSize)
le_result_t le_sim_OpenLogicalChannel(uint8_t *channelPtrPtr)
le_result_t le_sim_GetSimToolkitRefreshMode(le_sim_Id_t simId, le_sim_StkRefreshMode_t *refreshModePtr)
le_sim_ProfileUpdateHandlerRef_t le_sim_AddProfileUpdateHandler(le_sim_ProfileUpdateHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_sim_GetICCID(le_sim_Id_t simId, char *iccid, size_t iccidSize)
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_AcceptSimToolkitCommand(le_sim_Id_t simId)
le_result_t le_sim_SendApduOnChannel(le_sim_Id_t simId, uint8_t channel, const uint8_t *commandApduPtr, size_t commandApduSize, uint8_t *responseApduPtr, size_t *responseApduSizePtr)
le_sim_FPLMNListRef_t le_sim_ReadFPLMNList(le_sim_Id_t simId)
void le_sim_ConnectService(void)
le_result_t le_sim_GetIMSI(le_sim_Id_t simId, char *imsi, size_t imsiSize)
le_result_t le_sim_SetAutomaticSelection(bool enable)
le_result_t le_sim_CloseLogicalChannel(uint8_t channel)
le_sim_IccidChangeHandlerRef_t le_sim_AddIccidChangeHandler(le_sim_IccidChangeHandlerFunc_t handlerPtr, void *contextPtr)
void le_sim_DisconnectService(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
void le_sim_DeleteFPLMNList(le_sim_FPLMNListRef_t FPLMNListRef)
le_result_t le_sim_Reset(le_sim_Id_t simId)
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_WriteFPLMNList(le_sim_Id_t simId, le_sim_FPLMNListRef_t FPLMNListRef)
le_result_t le_sim_AddFPLMNOperator(le_sim_FPLMNListRef_t FPLMNListRef, const char *LE_NONNULL mcc, const char *LE_NONNULL mnc)
le_result_t le_sim_SelectCard(le_sim_Id_t simId)
le_result_t le_sim_GetEID(le_sim_Id_t simId, char *eid, size_t eidSize)
void(* le_sim_DisconnectHandler_t)(void *)
Definition: le_sim_interface.h:437
le_result_t le_sim_GetSimToolkitRefreshStage(le_sim_Id_t simId, le_sim_StkRefreshStage_t *refreshStagePtr)
le_result_t le_sim_GetAutomaticSelection(bool *enablePtr)
int32_t le_sim_GetRemainingPINTries(le_sim_Id_t simId)
le_sim_FPLMNListRef_t le_sim_CreateFPLMNList(void)
bool le_sim_IsReady(le_sim_Id_t simId)
le_sim_SimToolkitEventHandlerRef_t le_sim_AddSimToolkitEventHandler(le_sim_SimToolkitEventHandlerFunc_t handlerPtr, void *contextPtr)
void le_sim_RemoveSimToolkitEventHandler(le_sim_SimToolkitEventHandlerRef_t handlerRef)
void le_sim_RemoveNewStateHandler(le_sim_NewStateHandlerRef_t handlerRef)
le_result_t le_sim_RejectSimToolkitCommand(le_sim_Id_t simId)
le_result_t le_sim_SetPower(le_sim_Id_t simId, le_onoff_t power)
le_result_t le_sim_GetSubscriberPhoneNumber(le_sim_Id_t simId, char *phoneNumberStr, size_t phoneNumberStrSize)
void le_sim_RemoveIccidChangeHandler(le_sim_IccidChangeHandlerRef_t handlerRef)
le_result_t le_sim_Unblock(le_sim_Id_t simId, const char *LE_NONNULL puk, const char *LE_NONNULL newpin)
le_result_t le_sim_IsEmergencyCallSubscriptionSelected(le_sim_Id_t simId, bool *isEcsPtr)
le_result_t le_sim_Unlock(le_sim_Id_t simId, const char *LE_NONNULL pin)
le_result_t le_sim_Lock(le_sim_Id_t simId, const char *LE_NONNULL pin)
le_sim_Id_t le_sim_GetSelectedCard(void)
le_result_t le_sim_EnterPIN(le_sim_Id_t simId, const char *LE_NONNULL pin)
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)
le_result_t le_sim_TryConnectService(void)
le_onoff_t
Definition: le_basics.h:71