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