le_rsim_interface.h

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


le_result_t
le_result_t
Definition: le_basics.h:35


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:219


le_rsim_CallbackHandlerFunc_t
void(* le_rsim_CallbackHandlerFunc_t)(uint8_t messageId, le_result_t result, void *contextPtr)
Definition: le_rsim_interface.h:252


le_rsim_DisconnectService
void le_rsim_DisconnectService(void)



le_rsim_RemoveMessageHandler
void le_rsim_RemoveMessageHandler(le_rsim_MessageHandlerRef_t addHandlerRef)


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


le_rsim_TryConnectService
le_result_t le_rsim_TryConnectService(void)


le_rsim_AddMessageHandler
le_rsim_MessageHandlerRef_t le_rsim_AddMessageHandler(le_rsim_MessageHandlerFunc_t handlerPtr, void *contextPtr)