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