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 //--------------------------------------------------------------------------------------------------
150 /**
151  * Type for handler called when a server disconnects.
152  */
153 //--------------------------------------------------------------------------------------------------
154 typedef void (*le_atClient_DisconnectHandler_t)(void *);
155 
156 //--------------------------------------------------------------------------------------------------
157 /**
158  *
159  * Connect the current client thread to the service providing this API. Block until the service is
160  * available.
161  *
162  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
163  * called before any other functions in this API. Normally, ConnectService is automatically called
164  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
165  *
166  * This function is created automatically.
167  */
168 //--------------------------------------------------------------------------------------------------
170 (
171  void
172 );
173 
174 //--------------------------------------------------------------------------------------------------
175 /**
176  *
177  * Try to connect the current client thread to the service providing this API. Return with an error
178  * if the service is not available.
179  *
180  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
181  * called before any other functions in this API. Normally, ConnectService is automatically called
182  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
183  *
184  * This function is created automatically.
185  *
186  * @return
187  * - LE_OK if the client connected successfully to the service.
188  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
189  * bound.
190  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
191  * - LE_COMM_ERROR if the Service Directory cannot be reached.
192  */
193 //--------------------------------------------------------------------------------------------------
195 (
196  void
197 );
198 
199 //--------------------------------------------------------------------------------------------------
200 /**
201  * Set handler called when server disconnection is detected.
202  *
203  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
204  * to continue without exiting, it should call longjmp() from inside the handler.
205  */
206 //--------------------------------------------------------------------------------------------------
208 (
209  le_atClient_DisconnectHandler_t disconnectHandler,
210  void *contextPtr
211 );
212 
213 //--------------------------------------------------------------------------------------------------
214 /**
215  *
216  * Disconnect the current client thread from the service providing this API.
217  *
218  * Normally, this function doesn't need to be called. After this function is called, there's no
219  * longer a connection to the service, and the functions in this API can't be used. For details, see
220  * @ref apiFilesC_client.
221  *
222  * This function is created automatically.
223  */
224 //--------------------------------------------------------------------------------------------------
226 (
227  void
228 );
229 
230 
231 //--------------------------------------------------------------------------------------------------
232 /**
233  */
234 //--------------------------------------------------------------------------------------------------
235 
236 
237 //--------------------------------------------------------------------------------------------------
238 /**
239  */
240 //--------------------------------------------------------------------------------------------------
241 
242 
243 //--------------------------------------------------------------------------------------------------
244 /**
245  * Handler for unsolicited response reception.
246  *
247  */
248 //--------------------------------------------------------------------------------------------------
249 
250 
251 //--------------------------------------------------------------------------------------------------
252 /**
253  * Reference type used by Add/Remove functions for EVENT 'le_atClient_UnsolicitedResponse'
254  */
255 //--------------------------------------------------------------------------------------------------
256 
257 
258 //--------------------------------------------------------------------------------------------------
259 /**
260  * This function must be called to start a ATClient session on a specified device.
261  *
262  * @return reference on a device context
263  */
264 //--------------------------------------------------------------------------------------------------
265 le_atClient_DeviceRef_t le_atClient_Start
266 (
267  int fd
268  ///< [IN] File descriptor.
269 );
270 
271 //--------------------------------------------------------------------------------------------------
272 /**
273  * This function must be called to stop the ATClient session on the specified device.
274  *
275  * @return
276  * - LE_FAULT when function failed
277  * - LE_OK when function succeed
278  */
279 //--------------------------------------------------------------------------------------------------
281 (
282  le_atClient_DeviceRef_t device
283  ///< [IN] Device reference
284 );
285 
286 //--------------------------------------------------------------------------------------------------
287 /**
288  * This function must be called to create a new AT command.
289  *
290  * @return pointer to the new AT Command reference
291  */
292 //--------------------------------------------------------------------------------------------------
293 le_atClient_CmdRef_t le_atClient_Create
294 (
295  void
296 );
297 
298 //--------------------------------------------------------------------------------------------------
299 /**
300  * This function must be called to delete an AT command reference.
301  *
302  * @return
303  * - LE_OK when function succeed
304  *
305  * @note If the AT Command reference is invalid, a fatal error occurs,
306  * the function won't return.
307  */
308 //--------------------------------------------------------------------------------------------------
310 (
311  le_atClient_CmdRef_t cmdRef
312  ///< [IN] AT Command
313 );
314 
315 //--------------------------------------------------------------------------------------------------
316 /**
317  * This function must be called to set the AT command string to be sent.
318  *
319  * @return
320  * - LE_OK when function succeed
321  *
322  * @note If the AT Command reference is invalid, a fatal error occurs,
323  * the function won't return.
324  */
325 //--------------------------------------------------------------------------------------------------
327 (
328  le_atClient_CmdRef_t cmdRef,
329  ///< [IN] AT Command
330  const char* LE_NONNULL command
331  ///< [IN] Set Command
332 );
333 
334 //--------------------------------------------------------------------------------------------------
335 /**
336  * This function must be called to set the waiting intermediate responses.
337  * Several intermediate responses can be specified separated by a '|' character into the string
338  * given in parameter.
339  *
340  * @return
341  * - LE_FAULT when function failed
342  * - LE_OK when function succeed
343  *
344  * @note If the AT Command reference or set intermediate response is invalid, a fatal error occurs,
345  * the function won't return.
346  */
347 //--------------------------------------------------------------------------------------------------
349 (
350  le_atClient_CmdRef_t cmdRef,
351  ///< [IN] AT Command
352  const char* LE_NONNULL intermediate
353  ///< [IN] Set Intermediate
354 );
355 
356 //--------------------------------------------------------------------------------------------------
357 /**
358  * This function must be called to set the final response(s) of the AT command execution.
359  * Several final responses can be specified separated by a '|' character into the string given in
360  * parameter.
361  *
362  * @return
363  * - LE_FAULT when function failed
364  * - LE_OK when function succeed
365  *
366  * @note If the AT Command reference or set response is invalid, a fatal error occurs,
367  * the function won't return.
368  */
369 //--------------------------------------------------------------------------------------------------
371 (
372  le_atClient_CmdRef_t cmdRef,
373  ///< [IN] AT Command
374  const char* LE_NONNULL response
375  ///< [IN] Set Response
376 );
377 
378 //--------------------------------------------------------------------------------------------------
379 /**
380  * This function must be called to set the text when the prompt is expected.
381  *
382  * @return
383  * - LE_FAULT when function failed
384  * - LE_OK when function succeed
385  *
386  * @note If the AT Command reference is invalid, a fatal error occurs,
387  * the function won't return.
388  */
389 //--------------------------------------------------------------------------------------------------
391 (
392  le_atClient_CmdRef_t cmdRef,
393  ///< [IN] AT Command
394  const char* LE_NONNULL text
395  ///< [IN] The AT Data to send
396 );
397 
398 //--------------------------------------------------------------------------------------------------
399 /**
400  * This function must be called to set the timeout of the AT command execution.
401  *
402  * @return
403  * - LE_OK when function succeed
404  *
405  * @note If the AT Command reference is invalid, a fatal error occurs,
406  * the function won't return.
407  */
408 //--------------------------------------------------------------------------------------------------
410 (
411  le_atClient_CmdRef_t cmdRef,
412  ///< [IN] AT Command
413  uint32_t timer
414  ///< [IN] The timeout value in milliseconds.
415 );
416 
417 //--------------------------------------------------------------------------------------------------
418 /**
419  * This function must be called to set the device where the AT command will be sent.
420  *
421  * @return
422  * - LE_FAULT when function failed
423  * - LE_OK when function succeed
424  *
425  * @note If the AT Command reference is invalid, a fatal error occurs,
426  * the function won't return.
427  */
428 //--------------------------------------------------------------------------------------------------
430 (
431  le_atClient_CmdRef_t cmdRef,
432  ///< [IN] AT Command
433  le_atClient_DeviceRef_t devRef
434  ///< [IN] Device where the AT command has to be sent
435 );
436 
437 //--------------------------------------------------------------------------------------------------
438 /**
439  * This function must be called to send an AT Command and wait for response.
440  *
441  * @return
442  * - LE_FAULT when function failed
443  * - LE_TIMEOUT when a timeout occur
444  * - LE_OK when function succeed
445  *
446  * @note If the AT Command reference is invalid, a fatal error occurs,
447  * the function won't return.
448  */
449 //--------------------------------------------------------------------------------------------------
451 (
452  le_atClient_CmdRef_t cmdRef
453  ///< [IN] AT Command
454 );
455 
456 //--------------------------------------------------------------------------------------------------
457 /**
458  * This function is used to get the first intermediate response.
459  *
460  * @return
461  * - LE_FAULT when function failed
462  * - LE_OK when function succeed
463  *
464  * @note If the AT Command reference is invalid, a fatal error occurs,
465  * the function won't return.
466  */
467 //--------------------------------------------------------------------------------------------------
469 (
470  le_atClient_CmdRef_t cmdRef,
471  ///< [IN] AT Command
472  char* intermediateRsp,
473  ///< [OUT] First intermediate result code
474  size_t intermediateRspSize
475  ///< [IN]
476 );
477 
478 //--------------------------------------------------------------------------------------------------
479 /**
480  * This function is used to get the next intermediate response.
481  *
482  * @return
483  * - LE_NOT_FOUND when there are no further results
484  * - LE_OK when function succeed
485  *
486  * @note If the AT Command reference is invalid, a fatal error occurs,
487  * the function won't return.
488  */
489 //--------------------------------------------------------------------------------------------------
491 (
492  le_atClient_CmdRef_t cmdRef,
493  ///< [IN] AT Command
494  char* intermediateRsp,
495  ///< [OUT] Get Next intermediate result
496  ///< code.
497  size_t intermediateRspSize
498  ///< [IN]
499 );
500 
501 //--------------------------------------------------------------------------------------------------
502 /**
503  * This function is used to get the final response
504  *
505  * @return
506  * - LE_FAULT when function failed
507  * - LE_OK when function succeed
508  *
509  * @note If the AT Command reference is invalid, a fatal error occurs,
510  * the function won't return.
511  */
512 //--------------------------------------------------------------------------------------------------
514 (
515  le_atClient_CmdRef_t cmdRef,
516  ///< [IN] AT Command
517  char* finalRsp,
518  ///< [OUT] Get Final Line
519  size_t finalRspSize
520  ///< [IN]
521 );
522 
523 //--------------------------------------------------------------------------------------------------
524 /**
525  * This function must be called to automatically set and send an AT Command.
526  *
527  * @return
528  * - LE_FAULT when function failed
529  * - LE_TIMEOUT when a timeout occur
530  * - LE_OK when function succeed
531  *
532  * @note This command creates a command reference when called
533  *
534  * @note In case of an Error the command reference will be deleted and though
535  * not usable. Make sure to test the return code and not use the reference
536  * in other functions.
537  *
538  * @note If the AT command is invalid, a fatal error occurs,
539  * the function won't return.
540  *
541  */
542 //--------------------------------------------------------------------------------------------------
544 (
545  le_atClient_CmdRef_t* cmdRefPtr,
546  ///< [OUT] Cmd reference
547  le_atClient_DeviceRef_t devRef,
548  ///< [IN] Dev reference
549  const char* LE_NONNULL command,
550  ///< [IN] AT Command
551  const char* LE_NONNULL interResp,
552  ///< [IN] Expected intermediate response
553  const char* LE_NONNULL finalResp,
554  ///< [IN] Expected final response
555  uint32_t timeout
556  ///< [IN] Timeout value in milliseconds.
557 );
558 
559 //--------------------------------------------------------------------------------------------------
560 /**
561  * Add handler function for EVENT 'le_atClient_UnsolicitedResponse'
562  *
563  * This event provides information on a subscribed unsolicited response when this unsolicited
564  * response is received.
565  *
566  */
567 //--------------------------------------------------------------------------------------------------
568 le_atClient_UnsolicitedResponseHandlerRef_t le_atClient_AddUnsolicitedResponseHandler
569 (
570  const char* LE_NONNULL unsolRsp,
571  ///< [IN] Pattern to match
572  le_atClient_DeviceRef_t devRef,
573  ///< [IN] Device to listen
574  le_atClient_UnsolicitedResponseHandlerFunc_t handlerPtr,
575  ///< [IN] unsolicited handler
576  void* contextPtr,
577  ///< [IN]
578  uint32_t lineCount
579  ///< [IN] Indicate the number of line of
580  ///< the unsolicited
581 );
582 
583 //--------------------------------------------------------------------------------------------------
584 /**
585  * Remove handler function for EVENT 'le_atClient_UnsolicitedResponse'
586  */
587 //--------------------------------------------------------------------------------------------------
589 (
590  le_atClient_UnsolicitedResponseHandlerRef_t handlerRef
591  ///< [IN]
592 );
593 
594 #endif // LE_ATCLIENT_INTERFACE_H_INCLUDE_GUARD
le_result_t le_atClient_TryConnectService(void)
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)
le_result_t le_atClient_SetTimeout(le_atClient_CmdRef_t cmdRef, uint32_t timer)
le_result_t
Definition: le_basics.h:35
le_result_t le_atClient_SetText(le_atClient_CmdRef_t cmdRef, const char *LE_NONNULL text)
le_result_t le_atClient_SetIntermediateResponse(le_atClient_CmdRef_t cmdRef, const char *LE_NONNULL intermediate)
le_result_t le_atClient_Delete(le_atClient_CmdRef_t cmdRef)
le_atClient_DeviceRef_t le_atClient_Start(int fd)
le_result_t le_atClient_GetNextIntermediateResponse(le_atClient_CmdRef_t cmdRef, char *intermediateRsp, size_t intermediateRspSize)
void(* le_atClient_DisconnectHandler_t)(void *)
Definition: le_atClient_interface.h:154
le_result_t le_atClient_SetDevice(le_atClient_CmdRef_t cmdRef, le_atClient_DeviceRef_t devRef)
LE_FULL_API void le_atClient_SetServerDisconnectHandler(le_atClient_DisconnectHandler_t disconnectHandler, void *contextPtr)
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)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_atClient_CmdRef_t le_atClient_Create(void)
le_result_t le_atClient_GetFinalResponse(le_atClient_CmdRef_t cmdRef, char *finalRsp, size_t finalRspSize)
le_result_t le_atClient_Send(le_atClient_CmdRef_t cmdRef)
le_result_t le_atClient_Stop(le_atClient_DeviceRef_t device)
void le_atClient_RemoveUnsolicitedResponseHandler(le_atClient_UnsolicitedResponseHandlerRef_t handlerRef)
le_result_t le_atClient_SetFinalResponse(le_atClient_CmdRef_t cmdRef, const char *LE_NONNULL response)
void le_atClient_ConnectService(void)
le_result_t le_atClient_GetFirstIntermediateResponse(le_atClient_CmdRef_t cmdRef, char *intermediateRsp, size_t intermediateRspSize)
void le_atClient_DisconnectService(void)
le_result_t le_atClient_SetCommand(le_atClient_CmdRef_t cmdRef, const char *LE_NONNULL command)