le_atServer_interface.h

Go to the documentation of this file.
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 {
443  ///< Action AT command (e.g. 'AT+CMD')
445  ///< AT command received with parameters (e.g. 'AT+CMD=x,y')
447  ///< Test AT command (e.g. 'AT+CMD=?')
449  ///< Read AT command (e.g. 'AT+CMD?')
450 }
452 
453 
454 //--------------------------------------------------------------------------------------------------
455 /**
456  * Final response.
457  */
458 //--------------------------------------------------------------------------------------------------
459 typedef enum
460 {
462  ///< AT command successfully treated
464  ///< Connection terminated
466  ///< Error in AT command treatement
468  ///< No dialtone detected
470  ///< Busy signal detected
471 }
473 
474 
475 //--------------------------------------------------------------------------------------------------
476 /**
477  * Device availability.
478  */
479 //--------------------------------------------------------------------------------------------------
480 typedef enum
481 {
483  ///< action will be done on all bound devices
485  ///< action will be done on a specified device
486 }
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 //--------------------------------------------------------------------------------------------------
558 (
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 //--------------------------------------------------------------------------------------------------
578 (
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
615 (
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
661 (
662  le_atServer_CmdRef_t commandRef,
663  ///< [IN] AT command reference
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 //--------------------------------------------------------------------------------------------------
676 (
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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
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 //--------------------------------------------------------------------------------------------------
847 (
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 //--------------------------------------------------------------------------------------------------
862 (
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
943 (
944  void
945 );
946 
947 //--------------------------------------------------------------------------------------------------
948 /**
949  * This function enables extended error codes on the selected device.
950  */
951 //--------------------------------------------------------------------------------------------------
953 (
954  void
955 );
956 
957 //--------------------------------------------------------------------------------------------------
958 /**
959  * This function disables extended error codes on the selected device.
960  */
961 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
1031 (
1032  le_atServer_CmdRef_t cmdRef,
1033  ///< [IN] AT command reference
1035  ///< [IN] Get text callback
1036  void* contextPtr
1037  ///< [IN]
1038 );
1039 
1040 #endif // LE_ATSERVER_INTERFACE_H_INCLUDE_GUARD
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_result_t le_atServer_Close(le_atServer_DeviceRef_t device)
void(* le_atServer_DisconnectHandler_t)(void *)
Definition: le_atServer_interface.h:304
Action AT command (e.g. &#39;AT+CMD&#39;)
Definition: le_atServer_interface.h:442
Error in AT command treatement.
Definition: le_atServer_interface.h:465
No dialtone detected.
Definition: le_atServer_interface.h:467
le_result_t
Definition: le_basics.h:35
le_result_t le_atServer_TryConnectService(void)
le_result_t le_atServer_RemoveDeviceFromBridge(le_atServer_DeviceRef_t deviceRef, le_atServer_BridgeRef_t bridgeRef)
void le_atServer_EnableExtendedErrorCodes(void)
le_result_t le_atServer_GetParameter(le_atServer_CmdRef_t commandRef, uint32_t index, char *parameter, size_t parameterSize)
action will be done on a specified device
Definition: le_atServer_interface.h:484
le_atServer_FinalRsp_t
Definition: le_atServer_interface.h:459
le_result_t le_atServer_GetCommandName(le_atServer_CmdRef_t commandRef, char *name, size_t nameSize)
struct le_atServer_CommandHandler * le_atServer_CommandHandlerRef_t
Definition: le_atServer_interface.h:495
AT command successfully treated.
Definition: le_atServer_interface.h:461
le_result_t le_atServer_GetDevice(le_atServer_CmdRef_t commandRef, le_atServer_DeviceRef_t *deviceRefPtr)
le_result_t le_atServer_SetVerboseErrorCode(le_atServer_ErrorCodeRef_t errorCodeRef, const char *LE_NONNULL verboseCode)
le_result_t le_atServer_EnableEcho(le_atServer_DeviceRef_t device)
le_atServer_CommandHandlerRef_t le_atServer_AddCommandHandler(le_atServer_CmdRef_t commandRef, le_atServer_CommandHandlerFunc_t handlerPtr, void *contextPtr)
le_atServer_DeviceRef_t le_atServer_Open(int fd)
le_atServer_CmdRef_t le_atServer_Create(const char *LE_NONNULL name)
Busy signal detected.
Definition: le_atServer_interface.h:469
void le_atServer_ConnectService(void)
le_result_t le_atServer_AddDeviceToBridge(le_atServer_DeviceRef_t deviceRef, le_atServer_BridgeRef_t bridgeRef)
action will be done on all bound devices
Definition: le_atServer_interface.h:482
le_result_t le_atServer_Resume(le_atServer_DeviceRef_t device)
le_result_t le_atServer_Delete(le_atServer_CmdRef_t commandRef)
le_atServer_AvailableDevice_t
Definition: le_atServer_interface.h:480
Connection terminated.
Definition: le_atServer_interface.h:463
le_result_t le_atServer_CloseBridge(le_atServer_BridgeRef_t bridgeRef)
le_result_t le_atServer_SendFinalResponse(le_atServer_CmdRef_t commandRef, le_atServer_FinalRsp_t finalResponse, bool customStringAvailable, const char *LE_NONNULL finalRsp)
void le_atServer_EnableVerboseErrorCodes(void)
struct le_atServer_Bridge * le_atServer_BridgeRef_t
Definition: le_atServer_interface.h:423
le_atServer_Type_t
Definition: le_atServer_interface.h:440
void le_atServer_RemoveCommandHandler(le_atServer_CommandHandlerRef_t handlerRef)
le_result_t le_atServer_Suspend(le_atServer_DeviceRef_t device)
Test AT command (e.g. &#39;AT+CMD=?&#39;)
Definition: le_atServer_interface.h:446
le_result_t le_atServer_GetTextAsync(le_atServer_CmdRef_t cmdRef, le_atServer_GetTextCallbackFunc_t callbackPtr, void *contextPtr)
void le_atServer_DisableExtendedErrorCodes(void)
struct le_atServer_ErrorCode * le_atServer_ErrorCodeRef_t
Definition: le_atServer_interface.h:431
struct le_atServer_Device * le_atServer_DeviceRef_t
Definition: le_atServer_interface.h:415
void le_atServer_SetServerDisconnectHandler(le_atServer_DisconnectHandler_t disconnectHandler, void *contextPtr)
AT command received with parameters (e.g. &#39;AT+CMD=x,y&#39;)
Definition: le_atServer_interface.h:444
le_result_t le_atServer_SendIntermediateResponse(le_atServer_CmdRef_t commandRef, const char *LE_NONNULL intermediateRsp)
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_ErrorCodeRef_t le_atServer_CreateErrorCode(uint32_t errorCode, const char *LE_NONNULL pattern)
void le_atServer_DisconnectService(void)
le_result_t le_atServer_SendUnsolicitedResponse(const char *LE_NONNULL unsolRsp, le_atServer_AvailableDevice_t availableDevice, le_atServer_DeviceRef_t device)
Read AT command (e.g. &#39;AT+CMD?&#39;)
Definition: le_atServer_interface.h:448
le_result_t le_atServer_DisableEcho(le_atServer_DeviceRef_t device)
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_BridgeRef_t le_atServer_OpenBridge(int fd)
le_result_t le_atServer_DeleteErrorCode(le_atServer_ErrorCodeRef_t errorCodeRef)
struct le_atServer_Cmd * le_atServer_CmdRef_t
Definition: le_atServer_interface.h:407