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