le_mcc_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_mcc Modem Call Control
14  *
15  * @ref le_mcc_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * The Modem Call Control (mcc) API functions of this API are provided by the @b modemService
20  * service.
21  *
22  * @section le_mcc_binding IPC interfaces binding
23  *
24  * Here's a code sample binding to modem services:
25  * @verbatim
26  bindings:
27  {
28  clientExe.clientComponent.le_mcc -> modemService.le_mcc
29  }
30  @endverbatim
31  *
32  * @section le_mcc_starting_a_call Starting a Call
33  *
34  * To initiate a call, create a new call object with a destination telephone
35  * number calling the le_mcc_Create() function.
36  *
37  * le_mcc_Start() must still initiate the call when ready.
38  *
39  * The le_mcc_Start() function initiates a call attempt (it's asynchronous because it can take
40  * time for a call to connect). If function failed, the le_mcc_GetTerminationReason() API can be
41  * used to retrieve the terminal reason.
42  *
43  * It's essential to register a handler function to get the call events. Use
44  * le_mcc_AddCallEventHandler() API to install that handler function. The handler will be
45  * called for all calls' events (incoming and outgoing).
46  *
47  * The le_mcc_RemoveCallEventHandler() API uninstalls the handler function.
48  *
49  * The following APIs can be used to manage incoming or outgoing calls:
50  * - le_mcc_GetTerminationReason() - termination reason.
51  * - le_mcc_GetPlatformSpecificTerminationCode() - let you get the platform specific
52  * termination code by retrieving the termination code from @c le_mcc_CallRef_t.
53  * Please refer to @ref platformConstraintsSpecificErrorCodes for platform specific
54  * termination code description.
55  *
56  * - le_mcc_IsConnected() - connection status.
57  * - le_mcc_GetRemoteTel() - displays remote party telephone number associated with the call.
58  * - le_mcc_HangUp() will disconnect this call.
59  *
60  * When finished with the call object, call le_mcc_Delete() to free all the allocated resources
61  * associated with the object.
62  *
63  * Multi-threading/multi-application behaviour: the callRef is linked to a specific client
64  * (i.e. connection with the mcc service). Each client will have its own callRef for a same call.
65  * That is, if a call event handler is registered by one thread but le_mcc_Create() is called by
66  * another thread, they will each get different call references for the same call. So, when multiple
67  * threads are being used to work with the same call, a comparison of the call references themselves
68  * can't be used to tell whether or not they refer to the same call. The callRefs of the thread will
69  * be deleted when the thread is disconnected from the mcc service.
70  *
71  * The Adaptive Multi Rate (AMR) is an audio compression format optimized for speech coding and used
72  * during a voice call. Two AMRs are supported:
73  * An AMR Narrowband that encodes a bandwidth of 200--3400 Hz signals at variable bitrates ranging
74  * from 4.75 to 12.2 kbit/s and an AMR Wideband that encodes a wider bandwidth of 50--7000 Hz and
75  * thus improves the speech quality.
76  *
77  * le_mcc_SetAmrWbCapability() function enables or disables the AMR Wideband supported capability.
78  * le_mcc_GetAmrWbCapability() function returns the AMR Wideband capability status.
79  *
80  * @section le_mcc_answering_a_call Answering a call
81  *
82  * Receiving calls is similar sending calls. Add a handler through le_mcc_AddCallEventHandler()
83  * to be notified of incoming calls.
84  *
85  * To answer, call le_mcc_Answer(). To reject it, call le_mcc_HangUp().
86  *
87  *
88  * @section le_mcc_ending_all_call Ending all calls
89  *
90  * A special function can be used to hang-up all the ongoing calls: le_mcc_HangUpAll().
91  * This function can be used to hang-up any calls that have been initiated through another client
92  * like AT commands.
93  *
94  *
95  *
96  * @section le_mcc_ss Supplementary service
97  *
98  * Calling Line Identification Restriction (CLIR) can be activated or deactivated by
99  * le_mcc_SetCallerIdRestrict() API. The status is independent for each call object reference.
100  * Status can be read with the le_mcc_GetCallerIdRestrict() API. If the status is not set,
101  * le_mcc_GetCallerIdRestrict() API returns LE_UNAVAILABLE.
102  * By default the CLIR status is not set.
103  *
104  * Call waiting supplementary service can be activated or deactivated by
105  * le_mcc_SetCallWaitingService(). Its status can be given by le_mcc_GetCallWaitingService().
106  * A call waiting can be answered using le_mcc_ActivateCall() API. This API is also used to
107  * activate an on hold call (current call is then placed on hold).
108  * An activated, waiting or on hold call can be released using le_mcc_HangUp() function.
109  * See 3GPP TS 02.83 / 22.083 for any details concerning call waiting / call hold supplementary
110  * services.
111  *
112  * @todo Other Supplementary services will be available in a future release. Create simpler examples.
113  *
114  * @section le_mcc_samples Sample codes
115  *
116  * A sample code that implements a dialing call can be found in \b le_mccTest.c file (please refer
117  * to @ref c_mccTest page).
118  *
119  *
120  * <HR>
121  *
122  * Copyright (C) Sierra Wireless Inc.
123  */
124 /**
125  * @file le_mcc_interface.h
126  *
127  * Legato @ref c_mcc include file.
128  *
129  * Copyright (C) Sierra Wireless Inc.
130  */
131 /**
132  * @page c_mccTest Sample code of Modem Call control
133  *
134  * @include "apps/test/modemServices/mcc/mccIntegrationTest/mccTest/le_mccTest.c"
135  */
136 
137 #ifndef LE_MCC_INTERFACE_H_INCLUDE_GUARD
138 #define LE_MCC_INTERFACE_H_INCLUDE_GUARD
139 
140 
141 #include "legato.h"
142 
143 // Interface specific includes
144 #include "le_mdmDefs_interface.h"
145 
146 // Internal includes for this interface
147 #include "le_mcc_common.h"
148 /** @addtogroup le_mcc le_mcc API Reference
149  * @{
150  * @file le_mcc_common.h
151  * @file le_mcc_interface.h **/
152 //--------------------------------------------------------------------------------------------------
153 /**
154  * Type for handler called when a server disconnects.
155  */
156 //--------------------------------------------------------------------------------------------------
157 typedef void (*le_mcc_DisconnectHandler_t)(void *);
158 
159 //--------------------------------------------------------------------------------------------------
160 /**
161  *
162  * Connect the current client thread to the service providing this API. Block until the service is
163  * available.
164  *
165  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
166  * called before any other functions in this API. Normally, ConnectService is automatically called
167  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
168  *
169  * This function is created automatically.
170  */
171 //--------------------------------------------------------------------------------------------------
173 (
174  void
175 );
176 
177 //--------------------------------------------------------------------------------------------------
178 /**
179  *
180  * Try to connect the current client thread to the service providing this API. Return with an error
181  * if the service is not available.
182  *
183  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
184  * called before any other functions in this API. Normally, ConnectService is automatically called
185  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
186  *
187  * This function is created automatically.
188  *
189  * @return
190  * - LE_OK if the client connected successfully to the service.
191  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
192  * bound.
193  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
194  * - LE_COMM_ERROR if the Service Directory cannot be reached.
195  */
196 //--------------------------------------------------------------------------------------------------
198 (
199  void
200 );
201 
202 //--------------------------------------------------------------------------------------------------
203 /**
204  * Set handler called when server disconnection is detected.
205  *
206  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
207  * to continue without exiting, it should call longjmp() from inside the handler.
208  */
209 //--------------------------------------------------------------------------------------------------
211 (
212  le_mcc_DisconnectHandler_t disconnectHandler,
213  void *contextPtr
214 );
215 
216 //--------------------------------------------------------------------------------------------------
217 /**
218  *
219  * Disconnect the current client thread from the service providing this API.
220  *
221  * Normally, this function doesn't need to be called. After this function is called, there's no
222  * longer a connection to the service, and the functions in this API can't be used. For details, see
223  * @ref apiFilesC_client.
224  *
225  * This function is created automatically.
226  */
227 //--------------------------------------------------------------------------------------------------
229 (
230  void
231 );
232 
233 
234 //--------------------------------------------------------------------------------------------------
235 /**
236  * Enumeration of the possible events that may be reported to a call event handler.
237  */
238 //--------------------------------------------------------------------------------------------------
239 
240 
241 //--------------------------------------------------------------------------------------------------
242 /**
243  * Enumeration of the possible reasons for call termination.
244  */
245 //--------------------------------------------------------------------------------------------------
246 
247 
248 //--------------------------------------------------------------------------------------------------
249 /**
250  * Reference type for managing active calls.
251  */
252 //--------------------------------------------------------------------------------------------------
253 
254 
255 //--------------------------------------------------------------------------------------------------
256 /**
257  * Handler for call state changes.
258  *
259  * @note The callRef has to be deleted using le_mcc_Delete() when LE_MCC_TERMINATED event
260  * is received, except if is has to be used for a future usage (with le_mcc_profile handler for
261  * instance, or dialing again the same number).
262  *
263  */
264 //--------------------------------------------------------------------------------------------------
265 
266 
267 //--------------------------------------------------------------------------------------------------
268 /**
269  * Reference type used by Add/Remove functions for EVENT 'le_mcc_CallEvent'
270  */
271 //--------------------------------------------------------------------------------------------------
272 
273 
274 //--------------------------------------------------------------------------------------------------
275 /**
276  * Create a call reference.
277  *
278  * @note Return NULL if call reference can't be created
279  *
280  * @note If destination number is too long (max LE_MDMDEFS_PHONE_NUM_MAX_LEN digits),
281  * it is a fatal error, the function will not return.
282  *
283  */
284 //--------------------------------------------------------------------------------------------------
286 (
287  const char* LE_NONNULL phoneNumPtr
288  ///< [IN] The target number we are going to
289  ///< call.
290 );
291 
292 //--------------------------------------------------------------------------------------------------
293 /**
294  * Call to free up a call reference.
295  *
296  * @return
297  * - LE_OK The function succeed.
298  * - LE_NOT_FOUND The call reference was not found.
299  * - LE_FAULT The function failed.
300  *
301  *
302  */
303 //--------------------------------------------------------------------------------------------------
305 (
306  le_mcc_CallRef_t callRef
307  ///< [IN] The call object to free.
308 );
309 
310 //--------------------------------------------------------------------------------------------------
311 /**
312  * Start a call attempt.
313  *
314  * Asynchronous due to possible time to connect.
315  *
316  * As the call attempt proceeds, the profile's registered call event handler receives events.
317  *
318  * @return
319  * - LE_OK Function succeed.
320  * - LE_BUSY The call is already in progress
321  *
322  * * @note As this is an asynchronous call, a successful only confirms a call has been
323  * started. Don't assume a call has been successful yet.
324  *
325  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
326  * function will not return.
327  */
328 //--------------------------------------------------------------------------------------------------
330 (
331  le_mcc_CallRef_t callRef
332  ///< [IN] Reference to the call object.
333 );
334 
335 //--------------------------------------------------------------------------------------------------
336 /**
337  * Allow the caller to know if the given call is actually connected or not.
338  *
339  * @return TRUE if the call is connected, FALSE otherwise.
340  *
341  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
342  * function will not return.
343  */
344 //--------------------------------------------------------------------------------------------------
346 (
347  le_mcc_CallRef_t callRef
348  ///< [IN] The call reference to read.
349 );
350 
351 //--------------------------------------------------------------------------------------------------
352 /**
353  * Read out the remote party telephone number associated with the call.
354  *
355  * Output parameter is updated with the telephone number. If the Telephone number string length exceeds
356  * the value of 'len' parameter, the LE_OVERFLOW error code is returned and 'telPtr' is used until
357  * 'len-1' characters and a null-character is implicitly appended at the end of 'telPtr'.
358  * Note that 'len' sould be at least equal to LE_MDMDEFS_PHONE_NUM_MAX_BYTES, otherwise LE_OVERFLOW
359  * error code will be common.
360  *
361  * @return LE_OVERFLOW The Telephone number length exceed the maximum length.
362  * @return LE_OK The function succeeded.
363  *
364  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
365  * function will not return.
366  */
367 //--------------------------------------------------------------------------------------------------
369 (
370  le_mcc_CallRef_t callRef,
371  ///< [IN] The call reference to read from.
372  char* telPtr,
373  ///< [OUT] The telephone number string.
374  size_t telPtrSize
375  ///< [IN]
376 );
377 
378 //--------------------------------------------------------------------------------------------------
379 /**
380  * Called to get the termination reason.
381  *
382  * @return The termination reason.
383  *
384  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
385  * function will not return.
386  */
387 //--------------------------------------------------------------------------------------------------
389 (
390  le_mcc_CallRef_t callRef
391  ///< [IN] The call reference to read from.
392 );
393 
394 //--------------------------------------------------------------------------------------------------
395 /**
396  * Called to get the platform specific termination code.
397  *
398  * Refer to @ref platformConstraintsSpecificErrorCodes for platform specific
399  * termination code description.
400  *
401  * @return The platform specific termination code.
402  *
403  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
404  * function will not return.
405  */
406 //--------------------------------------------------------------------------------------------------
408 (
409  le_mcc_CallRef_t callRef
410  ///< [IN] The call reference to read from.
411 );
412 
413 //--------------------------------------------------------------------------------------------------
414 /**
415  * Answers incoming call.
416  *
417  * @return LE_TIMEOUT No response was received from the Modem.
418  * @return LE_OK The function succeeded.
419  *
420  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
421  * function will not return.
422  * @note A call waiting call must be answered using SetCallActive() API. This API doesn't manage
423  * call waiting supplementary service.
424  */
425 //--------------------------------------------------------------------------------------------------
427 (
428  le_mcc_CallRef_t callRef
429  ///< [IN] The call reference.
430 );
431 
432 //--------------------------------------------------------------------------------------------------
433 /**
434  * Disconnect, or hang up, the specifed call. Any active call handlers
435  * will be notified.
436  *
437  * @return LE_FAULT The function failed.
438  * @return LE_TIMEOUT No response was received from the Modem.
439  * @return LE_OK Function succeeded.
440  *
441  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
442  * function will not return.
443  * @note this API can also be used to disconnect a waiting or on hold call.
444  */
445 //--------------------------------------------------------------------------------------------------
447 (
448  le_mcc_CallRef_t callRef
449  ///< [IN] The call to end.
450 );
451 
452 //--------------------------------------------------------------------------------------------------
453 /**
454  * This function will disconnect, or hang up all the ongoing calls. Any active call handlers will
455  * be notified.
456  *
457  * @return LE_FAULT The function failed.
458  * @return LE_TIMEOUT No response was received from the Modem.
459  * @return LE_OK The function succeeded.
460  */
461 //--------------------------------------------------------------------------------------------------
463 (
464  void
465 );
466 
467 //--------------------------------------------------------------------------------------------------
468 /**
469  * This function return the Calling Line Identification Restriction (CLIR) status on the specific
470  * call.
471  *
472  * The output parameter is updated with the CLIR status.
473  * - LE_ON Disable presentation of own phone number to remote.
474  * - LE_OFF Enable presentation of own phone number to remote.
475  *
476  * @return
477  * - LE_OK The function succeed.
478  * - LE_NOT_FOUND The call reference was not found.
479  * - LE_UNAVAILABLE CLIR status was not set.
480  */
481 //--------------------------------------------------------------------------------------------------
483 (
484  le_mcc_CallRef_t callRef,
485  ///< [IN] The call reference.
486  le_onoff_t* clirStatusPtrPtr
487  ///< [OUT] the Calling Line Identification Restriction (CLIR) status
488 );
489 
490 //--------------------------------------------------------------------------------------------------
491 /**
492  * This function set the Calling Line Identification Restriction (CLIR) status on the specific call.
493  * By default the CLIR status is not set.
494  *
495  * @return
496  * - LE_OK The function succeed.
497  * - LE_NOT_FOUND The call reference was not found.
498  *
499  */
500 //--------------------------------------------------------------------------------------------------
502 (
503  le_mcc_CallRef_t callRef,
504  ///< [IN] The call reference.
505  le_onoff_t clirStatus
506  ///< [IN] The Calling Line Identification Restriction (CLIR) status.
507 );
508 
509 //--------------------------------------------------------------------------------------------------
510 /**
511  * Add handler function for EVENT 'le_mcc_CallEvent'
512  *
513  * Register an event handler that will be notified when an call's event occurs.
514  *
515  * @return A reference to the new event handler object.
516  *
517  * @note It is a fatal error if this function does succeed. If this function fails, it will not
518  * return.
519  *
520  */
521 //--------------------------------------------------------------------------------------------------
523 (
525  ///< [IN]
526  void* contextPtr
527  ///< [IN]
528 );
529 
530 //--------------------------------------------------------------------------------------------------
531 /**
532  * Remove handler function for EVENT 'le_mcc_CallEvent'
533  */
534 //--------------------------------------------------------------------------------------------------
536 (
538  ///< [IN]
539 );
540 
541 //--------------------------------------------------------------------------------------------------
542 /**
543  * This function activates or deactivates the call waiting service.
544  *
545  * @return
546  * - LE_OK The function succeed.
547  * - LE_FAULT The function failed.
548  *
549  */
550 //--------------------------------------------------------------------------------------------------
552 (
553  bool active
554  ///< [IN] The call waiting activation.
555 );
556 
557 //--------------------------------------------------------------------------------------------------
558 /**
559  * This function gets the call waiting service status.
560  *
561  * @return
562  * - LE_OK The function succeed.
563  * - LE_FAULT The function failed.
564  *
565  */
566 //--------------------------------------------------------------------------------------------------
568 (
569  bool* activePtr
570  ///< [OUT] The call waiting activation.
571 );
572 
573 //--------------------------------------------------------------------------------------------------
574 /**
575  * This function activates the specified call. Other calls are placed on hold.
576  *
577  * @return
578  * - LE_OK The function succeed.
579  * - LE_FAULT The function failed.
580  *
581  */
582 //--------------------------------------------------------------------------------------------------
584 (
585  le_mcc_CallRef_t callRef
586  ///< [IN] The call reference.
587 );
588 
589 //--------------------------------------------------------------------------------------------------
590 /**
591  * This function enables/disables the audio AMR Wideband capability.
592  *
593  * @return
594  * - LE_OK The function succeeded.
595  * - LE_UNAVAILABLE The service is not available.
596  * - LE_FAULT On any other failure.
597  *
598  * @note The capability setting takes effect immediately and is not persistent to reset.
599  */
600 //--------------------------------------------------------------------------------------------------
602 (
603  bool enable
604  ///< [IN] True enables the AMR Wideband capability, false disables it.
605 );
606 
607 //--------------------------------------------------------------------------------------------------
608 /**
609  * This function gets the audio AMR Wideband capability.
610  *
611  * @return
612  * - LE_OK The function succeeded.
613  * - LE_UNAVAILABLE The service is not available.
614  * - LE_FAULT On any other failure.
615  */
616 //--------------------------------------------------------------------------------------------------
618 (
619  bool* enabledPtr
620  ///< [OUT] True if AMR Wideband capability is enabled, false otherwise.
621 );
622 
623 /** @} **/
624 
625 #endif // LE_MCC_INTERFACE_H_INCLUDE_GUARD
le_result_t le_mcc_Start(le_mcc_CallRef_t callRef)
void le_mcc_RemoveCallEventHandler(le_mcc_CallEventHandlerRef_t handlerRef)
int32_t le_mcc_GetPlatformSpecificTerminationCode(le_mcc_CallRef_t callRef)
le_result_t
Definition: le_basics.h:46
LE_FULL_API void le_mcc_SetServerDisconnectHandler(le_mcc_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_mcc_CallEventHandlerRef_t le_mcc_AddCallEventHandler(le_mcc_CallEventHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_mcc_GetRemoteTel(le_mcc_CallRef_t callRef, char *telPtr, size_t telPtrSize)
le_result_t le_mcc_SetCallWaitingService(bool active)
le_result_t le_mcc_HangUp(le_mcc_CallRef_t callRef)
le_mcc_TerminationReason_t le_mcc_GetTerminationReason(le_mcc_CallRef_t callRef)
le_result_t le_mcc_ActivateCall(le_mcc_CallRef_t callRef)
le_mcc_CallRef_t le_mcc_Create(const char *LE_NONNULL phoneNumPtr)
bool le_mcc_IsConnected(le_mcc_CallRef_t callRef)
le_result_t le_mcc_TryConnectService(void)
le_result_t le_mcc_HangUpAll(void)
le_result_t le_mcc_GetCallWaitingService(bool *activePtr)
void(* le_mcc_CallEventHandlerFunc_t)(le_mcc_CallRef_t callRef, le_mcc_Event_t event, void *contextPtr)
Definition: le_mcc_common.h:212
struct le_mcc_CallEventHandler * le_mcc_CallEventHandlerRef_t
Definition: le_mcc_common.h:198
#define LE_FULL_API
Definition: le_apiFeatures.h:40
void le_mcc_ConnectService(void)
le_mcc_TerminationReason_t
Definition: le_mcc_common.h:65
le_result_t le_mcc_SetCallerIdRestrict(le_mcc_CallRef_t callRef, le_onoff_t clirStatus)
struct le_mcc_Call * le_mcc_CallRef_t
Definition: le_mcc_common.h:190
le_result_t le_mcc_Answer(le_mcc_CallRef_t callRef)
le_result_t le_mcc_GetCallerIdRestrict(le_mcc_CallRef_t callRef, le_onoff_t *clirStatusPtrPtr)
le_result_t le_mcc_GetAmrWbCapability(bool *enabledPtr)
le_result_t le_mcc_Delete(le_mcc_CallRef_t callRef)
void(* le_mcc_DisconnectHandler_t)(void *)
Definition: le_mcc_interface.h:157
void le_mcc_DisconnectService(void)
le_result_t le_mcc_SetAmrWbCapability(bool enable)
le_onoff_t
Definition: le_basics.h:85