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 //--------------------------------------------------------------------------------------------------
149 /**
150  * Type for handler called when a server disconnects.
151  */
152 //--------------------------------------------------------------------------------------------------
153 typedef void (*le_mcc_DisconnectHandler_t)(void *);
154 
155 //--------------------------------------------------------------------------------------------------
156 /**
157  *
158  * Connect the current client thread to the service providing this API. Block until the service is
159  * available.
160  *
161  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
162  * called before any other functions in this API. Normally, ConnectService is automatically called
163  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
164  *
165  * This function is created automatically.
166  */
167 //--------------------------------------------------------------------------------------------------
169 (
170  void
171 );
172 
173 //--------------------------------------------------------------------------------------------------
174 /**
175  *
176  * Try to connect the current client thread to the service providing this API. Return with an error
177  * if the service is not available.
178  *
179  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
180  * called before any other functions in this API. Normally, ConnectService is automatically called
181  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
182  *
183  * This function is created automatically.
184  *
185  * @return
186  * - LE_OK if the client connected successfully to the service.
187  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
188  * bound.
189  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
190  * - LE_COMM_ERROR if the Service Directory cannot be reached.
191  */
192 //--------------------------------------------------------------------------------------------------
194 (
195  void
196 );
197 
198 //--------------------------------------------------------------------------------------------------
199 /**
200  * Set handler called when server disconnection is detected.
201  *
202  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
203  * to continue without exiting, it should call longjmp() from inside the handler.
204  */
205 //--------------------------------------------------------------------------------------------------
207 (
208  le_mcc_DisconnectHandler_t disconnectHandler,
209  void *contextPtr
210 );
211 
212 //--------------------------------------------------------------------------------------------------
213 /**
214  *
215  * Disconnect the current client thread from the service providing this API.
216  *
217  * Normally, this function doesn't need to be called. After this function is called, there's no
218  * longer a connection to the service, and the functions in this API can't be used. For details, see
219  * @ref apiFilesC_client.
220  *
221  * This function is created automatically.
222  */
223 //--------------------------------------------------------------------------------------------------
225 (
226  void
227 );
228 
229 
230 //--------------------------------------------------------------------------------------------------
231 /**
232  * Enumeration of the possible events that may be reported to a call event handler.
233  */
234 //--------------------------------------------------------------------------------------------------
235 
236 
237 //--------------------------------------------------------------------------------------------------
238 /**
239  * Enumeration of the possible reasons for call termination.
240  */
241 //--------------------------------------------------------------------------------------------------
242 
243 
244 //--------------------------------------------------------------------------------------------------
245 /**
246  * Reference type for managing active calls.
247  */
248 //--------------------------------------------------------------------------------------------------
249 
250 
251 //--------------------------------------------------------------------------------------------------
252 /**
253  * Handler for call state changes.
254  *
255  * @note The callRef has to be deleted using le_mcc_Delete() when LE_MCC_TERMINATED event
256  * is received, except if is has to be used for a future usage (with le_mcc_profile handler for
257  * instance, or dialing again the same number).
258  *
259  */
260 //--------------------------------------------------------------------------------------------------
261 
262 
263 //--------------------------------------------------------------------------------------------------
264 /**
265  * Reference type used by Add/Remove functions for EVENT 'le_mcc_CallEvent'
266  */
267 //--------------------------------------------------------------------------------------------------
268 
269 
270 //--------------------------------------------------------------------------------------------------
271 /**
272  * Create a call reference.
273  *
274  * @note Return NULL if call reference can't be created
275  *
276  * @note If destination number is too long (max LE_MDMDEFS_PHONE_NUM_MAX_LEN digits),
277  * it is a fatal error, the function will not return.
278  *
279  */
280 //--------------------------------------------------------------------------------------------------
281 le_mcc_CallRef_t le_mcc_Create
282 (
283  const char* LE_NONNULL phoneNumPtr
284  ///< [IN] The target number we are going to
285  ///< call.
286 );
287 
288 //--------------------------------------------------------------------------------------------------
289 /**
290  * Call to free up a call reference.
291  *
292  * @return
293  * - LE_OK The function succeed.
294  * - LE_NOT_FOUND The call reference was not found.
295  * - LE_FAULT The function failed.
296  *
297  *
298  */
299 //--------------------------------------------------------------------------------------------------
301 (
302  le_mcc_CallRef_t callRef
303  ///< [IN] The call object to free.
304 );
305 
306 //--------------------------------------------------------------------------------------------------
307 /**
308  * Start a call attempt.
309  *
310  * Asynchronous due to possible time to connect.
311  *
312  * As the call attempt proceeds, the profile's registered call event handler receives events.
313  *
314  * @return
315  * - LE_OK Function succeed.
316  * - LE_BUSY The call is already in progress
317  *
318  * * @note As this is an asynchronous call, a successful only confirms a call has been
319  * started. Don't assume a call has been successful yet.
320  *
321  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
322  * function will not return.
323  */
324 //--------------------------------------------------------------------------------------------------
326 (
327  le_mcc_CallRef_t callRef
328  ///< [IN] Reference to the call object.
329 );
330 
331 //--------------------------------------------------------------------------------------------------
332 /**
333  * Allow the caller to know if the given call is actually connected or not.
334  *
335  * @return TRUE if the call is connected, FALSE otherwise.
336  *
337  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
338  * function will not return.
339  */
340 //--------------------------------------------------------------------------------------------------
342 (
343  le_mcc_CallRef_t callRef
344  ///< [IN] The call reference to read.
345 );
346 
347 //--------------------------------------------------------------------------------------------------
348 /**
349  * Read out the remote party telephone number associated with the call.
350  *
351  * Output parameter is updated with the telephone number. If the Telephone number string length exceeds
352  * the value of 'len' parameter, the LE_OVERFLOW error code is returned and 'telPtr' is used until
353  * 'len-1' characters and a null-character is implicitly appended at the end of 'telPtr'.
354  * Note that 'len' sould be at least equal to LE_MDMDEFS_PHONE_NUM_MAX_BYTES, otherwise LE_OVERFLOW
355  * error code will be common.
356  *
357  * @return LE_OVERFLOW The Telephone number length exceed the maximum length.
358  * @return LE_OK The function succeeded.
359  *
360  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
361  * function will not return.
362  */
363 //--------------------------------------------------------------------------------------------------
365 (
366  le_mcc_CallRef_t callRef,
367  ///< [IN] The call reference to read from.
368  char* telPtr,
369  ///< [OUT] The telephone number string.
370  size_t telPtrSize
371  ///< [IN]
372 );
373 
374 //--------------------------------------------------------------------------------------------------
375 /**
376  * Called to get the termination reason.
377  *
378  * @return The termination reason.
379  *
380  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
381  * function will not return.
382  */
383 //--------------------------------------------------------------------------------------------------
384 le_mcc_TerminationReason_t le_mcc_GetTerminationReason
385 (
386  le_mcc_CallRef_t callRef
387  ///< [IN] The call reference to read from.
388 );
389 
390 //--------------------------------------------------------------------------------------------------
391 /**
392  * Called to get the platform specific termination code.
393  *
394  * Refer to @ref platformConstraintsSpecificErrorCodes for platform specific
395  * termination code description.
396  *
397  * @return The platform specific termination code.
398  *
399  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
400  * function will not return.
401  */
402 //--------------------------------------------------------------------------------------------------
404 (
405  le_mcc_CallRef_t callRef
406  ///< [IN] The call reference to read from.
407 );
408 
409 //--------------------------------------------------------------------------------------------------
410 /**
411  * Answers incoming call.
412  *
413  * @return LE_TIMEOUT No response was received from the Modem.
414  * @return LE_OK The function succeeded.
415  *
416  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
417  * function will not return.
418  * @note A call waiting call must be answered using SetCallActive() API. This API doesn't manage
419  * call waiting supplementary service.
420  */
421 //--------------------------------------------------------------------------------------------------
423 (
424  le_mcc_CallRef_t callRef
425  ///< [IN] The call reference.
426 );
427 
428 //--------------------------------------------------------------------------------------------------
429 /**
430  * Disconnect, or hang up, the specifed call. Any active call handlers
431  * will be notified.
432  *
433  * @return LE_FAULT The function failed.
434  * @return LE_TIMEOUT No response was received from the Modem.
435  * @return LE_OK Function succeeded.
436  *
437  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
438  * function will not return.
439  * @note this API can also be used to disconnect a waiting or on hold call.
440  */
441 //--------------------------------------------------------------------------------------------------
443 (
444  le_mcc_CallRef_t callRef
445  ///< [IN] The call to end.
446 );
447 
448 //--------------------------------------------------------------------------------------------------
449 /**
450  * This function will disconnect, or hang up all the ongoing calls. Any active call handlers will
451  * be notified.
452  *
453  * @return LE_FAULT The function failed.
454  * @return LE_TIMEOUT No response was received from the Modem.
455  * @return LE_OK The function succeeded.
456  */
457 //--------------------------------------------------------------------------------------------------
459 (
460  void
461 );
462 
463 //--------------------------------------------------------------------------------------------------
464 /**
465  * This function return the Calling Line Identification Restriction (CLIR) status on the specific
466  * call.
467  *
468  * The output parameter is updated with the CLIR status.
469  * - LE_ON Disable presentation of own phone number to remote.
470  * - LE_OFF Enable presentation of own phone number to remote.
471  *
472  * @return
473  * - LE_OK The function succeed.
474  * - LE_NOT_FOUND The call reference was not found.
475  * - LE_UNAVAILABLE CLIR status was not set.
476  */
477 //--------------------------------------------------------------------------------------------------
479 (
480  le_mcc_CallRef_t callRef,
481  ///< [IN] The call reference.
482  le_onoff_t* clirStatusPtrPtr
483  ///< [OUT] the Calling Line Identification Restriction (CLIR) status
484 );
485 
486 //--------------------------------------------------------------------------------------------------
487 /**
488  * This function set the Calling Line Identification Restriction (CLIR) status on the specific call.
489  * By default the CLIR status is not set.
490  *
491  * @return
492  * - LE_OK The function succeed.
493  * - LE_NOT_FOUND The call reference was not found.
494  *
495  */
496 //--------------------------------------------------------------------------------------------------
498 (
499  le_mcc_CallRef_t callRef,
500  ///< [IN] The call reference.
501  le_onoff_t clirStatus
502  ///< [IN] The Calling Line Identification Restriction (CLIR) status.
503 );
504 
505 //--------------------------------------------------------------------------------------------------
506 /**
507  * Add handler function for EVENT 'le_mcc_CallEvent'
508  *
509  * Register an event handler that will be notified when an call's event occurs.
510  *
511  * @return A reference to the new event handler object.
512  *
513  * @note It is a fatal error if this function does succeed. If this function fails, it will not
514  * return.
515  *
516  */
517 //--------------------------------------------------------------------------------------------------
518 le_mcc_CallEventHandlerRef_t le_mcc_AddCallEventHandler
519 (
520  le_mcc_CallEventHandlerFunc_t handlerPtr,
521  ///< [IN]
522  void* contextPtr
523  ///< [IN]
524 );
525 
526 //--------------------------------------------------------------------------------------------------
527 /**
528  * Remove handler function for EVENT 'le_mcc_CallEvent'
529  */
530 //--------------------------------------------------------------------------------------------------
532 (
533  le_mcc_CallEventHandlerRef_t handlerRef
534  ///< [IN]
535 );
536 
537 //--------------------------------------------------------------------------------------------------
538 /**
539  * This function activates or deactivates the call waiting service.
540  *
541  * @return
542  * - LE_OK The function succeed.
543  * - LE_FAULT The function failed.
544  *
545  */
546 //--------------------------------------------------------------------------------------------------
548 (
549  bool active
550  ///< [IN] The call waiting activation.
551 );
552 
553 //--------------------------------------------------------------------------------------------------
554 /**
555  * This function gets the call waiting service status.
556  *
557  * @return
558  * - LE_OK The function succeed.
559  * - LE_FAULT The function failed.
560  *
561  */
562 //--------------------------------------------------------------------------------------------------
564 (
565  bool* activePtr
566  ///< [OUT] The call waiting activation.
567 );
568 
569 //--------------------------------------------------------------------------------------------------
570 /**
571  * This function activates the specified call. Other calls are placed on hold.
572  *
573  * @return
574  * - LE_OK The function succeed.
575  * - LE_FAULT The function failed.
576  *
577  */
578 //--------------------------------------------------------------------------------------------------
580 (
581  le_mcc_CallRef_t callRef
582  ///< [IN] The call reference.
583 );
584 
585 //--------------------------------------------------------------------------------------------------
586 /**
587  * This function enables/disables the audio AMR Wideband capability.
588  *
589  * @return
590  * - LE_OK The function succeeded.
591  * - LE_UNAVAILABLE The service is not available.
592  * - LE_FAULT On any other failure.
593  *
594  * @note The capability setting takes effect immediately and is not persistent to reset.
595  */
596 //--------------------------------------------------------------------------------------------------
598 (
599  bool enable
600  ///< [IN] True enables the AMR Wideband capability, false disables it.
601 );
602 
603 //--------------------------------------------------------------------------------------------------
604 /**
605  * This function gets the audio AMR Wideband capability.
606  *
607  * @return
608  * - LE_OK The function succeeded.
609  * - LE_UNAVAILABLE The service is not available.
610  * - LE_FAULT On any other failure.
611  */
612 //--------------------------------------------------------------------------------------------------
614 (
615  bool* enabledPtr
616  ///< [OUT] True if AMR Wideband capability is enabled, false otherwise.
617 );
618 
619 #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:153
le_onoff_t
Definition: le_basics.h:95