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 
  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 //--------------------------------------------------------------------------------------------------
  152 void le_rsim_ConnectService
  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 //--------------------------------------------------------------------------------------------------
  177 le_result_t le_rsim_TryConnectService
  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 //--------------------------------------------------------------------------------------------------
  190 void le_rsim_SetServerDisconnectHandler
  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 //--------------------------------------------------------------------------------------------------
  208 void le_rsim_DisconnectService
  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 //--------------------------------------------------------------------------------------------------
  282 le_rsim_MessageHandlerRef_t le_rsim_AddMessageHandler
  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 //--------------------------------------------------------------------------------------------------
  295 void le_rsim_RemoveMessageHandler
  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 //--------------------------------------------------------------------------------------------------
  314 le_result_t le_rsim_SendMessage
  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_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:137
le_rsim_SetServerDisconnectHandler
void le_rsim_SetServerDisconnectHandler(le_rsim_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_rsim_ConnectService
void le_rsim_ConnectService(void)
le_rsim_MessageHandlerRef_t
struct le_rsim_MessageHandler * le_rsim_MessageHandlerRef_t
Definition: le_rsim_interface.h:242
le_rsim_CallbackHandlerFunc_t
void(* le_rsim_CallbackHandlerFunc_t)(uint8_t messageId, le_result_t result, void *contextPtr)
Definition: le_rsim_interface.h:266
le_rsim_DisconnectService
void le_rsim_DisconnectService(void)
legato.h
le_rsim_TryConnectService
le_result_t le_rsim_TryConnectService(void)
le_rsim_RemoveMessageHandler
void le_rsim_RemoveMessageHandler(le_rsim_MessageHandlerRef_t handlerRef)
le_rsim_MessageHandlerFunc_t
void(* le_rsim_MessageHandlerFunc_t)(const uint8_t *messagePtr, size_t messageSize, void *contextPtr)
Definition: le_rsim_interface.h:251
le_rsim_AddMessageHandler
le_rsim_MessageHandlerRef_t le_rsim_AddMessageHandler(le_rsim_MessageHandlerFunc_t handlerPtr, void *contextPtr)