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