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 //--------------------------------------------------------------------------------------------------
351 /**
352  * Type for handler called when a server disconnects.
353  */
354 //--------------------------------------------------------------------------------------------------
355 typedef void (*le_audio_DisconnectHandler_t)(void *);
356 
357 //--------------------------------------------------------------------------------------------------
358 /**
359  *
360  * Connect the current client thread to the service providing this API. Block until the service is
361  * available.
362  *
363  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
364  * called before any other functions in this API. Normally, ConnectService is automatically called
365  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
366  *
367  * This function is created automatically.
368  */
369 //--------------------------------------------------------------------------------------------------
371 (
372  void
373 );
374 
375 //--------------------------------------------------------------------------------------------------
376 /**
377  *
378  * Try to connect the current client thread to the service providing this API. Return with an error
379  * if the service is not available.
380  *
381  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
382  * called before any other functions in this API. Normally, ConnectService is automatically called
383  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
384  *
385  * This function is created automatically.
386  *
387  * @return
388  * - LE_OK if the client connected successfully to the service.
389  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
390  * bound.
391  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
392  * - LE_COMM_ERROR if the Service Directory cannot be reached.
393  */
394 //--------------------------------------------------------------------------------------------------
396 (
397  void
398 );
399 
400 //--------------------------------------------------------------------------------------------------
401 /**
402  * Set handler called when server disconnection is detected.
403  *
404  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
405  * to continue without exiting, it should call longjmp() from inside the handler.
406  */
407 //--------------------------------------------------------------------------------------------------
409 (
410  le_audio_DisconnectHandler_t disconnectHandler,
411  void *contextPtr
412 );
413 
414 //--------------------------------------------------------------------------------------------------
415 /**
416  *
417  * Disconnect the current client thread from the service providing this API.
418  *
419  * Normally, this function doesn't need to be called. After this function is called, there's no
420  * longer a connection to the service, and the functions in this API can't be used. For details, see
421  * @ref apiFilesC_client.
422  *
423  * This function is created automatically.
424  */
425 //--------------------------------------------------------------------------------------------------
427 (
428  void
429 );
430 
431 
432 //--------------------------------------------------------------------------------------------------
433 /**
434  * Audio recording/playback events.
435  */
436 //--------------------------------------------------------------------------------------------------
437 
438 
439 //--------------------------------------------------------------------------------------------------
440 /**
441  * Companding.
442  */
443 //--------------------------------------------------------------------------------------------------
444 
445 
446 //--------------------------------------------------------------------------------------------------
447 /**
448  * I2S channel mode.
449  */
450 //--------------------------------------------------------------------------------------------------
451 
452 
453 //--------------------------------------------------------------------------------------------------
454 /**
455  * Audio format.
456  */
457 //--------------------------------------------------------------------------------------------------
458 
459 
460 //--------------------------------------------------------------------------------------------------
461 /**
462  * AMR mode.
463  */
464 //--------------------------------------------------------------------------------------------------
465 
466 
467 //--------------------------------------------------------------------------------------------------
468 /**
469  * Reference type for Audio Stream
470  */
471 //--------------------------------------------------------------------------------------------------
472 
473 
474 //--------------------------------------------------------------------------------------------------
475 /**
476  * Reference type for Audio Connector
477  */
478 //--------------------------------------------------------------------------------------------------
479 
480 
481 //--------------------------------------------------------------------------------------------------
482 /**
483  * Handler for audio stream event.
484  *
485  */
486 //--------------------------------------------------------------------------------------------------
487 
488 
489 //--------------------------------------------------------------------------------------------------
490 /**
491  * Reference type used by Add/Remove functions for EVENT 'le_audio_Media'
492  */
493 //--------------------------------------------------------------------------------------------------
494 
495 
496 //--------------------------------------------------------------------------------------------------
497 /**
498  * Handler for DTMF decoding.
499  *
500  */
501 //--------------------------------------------------------------------------------------------------
502 
503 
504 //--------------------------------------------------------------------------------------------------
505 /**
506  * Reference type used by Add/Remove functions for EVENT 'le_audio_DtmfDetector'
507  */
508 //--------------------------------------------------------------------------------------------------
509 
510 
511 //--------------------------------------------------------------------------------------------------
512 /**
513  * Open the Microphone.
514  *
515  * @return Reference to the input audio stream, NULL if the function fails.
516  */
517 //--------------------------------------------------------------------------------------------------
518 le_audio_StreamRef_t le_audio_OpenMic
519 (
520  void
521 );
522 
523 //--------------------------------------------------------------------------------------------------
524 /**
525  * Open the Speaker-phone.
526  *
527  * @return Reference to the output audio stream, NULL if the function fails.
528  */
529 //--------------------------------------------------------------------------------------------------
530 le_audio_StreamRef_t le_audio_OpenSpeaker
531 (
532  void
533 );
534 
535 //--------------------------------------------------------------------------------------------------
536 /**
537  * Open the received audio stream of an USB audio class.
538  *
539  * @return Reference to the input audio stream, NULL if the function fails.
540  */
541 //--------------------------------------------------------------------------------------------------
542 le_audio_StreamRef_t le_audio_OpenUsbRx
543 (
544  void
545 );
546 
547 //--------------------------------------------------------------------------------------------------
548 /**
549  * Open the transmitted audio stream of an USB audio class.
550  *
551  * @return Reference to the output audio stream, NULL if the function fails.
552  */
553 //--------------------------------------------------------------------------------------------------
554 le_audio_StreamRef_t le_audio_OpenUsbTx
555 (
556  void
557 );
558 
559 //--------------------------------------------------------------------------------------------------
560 /**
561  * Open the received audio stream of the PCM interface.
562  *
563  * @return Reference to the input audio stream, NULL if the function fails.
564  */
565 //--------------------------------------------------------------------------------------------------
566 le_audio_StreamRef_t le_audio_OpenPcmRx
567 (
568  uint32_t timeslot
569  ///< [IN] The time slot number.
570 );
571 
572 //--------------------------------------------------------------------------------------------------
573 /**
574  * Open the transmitted audio stream of the PCM interface.
575  *
576  * @return Reference to the output audio stream, NULL if the function fails.
577  */
578 //--------------------------------------------------------------------------------------------------
579 le_audio_StreamRef_t le_audio_OpenPcmTx
580 (
581  uint32_t timeslot
582  ///< [IN] The time slot number.
583 );
584 
585 //--------------------------------------------------------------------------------------------------
586 /**
587  * Open the received audio stream of the I2S interface.
588  *
589  * @return Reference to the input audio stream, NULL if the function fails.
590  */
591 //--------------------------------------------------------------------------------------------------
592 le_audio_StreamRef_t le_audio_OpenI2sRx
593 (
594  le_audio_I2SChannel_t mode
595  ///< [IN] The channel mode.
596 );
597 
598 //--------------------------------------------------------------------------------------------------
599 /**
600  * Open the transmitted audio stream of the I2S interface.
601  *
602  * @return Reference to the output audio stream, NULL if the function fails.
603  */
604 //--------------------------------------------------------------------------------------------------
605 le_audio_StreamRef_t le_audio_OpenI2sTx
606 (
607  le_audio_I2SChannel_t mode
608  ///< [IN] The channel mode.
609 );
610 
611 //--------------------------------------------------------------------------------------------------
612 /**
613  * Open the audio stream for playback.
614  *
615  * @return Reference to the audio stream, NULL if the function fails.
616  */
617 //--------------------------------------------------------------------------------------------------
618 le_audio_StreamRef_t le_audio_OpenPlayer
619 (
620  void
621 );
622 
623 //--------------------------------------------------------------------------------------------------
624 /**
625  * Open the audio stream for recording.
626  *
627  * @return Reference to the audio stream, NULL if the function fails.
628  */
629 //--------------------------------------------------------------------------------------------------
630 le_audio_StreamRef_t le_audio_OpenRecorder
631 (
632  void
633 );
634 
635 //--------------------------------------------------------------------------------------------------
636 /**
637  * Open the received audio stream of a voice call.
638  *
639  * @return Reference to the input audio stream, NULL if the function fails.
640  */
641 //--------------------------------------------------------------------------------------------------
642 le_audio_StreamRef_t le_audio_OpenModemVoiceRx
643 (
644  void
645 );
646 
647 //--------------------------------------------------------------------------------------------------
648 /**
649  * Open the transmitted audio stream of a voice call.
650  *
651  * @return Reference to the output audio stream, NULL if the function fails.
652  */
653 //--------------------------------------------------------------------------------------------------
654 le_audio_StreamRef_t le_audio_OpenModemVoiceTx
655 (
656  void
657 );
658 
659 //--------------------------------------------------------------------------------------------------
660 /**
661  * Add handler function for EVENT 'le_audio_Media'
662  *
663  * This event provides information on player / recorder stream events.
664  *
665  */
666 //--------------------------------------------------------------------------------------------------
667 le_audio_MediaHandlerRef_t le_audio_AddMediaHandler
668 (
669  le_audio_StreamRef_t streamRef,
670  ///< [IN] The audio stream reference.
671  le_audio_MediaHandlerFunc_t handlerPtr,
672  ///< [IN]
673  void* contextPtr
674  ///< [IN]
675 );
676 
677 //--------------------------------------------------------------------------------------------------
678 /**
679  * Remove handler function for EVENT 'le_audio_Media'
680  */
681 //--------------------------------------------------------------------------------------------------
683 (
684  le_audio_MediaHandlerRef_t handlerRef
685  ///< [IN]
686 );
687 
688 //--------------------------------------------------------------------------------------------------
689 /**
690  * Close an audio stream.
691  * If several users own the stream reference, the interface closes only after
692  * the last user closes the audio stream.
693  *
694  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
695  * function will not return.
696  */
697 //--------------------------------------------------------------------------------------------------
698 void le_audio_Close
699 (
700  le_audio_StreamRef_t streamRef
701  ///< [IN] Audio stream reference.
702 );
703 
704 //--------------------------------------------------------------------------------------------------
705 /**
706  * Set the Gain value of an input or output stream.
707  *
708  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
709  * @return LE_OUT_OF_RANGE The gain value is out of range.
710  * @return LE_UNAVAILABLE The audio service initialization failed.
711  * @return LE_FAULT On any other failure.
712  * @return LE_OK The function succeeded.
713  *
714  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
715  * function will not return.
716  */
717 //--------------------------------------------------------------------------------------------------
719 (
720  le_audio_StreamRef_t streamRef,
721  ///< [IN] Audio stream reference.
722  int32_t gain
723  ///< [IN] Gain value (specific to the platform)
724 );
725 
726 //--------------------------------------------------------------------------------------------------
727 /**
728  * Get the Gain value of an input or output stream.
729  *
730  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
731  * @return LE_UNAVAILABLE The audio service initialization failed.
732  * @return LE_FAULT On any other failure.
733  * @return LE_OK The function succeeded.
734  *
735  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
736  * function will not return.
737  */
738 //--------------------------------------------------------------------------------------------------
740 (
741  le_audio_StreamRef_t streamRef,
742  ///< [IN] Audio stream reference.
743  int32_t* gainPtr
744  ///< [OUT] Gain value (specific to the platform)
745 );
746 
747 //--------------------------------------------------------------------------------------------------
748 /**
749  * Mute an audio stream.
750  *
751  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
752  * @return LE_UNAVAILABLE The audio service initialization failed.
753  * @return LE_FAULT On any other failure.
754  * @return LE_OK The function succeeded.
755  *
756  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
757  * function will not return.
758  */
759 //--------------------------------------------------------------------------------------------------
761 (
762  le_audio_StreamRef_t streamRef
763  ///< [IN] Audio stream reference.
764 );
765 
766 //--------------------------------------------------------------------------------------------------
767 /**
768  * Unmute an audio stream.
769  *
770  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
771  * @return LE_UNAVAILABLE The audio service initialization failed.
772  * @return LE_FAULT On any other failure.
773  * @return LE_OK The function succeeded.
774  *
775  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
776  * function will not return.
777  */
778 //--------------------------------------------------------------------------------------------------
780 (
781  le_audio_StreamRef_t streamRef
782  ///< [IN] Audio stream reference.
783 );
784 
785 //--------------------------------------------------------------------------------------------------
786 /**
787  * Create an audio connector reference.
788  *
789  * @return Reference to the audio connector, NULL if the function fails.
790  */
791 //--------------------------------------------------------------------------------------------------
792 le_audio_ConnectorRef_t le_audio_CreateConnector
793 (
794  void
795 );
796 
797 //--------------------------------------------------------------------------------------------------
798 /**
799  * Delete an audio connector reference.
800  *
801  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
802  * function will not return.
803  */
804 //--------------------------------------------------------------------------------------------------
806 (
807  le_audio_ConnectorRef_t connectorRef
808  ///< [IN] Connector reference.
809 );
810 
811 //--------------------------------------------------------------------------------------------------
812 /**
813  * Connect an audio stream to the connector reference.
814  *
815  * @return LE_BUSY There are insufficient DSP resources available.
816  * @return LE_UNAVAILABLE The audio service initialization failed.
817  * @return LE_BAD_PARAMETER The connector and/or the audio stream references are invalid.
818  * @return LE_FAULT On any other failure.
819  * @return LE_OK The function succeeded.
820  *
821  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
822  * function will not return.
823  */
824 //--------------------------------------------------------------------------------------------------
826 (
827  le_audio_ConnectorRef_t connectorRef,
828  ///< [IN] Connector reference.
829  le_audio_StreamRef_t streamRef
830  ///< [IN] Audio stream reference.
831 );
832 
833 //--------------------------------------------------------------------------------------------------
834 /**
835  * Disconnect an audio stream from the connector reference.
836  *
837  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
838  * function will not return.
839  */
840 //--------------------------------------------------------------------------------------------------
842 (
843  le_audio_ConnectorRef_t connectorRef,
844  ///< [IN] Connector reference.
845  le_audio_StreamRef_t streamRef
846  ///< [IN] Audio stream reference.
847 );
848 
849 //--------------------------------------------------------------------------------------------------
850 /**
851  * Add handler function for EVENT 'le_audio_DtmfDetector'
852  *
853  * This event provides information on DTMF decoding for the specified streamRef
854  *
855  */
856 //--------------------------------------------------------------------------------------------------
857 le_audio_DtmfDetectorHandlerRef_t le_audio_AddDtmfDetectorHandler
858 (
859  le_audio_StreamRef_t streamRef,
860  ///< [IN] Audio stream reference.
861  le_audio_DtmfDetectorHandlerFunc_t handlerPtr,
862  ///< [IN]
863  void* contextPtr
864  ///< [IN]
865 );
866 
867 //--------------------------------------------------------------------------------------------------
868 /**
869  * Remove handler function for EVENT 'le_audio_DtmfDetector'
870  */
871 //--------------------------------------------------------------------------------------------------
873 (
874  le_audio_DtmfDetectorHandlerRef_t handlerRef
875  ///< [IN]
876 );
877 
878 //--------------------------------------------------------------------------------------------------
879 /**
880  * This function must be called to enable the Noise Suppressor.
881  *
882  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
883  * @return LE_UNAVAILABLE The audio service initialization failed.
884  * @return LE_FAULT On any other failure.
885  * @return LE_OK Function succeeded.
886  *
887  * @note The process exits, if an invalid audio stream reference is given.
888  */
889 //--------------------------------------------------------------------------------------------------
891 (
892  le_audio_StreamRef_t streamRef
893  ///< [IN] Audio stream reference.
894 );
895 
896 //--------------------------------------------------------------------------------------------------
897 /**
898  * This function must be called to disable the Noise Suppressor.
899  *
900  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
901  * @return LE_UNAVAILABLE The audio service initialization failed.
902  * @return LE_FAULT On any other failure.
903  * @return LE_OK Function succeeded.
904  *
905  * @note The process exits, if an invalid audio stream reference is given.
906  */
907 //--------------------------------------------------------------------------------------------------
909 (
910  le_audio_StreamRef_t streamRef
911  ///< [IN] Audio stream reference.
912 );
913 
914 //--------------------------------------------------------------------------------------------------
915 /**
916  * This function must be called to enable the Echo Canceller.
917  *
918  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
919  * @return LE_UNAVAILABLE The audio service initialization failed.
920  * @return LE_FAULT On any other failure.
921  * @return LE_OK Function succeeded.
922  *
923  * @note The process exits, if an invalid audio stream reference is given.
924  */
925 //--------------------------------------------------------------------------------------------------
927 (
928  le_audio_StreamRef_t streamRef
929  ///< [IN] Audio stream reference.
930 );
931 
932 //--------------------------------------------------------------------------------------------------
933 /**
934  * This function must be called to disable the Echo Canceller.
935  *
936  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
937  * @return LE_UNAVAILABLE The audio service initialization failed.
938  * @return LE_FAULT On any other failure.
939  * @return LE_OK Function succeeded.
940  *
941  * @note The process exits, if an invalid audio stream reference is given.
942  */
943 //--------------------------------------------------------------------------------------------------
945 (
946  le_audio_StreamRef_t streamRef
947  ///< [IN] Audio stream reference.
948 );
949 
950 //--------------------------------------------------------------------------------------------------
951 /**
952  * This function must be called to get the status of Noise Suppressor.
953  *
954  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
955  * @return LE_UNAVAILABLE The audio service initialization failed.
956  * @return LE_FAULT On any other failure.
957  * @return LE_OK Function succeeded.
958  *
959  * @note The process exits, if an invalid audio stream reference is given.
960  */
961 //--------------------------------------------------------------------------------------------------
963 (
964  le_audio_StreamRef_t streamRef,
965  ///< [IN] Audio stream reference.
966  bool* statusPtr
967  ///< [OUT] true if NS is enabled, false otherwise
968 );
969 
970 //--------------------------------------------------------------------------------------------------
971 /**
972  * This function must be called to get the status of Echo Canceller.
973  *
974  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
975  * @return LE_UNAVAILABLE The audio service initialization failed.
976  * @return LE_FAULT On any other failure.
977  * @return LE_OK Function succeeded.
978  *
979  * @note The process exits, if an invalid audio stream reference is given.
980  */
981 //--------------------------------------------------------------------------------------------------
983 (
984  le_audio_StreamRef_t streamRef,
985  ///< [IN] Audio stream reference.
986  bool* statusPtr
987  ///< [OUT] true if EC is enabled, false otherwise
988 );
989 
990 //--------------------------------------------------------------------------------------------------
991 /**
992  * This function must be called to enable the FIR (Finite Impulse Response) filter.
993  *
994  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
995  * @return LE_UNAVAILABLE The audio service initialization failed.
996  * @return LE_FAULT On any other failure.
997  * @return LE_OK Function succeeded.
998  *
999  * @note The process exits, if an invalid audio stream reference is given.
1000  */
1001 //--------------------------------------------------------------------------------------------------
1003 (
1004  le_audio_StreamRef_t streamRef
1005  ///< [IN] Audio stream reference.
1006 );
1007 
1008 //--------------------------------------------------------------------------------------------------
1009 /**
1010  * This function must be called to disable the FIR (Finite Impulse Response) filter.
1011  *
1012  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1013  * @return LE_UNAVAILABLE The audio service initialization failed.
1014  * @return LE_FAULT On any other failure.
1015  * @return LE_OK Function succeeded.
1016  *
1017  * @note The process exits, if an invalid audio stream reference is given.
1018  */
1019 //--------------------------------------------------------------------------------------------------
1021 (
1022  le_audio_StreamRef_t streamRef
1023  ///< [IN] Audio stream reference.
1024 );
1025 
1026 //--------------------------------------------------------------------------------------------------
1027 /**
1028  * This function must be called to enable the IIR (Infinite Impulse Response) filter.
1029  *
1030  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1031  * @return LE_UNAVAILABLE The audio service initialization failed.
1032  * @return LE_FAULT On any other failure.
1033  * @return LE_OK Function succeeded.
1034  *
1035  * @note The process exits, if an invalid audio stream reference is given.
1036  */
1037 //--------------------------------------------------------------------------------------------------
1039 (
1040  le_audio_StreamRef_t streamRef
1041  ///< [IN] Audio stream reference.
1042 );
1043 
1044 //--------------------------------------------------------------------------------------------------
1045 /**
1046  * This function must be called to disable the IIR (Infinite Impulse Response) filter.
1047  *
1048  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1049  * @return LE_UNAVAILABLE The audio service initialization failed.
1050  * @return LE_FAULT On any other failure.
1051  * @return LE_OK Function succeeded.
1052  *
1053  * @note The process exits, if an invalid audio stream reference is given.
1054  */
1055 //--------------------------------------------------------------------------------------------------
1057 (
1058  le_audio_StreamRef_t streamRef
1059  ///< [IN] Audio stream reference.
1060 );
1061 
1062 //--------------------------------------------------------------------------------------------------
1063 /**
1064  * This function must be called to enable the automatic gain control on the selected audio stream.
1065  *
1066  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1067  * @return LE_UNAVAILABLE The audio service initialization failed.
1068  * @return LE_FAULT On any other failure.
1069  * @return LE_OK Function succeeded.
1070  *
1071  * @note The process exits, if an invalid audio stream reference is given.
1072  */
1073 //--------------------------------------------------------------------------------------------------
1075 (
1076  le_audio_StreamRef_t streamRef
1077  ///< [IN] Audio stream reference.
1078 );
1079 
1080 //--------------------------------------------------------------------------------------------------
1081 /**
1082  * This function must be called to disable the automatic gain control on the selected audio stream.
1083  *
1084  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1085  * @return LE_UNAVAILABLE The audio service initialization failed.
1086  * @return LE_FAULT On any other failure.
1087  * @return LE_OK Function succeeded.
1088  *
1089  * @note The process exits, if an invalid audio stream reference is given.
1090  */
1091 //--------------------------------------------------------------------------------------------------
1093 (
1094  le_audio_StreamRef_t streamRef
1095  ///< [IN] Audio stream reference.
1096 );
1097 
1098 //--------------------------------------------------------------------------------------------------
1099 /**
1100  * This function must be called to set the audio profile.
1101  *
1102  * @return LE_UNAVAILABLE On audio service initialization failure.
1103  * @return LE_FAULT On any other failure.
1104  * @return LE_OK Function succeeded.
1105  *
1106  */
1107 //--------------------------------------------------------------------------------------------------
1109 (
1110  uint32_t profile
1111  ///< [IN] Audio profile.
1112 );
1113 
1114 //--------------------------------------------------------------------------------------------------
1115 /**
1116  * This function must be called to get the audio profile in use.
1117  *
1118  * @return LE_UNAVAILABLE On audio service initialization failure.
1119  * @return LE_FAULT On any other failure.
1120  * @return LE_OK Function succeeded.
1121  *
1122  */
1123 //--------------------------------------------------------------------------------------------------
1125 (
1126  uint32_t* profilePtr
1127  ///< [OUT] Audio profile.
1128 );
1129 
1130 //--------------------------------------------------------------------------------------------------
1131 /**
1132  * Configure the PCM Sampling Rate.
1133  *
1134  * @return LE_FAULT Function failed.
1135  * @return LE_OUT_OF_RANGE Your platform does not support the setting's value.
1136  * @return LE_BUSY PCM interface is already active.
1137  * @return LE_OK Function succeeded.
1138  */
1139 //--------------------------------------------------------------------------------------------------
1141 (
1142  uint32_t rate
1143  ///< [IN] Sampling rate in Hz.
1144 );
1145 
1146 //--------------------------------------------------------------------------------------------------
1147 /**
1148  * Configure the PCM Sampling Resolution.
1149  *
1150  * @return LE_FAULT Function failed.
1151  * @return LE_OUT_OF_RANGE Your platform does not support the setting's value.
1152  * @return LE_BUSY PCM interface is already active.
1153  * @return LE_OK Function succeeded.
1154  */
1155 //--------------------------------------------------------------------------------------------------
1157 (
1158  uint32_t bitsPerSample
1159  ///< [IN] Sampling resolution (bits/sample).
1160 );
1161 
1162 //--------------------------------------------------------------------------------------------------
1163 /**
1164  * Configure the PCM Companding.
1165  *
1166  * @return LE_FAULT Function failed.
1167  * @return LE_OUT_OF_RANGE Your platform does not support the setting's value.
1168  * @return LE_BUSY PCM interface is already active.
1169  * @return LE_OK Function succeeded.
1170  */
1171 //--------------------------------------------------------------------------------------------------
1173 (
1174  le_audio_Companding_t companding
1175  ///< [IN] Companding.
1176 );
1177 
1178 //--------------------------------------------------------------------------------------------------
1179 /**
1180  * Retrieve the PCM Sampling Rate.
1181  *
1182  * @return The sampling rate in Hz.
1183  */
1184 //--------------------------------------------------------------------------------------------------
1186 (
1187  void
1188 );
1189 
1190 //--------------------------------------------------------------------------------------------------
1191 /**
1192  * Retrieve the PCM Sampling Resolution.
1193  *
1194  * @return The sampling resolution (bits/sample).
1195  */
1196 //--------------------------------------------------------------------------------------------------
1198 (
1199  void
1200 );
1201 
1202 //--------------------------------------------------------------------------------------------------
1203 /**
1204  * Retrieve the PCM Companding.
1205  *
1206  * @return The PCM companding.
1207  */
1208 //--------------------------------------------------------------------------------------------------
1209 le_audio_Companding_t le_audio_GetPcmCompanding
1210 (
1211  void
1212 );
1213 
1214 //--------------------------------------------------------------------------------------------------
1215 /**
1216  * Get the default PCM time slot used on the current platform.
1217  *
1218  * @return the time slot number.
1219  */
1220 //--------------------------------------------------------------------------------------------------
1222 (
1223  void
1224 );
1225 
1226 //--------------------------------------------------------------------------------------------------
1227 /**
1228  * Get the default I2S channel mode used on the current platform.
1229  *
1230  * @return the I2S channel mode.
1231  */
1232 //--------------------------------------------------------------------------------------------------
1233 le_audio_I2SChannel_t le_audio_GetDefaultI2sMode
1234 (
1235  void
1236 );
1237 
1238 //--------------------------------------------------------------------------------------------------
1239 /**
1240  * Play a file on a playback stream.
1241  *
1242  * @return LE_FAULT Function failed.
1243  * @return LE_BAD_PARAMETER Audio stream reference is invalid.
1244  * @return LE_BUSY Player interface is already active.
1245  * @return LE_OK Function succeeded.
1246  *
1247  * @note
1248  * - The fd is closed by the IPC API. To play again the same file, the fd parameter can be set
1249  * to LE_AUDIO_NO_FD: in this case, the previous file descriptor is re-used.
1250  * If the fd as to be kept on its side, the application should duplicate the fd (e.g., using
1251  * dup() ) before calling the API.
1252  * In that case, the old and new file descriptors refer to the same open file description and
1253  * thus share file offset. So, once a playback has reached the end of file, the application must
1254  * reset the file offset by using lseek on the duplicated descriptor to start the playback from
1255  * the beginning.
1256  *
1257  * @note
1258  * - Calling le_audio_PlayFile(<..>, LE_AUDIO_NO_FD) will rewind the audio file to the
1259  * beginning when a playback is already in progress.
1260  *
1261  */
1262 //--------------------------------------------------------------------------------------------------
1264 (
1265  le_audio_StreamRef_t streamRef,
1266  ///< [IN] Audio stream reference.
1267  int fd
1268  ///< [IN] File descriptor.
1269 );
1270 
1271 //--------------------------------------------------------------------------------------------------
1272 /**
1273  * Initiate a playback sending samples over a pipe.
1274  *
1275  * @return LE_FAULT Function failed.
1276  * @return LE_BUSY Player interface is already active.
1277  * @return LE_OK Function succeeded.
1278  *
1279  * @note The fd is closed by the IPC API. To use again the same pipe, the fd parameter can be set
1280  * to LE_AUDIO_NO_FD: in this case, the previous file descriptor is re-used.
1281  * If the fd as to be kept on its side, the application should duplicate the fd (e.g., using dup() )
1282  * before calling the API.
1283  *
1284  * @note Playback initiated with this function must be stopped by calling le_audio_Stop().
1285  */
1286 //--------------------------------------------------------------------------------------------------
1288 (
1289  le_audio_StreamRef_t streamRef,
1290  ///< [IN] Audio stream reference.
1291  int fd
1292  ///< [IN] File descriptor.
1293 );
1294 
1295 //--------------------------------------------------------------------------------------------------
1296 /**
1297  * Record a file on a recorder stream.
1298  *
1299  * @return LE_FAULT Function failed.
1300  * @return LE_BAD_PARAMETER The audio stream reference is invalid.
1301  * @return LE_BUSY Recorder interface is already active.
1302  * @return LE_OK Function succeeded.
1303  *
1304  * @note the fd is closed by the API. To record again the same file, the fd parameter can be set to
1305  * LE_AUDIO_NO_FD: in this case, the previous file descriptor is re-used.
1306  * If the fd as to be kept on its side, the application should duplicate the fd (e.g., using dup() )
1307  * before calling the API.
1308  *
1309  */
1310 //--------------------------------------------------------------------------------------------------
1312 (
1313  le_audio_StreamRef_t streamRef,
1314  ///< [IN] Audio stream reference.
1315  int fd
1316  ///< [IN] File descriptor.
1317 );
1318 
1319 //--------------------------------------------------------------------------------------------------
1320 /**
1321  * Get samples from a recorder stream.
1322  *
1323  * @return LE_FAULT Function failed.
1324  * @return LE_BUSY Recorder interface is already active.
1325  * @return LE_OK Function succeeded.
1326  *
1327  * @note The fd is closed by the API. To use again the same pipe, the fd parameter can be set to
1328  * LE_AUDIO_NO_FD: in this case, the previous file descriptor is re-used.
1329  * If the fd as to be kept on its side, the application should duplicate the fd (e.g., using dup() )
1330  * before calling the API.
1331  *
1332  * @note When using this function recording must be stopped by calling le_audio_Stop().
1333  */
1334 //--------------------------------------------------------------------------------------------------
1336 (
1337  le_audio_StreamRef_t streamRef,
1338  ///< [IN] Audio stream reference.
1339  int fd
1340  ///< [IN] File descriptor.
1341 );
1342 
1343 //--------------------------------------------------------------------------------------------------
1344 /**
1345  * Stop the file playback/recording.
1346  *
1347  * @return LE_FAULT Function failed.
1348  * @return LE_OK Function succeeded.
1349  *
1350  * @note The used file descriptor is not deallocated, but is is rewound to the beginning.
1351  *
1352  */
1353 //--------------------------------------------------------------------------------------------------
1355 (
1356  le_audio_StreamRef_t streamRef
1357  ///< [IN] Audio stream reference.
1358 );
1359 
1360 //--------------------------------------------------------------------------------------------------
1361 /**
1362  * Pause the file playback/recording.
1363  *
1364  * @return LE_FAULT Function failed.
1365  * @return LE_OK Function succeeded.
1366  *
1367  */
1368 //--------------------------------------------------------------------------------------------------
1370 (
1371  le_audio_StreamRef_t streamRef
1372  ///< [IN] Audio stream reference.
1373 );
1374 
1375 //--------------------------------------------------------------------------------------------------
1376 /**
1377  * Flush the remaining audio samples.
1378  *
1379  * @return LE_FAULT Function failed.
1380  * @return LE_OK Function succeeded.
1381  *
1382  */
1383 //--------------------------------------------------------------------------------------------------
1385 (
1386  le_audio_StreamRef_t streamRef
1387  ///< [IN] Audio stream reference.
1388 );
1389 
1390 //--------------------------------------------------------------------------------------------------
1391 /**
1392  * Resume a file playback/recording (need to be in pause state).
1393  *
1394  * @return LE_FAULT Function failed.
1395  * @return LE_OK Function succeeded.
1396  *
1397  */
1398 //--------------------------------------------------------------------------------------------------
1400 (
1401  le_audio_StreamRef_t streamRef
1402  ///< [IN] Audio stream reference.
1403 );
1404 
1405 //--------------------------------------------------------------------------------------------------
1406 /**
1407  * Set the channel number of a PCM sample.
1408  *
1409  * @return LE_FAULT Function failed.
1410  * @return LE_OK Function succeeded.
1411  *
1412  */
1413 //--------------------------------------------------------------------------------------------------
1415 (
1416  le_audio_StreamRef_t streamRef,
1417  ///< [IN] Audio stream reference.
1418  uint32_t nbChannel
1419  ///< [IN] Channel Number
1420 );
1421 
1422 //--------------------------------------------------------------------------------------------------
1423 /**
1424  * Get the channel number of a PCM sample.
1425  *
1426  * @return LE_FAULT Function failed.
1427  * @return LE_OK Function succeeded.
1428  *
1429  */
1430 //--------------------------------------------------------------------------------------------------
1432 (
1433  le_audio_StreamRef_t streamRef,
1434  ///< [IN] Audio stream reference.
1435  uint32_t* nbChannelPtr
1436  ///< [OUT] Channel Number
1437 );
1438 
1439 //--------------------------------------------------------------------------------------------------
1440 /**
1441  * Set the PCM sampling rate of a PCM sample.
1442  *
1443  * @return LE_FAULT Function failed.
1444  * @return LE_OK Function succeeded.
1445  *
1446  */
1447 //--------------------------------------------------------------------------------------------------
1449 (
1450  le_audio_StreamRef_t streamRef,
1451  ///< [IN] Audio stream reference.
1452  uint32_t rate
1453  ///< [IN] PCM sampling Rate.
1454 );
1455 
1456 //--------------------------------------------------------------------------------------------------
1457 /**
1458  * Get the PCM sampling rate of a PCM sample.
1459  *
1460  * @return LE_FAULT Function failed.
1461  * @return LE_OK Function succeeded.
1462  *
1463  */
1464 //--------------------------------------------------------------------------------------------------
1466 (
1467  le_audio_StreamRef_t streamRef,
1468  ///< [IN] Audio stream reference.
1469  uint32_t* ratePtr
1470  ///< [OUT] PCM sampling Rate.
1471 );
1472 
1473 //--------------------------------------------------------------------------------------------------
1474 /**
1475  * Set the sampling resolution (in bits per sample) of a PCM sample.
1476  *
1477  * @return LE_FAULT Function failed.
1478  * @return LE_OK Function succeeded.
1479  *
1480  */
1481 //--------------------------------------------------------------------------------------------------
1483 (
1484  le_audio_StreamRef_t streamRef,
1485  ///< [IN] Audio stream reference.
1486  uint32_t samplingRes
1487  ///< [IN] Sampling resolution (in bits per sample).
1488 );
1489 
1490 //--------------------------------------------------------------------------------------------------
1491 /**
1492  * Get the sampling resolution (in bits per sample) of a PCM sample.
1493  *
1494  * @return LE_FAULT Function failed.
1495  * @return LE_OK Function succeeded.
1496  *
1497  */
1498 //--------------------------------------------------------------------------------------------------
1500 (
1501  le_audio_StreamRef_t streamRef,
1502  ///< [IN] Audio stream reference.
1503  uint32_t* samplingResPtr
1504  ///< [OUT] Sampling resolution (in bits per sample).
1505 );
1506 
1507 //--------------------------------------------------------------------------------------------------
1508 /**
1509  * This function must be called to play a DTMF on a specific audio stream.
1510  *
1511  * @return LE_FORMAT_ERROR The DTMF characters are invalid.
1512  * @return LE_BUSY A DTMF playback is already in progress on the playback stream.
1513  * @return LE_FAULT Function failed to play the DTMFs.
1514  * @return LE_OK Function succeeded.
1515  *
1516  * @note If the DTMF string is too long (max DTMF_MAX_LEN characters), it is a fatal
1517  * error, the function will not return.
1518  * @note The process exits, if an invalid audio stream reference is given.
1519  */
1520 //--------------------------------------------------------------------------------------------------
1522 (
1523  le_audio_StreamRef_t streamRef,
1524  ///< [IN] Audio stream reference.
1525  const char* LE_NONNULL dtmf,
1526  ///< [IN] DTMFs to play.
1527  uint32_t duration,
1528  ///< [IN] DTMF duration in milliseconds.
1529  uint32_t pause
1530  ///< [IN] Pause duration between tones in milliseconds.
1531 );
1532 
1533 //--------------------------------------------------------------------------------------------------
1534 /**
1535  * This function must be called to ask to the Mobile Network to generate on the remote audio party
1536  * the DTMFs.
1537  *
1538  * @return LE_FORMAT_ERROR The DTMF characters are invalid.
1539  * @return LE_BUSY A DTMF playback is in progress.
1540  * @return LE_FAULT Function failed.
1541  * @return LE_OK Function succeeded.
1542  *
1543  * @note If the DTMF string is too long (max DTMF_MAX_LEN characters), it is a fatal
1544  * error, the function will not return.
1545  */
1546 //--------------------------------------------------------------------------------------------------
1548 (
1549  const char* LE_NONNULL dtmf,
1550  ///< [IN] DTMFs to play.
1551  uint32_t duration,
1552  ///< [IN] DTMF duration in milliseconds.
1553  uint32_t pause
1554  ///< [IN] Pause duration between tones in milliseconds.
1555 );
1556 
1557 //--------------------------------------------------------------------------------------------------
1558 /**
1559  * Set the encoding format of a recorder stream.
1560  *
1561  * @return LE_FAULT Function failed.
1562  * @return LE_OK Function succeeded.
1563  *
1564  */
1565 //--------------------------------------------------------------------------------------------------
1567 (
1568  le_audio_StreamRef_t streamRef,
1569  ///< [IN] Audio stream reference.
1570  le_audio_Format_t format
1571  ///< [IN] Encoding format.
1572 );
1573 
1574 //--------------------------------------------------------------------------------------------------
1575 /**
1576  * Get the encoding format of a recorder stream.
1577  *
1578  * @return LE_FAULT Function failed.
1579  * @return LE_OK Function succeeded.
1580  *
1581  * @note A client calling this function with either an invalid
1582  * streamRef or null out pointer parameter will be killed and the
1583  * function will not return.
1584  */
1585 //--------------------------------------------------------------------------------------------------
1587 (
1588  le_audio_StreamRef_t streamRef,
1589  ///< [IN] Audio stream reference.
1590  le_audio_Format_t* formatPtr
1591  ///< [OUT] Encoding format.
1592 );
1593 
1594 //--------------------------------------------------------------------------------------------------
1595 /**
1596  * Set the AMR mode for AMR encoder.
1597  *
1598  * @return LE_FAULT Function failed.
1599  * @return LE_OK Function succeeded.
1600  *
1601  */
1602 //--------------------------------------------------------------------------------------------------
1604 (
1605  le_audio_StreamRef_t streamRef,
1606  ///< [IN] Audio stream reference.
1607  le_audio_AmrMode_t mode
1608  ///< [IN] AMR mode.
1609 );
1610 
1611 //--------------------------------------------------------------------------------------------------
1612 /**
1613  * Get the AMR mode for AMR encoder.
1614  *
1615  * @return LE_FAULT Function failed.
1616  * @return LE_OK Function succeeded.
1617  *
1618  * @note A client calling this function with a null out pointer
1619  * parameter will be killed and the function will not return.
1620  */
1621 //--------------------------------------------------------------------------------------------------
1623 (
1624  le_audio_StreamRef_t streamRef,
1625  ///< [IN] Audio stream reference.
1626  le_audio_AmrMode_t* modePtr
1627  ///< [OUT] AMR mode.
1628 );
1629 
1630 //--------------------------------------------------------------------------------------------------
1631 /**
1632  * Set the AMR discontinuous transmission (DTX). The DTX is activated by default.
1633  *
1634  * @return LE_FAULT Function failed.
1635  * @return LE_OK Function succeeded.
1636  *
1637  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
1638  * function will not return.
1639  */
1640 //--------------------------------------------------------------------------------------------------
1642 (
1643  le_audio_StreamRef_t streamRef,
1644  ///< [IN] Audio stream reference.
1645  bool dtx
1646  ///< [IN] DTX.
1647 );
1648 
1649 //--------------------------------------------------------------------------------------------------
1650 /**
1651  * Get the AMR discontinuous transmission (DTX) value.
1652  *
1653  * @return LE_FAULT Function failed.
1654  * @return LE_OK Function succeeded.
1655  *
1656  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
1657  * function will not return.
1658  */
1659 //--------------------------------------------------------------------------------------------------
1661 (
1662  le_audio_StreamRef_t streamRef,
1663  ///< [IN] Audio stream reference.
1664  bool* dtxPtr
1665  ///< [OUT] DTX.
1666 );
1667 
1668 //--------------------------------------------------------------------------------------------------
1669 /**
1670  * Set the value of a platform specific gain in the audio subsystem.
1671  *
1672  * @return LE_BAD_PARAMETER The pointer to the name of the platform specific gain is invalid.
1673  * @return LE_NOT_FOUND The specified gain's name is not recognized in your audio subsystem.
1674  * @return LE_OUT_OF_RANGE The gain parameter is out of range.
1675  * @return LE_UNAVAILABLE The audio service initialization failed.
1676  * @return LE_FAULT On any other failure.
1677  * @return LE_OK The function succeeded.
1678  *
1679  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
1680  * function will not return.
1681  * @warning Ensure to check the names of supported gains for your specific platform.
1682  */
1683 //--------------------------------------------------------------------------------------------------
1685 (
1686  const char* LE_NONNULL gainName,
1687  ///< [IN] Name of the platform specific gain.
1688  int32_t gain
1689  ///< [IN] The gain value (specific to the platform)
1690 );
1691 
1692 //--------------------------------------------------------------------------------------------------
1693 /**
1694  * Get the value of a platform specific gain in the audio subsystem.
1695  *
1696  * @return LE_BAD_PARAMETER The pointer to the name of the platform specific gain is invalid.
1697  * @return LE_NOT_FOUND The specified gain's name is not recognized in your audio subsystem.
1698  * @return LE_UNAVAILABLE The audio service initialization failed.
1699  * @return LE_FAULT On any other failure.
1700  * @return LE_OK The function succeeded.
1701  *
1702  * @note If the caller is passing a bad reference into this function, it is a fatal error, the
1703  * function will not return.
1704  * @warning Ensure to check the names of supported gains for your specific platform.
1705  */
1706 //--------------------------------------------------------------------------------------------------
1708 (
1709  const char* LE_NONNULL gainName,
1710  ///< [IN] Name of the platform specific gain.
1711  int32_t* gainPtr
1712  ///< [OUT] The gain value (specific to the platform)
1713 );
1714 
1715 //--------------------------------------------------------------------------------------------------
1716 /**
1717  * Mute the Call Waiting Tone.
1718  *
1719  * @return LE_UNAVAILABLE On audio service initialization failure.
1720  * @return LE_FAULT On any other failure.
1721  * @return LE_OK The function succeeded.
1722  */
1723 //--------------------------------------------------------------------------------------------------
1725 (
1726  void
1727 );
1728 
1729 //--------------------------------------------------------------------------------------------------
1730 /**
1731  * Unmute the Call Waiting Tone.
1732  *
1733  * @return LE_UNAVAILABLE On audio service initialization failure.
1734  * @return LE_FAULT On any other failure.
1735  * @return LE_OK The function succeeded.
1736  */
1737 //--------------------------------------------------------------------------------------------------
1739 (
1740  void
1741 );
1742 
1743 #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)
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)
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_result_t le_audio_GetSampleAmrDtx(le_audio_StreamRef_t streamRef, bool *dtxPtr)
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)
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)
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)
le_audio_StreamRef_t le_audio_OpenSpeaker(void)
le_result_t le_audio_EnableFirFilter(le_audio_StreamRef_t streamRef)
uint32_t le_audio_GetPcmSamplingRate(void)
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)
le_result_t le_audio_DisableAutomaticGainControl(le_audio_StreamRef_t streamRef)
le_audio_ConnectorRef_t le_audio_CreateConnector(void)
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_FULL_API void le_audio_SetServerDisconnectHandler(le_audio_DisconnectHandler_t disconnectHandler, void *contextPtr)
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)
le_result_t le_audio_IsNoiseSuppressorEnabled(le_audio_StreamRef_t streamRef, bool *statusPtr)
le_result_t le_audio_SetProfile(uint32_t profile)
le_audio_StreamRef_t le_audio_OpenModemVoiceRx(void)
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:355
void le_audio_Close(le_audio_StreamRef_t streamRef)
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_result_t le_audio_SetPcmSamplingResolution(uint32_t bitsPerSample)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
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)
le_result_t le_audio_DisableFirFilter(le_audio_StreamRef_t streamRef)
void le_audio_ConnectService(void)
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)
le_result_t le_audio_SetSamplePcmSamplingResolution(le_audio_StreamRef_t streamRef, uint32_t samplingRes)
le_audio_MediaHandlerRef_t le_audio_AddMediaHandler(le_audio_StreamRef_t streamRef, le_audio_MediaHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_audio_GetEncodingFormat(le_audio_StreamRef_t streamRef, le_audio_Format_t *formatPtr)
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)
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)
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)