le_atClient_interface.h

    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_atClient AT Commands Client
   12  *
   13  * @ref le_atClient_interface.h "API Reference"
   14  *
   15  * @warning Some AT commands may conflict with Legato APIs; using both may cause problems that can
   16  * be difficult to diagnose. AT commands should be avoided whenever possible, and should only be
   17  * used with great care.
   18  *
   19  * The AT Client Service handles the AT commands sent to the modem on a specified
   20  * serial device. It also supports getting AT command responses (intermediate, final or
   21  * unsolicited responses).
   22  * This service can be subscribed to by several apps simultaneously.
   23  *
   24  * @section atClient_binding Device Binding
   25  *
   26  * le_atClient_Start() must be called to bind a specific device with the ATClient.
   27  * Multiple devices can be bound. The app has to configured the device before using it with
   28  * the ATClient.
   29  * A device can be unbound using le_atClient_Stop().
   30  *
   31  * @section atClient_statement Statement
   32  *
   33  * An AT command statement is requested before sending it. The following steps have to be done for
   34  * its declaration:
   35  *
   36  * - create an AT command reference using le_atClient_Create().
   37  *
   38  * - use le_atClient_SetCommand() to set the AT command to be sent to the modem.
   39  *
   40  * - set the sending port to use le_atClient_SetDevice().
   41  *
   42  * - can set a timeout value using le_atClient_SetTimeout(); default value is @c 30s.
   43  *
   44  * - request expected final responses and set using le_atClient_SetFinalResponse().The final
   45  * response is mandatory to detect
   46  * the end of the AT command execution. If an AT command answers with a final response that
   47  * doesn't belong to the final responses set, the AT command execution will end by timeout.
   48  *
   49  * - can call le_atClient_SetIntermediateResponse() to set the intermediate responses
   50  * filters. This is optional.
   51  *
   52  * Command responses given in le_atClient_SetIntermediateResponse() and
   53  * le_atClient_SetFinalResponse() are the first characters of the response lines. They are used as a
   54  * filter of the received lines (a line are the characters received between receiving a
   55  * <CR> and an <LF>). Other lines are dropped.
   56  *
   57  * - text can be set using le_atClient_SetText(). This is used for commands that answers a
   58  * '>' character to receive additional information. The given text is sent to the modem when '>' is
   59  * detected. The character @c CTRL-Z is automatically sent.
   60  *
   61  *
   62  * @section atClient_send Sending
   63  *
   64  * When the AT command declaration is complete, it can be sent using le_atClient_Send(). This API is
   65  * synchronous (blocking until final response is detected, or timeout reached).
   66  *
   67  * le_atClient_SetCommandAndSend() is equivalent to le_atClient_Create(), le_atClient_SetCommand(),
   68  * le_atClient_SetDevice(), le_atClient_SetTimeout(), le_atClient_SetIntermediateResponse() and
   69  * le_atClient_SetFinalResponse(), in case of an Error le_atClient_Delete(),
   70  * in one API call.
   71  * The AT command reference is created and returned by this API. When an error
   72  * occurs the command reference is deleted and is not a valid reference anymore
   73  *
   74  * @section atClient_responses Responses
   75  *
   76  * When the AT command has been sent correctly (i.e., le_atClient_Send() or
   77  * le_atClient_SetCommandAndSend() execution is successful), the app gets these AT command
   78  * responses:
   79  * - le_atClient_GetFinalResponse() is used to get the final responses
   80  * - le_atClient_GetFirstIntermediateResponse() is used to get the first intermediate result code.
   81  * Other intermediate result codes can be obtained by calling
   82  * le_atClient_GetNextIntermediateResponse().Returns LE_NOT_FOUND when there are no further results.
   83  *
   84  * When a response has been set in the AT command declaration, the AT command response returned by
   85  * these APIs start with the given pattern, and ends when a <CR><LF> is detected.
   86  *
   87  * @section atClient__delete Deleting
   88  *
   89  * When the AT command is over, the reference has to be deleted by calling le_atClient_Delete().
   90  *
   91  * @section atClient_unsolicited Unsolicited Responses
   92  *
   93  * An app can subscribe to a specific, unsolicited response using
   94  * le_atClient_AddUnsolicitedResponseHandler(), and can be removed using
   95  * le_atClient_RemoveUnsolicitedResponseHandler(). The subscribed handler is called when the given
   96  * pattern is detected. The handler receives a parameter with the complete line of the unsolicited
   97  * response.
   98  * The parameter @c lineCount is used to set the unsolicited lines number.
   99  * For example, @c +CMT unsolicited response has the following syntax:
  100  * @code
  101  * +CMT: ...<CR><LF>
  102  * <sms text>
  103  * @endcode
  104  * In this case, @c lineCount has to be set to @c 2 to receive both lines into the handler.
  105  * @c +CREG unsolicited response is sent only one line, so @c lineCount is set to @c 1.
  106  *
  107  * <HR>
  108  *
  109  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
  110  */
  111 /**
  112  * @file le_atClient_interface.h
  113  *
  114  * Legato @ref c_atClient include file.
  115  *
  116  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
  117  */
  118 
  119 #ifndef LE_ATCLIENT_INTERFACE_H_INCLUDE_GUARD
  120 #define LE_ATCLIENT_INTERFACE_H_INCLUDE_GUARD
  121 
  122 
  123 #include "legato.h"
  124 
  125 // Interface specific includes
  126 #include "le_atDefs_interface.h"
  127 
  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_atClient_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_atClient_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_atClient_DisconnectService
  184 (
  185     void
  186 );
  187 
  188 
  189 //--------------------------------------------------------------------------------------------------
  190 
  191 //--------------------------------------------------------------------------------------------------
  192 typedef struct le_atClient_Cmd* le_atClient_CmdRef_t;
  193 
  194 
  195 //--------------------------------------------------------------------------------------------------
  196 
  197 //--------------------------------------------------------------------------------------------------
  198 typedef struct le_atClient_Device* le_atClient_DeviceRef_t;
  199 
  200 
  201 //--------------------------------------------------------------------------------------------------
  202 /**
  203  * Reference type used by Add/Remove functions for EVENT 'le_atClient_UnsolicitedResponse'
  204  */
  205 //--------------------------------------------------------------------------------------------------
  206 typedef struct le_atClient_UnsolicitedResponseHandler* le_atClient_UnsolicitedResponseHandlerRef_t;
  207 
  208 
  209 //--------------------------------------------------------------------------------------------------
  210 /**
  211  * Handler for unsolicited response reception.
  212  *
  213  *
  214  * @param unsolicitedRsp
  215  *        The call reference.
  216  * @param contextPtr
  217  */
  218 //--------------------------------------------------------------------------------------------------
  219 typedef void (*le_atClient_UnsolicitedResponseHandlerFunc_t)
  220 (
  221     const char* unsolicitedRsp,
  222     void* contextPtr
  223 );
  224 
  225 //--------------------------------------------------------------------------------------------------
  226 /**
  227  * This function must be called to start a ATClient session on a specified device.
  228  *
  229  * @return reference on a device context
  230  */
  231 //--------------------------------------------------------------------------------------------------
  232 le_atClient_DeviceRef_t le_atClient_Start
  233 (
  234     int fd
  235         ///< [IN] File descriptor.
  236 );
  237 
  238 //--------------------------------------------------------------------------------------------------
  239 /**
  240  * This function must be called to stop the ATClient session on the specified device.
  241  *
  242  * @return
  243  *      - LE_FAULT when function failed
  244  *      - LE_OK when function succeed
  245  */
  246 //--------------------------------------------------------------------------------------------------
  247 le_result_t le_atClient_Stop
  248 (
  249     le_atClient_DeviceRef_t device
  250         ///< [IN] Device reference
  251 );
  252 
  253 //--------------------------------------------------------------------------------------------------
  254 /**
  255  * This function must be called to create a new AT command.
  256  *
  257  * @return pointer to the new AT Command reference
  258  */
  259 //--------------------------------------------------------------------------------------------------
  260 le_atClient_CmdRef_t le_atClient_Create
  261 (
  262     void
  263 );
  264 
  265 //--------------------------------------------------------------------------------------------------
  266 /**
  267  * This function must be called to delete an AT command reference.
  268  *
  269  * @return
  270  *      - LE_OK when function succeed
  271  *
  272  * @note If the AT Command reference is invalid, a fatal error occurs,
  273  *       the function won't return.
  274  */
  275 //--------------------------------------------------------------------------------------------------
  276 le_result_t le_atClient_Delete
  277 (
  278     le_atClient_CmdRef_t cmdRef
  279         ///< [IN] AT Command
  280 );
  281 
  282 //--------------------------------------------------------------------------------------------------
  283 /**
  284  * This function must be called to set the AT command string to be sent.
  285  *
  286  * @return
  287  *      - LE_OK when function succeed
  288  *
  289  * @note If the AT Command reference is invalid, a fatal error occurs,
  290  *       the function won't return.
  291  */
  292 //--------------------------------------------------------------------------------------------------
  293 le_result_t le_atClient_SetCommand
  294 (
  295     le_atClient_CmdRef_t cmdRef,
  296         ///< [IN] AT Command
  297 
  298     const char* command
  299         ///< [IN] Set Command
  300 );
  301 
  302 //--------------------------------------------------------------------------------------------------
  303 /**
  304  * This function must be called to set the waiting intermediate responses.
  305  * Several intermediate responses can be specified separated by a '|' character into the string
  306  * given in parameter.
  307  *
  308  * @return
  309  *      - LE_FAULT when function failed
  310  *      - LE_OK when function succeed
  311  *
  312  * @note If the AT Command reference is invalid, a fatal error occurs,
  313  *       the function won't return.
  314  */
  315 //--------------------------------------------------------------------------------------------------
  316 le_result_t le_atClient_SetIntermediateResponse
  317 (
  318     le_atClient_CmdRef_t cmdRef,
  319         ///< [IN] AT Command
  320 
  321     const char* intermediate
  322         ///< [IN] Set Intermediate
  323 );
  324 
  325 //--------------------------------------------------------------------------------------------------
  326 /**
  327  * This function must be called to set the final response(s) of the AT command execution.
  328  * Several final responses can be specified separated by a '|' character into the string given in
  329  * parameter.
  330  *
  331  * @return
  332  *      - LE_FAULT when function failed
  333  *      - LE_OK when function succeed
  334  *
  335  * @note If the AT Command reference is invalid, a fatal error occurs,
  336  *       the function won't return.
  337  */
  338 //--------------------------------------------------------------------------------------------------
  339 le_result_t le_atClient_SetFinalResponse
  340 (
  341     le_atClient_CmdRef_t cmdRef,
  342         ///< [IN] AT Command
  343 
  344     const char* response
  345         ///< [IN] Set Response
  346 );
  347 
  348 //--------------------------------------------------------------------------------------------------
  349 /**
  350  * This function must be called to set the text when the prompt is expected.
  351  *
  352  * @return
  353  *      - LE_FAULT when function failed
  354  *      - LE_OK when function succeed
  355  *
  356  * @note If the AT Command reference is invalid, a fatal error occurs,
  357  *       the function won't return.
  358  */
  359 //--------------------------------------------------------------------------------------------------
  360 le_result_t le_atClient_SetText
  361 (
  362     le_atClient_CmdRef_t cmdRef,
  363         ///< [IN] AT Command
  364 
  365     const char* text
  366         ///< [IN] The AT Data to send
  367 );
  368 
  369 //--------------------------------------------------------------------------------------------------
  370 /**
  371  * This function must be called to set the timeout of the AT command execution.
  372  *
  373  * @return
  374  *      - LE_OK when function succeed
  375  *
  376  * @note If the AT Command reference is invalid, a fatal error occurs,
  377  *       the function won't return.
  378  */
  379 //--------------------------------------------------------------------------------------------------
  380 le_result_t le_atClient_SetTimeout
  381 (
  382     le_atClient_CmdRef_t cmdRef,
  383         ///< [IN] AT Command
  384 
  385     uint32_t timer
  386         ///< [IN] The timeout value in milliseconds.
  387 );
  388 
  389 //--------------------------------------------------------------------------------------------------
  390 /**
  391  * This function must be called to set the device where the AT command will be sent.
  392  *
  393  * @return
  394  *      - LE_FAULT when function failed
  395  *      - LE_OK when function succeed
  396  *
  397  * @note If the AT Command reference is invalid, a fatal error occurs,
  398  *       the function won't return.
  399  */
  400 //--------------------------------------------------------------------------------------------------
  401 le_result_t le_atClient_SetDevice
  402 (
  403     le_atClient_CmdRef_t cmdRef,
  404         ///< [IN] AT Command
  405 
  406     le_atClient_DeviceRef_t devRef
  407         ///< [IN] Device where the AT command has to be sent
  408 );
  409 
  410 //--------------------------------------------------------------------------------------------------
  411 /**
  412  * This function must be called to send an AT Command and wait for response.
  413  *
  414  * @return
  415  *      - LE_FAULT when function failed
  416  *      - LE_TIMEOUT when a timeout occur
  417  *      - LE_OK when function succeed
  418  *
  419  * @note If the AT Command reference is invalid, a fatal error occurs,
  420  *       the function won't return.
  421  */
  422 //--------------------------------------------------------------------------------------------------
  423 le_result_t le_atClient_Send
  424 (
  425     le_atClient_CmdRef_t cmdRef
  426         ///< [IN] AT Command
  427 );
  428 
  429 //--------------------------------------------------------------------------------------------------
  430 /**
  431  * This function is used to get the first intermediate response.
  432  *
  433  * @return
  434  *      - LE_FAULT when function failed
  435  *      - LE_OK when function succeed
  436  *
  437  * @note If the AT Command reference is invalid, a fatal error occurs,
  438  *       the function won't return.
  439 */
  440 //--------------------------------------------------------------------------------------------------
  441 le_result_t le_atClient_GetFirstIntermediateResponse
  442 (
  443     le_atClient_CmdRef_t cmdRef,
  444         ///< [IN] AT Command
  445 
  446     char* intermediateRsp,
  447         ///< [OUT] First intermediate result code
  448 
  449     size_t intermediateRspNumElements
  450         ///< [IN]
  451 );
  452 
  453 //--------------------------------------------------------------------------------------------------
  454 /**
  455  * This function is used to get the next intermediate response.
  456  *
  457  * @return
  458  *      - LE_NOT_FOUND when there are no further results
  459  *      - LE_OK when function succeed
  460  *
  461  * @note If the AT Command reference is invalid, a fatal error occurs,
  462  *       the function won't return.
  463  */
  464 //--------------------------------------------------------------------------------------------------
  465 le_result_t le_atClient_GetNextIntermediateResponse
  466 (
  467     le_atClient_CmdRef_t cmdRef,
  468         ///< [IN] AT Command
  469 
  470     char* intermediateRsp,
  471         ///< [OUT] Get Next intermediate result
  472         ///<       code.
  473 
  474     size_t intermediateRspNumElements
  475         ///< [IN]
  476 );
  477 
  478 //--------------------------------------------------------------------------------------------------
  479 /**
  480  * This function is used to get the final response
  481  *
  482  * @return
  483  *      - LE_FAULT when function failed
  484  *      - LE_OK when function succeed
  485  *
  486  * @note If the AT Command reference is invalid, a fatal error occurs,
  487  *       the function won't return.
  488  */
  489 //--------------------------------------------------------------------------------------------------
  490 le_result_t le_atClient_GetFinalResponse
  491 (
  492     le_atClient_CmdRef_t cmdRef,
  493         ///< [IN] AT Command
  494 
  495     char* finalRsp,
  496         ///< [OUT] Get Final Line
  497 
  498     size_t finalRspNumElements
  499         ///< [IN]
  500 );
  501 
  502 //--------------------------------------------------------------------------------------------------
  503 /**
  504  * This function must be called to automatically set and send an AT Command.
  505  *
  506  * @return
  507  *      - LE_FAULT when function failed
  508  *      - LE_TIMEOUT when a timeout occur
  509  *      - LE_OK when function succeed
  510  *
  511  * @note This command creates a command reference when called
  512  *
  513  * @note In case of an Error the command reference will be deleted and though
  514  *       not usable. Make sure to test the return code and not use the reference
  515  *       in other functions.
  516  *
  517  * @note If the AT command is invalid, a fatal error occurs,
  518  *        the function won't return.
  519  *
  520  */
  521 //--------------------------------------------------------------------------------------------------
  522 le_result_t le_atClient_SetCommandAndSend
  523 (
  524     le_atClient_CmdRef_t* cmdRefPtr,
  525         ///< [OUT] Cmd reference
  526 
  527     le_atClient_DeviceRef_t devRef,
  528         ///< [IN] Dev reference
  529 
  530     const char* command,
  531         ///< [IN] AT Command
  532 
  533     const char* interResp,
  534         ///< [IN] Expected intermediate response
  535 
  536     const char* finalResp,
  537         ///< [IN] Expected final response
  538 
  539     uint32_t timeout
  540         ///< [IN] Timeout value in milliseconds.
  541 );
  542 
  543 //--------------------------------------------------------------------------------------------------
  544 /**
  545  * Add handler function for EVENT 'le_atClient_UnsolicitedResponse'
  546  *
  547  * This event provides information on a subscribed unsolicited response when this unsolicited
  548  * response is received.
  549  */
  550 //--------------------------------------------------------------------------------------------------
  551 le_atClient_UnsolicitedResponseHandlerRef_t le_atClient_AddUnsolicitedResponseHandler
  552 (
  553     const char* unsolRsp,
  554         ///< [IN] Pattern to match
  555 
  556     le_atClient_DeviceRef_t devRef,
  557         ///< [IN] Device to listen
  558 
  559     le_atClient_UnsolicitedResponseHandlerFunc_t handlerPtr,
  560         ///< [IN]
  561 
  562     void* contextPtr,
  563         ///< [IN]
  564 
  565     uint32_t lineCount
  566         ///< [IN] Indicate the number of line of
  567         ///<      the unsolicited
  568 );
  569 
  570 //--------------------------------------------------------------------------------------------------
  571 /**
  572  * Remove handler function for EVENT 'le_atClient_UnsolicitedResponse'
  573  */
  574 //--------------------------------------------------------------------------------------------------
  575 void le_atClient_RemoveUnsolicitedResponseHandler
  576 (
  577     le_atClient_UnsolicitedResponseHandlerRef_t addHandlerRef
  578         ///< [IN]
  579 );
  580 
  581 
  582 #endif // LE_ATCLIENT_INTERFACE_H_INCLUDE_GUARD
  583 
le_atClient_UnsolicitedResponseHandlerRef_t
struct le_atClient_UnsolicitedResponseHandler * le_atClient_UnsolicitedResponseHandlerRef_t
Definition: le_atClient_interface.h:206
le_atClient_SetIntermediateResponse
le_result_t le_atClient_SetIntermediateResponse(le_atClient_CmdRef_t cmdRef, const char *intermediate)
le_atClient_SetCommand
le_result_t le_atClient_SetCommand(le_atClient_CmdRef_t cmdRef, const char *command)
le_result_t
le_result_t
Definition: le_basics.h:35
le_atDefs_interface.h
le_atClient_SetText
le_result_t le_atClient_SetText(le_atClient_CmdRef_t cmdRef, const char *text)
le_atClient_SetCommandAndSend
le_result_t le_atClient_SetCommandAndSend(le_atClient_CmdRef_t *cmdRefPtr, le_atClient_DeviceRef_t devRef, const char *command, const char *interResp, const char *finalResp, uint32_t timeout)
le_atClient_Create
le_atClient_CmdRef_t le_atClient_Create(void)
le_atClient_Start
le_atClient_DeviceRef_t le_atClient_Start(int fd)
le_atClient_Delete
le_result_t le_atClient_Delete(le_atClient_CmdRef_t cmdRef)
le_atClient_AddUnsolicitedResponseHandler
le_atClient_UnsolicitedResponseHandlerRef_t le_atClient_AddUnsolicitedResponseHandler(const char *unsolRsp, le_atClient_DeviceRef_t devRef, le_atClient_UnsolicitedResponseHandlerFunc_t handlerPtr, void *contextPtr, uint32_t lineCount)
le_atClient_Stop
le_result_t le_atClient_Stop(le_atClient_DeviceRef_t device)
le_atClient_UnsolicitedResponseHandlerFunc_t
void(* le_atClient_UnsolicitedResponseHandlerFunc_t)(const char *unsolicitedRsp, void *contextPtr)
Definition: le_atClient_interface.h:220
le_atClient_Send
le_result_t le_atClient_Send(le_atClient_CmdRef_t cmdRef)
le_atClient_GetFirstIntermediateResponse
le_result_t le_atClient_GetFirstIntermediateResponse(le_atClient_CmdRef_t cmdRef, char *intermediateRsp, size_t intermediateRspNumElements)
le_atClient_GetFinalResponse
le_result_t le_atClient_GetFinalResponse(le_atClient_CmdRef_t cmdRef, char *finalRsp, size_t finalRspNumElements)
le_atClient_SetTimeout
le_result_t le_atClient_SetTimeout(le_atClient_CmdRef_t cmdRef, uint32_t timer)
le_atClient_DisconnectService
void le_atClient_DisconnectService(void)
legato.h
le_atClient_SetFinalResponse
le_result_t le_atClient_SetFinalResponse(le_atClient_CmdRef_t cmdRef, const char *response)
le_atClient_RemoveUnsolicitedResponseHandler
void le_atClient_RemoveUnsolicitedResponseHandler(le_atClient_UnsolicitedResponseHandlerRef_t addHandlerRef)
le_atClient_ConnectService
void le_atClient_ConnectService(void)
le_atClient_GetNextIntermediateResponse
le_result_t le_atClient_GetNextIntermediateResponse(le_atClient_CmdRef_t cmdRef, char *intermediateRsp, size_t intermediateRspNumElements)
le_atClient_TryConnectService
le_result_t le_atClient_TryConnectService(void)
le_atClient_SetDevice
le_result_t le_atClient_SetDevice(le_atClient_CmdRef_t cmdRef, le_atClient_DeviceRef_t devRef)