le_rsim_interface.h

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