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