le_atServer_interface.h

Go to the documentation of this file.
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  * The AT commands Server handles AT commands' subscriptions on a requested serial device. The
16  * server is compliant with 3GPP 27.007, paragraphs 4.0, 4.1 and 4.2, and V25 ter, paragraphs 5.3,
17  * 5.4.
18  *
19  * @section atServer_syntax AT command syntax
20  *
21  * @subsection atServer_Syntax Syntax rules
22  *
23  * To be interpreted, the command line sent to the AT commands server must start by the pattern
24  * "AT" (mean ATtention command).<br>
25  * Lowercase characters are changed to their uppercase equivalents. Only characters between quotes
26  * are not replaced.
27  *
28  * The supported command formats are:
29  * - Basic syntax command:
30  * - using the format AT<command>[<number>]<br>
31  * The command name is composed of one or several of those characters: A to Z, & and \\.
32  * - the syntax of S command is also supported, like:
33  * - ATS<parameter_number>?
34  * - ATS<parameter_number>=<value>
35  * - D command syntax is a limitation right now, and is not supported.
36  *
37  * - Extended command format, with the following format:
38  * - action command with no parameters: AT+<name>
39  * - parameter command: AT+<name>=<value1>[,<value2>[,<value3>[...]]]<br>
40  * Values must be separated by a coma. Some values may be optional: in that case, optional
41  * value can be omitted in the AT command (e.g. AT+ABCD=,1).<br>
42  * A value is a string composed of one or several of the following characters: 0 to 9,
43  * A to F, H, z*, #, +, -. To set a value with other characters, the value has to be set
44  * between quote.
45  * - test command (determine the supported values): AT+<name>=?
46  * - read command (determine the current values, or stored values): AT+<name>?
47  *
48  * @note '+' AT command starting character shall be replaced by other symbol, not included into
49  * a to z, A to Z, & and \\.
50  *
51  * @subsection atServer_concate Concatenating commands
52  *
53  * Basic syntax command can be concatenated without a separator:<br>
54  * ATE1V1S95=47S0=0
55  *
56  * Additional commands (extended syntax command or basic syntax command) can be added after an
57  * extended syntax command with the insertion of a semicolon at the end of the command:<br>
58  * AT+CMDA=<param1>,<param2>;+CMDB?;+CMDC=?<br>
59  * AT+CMDA=<param1>,<param2>;E1V1
60  *
61  * Extended syntax command can be concatenated after basic syntax commands without a separator:<br>
62  * ATE1V1+CMD=<param1>
63  *
64  * @section atServer_binding Device Binding
65  *
66  * le_atServer_Start() must be called to bind the file descriptor of the device with the AT commands
67  * server. Note that a socket can also be bound.
68  * Multiple devices can be bound.
69  * A file descriptor can be unbound using le_atServer_Stop().
70  *
71  * The server can be suspended using le_atServer_Suspend() in order to use the
72  * opened fd for other purposes like starting a PPP service on the opened fd.
73  * For that a fd dup needs to be done before opening a server session.
74  * When needed, the server can be resumed using le_atServer_Resume(). Make sure
75  * to close the fd when the application exists or you may get too many open files error.
76  *
77  * used before opening a server session
78  * @section atServer_subscription Subscription
79  *
80  * A new AT command can be added into the parser using le_atServer_Create(), and it can be deleted
81  * using le_atServer_Delete().
82  * An AT command can be available only on one dedicated device, or on all bound devices, using
83  * le_atServer_SetDevice().
84  *
85  * @section atServer_handler Handler
86  *
87  * To handle the AT command, the application has to subscribe a handler using
88  * le_atServer_AddCommandHandler(). It can be removed with le_atServer_RemoveCommandHandler().<br>
89  * The called handler (le_atServer_CommandHandlerRef_t prototype) can use
90  * le_atServer_GetCommandName() to retrieve the received AT command string.<br>
91  * It can also call le_atServer_GetParameter() to retrieve parameters of the AT command. This
92  * function gets the string sending through the AT command. If the parameter was sent between
93  * quotes, the quotes are removed. This API can be used for both formats:
94  * - In case of a basic format command, if exists, the parameter can be retrieved at the index 0.<br>
95  * For S command specific format (ATS<parameter_number>=<value>), the <parameter_number> is
96  * retrieved at the index 0, the <value> parameter at the index 1.
97  *
98  * - In case of an extended format command, parameters are retrieved thanks to their indexes,
99  * starting from 0. If the parameter is missed (e.g. "AT+CMD=,1"), the getting value is an empty
100  * string (i.e. '\0' with null length).
101  *
102  * The handler receives in argument the type of the AT command (of le_atServer_Type_t type).
103  * Even if these types are specific to the extended format commands according to the standards, they
104  * are also applicable here to basic format commands to detect commands with parameters, or read
105  * values (e.g. ATS<parameter_number>?).
106  *
107  * @section atServer_responses Responses
108  *
109  * @subsection intermediateRsp Intermediate response
110  *
111  * The application has can send intermediate responses through
112  * le_atServer_SendIntermediateResponse().
113  *
114  * @subsection finalRsp Final response
115  *
116  * In all cases, the application must send a final response using
117  * le_atServer_SendFinalResponse(). The corresponding device will be locked until the final response
118  * is sent.
119  *
120  * If no answer is sent, the device will not accept any new AT commands (an error will be
121  * returned).
122  *
123  * le_atServer_SendFinalResponse() has to inform of the result thanks to the argument of
124  * le_atServer_FinalRsp_t type. This argument permits to the AT command Server to:
125  * - create the result string if no custom string is provided
126  * - continue or stop the parsing of concatenated commands: if one command is failed, next commands
127  * are not executed, the final result of the concatenated AT command is the last error.
128  *
129  * @subsection unsolicitedRsp Unsolicited response
130  *
131  * The application can also send unsolicited responses to warn a host
132  * application using le_atServer_SendUnsolicitedResponse().
133  *
134  * This response is sent when no AT command is being processing on the device (i.e. unsolicited
135  * response is sent between the latest final response and the next reception of an AT command).<br>
136  * If an unsolicited response is sent when an AT command is in progress, the unsolicited response
137  * is buffered and sent as soon as the device becomes available (i.e., the processing AT command
138  * sends its final response).
139  *
140  * The application can send an unsolicited on all opened device, or only one on a dedicated deivce.
141  *
142  * <HR>
143  *
144  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
145  */
146 /**
147  * @file le_atServer_interface.h
148  *
149  * Legato @ref c_atServer include file.
150  *
151  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
152  */
153 
154 #ifndef LE_ATSERVER_INTERFACE_H_INCLUDE_GUARD
155 #define LE_ATSERVER_INTERFACE_H_INCLUDE_GUARD
156 
157 
158 #include "legato.h"
159 
160 // Interface specific includes
161 #include "le_atDefs_interface.h"
162 
163 
164 //--------------------------------------------------------------------------------------------------
165 /**
166  *
167  * Connect the current client thread to the service providing this API. Block until the service is
168  * available.
169  *
170  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
171  * called before any other functions in this API. Normally, ConnectService is automatically called
172  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
173  *
174  * This function is created automatically.
175  */
176 //--------------------------------------------------------------------------------------------------
178 (
179  void
180 );
181 
182 //--------------------------------------------------------------------------------------------------
183 /**
184  *
185  * Try to connect the current client thread to the service providing this API. Return with an error
186  * if the service is not available.
187  *
188  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
189  * called before any other functions in this API. Normally, ConnectService is automatically called
190  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
191  *
192  * This function is created automatically.
193  *
194  * @return
195  * - LE_OK if the client connected successfully to the service.
196  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is bound.
197  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
198  * - LE_COMM_ERROR if the Service Directory cannot be reached.
199  */
200 //--------------------------------------------------------------------------------------------------
202 (
203  void
204 );
205 
206 //--------------------------------------------------------------------------------------------------
207 /**
208  *
209  * Disconnect the current client thread from the service providing this API.
210  *
211  * Normally, this function doesn't need to be called. After this function is called, there's no
212  * longer a connection to the service, and the functions in this API can't be used. For details, see
213  * @ref apiFilesC_client.
214  *
215  * This function is created automatically.
216  */
217 //--------------------------------------------------------------------------------------------------
219 (
220  void
221 );
222 
223 
224 //--------------------------------------------------------------------------------------------------
225 /**
226  * Reference type for an AT command.
227  */
228 //--------------------------------------------------------------------------------------------------
229 typedef struct le_atServer_Cmd* le_atServer_CmdRef_t;
230 
231 
232 //--------------------------------------------------------------------------------------------------
233 /**
234  * Reference type for a AT command device.
235  */
236 //--------------------------------------------------------------------------------------------------
237 typedef struct le_atServer_Device* le_atServer_DeviceRef_t;
238 
239 
240 //--------------------------------------------------------------------------------------------------
241 /**
242  * Received AT command type.
243  *
244  */
245 //--------------------------------------------------------------------------------------------------
246 typedef enum
247 {
249  ///< Action AT command (e.g. 'AT+CMD')
250 
252  ///< AT command received with parameters (e.g. 'AT+CMD=x,y')
253 
255  ///< Test AT command (e.g. 'AT+CMD=?')
256 
258  ///< Read AT command (e.g. 'AT+CMD?')
259 }
261 
262 
263 //--------------------------------------------------------------------------------------------------
264 /**
265  * Final response.
266  */
267 //--------------------------------------------------------------------------------------------------
268 typedef enum
269 {
271  ///< AT command successfully treated, "\r\nOK\r\n" is sent if no custom
272  ///< response is set
273 
275  ///< error in AT command treatement, "\r\nERROR\r\n" is sent if no custom
276  ///< response is set
277 }
279 
280 
281 //--------------------------------------------------------------------------------------------------
282 /**
283  * Device availability.
284  */
285 //--------------------------------------------------------------------------------------------------
286 typedef enum
287 {
289  ///< action will be done on all bound devices
290 
292  ///< action will be done on a specified device
293 }
295 
296 
297 //--------------------------------------------------------------------------------------------------
298 /**
299  * Reference type used by Add/Remove functions for EVENT 'le_atServer_Command'
300  */
301 //--------------------------------------------------------------------------------------------------
302 typedef struct le_atServer_CommandHandler* le_atServer_CommandHandlerRef_t;
303 
304 
305 //--------------------------------------------------------------------------------------------------
306 /**
307  * Handler for the AT command processing.
308  *
309  * @note The argument "parametersNumber" is set only when "type" parameter value is
310  * LE_AT_SERVER_TYPE_PARA
311  *
312  * @param commandRef
313  * Received AT command reference
314  * @param type
315  * Received AT command type
316  * @param parametersNumber
317  * Parameters number
318  * @param contextPtr
319  */
320 //--------------------------------------------------------------------------------------------------
321 typedef void (*le_atServer_CommandHandlerFunc_t)
322 (
323  le_atServer_CmdRef_t commandRef,
324  le_atServer_Type_t type,
325  uint32_t parametersNumber,
326  void* contextPtr
327 );
328 
329 //--------------------------------------------------------------------------------------------------
330 /**
331  * Suspend server / enter data mode
332  *
333  * When this function is called the server stops monitoring the fd for events
334  * hence no more I/O operations are done on the fd by the server.
335  *
336  * @return
337  * - LE_OK Success.
338  * - LE_BAD_PARAMETER Invalid device reference.
339  * - LE_FAULT Device not monitored
340  *
341  */
342 //--------------------------------------------------------------------------------------------------
344 (
346  ///< [IN] device to be suspended
347 );
348 
349 //--------------------------------------------------------------------------------------------------
350 /**
351  * Resume server / enter command mode
352  *
353  * When this function is called the server resumes monitoring the fd for events
354  * and is able to interpret AT commands again.
355  *
356  * @return
357  * - LE_OK Success.
358  * - LE_BAD_PARAMETER Invalid device reference.
359  * - LE_FAULT Device not monitored
360  *
361  */
362 //--------------------------------------------------------------------------------------------------
364 (
366  ///< [IN] device to be resumed
367 );
368 
369 //--------------------------------------------------------------------------------------------------
370 /**
371  * This function opens an AT server session on the requested device.
372  *
373  * @return
374  * - Reference to the requested device.
375  * - NULL if the device is not available or fd is a BAD FILE DESCRIPTOR.
376  *
377  * @note Make sure to duplicate (man dup) your file descriptor before opening
378  * a server session to be able to use the suspend/resume feature
379  *
380  */
381 //--------------------------------------------------------------------------------------------------
383 (
384  int fd
385  ///< [IN] File descriptor.
386 );
387 
388 //--------------------------------------------------------------------------------------------------
389 /**
390  * This function closes the AT server session on the requested device.
391  *
392  * @return
393  * - LE_OK The function succeeded.
394  * - LE_BAD_PARAMETER Invalid device reference.
395  * - LE_BUSY The requested device is busy.
396  * - LE_FAULT Failed to stop the server, check logs
397  * for more information.
398  */
399 //--------------------------------------------------------------------------------------------------
401 (
403  ///< [IN] device to be unbound
404 );
405 
406 //--------------------------------------------------------------------------------------------------
407 /**
408  * This function created an AT command and register it into the AT parser.
409  *
410  * @return
411  * - Reference to the AT command.
412  * - NULL if an error occurs.
413  */
414 //--------------------------------------------------------------------------------------------------
416 (
417  const char* name
418  ///< [IN] AT command name string
419 );
420 
421 //--------------------------------------------------------------------------------------------------
422 /**
423  * This function deletes an AT command (i.e. unregister from the AT parser).
424  *
425  * @return
426  * - LE_OK The function succeeded.
427  * - LE_FAULT The function failed to delete the command.
428  * - LE_BUSY Command is in progress.
429  *
430  */
431 //--------------------------------------------------------------------------------------------------
433 (
434  le_atServer_CmdRef_t commandRef
435  ///< [IN] AT command reference
436 );
437 
438 //--------------------------------------------------------------------------------------------------
439 /**
440  * This function sets the device(s) where the specified AT command is available.
441  *
442  * @return
443  * - LE_OK The function succeeded.
444  * - LE_FAULT The function failed to set the device.
445  *
446  * @note If the AT command is available for all devices (i.e. availableDevice argument is set to
447  * LE_ATSERVER_ALL_DEVICES), the "device" argument is unused.
448  */
449 //--------------------------------------------------------------------------------------------------
451 (
452  le_atServer_CmdRef_t commandRef,
453  ///< [IN] AT command reference
454 
455  le_atServer_AvailableDevice_t availableDevice,
456  ///< [IN] device available for the AT command
457 
459  ///< [IN] device reference where the AT command is available
460 );
461 
462 //--------------------------------------------------------------------------------------------------
463 /**
464  * Add handler function for EVENT 'le_atServer_Command'
465  *
466  * This event provides information when the AT command is detected.
467  */
468 //--------------------------------------------------------------------------------------------------
470 (
471  le_atServer_CmdRef_t commandRef,
472  ///< [IN] AT command reference
473 
475  ///< [IN]
476 
477  void* contextPtr
478  ///< [IN]
479 );
480 
481 //--------------------------------------------------------------------------------------------------
482 /**
483  * Remove handler function for EVENT 'le_atServer_Command'
484  */
485 //--------------------------------------------------------------------------------------------------
487 (
488  le_atServer_CommandHandlerRef_t addHandlerRef
489  ///< [IN]
490 );
491 
492 //--------------------------------------------------------------------------------------------------
493 /**
494  * This function can be used to get the parameters of a received AT command.
495  *
496  * @return
497  * - LE_OK The function succeeded.
498  * - LE_FAULT The function failed to get the requested parameter.
499  *
500  */
501 //--------------------------------------------------------------------------------------------------
503 (
504  le_atServer_CmdRef_t commandRef,
505  ///< [IN] AT command reference
506 
507  uint32_t index,
508  ///< [IN] agument index
509 
510  char* parameter,
511  ///< [OUT] parameter value
512 
513  size_t parameterNumElements
514  ///< [IN]
515 );
516 
517 //--------------------------------------------------------------------------------------------------
518 /**
519  * This function can be used to get the AT command string.
520  *
521  * @return
522  * - LE_OK The function succeeded.
523  * - LE_FAULT The function failed to get the AT command string.
524  *
525  */
526 //--------------------------------------------------------------------------------------------------
528 (
529  le_atServer_CmdRef_t commandRef,
530  ///< [IN] AT command reference
531 
532  char* name,
533  ///< [OUT] AT command string
534 
535  size_t nameNumElements
536  ///< [IN]
537 );
538 
539 //--------------------------------------------------------------------------------------------------
540 /**
541  * This function can be used to send an intermediate response.
542  *
543  * @return
544  * - LE_OK The function succeeded.
545  * - LE_FAULT The function failed to send the intermediate response.
546  *
547  */
548 //--------------------------------------------------------------------------------------------------
550 (
551  le_atServer_CmdRef_t commandRef,
552  ///< [IN] AT command reference
553 
554  const char* intermediateRsp
555  ///< [IN] Intermediate rsp to be sent
556 );
557 
558 //--------------------------------------------------------------------------------------------------
559 /**
560  * This function can be used to send the final response.
561  *
562  * @return
563  * - LE_OK The function succeeded.
564  * - LE_FAULT The function failed to send the final response.
565  *
566  */
567 //--------------------------------------------------------------------------------------------------
569 (
570  le_atServer_CmdRef_t commandRef,
571  ///< [IN] AT command reference
572 
574  ///< [IN] Final response to be sent
575 
576  bool customStringAvailable,
577  ///< [IN] Custom finalRsp str has to be sent
578  ///< instead of the default one.
579 
580  const char* finalRsp
581  ///< [IN] custom final response string
582 );
583 
584 //--------------------------------------------------------------------------------------------------
585 /**
586  * This function can be used to send the unsolicited response.
587  *
588  * @return
589  * - LE_OK The function succeeded.
590  * - LE_FAULT The function failed to send the unsolicited response.
591  *
592  */
593 //--------------------------------------------------------------------------------------------------
595 (
596  const char* unsolRsp,
597  ///< [IN] Unsolicited rsp to be sent
598 
599  le_atServer_AvailableDevice_t availableDevice,
600  ///< [IN] device to send unsol rsp
601 
603  ///< [IN] device reference where the
604  ///< unsol rsp has to be sent
605 );
606 
607 
608 #endif // LE_ATSERVER_INTERFACE_H_INCLUDE_GUARD
609 
Definition: le_atServer_interface.h:270
le_result_t
Definition: le_basics.h:35
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:322
le_result_t le_atServer_SendIntermediateResponse(le_atServer_CmdRef_t commandRef, const char *intermediateRsp)
action will be done on all bound devices
Definition: le_atServer_interface.h:288
Action AT command (e.g. &#39;AT+CMD&#39;)
Definition: le_atServer_interface.h:248
struct le_atServer_Device * le_atServer_DeviceRef_t
Definition: le_atServer_interface.h:237
action will be done on a specified device
Definition: le_atServer_interface.h:291
void le_atServer_RemoveCommandHandler(le_atServer_CommandHandlerRef_t addHandlerRef)
le_atServer_DeviceRef_t le_atServer_Open(int fd)
le_result_t le_atServer_SendFinalResponse(le_atServer_CmdRef_t commandRef, le_atServer_FinalRsp_t final, bool customStringAvailable, const char *finalRsp)
le_result_t le_atServer_Close(le_atServer_DeviceRef_t device)
le_result_t le_atServer_Delete(le_atServer_CmdRef_t commandRef)
le_atServer_FinalRsp_t
Definition: le_atServer_interface.h:268
le_atServer_Type_t
Definition: le_atServer_interface.h:246
le_atServer_CommandHandlerRef_t le_atServer_AddCommandHandler(le_atServer_CmdRef_t commandRef, le_atServer_CommandHandlerFunc_t handlerPtr, void *contextPtr)
void le_atServer_DisconnectService(void)
AT command received with parameters (e.g. &#39;AT+CMD=x,y&#39;)
Definition: le_atServer_interface.h:251
le_result_t le_atServer_SendUnsolicitedResponse(const char *unsolRsp, le_atServer_AvailableDevice_t availableDevice, le_atServer_DeviceRef_t device)
void le_atServer_ConnectService(void)
Test AT command (e.g. &#39;AT+CMD=?&#39;)
Definition: le_atServer_interface.h:254
le_atServer_AvailableDevice_t
Definition: le_atServer_interface.h:286
struct le_atServer_CommandHandler * le_atServer_CommandHandlerRef_t
Definition: le_atServer_interface.h:302
Definition: le_atServer_interface.h:274
le_atServer_CmdRef_t le_atServer_Create(const char *name)
le_result_t le_atServer_TryConnectService(void)
le_result_t le_atServer_Suspend(le_atServer_DeviceRef_t device)
le_result_t le_atServer_SetDevice(le_atServer_CmdRef_t commandRef, le_atServer_AvailableDevice_t availableDevice, le_atServer_DeviceRef_t device)
le_result_t le_atServer_GetCommandName(le_atServer_CmdRef_t commandRef, char *name, size_t nameNumElements)
struct le_atServer_Cmd * le_atServer_CmdRef_t
Definition: le_atServer_interface.h:229
le_result_t le_atServer_GetParameter(le_atServer_CmdRef_t commandRef, uint32_t index, char *parameter, size_t parameterNumElements)
le_result_t le_atServer_Resume(le_atServer_DeviceRef_t device)
Read AT command (e.g. &#39;AT+CMD?&#39;)
Definition: le_atServer_interface.h:257