le_audio_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_audio Audio
14  *
15  * @ref le_audio_interface.h "API Reference" <br>
16  * @ref platformConstraintsAudio Constraints
17  *
18  * The Audio API handles audio interfaces including play and record supported formats.
19  *
20  * A Legato device can use several audio interfaces. You choose the input and output
21  * interfaces to tie together. The Audio stream related to a particular interface is
22  * represented with an 'Audio Stream Reference'.
23  *
24  * You can create your own audio path by connecting several audio streams together using
25  * audio connectors.
26  *
27  * An audio path can support more than two audio interfaces. You can have a basic output audio
28  * path of a voice call to connect the Modem Voice Received interface with the Speaker
29  * interface, and at the same time, the Modem Voice Received interface can be also connected to a
30  * Recorder Device interface.
31  *
32  * @section le_audio_binding IPC interfaces binding
33  *
34  * All the functions of this API are provided by the @b audioService.
35  *
36  * @note The functions that are highly dependent on the initialization of the lower layers of the
37  * @b audioService will return LE_UNAVAILABLE error code if those layers failed to initialize.
38  * Recovery can be attempted by restarting the service.
39  *
40  * Here's a code sample binding to audio services:
41  * @verbatim
42  bindings:
43  {
44  clientExe.clientComponent.le_audio -> audioService.le_audio
45  }
46  @endverbatim
47  *
48  * @section le_audio_configuration Configure the Audio
49  *
50  * The audio profile can be set with the le_audio_SetProfile() function.
51  *
52  * @warning Ensure to check the number of supported audio profiles for your specific platform.
53  *
54  * An audio profile can be retrieved with le_audio_GetProfile() and set with le_audio_SetProfile().
55  *
56  * Then, the following functions let you enable or disable the audio settings on the selected audio
57  * interface:
58  * - le_audio_EnableNoiseSuppressor()/le_audio_DisableNoiseSuppressor(): Noise Suppressor.
59  * - le_audio_EnableEchoCanceller()/ le_audio_DisableEchoCanceller(): Echo Canceller.
60  * - le_audio_EnableFirFilter()/ le_audio_DisableFirFilter(): downlink FIR Filter (Finite Impulse
61  * Response).
62  * - le_audio_EnableIirFilter()/ le_audio_DisableIirFilter(): downlink IIR Filter (Infinite Impulse
63  * Response).
64  * - le_audio_EnableAutomaticGainControl()/ le_audio_DisableAutomaticGainControl(): automatic
65  * gain on the selected audio stream.
66  *
67  * - le_audio_IsNoiseSuppressorEnabled(): To get the status of Noise Suppressor.
68  * - le_audio_IsEchoCancellerEnabled(): To get the status of Echo Canceller.
69  *
70  * To configure the encoding format, use le_audio_GetEncodingFormat() and le_audio_SetEncodingFormat().
71  *
72  * To configure gain settings, use le_audio_GetGain() and le_audio_SetGain().
73  *
74  * PCM has the following configuration get/set functions:
75  * - le_audio_GetPcmSamplingRate() and le_audio_SetPcmSamplingRate() for Hz rate.
76  * - le_audio_GetPcmSamplingResolution() and le_audio_SetPcmSamplingResolution() for bit/sample settings.
77  * - le_audio_GetPcmCompanding() and le_audio_SetPcmCompanding() for signal settings.
78  * - le_audio_GetSamplePcmChannelNumber() and le_audio_SetSamplePcmChannelNumber() for channel numbers.
79  *
80  * To Mute/Unmute the Call Waiting Tone to alert for an incoming voice call when a voice call is
81  * already in progress, use le_audio_MuteCallWaitingTone() and le_audio_UnmuteCallWaitingTone().
82  *
83  * @note The Call Waiting Supplementary Service must be enabled.
84  *
85  * @section le_audio_interfaces Open/Close an Audio Interface
86  *
87  * The following functions let you select the desired interface attributes. Please check the
88  * platform constraints in @subpage platformConstraintsAudio page to ensure that the function is
89  * supported before calling it:
90  *
91  * - le_audio_OpenMic(): returns an Audio Stream Reference of the analog audio signal coming from
92  * the microphone input.
93  * - le_audio_OpenSpeaker(): returns an Audio Stream Reference of the analog audio signal routed
94  * to the Speaker output.
95  * - le_audio_OpenUsbRx(): returns an Audio Stream Reference of the digitized audio signal coming
96  * from an external device connected via USB Audio Class.
97  * - le_audio_OpenUsbTx(): returns an Audio Stream Reference of the digitized audio signal routed
98  * to an external device connected via USB Audio Class.
99  * - le_audio_OpenPcmRx(): it returns an Audio Stream Reference of the digitized audio signal
100  * coming from an external device connected via the PCM interface.
101  * - le_audio_OpenPcmTx(): it returns an Audio Stream Reference of the digitized audio signal
102  * routed to an external device connected via the PCM interface.
103  * - le_audio_OpenI2sRx(): it returns an Audio Stream Reference of the digitized audio signal
104  * coming from an external device connected via the I2S interface.
105  * - le_audio_OpenI2sTx(): it returns an Audio Stream Reference of the digitized audio signal
106  * routed to an external device connected via the I2S interface.
107  * - le_audio_OpenModemVoiceRx(): returns an Audio Stream Reference of the digitized audio signal
108  * coming from a voice call. The audio format is negotiated with the
109  * network when the call is established.
110  * - le_audio_OpenModemVoiceTx(): returns an Audio Stream Reference of the digitized audio signal
111  * routed to a voice call. The audio format is negotiated with the
112  * network when the call is established.
113  *
114  * Multiple users can own the same stream at the same time.
115  *
116  * le_audio_GetDefaultPcmTimeSlot() can be called to get the default PCM time slot used on the
117  * current platform.
118  *
119  * le_audio_GetDefaultI2sMode() can be called to get the default I2s channel mode slot used on
120  * the current platform.
121  *
122  * Call le_audio_Close() to release it. If
123  * several users own the same, corresponding stream reference, the interface will
124  * close only after the last user releases the audio stream.
125  *
126  * You can configure the PCM interface with the le_audio_SetPcmSamplingRate(),
127  * le_audio_SetPcmSamplingResolution() and le_audio_SetPcmCompanding() functions.
128  * This function must be called before activating an audio path with the PCM interface, in other
129  * words you must call this function before connecting the PCM Stream to a connector.
130  *
131  * In addition, the le_audio_GetPcmSamplingRate(), le_audio_GetPcmSamplingResolution() and
132  * le_audio_GetPcmCompanding() functions allows you to retrieve the PCM interface configuration.
133  *
134  * @note Opening a Legato audio stream doesn’t necessarily interact with the audio HW interface.
135  * On most platforms, it only allocates a context in memory. The audio path becomes active when the
136  * streams are plugged into a connector.
137  *
138  *
139  * @section le_audio_streams Control an Audio Stream
140  *
141  * Once the users get an Audio Stream reference, they can control it with the following functions:
142  *
143  * - le_audio_SetGain(): adjust the gain of an audio stream (gain value is specific to the
144  * platform).
145  * - le_audio_GetGain(): retrieve the gain of an audio stream (gain value is specific to the
146  * platform).
147  * - le_audio_Mute(): mute an audio stream.
148  * - le_audio_Unmute(): unmute an audio stream.
149  *
150  * @note Multimedia (playback and recording) must be controlled separately from the main audio path
151  * (Microphone/Speaker, I2S, PCM, USB). Muting/Unmuting a multimedia is done by
152  * muting/unmuting the multimedia stream, and not the other connected stream. For example, in case
153  * of playback + voice on the speaker, if the user wants to mute all the audio coming out of the
154  * speaker, it must mute both the Speaker stream and the playback stream.
155  *
156  * @warning Ensure to check the list of supported audio streams for these functions on your
157  * specific platform.
158  *
159  * In the case your platform can support other gains in your audio subsystem, you can set or get
160  * the value of them with the following functions:
161  *
162  * - le_audio_SetPlatformSpecificGain(): adjust the value of a platform specific gain in the audio
163  * subsystem.
164  * - le_audio_GetPlatformSpecificGain(): retrieve the value of a platform specific gain in the
165  * audio subsystem.
166  *
167  * @warning Ensure to check the names of supported gains for your specific platform.
168  *
169  * @section le_audio_connectors Create Audio connectors
170  *
171  * You can create your own audio path by connecting several audio streams together.
172  *
173  * le_audio_CreateConnector() function creates a reference to an audio connector.
174  *
175  * You can tie an audio stream to a connector by calling the le_audio_Connect()
176  * function.
177  *
178  * You can remove an audio stream from a connector by calling the le_audio_Disconnect()
179  * function.
180  *
181  * When finished with it, delete it using the le_audio_DeleteConnector() function.
182  *
183  * The following image shows how to connect a Player stream to play a file towards a remote end
184  * during a voice call.
185  * @image html AudioConnector.png
186  *
187  * A sample code that implements audio connectors and audio streams during voice call can be found in
188  * \b audioMccTest.c file (please refer to @ref c_audioMcc page).
189  *
190  * @note It is recommended to set the connectors before the connected streams are used.
191  * In particular, a connector using Modem Voice Rx or Tx interfaces has to be created before dialing
192  * or answering the call if the application needs to customize the audio path.
193  *
194  * @section le_audio_pb_playback Playback
195  *
196  * An audio file can be played to any active output interfaces.
197  *
198  * Open a player interface by calling:
199  * - le_audio_OpenPlayer(): returns an Audio Stream Reference for file playback.
200  * An audio file can be played on the local audio interface like
201  * Speaker, USB Tx, PCM Tx, I2S Tx or on the remote audio
202  * interface Modem Voice Tx depending the kind of connector
203  * (input or output) is tied to.
204  *
205  * - le_audio_PlayFile(): plays a specified file. WAVE (Waveform audio file) and
206  * AMR (Adaptive Multi Rate) are supported.
207  * AMR is an audio compression format optimized for speech coding. Two codecs are supported:
208  * - AMR_NB (AMR Narrowband) codec that encodes narrowband (200--3400 Hz) signals at variable bit
209  * rates ranging from 4.75 to 12.2 kbit/s. It was adopted as the standard speech codec by 3GPP.
210  * - AMR-WB (AMR Wideband) is an ITU-T standard speech codec which improved speech quality due to a
211  * wider speech bandwidth of 50--7000 Hz.
212  *
213  * - le_audio_PlaySamples(): initiates a playback using an audio flow. A pipe has
214  * to be opened first, then the PCM samples are sent through the opened pipe.
215  * A play can be done only on a connected stream. For instance, the
216  * "I2S Tx", "Modem Voice Rx" and "Player" must be previously connected before playing a file.
217  * If there are no more PCM samples to be played, the playback must be stopped by calling
218  * le_audio_Stop().
219  *
220  * @section le_audio_pb_rec Record
221  *
222  * * Audio file recording can be done from any active input interface.
223  *
224  * Open a "File Recording" interface by calling:
225  * - le_audio_OpenRecorder(): returns an Audio Stream Reference for file recording.
226  * The local audio interface like Microphone, USB Rx, PCM Rx,
227  * I2S Rx is recorded into an audio file; or the Modem Voice Rx
228  * remote audio interface is recorded into an audio file,
229  * depending the kind of connector (input or output) is tied to.
230  * - le_audio_RecordFile(): records in a specified file.
231  * - le_audio_SetEncodingFormat(): sets the encoding format. The same formats as the
232  * player are supported.
233  * - le_audio_GetEncodingFormat(): gets the encoding format.
234  * - le_audio_GetSamples(): records the audio PCM samples. A pipe has
235  * to be opened first, then the PCM samples are sent through the opened pipe.
236  * Recording can only be done on a connected stream. For example, the
237  * "I2S Rx", "Modem Voice Tx" and "Recorder" must be previously connected before recording a file.
238  * If there are no more PCM samples to be retrieved, the recording must be stopped by calling
239  * le_audio_Stop().
240  *
241  * A PCM configuration must be set with:
242  * - le_audio_SetSamplePcmChannelNumber(): sets the channel number of a PCM
243  * sample.
244  * - le_audio_SetSamplePcmSamplingRate(): sets the sampling rate of a PCM
245  * sample.
246  * - le_audio_SetSamplePcmSamplingResolution(): sets the sampling resolution
247  * (in bits per sample) of a PCM sample.
248  *
249  * The PCM samples configuration can be retrieved with:
250  * - le_audio_GetSamplePcmChannelNumber(): gets the channel number of a PCM
251  * sample.
252  * - le_audio_GetSamplePcmSamplingRate(): gets the sampling rate of a PCM
253  * sample.
254  * - le_audio_GetSamplePcmSamplingResolution(): can be called to get the sampling resolution
255  * (in bits per sample) of a PCM sample.
256  * The default configuration is PCM 16-bit audio @ 8KHz one channel.
257  *
258  * An AMR configuration must be set with:
259  * - le_audio_SetSampleAmrMode(): sets the AMR mode (NB/WB, bitrate).
260  * - le_audio_SetSampleAmrDtx(): can be called to activate/deactivate the Discontinuous
261  * Transmission (DTX) to reduce bandwidth usage during silence periods.
262  * The AMR configuration can be retrieved with:
263  * - le_audio_GetSampleAmrMode(): gets the AMR mode.
264  * - le_audio_GetSampleAmrDtx(): gets the Discontinuous
265  * Transmission (DTX).
266  *
267  * To stop a play/record call le_audio_Stop():
268  * - The playback/record stops playing/recording, and the read/write position indicator associated
269  * with the file stream is rewound to the beginning of the file. A new file can be played/recorded
270  * using le_audio_PlayFile()/le_audio_PlaySamples()/le_audio_RecordFile()/le_audio_GetSamples().
271  * - le_audio_Pause(): can be called to pause a play/record. The file playing/recording is put on
272  * hold, the read/write position indicator of the file is not moved.
273  * - le_audio_Resume(): can be called to resume a paused play/record. The file playing/recording
274  * continues at the file's position indicator held after the pause.
275  * - le_audio_Flush(): can be called to flush the remaining audio samples before sending
276  * them to the audio driver.
277  *
278  * You can also register a handler function for media-related notifications like errors or audio
279  * events.
280  *
281  * le_audio_AddMediaHandler() function installs a handler for player/recorder stream
282  * notifications.
283  *
284  * le_audio_RemoveMediaHandler() function removes the player/recorder handler function.
285  *
286  * @note The @c LE_AUDIO_MEDIA_NO_MORE_SAMPLES event indicates when all samples put into the pipe
287  * by the user's App have been sent to the audio driver (see le_audio_PlaySamples()).
288  *
289  * A sample code that implements audio playback and capture can be found in \b audioPlaybackRec.c
290  * file (please refer to @ref c_audioCapturePlayback page).
291  *
292  * @section le_audio_dtmf DTMF
293  *
294  * The le_audio_PlayDtmf() function allows the application to play one or several DTMF on a playback
295  * stream. The duration and the pause of the DTMFs must also be specified with the input parameters.
296  *
297  * The le_audio_PlaySignallingDtmf() function allows the application to ask the Mobile Network to
298  * generate on the remote audio party the DTMFs. Compared with le_audio_PlayDtmf(),
299  * le_audio_PlaySignallingDtmf() function may offer a better signal quality, but the the duration
300  * and the pause timings may be less accurate.
301  *
302  * The application must register a handler function to detect incoming DTMF characters on a specific
303  * input audio stream. The le_audio_AddDtmfDetectorHandler() function installs a handler for DTMF
304  * detection.
305  *
306  * The le_audio_RemoveDtmfDetectorHandler() function uninstalls the handler function.
307  *
308  * The DTMFs are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, #, A, B, C, D. Not case sensitive.
309  *
310  * @note The DTMF decoding works only on an active audio path.
311  *
312  * A sample code that implements DTMF playback and decoding can be found in \b audioDtmfTest.c file
313  * (please refer to @ref c_audiodtmf page).
314  *
315  * <HR>
316  *
317  * Copyright (C) Sierra Wireless Inc.
318  */
319 /**
320  * @file le_audio_interface.h
321  *
322  * Legato @ref c_audio include file.
323  *
324  * Copyright (C) Sierra Wireless Inc.
325  */
326 /**
327  * @page c_audioMcc Sample code of audio settings for a dialing call
328  *
329  * @include "apps/test/audio/audioMcc/audioMccComp/audioMccTest.c"
330  */
331 /**
332  * @page c_audiodtmf Sample code of dtmf playback and decoding
333  *
334  * @include "apps/test/audio/dtmf/dtmfTestComp/audioDtmfTest.c"
335  */
336 /**
337  * @page c_audioCapturePlayback Sample code of audio playback and capture
338  *
339  * @include "apps/test/audio/audioPlaybackRec/audioPlaybackRecComp/audioPlaybackRec.c"
340  */
341 
342 #ifndef LE_AUDIO_INTERFACE_H_INCLUDE_GUARD
343 #define LE_AUDIO_INTERFACE_H_INCLUDE_GUARD
344 
345 
346 #include "legato.h"
347 
348 // Internal includes for this interface
349 #include "le_audio_common.h"
350 /** @addtogroup le_audio le_audio API Reference
351  * @{
352  * @file le_audio_common.h
353  * @file le_audio_interface.h **/
354 //--------------------------------------------------------------------------------------------------
355 /**
356  * Type for handler called when a server disconnects.
357  */
358 //--------------------------------------------------------------------------------------------------
359 typedef void (*le_audio_DisconnectHandler_t)(void *);
360 
361 //--------------------------------------------------------------------------------------------------
362 /**
363  *
364  * Connect the current client thread to the service providing this API. Block until the service is
365  * available.
366  *
367  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
368  * called before any other functions in this API. Normally, ConnectService is automatically called
369  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
370  *
371  * This function is created automatically.
372  */
373 //--------------------------------------------------------------------------------------------------
375 (
376  void
377 );
378 
379 //--------------------------------------------------------------------------------------------------
380 /**
381  *
382  * Try to connect the current client thread to the service providing this API. Return with an error
383  * if the service is not available.
384  *
385  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
386  * called before any other functions in this API. Normally, ConnectService is automatically called
387  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
388  *
389  * This function is created automatically.
390  *
391  * @return
392  * - LE_OK if the client connected successfully to the service.
393  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
394  * bound.
395  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
396  * - LE_COMM_ERROR if the Service Directory cannot be reached.
397  */
398 //--------------------------------------------------------------------------------------------------
400 (
401  void
402 );
403 
404 //--------------------------------------------------------------------------------------------------
405 /**
406  * Set handler called when server disconnection is detected.
407  *
408  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
409  * to continue without exiting, it should call longjmp() from inside the handler.
410  */
411 //--------------------------------------------------------------------------------------------------
413 (
414  le_audio_DisconnectHandler_t disconnectHandler,
415  void *contextPtr
416 );
417 
418 //--------------------------------------------------------------------------------------------------
419 /**
420  *
421  * Disconnect the current client thread from the service providing this API.
422  *
423  * Normally, this function doesn't need to be called. After this function is called, there's no
424  * longer a connection to the service, and the functions in this API can't be used. For details, see
425  * @ref apiFilesC_client.
426  *
427  * This function is created automatically.
428  */
429 //--------------------------------------------------------------------------------------------------
431 (
432  void
433 );
434 
435 
436 //--------------------------------------------------------------------------------------------------
437 /**
438  * Audio recording/playback events.
439  */
440 //--------------------------------------------------------------------------------------------------
441 
442 
443 //--------------------------------------------------------------------------------------------------
444 /**
445  * Companding.
446  */
447 //--------------------------------------------------------------------------------------------------
448 
449 
450 //--------------------------------------------------------------------------------------------------
451 /**
452  * I2S channel mode.
453  */
454 //--------------------------------------------------------------------------------------------------
455 
456 
457 //--------------------------------------------------------------------------------------------------
458 /**
459  * Audio format.
460  */
461 //--------------------------------------------------------------------------------------------------
462 
463 
464 //--------------------------------------------------------------------------------------------------
465 /**
466  * AMR mode.
467  */
468 //--------------------------------------------------------------------------------------------------
469 
470 
471 //--------------------------------------------------------------------------------------------------
472 /**
473  * Reference type for Audio Stream
474  */
475 //--------------------------------------------------------------------------------------------------
476 
477 
478 //--------------------------------------------------------------------------------------------------
479 /**
480  * Reference type for Audio Connector
481  */
482 //--------------------------------------------------------------------------------------------------
483 
484 
485 //--------------------------------------------------------------------------------------------------
486 /**
487  * Handler for audio stream event.
488  *
489  */
490 //--------------------------------------------------------------------------------------------------
491 
492 
493 //--------------------------------------------------------------------------------------------------
494 /**
495  * Reference type used by Add/Remove functions for EVENT 'le_audio_Media'
496  */
497 //--------------------------------------------------------------------------------------------------
498 
499 
500 //--------------------------------------------------------------------------------------------------
501 /**
502  * Handler for DTMF decoding.
503  *
504  */
505 //--------------------------------------------------------------------------------------------------
506 
507 
508 //--------------------------------------------------------------------------------------------------
509 /**
510  * Reference type used by Add/Remove functions for EVENT 'le_audio_DtmfDetector'
511  */
512 //--------------------------------------------------------------------------------------------------
513 
514 
515 //--------------------------------------------------------------------------------------------------
516 /**
517  * Open the Microphone.
518  *
519  * @return Reference to the input audio stream, NULL if the function fails.
520  */
521 //--------------------------------------------------------------------------------------------------
523 (
524  void
525 );
526 
527 //--------------------------------------------------------------------------------------------------
528 /**
529  * Open the Speaker-phone.
530  *
531  * @return Reference to the output audio stream, NULL if the function fails.
532  */
533 //--------------------------------------------------------------------------------------------------
535 (
536  void
537 );
538 
539 //--------------------------------------------------------------------------------------------------
540 /**
541  * Open the received audio stream of an USB audio class.
542  *
543  * @return Reference to the input audio stream, NULL if the function fails.
544  */
545 //--------------------------------------------------------------------------------------------------
547 (
548  void
549 );
550 
551 //--------------------------------------------------------------------------------------------------
552 /**
553  * Open the transmitted audio stream of an USB audio class.
554  *
555  * @return Reference to the output audio stream, NULL if the function fails.
556  */
557 //--------------------------------------------------------------------------------------------------
559 (
560  void
561 );
562 
563 //--------------------------------------------------------------------------------------------------
564 /**
565  * Open the received audio stream of the PCM interface.
566  *
567  * @return Reference to the input audio stream, NULL if the function fails.
568  */
569 //--------------------------------------------------------------------------------------------------
571 (
572  uint32_t timeslot
573  ///< [IN] The time slot number.
574 );
575 
576 //--------------------------------------------------------------------------------------------------
577 /**
578  * Open the transmitted audio stream of the PCM interface.
579  *
580  * @return Reference to the output audio stream, NULL if the function fails.
581  */
582 //--------------------------------------------------------------------------------------------------
584 (
585  uint32_t timeslot
586  ///< [IN] The time slot number.
587 );
588 
589 //--------------------------------------------------------------------------------------------------
590 /**
591  * Open the received audio stream of the I2S interface.
592  *
593  * @return Reference to the input audio stream, NULL if the function fails.
594  */
595 //--------------------------------------------------------------------------------------------------
597 (
599  ///< [IN] The channel mode.
600 );
601 
602 //--------------------------------------------------------------------------------------------------
603 /**
604  * Open the transmitted audio stream of the I2S interface.
605  *
606  * @return Reference to the output audio stream, NULL if the function fails.
607  */
608 //--------------------------------------------------------------------------------------------------
610 (
612  ///< [IN] The channel mode.
613 );
614 
615 //--------------------------------------------------------------------------------------------------
616 /**
617  * Open the audio stream for playback.
618  *
619  * @return Reference to the audio stream, NULL if the function fails.
620  */
621 //--------------------------------------------------------------------------------------------------
623 (
624  void
625 );
626 
627 //--------------------------------------------------------------------------------------------------
628 /**
629  * Open the audio stream for recording.
630  *
631  * @return Reference to the audio stream, NULL if the function fails.
632  */
633 //--------------------------------------------------------------------------------------------------
635 (
636  void
637 );
638 
639 //--------------------------------------------------------------------------------------------------
640 /**
641  * Open the received audio stream of a voice call.
642  *
643  * @return Reference to the input audio stream, NULL if the function fails.
644  */
645 //--------------------------------------------------------------------------------------------------
647 (
648  void
649 );
650 
651 //--------------------------------------------------------------------------------------------------
652 /**
653  * Open the transmitted audio stream of a voice call.
654  *
655  * @return Reference to the output audio stream, NULL if the function fails.
656  */
657 //--------------------------------------------------------------------------------------------------
659 (
660  void
661 );
662 
663 //--------------------------------------------------------------------------------------------------
664 /**
665  * Add handler function for EVENT 'le_audio_Media'
666  *
667  * This event provides information on player / recorder stream events.
668  *
669  */
670 //--------------------------------------------------------------------------------------------------
672 (
673  le_audio_StreamRef_t streamRef,
674  ///< [IN] The audio stream reference.
675  le_audio_MediaHandlerFunc_t handlerPtr,
676  ///< [IN]
677  void* contextPtr
678  ///< [IN]
679 );
680 
681 //--------------------------------------------------------------------------------------------------
682 /**
683  * Remove handler function for EVENT 'le_audio_Media'
684  */
685 //--------------------------------------------------------------------------------------------------
687 (
688  le_audio_MediaHandlerRef_t handlerRef
689  ///< [IN]
690 );
691 
692 //--------------------------------------------------------------------------------------------------
693 /**
694  * Close an audio stream.
695  * If several users own the stream reference, the interface closes only after
696  * the last user closes the audio stream.
697  *
698  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
699  * function will not return.
700  */
701 //--------------------------------------------------------------------------------------------------
702 void le_audio_Close
703 (
704  le_audio_StreamRef_t streamRef
705  ///< [IN] Audio stream reference.
706 );
707 
708 //--------------------------------------------------------------------------------------------------
709 /**
710  * Set the Gain value of an input or output stream.
711  *
712  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
713  * @return LE_OUT_OF_RANGE The gain value is out of range.
714  * @return LE_UNAVAILABLE The audio service initialization failed.
715  * @return LE_FAULT On any other failure.
716  * @return LE_OK The function succeeded.
717  *
718  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
719  * function will not return.
720  */
721 //--------------------------------------------------------------------------------------------------
723 (
724  le_audio_StreamRef_t streamRef,
725  ///< [IN] Audio stream reference.
726  int32_t gain
727  ///< [IN] Gain value (specific to the platform)
728 );
729 
730 //--------------------------------------------------------------------------------------------------
731 /**
732  * Get the Gain value of an input or output stream.
733  *
734  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
735  * @return LE_UNAVAILABLE The audio service initialization failed.
736  * @return LE_FAULT On any other failure.
737  * @return LE_OK The function succeeded.
738  *
739  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
740  * function will not return.
741  */
742 //--------------------------------------------------------------------------------------------------
744 (
745  le_audio_StreamRef_t streamRef,
746  ///< [IN] Audio stream reference.
747  int32_t* gainPtr
748  ///< [OUT] Gain value (specific to the platform)
749 );
750 
751 //--------------------------------------------------------------------------------------------------
752 /**
753  * Mute an audio stream.
754  *
755  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
756  * @return LE_UNAVAILABLE The audio service initialization failed.
757  * @return LE_FAULT On any other failure.
758  * @return LE_OK The function succeeded.
759  *
760  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
761  * function will not return.
762  */
763 //--------------------------------------------------------------------------------------------------
765 (
766  le_audio_StreamRef_t streamRef
767  ///< [IN] Audio stream reference.
768 );
769 
770 //--------------------------------------------------------------------------------------------------
771 /**
772  * Unmute an audio stream.
773  *
774  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
775  * @return LE_UNAVAILABLE The audio service initialization failed.
776  * @return LE_FAULT On any other failure.
777  * @return LE_OK The function succeeded.
778  *
779  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
780  * function will not return.
781  */
782 //--------------------------------------------------------------------------------------------------
784 (
785  le_audio_StreamRef_t streamRef
786  ///< [IN] Audio stream reference.
787 );
788 
789 //--------------------------------------------------------------------------------------------------
790 /**
791  * Create an audio connector reference.
792  *
793  * @return Reference to the audio connector, NULL if the function fails.
794  */
795 //--------------------------------------------------------------------------------------------------
797 (
798  void
799 );
800 
801 //--------------------------------------------------------------------------------------------------
802 /**
803  * Delete an audio connector reference.
804  *
805  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
806  * function will not return.
807  */
808 //--------------------------------------------------------------------------------------------------
810 (
811  le_audio_ConnectorRef_t connectorRef
812  ///< [IN] Connector reference.
813 );
814 
815 //--------------------------------------------------------------------------------------------------
816 /**
817  * Connect an audio stream to the connector reference.
818  *
819  * @return LE_BUSY There are insufficient DSP resources available.
820  * @return LE_UNAVAILABLE The audio service initialization failed.
821  * @return LE_BAD_PARAMETER The connector and/or the audio stream references are invalid.
822  * @return LE_FAULT On any other failure.
823  * @return LE_OK The function succeeded.
824  *
825  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
826  * function will not return.
827  */
828 //--------------------------------------------------------------------------------------------------
830 (
831  le_audio_ConnectorRef_t connectorRef,
832  ///< [IN] Connector reference.
833  le_audio_StreamRef_t streamRef
834  ///< [IN] Audio stream reference.
835 );
836 
837 //--------------------------------------------------------------------------------------------------
838 /**
839  * Disconnect an audio stream from the connector reference.
840  *
841  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
842  * function will not return.
843  */
844 //--------------------------------------------------------------------------------------------------
846 (
847  le_audio_ConnectorRef_t connectorRef,
848  ///< [IN] Connector reference.
849  le_audio_StreamRef_t streamRef
850  ///< [IN] Audio stream reference.
851 );
852 
853 //--------------------------------------------------------------------------------------------------
854 /**
855  * Add handler function for EVENT 'le_audio_DtmfDetector'
856  *
857  * This event provides information on DTMF decoding for the specified streamRef
858  *
859  */
860 //--------------------------------------------------------------------------------------------------
862 (
863  le_audio_StreamRef_t streamRef,
864  ///< [IN] Audio stream reference.
866  ///< [IN]
867  void* contextPtr
868  ///< [IN]
869 );
870 
871 //--------------------------------------------------------------------------------------------------
872 /**
873  * Remove handler function for EVENT 'le_audio_DtmfDetector'
874  */
875 //--------------------------------------------------------------------------------------------------
877 (
879  ///< [IN]
880 );
881 
882 //--------------------------------------------------------------------------------------------------
883 /**
884  * This function must be called to enable the Noise Suppressor.
885  *
886  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
887  * @return LE_UNAVAILABLE The audio service initialization failed.
888  * @return LE_FAULT On any other failure.
889  * @return LE_OK Function succeeded.
890  *
891  * @note The process exits, if an invalid audio stream reference is given.
892  */
893 //--------------------------------------------------------------------------------------------------
895 (
896  le_audio_StreamRef_t streamRef
897  ///< [IN] Audio stream reference.
898 );
899 
900 //--------------------------------------------------------------------------------------------------
901 /**
902  * This function must be called to disable the Noise Suppressor.
903  *
904  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
905  * @return LE_UNAVAILABLE The audio service initialization failed.
906  * @return LE_FAULT On any other failure.
907  * @return LE_OK Function succeeded.
908  *
909  * @note The process exits, if an invalid audio stream reference is given.
910  */
911 //--------------------------------------------------------------------------------------------------
913 (
914  le_audio_StreamRef_t streamRef
915  ///< [IN] Audio stream reference.
916 );
917 
918 //--------------------------------------------------------------------------------------------------
919 /**
920  * This function must be called to enable the Echo Canceller.
921  *
922  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
923  * @return LE_UNAVAILABLE The audio service initialization failed.
924  * @return LE_FAULT On any other failure.
925  * @return LE_OK Function succeeded.
926  *
927  * @note The process exits, if an invalid audio stream reference is given.
928  */
929 //--------------------------------------------------------------------------------------------------
931 (
932  le_audio_StreamRef_t streamRef
933  ///< [IN] Audio stream reference.
934 );
935 
936 //--------------------------------------------------------------------------------------------------
937 /**
938  * This function must be called to disable the Echo Canceller.
939  *
940  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
941  * @return LE_UNAVAILABLE The audio service initialization failed.
942  * @return LE_FAULT On any other failure.
943  * @return LE_OK Function succeeded.
944  *
945  * @note The process exits, if an invalid audio stream reference is given.
946  */
947 //--------------------------------------------------------------------------------------------------
949 (
950  le_audio_StreamRef_t streamRef
951  ///< [IN] Audio stream reference.
952 );
953 
954 //--------------------------------------------------------------------------------------------------
955 /**
956  * This function must be called to get the status of Noise Suppressor.
957  *
958  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
959  * @return LE_UNAVAILABLE The audio service initialization failed.
960  * @return LE_FAULT On any other failure.
961  * @return LE_OK Function succeeded.
962  *
963  * @note The process exits, if an invalid audio stream reference is given.
964  */
965 //--------------------------------------------------------------------------------------------------
967 (
968  le_audio_StreamRef_t streamRef,
969  ///< [IN] Audio stream reference.
970  bool* statusPtr
971  ///< [OUT] true if NS is enabled, false otherwise
972 );
973 
974 //--------------------------------------------------------------------------------------------------
975 /**
976  * This function must be called to get the status of Echo Canceller.
977  *
978  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
979  * @return LE_UNAVAILABLE The audio service initialization failed.
980  * @return LE_FAULT On any other failure.
981  * @return LE_OK Function succeeded.
982  *
983  * @note The process exits, if an invalid audio stream reference is given.
984  */
985 //--------------------------------------------------------------------------------------------------
987 (
988  le_audio_StreamRef_t streamRef,
989  ///< [IN] Audio stream reference.
990  bool* statusPtr
991  ///< [OUT] true if EC is enabled, false otherwise
992 );
993 
994 //--------------------------------------------------------------------------------------------------
995 /**
996  * This function must be called to enable the FIR (Finite Impulse Response) filter.
997  *
998  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
999  * @return LE_UNAVAILABLE The audio service initialization failed.
1000  * @return LE_FAULT On any other failure.
1001  * @return LE_OK Function succeeded.
1002  *
1003  * @note The process exits, if an invalid audio stream reference is given.
1004  */
1005 //--------------------------------------------------------------------------------------------------
1007 (
1008  le_audio_StreamRef_t streamRef
1009  ///< [IN] Audio stream reference.
1010 );
1011 
1012 //--------------------------------------------------------------------------------------------------
1013 /**
1014  * This function must be called to disable the FIR (Finite Impulse Response) filter.
1015  *
1016  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1017  * @return LE_UNAVAILABLE The audio service initialization failed.
1018  * @return LE_FAULT On any other failure.
1019  * @return LE_OK Function succeeded.
1020  *
1021  * @note The process exits, if an invalid audio stream reference is given.
1022  */
1023 //--------------------------------------------------------------------------------------------------
1025 (
1026  le_audio_StreamRef_t streamRef
1027  ///< [IN] Audio stream reference.
1028 );
1029 
1030 //--------------------------------------------------------------------------------------------------
1031 /**
1032  * This function must be called to enable the IIR (Infinite Impulse Response) filter.
1033  *
1034  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1035  * @return LE_UNAVAILABLE The audio service initialization failed.
1036  * @return LE_FAULT On any other failure.
1037  * @return LE_OK Function succeeded.
1038  *
1039  * @note The process exits, if an invalid audio stream reference is given.
1040  */
1041 //--------------------------------------------------------------------------------------------------
1043 (
1044  le_audio_StreamRef_t streamRef
1045  ///< [IN] Audio stream reference.
1046 );
1047 
1048 //--------------------------------------------------------------------------------------------------
1049 /**
1050  * This function must be called to disable the IIR (Infinite Impulse Response) filter.
1051  *
1052  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1053  * @return LE_UNAVAILABLE The audio service initialization failed.
1054  * @return LE_FAULT On any other failure.
1055  * @return LE_OK Function succeeded.
1056  *
1057  * @note The process exits, if an invalid audio stream reference is given.
1058  */
1059 //--------------------------------------------------------------------------------------------------
1061 (
1062  le_audio_StreamRef_t streamRef
1063  ///< [IN] Audio stream reference.
1064 );
1065 
1066 //--------------------------------------------------------------------------------------------------
1067 /**
1068  * This function must be called to enable the automatic gain control on the selected audio stream.
1069  *
1070  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1071  * @return LE_UNAVAILABLE The audio service initialization failed.
1072  * @return LE_FAULT On any other failure.
1073  * @return LE_OK Function succeeded.
1074  *
1075  * @note The process exits, if an invalid audio stream reference is given.
1076  */
1077 //--------------------------------------------------------------------------------------------------
1079 (
1080  le_audio_StreamRef_t streamRef
1081  ///< [IN] Audio stream reference.
1082 );
1083 
1084 //--------------------------------------------------------------------------------------------------
1085 /**
1086  * This function must be called to disable the automatic gain control on the selected audio stream.
1087  *
1088  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1089  * @return LE_UNAVAILABLE The audio service initialization failed.
1090  * @return LE_FAULT On any other failure.
1091  * @return LE_OK Function succeeded.
1092  *
1093  * @note The process exits, if an invalid audio stream reference is given.
1094  */
1095 //--------------------------------------------------------------------------------------------------
1097 (
1098  le_audio_StreamRef_t streamRef
1099  ///< [IN] Audio stream reference.
1100 );
1101 
1102 //--------------------------------------------------------------------------------------------------
1103 /**
1104  * This function must be called to set the audio profile.
1105  *
1106  * @return LE_UNAVAILABLE On audio service initialization failure.
1107  * @return LE_FAULT On any other failure.
1108  * @return LE_OK Function succeeded.
1109  *
1110  */
1111 //--------------------------------------------------------------------------------------------------
1113 (
1114  uint32_t profile
1115  ///< [IN] Audio profile.
1116 );
1117 
1118 //--------------------------------------------------------------------------------------------------
1119 /**
1120  * This function must be called to get the audio profile in use.
1121  *
1122  * @return LE_UNAVAILABLE On audio service initialization failure.
1123  * @return LE_FAULT On any other failure.
1124  * @return LE_OK Function succeeded.
1125  *
1126  */
1127 //--------------------------------------------------------------------------------------------------
1129 (
1130  uint32_t* profilePtr
1131  ///< [OUT] Audio profile.
1132 );
1133 
1134 //--------------------------------------------------------------------------------------------------
1135 /**
1136  * Configure the PCM Sampling Rate.
1137  *
1138  * @return LE_FAULT Function failed.
1139  * @return LE_OUT_OF_RANGE Your platform does not support the setting's value.
1140  * @return LE_BUSY PCM interface is already active.
1141  * @return LE_OK Function succeeded.
1142  */
1143 //--------------------------------------------------------------------------------------------------
1145 (
1146  uint32_t rate
1147  ///< [IN] Sampling rate in Hz.
1148 );
1149 
1150 //--------------------------------------------------------------------------------------------------
1151 /**
1152  * Configure the PCM Sampling Resolution.
1153  *
1154  * @return LE_FAULT Function failed.
1155  * @return LE_OUT_OF_RANGE Your platform does not support the setting's value.
1156  * @return LE_BUSY PCM interface is already active.
1157  * @return LE_OK Function succeeded.
1158  */
1159 //--------------------------------------------------------------------------------------------------
1161 (
1162  uint32_t bitsPerSample
1163  ///< [IN] Sampling resolution (bits/sample).
1164 );
1165 
1166 //--------------------------------------------------------------------------------------------------
1167 /**
1168  * Configure the PCM Companding.
1169  *
1170  * @return LE_FAULT Function failed.
1171  * @return LE_OUT_OF_RANGE Your platform does not support the setting's value.
1172  * @return LE_BUSY PCM interface is already active.
1173  * @return LE_OK Function succeeded.
1174  */
1175 //--------------------------------------------------------------------------------------------------
1177 (
1178  le_audio_Companding_t companding
1179  ///< [IN] Companding.
1180 );
1181 
1182 //--------------------------------------------------------------------------------------------------
1183 /**
1184  * Retrieve the PCM Sampling Rate.
1185  *
1186  * @return The sampling rate in Hz.
1187  */
1188 //--------------------------------------------------------------------------------------------------
1190 (
1191  void
1192 );
1193 
1194 //--------------------------------------------------------------------------------------------------
1195 /**
1196  * Retrieve the PCM Sampling Resolution.
1197  *
1198  * @return The sampling resolution (bits/sample).
1199  */
1200 //--------------------------------------------------------------------------------------------------
1202 (
1203  void
1204 );
1205 
1206 //--------------------------------------------------------------------------------------------------
1207 /**
1208  * Retrieve the PCM Companding.
1209  *
1210  * @return The PCM companding.
1211  */
1212 //--------------------------------------------------------------------------------------------------
1214 (
1215  void
1216 );
1217 
1218 //--------------------------------------------------------------------------------------------------
1219 /**
1220  * Get the default PCM time slot used on the current platform.
1221  *
1222  * @return the time slot number.
1223  */
1224 //--------------------------------------------------------------------------------------------------
1226 (
1227  void
1228 );
1229 
1230 //--------------------------------------------------------------------------------------------------
1231 /**
1232  * Get the default I2S channel mode used on the current platform.
1233  *
1234  * @return the I2S channel mode.
1235  */
1236 //--------------------------------------------------------------------------------------------------
1238 (
1239  void
1240 );
1241 
1242 //--------------------------------------------------------------------------------------------------
1243 /**
1244  * Play a file on a playback stream.
1245  *
1246  * @return LE_FAULT Function failed.
1247  * @return LE_BAD_PARAMETER Audio stream reference is invalid.
1248  * @return LE_BUSY Player interface is already active.
1249  * @return LE_OK Function succeeded.
1250  *
1251  * @note
1252  * - The fd is closed by the IPC API. To play again the same file, the fd parameter can be set
1253  * to LE_AUDIO_NO_FD: in this case, the previous file descriptor is re-used.
1254  * If the fd as to be kept on its side, the application should duplicate the fd (e.g., using
1255  * dup() ) before calling the API.
1256  * In that case, the old and new file descriptors refer to the same open file description and
1257  * thus share file offset. So, once a playback has reached the end of file, the application must
1258  * reset the file offset by using lseek on the duplicated descriptor to start the playback from
1259  * the beginning.
1260  *
1261  * @note
1262  * - Calling le_audio_PlayFile(<..>, LE_AUDIO_NO_FD) will rewind the audio file to the
1263  * beginning when a playback is already in progress.
1264  *
1265  */
1266 //--------------------------------------------------------------------------------------------------
1268 (
1269  le_audio_StreamRef_t streamRef,
1270  ///< [IN] Audio stream reference.
1271  int fd
1272  ///< [IN] File descriptor.
1273 );
1274 
1275 //--------------------------------------------------------------------------------------------------
1276 /**
1277  * Initiate a playback sending samples over a pipe.
1278  *
1279  * @return LE_FAULT Function failed.
1280  * @return LE_BUSY Player interface is already active.
1281  * @return LE_OK Function succeeded.
1282  *
1283  * @note The fd is closed by the IPC API. To use again the same pipe, the fd parameter can be set
1284  * to LE_AUDIO_NO_FD: in this case, the previous file descriptor is re-used.
1285  * If the fd as to be kept on its side, the application should duplicate the fd (e.g., using dup() )
1286  * before calling the API.
1287  *
1288  * @note Playback initiated with this function must be stopped by calling le_audio_Stop().
1289  */
1290 //--------------------------------------------------------------------------------------------------
1292 (
1293  le_audio_StreamRef_t streamRef,
1294  ///< [IN] Audio stream reference.
1295  int fd
1296  ///< [IN] File descriptor.
1297 );
1298 
1299 //--------------------------------------------------------------------------------------------------
1300 /**
1301  * Record a file on a recorder stream.
1302  *
1303  * @return LE_FAULT Function failed.
1304  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1305  * @return LE_BUSY Recorder interface is already active.
1306  * @return LE_OK Function succeeded.
1307  *
1308  * @note the fd is closed by the API. To record again the same file, the fd parameter can be set to
1309  * LE_AUDIO_NO_FD: in this case, the previous file descriptor is re-used.
1310  * If the fd as to be kept on its side, the application should duplicate the fd (e.g., using dup() )
1311  * before calling the API.
1312  *
1313  */
1314 //--------------------------------------------------------------------------------------------------
1316 (
1317  le_audio_StreamRef_t streamRef,
1318  ///< [IN] Audio stream reference.
1319  int fd
1320  ///< [IN] File descriptor.
1321 );
1322 
1323 //--------------------------------------------------------------------------------------------------
1324 /**
1325  * Get samples from a recorder stream.
1326  *
1327  * @return LE_FAULT Function failed.
1328  * @return LE_BUSY Recorder interface is already active.
1329  * @return LE_OK Function succeeded.
1330  *
1331  * @note The fd is closed by the API. To use again the same pipe, the fd parameter can be set to
1332  * LE_AUDIO_NO_FD: in this case, the previous file descriptor is re-used.
1333  * If the fd as to be kept on its side, the application should duplicate the fd (e.g., using dup() )
1334  * before calling the API.
1335  *
1336  * @note When using this function recording must be stopped by calling le_audio_Stop().
1337  */
1338 //--------------------------------------------------------------------------------------------------
1340 (
1341  le_audio_StreamRef_t streamRef,
1342  ///< [IN] Audio stream reference.
1343  int fd
1344  ///< [IN] File descriptor.
1345 );
1346 
1347 //--------------------------------------------------------------------------------------------------
1348 /**
1349  * Stop the file playback/recording.
1350  *
1351  * @return LE_FAULT Function failed.
1352  * @return LE_OK Function succeeded.
1353  *
1354  * @note The used file descriptor is not deallocated, but is is rewound to the beginning.
1355  *
1356  */
1357 //--------------------------------------------------------------------------------------------------
1359 (
1360  le_audio_StreamRef_t streamRef
1361  ///< [IN] Audio stream reference.
1362 );
1363 
1364 //--------------------------------------------------------------------------------------------------
1365 /**
1366  * Pause the file playback/recording.
1367  *
1368  * @return LE_FAULT Function failed.
1369  * @return LE_OK Function succeeded.
1370  *
1371  */
1372 //--------------------------------------------------------------------------------------------------
1374 (
1375  le_audio_StreamRef_t streamRef
1376  ///< [IN] Audio stream reference.
1377 );
1378 
1379 //--------------------------------------------------------------------------------------------------
1380 /**
1381  * Flush the remaining audio samples.
1382  *
1383  * @return LE_FAULT Function failed.
1384  * @return LE_OK Function succeeded.
1385  *
1386  */
1387 //--------------------------------------------------------------------------------------------------
1389 (
1390  le_audio_StreamRef_t streamRef
1391  ///< [IN] Audio stream reference.
1392 );
1393 
1394 //--------------------------------------------------------------------------------------------------
1395 /**
1396  * Resume a file playback/recording (need to be in pause state).
1397  *
1398  * @return LE_FAULT Function failed.
1399  * @return LE_OK Function succeeded.
1400  *
1401  */
1402 //--------------------------------------------------------------------------------------------------
1404 (
1405  le_audio_StreamRef_t streamRef
1406  ///< [IN] Audio stream reference.
1407 );
1408 
1409 //--------------------------------------------------------------------------------------------------
1410 /**
1411  * Set the channel number of a PCM sample.
1412  *
1413  * @return LE_FAULT Function failed.
1414  * @return LE_OK Function succeeded.
1415  *
1416  */
1417 //--------------------------------------------------------------------------------------------------
1419 (
1420  le_audio_StreamRef_t streamRef,
1421  ///< [IN] Audio stream reference.
1422  uint32_t nbChannel
1423  ///< [IN] Channel Number
1424 );
1425 
1426 //--------------------------------------------------------------------------------------------------
1427 /**
1428  * Get the channel number of a PCM sample.
1429  *
1430  * @return LE_FAULT Function failed.
1431  * @return LE_OK Function succeeded.
1432  *
1433  */
1434 //--------------------------------------------------------------------------------------------------
1436 (
1437  le_audio_StreamRef_t streamRef,
1438  ///< [IN] Audio stream reference.
1439  uint32_t* nbChannelPtr
1440  ///< [OUT] Channel Number
1441 );
1442 
1443 //--------------------------------------------------------------------------------------------------
1444 /**
1445  * Set the PCM sampling rate of a PCM sample.
1446  *
1447  * @return LE_FAULT Function failed.
1448  * @return LE_OK Function succeeded.
1449  *
1450  */
1451 //--------------------------------------------------------------------------------------------------
1453 (
1454  le_audio_StreamRef_t streamRef,
1455  ///< [IN] Audio stream reference.
1456  uint32_t rate
1457  ///< [IN] PCM sampling Rate.
1458 );
1459 
1460 //--------------------------------------------------------------------------------------------------
1461 /**
1462  * Get the PCM sampling rate of a PCM sample.
1463  *
1464  * @return LE_FAULT Function failed.
1465  * @return LE_OK Function succeeded.
1466  *
1467  */
1468 //--------------------------------------------------------------------------------------------------
1470 (
1471  le_audio_StreamRef_t streamRef,
1472  ///< [IN] Audio stream reference.
1473  uint32_t* ratePtr
1474  ///< [OUT] PCM sampling Rate.
1475 );
1476 
1477 //--------------------------------------------------------------------------------------------------
1478 /**
1479  * Set the sampling resolution (in bits per sample) of a PCM sample.
1480  *
1481  * @return LE_FAULT Function failed.
1482  * @return LE_OK Function succeeded.
1483  *
1484  */
1485 //--------------------------------------------------------------------------------------------------
1487 (
1488  le_audio_StreamRef_t streamRef,
1489  ///< [IN] Audio stream reference.
1490  uint32_t samplingRes
1491  ///< [IN] Sampling resolution (in bits per sample).
1492 );
1493 
1494 //--------------------------------------------------------------------------------------------------
1495 /**
1496  * Get the sampling resolution (in bits per sample) of a PCM sample.
1497  *
1498  * @return LE_FAULT Function failed.
1499  * @return LE_OK Function succeeded.
1500  *
1501  */
1502 //--------------------------------------------------------------------------------------------------
1504 (
1505  le_audio_StreamRef_t streamRef,
1506  ///< [IN] Audio stream reference.
1507  uint32_t* samplingResPtr
1508  ///< [OUT] Sampling resolution (in bits per sample).
1509 );
1510 
1511 //--------------------------------------------------------------------------------------------------
1512 /**
1513  * This function must be called to play a DTMF on a specific audio stream.
1514  *
1515  * @return LE_FORMAT_ERROR The DTMF characters are invalid.
1516  * @return LE_BUSY A DTMF playback is already in progress on the playback stream.
1517  * @return LE_FAULT Function failed to play the DTMFs.
1518  * @return LE_OK Function succeeded.
1519  *
1520  * @note If the DTMF string is too long (max DTMF_MAX_LEN characters), it is a fatal
1521  * error, the function will not return.
1522  * @note If the DTMF duration or pause is more than 5000ms, it is a fatal
1523  * error, the function will not return.
1524  * @note The process exits, if an invalid audio stream reference is given.
1525  */
1526 //--------------------------------------------------------------------------------------------------
1528 (
1529  le_audio_StreamRef_t streamRef,
1530  ///< [IN] Audio stream reference.
1531  const char* LE_NONNULL dtmf,
1532  ///< [IN] DTMFs to play.
1533  uint32_t duration,
1534  ///< [IN] DTMF duration in milliseconds.
1535  uint32_t pause
1536  ///< [IN] Pause duration between tones in milliseconds.
1537 );
1538 
1539 //--------------------------------------------------------------------------------------------------
1540 /**
1541  * This function must be called to ask to the Mobile Network to generate on the remote audio party
1542  * the DTMFs.
1543  *
1544  * @return LE_FORMAT_ERROR The DTMF characters are invalid.
1545  * @return LE_BUSY A DTMF playback is in progress.
1546  * @return LE_FAULT Function failed.
1547  * @return LE_OK Function succeeded.
1548  *
1549  * @note If the DTMF string is too long (max DTMF_MAX_LEN characters), it is a fatal
1550  * error, the function will not return.
1551  */
1552 //--------------------------------------------------------------------------------------------------
1554 (
1555  const char* LE_NONNULL dtmf,
1556  ///< [IN] DTMFs to play.
1557  uint32_t duration,
1558  ///< [IN] DTMF duration in milliseconds.
1559  uint32_t pause
1560  ///< [IN] Pause duration between tones in milliseconds.
1561 );
1562 
1563 //--------------------------------------------------------------------------------------------------
1564 /**
1565  * Set the encoding format of a recorder stream.
1566  *
1567  * @return LE_FAULT Function failed.
1568  * @return LE_OK Function succeeded.
1569  *
1570  */
1571 //--------------------------------------------------------------------------------------------------
1573 (
1574  le_audio_StreamRef_t streamRef,
1575  ///< [IN] Audio stream reference.
1576  le_audio_Format_t format
1577  ///< [IN] Encoding format.
1578 );
1579 
1580 //--------------------------------------------------------------------------------------------------
1581 /**
1582  * Get the encoding format of a recorder stream.
1583  *
1584  * @return LE_FAULT Function failed.
1585  * @return LE_OK Function succeeded.
1586  *
1587  * @note A client calling this function with either an invalid
1588  * streamRef or null out pointer parameter will be killed and the
1589  * function will not return.
1590  */
1591 //--------------------------------------------------------------------------------------------------
1593 (
1594  le_audio_StreamRef_t streamRef,
1595  ///< [IN] Audio stream reference.
1596  le_audio_Format_t* formatPtr
1597  ///< [OUT] Encoding format.
1598 );
1599 
1600 //--------------------------------------------------------------------------------------------------
1601 /**
1602  * Set the AMR mode for AMR encoder.
1603  *
1604  * @return LE_FAULT Function failed.
1605  * @return LE_OK Function succeeded.
1606  *
1607  */
1608 //--------------------------------------------------------------------------------------------------
1610 (
1611  le_audio_StreamRef_t streamRef,
1612  ///< [IN] Audio stream reference.
1613  le_audio_AmrMode_t mode
1614  ///< [IN] AMR mode.
1615 );
1616 
1617 //--------------------------------------------------------------------------------------------------
1618 /**
1619  * Get the AMR mode for AMR encoder.
1620  *
1621  * @return LE_FAULT Function failed.
1622  * @return LE_OK Function succeeded.
1623  *
1624  * @note A client calling this function with a null out pointer
1625  * parameter will be killed and the function will not return.
1626  */
1627 //--------------------------------------------------------------------------------------------------
1629 (
1630  le_audio_StreamRef_t streamRef,
1631  ///< [IN] Audio stream reference.
1632  le_audio_AmrMode_t* modePtr
1633  ///< [OUT] AMR mode.
1634 );
1635 
1636 //--------------------------------------------------------------------------------------------------
1637 /**
1638  * Set the AMR discontinuous transmission (DTX). The DTX is activated by default.
1639  *
1640  * @return LE_FAULT Function failed.
1641  * @return LE_OK Function succeeded.
1642  *
1643  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
1644  * function will not return.
1645  */
1646 //--------------------------------------------------------------------------------------------------
1648 (
1649  le_audio_StreamRef_t streamRef,
1650  ///< [IN] Audio stream reference.
1651  bool dtx
1652  ///< [IN] DTX.
1653 );
1654 
1655 //--------------------------------------------------------------------------------------------------
1656 /**
1657  * Get the AMR discontinuous transmission (DTX) value.
1658  *
1659  * @return LE_FAULT Function failed.
1660  * @return LE_OK Function succeeded.
1661  *
1662  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
1663  * function will not return.
1664  */
1665 //--------------------------------------------------------------------------------------------------
1667 (
1668  le_audio_StreamRef_t streamRef,
1669  ///< [IN] Audio stream reference.
1670  bool* dtxPtr
1671  ///< [OUT] DTX.
1672 );
1673 
1674 //--------------------------------------------------------------------------------------------------
1675 /**
1676  * Set the value of a platform specific gain in the audio subsystem.
1677  *
1678  * @return LE_BAD_PARAMETER The pointer to the name of the platform specific gain is invalid.
1679  * @return LE_NOT_FOUND The specified gain's name is not recognized in your audio subsystem.
1680  * @return LE_OUT_OF_RANGE The gain parameter is out of range.
1681  * @return LE_UNAVAILABLE The audio service initialization failed.
1682  * @return LE_FAULT On any other failure.
1683  * @return LE_OK The function succeeded.
1684  *
1685  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
1686  * function will not return.
1687  * @warning Ensure to check the names of supported gains for your specific platform.
1688  */
1689 //--------------------------------------------------------------------------------------------------
1691 (
1692  const char* LE_NONNULL gainName,
1693  ///< [IN] Name of the platform specific gain.
1694  int32_t gain
1695  ///< [IN] The gain value (specific to the platform)
1696 );
1697 
1698 //--------------------------------------------------------------------------------------------------
1699 /**
1700  * Get the value of a platform specific gain in the audio subsystem.
1701  *
1702  * @return LE_BAD_PARAMETER The pointer to the name of the platform specific gain is invalid.
1703  * @return LE_NOT_FOUND The specified gain's name is not recognized in your audio subsystem.
1704  * @return LE_UNAVAILABLE The audio service initialization failed.
1705  * @return LE_FAULT On any other failure.
1706  * @return LE_OK The function succeeded.
1707  *
1708  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
1709  * function will not return.
1710  * @warning Ensure to check the names of supported gains for your specific platform.
1711  */
1712 //--------------------------------------------------------------------------------------------------
1714 (
1715  const char* LE_NONNULL gainName,
1716  ///< [IN] Name of the platform specific gain.
1717  int32_t* gainPtr
1718  ///< [OUT] The gain value (specific to the platform)
1719 );
1720 
1721 //--------------------------------------------------------------------------------------------------
1722 /**
1723  * Mute the Call Waiting Tone.
1724  *
1725  * @return LE_UNAVAILABLE On audio service initialization failure.
1726  * @return LE_FAULT On any other failure.
1727  * @return LE_OK The function succeeded.
1728  */
1729 //--------------------------------------------------------------------------------------------------
1731 (
1732  void
1733 );
1734 
1735 //--------------------------------------------------------------------------------------------------
1736 /**
1737  * Unmute the Call Waiting Tone.
1738  *
1739  * @return LE_UNAVAILABLE On audio service initialization failure.
1740  * @return LE_FAULT On any other failure.
1741  * @return LE_OK The function succeeded.
1742  */
1743 //--------------------------------------------------------------------------------------------------
1745 (
1746  void
1747 );
1748 
1749 /** @} **/
1750 
1751 #endif // LE_AUDIO_INTERFACE_H_INCLUDE_GUARD
le_result_t le_audio_GetProfile(uint32_t *profilePtr)
le_result_t le_audio_RecordFile(le_audio_StreamRef_t streamRef, int fd)
le_result_t le_audio_GetSampleAmrMode(le_audio_StreamRef_t streamRef, le_audio_AmrMode_t *modePtr)
le_audio_StreamRef_t le_audio_OpenMic(void)
le_audio_StreamRef_t le_audio_OpenPcmRx(uint32_t timeslot)
struct le_audio_DtmfDetectorHandler * le_audio_DtmfDetectorHandlerRef_t
Definition: le_audio_common.h:215
le_result_t le_audio_SetPcmSamplingRate(uint32_t rate)
le_result_t le_audio_PlaySignallingDtmf(const char *LE_NONNULL dtmf, uint32_t duration, uint32_t pause)
le_result_t le_audio_GetSamplePcmSamplingResolution(le_audio_StreamRef_t streamRef, uint32_t *samplingResPtr)
le_result_t
Definition: le_basics.h:46
le_audio_ConnectorRef_t le_audio_CreateConnector(void)
le_result_t le_audio_SetPlatformSpecificGain(const char *LE_NONNULL gainName, int32_t gain)
void le_audio_ConnectService(void)
le_result_t le_audio_GetSamplePcmChannelNumber(le_audio_StreamRef_t streamRef, uint32_t *nbChannelPtr)
LE_FULL_API void le_audio_SetServerDisconnectHandler(le_audio_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_audio_StreamRef_t le_audio_OpenRecorder(void)
le_audio_I2SChannel_t
Definition: le_audio_common.h:106
le_audio_AmrMode_t
Definition: le_audio_common.h:144
le_result_t le_audio_Stop(le_audio_StreamRef_t streamRef)
le_result_t le_audio_GetSampleAmrDtx(le_audio_StreamRef_t streamRef, bool *dtxPtr)
le_result_t le_audio_MuteCallWaitingTone(void)
void le_audio_Close(le_audio_StreamRef_t streamRef)
le_result_t le_audio_SetEncodingFormat(le_audio_StreamRef_t streamRef, le_audio_Format_t format)
le_result_t le_audio_EnableIirFilter(le_audio_StreamRef_t streamRef)
le_result_t le_audio_EnableFirFilter(le_audio_StreamRef_t streamRef)
le_result_t le_audio_GetEncodingFormat(le_audio_StreamRef_t streamRef, le_audio_Format_t *formatPtr)
le_result_t le_audio_Unmute(le_audio_StreamRef_t streamRef)
le_result_t le_audio_PlaySamples(le_audio_StreamRef_t streamRef, int fd)
le_result_t le_audio_UnmuteCallWaitingTone(void)
le_result_t le_audio_DisableEchoCanceller(le_audio_StreamRef_t streamRef)
void le_audio_DisconnectService(void)
void(* le_audio_DtmfDetectorHandlerFunc_t)(le_audio_StreamRef_t streamRef, char dtmf, void *contextPtr)
Definition: le_audio_common.h:241
le_result_t le_audio_GetGain(le_audio_StreamRef_t streamRef, int32_t *gainPtr)
le_audio_Companding_t le_audio_GetPcmCompanding(void)
le_result_t le_audio_EnableNoiseSuppressor(le_audio_StreamRef_t streamRef)
void le_audio_Disconnect(le_audio_ConnectorRef_t connectorRef, le_audio_StreamRef_t streamRef)
le_result_t le_audio_SetSamplePcmChannelNumber(le_audio_StreamRef_t streamRef, uint32_t nbChannel)
le_result_t le_audio_SetGain(le_audio_StreamRef_t streamRef, int32_t gain)
le_result_t le_audio_GetSamples(le_audio_StreamRef_t streamRef, int fd)
le_audio_StreamRef_t le_audio_OpenUsbRx(void)
le_result_t le_audio_Connect(le_audio_ConnectorRef_t connectorRef, le_audio_StreamRef_t streamRef)
le_result_t le_audio_SetSamplePcmSamplingRate(le_audio_StreamRef_t streamRef, uint32_t rate)
le_audio_StreamRef_t le_audio_OpenModemVoiceRx(void)
le_audio_Companding_t
Definition: le_audio_common.h:89
le_result_t le_audio_DisableNoiseSuppressor(le_audio_StreamRef_t streamRef)
le_result_t le_audio_Flush(le_audio_StreamRef_t streamRef)
le_audio_MediaHandlerRef_t le_audio_AddMediaHandler(le_audio_StreamRef_t streamRef, le_audio_MediaHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_audio_Mute(le_audio_StreamRef_t streamRef)
le_audio_StreamRef_t le_audio_OpenModemVoiceTx(void)
uint32_t le_audio_GetDefaultPcmTimeSlot(void)
le_result_t le_audio_Resume(le_audio_StreamRef_t streamRef)
le_result_t le_audio_TryConnectService(void)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_audio_Pause(le_audio_StreamRef_t streamRef)
le_audio_StreamRef_t le_audio_OpenI2sTx(le_audio_I2SChannel_t mode)
le_audio_StreamRef_t le_audio_OpenPcmTx(uint32_t timeslot)
le_result_t le_audio_SetSamplePcmSamplingResolution(le_audio_StreamRef_t streamRef, uint32_t samplingRes)
struct le_audio_MediaHandler * le_audio_MediaHandlerRef_t
Definition: le_audio_common.h:207
struct le_audio_Connector * le_audio_ConnectorRef_t
Definition: le_audio_common.h:199
le_audio_DtmfDetectorHandlerRef_t le_audio_AddDtmfDetectorHandler(le_audio_StreamRef_t streamRef, le_audio_DtmfDetectorHandlerFunc_t handlerPtr, void *contextPtr)
struct le_audio_Stream * le_audio_StreamRef_t
Definition: le_audio_common.h:191
le_result_t le_audio_SetProfile(uint32_t profile)
le_result_t le_audio_SetPcmCompanding(le_audio_Companding_t companding)
void(* le_audio_MediaHandlerFunc_t)(le_audio_StreamRef_t streamRef, le_audio_MediaEvent_t event, void *contextPtr)
Definition: le_audio_common.h:225
le_audio_StreamRef_t le_audio_OpenSpeaker(void)
le_result_t le_audio_SetSampleAmrMode(le_audio_StreamRef_t streamRef, le_audio_AmrMode_t mode)
le_result_t le_audio_GetSamplePcmSamplingRate(le_audio_StreamRef_t streamRef, uint32_t *ratePtr)
le_audio_StreamRef_t le_audio_OpenI2sRx(le_audio_I2SChannel_t mode)
uint32_t le_audio_GetPcmSamplingRate(void)
le_audio_StreamRef_t le_audio_OpenPlayer(void)
le_audio_StreamRef_t le_audio_OpenUsbTx(void)
uint32_t le_audio_GetPcmSamplingResolution(void)
le_result_t le_audio_DisableAutomaticGainControl(le_audio_StreamRef_t streamRef)
le_result_t le_audio_IsEchoCancellerEnabled(le_audio_StreamRef_t streamRef, bool *statusPtr)
void le_audio_RemoveDtmfDetectorHandler(le_audio_DtmfDetectorHandlerRef_t handlerRef)
le_audio_I2SChannel_t le_audio_GetDefaultI2sMode(void)
le_result_t le_audio_GetPlatformSpecificGain(const char *LE_NONNULL gainName, int32_t *gainPtr)
le_result_t le_audio_EnableEchoCanceller(le_audio_StreamRef_t streamRef)
le_result_t le_audio_IsNoiseSuppressorEnabled(le_audio_StreamRef_t streamRef, bool *statusPtr)
void le_audio_DeleteConnector(le_audio_ConnectorRef_t connectorRef)
le_result_t le_audio_DisableFirFilter(le_audio_StreamRef_t streamRef)
le_result_t le_audio_DisableIirFilter(le_audio_StreamRef_t streamRef)
le_audio_Format_t
Definition: le_audio_common.h:127
void(* le_audio_DisconnectHandler_t)(void *)
Definition: le_audio_interface.h:359
le_result_t le_audio_EnableAutomaticGainControl(le_audio_StreamRef_t streamRef)
le_result_t le_audio_PlayDtmf(le_audio_StreamRef_t streamRef, const char *LE_NONNULL dtmf, uint32_t duration, uint32_t pause)
void le_audio_RemoveMediaHandler(le_audio_MediaHandlerRef_t handlerRef)
le_result_t le_audio_SetSampleAmrDtx(le_audio_StreamRef_t streamRef, bool dtx)
le_result_t le_audio_PlayFile(le_audio_StreamRef_t streamRef, int fd)
le_result_t le_audio_SetPcmSamplingResolution(uint32_t bitsPerSample)