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