le_atServer_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_atServer AT Commands Server
   14  *
   15  * @ref le_atServer_interface.h "API Reference"
   16  *
   17  * The AT commands Server handles AT commands' subscriptions on a requested serial device. The
   18  * server is compliant with 3GPP 27.007, paragraphs 4.0, 4.1 and 4.2, and V25 ter, paragraphs 5.3,
   19  * 5.4.
   20  *
   21  * @section le_atServer_binding IPC interfaces binding
   22  *
   23  * All the functions of this API are provided by the @b atService.
   24  *
   25  * Here's a code sample binding to the AT commands server:
   26  * @verbatim
   27    bindings:
   28    {
   29      atServerTest.atServerTestComp.le_atServer -> atService.le_atServer
   30    }
   31    @endverbatim
   32  *
   33  * @section atServer_syntax AT command syntax
   34  *
   35  * @subsection atServer_Syntax Syntax rules
   36  *
   37  * To be interpreted, the command line sent to the AT commands server must start by the pattern
   38  * "AT" (mean ATtention command).<br>
   39  * Lowercase characters are changed to their uppercase equivalents. Only characters between quotes
   40  * are not replaced.
   41  *
   42  * The supported command formats are:
   43  * - Basic syntax command:
   44  *      - using the format AT<command>[<number>]<br>
   45  * The command name is composed of one or several of those characters: A to Z, & and \\.
   46  *      - the syntax of S command is also supported, like:
   47  *          - ATS<parameter_number>?
   48  *          - ATS<parameter_number>=<value>
   49  *      - D command is supported. The characters which don't belong to the following list are
   50  * ignore:
   51  *              - V.250 dialing digits: 0 1 2 3 4 5 6 7 8 9 * # + A B C D
   52  *              - V.250 modifier characters: , T P ! W @
   53  *              - V.250 semicolon character: ;
   54  *              - GSM/UMTS modifier characters:
   55  *                  - I or i for CLIR supplementary service subscription
   56  * (I=invocation, i=suppression)
   57  *                  - G or g for CUG supplementary service subscription (G=invocation,
   58  * g=suppression)
   59  *                  - Direct dialing from phonebook: > (if follow by a string, it has to be put
   60  * between quote)
   61  *              .
   62  * @if 0 doxygen comment: The dot above ends the sub item, and must be kept @endif
   63  * All characters after the "D" are considered part of The D command parameter up to a semicolon or
   64  * the end of command line.
   65  * <br>
   66  * - Extended command format, with the following format:
   67  *      - action command with no parameters: AT+<name>
   68  *      - parameter command: AT+<name>=<value1>[,<value2>[,<value3>[...]]]<br>
   69  *        Values must be separated by a coma. Some values may be optional: in that case, optional
   70  *        value can be omitted in the AT command (e.g. AT+ABCD=,1).<br>
   71  *        A value is a string composed of one or several of the following characters: 0 to 9,
   72  *        A to F, H, z*, #, +, -. To set a value with other characters, the value has to be set
   73  * between quote.
   74  *      - test command (determine the supported values): AT+<name>=?
   75  *      - read command (determine the current values, or stored values): AT+<name>?
   76  *
   77  * @note '+' AT command starting character shall be replaced by other symbol, not included into
   78  * a to z, A to Z, & and \\.
   79  *
   80  * @subsection atServer_concate Concatenating commands
   81  *
   82  * Basic syntax command can be concatenated without a separator:<br>
   83  * ATE1V1S95=47S0=0
   84  *
   85  * Additional commands (extended syntax command or basic syntax command) can be added after an
   86  * extended syntax command with the insertion of a semicolon at the end of the command:<br>
   87  * AT+CMDA=<param1>,<param2>;+CMDB?;+CMDC=?<br>
   88  * AT+CMDA=<param1>,<param2>;E1V1
   89  *
   90  * Extended syntax command can be concatenated after basic syntax commands without a separator:<br>
   91  * ATE1V1+CMD=<param1>
   92  *
   93  * @section atServer_binding Device Binding
   94  *
   95  * le_atServer_Open() must be called to bind the file descriptor of the device with the AT commands
   96  * server. Note that a socket can also be bound.
   97  * Multiple devices can be bound.
   98  * A file descriptor can be unbound using le_atServer_Close().
   99  *
  100  * The server can be suspended using le_atServer_Suspend() in order to use the
  101  * opened fd for other purposes like starting a PPP service on the opened fd.
  102  * For that a fd dup needs to be done before opening a server session.
  103  * When needed, the server can be resumed using le_atServer_Resume(). Make sure
  104  * to close the fd when the application exists or you may get too many open files error.
  105  *
  106  * used before opening a server session
  107  * @section atServer_subscription Subscription
  108  *
  109  * A new AT command can be added into the parser using le_atServer_Create(), and it can be deleted
  110  * using le_atServer_Delete().
  111  * le_atServer_EnableEcho() allows the user to enable echo on a selected device.
  112  * le_atServer_DisableEcho() allows the user to disable echo on a selected device.
  113  *
  114  * @section atServer_handler Handler
  115  *
  116  * To handle the AT command, the application has to subscribe a handler using
  117  * le_atServer_AddCommandHandler(). It can be removed with le_atServer_RemoveCommandHandler().
  118  *
  119  * The called handler (le_atServer_CommandHandlerRef_t prototype) can use
  120  * le_atServer_GetCommandName() to retrieve the received AT command string.
  121  *
  122  * The device used to execute the AT command can be retrieve thanks to le_atServer_GetDevice().
  123  *
  124  * It can also call le_atServer_GetParameter() to retrieve parameters of the AT command. This
  125  * function gets the string sending through the AT command. If the parameter was sent between
  126  * quotes, the quotes are removed. This API can be used for both formats:
  127  * - In case of a basic format command, if exists, the parameter can be retrieved at the index 0.
  128  *
  129  * For S command specific format (ATS<parameter_number>=<value>), the <parameter_number> is
  130  * retrieved at the index 0, the <value> parameter at the index 1.
  131  *
  132  * - In case of an extended format command, parameters are retrieved thanks to their indexes,
  133  * starting from 0. If the parameter is missed (e.g. "AT+CMD=,1"), the getting value is an empty
  134  * string (i.e. '\0' with null length).
  135  *
  136  * The handler receives in argument the type of the AT command (of le_atServer_Type_t type).
  137  * Even if these types are specific to the extended format commands according to the standards, they
  138  * are also applicable here to basic format commands to detect commands with parameters, or read
  139  * values (e.g. ATS<parameter_number>?).
  140  *
  141  * @note If the parameter is parsed with quotes, the quotes are removed when retrieving the
  142  * parameter value using le_atServer_GetParameter() API. If a parmeter is not parsed with quotes,
  143  * that parameter is converted to uppercase equivalent.
  144  *
  145  * @section atServer_responses Responses
  146  *
  147  * @subsection intermediateRsp Intermediate response
  148  *
  149  * The application has can send intermediate responses through
  150  * le_atServer_SendIntermediateResponse().
  151  *
  152  * @subsection finalResultCode Final result code
  153  *
  154  * The application must return a final result code using le_atServer_SendFinalResultCode().
  155  * The corresponding device will be locked until the final response is sent.
  156  *
  157  * If no answer is sent, the device will not accept any new AT commands (an error will be
  158  * returned).
  159  *
  160  * le_atServer_SendFinalResultCode() takes as arguments the AT command reference, a pattern (which
  161  * is the prefix of the final response), a final response type as defined in
  162  * @ref le_atServer_FinalRsp_t and an error code identifier.
  163  *
  164  * The final response type permits to the AT command Server to continue or stop the parsing of
  165  * concatenated commands: if one command is failed, next commands are not executed, the final result
  166  * of the concatenated AT command is the last error.
  167  *
  168  * @subsection finalRsp Final response
  169  *
  170  * @deprecated le_atServer_SendFinalResponse() should not be used anymore and will be removed soon.
  171  * It has been replaced by le_atServer_SendFinalResultCode().
  172  *
  173  * In all cases, the application must send a final response using
  174  * le_atServer_SendFinalResponse(). The corresponding device will be locked until the final response
  175  * is sent.
  176  *
  177  * If no answer is sent, the device will not accept any new AT commands (an error will be
  178  * returned).
  179  *
  180  * le_atServer_SendFinalResponse() has to inform of the result thanks to the argument of
  181  * le_atServer_FinalRsp_t type. This argument permits to the AT command Server to:
  182  * - create the result string if no custom string is provided
  183  * - continue or stop the parsing of concatenated commands: if one command is failed, next commands
  184  * are not executed, the final result of the concatenated AT command is the last error.
  185  *
  186  * @subsection unsolicitedRsp Unsolicited response
  187  *
  188  * The application can also send unsolicited responses to warn a host
  189  * application using le_atServer_SendUnsolicitedResponse().
  190  *
  191  * This response is sent when no AT command is being processing on the device (i.e. unsolicited
  192  * response is sent between the latest final response and the next reception of an AT command).
  193  *
  194  * If an unsolicited response is sent when an AT command is in progress, the unsolicited response
  195  * is buffered and sent as soon as the device becomes available (i.e., the processing AT command
  196  * sends its final response).
  197  *
  198  * @section atServer_errors Error codes
  199  *
  200  * le_atServer_EnableExtendedErrorCodes() allows the user to use extended error codes on a selected
  201  * device. When this mode is enabled, numerical codes are displayed when an error occurs.
  202  * le_atServer_EnableVerboseErrorCodes() allows the user to enable verbose error codes on a selected
  203  * device. Thus, instead of numerical codes, error are actually displayed as verbose messages.
  204  * le_atServer_DisableExtendedErrorCodes() allows the user to disable the current error mode namely
  205  * extended error codes or verbose error codes on a selected device.
  206  *
  207  * User can create custom error codes using le_atServer_CreateErrorCode() by providing an error
  208  * code identifier and a specific pattern. The pattern is a prefix of the final response string.
  209  * Standard error codes use the patterns "+CME ERROR: " and "+CMS ERROR: " for instance. These
  210  * standard patterns are defined in the following macros: CME_ERROR and CMS_ERROR.
  211  * The code identifier should be equal or higher than 512 as the range [0, 511] is reserved for
  212  * standard error codes defined in 3GPP 27.007 9.2 and TS 127.005 3.2.5.
  213  *
  214  * le_atServer_CreateErrorCode() returns a reference which can be used to attach a custom verbose
  215  * message to the error codes by calling le_atServer_SetVerboseErrorCode().
  216  * le_atServer_DeleteErrorCode() allows the user to drop an already registered error code.
  217  *
  218  * @section Text
  219  *
  220  * le_atServer_GetTextAsync() allows the user to register a le_atServer_GetTextCallback_t callback
  221  * to retrieve text and sends a prompt <CR><LF><greater_than><SPACE> on the current command's
  222  * device.
  223  *
  224  * It will receive at max LE_ATDEFS_TEXT_MAX_LEN bytes.
  225  * If Esc Key is hit then the command is canceled and an empty buffer is returned with result
  226  * set to LE_OK.
  227  * If Ctrl+z is hit then the received buffer is returned and the result is set to LE_OK.
  228  * In case of a read error, an empty buffer is returned with result set to LE_IO_ERROR;
  229  *
  230  * Example:
  231  *
  232  * AT+CMGS="+85291234567"
  233  * > <ESC>
  234  *
  235  * OK
  236  *
  237  * AT+CMGS="+85291234567"
  238  * > It is easy to send text messages. <CTRL-Z>
  239  * +CMGS: 5
  240  *
  241  * OK
  242  *
  243  * @section atServer_bridge Bridge
  244  *
  245  * A second file descriptor can be used thanks to le_atServer_OpenBridge() to send
  246  * all unknown AT commands to an alternative device (such as the modem). For all devices linked to
  247  * that bridge using le_atServer_AddDeviceToBridge(), unknown commands will be sent through that
  248  * file descriptor.
  249  *
  250  * The bridge only works with AT commands that have the following terminal responses:
  251  * - "OK"
  252  * - "NO CARRIER"
  253  * - "NO DIALTONE"
  254  * - "BUSY"
  255  * - "NO ANSWSER"
  256  * - "ERROR"
  257  * - "+CME ERROR"
  258  * - "+CMS ERROR"
  259  *
  260  * AT commands executed through the bridge do not support text mode (e.g.; +CMGS) or data mode
  261  * (e.g.; ATD*99***1#). Sending these commands through the bridge may lock the Legato AT commands
  262  * parser.
  263  *
  264  * @image html atCommandsParserBridge.png
  265  *
  266  * @note AT commands server is opened on the file descriptor fd1 using le_atServer_Open() API.
  267  * AT commands server is bridged on the file descriptor fd2 using le_atServer_OpenBridge() API.
  268  *
  269  * A device can be remove from a bridge thanks to le_atServer_RemoveDeviceFromBridge() API.
  270  * A bridge can be closed using le_atServer_CloseBridge() API.
  271  *
  272  * @warning Some modem AT commands may conflict with Legato APIs; using both may cause problems that
  273  * can be difficult to diagnose. The modem AT commands should be avoided whenever possible, and
  274  * should only be used with great care.
  275  *
  276  * The application can send an unsolicited on all opened device, or only one on a dedicated device.
  277  *
  278  *
  279  * Copyright (C) Sierra Wireless Inc.
  280  */
  281 /**
  282  * @file le_atServer_interface.h
  283  *
  284  * Legato @ref c_atServer include file.
  285  *
  286  * Copyright (C) Sierra Wireless Inc.
  287  */
  288 
  289 #ifndef LE_ATSERVER_INTERFACE_H_INCLUDE_GUARD
  290 #define LE_ATSERVER_INTERFACE_H_INCLUDE_GUARD
  291 
  292 
  293 #include "legato.h"
  294 
  295 // Interface specific includes
  296 #include "le_atDefs_interface.h"
  297 
  298 
  299 //--------------------------------------------------------------------------------------------------
  300 /**
  301  * Type for handler called when a server disconnects.
  302  */
  303 //--------------------------------------------------------------------------------------------------
  304 typedef void (*le_atServer_DisconnectHandler_t)(void *);
  305 
  306 //--------------------------------------------------------------------------------------------------
  307 /**
  308  *
  309  * Connect the current client thread to the service providing this API. Block until the service is
  310  * available.
  311  *
  312  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  313  * called before any other functions in this API.  Normally, ConnectService is automatically called
  314  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  315  *
  316  * This function is created automatically.
  317  */
  318 //--------------------------------------------------------------------------------------------------
  319 void le_atServer_ConnectService
  320 (
  321     void
  322 );
  323 
  324 //--------------------------------------------------------------------------------------------------
  325 /**
  326  *
  327  * Try to connect the current client thread to the service providing this API. Return with an error
  328  * if the service is not available.
  329  *
  330  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  331  * called before any other functions in this API.  Normally, ConnectService is automatically called
  332  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  333  *
  334  * This function is created automatically.
  335  *
  336  * @return
  337  *  - LE_OK if the client connected successfully to the service.
  338  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  339  *    bound.
  340  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  341  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  342  */
  343 //--------------------------------------------------------------------------------------------------
  344 le_result_t le_atServer_TryConnectService
  345 (
  346     void
  347 );
  348 
  349 //--------------------------------------------------------------------------------------------------
  350 /**
  351  * Set handler called when server disconnection is detected.
  352  *
  353  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  354  * to continue without exiting, it should call longjmp() from inside the handler.
  355  */
  356 //--------------------------------------------------------------------------------------------------
  357 void le_atServer_SetServerDisconnectHandler
  358 (
  359     le_atServer_DisconnectHandler_t disconnectHandler,
  360     void *contextPtr
  361 );
  362 
  363 //--------------------------------------------------------------------------------------------------
  364 /**
  365  *
  366  * Disconnect the current client thread from the service providing this API.
  367  *
  368  * Normally, this function doesn't need to be called. After this function is called, there's no
  369  * longer a connection to the service, and the functions in this API can't be used. For details, see
  370  * @ref apiFilesC_client.
  371  *
  372  * This function is created automatically.
  373  */
  374 //--------------------------------------------------------------------------------------------------
  375 void le_atServer_DisconnectService
  376 (
  377     void
  378 );
  379 
  380 
  381 //--------------------------------------------------------------------------------------------------
  382 /**
  383  *  Maximum text length.
  384  */
  385 //--------------------------------------------------------------------------------------------------
  386 #define LE_ATSERVER_TEXT_MAX_LEN 4096
  387 
  388 //--------------------------------------------------------------------------------------------------
  389 /**
  390  *  CME error pattern
  391  */
  392 //--------------------------------------------------------------------------------------------------
  393 #define LE_ATSERVER_CME_ERROR "+CME ERROR: "
  394 
  395 //--------------------------------------------------------------------------------------------------
  396 /**
  397  *  CMS error pattern
  398  */
  399 //--------------------------------------------------------------------------------------------------
  400 #define LE_ATSERVER_CMS_ERROR "+CMS ERROR: "
  401 
  402 //--------------------------------------------------------------------------------------------------
  403 /**
  404  *  Reference type for an AT command.
  405  */
  406 //--------------------------------------------------------------------------------------------------
  407 typedef struct le_atServer_Cmd* le_atServer_CmdRef_t;
  408 
  409 
  410 //--------------------------------------------------------------------------------------------------
  411 /**
  412  *  Reference type for a AT command device.
  413  */
  414 //--------------------------------------------------------------------------------------------------
  415 typedef struct le_atServer_Device* le_atServer_DeviceRef_t;
  416 
  417 
  418 //--------------------------------------------------------------------------------------------------
  419 /**
  420  *  Reference type for a AT commands server / AT commands client bridge.
  421  */
  422 //--------------------------------------------------------------------------------------------------
  423 typedef struct le_atServer_Bridge* le_atServer_BridgeRef_t;
  424 
  425 
  426 //--------------------------------------------------------------------------------------------------
  427 /**
  428  *  Reference type for an error code.
  429  */
  430 //--------------------------------------------------------------------------------------------------
  431 typedef struct le_atServer_ErrorCode* le_atServer_ErrorCodeRef_t;
  432 
  433 
  434 //--------------------------------------------------------------------------------------------------
  435 /**
  436  * Received AT command type.
  437  *
  438  */
  439 //--------------------------------------------------------------------------------------------------
  440 typedef enum
  441 {
  442     LE_ATSERVER_TYPE_ACT = 0,
  443         ///< Action AT command (e.g. 'AT+CMD')
  444     LE_ATSERVER_TYPE_PARA = 1,
  445         ///< AT command received with parameters (e.g. 'AT+CMD=x,y')
  446     LE_ATSERVER_TYPE_TEST = 2,
  447         ///< Test AT command (e.g. 'AT+CMD=?')
  448     LE_ATSERVER_TYPE_READ = 3
  449         ///< Read AT command (e.g. 'AT+CMD?')
  450 }
  451 le_atServer_Type_t;
  452 
  453 
  454 //--------------------------------------------------------------------------------------------------
  455 /**
  456  * Final response.
  457  */
  458 //--------------------------------------------------------------------------------------------------
  459 typedef enum
  460 {
  461     LE_ATSERVER_OK = 0,
  462         ///< AT command successfully treated
  463     LE_ATSERVER_NO_CARRIER = 1,
  464         ///< Connection terminated
  465     LE_ATSERVER_ERROR = 2,
  466         ///< Error in AT command treatement
  467     LE_ATSERVER_NO_DIALTONE = 3,
  468         ///< No dialtone detected
  469     LE_ATSERVER_BUSY = 4
  470         ///< Busy signal detected
  471 }
  472 le_atServer_FinalRsp_t;
  473 
  474 
  475 //--------------------------------------------------------------------------------------------------
  476 /**
  477  * Device availability.
  478  */
  479 //--------------------------------------------------------------------------------------------------
  480 typedef enum
  481 {
  482     LE_ATSERVER_ALL_DEVICES = 0,
  483         ///< action will be done on all bound devices
  484     LE_ATSERVER_SPECIFIC_DEVICE = 1
  485         ///< action will be done on a specified device
  486 }
  487 le_atServer_AvailableDevice_t;
  488 
  489 
  490 //--------------------------------------------------------------------------------------------------
  491 /**
  492  * Reference type used by Add/Remove functions for EVENT 'le_atServer_Command'
  493  */
  494 //--------------------------------------------------------------------------------------------------
  495 typedef struct le_atServer_CommandHandler* le_atServer_CommandHandlerRef_t;
  496 
  497 
  498 //--------------------------------------------------------------------------------------------------
  499 /**
  500  * Handler for the AT command processing.
  501  *
  502  * @note The argument "parametersNumber" is set only when "type" parameter value is
  503  * LE_AT_SERVER_TYPE_PARA
  504  */
  505 //--------------------------------------------------------------------------------------------------
  506 typedef void (*le_atServer_CommandHandlerFunc_t)
  507 (
  508     le_atServer_CmdRef_t commandRef,
  509         ///< Received AT command reference
  510     le_atServer_Type_t type,
  511         ///< Received AT command type
  512     uint32_t parametersNumber,
  513         ///< Parameters number
  514     void* contextPtr
  515         ///<
  516 );
  517 
  518 //--------------------------------------------------------------------------------------------------
  519 /**
  520  * Get text callback
  521  *
  522  * @return
  523  *      - LE_OK: The function succeeded
  524  *      - LE_IO_ERROR: An io error happened and the function couldn't read from the device
  525  *      - LE_FORMAT_ERROR: Received an invalid character or an invalid sequence
  526  *      - LE_FAULT: Failed to remove backspaces
  527  */
  528 //--------------------------------------------------------------------------------------------------
  529 typedef void (*le_atServer_GetTextCallbackFunc_t)
  530 (
  531     le_atServer_CmdRef_t cmdRef,
  532         ///< Received AT command reference
  533     le_result_t result,
  534         ///< Result
  535     const char* LE_NONNULL text,
  536         ///< Received text
  537     uint32_t len,
  538         ///< Text length
  539     void* contextPtr
  540         ///<
  541 );
  542 
  543 //--------------------------------------------------------------------------------------------------
  544 /**
  545  * Suspend server / enter data mode
  546  *
  547  * When this function is called the server stops monitoring the fd for events
  548  * hence no more I/O operations are done on the fd by the server.
  549  *
  550  * @return
  551  *      - LE_OK             Success.
  552  *      - LE_BAD_PARAMETER  Invalid device reference.
  553  *      - LE_FAULT          Device not monitored
  554  *
  555  */
  556 //--------------------------------------------------------------------------------------------------
  557 le_result_t le_atServer_Suspend
  558 (
  559     le_atServer_DeviceRef_t device
  560         ///< [IN] device to be suspended
  561 );
  562 
  563 //--------------------------------------------------------------------------------------------------
  564 /**
  565  * Resume server / enter command mode
  566  *
  567  * When this function is called the server resumes monitoring the fd for events
  568  * and is able to interpret AT commands again.
  569  *
  570  * @return
  571  *      - LE_OK             Success.
  572  *      - LE_BAD_PARAMETER  Invalid device reference.
  573  *      - LE_FAULT          Device not monitored
  574  *
  575  */
  576 //--------------------------------------------------------------------------------------------------
  577 le_result_t le_atServer_Resume
  578 (
  579     le_atServer_DeviceRef_t device
  580         ///< [IN] device to be resumed
  581 );
  582 
  583 //--------------------------------------------------------------------------------------------------
  584 /**
  585  * This function opens an AT server session on the requested device.
  586  *
  587  * @return
  588  *      - Reference to the requested device.
  589  *      - NULL if the device is not available or fd is a BAD FILE DESCRIPTOR.
  590  *
  591  * @note Make sure to duplicate (man dup) your file descriptor before opening
  592  *       a server session to be able to use the suspend/resume feature
  593  *
  594  */
  595 //--------------------------------------------------------------------------------------------------
  596 le_atServer_DeviceRef_t le_atServer_Open
  597 (
  598     int fd
  599         ///< [IN] File descriptor.
  600 );
  601 
  602 //--------------------------------------------------------------------------------------------------
  603 /**
  604  * This function closes the AT server session on the requested device.
  605  *
  606  * @return
  607  *      - LE_OK             The function succeeded.
  608  *      - LE_BAD_PARAMETER  Invalid device reference.
  609  *      - LE_BUSY           The requested device is busy.
  610  *      - LE_FAULT          Failed to stop the server, check logs
  611  *                              for more information.
  612  */
  613 //--------------------------------------------------------------------------------------------------
  614 le_result_t le_atServer_Close
  615 (
  616     le_atServer_DeviceRef_t device
  617         ///< [IN] device to be unbound
  618 );
  619 
  620 //--------------------------------------------------------------------------------------------------
  621 /**
  622  * This function created an AT command and register it into the AT parser.
  623  *
  624  * @return
  625  *      - Reference to the AT command.
  626  *      - NULL if an error occurs.
  627  */
  628 //--------------------------------------------------------------------------------------------------
  629 le_atServer_CmdRef_t le_atServer_Create
  630 (
  631     const char* LE_NONNULL name
  632         ///< [IN] AT command name string
  633 );
  634 
  635 //--------------------------------------------------------------------------------------------------
  636 /**
  637  * This function deletes an AT command (i.e. unregister from the AT parser).
  638  *
  639  * @return
  640  *      - LE_OK            The function succeeded.
  641  *      - LE_FAULT         The function failed to delete the command.
  642  *      - LE_BUSY          Command is in progress.
  643  *
  644  */
  645 //--------------------------------------------------------------------------------------------------
  646 le_result_t le_atServer_Delete
  647 (
  648     le_atServer_CmdRef_t commandRef
  649         ///< [IN] AT command reference
  650 );
  651 
  652 //--------------------------------------------------------------------------------------------------
  653 /**
  654  * Add handler function for EVENT 'le_atServer_Command'
  655  *
  656  * This event provides information when the AT command is detected.
  657  *
  658  */
  659 //--------------------------------------------------------------------------------------------------
  660 le_atServer_CommandHandlerRef_t le_atServer_AddCommandHandler
  661 (
  662     le_atServer_CmdRef_t commandRef,
  663         ///< [IN] AT command reference
  664     le_atServer_CommandHandlerFunc_t handlerPtr,
  665         ///< [IN] Handler to called when the AT command is detected
  666     void* contextPtr
  667         ///< [IN]
  668 );
  669 
  670 //--------------------------------------------------------------------------------------------------
  671 /**
  672  * Remove handler function for EVENT 'le_atServer_Command'
  673  */
  674 //--------------------------------------------------------------------------------------------------
  675 void le_atServer_RemoveCommandHandler
  676 (
  677     le_atServer_CommandHandlerRef_t handlerRef
  678         ///< [IN]
  679 );
  680 
  681 //--------------------------------------------------------------------------------------------------
  682 /**
  683  * This function can be used to get the parameters of a received AT command.
  684  *
  685  * @return
  686  *      - LE_OK            The function succeeded.
  687  *      - LE_FAULT         The function failed to get the requested parameter.
  688  *
  689  * @note If the parameter is parsed with quotes, the quotes are removed when retrieving the
  690  * parameter value using this API. If a parmeter is not parsed with quotes, that parameter is
  691  * converted to uppercase equivalent.
  692  *
  693  */
  694 //--------------------------------------------------------------------------------------------------
  695 le_result_t le_atServer_GetParameter
  696 (
  697     le_atServer_CmdRef_t commandRef,
  698         ///< [IN] AT command reference
  699     uint32_t index,
  700         ///< [IN] agument index
  701     char* parameter,
  702         ///< [OUT] parameter value
  703     size_t parameterSize
  704         ///< [IN]
  705 );
  706 
  707 //--------------------------------------------------------------------------------------------------
  708 /**
  709  * This function can be used to get the AT command string.
  710  *
  711  * @return
  712  *      - LE_OK            The function succeeded.
  713  *      - LE_FAULT         The function failed to get the AT command string.
  714  *
  715  */
  716 //--------------------------------------------------------------------------------------------------
  717 le_result_t le_atServer_GetCommandName
  718 (
  719     le_atServer_CmdRef_t commandRef,
  720         ///< [IN] AT command reference
  721     char* name,
  722         ///< [OUT] AT command string
  723     size_t nameSize
  724         ///< [IN]
  725 );
  726 
  727 //--------------------------------------------------------------------------------------------------
  728 /**
  729  * This function can be used to get the device reference in use for an AT command specified with
  730  * its reference.
  731  *
  732  * @return
  733  *      - LE_OK            The function succeeded.
  734  *      - LE_FAULT         The function failed to get the AT command string.
  735  *
  736  */
  737 //--------------------------------------------------------------------------------------------------
  738 le_result_t le_atServer_GetDevice
  739 (
  740     le_atServer_CmdRef_t commandRef,
  741         ///< [IN] AT command reference
  742     le_atServer_DeviceRef_t* deviceRefPtr
  743         ///< [OUT] Device reference
  744 );
  745 
  746 //--------------------------------------------------------------------------------------------------
  747 /**
  748  * This function can be used to send an intermediate response.
  749  *
  750  * @return
  751  *      - LE_OK            The function succeeded.
  752  *      - LE_FAULT         The function failed to send the intermediate response.
  753  *
  754  */
  755 //--------------------------------------------------------------------------------------------------
  756 le_result_t le_atServer_SendIntermediateResponse
  757 (
  758     le_atServer_CmdRef_t commandRef,
  759         ///< [IN] AT command reference
  760     const char* LE_NONNULL intermediateRsp
  761         ///< [IN] Intermediate response to be
  762         ///< sent
  763 );
  764 
  765 //--------------------------------------------------------------------------------------------------
  766 /**
  767  * This function can be used to send the final response.
  768  *
  769  * @deprecated le_atServer_SendFinalResponse() should not be used anymore and will be removed soon.
  770  * It has been replaced by le_atServer_SendFinalResultCode()
  771  *
  772  * @return
  773  *      - LE_OK            The function succeeded.
  774  *      - LE_FAULT         The function failed to send the final response.
  775  *
  776  */
  777 //--------------------------------------------------------------------------------------------------
  778 le_result_t le_atServer_SendFinalResponse
  779 (
  780     le_atServer_CmdRef_t commandRef,
  781         ///< [IN] AT command reference
  782     le_atServer_FinalRsp_t finalResponse,
  783         ///< [IN] Final response to be sent
  784     bool customStringAvailable,
  785         ///< [IN] Custom final response has to be sent
  786         ///< instead of the default one.
  787     const char* LE_NONNULL finalRsp
  788         ///< [IN] custom final response string
  789 );
  790 
  791 //--------------------------------------------------------------------------------------------------
  792 /**
  793  * This function can be used to send the final result code.
  794  *
  795  * @return
  796  *      - LE_OK            The function succeeded.
  797  *      - LE_FAULT         The function failed to send the final result code.
  798  *
  799  */
  800 //--------------------------------------------------------------------------------------------------
  801 le_result_t le_atServer_SendFinalResultCode
  802 (
  803     le_atServer_CmdRef_t commandRef,
  804         ///< [IN] AT command reference
  805     le_atServer_FinalRsp_t finalResult,
  806         ///< [IN] Final result code to be sent
  807     const char* LE_NONNULL pattern,
  808         ///< [IN] Prefix of the return message
  809     uint32_t errorCode
  810         ///< [IN] Numeric error code
  811 );
  812 
  813 //--------------------------------------------------------------------------------------------------
  814 /**
  815  * This function can be used to send the unsolicited response.
  816  *
  817  * @return
  818  *      - LE_OK            The function succeeded.
  819  *      - LE_FAULT         The function failed to send the unsolicited response.
  820  *
  821  */
  822 //--------------------------------------------------------------------------------------------------
  823 le_result_t le_atServer_SendUnsolicitedResponse
  824 (
  825     const char* LE_NONNULL unsolRsp,
  826         ///< [IN] Unsolicited response to be
  827         ///< sent
  828     le_atServer_AvailableDevice_t availableDevice,
  829         ///< [IN] device to send the
  830         ///< unsolicited response
  831     le_atServer_DeviceRef_t device
  832         ///< [IN] device reference where the
  833         ///< unsolicited response has to
  834         ///< be sent
  835 );
  836 
  837 //--------------------------------------------------------------------------------------------------
  838 /**
  839  * This function enables echo on the selected device.
  840  *
  841  * @return
  842  *      - LE_OK             The function succeeded.
  843  *      - LE_BAD_PARAMETER  Invalid device reference.
  844  */
  845 //--------------------------------------------------------------------------------------------------
  846 le_result_t le_atServer_EnableEcho
  847 (
  848     le_atServer_DeviceRef_t device
  849         ///< [IN] device reference
  850 );
  851 
  852 //--------------------------------------------------------------------------------------------------
  853 /**
  854  * This function disables echo on the selected device.
  855  *
  856  * @return
  857  *      - LE_OK             The function succeeded.
  858  *      - LE_BAD_PARAMETER  Invalid device reference.
  859  */
  860 //--------------------------------------------------------------------------------------------------
  861 le_result_t le_atServer_DisableEcho
  862 (
  863     le_atServer_DeviceRef_t device
  864         ///< [IN] device reference
  865 );
  866 
  867 //--------------------------------------------------------------------------------------------------
  868 /**
  869  * This function opens a AT commands server bridge.
  870  * All unknown AT commands will be sent on this alternative file descriptor thanks to the AT client
  871  * Service.
  872  *
  873  * @return
  874  *      - Reference to the requested bridge.
  875  *      - NULL if the device can't be bridged
  876  */
  877 //--------------------------------------------------------------------------------------------------
  878 le_atServer_BridgeRef_t le_atServer_OpenBridge
  879 (
  880     int fd
  881         ///< [IN] File descriptor.
  882 );
  883 
  884 //--------------------------------------------------------------------------------------------------
  885 /**
  886  * This function closes an opened bridge.
  887  *
  888  * @return
  889  *      - LE_OK            The function succeeded.
  890  *      - LE_FAULT         The function failed to close the bridge.
  891  *      - LE_BUSY          The bridge is in use (devices references have to be removed first).
  892  */
  893 //--------------------------------------------------------------------------------------------------
  894 le_result_t le_atServer_CloseBridge
  895 (
  896     le_atServer_BridgeRef_t bridgeRef
  897         ///< [IN] Bridge reference
  898 );
  899 
  900 //--------------------------------------------------------------------------------------------------
  901 /**
  902  * This function adds a device to an opened bridge.
  903  *
  904  * @return
  905  *      - LE_OK            The function succeeded.
  906  *      - LE_BUSY          The device is already used by the bridge.
  907  *      - LE_FAULT         The function failed to add the device to the bridge.
  908  */
  909 //--------------------------------------------------------------------------------------------------
  910 le_result_t le_atServer_AddDeviceToBridge
  911 (
  912     le_atServer_DeviceRef_t deviceRef,
  913         ///< [IN] Device reference to add to the bridge
  914     le_atServer_BridgeRef_t bridgeRef
  915         ///< [IN] Bridge refence
  916 );
  917 
  918 //--------------------------------------------------------------------------------------------------
  919 /**
  920  * This function removes a device from a bridge
  921  *
  922  * @return
  923  *      - LE_OK            The function succeeded.
  924  *      - LE_NOT_FOUND     The device is not isued by the specified bridge
  925  *      - LE_BUSY          The device is currently in use
  926  *      - LE_FAULT         The function failed to add the device to the bridge.
  927  */
  928 //--------------------------------------------------------------------------------------------------
  929 le_result_t le_atServer_RemoveDeviceFromBridge
  930 (
  931     le_atServer_DeviceRef_t deviceRef,
  932         ///< [IN] Device reference to add to the bridge
  933     le_atServer_BridgeRef_t bridgeRef
  934         ///< [IN] Bridge refence
  935 );
  936 
  937 //--------------------------------------------------------------------------------------------------
  938 /**
  939  * This function enables verbose error codes on the selected device.
  940  */
  941 //--------------------------------------------------------------------------------------------------
  942 void le_atServer_EnableVerboseErrorCodes
  943 (
  944     void
  945 );
  946 
  947 //--------------------------------------------------------------------------------------------------
  948 /**
  949  * This function enables extended error codes on the selected device.
  950  */
  951 //--------------------------------------------------------------------------------------------------
  952 void le_atServer_EnableExtendedErrorCodes
  953 (
  954     void
  955 );
  956 
  957 //--------------------------------------------------------------------------------------------------
  958 /**
  959  * This function disables extended error codes on the selected device.
  960  */
  961 //--------------------------------------------------------------------------------------------------
  962 void le_atServer_DisableExtendedErrorCodes
  963 (
  964     void
  965 );
  966 
  967 //--------------------------------------------------------------------------------------------------
  968 /**
  969  * This function creates a custom error code.
  970  * @return
  971  *      - ErrorCode    Reference to the created error code
  972  *      - NULL         Function failed to create the error code
  973  *
  974  * @note This function fails to create the error code if the combinaison (errorCode, pattern)
  975  * already exists or if the errorCode number is lower than 512.
  976  *
  977  */
  978 //--------------------------------------------------------------------------------------------------
  979 le_atServer_ErrorCodeRef_t le_atServer_CreateErrorCode
  980 (
  981     uint32_t errorCode,
  982         ///< [IN] Numerical error code
  983     const char* LE_NONNULL pattern
  984         ///< [IN] Prefix of the response message
  985 );
  986 
  987 //--------------------------------------------------------------------------------------------------
  988 /**
  989  * This function deletes a custom error code.
  990  *
  991  * @return
  992  *      - LE_OK            The function succeeded
  993  *      - LE_FAULT         The function failed to delete the error code
  994  */
  995 //--------------------------------------------------------------------------------------------------
  996 le_result_t le_atServer_DeleteErrorCode
  997 (
  998     le_atServer_ErrorCodeRef_t errorCodeRef
  999         ///< [IN] Error code reference
 1000 );
 1001 
 1002 //--------------------------------------------------------------------------------------------------
 1003 /**
 1004  * This function adds a verbose message to a specified error code
 1005  *
 1006  * @return
 1007  *      - LE_OK            The function succeeded
 1008  *      - LE_FAULT         The function failed to set the verbose message
 1009  */
 1010 //--------------------------------------------------------------------------------------------------
 1011 le_result_t le_atServer_SetVerboseErrorCode
 1012 (
 1013     le_atServer_ErrorCodeRef_t errorCodeRef,
 1014         ///< [IN] Error code reference
 1015     const char* LE_NONNULL verboseCode
 1016         ///< [IN] Verbose message
 1017 );
 1018 
 1019 //--------------------------------------------------------------------------------------------------
 1020 /**
 1021  * This function allows the user to register a le_atServer_GetTextCallback_t callback
 1022  * to retrieve text and sends a prompt <CR><LF><greater_than><SPACE> on the current command's
 1023  * device.
 1024  *
 1025  * @return
 1026  *      - LE_OK             The function succeeded.
 1027  *      - LE_BAD_PARAMETER  Invalid device or command reference.
 1028  */
 1029 //--------------------------------------------------------------------------------------------------
 1030 le_result_t le_atServer_GetTextAsync
 1031 (
 1032     le_atServer_CmdRef_t cmdRef,
 1033         ///< [IN] AT command reference
 1034     le_atServer_GetTextCallbackFunc_t callbackPtr,
 1035         ///< [IN] Get text callback
 1036     void* contextPtr
 1037         ///< [IN]
 1038 );
 1039 
 1040 #endif // LE_ATSERVER_INTERFACE_H_INCLUDE_GUARD
le_atServer_CommandHandlerFunc_t
void(* le_atServer_CommandHandlerFunc_t)(le_atServer_CmdRef_t commandRef, le_atServer_Type_t type, uint32_t parametersNumber, void *contextPtr)
Definition: le_atServer_interface.h:507
le_atServer_Close
le_result_t le_atServer_Close(le_atServer_DeviceRef_t device)
le_atServer_DisconnectHandler_t
void(* le_atServer_DisconnectHandler_t)(void *)
Definition: le_atServer_interface.h:304
LE_ATSERVER_TYPE_ACT
Action AT command (e.g. &#39;AT+CMD&#39;) 
Definition: le_atServer_interface.h:442
LE_ATSERVER_ERROR
Error in AT command treatement. 
Definition: le_atServer_interface.h:465
LE_ATSERVER_NO_DIALTONE
No dialtone detected. 
Definition: le_atServer_interface.h:467
le_result_t
le_result_t
Definition: le_basics.h:35
le_atServer_TryConnectService
le_result_t le_atServer_TryConnectService(void)
le_atServer_RemoveDeviceFromBridge
le_result_t le_atServer_RemoveDeviceFromBridge(le_atServer_DeviceRef_t deviceRef, le_atServer_BridgeRef_t bridgeRef)
le_atServer_EnableExtendedErrorCodes
void le_atServer_EnableExtendedErrorCodes(void)
le_atServer_GetParameter
le_result_t le_atServer_GetParameter(le_atServer_CmdRef_t commandRef, uint32_t index, char *parameter, size_t parameterSize)
LE_ATSERVER_SPECIFIC_DEVICE
action will be done on a specified device 
Definition: le_atServer_interface.h:484
le_atServer_FinalRsp_t
le_atServer_FinalRsp_t
Definition: le_atServer_interface.h:459
le_atServer_GetCommandName
le_result_t le_atServer_GetCommandName(le_atServer_CmdRef_t commandRef, char *name, size_t nameSize)
le_atServer_CommandHandlerRef_t
struct le_atServer_CommandHandler * le_atServer_CommandHandlerRef_t
Definition: le_atServer_interface.h:495
LE_ATSERVER_OK
AT command successfully treated. 
Definition: le_atServer_interface.h:461
le_atDefs_interface.h
le_atServer_GetDevice
le_result_t le_atServer_GetDevice(le_atServer_CmdRef_t commandRef, le_atServer_DeviceRef_t *deviceRefPtr)
le_atServer_SetVerboseErrorCode
le_result_t le_atServer_SetVerboseErrorCode(le_atServer_ErrorCodeRef_t errorCodeRef, const char *LE_NONNULL verboseCode)
le_atServer_EnableEcho
le_result_t le_atServer_EnableEcho(le_atServer_DeviceRef_t device)
le_atServer_AddCommandHandler
le_atServer_CommandHandlerRef_t le_atServer_AddCommandHandler(le_atServer_CmdRef_t commandRef, le_atServer_CommandHandlerFunc_t handlerPtr, void *contextPtr)
le_atServer_Open
le_atServer_DeviceRef_t le_atServer_Open(int fd)
le_atServer_Create
le_atServer_CmdRef_t le_atServer_Create(const char *LE_NONNULL name)
LE_ATSERVER_BUSY
Busy signal detected. 
Definition: le_atServer_interface.h:469
le_atServer_ConnectService
void le_atServer_ConnectService(void)
le_atServer_AddDeviceToBridge
le_result_t le_atServer_AddDeviceToBridge(le_atServer_DeviceRef_t deviceRef, le_atServer_BridgeRef_t bridgeRef)
LE_ATSERVER_ALL_DEVICES
action will be done on all bound devices 
Definition: le_atServer_interface.h:482
le_atServer_Resume
le_result_t le_atServer_Resume(le_atServer_DeviceRef_t device)
le_atServer_Delete
le_result_t le_atServer_Delete(le_atServer_CmdRef_t commandRef)
le_atServer_AvailableDevice_t
le_atServer_AvailableDevice_t
Definition: le_atServer_interface.h:480
LE_ATSERVER_NO_CARRIER
Connection terminated. 
Definition: le_atServer_interface.h:463
le_atServer_CloseBridge
le_result_t le_atServer_CloseBridge(le_atServer_BridgeRef_t bridgeRef)
le_atServer_SendFinalResponse
le_result_t le_atServer_SendFinalResponse(le_atServer_CmdRef_t commandRef, le_atServer_FinalRsp_t finalResponse, bool customStringAvailable, const char *LE_NONNULL finalRsp)
le_atServer_EnableVerboseErrorCodes
void le_atServer_EnableVerboseErrorCodes(void)
le_atServer_BridgeRef_t
struct le_atServer_Bridge * le_atServer_BridgeRef_t
Definition: le_atServer_interface.h:423
le_atServer_Type_t
le_atServer_Type_t
Definition: le_atServer_interface.h:440
legato.h
le_atServer_RemoveCommandHandler
void le_atServer_RemoveCommandHandler(le_atServer_CommandHandlerRef_t handlerRef)
le_atServer_Suspend
le_result_t le_atServer_Suspend(le_atServer_DeviceRef_t device)
LE_ATSERVER_TYPE_TEST
Test AT command (e.g. &#39;AT+CMD=?&#39;) 
Definition: le_atServer_interface.h:446
le_atServer_GetTextAsync
le_result_t le_atServer_GetTextAsync(le_atServer_CmdRef_t cmdRef, le_atServer_GetTextCallbackFunc_t callbackPtr, void *contextPtr)
le_atServer_DisableExtendedErrorCodes
void le_atServer_DisableExtendedErrorCodes(void)
le_atServer_ErrorCodeRef_t
struct le_atServer_ErrorCode * le_atServer_ErrorCodeRef_t
Definition: le_atServer_interface.h:431
le_atServer_DeviceRef_t
struct le_atServer_Device * le_atServer_DeviceRef_t
Definition: le_atServer_interface.h:415
le_atServer_SetServerDisconnectHandler
void le_atServer_SetServerDisconnectHandler(le_atServer_DisconnectHandler_t disconnectHandler, void *contextPtr)
LE_ATSERVER_TYPE_PARA
AT command received with parameters (e.g. &#39;AT+CMD=x,y&#39;) 
Definition: le_atServer_interface.h:444
le_atServer_SendIntermediateResponse
le_result_t le_atServer_SendIntermediateResponse(le_atServer_CmdRef_t commandRef, const char *LE_NONNULL intermediateRsp)
le_atServer_GetTextCallbackFunc_t
void(* le_atServer_GetTextCallbackFunc_t)(le_atServer_CmdRef_t cmdRef, le_result_t result, const char *LE_NONNULL text, uint32_t len, void *contextPtr)
Definition: le_atServer_interface.h:530
le_atServer_CreateErrorCode
le_atServer_ErrorCodeRef_t le_atServer_CreateErrorCode(uint32_t errorCode, const char *LE_NONNULL pattern)
le_atServer_DisconnectService
void le_atServer_DisconnectService(void)
le_atServer_SendUnsolicitedResponse
le_result_t le_atServer_SendUnsolicitedResponse(const char *LE_NONNULL unsolRsp, le_atServer_AvailableDevice_t availableDevice, le_atServer_DeviceRef_t device)
LE_ATSERVER_TYPE_READ
Read AT command (e.g. &#39;AT+CMD?&#39;) 
Definition: le_atServer_interface.h:448
le_atServer_DisableEcho
le_result_t le_atServer_DisableEcho(le_atServer_DeviceRef_t device)
le_atServer_SendFinalResultCode
le_result_t le_atServer_SendFinalResultCode(le_atServer_CmdRef_t commandRef, le_atServer_FinalRsp_t finalResult, const char *LE_NONNULL pattern, uint32_t errorCode)
le_atServer_OpenBridge
le_atServer_BridgeRef_t le_atServer_OpenBridge(int fd)
le_atServer_DeleteErrorCode
le_result_t le_atServer_DeleteErrorCode(le_atServer_ErrorCodeRef_t errorCodeRef)
le_atServer_CmdRef_t
struct le_atServer_Cmd * le_atServer_CmdRef_t
Definition: le_atServer_interface.h:407