• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*---------------------------------------------------------------------------*
2  *  SR_AcousticState.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 __SR_ACOUSTICSTATE_H
21 #define __SR_ACOUSTICSTATE_H
22 
23 
24 
25 #include <stddef.h>
26 #include <stdlib.h>
27 #include "SR_AcousticModels.h"
28 #include "SR_AcousticStatePrefix.h"
29 #include "SR_Recognizer.h"
30 #include "pstdio.h"
31 #include "ESR_ReturnCode.h"
32 
33 
34 /**
35  * @addtogroup SR_AcousticStateModule SR_AcousticState API functions
36  * Contains Acoustic state information.
37  *
38  * @{
39  */
40 
41 /**
42  * Contains Acoustic state information.
43  */
44 typedef struct SR_AcousticState_t
45 {
46   /**
47    * Resets the acoustic state object.
48    * The recognizer adapts to the acoustic state of the caller and calling environment
49    * during a call in order to improve recognition accuracy. The platform must reset
50    * the AcousticState either at the beginning of a new call or at the end of a call in
51    * order to reset acoustic state information for a new caller.
52    *
53    * @param recognizer SR_Recognizer handle
54   * @return ESR_INVALID_ARGUMENT if recognizer is null
55    */
56   ESR_ReturnCode(*reset)(SR_Recognizer* recognizer);
57   /**
58    * Loads an AcousticState from file.
59    *
60    * @param recognizer SR_Recognizer handle
61    * @param file File to read from
62    * @return ESR_INVALID_ARGUMENT if recognizer is null
63    */
64   ESR_ReturnCode(*load)(SR_Recognizer* recognizer, const LCHAR* filename);
65   /**
66    * Saves an AcousticState to a file.
67    *
68    * @param recognizer SR_Recognizer handle
69    * @param file File to write into
70    * @return ESR_INVALID_ARGUMENT if recognizer is null
71    */
72   ESR_ReturnCode(*save)(SR_Recognizer* recognizer, const LCHAR* filename);
73   /**
74    * Gets an AcousticState into a string.
75    *
76    * @param recognizer SR_Recognizer handle
77    * @param param_string contains data from the recognizer
78    * @return ESR_INVALID_ARGUMENT if recognizer is null
79    */
80   ESR_ReturnCode(*get)(SR_Recognizer* recognizer, LCHAR *param_string, size_t* len );
81   /**
82    * Sets an AcousticState from a string.
83    *
84    * @param recognizer SR_Recognizer handle
85    * @param param_string contains data to set
86    * @return ESR_INVALID_ARGUMENT if recognizer is null
87    */
88   ESR_ReturnCode(*set)(SR_Recognizer* recognizer, const LCHAR *param_string );
89   /**
90    * Destrroys the acoustic state of a recognizer
91    *
92    * @param recognizer SR_Recognizer handle
93   * @return ESR_INVALID_ARGUMENT if recognizer is null
94    */
95   ESR_ReturnCode(*destroy)(SR_Recognizer* recognizer);
96 }
97 SR_AcousticState;
98 
99 /**
100  * @name AcousticState
101  *
102  * An AcousticState is a container for the configurations of several items used in recognition:
103  *
104  * - What models are in use (where there is more than one available). E.g. M/F or adapted models.
105  * - Properties of the channels (microphone, environment, speaker). These properties are updated
106  * during recognition. E.g. There may be more than one microphone in use, offering zone-based
107  * input. Each zone may require the maintenance of its own channel settings.
108  *
109  * AcousticState must offer persistence to reflect optimal settings and preferred use on start-up.
110  *
111  * @{
112  */
113 
114 /**
115  * Loads an AcousticState from file.
116  *
117  * @param recognizer SR_Recognizer handle
118  * @param filename File to read from
119  * @return ESR_INVALID_ARGUMENT if recognizer is null
120  */
121 SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateLoad(SR_Recognizer* recognizer, const LCHAR* filename);
122 /**
123  * Saves an AcousticState to a file.
124  *
125  * @param recognizer SR_Recognizer handle
126  * @param filename File to write into
127  * @return ESR_NOT_IMPLEMENTED
128  */
129 SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateSave(SR_Recognizer* recognizer, const LCHAR* filename);
130 /**
131  * @}
132  *
133  * @name Possible AcousticState <-> Model operations
134  *
135  * @{
136  */
137 
138 /**
139  * Resets the acoustic state object.
140  * The recognizer adapts to the acoustic state of the caller and calling environment
141  * during a call in order to improve recognition accuracy. The platform must reset
142  * the AcousticState either at the beginning of a new call or at the end of a call in
143  * order to reset acoustic state information for a new caller.
144  *
145  * @param recognizer SR_Recognizer handle
146  * @return ESR_INVALID_ARGUMENT if recognizer is null
147  */
148 SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateReset(SR_Recognizer* recognizer);
149 SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateSet ( SR_Recognizer* recognizer, const LCHAR *param_string );
150 SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateGet ( SR_Recognizer* recognizer, LCHAR *param_string, size_t* len );
151 /**
152  * @}
153  */
154 
155 /**
156  * @}
157  */
158 
159 #endif /* __SR_ACOUSTICSTATE_H */
160