1/*---------------------------------------------------------------------------*
2 *  audioin.h  *
3 *                                                                           *
4 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
5 *                                                                           *
6 *  Licensed under the Apache License, Version 2.0 (the 'License');          *
7 *  you may not use this file except in compliance with the License.         *
8 *                                                                           *
9 *  You may obtain a copy of the License at                                  *
10 *      http://www.apache.org/licenses/LICENSE-2.0                           *
11 *                                                                           *
12 *  Unless required by applicable law or agreed to in writing, software      *
13 *  distributed under the License is distributed on an 'AS IS' BASIS,        *
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
15 *  See the License for the specific language governing permissions and      *
16 *  limitations under the License.                                           *
17 *                                                                           *
18 *---------------------------------------------------------------------------*/
19
20#ifndef __AUDIOIN_H__
21#define __AUDIOIN_H__
22/* -------------------------------------------------------------------------+
23 |                               ScanSoft Inc.                              |
24 + -------------------------------------------------------------------------*/
25
26
27
28/* -------------------------------------------------------------------------+
29 | Project       : ScanSoft AudioIn component
30 | Module        : AUDIOIN
31 | File name     : audioin.h
32 | Description   : Interface definition for AUDIOIN
33 | Reference(s)  : wavein, audioin.chm, audioin.doc, audioin.hlp
34 |                 SltGl00001_audioin_gl1.doc
35 | Status        : Version 1.2
36 + -------------------------------------------------------------------------*/
37/*     Oct/8/2002: Fixes for Windows 2000, and memory leaks. Version 1.1    */
38/*  PVP   Jan/8/2004: Default audio format changed to 16kHz. Version 2.0       */
39/*--------------------------------------------------------------------------*/
40
41/* @doc AUDIOININTERFACE */
42
43
44#include "audioinerr.h"
45
46#if defined( __cplusplus )
47extern "C"
48{
49#endif
50
51/* -------------------------------------------------------------------------+
52 |   MACROS                                                                 |
53 + -------------------------------------------------------------------------*/
54
55/* none */
56
57/* -------------------------------------------------------------------------+
58 |   TYPE DEFINITIONS                                                       |
59 + -------------------------------------------------------------------------*/
60
61typedef short audioinSample;
62
63
64/* Type Definitions for SCANSOFT-TYPES (re-definition)*/
65
66/* @type AUDIOIN_H | Handle to an audio-in component.
67 * @comm Type is declared as a void *. The actual implementation is
68 *       done by the implementation engineer. */
69typedef void *  AUDIOIN_H;
70#define WAVE_MAPPER 0
71/* @enum AUDIOIN_STATUSINFO | Enumerator for the Status Information of the AudioIn component.
72 * @comm The information contained in this definition concerns not only to the status of
73 *       the FIFO but also the general status of the audio component.
74 *
75 * @xref <f lh_audioinGetSamples>(), AudioIn Diagram State */
76typedef enum _AUDIOIN_STATUSINFO {
77  AUDIOIN_NORMAL,       /* @emem Normal state of the audio buffer. No problems detected while retrieving
78                                 samples.*/
79  AUDIOIN_TIMEOUT,      /* @emem The audio-in component timed out after no audio was received from the
80                                 audio device. The MMSystem is not providing any more samples, or the
81                                 lh_audioinGetSamples function may be called much faster than the actual
82                                 thread filling the buffer (Probable issue with the audio device). This could
83                                 be fixed by decreasing the number of samples that you want to retrieve or by
84                                 waiting till samples are available. A time out period is set internally on
85                                 the audioin implementation. Default of:
86                                 <nlpar>const DWORD GETSAMPLESTIMEOUT_PERIOD = 10000; (time in milliseconds)*/
87  AUDIOIN_HIGHWATERMARK,/* @emem The buffer has been filled out with 75% or more. A high watermark on
88                                 the audio buffer has been detected and the buffer could be close to an OVERRUN
89                                 state.*/
90  AUDIOIN_FIFOOVERRUN,  /* @emem The buffer has been overfilled with audio samples. You can still retrieve
91                                 samples from the FIFO with the lhs_audioinGetSamples function, but the audio-in
92                                 component will not buffer any new audio into the FIFO. AudioinStop must be
93                                 called to reset the audio-in component.*/
94  AUDIOIN_FLUSHED,      /* @emem The buffer has been overfilled with audio samples. You can no longer retrieve
95                                 samples from the FIFO, since you already emptied it with lhs_audioinGetSamples.
96                                 The audio-in component will not buffer any new audio into the FIFO.
97                                 lhs_audioinStop must be called in the audio-in component since
98                                 lhs_audioinGetSamples will not longer work.*/
99  AUDIOIN_HWOVERRUN,    /* @emem The buffer has been overfilled with audio samples inside the device component
100                                 (audio device). lhs_audioinStop should be called to reset the contents of the
101                                 FIFO and the codec. This state is caused by an error in the MMSystem. It is
102                                 recommended to initialize the audio-in component before retrieving samples
103                                 again.*/
104} AUDIOIN_STATUSINFO;
105
106
107/* @struct AUDIOIN_INFO | Structure for the AudioIn Information
108 * @comm The AUDIOIN_INFO contains information about several parts of the audio-in component.
109 *       It gives information about the FIFO buffering audio and at the same time about the audio
110 *       component.
111 *
112 * @xref <f lh_audioinGetSamples>(), AudioIn Diagram State */
113typedef struct _AUDIOIN_INFO{
114  AUDIOIN_STATUSINFO eStatusInfo;    /* @field The state in which the audio Buffer of the audio-in component
115                                               is. This is detailed in AUDIOIN_STATUSINFO. */
116  unsigned long u32SamplesAvailable; /* @field The number of Samples still available in the audio Buffer after
117                                               lhs_audioinGetSamples is called. This value can help you to
118                                               detect over-runs in the audio buffer.*/
119} AUDIOIN_INFO;
120
121#ifdef AUDIOIN_SUPPORT_CALLBACK
122typedef enum _AUDIOIN_MSG {
123  AUDIOIN_MSG_OPEN,           // audio device was opened
124  AUDIOIN_MSG_START,          // start audio acquisition
125  AUDIOIN_MSG_DATA,           // audio samples are available
126  AUDIOIN_MSG_STOP,           // stop audio acquisition
127  AUDIOIN_MSG_CLOSE,          // audio device was closed
128  AUDIOIN_MSG_INVALID,        // bogus
129} AUDIOIN_MSG;
130
131/* callback function for "samples ready" notification */
132typedef void (*pCallbackFunc)(AUDIOIN_H hAudioIn, AUDIOIN_MSG uMsg, void* dwInstance, void* dwParam1, void* dwParam2);
133
134/* data structure passed to callback function; loosely based on Windows' WAVEHDR */
135typedef struct {
136    void               *pData;
137    unsigned long       nBufferLength;
138    unsigned long       nBytesRecorded;
139    AUDIOIN_STATUSINFO  status;
140} AUDIOIN_WAVEHDR;
141#endif
142
143/* -------------------------------------------------------------------------+
144|   EXTERNAL DATA (+ meaning)                                              |
145+ -------------------------------------------------------------------------*/
146
147/* none */
148
149/* -------------------------------------------------------------------------+
150|   GLOBAL FUNCTION PROTOTYPES                                             |
151+ -------------------------------------------------------------------------*/
152#if 0
153 LHS_AUDIOIN_ERROR  lhs_audioinOpenEx (
154  unsigned long u32AudioInID,         /*@parm [in]  Audio-in device ID (ranges from 0 to a number of available
155                                                    devices on the system). You can also use the following flag
156                                                    instead of a device identifier.
157                                                    <nl><nl><bold WAVE_MAPPER> = The function selects a
158                                                    waveform-audio input device capable of recording in the
159                                                    specified format. <bold Header:> Declared in Mmsystem.h from
160                                                    the Windows Multimedia: Platform SDK.*/
161  unsigned long u32Frequency,         /*@parm [in]  Frequency of the recognition engine in Hz. */
162  unsigned long u32NbrOfFrames,       /*@parm [in]  (not used) Number of frames buffered internally */
163  unsigned long u32SamplesPerFrame,   /*@parm [in]  Size, in samples, of each individual frame. */
164  AUDIOIN_H * phAudioIn               /*@parm [out] Handle to the audio-in device */
165 );
166#endif
167
168LHS_AUDIOIN_ERROR  lhs_audioinOpen(
169  unsigned long u32AudioInID, /* [in] audio-in device ID (ranges from 0 to a number of available devices on the
170                                      system). You can also use the following flag instead of a device identifier.
171                                      <nl><nl><bold WAVE_MAPPER> = The function selects a waveform-audio input
172                                      device capable of recording in the specified format. <bold Header:>
173                                      Declared in Mmsystem.h from the Windows Multimedia: Platform SDK.*/
174  unsigned long u32Frequency, /* [in] Frequency of the recognition engine in Hz. */
175  AUDIOIN_H * phAudioIn       /* [out] Handle to the audio-in device */
176);
177
178#ifdef AUDIOIN_SUPPORT_CALLBACK
179LHS_AUDIOIN_ERROR  lhs_audioinOpenCallback(
180  unsigned long u32AudioInID,      /* [in] audio-in device ID (ranges from 0 to a number of available devices on the
181                                      system). You can also use the following flag instead of a device identifier.
182                                      <nl><nl><bold WAVE_MAPPER> = The function selects a waveform-audio input
183                                      device capable of recording in the specified format. <bold Header:>
184                                      Declared in Mmsystem.h from the Windows Multimedia: Platform SDK.*/
185  unsigned long u32Frequency,      /* [in] Frequency of the recognition engine in Hz. */
186  unsigned long u32NbrOfSamples,   /*[in] <nl><bold Input:> Number of samples requested per callback */
187
188  pCallbackFunc pCallback,         /* [in] callback function */
189  void         *pCallbackInstance, /* [in] callback instance */
190  AUDIOIN_H * phAudioIn            /* [out] Handle to the audio-in device */
191);
192#endif
193
194LHS_AUDIOIN_ERROR lhs_audioinClose(
195  AUDIOIN_H * phAudioIn /*[in] Pointer to the handle of the audio-in device to be closed.*/
196);
197
198LHS_AUDIOIN_ERROR lhs_audioinStart(
199  AUDIOIN_H hAudioIn    /*[in] Handle of the audio-in device */
200);
201
202LHS_AUDIOIN_ERROR lhs_audioinStop(
203  AUDIOIN_H hAudioIn    /*[in] Handle of the audio-in device*/
204);
205
206LHS_AUDIOIN_ERROR lhs_audioinGetSamples (
207  AUDIOIN_H hAudioIn,              /*[in] Handle of the audio-in device */
208  unsigned long * u32NbrOfSamples, /*[in/out] <nl><bold Input:> The requested number of samples to be filled in
209                                              the pAudioBuffer. Note that the memory used for pBuffer should be large enough
210                                              to contain the requested number of samples, also note how the u32NbrOfSamples
211                                              is different than the Buffer size, since each frame has an specific size depending
212                                              on the audio format.
213                                              <nl><bold Output:> The actual number of recorded audio samples written in pBuffer.
214                                              If you pass 0 to this parameter then you may still retrieve the AUDIOIN_STATUSINFO
215                                              on the audio component. */
216  void * pAudioBuffer,              /*[out] Buffer that contains the recorded samples. The memory used for this
217                                            buffer is allocated by the client. So, it is the responsibility of the client to
218                                            make sure that this memory can contain the requested number of samples. The memory
219                                            for this buffer needs also to be freed by the client. */
220  AUDIOIN_INFO * pAudioInInfo       /*[out] Information about the audio internal buffer described in
221                                            AUDIOIN_INFO.*/
222);
223
224
225LHS_AUDIOIN_ERROR lhs_audioinGetVersion(
226  unsigned long * pu32Version       /*[out] The version number of the API implementation. */
227);
228
229
230LHS_AUDIOIN_ERROR lhs_audioinGetVolume(
231  AUDIOIN_H hAudioIn,             /*[in] Handle of the audio-in device.*/
232  unsigned long * pu32Volume      /*[out] Pointer to a variable that will be filled with the current volume
233                                          (normally range of  0 - 65535). Depending on the platform the volume
234                                          value may be set to in sizes of 16, 32 or other size, the range also
235                                          depends on the platform (Implementations of this interface may
236                                          change because of the compatibility of the internal function).*/
237);
238
239LHS_AUDIOIN_ERROR lhs_audioinSetVolume(
240  AUDIOIN_H hAudioIn,         /*[in] Handle of the audio-in device.*/
241  unsigned long u32Volume     /*[in] The volume to be set (normal range 0-65535). Depending on the
242                                     platform the volume value may be set to in sizes of 16, 32 or other size,
243                                     the range also depends on the platform. (Implementations of this interface
244                                     may change because of the compatibility of the internal function)*/
245);
246
247
248const TCHAR * lhs_audioinErrorGetString(
249  const LHS_AUDIOIN_ERROR Error    /*[in] The Error code.*/
250);
251
252
253/* -------------------------------------------------------------------------+
254 |   END                                                                    |
255 + -------------------------------------------------------------------------*/
256
257#if defined( __cplusplus )
258}
259#endif
260
261
262#endif /* #ifndef __AUDIOIN_H__ */
263