le_atClient_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_atClient AT Commands Client
14  *
15  * @ref le_atClient_interface.h "API Reference"
16  *
17  * @warning Some AT commands may conflict with Legato APIs; using both may cause problems that can
18  * be difficult to diagnose. AT commands should be avoided whenever possible, and should only be
19  * used with great care.
20  *
21  * The AT Client Service handles the AT commands sent to the modem on a specified
22  * serial device. It also supports getting AT command responses (intermediate, final or
23  * unsolicited responses).
24  * This service can be subscribed to by several apps simultaneously.
25  *
26  * @section le_atClient_binding IPC interfaces binding
27  *
28  * All the functions of this API are provided by the @b atService.
29  *
30  * Here's a code sample binding to the AT commands server:
31  * @verbatim
32  bindings:
33  {
34  atClientTest.atClientTestComp.le_atClient -> atService.le_atClient
35  }
36  @endverbatim
37  *
38  * @section atClient_binding Device Binding
39  *
40  * le_atClient_Start() must be called to bind a specific device with the ATClient, the user app must
41  * also pass in an open file descriptor to le_atClient_Start() The file descriptor will
42  * automatically close when le_atClient_Stop() is called.
43  *
44  * Multiple devices can be bound. The app has to configured the device before using it with
45  * the ATClient.
46  *
47  * A device can be unbound using le_atClient_Stop(), which will also automatically close the file
48  * descriptor.
49  *
50  * @section atClient_statement Statement
51  *
52  * An AT command statement is requested before sending it. The following steps have to be done for
53  * its declaration:
54  *
55  * - create an AT command reference using le_atClient_Create().
56  *
57  * - use le_atClient_SetCommand() to set the AT command to be sent to the modem.
58  *
59  * - set the sending port to use le_atClient_SetDevice().
60  *
61  * - can set a timeout value using le_atClient_SetTimeout(); default value is @c 30s.
62  *
63  * - request expected final responses and set using le_atClient_SetFinalResponse().The final
64  * response is mandatory to detect
65  * the end of the AT command execution. If an AT command answers with a final response that
66  * doesn't belong to the final responses set, the AT command execution will end by timeout.
67  *
68  * - can call le_atClient_SetIntermediateResponse() to set the intermediate responses
69  * filters. This is optional.
70  *
71  * Command responses given in le_atClient_SetIntermediateResponse() and
72  * le_atClient_SetFinalResponse() are the first characters of the response lines. They are used as a
73  * filter of the received lines (a line are the characters received between receiving a
74  * <CR> and an <LF>). Other lines are dropped.
75  *
76  * - text can be set using le_atClient_SetText(). This is used for commands that answers a
77  * '>' character to receive additional information. The given text is sent to the modem when '>' is
78  * detected. The character @c CTRL-Z is automatically sent.
79  *
80  *
81  * @section atClient_send Sending
82  *
83  * When the AT command declaration is complete, it can be sent using le_atClient_Send(). This API is
84  * synchronous (blocking until final response is detected, or timeout reached).
85  *
86  * le_atClient_SetCommandAndSend() is equivalent to le_atClient_Create(), le_atClient_SetCommand(),
87  * le_atClient_SetDevice(), le_atClient_SetTimeout(), le_atClient_SetIntermediateResponse() and
88  * le_atClient_SetFinalResponse(), in case of an Error le_atClient_Delete(),
89  * in one API call.
90  * The AT command reference is created and returned by this API. When an error
91  * occurs the command reference is deleted and is not a valid reference anymore
92  *
93  * @section atClient_responses Responses
94  *
95  * When the AT command has been sent correctly (i.e., le_atClient_Send() or
96  * le_atClient_SetCommandAndSend() execution is successful), the app gets these AT command
97  * responses:
98  * - le_atClient_GetFinalResponse() is used to get the final responses
99  * - le_atClient_GetFirstIntermediateResponse() is used to get the first intermediate result code.
100  * Other intermediate result codes can be obtained by calling
101  * le_atClient_GetNextIntermediateResponse().Returns LE_NOT_FOUND when there are no further results.
102  *
103  * When a response has been set in the AT command declaration, the AT command response returned by
104  * these APIs start with the given pattern, and ends when a <CR><LF> is detected.
105  *
106  * @section atClient__delete Deleting
107  *
108  * When the AT command is over, the reference has to be deleted by calling le_atClient_Delete().
109  *
110  * @section atClient_unsolicited Unsolicited Responses
111  *
112  * An app can subscribe to a specific, unsolicited response using
113  * le_atClient_AddUnsolicitedResponseHandler(), and can be removed using
114  * le_atClient_RemoveUnsolicitedResponseHandler(). The subscribed handler is called when the given
115  * pattern is detected. The handler receives a parameter with the complete line of the unsolicited
116  * response.
117  * The parameter @c lineCount is used to set the unsolicited lines number.
118  * For example, @c +CMT unsolicited response has the following syntax:
119  * @code
120  * +CMT: ...<CR><LF>
121  * <sms text>
122  * @endcode
123  * In this case, @c lineCount has to be set to @c 2 to receive both lines into the handler.
124  * @c +CREG unsolicited response is sent only one line, so @c lineCount is set to @c 1.
125  *
126  * <HR>
127  *
128  * Copyright (C) Sierra Wireless Inc.
129  */
130 /**
131  * @file le_atClient_interface.h
132  *
133  * Legato @ref c_atClient include file.
134  *
135  * Copyright (C) Sierra Wireless Inc.
136  */
137 
138 #ifndef LE_ATCLIENT_INTERFACE_H_INCLUDE_GUARD
139 #define LE_ATCLIENT_INTERFACE_H_INCLUDE_GUARD
140 
141 
142 #include "legato.h"
143 
144 // Interface specific includes
145 #include "le_atDefs_interface.h"
146 
147 // Internal includes for this interface
148 #include "le_atClient_common.h"
149 /** @addtogroup le_atClient le_atClient API Reference
150  * @{
151  * @file le_atClient_common.h
152  * @file le_atClient_interface.h **/
153 //--------------------------------------------------------------------------------------------------
154 /**
155  * Type for handler called when a server disconnects.
156  */
157 //--------------------------------------------------------------------------------------------------
158 typedef void (*le_atClient_DisconnectHandler_t)(void *);
159 
160 //--------------------------------------------------------------------------------------------------
161 /**
162  *
163  * Connect the current client thread to the service providing this API. Block until the service is
164  * available.
165  *
166  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
167  * called before any other functions in this API. Normally, ConnectService is automatically called
168  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
169  *
170  * This function is created automatically.
171  */
172 //--------------------------------------------------------------------------------------------------
174 (
175  void
176 );
177 
178 //--------------------------------------------------------------------------------------------------
179 /**
180  *
181  * Try to connect the current client thread to the service providing this API. Return with an error
182  * if the service is not available.
183  *
184  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
185  * called before any other functions in this API. Normally, ConnectService is automatically called
186  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
187  *
188  * This function is created automatically.
189  *
190  * @return
191  * - LE_OK if the client connected successfully to the service.
192  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
193  * bound.
194  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
195  * - LE_COMM_ERROR if the Service Directory cannot be reached.
196  */
197 //--------------------------------------------------------------------------------------------------
199 (
200  void
201 );
202 
203 //--------------------------------------------------------------------------------------------------
204 /**
205  * Set handler called when server disconnection is detected.
206  *
207  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
208  * to continue without exiting, it should call longjmp() from inside the handler.
209  */
210 //--------------------------------------------------------------------------------------------------
212 (
213  le_atClient_DisconnectHandler_t disconnectHandler,
214  void *contextPtr
215 );
216 
217 //--------------------------------------------------------------------------------------------------
218 /**
219  *
220  * Disconnect the current client thread from the service providing this API.
221  *
222  * Normally, this function doesn't need to be called. After this function is called, there's no
223  * longer a connection to the service, and the functions in this API can't be used. For details, see
224  * @ref apiFilesC_client.
225  *
226  * This function is created automatically.
227  */
228 //--------------------------------------------------------------------------------------------------
230 (
231  void
232 );
233 
234 
235 //--------------------------------------------------------------------------------------------------
236 /**
237  */
238 //--------------------------------------------------------------------------------------------------
239 
240 
241 //--------------------------------------------------------------------------------------------------
242 /**
243  */
244 //--------------------------------------------------------------------------------------------------
245 
246 
247 //--------------------------------------------------------------------------------------------------
248 /**
249  * Handler for unsolicited response reception.
250  *
251  */
252 //--------------------------------------------------------------------------------------------------
253 
254 
255 //--------------------------------------------------------------------------------------------------
256 /**
257  * Reference type used by Add/Remove functions for EVENT 'le_atClient_UnsolicitedResponse'
258  */
259 //--------------------------------------------------------------------------------------------------
260 
261 
262 //--------------------------------------------------------------------------------------------------
263 /**
264  * This function must be called to start a ATClient session on a specified device.
265  *
266  * @return reference on a device context
267  */
268 //--------------------------------------------------------------------------------------------------
269 le_atClient_DeviceRef_t le_atClient_Start
270 (
271  int fd
272  ///< [IN] File descriptor.
273 );
274 
275 //--------------------------------------------------------------------------------------------------
276 /**
277  * This function must be called to stop the ATClient session on the specified device.
278  *
279  * @return
280  * - LE_FAULT when function failed
281  * - LE_OK when function succeed
282  */
283 //--------------------------------------------------------------------------------------------------
285 (
286  le_atClient_DeviceRef_t device
287  ///< [IN] Device reference
288 );
289 
290 //--------------------------------------------------------------------------------------------------
291 /**
292  * This function must be called to create a new AT command.
293  *
294  * @return pointer to the new AT Command reference
295  */
296 //--------------------------------------------------------------------------------------------------
297 le_atClient_CmdRef_t le_atClient_Create
298 (
299  void
300 );
301 
302 //--------------------------------------------------------------------------------------------------
303 /**
304  * This function must be called to delete an AT command reference.
305  *
306  * @return
307  * - LE_OK when function succeed
308  *
309  * @note If the AT Command reference is invalid, a fatal error occurs,
310  * the function won't return.
311  */
312 //--------------------------------------------------------------------------------------------------
314 (
315  le_atClient_CmdRef_t cmdRef
316  ///< [IN] AT Command
317 );
318 
319 //--------------------------------------------------------------------------------------------------
320 /**
321  * This function must be called to set the AT command string to be sent.
322  *
323  * @return
324  * - LE_OK when function succeed
325  *
326  * @note If the AT Command reference is invalid, a fatal error occurs,
327  * the function won't return.
328  */
329 //--------------------------------------------------------------------------------------------------
331 (
332  le_atClient_CmdRef_t cmdRef,
333  ///< [IN] AT Command
334  const char* LE_NONNULL command
335  ///< [IN] Set Command
336 );
337 
338 //--------------------------------------------------------------------------------------------------
339 /**
340  * This function must be called to set the waiting intermediate responses.
341  * Several intermediate responses can be specified separated by a '|' character into the string
342  * given in parameter.
343  *
344  * @return
345  * - LE_FAULT when function failed
346  * - LE_OK when function succeed
347  *
348  * @note If the AT Command reference or set intermediate response is invalid, a fatal error occurs,
349  * the function won't return.
350  */
351 //--------------------------------------------------------------------------------------------------
353 (
354  le_atClient_CmdRef_t cmdRef,
355  ///< [IN] AT Command
356  const char* LE_NONNULL intermediate
357  ///< [IN] Set Intermediate
358 );
359 
360 //--------------------------------------------------------------------------------------------------
361 /**
362  * This function must be called to set the final response(s) of the AT command execution.
363  * Several final responses can be specified separated by a '|' character into the string given in
364  * parameter.
365  *
366  * @return
367  * - LE_FAULT when function failed
368  * - LE_OK when function succeed
369  *
370  * @note If the AT Command reference or set response is invalid, a fatal error occurs,
371  * the function won't return.
372  */
373 //--------------------------------------------------------------------------------------------------
375 (
376  le_atClient_CmdRef_t cmdRef,
377  ///< [IN] AT Command
378  const char* LE_NONNULL response
379  ///< [IN] Set Response
380 );
381 
382 //--------------------------------------------------------------------------------------------------
383 /**
384  * This function must be called to set the text when the prompt is expected.
385  *
386  * @return
387  * - LE_FAULT when function failed
388  * - LE_OK when function succeed
389  *
390  * @note If the AT Command reference is invalid, a fatal error occurs,
391  * the function won't return.
392  */
393 //--------------------------------------------------------------------------------------------------
395 (
396  le_atClient_CmdRef_t cmdRef,
397  ///< [IN] AT Command
398  const char* LE_NONNULL text
399  ///< [IN] The AT Data to send
400 );
401 
402 //--------------------------------------------------------------------------------------------------
403 /**
404  * This function must be called to set the timeout of the AT command execution.
405  *
406  * @return
407  * - LE_OK when function succeed
408  *
409  * @note If the AT Command reference is invalid, a fatal error occurs,
410  * the function won't return.
411  */
412 //--------------------------------------------------------------------------------------------------
414 (
415  le_atClient_CmdRef_t cmdRef,
416  ///< [IN] AT Command
417  uint32_t timer
418  ///< [IN] The timeout value in milliseconds.
419 );
420 
421 //--------------------------------------------------------------------------------------------------
422 /**
423  * This function must be called to set the device where the AT command will be sent.
424  *
425  * @return
426  * - LE_FAULT when function failed
427  * - LE_OK when function succeed
428  *
429  * @note If the AT Command reference is invalid, a fatal error occurs,
430  * the function won't return.
431  */
432 //--------------------------------------------------------------------------------------------------
434 (
435  le_atClient_CmdRef_t cmdRef,
436  ///< [IN] AT Command
437  le_atClient_DeviceRef_t devRef
438  ///< [IN] Device where the AT command has to be sent
439 );
440 
441 //--------------------------------------------------------------------------------------------------
442 /**
443  * This function must be called to send an AT Command and wait for response.
444  *
445  * @return
446  * - LE_FAULT when function failed
447  * - LE_TIMEOUT when a timeout occur
448  * - LE_OK when function succeed
449  *
450  * @note If the AT Command reference is invalid, a fatal error occurs,
451  * the function won't return.
452  */
453 //--------------------------------------------------------------------------------------------------
455 (
456  le_atClient_CmdRef_t cmdRef
457  ///< [IN] AT Command
458 );
459 
460 //--------------------------------------------------------------------------------------------------
461 /**
462  * This function is used to get the first intermediate response.
463  *
464  * @return
465  * - LE_FAULT when function failed
466  * - LE_OK when function succeed
467  *
468  * @note If the AT Command reference is invalid, a fatal error occurs,
469  * the function won't return.
470  */
471 //--------------------------------------------------------------------------------------------------
473 (
474  le_atClient_CmdRef_t cmdRef,
475  ///< [IN] AT Command
476  char* intermediateRsp,
477  ///< [OUT] First intermediate result code
478  size_t intermediateRspSize
479  ///< [IN]
480 );
481 
482 //--------------------------------------------------------------------------------------------------
483 /**
484  * This function is used to get the next intermediate response.
485  *
486  * @return
487  * - LE_NOT_FOUND when there are no further results
488  * - LE_OK when function succeed
489  *
490  * @note If the AT Command reference is invalid, a fatal error occurs,
491  * the function won't return.
492  */
493 //--------------------------------------------------------------------------------------------------
495 (
496  le_atClient_CmdRef_t cmdRef,
497  ///< [IN] AT Command
498  char* intermediateRsp,
499  ///< [OUT] Get Next intermediate result
500  ///< code.
501  size_t intermediateRspSize
502  ///< [IN]
503 );
504 
505 //--------------------------------------------------------------------------------------------------
506 /**
507  * This function is used to get the final response
508  *
509  * @return
510  * - LE_FAULT when function failed
511  * - LE_OK when function succeed
512  *
513  * @note If the AT Command reference is invalid, a fatal error occurs,
514  * the function won't return.
515  */
516 //--------------------------------------------------------------------------------------------------
518 (
519  le_atClient_CmdRef_t cmdRef,
520  ///< [IN] AT Command
521  char* finalRsp,
522  ///< [OUT] Get Final Line
523  size_t finalRspSize
524  ///< [IN]
525 );
526 
527 //--------------------------------------------------------------------------------------------------
528 /**
529  * This function must be called to automatically set and send an AT Command.
530  *
531  * @return
532  * - LE_FAULT when function failed
533  * - LE_TIMEOUT when a timeout occur
534  * - LE_OK when function succeed
535  *
536  * @note This command creates a command reference when called
537  *
538  * @note In case of an Error the command reference will be deleted and though
539  * not usable. Make sure to test the return code and not use the reference
540  * in other functions.
541  *
542  * @note If the AT command is invalid, a fatal error occurs,
543  * the function won't return.
544  *
545  */
546 //--------------------------------------------------------------------------------------------------
548 (
549  le_atClient_CmdRef_t* cmdRefPtr,
550  ///< [OUT] Cmd reference
551  le_atClient_DeviceRef_t devRef,
552  ///< [IN] Dev reference
553  const char* LE_NONNULL command,
554  ///< [IN] AT Command
555  const char* LE_NONNULL interResp,
556  ///< [IN] Expected intermediate response
557  const char* LE_NONNULL finalResp,
558  ///< [IN] Expected final response
559  uint32_t timeout
560  ///< [IN] Timeout value in milliseconds.
561 );
562 
563 //--------------------------------------------------------------------------------------------------
564 /**
565  * Add handler function for EVENT 'le_atClient_UnsolicitedResponse'
566  *
567  * This event provides information on a subscribed unsolicited response when this unsolicited
568  * response is received.
569  *
570  */
571 //--------------------------------------------------------------------------------------------------
573 (
574  const char* LE_NONNULL unsolRsp,
575  ///< [IN] Pattern to match
576  le_atClient_DeviceRef_t devRef,
577  ///< [IN] Device to listen
579  ///< [IN] unsolicited handler
580  void* contextPtr,
581  ///< [IN]
582  uint32_t lineCount
583  ///< [IN] Indicate the number of line of
584  ///< the unsolicited
585 );
586 
587 //--------------------------------------------------------------------------------------------------
588 /**
589  * Remove handler function for EVENT 'le_atClient_UnsolicitedResponse'
590  */
591 //--------------------------------------------------------------------------------------------------
593 (
595  ///< [IN]
596 );
597 
598 /** @} **/
599 
600 #endif // LE_ATCLIENT_INTERFACE_H_INCLUDE_GUARD
le_result_t le_atClient_SetIntermediateResponse(le_atClient_CmdRef_t cmdRef, const char *LE_NONNULL intermediate)
le_result_t le_atClient_Send(le_atClient_CmdRef_t cmdRef)
le_result_t
Definition: le_basics.h:46
le_result_t le_atClient_TryConnectService(void)
le_result_t le_atClient_SetTimeout(le_atClient_CmdRef_t cmdRef, uint32_t timer)
le_atClient_DeviceRef_t le_atClient_Start(int fd)
le_result_t le_atClient_Stop(le_atClient_DeviceRef_t device)
le_result_t le_atClient_GetFinalResponse(le_atClient_CmdRef_t cmdRef, char *finalRsp, size_t finalRspSize)
le_result_t le_atClient_GetNextIntermediateResponse(le_atClient_CmdRef_t cmdRef, char *intermediateRsp, size_t intermediateRspSize)
LE_FULL_API void le_atClient_SetServerDisconnectHandler(le_atClient_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_atClient_Delete(le_atClient_CmdRef_t cmdRef)
le_result_t le_atClient_SetText(le_atClient_CmdRef_t cmdRef, const char *LE_NONNULL text)
void(* le_atClient_UnsolicitedResponseHandlerFunc_t)(const char *LE_NONNULL unsolicitedRsp, void *contextPtr)
Definition: le_atClient_common.h:60
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_atClient_UnsolicitedResponseHandlerRef_t le_atClient_AddUnsolicitedResponseHandler(const char *LE_NONNULL unsolRsp, le_atClient_DeviceRef_t devRef, le_atClient_UnsolicitedResponseHandlerFunc_t handlerPtr, void *contextPtr, uint32_t lineCount)
struct le_atClient_UnsolicitedResponseHandler * le_atClient_UnsolicitedResponseHandlerRef_t
Definition: le_atClient_common.h:50
void le_atClient_DisconnectService(void)
le_result_t le_atClient_SetDevice(le_atClient_CmdRef_t cmdRef, le_atClient_DeviceRef_t devRef)
void le_atClient_RemoveUnsolicitedResponseHandler(le_atClient_UnsolicitedResponseHandlerRef_t handlerRef)
le_result_t le_atClient_SetCommandAndSend(le_atClient_CmdRef_t *cmdRefPtr, le_atClient_DeviceRef_t devRef, const char *LE_NONNULL command, const char *LE_NONNULL interResp, const char *LE_NONNULL finalResp, uint32_t timeout)
le_atClient_CmdRef_t le_atClient_Create(void)
le_result_t le_atClient_SetFinalResponse(le_atClient_CmdRef_t cmdRef, const char *LE_NONNULL response)
le_result_t le_atClient_GetFirstIntermediateResponse(le_atClient_CmdRef_t cmdRef, char *intermediateRsp, size_t intermediateRspSize)
void le_atClient_ConnectService(void)
le_result_t le_atClient_SetCommand(le_atClient_CmdRef_t cmdRef, const char *LE_NONNULL command)
void(* le_atClient_DisconnectHandler_t)(void *)
Definition: le_atClient_interface.h:158