le_rsim_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_rsim Remote SIM service
14  *
15  * @ref le_rsim_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * The remote SIM (RSIM) service allows using a remote SIM instead of the internal SIM cards.
20  *
21  * This service allows a user application to convey APDU requests to the remote SIM and APDU
22  * responses to the modem through the RSIM service. The link between the application and the RSIM
23  * service is based on the SIM Access Profile (SAP) specification: the user application must
24  * therefore implement a remote SIM server supporting this specification to handle the remote
25  * SIM card.
26  *
27  * @startuml{le_rsim_Overview.png}
28  * interface "Remote SIM card" as SIM
29  * SIM <-> [Remote SIM Server application] : APDU
30  * [Remote SIM Server application] <-d-> [Legato remote SIM service] : SAP messages
31  * [Legato remote SIM service] <-r-> Modem : APDU
32  * @enduml
33  *
34  * @note The remote SIM Server application is not part of the Legato implementation and
35  * should be developed by the user.
36  *
37  * @section le_rsim_binding IPC interfaces binding
38  *
39  * All the functions of this API are provided by the @b modemService application service.
40  *
41  * Here's a code sample binding to Data Connection services:
42  * @verbatim
43  bindings:
44  {
45  clientExe.clientComponent.le_rsim -> modemService.le_rsim
46  }
47  @endverbatim
48  *
49  * @section le_rsim_Communication Communication
50  *
51  * The communication between the application and the remote SIM service uses the SIM Access Profile
52  * (SAP) protocol.
53  *
54  * The latest <a href="https://www.bluetooth.org/DocMan/handlers/DownloadDoc.ashx?doc_id=158740">
55  * V11r00 SAP specification</a> is supported by the remote SIM service. All client-mandatory
56  * features and some optional features are supported. The table below summarizes all SAP messages
57  * supported by the remote SIM service.
58  * <table>
59  * <tr><th>Feature <th>Associated SAP messages <th>Support in SAP client <th>RSIM support
60  * <tr><td rowspan="5">Connection management <td>CONNECT_REQ <td rowspan="5">Mandatory <td>Supported
61  * <tr> <td>CONNECT_RESP <td>Supported
62  * <tr> <td>DISCONNECT_REQ <td>Supported
63  * <tr> <td>DISCONNECT_RESP <td>Supported
64  * <tr> <td>DISCONNECT_IND <td>Supported
65  * <tr><td rowspan="2">Transfer APDU <td>TRANSFER_APDU_REQ <td rowspan="2">Mandatory <td>Supported
66  * <tr> <td>TRANSFER_APDU_RESP <td>Supported
67  * <tr><td rowspan="2">Transfer ATR <td>TRANSFER_ATR_REQ <td rowspan="2">Mandatory <td>Supported
68  * <tr> <td>TRANSFER_ATR_RESP <td>Supported
69  * <tr><td rowspan="2">Power SIM off <td>POWER_SIM_OFF_REQ <td rowspan="2">Optional <td>Supported
70  * <tr> <td>POWER_SIM_OFF_RESP <td>Supported
71  * <tr><td rowspan="2">Power SIM on <td>POWER_SIM_ON_REQ <td rowspan="2">Mandatory <td>Supported
72  * <tr> <td>POWER_SIM_ON_RESP <td>Supported
73  * <tr><td rowspan="2">Reset SIM <td>RESET_SIM_REQ <td rowspan="2">Optional <td>Supported
74  * <tr> <td>RESET_SIM_RESP <td>Supported
75  * <tr><td>Report Status <td>STATUS_IND <td>Mandatory <td>Supported
76  * <tr><td rowspan="2">Transfer Card Reader Status <td>TRANSFER_CARD_READER_STATUS_REQ <td rowspan="2">Optional <td>Not supported
77  * <tr> <td>TRANSFER_CARD_READER_STATUS_RESP <td>Not supported
78  * <tr><td>Error handling <td>ERROR_RESP <td>Mandatory <td>Supported
79  * <tr><td rowspan="2">Set Transport Protocol <td>SET_TRANSPORT_PROTOCOL_REQ <td rowspan="2">Optional <td>Not supported
80  * <tr> <td>SET_TRANSPORT_PROTOCOL_RESP <td>Not supported
81  * </table>
82  *
83  * The application must register a handler function with le_rsim_AddMessageHandler() in order
84  * to receive the SAP messages sent by the remote SIM service. Registering the handler indicates
85  * that the remote SIM server is ready to receive messages and that a remote SIM card is available.
86  * The handler can be deregistered through the le_rsim_RemoveMessageHandler() function when it is
87  * not needed anymore.
88  *
89  * The application can send SAP messages to the remote SIM service with the le_rsim_SendMessage()
90  * function. Message sending is an asynchronous process: a callback can therefore be passed to
91  * le_rsim_SendMessage() in order to receive the sending result for this message.
92  *
93  * @warning The remote SIM service supports only one remote SIM card and can therefore be
94  * connected with only one application.
95  *
96  * @note
97  * - The remote SIM service has to be supported by the modem to be used: check your platform
98  * documentation.
99  * - The remote SIM card should be selected in order to use the remote SIM service.
100  * - As runtime switch is not currently supported, the switch between local and remote SIM card
101  * requires a platform reset to take effect.
102  *
103  * A sample code of a basic remote SIM server is available in the following page:
104  * - @subpage c_rsimTest
105  *
106  * <HR>
107  *
108  * Copyright (C) Sierra Wireless Inc.
109  */
110 /**
111  * @page c_rsimTest Sample code
112  *
113  * @include "apps/test/modemServices/rsim/rsimIntegrationTest/rsimTestComp/rsimTest.c"
114  */
115 /**
116  * @file le_rsim_interface.h
117  *
118  * Legato @ref c_rsim API.
119  *
120  * <HR>
121  *
122  * Copyright (C) Sierra Wireless Inc.
123  */
124 
125 #ifndef LE_RSIM_INTERFACE_H_INCLUDE_GUARD
126 #define LE_RSIM_INTERFACE_H_INCLUDE_GUARD
127 
128 
129 #include "legato.h"
130 
131 
132 //--------------------------------------------------------------------------------------------------
133 /**
134  * Type for handler called when a server disconnects.
135  */
136 //--------------------------------------------------------------------------------------------------
137 typedef void (*le_rsim_DisconnectHandler_t)(void *);
138 
139 //--------------------------------------------------------------------------------------------------
140 /**
141  *
142  * Connect the current client thread to the service providing this API. Block until the service is
143  * available.
144  *
145  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
146  * called before any other functions in this API. Normally, ConnectService is automatically called
147  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
148  *
149  * This function is created automatically.
150  */
151 //--------------------------------------------------------------------------------------------------
153 (
154  void
155 );
156 
157 //--------------------------------------------------------------------------------------------------
158 /**
159  *
160  * Try to connect the current client thread to the service providing this API. Return with an error
161  * if the service is not available.
162  *
163  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
164  * called before any other functions in this API. Normally, ConnectService is automatically called
165  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
166  *
167  * This function is created automatically.
168  *
169  * @return
170  * - LE_OK if the client connected successfully to the service.
171  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
172  * bound.
173  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
174  * - LE_COMM_ERROR if the Service Directory cannot be reached.
175  */
176 //--------------------------------------------------------------------------------------------------
178 (
179  void
180 );
181 
182 //--------------------------------------------------------------------------------------------------
183 /**
184  * Set handler called when server disconnection is detected.
185  *
186  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
187  * to continue without exiting, it should call longjmp() from inside the handler.
188  */
189 //--------------------------------------------------------------------------------------------------
191 (
192  le_rsim_DisconnectHandler_t disconnectHandler,
193  void *contextPtr
194 );
195 
196 //--------------------------------------------------------------------------------------------------
197 /**
198  *
199  * Disconnect the current client thread from the service providing this API.
200  *
201  * Normally, this function doesn't need to be called. After this function is called, there's no
202  * longer a connection to the service, and the functions in this API can't be used. For details, see
203  * @ref apiFilesC_client.
204  *
205  * This function is created automatically.
206  */
207 //--------------------------------------------------------------------------------------------------
209 (
210  void
211 );
212 
213 
214 //--------------------------------------------------------------------------------------------------
215 /**
216  * Remote SIM maximal message size
217  *
218  * @note
219  * The maximal message size of 276 bytes is based on the longest possible SAP message.
220  * This message is a @c TRANSFER_APDU_RESP composed of a 4-byte SAP header, a 8-byte ResultCode,
221  * a 4-byte ResponseAPDU header, 256 bytes of APDU data, 2 status bytes and 2 padding bytes.
222  */
223 //--------------------------------------------------------------------------------------------------
224 #define LE_RSIM_MAX_MSG_SIZE 276
225 
226 //--------------------------------------------------------------------------------------------------
227 /**
228  ** Remote SIM minimal message size
229  **
230  ** @note
231  ** This minimal length is set to ensure that the communication with the remote SIM server
232  ** can be effective.
233  */
234 //--------------------------------------------------------------------------------------------------
235 #define LE_RSIM_MIN_MSG_SIZE 200
236 
237 //--------------------------------------------------------------------------------------------------
238 /**
239  * Reference type used by Add/Remove functions for EVENT 'le_rsim_Message'
240  */
241 //--------------------------------------------------------------------------------------------------
242 typedef struct le_rsim_MessageHandler* le_rsim_MessageHandlerRef_t;
243 
244 
245 //--------------------------------------------------------------------------------------------------
246 /**
247  * Handler for message notification
248  */
249 //--------------------------------------------------------------------------------------------------
250 typedef void (*le_rsim_MessageHandlerFunc_t)
251 (
252  const uint8_t* messagePtr,
253  ///< Message to notify
254  size_t messageSize,
255  ///<
256  void* contextPtr
257  ///<
258 );
259 
260 //--------------------------------------------------------------------------------------------------
261 /**
262  * Handler for message sending result
263  */
264 //--------------------------------------------------------------------------------------------------
265 typedef void (*le_rsim_CallbackHandlerFunc_t)
266 (
267  uint8_t messageId,
268  ///< Message identifier
269  le_result_t result,
270  ///< Sending result
271  void* contextPtr
272  ///<
273 );
274 
275 //--------------------------------------------------------------------------------------------------
276 /**
277  * Add handler function for EVENT 'le_rsim_Message'
278  *
279  * This event is used to notify and send a message
280  */
281 //--------------------------------------------------------------------------------------------------
283 (
284  le_rsim_MessageHandlerFunc_t handlerPtr,
285  ///< [IN]
286  void* contextPtr
287  ///< [IN]
288 );
289 
290 //--------------------------------------------------------------------------------------------------
291 /**
292  * Remove handler function for EVENT 'le_rsim_Message'
293  */
294 //--------------------------------------------------------------------------------------------------
296 (
297  le_rsim_MessageHandlerRef_t handlerRef
298  ///< [IN]
299 );
300 
301 //--------------------------------------------------------------------------------------------------
302 /**
303  * This function is called by the application to send a message to the Legato remote SIM service
304  *
305  * @return
306  * - LE_OK Function succeeded
307  * - LE_BAD_PARAMETER Message is too long
308  *
309  * @warning The sending process is asynchronous: only the message length is checked by this function
310  * before returning a result. A callback function should be passed as a parameter in order to be
311  * notified of the message sending result.
312  */
313 //--------------------------------------------------------------------------------------------------
315 (
316  const uint8_t* messagePtr,
317  ///< [IN] Message to send
318  size_t messageSize,
319  ///< [IN]
320  le_rsim_CallbackHandlerFunc_t callbackPtr,
321  ///< [IN] Callback for sending result
322  void* contextPtr
323  ///< [IN]
324 );
325 
326 #endif // LE_RSIM_INTERFACE_H_INCLUDE_GUARD
le_result_t le_rsim_SendMessage(const uint8_t *messagePtr, size_t messageSize, le_rsim_CallbackHandlerFunc_t callbackPtr, void *contextPtr)
le_result_t
Definition: le_basics.h:35
void(* le_rsim_DisconnectHandler_t)(void *)
Definition: le_rsim_interface.h:137
void le_rsim_SetServerDisconnectHandler(le_rsim_DisconnectHandler_t disconnectHandler, void *contextPtr)
void le_rsim_ConnectService(void)
struct le_rsim_MessageHandler * le_rsim_MessageHandlerRef_t
Definition: le_rsim_interface.h:242
void(* le_rsim_CallbackHandlerFunc_t)(uint8_t messageId, le_result_t result, void *contextPtr)
Definition: le_rsim_interface.h:266
void le_rsim_DisconnectService(void)
le_result_t le_rsim_TryConnectService(void)
void le_rsim_RemoveMessageHandler(le_rsim_MessageHandlerRef_t handlerRef)
void(* le_rsim_MessageHandlerFunc_t)(const uint8_t *messagePtr, size_t messageSize, void *contextPtr)
Definition: le_rsim_interface.h:251
le_rsim_MessageHandlerRef_t le_rsim_AddMessageHandler(le_rsim_MessageHandlerFunc_t handlerPtr, void *contextPtr)