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