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 */
44typedef 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}
97SR_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 */
121SREC_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 */
129SREC_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 */
148SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateReset(SR_Recognizer* recognizer);
149SREC_ACOUSTICSTATE_API ESR_ReturnCode SR_AcousticStateSet ( SR_Recognizer* recognizer, const LCHAR *param_string );
150SREC_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