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