le_voicecall_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_le_voicecall Voice Call Service
14  *
15  * @ref le_voicecall_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * A voice call is needed for applications that want to establish a voice communication with
20  * a remote party. The voice call can be over a mobile network, or over VoIP.
21  *
22  * @section le_voicecall_binding IPC interfaces binding
23  *
24  * All the functions of this API are provided by the @b voiceCallService application service.
25  *
26  * Here's a code sample binding to Voice Call services:
27  * @verbatim
28  bindings:
29  {
30  clientExe.clientComponent.le_voicecall -> voiceCallService.le_voicecall
31  }
32  @endverbatim
33  *
34  * @section c_le_voicecall_outgoing Starting a Voice call
35  *
36  * A voice call can be started using le_voicecall_Start() with the destination identifier passed as
37  * a parameter.
38  *
39  * @snippet "apps/sample/voiceCallApp/voiceCallComponent/voiceCallApp.c" Starting a voicecall
40  *
41  * @note Available interfaces depend on used platform.
42  *
43  * Before the voice call is started, an application registers a state handler using
44  * le_voicecall_AddStateHandler(). Once the voice call is established, the handler will be called
45  * indicating it's now connected. If the state of the voice call changes, then the handler will be
46  * called with the new state.
47  *
48  * @snippet "apps/sample/voiceCallApp/voiceCallComponent/voiceCallApp.c" AddStateHandler
49  *
50  * To release a voice call, an application can use le_voicecall_End().
51  *
52  * @snippet "apps/sample/voiceCallApp/voiceCallComponent/voiceCallApp.c" Ending a voicecall
53  *
54  * Application must use le_voicecall_Delete() to release @ref le_voicecall_CallRef_t voice call
55  * reference object when it is no more used.
56  *
57  * If le_voicecall_End() failed a @ref LE_VOICECALL_EVENT_CALL_END_FAILED event will be sent.
58  *
59  * If a voice call is already started when le_voicecall_Start() is called(), a
60  * new voice call will not be established. Instead, @ref LE_VOICECALL_EVENT_RESOURCE_BUSY event
61  * will be sent. This event means call was not processed, while a
62  * @ref LE_VOICECALL_EVENT_TERMINATED event means that the call was not processed and then
63  * terminated or failed.
64  *
65  * Once an application makes a voice call request, it should monitor the establishment state
66  * reported to the registered state handler.
67  *
68  * Once the @ref LE_VOICECALL_EVENT_CONNECTED voice call event is received by the application, it
69  * must get the Rx and Tx audio streams with le_voicecall_GetRxAudioStream() and
70  * le_voicecall_GetTxAudioStream() functions in order to set up the audio path. The audio path
71  * can be set up thanks to the audio API (cf. @ref c_audio). An example of how to set up the audio path:
72  *
73  * @snippet "apps/sample/voiceCallApp/voiceCallComponent/voiceCallApp.c" setup audio path
74  *
75  *
76  * If a @ref LE_VOICECALL_EVENT_TERMINATED event is received, application can get the termination
77  * reason by using le_voicecall_GetTerminationReason().
78  *
79  * @note The voice call use the mobile network. VoIP is not yet supported.
80  *
81  * @section c_le_voicecall_incoming Answering a Voice call
82  *
83  * An Incoming voice call will be notified by an @ref LE_VOICECALL_EVENT_INCOMING event on state
84  * handler with a Call reference le_voicecall_CallRef_t().
85  *
86  * Application can answer the call by using le_voicecall_Answer() or reject the call by using
87  * le_voicecall_End() passing the call reference @ref le_voicecall_CallRef_t.
88  *
89  * @snippet "apps/sample/voiceCallApp/voiceCallComponent/voiceCallApp.c" answer
90  *
91  * If le_voicecall_End() failed a @ref LE_VOICECALL_EVENT_CALL_END_FAILED event will be sent. If
92  * le_voicecall_Answer() failed a @ref LE_VOICECALL_EVENT_CALL_ANSWER_FAILED event will be sent.
93  *
94  * Application have to use le_voicecall_Delete() to release @ref le_voicecall_CallRef_t voice call
95  * reference object when it is no more used.
96  *
97  * <HR>
98  *
99  * Copyright (C) Sierra Wireless Inc.
100  */
101 /**
102  * @file le_voicecall_interface.h
103  *
104  * Legato @ref c_le_voicecall include file.
105  *
106  * Copyright (C) Sierra Wireless Inc.
107  */
108 
109 #ifndef LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
110 #define LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
111 
112 
113 #include "legato.h"
114 
115 // Interface specific includes
116 #include "le_mdmDefs_interface.h"
117 #include "le_audio_interface.h"
118 
119 // Internal includes for this interface
120 #include "le_voicecall_common.h"
121 //--------------------------------------------------------------------------------------------------
122 /**
123  * Type for handler called when a server disconnects.
124  */
125 //--------------------------------------------------------------------------------------------------
126 typedef void (*le_voicecall_DisconnectHandler_t)(void *);
127 
128 //--------------------------------------------------------------------------------------------------
129 /**
130  *
131  * Connect the current client thread to the service providing this API. Block until the service is
132  * available.
133  *
134  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
135  * called before any other functions in this API. Normally, ConnectService is automatically called
136  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
137  *
138  * This function is created automatically.
139  */
140 //--------------------------------------------------------------------------------------------------
142 (
143  void
144 );
145 
146 //--------------------------------------------------------------------------------------------------
147 /**
148  *
149  * Try to connect the current client thread to the service providing this API. Return with an error
150  * if the service is not available.
151  *
152  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
153  * called before any other functions in this API. Normally, ConnectService is automatically called
154  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
155  *
156  * This function is created automatically.
157  *
158  * @return
159  * - LE_OK if the client connected successfully to the service.
160  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
161  * bound.
162  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
163  * - LE_COMM_ERROR if the Service Directory cannot be reached.
164  */
165 //--------------------------------------------------------------------------------------------------
167 (
168  void
169 );
170 
171 //--------------------------------------------------------------------------------------------------
172 /**
173  * Set handler called when server disconnection is detected.
174  *
175  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
176  * to continue without exiting, it should call longjmp() from inside the handler.
177  */
178 //--------------------------------------------------------------------------------------------------
180 (
181  le_voicecall_DisconnectHandler_t disconnectHandler,
182  void *contextPtr
183 );
184 
185 //--------------------------------------------------------------------------------------------------
186 /**
187  *
188  * Disconnect the current client thread from the service providing this API.
189  *
190  * Normally, this function doesn't need to be called. After this function is called, there's no
191  * longer a connection to the service, and the functions in this API can't be used. For details, see
192  * @ref apiFilesC_client.
193  *
194  * This function is created automatically.
195  */
196 //--------------------------------------------------------------------------------------------------
198 (
199  void
200 );
201 
202 
203 //--------------------------------------------------------------------------------------------------
204 /**
205  * Reference returned by Start function and used by End function
206  */
207 //--------------------------------------------------------------------------------------------------
208 
209 
210 //--------------------------------------------------------------------------------------------------
211 /**
212  * Voice call establishment states.
213  */
214 //--------------------------------------------------------------------------------------------------
215 
216 
217 //--------------------------------------------------------------------------------------------------
218 /**
219  * Voice call termination reason.
220  */
221 //--------------------------------------------------------------------------------------------------
222 
223 
224 //--------------------------------------------------------------------------------------------------
225 /**
226  * Handler for voice call state changes.
227  */
228 //--------------------------------------------------------------------------------------------------
229 
230 
231 //--------------------------------------------------------------------------------------------------
232 /**
233  * Reference type used by Add/Remove functions for EVENT 'le_voicecall_State'
234  */
235 //--------------------------------------------------------------------------------------------------
236 
237 
238 //--------------------------------------------------------------------------------------------------
239 /**
240  * Add handler function for EVENT 'le_voicecall_State'
241  *
242  * This event provides information on voice call state changes
243  *
244  */
245 //--------------------------------------------------------------------------------------------------
246 le_voicecall_StateHandlerRef_t le_voicecall_AddStateHandler
247 (
248  le_voicecall_StateHandlerFunc_t handlerPtr,
249  ///< [IN]
250  void* contextPtr
251  ///< [IN]
252 );
253 
254 //--------------------------------------------------------------------------------------------------
255 /**
256  * Remove handler function for EVENT 'le_voicecall_State'
257  */
258 //--------------------------------------------------------------------------------------------------
260 (
261  le_voicecall_StateHandlerRef_t handlerRef
262  ///< [IN]
263 );
264 
265 //--------------------------------------------------------------------------------------------------
266 /**
267  * Start a voice call.
268  *
269  * @return
270  * - Reference to the voice call (to be used later for releasing the voice call)
271  * - NULL if the voice call could not be processed
272  */
273 //--------------------------------------------------------------------------------------------------
274 le_voicecall_CallRef_t le_voicecall_Start
275 (
276  const char* LE_NONNULL DestinationID
277  ///< [IN] Destination identifier for the voice
278  ///< call establishment.
279 );
280 
281 //--------------------------------------------------------------------------------------------------
282 /**
283  * Release a voice call.
284  *
285  * @return
286  * - LE_OK if the end of voice call can be processed.
287  * - LE_NOT_FOUND if the voice call object reference is not found.
288  */
289 //--------------------------------------------------------------------------------------------------
291 (
292  le_voicecall_CallRef_t reference
293  ///< [IN] Voice call object reference to hang-up.
294 );
295 
296 //--------------------------------------------------------------------------------------------------
297 /**
298  * Delete voice call object reference create by le_voicecall_Start() or an incoming voice call.
299  *
300  * @return
301  * - LE_OK if the delete of voice call can be processed.
302  * - LE_FAULT if the voice call is not terminated.
303  * - LE_NOT_FOUND if the voice call object reference is not found.
304  */
305 //--------------------------------------------------------------------------------------------------
307 (
308  le_voicecall_CallRef_t reference
309  ///< [IN] Voice call object reference to delete.
310 );
311 
312 //--------------------------------------------------------------------------------------------------
313 /**
314  * Answer to incoming voice call.
315  *
316  * @return
317  * - LE_OK if the incoming voice call can be answered
318  * - LE_NOT_FOUND if the incoming voice call object reference is not found.
319  */
320 //--------------------------------------------------------------------------------------------------
322 (
323  le_voicecall_CallRef_t reference
324  ///< [IN] Incoming voice call object reference to answer.
325 );
326 
327 //--------------------------------------------------------------------------------------------------
328 /**
329  * Get the termination reason of a voice call reference.
330  *
331  * @return
332  * - LE_OK if the termination reason is got
333  * - LE_NOT_FOUND if the incoming voice call object reference is not found.
334  * - LE_FAULT if the voice call is not terminated.
335  */
336 //--------------------------------------------------------------------------------------------------
338 (
339  le_voicecall_CallRef_t reference,
340  ///< [IN] Voice call object reference to read from.
341  le_voicecall_TerminationReason_t* reasonPtr
342  ///< [OUT] Termination reason of the voice call.
343 );
344 
345 //--------------------------------------------------------------------------------------------------
346 /**
347  * Called to get the transmitted audio stream. All audio generated on this
348  * end of the call is sent on this stream.
349  *
350  * @return Transmitted audio stream reference.
351  */
352 //--------------------------------------------------------------------------------------------------
353 le_audio_StreamRef_t le_voicecall_GetTxAudioStream
354 (
355  le_voicecall_CallRef_t reference
356  ///< [IN] Voice call object reference to read from.
357 );
358 
359 //--------------------------------------------------------------------------------------------------
360 /**
361  * Called to get the received audio stream. All audio received from the
362  * other end of the call is received on this stream.
363  *
364  * @return Received audio stream reference.
365  */
366 //--------------------------------------------------------------------------------------------------
367 le_audio_StreamRef_t le_voicecall_GetRxAudioStream
368 (
369  le_voicecall_CallRef_t reference
370  ///< [IN] Voice call object reference to read from.
371 );
372 
373 #endif // LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
le_result_t le_voicecall_TryConnectService(void)
le_result_t le_voicecall_End(le_voicecall_CallRef_t reference)
le_result_t
Definition: le_basics.h:35
le_result_t le_voicecall_Delete(le_voicecall_CallRef_t reference)
le_voicecall_StateHandlerRef_t le_voicecall_AddStateHandler(le_voicecall_StateHandlerFunc_t handlerPtr, void *contextPtr)
le_audio_StreamRef_t le_voicecall_GetRxAudioStream(le_voicecall_CallRef_t reference)
LE_FULL_API void le_voicecall_SetServerDisconnectHandler(le_voicecall_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_audio_StreamRef_t le_voicecall_GetTxAudioStream(le_voicecall_CallRef_t reference)
le_result_t le_voicecall_GetTerminationReason(le_voicecall_CallRef_t reference, le_voicecall_TerminationReason_t *reasonPtr)
void le_voicecall_ConnectService(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
void le_voicecall_RemoveStateHandler(le_voicecall_StateHandlerRef_t handlerRef)
void(* le_voicecall_DisconnectHandler_t)(void *)
Definition: le_voicecall_interface.h:126
void le_voicecall_DisconnectService(void)
le_voicecall_CallRef_t le_voicecall_Start(const char *LE_NONNULL DestinationID)
le_result_t le_voicecall_Answer(le_voicecall_CallRef_t reference)