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 // Internal includes for this interface
  132 #include "le_rsim_common.h"
  133 /** @addtogroup le_rsim le_rsim API Reference
  134  * @{
  135  * @file le_rsim_common.h
  136  * @file le_rsim_interface.h **/
  137 //--------------------------------------------------------------------------------------------------
  138 /**
  139  * Type for handler called when a server disconnects.
  140  */
  141 //--------------------------------------------------------------------------------------------------
  142 typedef void (*le_rsim_DisconnectHandler_t)(void *);
  143 
  144 //--------------------------------------------------------------------------------------------------
  145 /**
  146  *
  147  * Connect the current client thread to the service providing this API. Block until the service is
  148  * available.
  149  *
  150  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  151  * called before any other functions in this API.  Normally, ConnectService is automatically called
  152  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  153  *
  154  * This function is created automatically.
  155  */
  156 //--------------------------------------------------------------------------------------------------
  157 void le_rsim_ConnectService
  158 (
  159     void
  160 );
  161 
  162 //--------------------------------------------------------------------------------------------------
  163 /**
  164  *
  165  * Try to connect the current client thread to the service providing this API. Return with an error
  166  * if the service is not available.
  167  *
  168  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  169  * called before any other functions in this API.  Normally, ConnectService is automatically called
  170  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  171  *
  172  * This function is created automatically.
  173  *
  174  * @return
  175  *  - LE_OK if the client connected successfully to the service.
  176  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  177  *    bound.
  178  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  179  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  180  */
  181 //--------------------------------------------------------------------------------------------------
  182 le_result_t le_rsim_TryConnectService
  183 (
  184     void
  185 );
  186 
  187 //--------------------------------------------------------------------------------------------------
  188 /**
  189  * Set handler called when server disconnection is detected.
  190  *
  191  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  192  * to continue without exiting, it should call longjmp() from inside the handler.
  193  */
  194 //--------------------------------------------------------------------------------------------------
  195 LE_FULL_API void le_rsim_SetServerDisconnectHandler
  196 (
  197     le_rsim_DisconnectHandler_t disconnectHandler,
  198     void *contextPtr
  199 );
  200 
  201 //--------------------------------------------------------------------------------------------------
  202 /**
  203  *
  204  * Disconnect the current client thread from the service providing this API.
  205  *
  206  * Normally, this function doesn't need to be called. After this function is called, there's no
  207  * longer a connection to the service, and the functions in this API can't be used. For details, see
  208  * @ref apiFilesC_client.
  209  *
  210  * This function is created automatically.
  211  */
  212 //--------------------------------------------------------------------------------------------------
  213 void le_rsim_DisconnectService
  214 (
  215     void
  216 );
  217 
  218 
  219 //--------------------------------------------------------------------------------------------------
  220 /**
  221  * Handler for message notification
  222  */
  223 //--------------------------------------------------------------------------------------------------
  224 
  225 
  226 //--------------------------------------------------------------------------------------------------
  227 /**
  228  * Handler for message sending result
  229  */
  230 //--------------------------------------------------------------------------------------------------
  231 
  232 
  233 //--------------------------------------------------------------------------------------------------
  234 /**
  235  * Reference type used by Add/Remove functions for EVENT 'le_rsim_Message'
  236  */
  237 //--------------------------------------------------------------------------------------------------
  238 
  239 
  240 //--------------------------------------------------------------------------------------------------
  241 /**
  242  * Add handler function for EVENT 'le_rsim_Message'
  243  *
  244  * This event is used to notify and send a message
  245  */
  246 //--------------------------------------------------------------------------------------------------
  247 le_rsim_MessageHandlerRef_t le_rsim_AddMessageHandler
  248 (
  249     le_rsim_MessageHandlerFunc_t handlerPtr,
  250         ///< [IN]
  251     void* contextPtr
  252         ///< [IN]
  253 );
  254 
  255 //--------------------------------------------------------------------------------------------------
  256 /**
  257  * Remove handler function for EVENT 'le_rsim_Message'
  258  */
  259 //--------------------------------------------------------------------------------------------------
  260 void le_rsim_RemoveMessageHandler
  261 (
  262     le_rsim_MessageHandlerRef_t handlerRef
  263         ///< [IN]
  264 );
  265 
  266 //--------------------------------------------------------------------------------------------------
  267 /**
  268  * This function is called by the application to send a message to the Legato remote SIM service
  269  *
  270  * @return
  271  *  - LE_OK             Function succeeded
  272  *  - LE_BAD_PARAMETER  Message is too long
  273  *
  274  * @warning The sending process is asynchronous: only the message length is checked by this function
  275  * before returning a result. A callback function should be passed as a parameter in order to be
  276  * notified of the message sending result.
  277  */
  278 //--------------------------------------------------------------------------------------------------
  279 le_result_t le_rsim_SendMessage
  280 (
  281     const uint8_t* messagePtr,
  282         ///< [IN] Message to send
  283     size_t messageSize,
  284         ///< [IN]
  285     le_rsim_CallbackHandlerFunc_t callbackPtr,
  286         ///< [IN] Callback for sending result
  287     void* contextPtr
  288         ///< [IN]
  289 );
  290 
  291 /** @} **/
  292 
  293 #endif // LE_RSIM_INTERFACE_H_INCLUDE_GUARD
le_rsim_MessageHandlerRef_t
struct le_rsim_MessageHandler * le_rsim_MessageHandlerRef_t
Definition: le_rsim_common.h:51


le_result_t
le_result_t
Definition: le_basics.h:46


le_rsim_DisconnectHandler_t
void(* le_rsim_DisconnectHandler_t)(void *)
Definition: le_rsim_interface.h:142


le_rsim_CallbackHandlerFunc_t
void(* le_rsim_CallbackHandlerFunc_t)(uint8_t messageId, le_result_t result, void *contextPtr)
Definition: le_rsim_common.h:75


le_rsim_MessageHandlerFunc_t
void(* le_rsim_MessageHandlerFunc_t)(const uint8_t *messagePtr, size_t messageSize, void *contextPtr)
Definition: le_rsim_common.h:60


le_rsim_ConnectService
void le_rsim_ConnectService(void)


le_rsim_TryConnectService
le_result_t le_rsim_TryConnectService(void)


le_rsim_RemoveMessageHandler
void le_rsim_RemoveMessageHandler(le_rsim_MessageHandlerRef_t handlerRef)


LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40


le_rsim_SetServerDisconnectHandler
LE_FULL_API void le_rsim_SetServerDisconnectHandler(le_rsim_DisconnectHandler_t disconnectHandler, void *contextPtr)


le_rsim_common.h


le_rsim_AddMessageHandler
le_rsim_MessageHandlerRef_t le_rsim_AddMessageHandler(le_rsim_MessageHandlerFunc_t handlerPtr, void *contextPtr)



le_rsim_DisconnectService
void le_rsim_DisconnectService(void)


le_rsim_SendMessage
le_result_t le_rsim_SendMessage(const uint8_t *messagePtr, size_t messageSize, le_rsim_CallbackHandlerFunc_t callbackPtr, void *contextPtr)