le_atServer_interface.h

    1 /*
    2  * ====================== WARNING ======================
    3  *
    4  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    5  * DO NOT MODIFY IN ANY WAY.
    6  *
    7  * ====================== WARNING ======================
    8  */
    9 
   10 /**
   11  * @page c_atServer AT Commands Server
   12  *
   13  * @ref le_atServer_interface.h "API Reference"
   14  *
   15  * @warning Some AT commands may conflict with Legato APIs; using both may cause problems that can be
   16  * difficult to diagnose. AT commands should be avoided whenever possible, and should only be used
   17  * with great care.
   18  *
   19  * The AT Commands Server handles AT commands' subscriptions on a requested serial device. The server
   20  * is compliant with 3GPP 27.007, paragraph 4.0, 4.1 and 4.2.
   21  *
   22  * @section atServer_binding Device Binding
   23  *
   24  * le_atServer_Start() must be called to bind a specific device with the AT commands server.
   25  * Multiple devices can be bound.
   26  * A device can be unbound using le_atServer_Stop().
   27  *
   28  * @section atServer_subscription Subscription
   29  *
   30  * A new AT command can be added into the parser using le_atServer_Create(), and it can be deleted
   31  * using le_atServer_Delete().
   32  * An AT command can be available only on one dedicated device, or on all bound AT devices, using
   33  * le_atServer_SetDevice().
   34  *
   35  * @section atServer_handler Handler
   36  *
   37  * To handle the AT command, the app has to subscribe a handler using
   38  * le_atServer_AddCommandHandler(). It can be removed with le_atServer_RemoveCommandHandler().
   39  * The called handler (le_atServer_CommandHandlerRef_t prototype) can use
   40  * le_atServer_GetCommandName() to retrieve the received AT command string. It can also call
   41  * le_atServer_GetParameter() to retrieve a parameter of the AT command thanks to its index.
   42  *
   43  * @section atServer_responses Responses
   44  *
   45  * The app has can send intermediate responses through
   46  * le_atServer_SendIntermediateResponse().
   47  * In all cases, the app must send a final response using
   48  * le_atServer_SendFinalResponse(). The AT device will be locked until the final response is sent.
   49  * If no answer is sent, the AT device will not accept any new AT commands (an error will be
   50  * returned).
   51  *
   52  * The app can also send unsolicited responses to warn a host
   53  * app using le_atServer_SendUnsolicitedResponse().
   54  * This response is sent when no AT command is being processing on the device (i.e. unsolicited
   55  * response is sent between the latest final response and the next reception of an AT command).
   56  * If an unsolicited response is sent when an AT command is in progress, the unsolicited response
   57  * is buffered and sent as soon as the AT device becomes available (i.e., the processing AT command
   58  * sends its final response).
   59  *
   60  * <HR>
   61  *
   62  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   63  */
   64 /**
   65  * @file le_atServer_interface.h
   66  *
   67  * Legato @ref c_atServer include file.
   68  *
   69  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
   70  */
   71 
   72 #ifndef LE_ATSERVER_INTERFACE_H_INCLUDE_GUARD
   73 #define LE_ATSERVER_INTERFACE_H_INCLUDE_GUARD
   74 
   75 
   76 #include "legato.h"
   77 
   78 // Interface specific includes
   79 #include "le_atClient_interface.h"
   80 
   81 
   82 //--------------------------------------------------------------------------------------------------
   83 /**
   84  *
   85  * Connect the current client thread to the service providing this API. Block until the service is
   86  * available.
   87  *
   88  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   89  * called before any other functions in this API.  Normally, ConnectService is automatically called
   90  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   91  *
   92  * This function is created automatically.
   93  */
   94 //--------------------------------------------------------------------------------------------------
   95 void le_atServer_ConnectService
   96 (
   97     void
   98 );
   99 
  100 //--------------------------------------------------------------------------------------------------
  101 /**
  102  *
  103  * Try to connect the current client thread to the service providing this API. Return with an error
  104  * if the service is not available.
  105  *
  106  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  107  * called before any other functions in this API.  Normally, ConnectService is automatically called
  108  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  109  *
  110  * This function is created automatically.
  111  *
  112  * @return
  113  *  - LE_OK if the client connected successfully to the service.
  114  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
  115  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  116  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  117  */
  118 //--------------------------------------------------------------------------------------------------
  119 le_result_t le_atServer_TryConnectService
  120 (
  121     void
  122 );
  123 
  124 //--------------------------------------------------------------------------------------------------
  125 /**
  126  *
  127  * Disconnect the current client thread from the service providing this API.
  128  *
  129  * Normally, this function doesn't need to be called. After this function is called, there's no
  130  * longer a connection to the service, and the functions in this API can't be used. For details, see
  131  * @ref apiFilesC_client.
  132  *
  133  * This function is created automatically.
  134  */
  135 //--------------------------------------------------------------------------------------------------
  136 void le_atServer_DisconnectService
  137 (
  138     void
  139 );
  140 
  141 
  142 //--------------------------------------------------------------------------------------------------
  143 /**
  144  *  Reference type for an AT command.
  145  */
  146 //--------------------------------------------------------------------------------------------------
  147 typedef struct le_atServer_Cmd* le_atServer_CmdRef_t;
  148 
  149 
  150 //--------------------------------------------------------------------------------------------------
  151 /**
  152  *  Reference type for a AT command device.
  153  */
  154 //--------------------------------------------------------------------------------------------------
  155 typedef struct le_atServer_Device* le_atServer_DeviceRef_t;
  156 
  157 
  158 //--------------------------------------------------------------------------------------------------
  159 /**
  160  * Command string maximum length.
  161  */
  162 //--------------------------------------------------------------------------------------------------
  163 #define LE_ATSERVER_COMMAND_MAX_LEN 100
  164 
  165 
  166 //--------------------------------------------------------------------------------------------------
  167 /**
  168  * Command string maximum length.
  169  * One extra byte is added for the null character.
  170  */
  171 //--------------------------------------------------------------------------------------------------
  172 #define LE_ATSERVER_COMMAND_MAX_BYTES 101
  173 
  174 
  175 //--------------------------------------------------------------------------------------------------
  176 /**
  177  * Parameter string maximum length.
  178  */
  179 //--------------------------------------------------------------------------------------------------
  180 #define LE_ATSERVER_PARAMETER_MAX_LEN 20
  181 
  182 
  183 //--------------------------------------------------------------------------------------------------
  184 /**
  185  * Parameter string maximum length.
  186  * One extra byte is added for the null character.
  187  */
  188 //--------------------------------------------------------------------------------------------------
  189 #define LE_ATSERVER_PARAMETER_MAX_BYTES 21
  190 
  191 
  192 //--------------------------------------------------------------------------------------------------
  193 /**
  194  * Device name maximum length.
  195  */
  196 //--------------------------------------------------------------------------------------------------
  197 #define LE_ATSERVER_PATH_MAX_LEN 30
  198 
  199 
  200 //--------------------------------------------------------------------------------------------------
  201 /**
  202  * Device name maximum length.
  203  * One extra byte is added for the null character.
  204  */
  205 //--------------------------------------------------------------------------------------------------
  206 #define LE_ATSERVER_DEVICE_NAME_MAX_BYTES 31
  207 
  208 
  209 //--------------------------------------------------------------------------------------------------
  210 /**
  211  * AT command response maximum length.
  212  */
  213 //--------------------------------------------------------------------------------------------------
  214 #define LE_ATSERVER_RESPONSE_MAX_LEN 40
  215 
  216 
  217 //--------------------------------------------------------------------------------------------------
  218 /**
  219  * AT command response maximum length.
  220  * One extra byte is added for the null character.
  221  */
  222 //--------------------------------------------------------------------------------------------------
  223 #define LE_ATSERVER_RESPONSE_MAX_BYTES 41
  224 
  225 
  226 //--------------------------------------------------------------------------------------------------
  227 /**
  228  * Received AT command type.
  229  */
  230 //--------------------------------------------------------------------------------------------------
  231 typedef enum
  232 {
  233     LE_ATSERVER_TYPE_ACT = 0,
  234         ///< Action AT command (e.g. 'AT+CMD')
  235 
  236     LE_ATSERVER_TYPE_PARA = 1,
  237         ///< AT command received with parameters (e.g. 'AT+CMD=x,y')
  238 
  239     LE_ATSERVER_TYPE_TEST = 2,
  240         ///< Test AT command (e.g. 'AT+CMD=?')
  241 
  242     LE_ATSERVER_TYPE_READ = 3
  243         ///< Read AT command (e.g. 'AT+CMD?')
  244 }
  245 le_atServer_Type_t;
  246 
  247 
  248 //--------------------------------------------------------------------------------------------------
  249 /**
  250  * Final response.
  251  */
  252 //--------------------------------------------------------------------------------------------------
  253 typedef enum
  254 {
  255     LE_ATSERVER_OK = 0,
  256         ///< AT command successfully treated, "\r\nOK\r\n" is sent if no custom
  257         ///< response is set
  258 
  259     LE_ATSERVER_ERROR = 1
  260         ///< error in AT command treatement, "\r\nERROR\r\n" is sent if no custom
  261         ///< response is set
  262 }
  263 le_atServer_FinalRsp_t;
  264 
  265 
  266 //--------------------------------------------------------------------------------------------------
  267 /**
  268  * Device availabality.
  269  */
  270 //--------------------------------------------------------------------------------------------------
  271 typedef enum
  272 {
  273     LE_ATSERVER_ALL_DEVICES = 0,
  274         ///< action will be done on all bound devices
  275 
  276     LE_ATSERVER_SPECIFIC_DEVICE = 1
  277         ///< action will be done on a specified device
  278 }
  279 le_atServer_AvailableDevice_t;
  280 
  281 
  282 //--------------------------------------------------------------------------------------------------
  283 /**
  284  * Reference type used by Add/Remove functions for EVENT 'le_atServer_Command'
  285  */
  286 //--------------------------------------------------------------------------------------------------
  287 typedef struct le_atServer_CommandHandler* le_atServer_CommandHandlerRef_t;
  288 
  289 
  290 //--------------------------------------------------------------------------------------------------
  291 /**
  292  * Handler for the AT command processing.
  293  *
  294  * @note The argument "parametersNumber" is set only when "type" parameter value is
  295  * LE_AT_SERVER_TYPE_PARA
  296  *
  297  * @param commandRef
  298  *        Received AT command reference
  299  * @param type
  300  *        Received AT command type
  301  * @param parametersNumber
  302  *        Parameters number
  303  * @param contextPtr
  304  */
  305 //--------------------------------------------------------------------------------------------------
  306 typedef void (*le_atServer_CommandHandlerFunc_t)
  307 (
  308     le_atServer_CmdRef_t commandRef,
  309     le_atServer_Type_t type,
  310     uint32_t parametersNumber,
  311     void* contextPtr
  312 );
  313 
  314 //--------------------------------------------------------------------------------------------------
  315 /**
  316  * This function starts an AT server session on the requested device.
  317  *
  318  * @return
  319  *      - Reference to the requested device.
  320  *      - NULL if the device is not available.
  321  */
  322 //--------------------------------------------------------------------------------------------------
  323 le_atServer_DeviceRef_t le_atServer_Start
  324 (
  325     const char* devicePath
  326         ///< [IN] device path which has to be used for the AT parser
  327 );
  328 
  329 //--------------------------------------------------------------------------------------------------
  330 /**
  331  * This function stops the AT server session on the requested device.
  332  *
  333  * @return
  334  *      - LE_OK            The function succeeded.
  335  *      - LE_FAULT         The function failed to stop the AT server session.
  336  */
  337 //--------------------------------------------------------------------------------------------------
  338 le_result_t le_atServer_Stop
  339 (
  340     le_atServer_DeviceRef_t device
  341         ///< [IN] device to be unbound
  342 );
  343 
  344 //--------------------------------------------------------------------------------------------------
  345 /**
  346  * This function created an AT command and register it into the AT parser.
  347  *
  348  * @return
  349  *      - Reference to the AT command.
  350  *      - NULL if an error occurs.
  351  */
  352 //--------------------------------------------------------------------------------------------------
  353 le_atServer_CmdRef_t le_atServer_Create
  354 (
  355     const char* name
  356         ///< [IN] AT command name string
  357 );
  358 
  359 //--------------------------------------------------------------------------------------------------
  360 /**
  361  * This function deletes an AT command (i.e. unregister from the AT parser).
  362  *
  363  * @return
  364  *      - LE_OK            The function succeeded.
  365  *      - LE_FAULT         The function failed to delete the command.
  366  */
  367 //--------------------------------------------------------------------------------------------------
  368 le_result_t le_atServer_Delete
  369 (
  370     le_atServer_CmdRef_t commandRef
  371         ///< [IN] AT command reference
  372 );
  373 
  374 //--------------------------------------------------------------------------------------------------
  375 /**
  376  * This function sets the device(s) where the specified AT command is available.
  377  *
  378  * @return
  379  *      - LE_OK            The function succeeded.
  380  *      - LE_FAULT         The function failed to set the device.
  381  *
  382  * @note If the AT command is available for all devices (i.e. availableDevice argument is set to
  383  * LE_ATSERVER_ALL_DEVICES), the "device" argument is unused.
  384  */
  385 //--------------------------------------------------------------------------------------------------
  386 le_result_t le_atServer_SetDevice
  387 (
  388     le_atServer_CmdRef_t commandRef,
  389         ///< [IN] AT command reference
  390 
  391     le_atServer_AvailableDevice_t availableDevice,
  392         ///< [IN] device available for the AT command
  393 
  394     le_atServer_DeviceRef_t device
  395         ///< [IN] device reference where the AT command is available
  396 );
  397 
  398 //--------------------------------------------------------------------------------------------------
  399 /**
  400  * Add handler function for EVENT 'le_atServer_Command'
  401  *
  402  * This event provides information when the AT command is detected.
  403  */
  404 //--------------------------------------------------------------------------------------------------
  405 le_atServer_CommandHandlerRef_t le_atServer_AddCommandHandler
  406 (
  407     le_atServer_CmdRef_t commandRef,
  408         ///< [IN] AT command reference
  409 
  410     le_atServer_CommandHandlerFunc_t handlerPtr,
  411         ///< [IN]
  412 
  413     void* contextPtr
  414         ///< [IN]
  415 );
  416 
  417 //--------------------------------------------------------------------------------------------------
  418 /**
  419  * Remove handler function for EVENT 'le_atServer_Command'
  420  */
  421 //--------------------------------------------------------------------------------------------------
  422 void le_atServer_RemoveCommandHandler
  423 (
  424     le_atServer_CommandHandlerRef_t addHandlerRef
  425         ///< [IN]
  426 );
  427 
  428 //--------------------------------------------------------------------------------------------------
  429 /**
  430  * This function can be used to get the parameters of a received AT command.
  431  *
  432  * @return
  433  *      - LE_OK            The function succeeded.
  434  *      - LE_FAULT         The function failed to get the requested parameter.
  435  *
  436  */
  437 //--------------------------------------------------------------------------------------------------
  438 le_result_t le_atServer_GetParameter
  439 (
  440     le_atServer_CmdRef_t commandRef,
  441         ///< [IN] AT command reference
  442 
  443     uint32_t index,
  444         ///< [IN] agument index
  445 
  446     char* parameter,
  447         ///< [OUT] parameter value
  448 
  449     size_t parameterNumElements
  450         ///< [IN]
  451 );
  452 
  453 //--------------------------------------------------------------------------------------------------
  454 /**
  455  * This function can be used to get the AT command string.
  456  *
  457  * @return
  458  *      - LE_OK            The function succeeded.
  459  *      - LE_FAULT         The function failed to get the AT command string.
  460  *
  461  */
  462 //--------------------------------------------------------------------------------------------------
  463 le_result_t le_atServer_GetCommandName
  464 (
  465     le_atServer_CmdRef_t commandRef,
  466         ///< [IN] AT command reference
  467 
  468     char* name,
  469         ///< [OUT] AT command string
  470 
  471     size_t nameNumElements
  472         ///< [IN]
  473 );
  474 
  475 //--------------------------------------------------------------------------------------------------
  476 /**
  477  * This function can be used to send an intermediate response.
  478  *
  479  * @return
  480  *      - LE_OK            The function succeeded.
  481  *      - LE_FAULT         The function failed to send the intermediate response.
  482  *
  483  */
  484 //--------------------------------------------------------------------------------------------------
  485 le_result_t le_atServer_SendIntermediateResponse
  486 (
  487     le_atServer_CmdRef_t commandRef,
  488         ///< [IN] AT command reference
  489 
  490     const char* intermediateRsp
  491         ///< [IN] Intermediate response to be sent
  492 );
  493 
  494 //--------------------------------------------------------------------------------------------------
  495 /**
  496  * This function can be used to send the final response.
  497  *
  498  * @return
  499  *      - LE_OK            The function succeeded.
  500  *      - LE_FAULT         The function failed to send the final response.
  501  *
  502  */
  503 //--------------------------------------------------------------------------------------------------
  504 le_result_t le_atServer_SendFinalResponse
  505 (
  506     le_atServer_CmdRef_t commandRef,
  507         ///< [IN] AT command reference
  508 
  509     le_atServer_FinalRsp_t final,
  510         ///< [IN] Final response to be sent
  511 
  512     bool customStringAvailable,
  513         ///< [IN] Custom finalRsp string has to be sent
  514         ///<      instead of the default one.
  515 
  516     const char* finalRsp
  517         ///< [IN] custom final response string
  518 );
  519 
  520 //--------------------------------------------------------------------------------------------------
  521 /**
  522  * This function can be used to send the unsolicited response.
  523  *
  524  * @return
  525  *      - LE_OK            The function succeeded.
  526  *      - LE_FAULT         The function failed to send the unsolicited response.
  527  *
  528  */
  529 //--------------------------------------------------------------------------------------------------
  530 le_result_t le_atServer_SendUnsolicitedResponse
  531 (
  532     const char* unsolRsp,
  533         ///< [IN] Unsolicited response to be sent
  534 
  535     le_atServer_AvailableDevice_t availableDevice,
  536         ///< [IN] device to send the unsolicited response
  537 
  538     le_atServer_DeviceRef_t device
  539         ///< [IN] device reference where the unsolicited
  540         ///<      response has to be sent
  541 );
  542 
  543 
  544 #endif // LE_ATSERVER_INTERFACE_H_INCLUDE_GUARD
  545 
LE_ATSERVER_OK
Definition: le_atServer_interface.h:255
le_atServer_Stop
le_result_t le_atServer_Stop(le_atServer_DeviceRef_t device)
le_result_t
le_result_t
Definition: le_basics.h:35
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:307
le_atServer_SendIntermediateResponse
le_result_t le_atServer_SendIntermediateResponse(le_atServer_CmdRef_t commandRef, const char *intermediateRsp)
LE_ATSERVER_ALL_DEVICES
action will be done on all bound devices 
Definition: le_atServer_interface.h:273
LE_ATSERVER_TYPE_ACT
Action AT command (e.g. &#39;AT+CMD&#39;) 
Definition: le_atServer_interface.h:233
le_atServer_DeviceRef_t
struct le_atServer_Device * le_atServer_DeviceRef_t
Definition: le_atServer_interface.h:155
LE_ATSERVER_SPECIFIC_DEVICE
action will be done on a specified device 
Definition: le_atServer_interface.h:276
le_atServer_RemoveCommandHandler
void le_atServer_RemoveCommandHandler(le_atServer_CommandHandlerRef_t addHandlerRef)
le_atServer_SendFinalResponse
le_result_t le_atServer_SendFinalResponse(le_atServer_CmdRef_t commandRef, le_atServer_FinalRsp_t final, bool customStringAvailable, const char *finalRsp)
le_atServer_Delete
le_result_t le_atServer_Delete(le_atServer_CmdRef_t commandRef)
le_atServer_FinalRsp_t
le_atServer_FinalRsp_t
Definition: le_atServer_interface.h:253
le_atServer_Type_t
le_atServer_Type_t
Definition: le_atServer_interface.h:231
le_atServer_AddCommandHandler
le_atServer_CommandHandlerRef_t le_atServer_AddCommandHandler(le_atServer_CmdRef_t commandRef, le_atServer_CommandHandlerFunc_t handlerPtr, void *contextPtr)
le_atServer_DisconnectService
void le_atServer_DisconnectService(void)
le_atServer_Start
le_atServer_DeviceRef_t le_atServer_Start(const char *devicePath)
LE_ATSERVER_TYPE_PARA
AT command received with parameters (e.g. &#39;AT+CMD=x,y&#39;) 
Definition: le_atServer_interface.h:236
le_atServer_SendUnsolicitedResponse
le_result_t le_atServer_SendUnsolicitedResponse(const char *unsolRsp, le_atServer_AvailableDevice_t availableDevice, le_atServer_DeviceRef_t device)
le_atServer_ConnectService
void le_atServer_ConnectService(void)
LE_ATSERVER_TYPE_TEST
Test AT command (e.g. &#39;AT+CMD=?&#39;) 
Definition: le_atServer_interface.h:239
le_atServer_AvailableDevice_t
le_atServer_AvailableDevice_t
Definition: le_atServer_interface.h:271
le_atServer_CommandHandlerRef_t
struct le_atServer_CommandHandler * le_atServer_CommandHandlerRef_t
Definition: le_atServer_interface.h:287
legato.h
LE_ATSERVER_ERROR
Definition: le_atServer_interface.h:259
le_atServer_Create
le_atServer_CmdRef_t le_atServer_Create(const char *name)
le_atServer_TryConnectService
le_result_t le_atServer_TryConnectService(void)
le_atServer_SetDevice
le_result_t le_atServer_SetDevice(le_atServer_CmdRef_t commandRef, le_atServer_AvailableDevice_t availableDevice, le_atServer_DeviceRef_t device)
le_atServer_GetCommandName
le_result_t le_atServer_GetCommandName(le_atServer_CmdRef_t commandRef, char *name, size_t nameNumElements)
le_atServer_CmdRef_t
struct le_atServer_Cmd * le_atServer_CmdRef_t
Definition: le_atServer_interface.h:147
le_atServer_GetParameter
le_result_t le_atServer_GetParameter(le_atServer_CmdRef_t commandRef, uint32_t index, char *parameter, size_t parameterNumElements)
le_atClient_interface.h
LE_ATSERVER_TYPE_READ
Read AT command (e.g. &#39;AT+CMD?&#39;) 
Definition: le_atServer_interface.h:242