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  * @note Available interfaces depend on used platform.
40  *
41  * Before the voice call is started, an application registers a state handler using
42  * le_voicecall_AddStateHandler(). Once the voice call is established, the handler will be called
43  * indicating it's now connected. If the state of the voice call changes, then the handler will be
44  * called with the new state. To release a voice call, an application can use le_voicecall_End().
45  * Application must use le_voicecall_Delete() to release @ref le_voicecall_CallRef_t voice call
46  * reference object when it is no more used.
47  *
48  * If le_voicecall_End() failed a @ref LE_VOICECALL_EVENT_CALL_END_FAILED event will be sent.
49  *
50  * If a voice call is already started when le_voicecall_Start() is called(), a
51  * new voice call will not be established. Instead, @ref LE_VOICECALL_EVENT_RESOURCE_BUSY event
52  * will be sent. This event means call was not processed, while a
53  * @ref LE_VOICECALL_EVENT_TERMINATED event means that the call was not processed and then
54  * terminated or failed.
55  *
56  * Once an application makes a voice call request, it should monitor the establishment state
57  * reported to the registered state handler.
58  *
59  * Once the @ref LE_VOICECALL_EVENT_CONNECTED voice call event is received by the application, it
60  * must get the Rx and Tx audio streams with le_voicecall_GetRxAudioStream() and
61  * le_voicecall_GetTxAudioStream() functions in order to set up the audio path. The audio path
62  * can be set up thanks to the audio API (cf. @ref c_audio).
63  *
64  * If a @ref LE_VOICECALL_EVENT_TERMINATED event is received, application can get the termination
65  * reason by using le_voicecall_GetTerminationReason().
66  *
67  * @note The voice call use the mobile network. VoIP is not yet supported.
68  *
69  * @section c_le_voicecall_incoming Answering a Voice call
70  *
71  * An Incoming voice call will be notified by an @ref LE_VOICECALL_EVENT_INCOMING event on state
72  * handler with a Call reference le_voicecall_CallRef_t().
73  *
74  * Application can answer the call by using le_voicecall_Answer() or reject the call by using
75  * le_voicecall_End() passing the call reference @ref le_voicecall_CallRef_t.
76  *
77  * If le_voicecall_End() failed a @ref LE_VOICECALL_EVENT_CALL_END_FAILED event will be sent. If
78  * le_voicecall_Answer() failed a @ref LE_VOICECALL_EVENT_CALL_ANSWER_FAILED event will be sent.
79  *
80  * Application have to use le_voicecall_Delete() to release @ref le_voicecall_CallRef_t voice call
81  * reference object when it is no more used.
82  *
83  * <HR>
84  *
85  * Copyright (C) Sierra Wireless Inc.
86  */
87 /**
88  * @file le_voicecall_interface.h
89  *
90  * Legato @ref c_le_voicecall include file.
91  *
92  * Copyright (C) Sierra Wireless Inc.
93  */
94 
95 #ifndef LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
96 #define LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
97 
98 
99 #include "legato.h"
100 
101 // Interface specific includes
102 #include "le_mdmDefs_interface.h"
103 #include "le_audio_interface.h"
104 
105 
106 //--------------------------------------------------------------------------------------------------
107 /**
108  * Type for handler called when a server disconnects.
109  */
110 //--------------------------------------------------------------------------------------------------
111 typedef void (*le_voicecall_DisconnectHandler_t)(void *);
112 
113 //--------------------------------------------------------------------------------------------------
114 /**
115  *
116  * Connect the current client thread to the service providing this API. Block until the service is
117  * available.
118  *
119  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
120  * called before any other functions in this API. Normally, ConnectService is automatically called
121  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
122  *
123  * This function is created automatically.
124  */
125 //--------------------------------------------------------------------------------------------------
127 (
128  void
129 );
130 
131 //--------------------------------------------------------------------------------------------------
132 /**
133  *
134  * Try to connect the current client thread to the service providing this API. Return with an error
135  * if the service is not available.
136  *
137  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
138  * called before any other functions in this API. Normally, ConnectService is automatically called
139  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
140  *
141  * This function is created automatically.
142  *
143  * @return
144  * - LE_OK if the client connected successfully to the service.
145  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
146  * bound.
147  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
148  * - LE_COMM_ERROR if the Service Directory cannot be reached.
149  */
150 //--------------------------------------------------------------------------------------------------
152 (
153  void
154 );
155 
156 //--------------------------------------------------------------------------------------------------
157 /**
158  * Set handler called when server disconnection is detected.
159  *
160  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
161  * to continue without exiting, it should call longjmp() from inside the handler.
162  */
163 //--------------------------------------------------------------------------------------------------
165 (
166  le_voicecall_DisconnectHandler_t disconnectHandler,
167  void *contextPtr
168 );
169 
170 //--------------------------------------------------------------------------------------------------
171 /**
172  *
173  * Disconnect the current client thread from the service providing this API.
174  *
175  * Normally, this function doesn't need to be called. After this function is called, there's no
176  * longer a connection to the service, and the functions in this API can't be used. For details, see
177  * @ref apiFilesC_client.
178  *
179  * This function is created automatically.
180  */
181 //--------------------------------------------------------------------------------------------------
183 (
184  void
185 );
186 
187 
188 //--------------------------------------------------------------------------------------------------
189 /**
190  * Reference returned by Start function and used by End function
191  */
192 //--------------------------------------------------------------------------------------------------
193 typedef struct le_voicecall_Call* le_voicecall_CallRef_t;
194 
195 
196 //--------------------------------------------------------------------------------------------------
197 /**
198  * Voice call establishment states.
199  */
200 //--------------------------------------------------------------------------------------------------
201 typedef enum
202 {
204  ///< Voice call establishment in progress.
205  ///< Far end is now alerting its user (outgoing call).
207  ///< Call has been established, and is media is active.
209  ///< Call has terminated.
211  ///< NO Service available to try establish a voice call.
213  ///< Remote party (callee) is busy.
215  ///< All local connection resources (lines/channels) are in use.
217  ///< Call ending failed.
219  ///< Call answering failed.
221  ///< Incoming voice call in progress.
222 }
224 
225 
226 //--------------------------------------------------------------------------------------------------
227 /**
228  * Voice call termination reason.
229  */
230 //--------------------------------------------------------------------------------------------------
231 typedef enum
232 {
234  ///< Network could not complete the call.
236  ///< Remote address could not be resolved.
238  ///< Caller is currently busy and cannot take the call.
240  ///< Local party ended the call.
242  ///< Remote party ended the call.
244  ///< Undefined reason.
245 }
247 
248 
249 //--------------------------------------------------------------------------------------------------
250 /**
251  * Reference type used by Add/Remove functions for EVENT 'le_voicecall_State'
252  */
253 //--------------------------------------------------------------------------------------------------
254 typedef struct le_voicecall_StateHandler* le_voicecall_StateHandlerRef_t;
255 
256 
257 //--------------------------------------------------------------------------------------------------
258 /**
259  * Handler for voice call state changes.
260  */
261 //--------------------------------------------------------------------------------------------------
262 typedef void (*le_voicecall_StateHandlerFunc_t)
263 (
264  le_voicecall_CallRef_t reference,
265  ///< Event voice call object reference.
266  const char* LE_NONNULL identifier,
267  ///< Identifier of the remote party
268  ///< associated with the call.
269  le_voicecall_Event_t event,
270  ///< Voice call event.
271  void* contextPtr
272  ///<
273 );
274 
275 //--------------------------------------------------------------------------------------------------
276 /**
277  * Add handler function for EVENT 'le_voicecall_State'
278  *
279  * This event provides information on voice call state changes
280  *
281  */
282 //--------------------------------------------------------------------------------------------------
284 (
286  ///< [IN]
287  void* contextPtr
288  ///< [IN]
289 );
290 
291 //--------------------------------------------------------------------------------------------------
292 /**
293  * Remove handler function for EVENT 'le_voicecall_State'
294  */
295 //--------------------------------------------------------------------------------------------------
297 (
299  ///< [IN]
300 );
301 
302 //--------------------------------------------------------------------------------------------------
303 /**
304  * Start a voice call.
305  *
306  * @return
307  * - Reference to the voice call (to be used later for releasing the voice call)
308  * - NULL if the voice call could not be processed
309  */
310 //--------------------------------------------------------------------------------------------------
312 (
313  const char* LE_NONNULL DestinationID
314  ///< [IN] Destination identifier for the voice
315  ///< call establishment.
316 );
317 
318 //--------------------------------------------------------------------------------------------------
319 /**
320  * Release a voice call.
321  *
322  * @return
323  * - LE_OK if the end of voice call can be processed.
324  * - LE_NOT_FOUND if the voice call object reference is not found.
325  */
326 //--------------------------------------------------------------------------------------------------
328 (
329  le_voicecall_CallRef_t reference
330  ///< [IN] Voice call object reference to hang-up.
331 );
332 
333 //--------------------------------------------------------------------------------------------------
334 /**
335  * Delete voice call object reference create by le_voicecall_Start() or an incoming voice call.
336  *
337  * @return
338  * - LE_OK if the delete of voice call can be processed.
339  * - LE_FAULT if the voice call is not terminated.
340  * - LE_NOT_FOUND if the voice call object reference is not found.
341  */
342 //--------------------------------------------------------------------------------------------------
344 (
345  le_voicecall_CallRef_t reference
346  ///< [IN] Voice call object reference to delete.
347 );
348 
349 //--------------------------------------------------------------------------------------------------
350 /**
351  * Answer to incoming voice call.
352  *
353  * @return
354  * - LE_OK if the incoming voice call can be answered
355  * - LE_NOT_FOUND if the incoming voice call object reference is not found.
356  */
357 //--------------------------------------------------------------------------------------------------
359 (
360  le_voicecall_CallRef_t reference
361  ///< [IN] Incoming voice call object reference to answer.
362 );
363 
364 //--------------------------------------------------------------------------------------------------
365 /**
366  * Get the termination reason of a voice call reference.
367  *
368  * @return
369  * - LE_OK if the termination reason is got
370  * - LE_NOT_FOUND if the incoming voice call object reference is not found.
371  * - LE_FAULT if the voice call is not terminated.
372  */
373 //--------------------------------------------------------------------------------------------------
375 (
376  le_voicecall_CallRef_t reference,
377  ///< [IN] Voice call object reference to read from.
379  ///< [OUT] Termination reason of the voice call.
380 );
381 
382 //--------------------------------------------------------------------------------------------------
383 /**
384  * Called to get the transmitted audio stream. All audio generated on this
385  * end of the call is sent on this stream.
386  *
387  * @return Transmitted audio stream reference.
388  */
389 //--------------------------------------------------------------------------------------------------
391 (
392  le_voicecall_CallRef_t reference
393  ///< [IN] Voice call object reference to read from.
394 );
395 
396 //--------------------------------------------------------------------------------------------------
397 /**
398  * Called to get the received audio stream. All audio received from the
399  * other end of the call is received on this stream.
400  *
401  * @return Received audio stream reference.
402  */
403 //--------------------------------------------------------------------------------------------------
405 (
406  le_voicecall_CallRef_t reference
407  ///< [IN] Voice call object reference to read from.
408 );
409 
410 #endif // LE_VOICECALL_INTERFACE_H_INCLUDE_GUARD
le_result_t le_voicecall_TryConnectService(void)
Local party ended the call.
Definition: le_voicecall_interface.h:239
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)
All local connection resources (lines/channels) are in use.
Definition: le_voicecall_interface.h:214
void le_voicecall_SetServerDisconnectHandler(le_voicecall_DisconnectHandler_t disconnectHandler, void *contextPtr)
struct le_audio_Stream * le_audio_StreamRef_t
Definition: le_audio_interface.h:591
le_voicecall_StateHandlerRef_t le_voicecall_AddStateHandler(le_voicecall_StateHandlerFunc_t handlerPtr, void *contextPtr)
Definition: le_voicecall_interface.h:203
Remote address could not be resolved.
Definition: le_voicecall_interface.h:235
struct le_voicecall_StateHandler * le_voicecall_StateHandlerRef_t
Definition: le_voicecall_interface.h:254
struct le_voicecall_Call * le_voicecall_CallRef_t
Definition: le_voicecall_interface.h:193
le_audio_StreamRef_t le_voicecall_GetRxAudioStream(le_voicecall_CallRef_t reference)
Call has terminated.
Definition: le_voicecall_interface.h:208
void(* le_voicecall_StateHandlerFunc_t)(le_voicecall_CallRef_t reference, const char *LE_NONNULL identifier, le_voicecall_Event_t event, void *contextPtr)
Definition: le_voicecall_interface.h:263
le_audio_StreamRef_t le_voicecall_GetTxAudioStream(le_voicecall_CallRef_t reference)
le_voicecall_Event_t
Definition: le_voicecall_interface.h:201
le_result_t le_voicecall_GetTerminationReason(le_voicecall_CallRef_t reference, le_voicecall_TerminationReason_t *reasonPtr)
Call has been established, and is media is active.
Definition: le_voicecall_interface.h:206
void le_voicecall_ConnectService(void)
Caller is currently busy and cannot take the call.
Definition: le_voicecall_interface.h:237
Call answering failed.
Definition: le_voicecall_interface.h:218
NO Service available to try establish a voice call.
Definition: le_voicecall_interface.h:210
Undefined reason.
Definition: le_voicecall_interface.h:243
Incoming voice call in progress.
Definition: le_voicecall_interface.h:220
void le_voicecall_RemoveStateHandler(le_voicecall_StateHandlerRef_t handlerRef)
Call ending failed.
Definition: le_voicecall_interface.h:216
Remote party (callee) is busy.
Definition: le_voicecall_interface.h:212
void(* le_voicecall_DisconnectHandler_t)(void *)
Definition: le_voicecall_interface.h:111
Network could not complete the call.
Definition: le_voicecall_interface.h:233
void le_voicecall_DisconnectService(void)
le_voicecall_CallRef_t le_voicecall_Start(const char *LE_NONNULL DestinationID)
le_voicecall_TerminationReason_t
Definition: le_voicecall_interface.h:231
Remote party ended the call.
Definition: le_voicecall_interface.h:241
le_result_t le_voicecall_Answer(le_voicecall_CallRef_t reference)