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* LE_NONNULL 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* LE_NONNULL command
334  ///< [IN] Set Command
335 );
336 
337 //--------------------------------------------------------------------------------------------------
338 /**
339  * This function must be called to set the waiting intermediate responses.
340  * Several intermediate responses can be specified separated by a '|' character into the string
341  * given in parameter.
342  *
343  * @return
344  * - LE_FAULT when function failed
345  * - LE_OK when function succeed
346  *
347  * @note If the AT Command reference or set intermediate response is invalid, a fatal error occurs,
348  * the function won't return.
349  */
350 //--------------------------------------------------------------------------------------------------
352 (
353  le_atClient_CmdRef_t cmdRef,
354  ///< [IN] AT Command
355  const char* LE_NONNULL intermediate
356  ///< [IN] Set Intermediate
357 );
358 
359 //--------------------------------------------------------------------------------------------------
360 /**
361  * This function must be called to set the final response(s) of the AT command execution.
362  * Several final responses can be specified separated by a '|' character into the string given in
363  * parameter.
364  *
365  * @return
366  * - LE_FAULT when function failed
367  * - LE_OK when function succeed
368  *
369  * @note If the AT Command reference or set response is invalid, a fatal error occurs,
370  * the function won't return.
371  */
372 //--------------------------------------------------------------------------------------------------
374 (
375  le_atClient_CmdRef_t cmdRef,
376  ///< [IN] AT Command
377  const char* LE_NONNULL response
378  ///< [IN] Set Response
379 );
380 
381 //--------------------------------------------------------------------------------------------------
382 /**
383  * This function must be called to set the text when the prompt is expected.
384  *
385  * @return
386  * - LE_FAULT when function failed
387  * - LE_OK when function succeed
388  *
389  * @note If the AT Command reference is invalid, a fatal error occurs,
390  * the function won't return.
391  */
392 //--------------------------------------------------------------------------------------------------
394 (
395  le_atClient_CmdRef_t cmdRef,
396  ///< [IN] AT Command
397  const char* LE_NONNULL text
398  ///< [IN] The AT Data to send
399 );
400 
401 //--------------------------------------------------------------------------------------------------
402 /**
403  * This function must be called to set the timeout of the AT command execution.
404  *
405  * @return
406  * - LE_OK when function succeed
407  *
408  * @note If the AT Command reference is invalid, a fatal error occurs,
409  * the function won't return.
410  */
411 //--------------------------------------------------------------------------------------------------
413 (
414  le_atClient_CmdRef_t cmdRef,
415  ///< [IN] AT Command
416  uint32_t timer
417  ///< [IN] The timeout value in milliseconds.
418 );
419 
420 //--------------------------------------------------------------------------------------------------
421 /**
422  * This function must be called to set the device where the AT command will be sent.
423  *
424  * @return
425  * - LE_FAULT when function failed
426  * - LE_OK when function succeed
427  *
428  * @note If the AT Command reference is invalid, a fatal error occurs,
429  * the function won't return.
430  */
431 //--------------------------------------------------------------------------------------------------
433 (
434  le_atClient_CmdRef_t cmdRef,
435  ///< [IN] AT Command
436  le_atClient_DeviceRef_t devRef
437  ///< [IN] Device where the AT command has to be sent
438 );
439 
440 //--------------------------------------------------------------------------------------------------
441 /**
442  * This function must be called to send an AT Command and wait for response.
443  *
444  * @return
445  * - LE_FAULT when function failed
446  * - LE_TIMEOUT when a timeout occur
447  * - LE_OK when function succeed
448  *
449  * @note If the AT Command reference is invalid, a fatal error occurs,
450  * the function won't return.
451  */
452 //--------------------------------------------------------------------------------------------------
454 (
455  le_atClient_CmdRef_t cmdRef
456  ///< [IN] AT Command
457 );
458 
459 //--------------------------------------------------------------------------------------------------
460 /**
461  * This function is used to get the first intermediate response.
462  *
463  * @return
464  * - LE_FAULT when function failed
465  * - LE_OK when function succeed
466  *
467  * @note If the AT Command reference is invalid, a fatal error occurs,
468  * the function won't return.
469  */
470 //--------------------------------------------------------------------------------------------------
472 (
473  le_atClient_CmdRef_t cmdRef,
474  ///< [IN] AT Command
475  char* intermediateRsp,
476  ///< [OUT] First intermediate result code
477  size_t intermediateRspSize
478  ///< [IN]
479 );
480 
481 //--------------------------------------------------------------------------------------------------
482 /**
483  * This function is used to get the next intermediate response.
484  *
485  * @return
486  * - LE_NOT_FOUND when there are no further results
487  * - LE_OK when function succeed
488  *
489  * @note If the AT Command reference is invalid, a fatal error occurs,
490  * the function won't return.
491  */
492 //--------------------------------------------------------------------------------------------------
494 (
495  le_atClient_CmdRef_t cmdRef,
496  ///< [IN] AT Command
497  char* intermediateRsp,
498  ///< [OUT] Get Next intermediate result
499  ///< code.
500  size_t intermediateRspSize
501  ///< [IN]
502 );
503 
504 //--------------------------------------------------------------------------------------------------
505 /**
506  * This function is used to get the final response
507  *
508  * @return
509  * - LE_FAULT when function failed
510  * - LE_OK when function succeed
511  *
512  * @note If the AT Command reference is invalid, a fatal error occurs,
513  * the function won't return.
514  */
515 //--------------------------------------------------------------------------------------------------
517 (
518  le_atClient_CmdRef_t cmdRef,
519  ///< [IN] AT Command
520  char* finalRsp,
521  ///< [OUT] Get Final Line
522  size_t finalRspSize
523  ///< [IN]
524 );
525 
526 //--------------------------------------------------------------------------------------------------
527 /**
528  * This function must be called to automatically set and send an AT Command.
529  *
530  * @return
531  * - LE_FAULT when function failed
532  * - LE_TIMEOUT when a timeout occur
533  * - LE_OK when function succeed
534  *
535  * @note This command creates a command reference when called
536  *
537  * @note In case of an Error the command reference will be deleted and though
538  * not usable. Make sure to test the return code and not use the reference
539  * in other functions.
540  *
541  * @note If the AT command is invalid, a fatal error occurs,
542  * the function won't return.
543  *
544  */
545 //--------------------------------------------------------------------------------------------------
547 (
548  le_atClient_CmdRef_t* cmdRefPtr,
549  ///< [OUT] Cmd reference
550  le_atClient_DeviceRef_t devRef,
551  ///< [IN] Dev reference
552  const char* LE_NONNULL command,
553  ///< [IN] AT Command
554  const char* LE_NONNULL interResp,
555  ///< [IN] Expected intermediate response
556  const char* LE_NONNULL finalResp,
557  ///< [IN] Expected final response
558  uint32_t timeout
559  ///< [IN] Timeout value in milliseconds.
560 );
561 
562 //--------------------------------------------------------------------------------------------------
563 /**
564  * Add handler function for EVENT 'le_atClient_UnsolicitedResponse'
565  *
566  * This event provides information on a subscribed unsolicited response when this unsolicited
567  * response is received.
568  *
569  */
570 //--------------------------------------------------------------------------------------------------
572 (
573  const char* LE_NONNULL unsolRsp,
574  ///< [IN] Pattern to match
575  le_atClient_DeviceRef_t devRef,
576  ///< [IN] Device to listen
578  ///< [IN] unsolicited handler
579  void* contextPtr,
580  ///< [IN]
581  uint32_t lineCount
582  ///< [IN] Indicate the number of line of
583  ///< the unsolicited
584 );
585 
586 //--------------------------------------------------------------------------------------------------
587 /**
588  * Remove handler function for EVENT 'le_atClient_UnsolicitedResponse'
589  */
590 //--------------------------------------------------------------------------------------------------
592 (
594  ///< [IN]
595 );
596 
597 #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:254
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:148
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:244
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)