1/*---------------------------------------------------------------------------*
2 *  SR_RecognizerResult.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_RECOGNIZERRESULT_H
21#define __SR_RECOGNIZERRESULT_H
22
23
24
25#include <stddef.h>
26#include "ESR_Locale.h"
27#include "ESR_ReturnCode.h"
28#include "SR_RecognizerPrefix.h"
29#include "ptypes.h"
30
31/**
32 * @addtogroup SR_RecognizerResultModule SR_RecognizerResult API functions
33 * Recognition result.
34 *
35 * @{
36 */
37
38/**
39 * Recognition result.
40 */
41typedef struct SR_RecognizerResult_t
42{
43  /**
44   * Returns the endpointed waveform that was used for recognition. This returns a read-only buffer,
45   * and may not be modified externally.
46   *
47   * @param self RecognizerResult handler
48   * @param waveform [out] Waveform buffer
49   * @param size [out] Size of waveform buffer (in bytes)
50   * @return ESR_INVALID_ARGUMENT if self, or waveform are null
51   */
52  ESR_ReturnCode(*getWaveform)(const struct SR_RecognizerResult_t* self, const asr_int16_t** waveform,
53                               size_t* size);
54  /**
55   * Returns number of entries in the n-best list.
56   *
57   * @param self RecognizerResult handler
58    * @param resultSize [out] Number of entries
59   * @return ESR_INVALID_ARGUMENT if self is null
60   */
61  ESR_ReturnCode(*getSize)(const struct SR_RecognizerResult_t* self, size_t* resultSize);
62  /**
63   * Returns number of [key, value] pairs in the current results.
64   *
65   * @param self SR_RecognizerResult handler
66    * @param nbest Index of n-best list element (0-based)
67   * @param count The number keys
68   * @return ESR_INVALID_ARGUMENT if self is null
69   */
70  ESR_ReturnCode(*getKeyCount)(const struct SR_RecognizerResult_t* self, const size_t nbest,
71                               size_t* count);
72  /**
73   * Given an array of pointers to <code>LCHAR*</code>, populates that array with pointers
74    * to the keys used internally by the recognition result. These keys should not be modified!
75   *
76   * @param self SemanticResult handler
77    * @param nbest Index of n-best list element (0-based)
78   * @param list [out] List of keys associated with n-best list entry.
79    * @param listSize [in/out] Size of list. If the return code is ESR_BUFFER_OVERFLOW, the required size
80    *                 is returned in this variable.
81   * @return ESR_INVALID_ARGUMENT if self or list are null; ESR_OUT_OF_BOUNDS if nbest entry does not exist;
82   * ESR_BUFFER_OVERFLOW if the list that was passed in was too small
83   */
84  ESR_ReturnCode(*getKeyList)(const struct SR_RecognizerResult_t* self, const size_t nbest,
85                              LCHAR** list, size_t* listSize);
86  /**
87   * Returns copy of semantic value.
88   *
89   * @param self SemanticResult handler
90    * @param nbest Index of n-best list element (0-based)
91    * @param key The key to look up
92   * @param value [out] The buffer used to hold the resulting value
93   * @param len [in/out] Length of value argument. If the return code is ESR_BUFFER_OVERFLOW,
94   *            the required length is returned in this variable.
95   * @return ESR_INVALID_ARGUMENT if self or list are null; ESR_OUT_OF_BOUNDS if nbest entry does not exist;
96   * ESR_BUFFER_OVERFLOW if the buffer that was passed in was too small
97   */
98  ESR_ReturnCode(*getValue)(const struct SR_RecognizerResult_t* self, const size_t nbest,
99                            const LCHAR* key, LCHAR* value, size_t* len);
100
101  /**
102   * Returns locale of the grammar that produced this recognition result
103   *
104   * @param self SR_RecognizerResult handle
105   * @param locale The locale associated with the result
106  * @return ESR_INVALID_ARGUMENT if self is null
107   */
108  ESR_ReturnCode(*getLocale)(const struct SR_RecognizerResult_t* self,  ESR_Locale* locale);
109
110}
111SR_RecognizerResult;
112
113/**
114 * Returns the endpointed waveform that was used for recognition. This returns a read-only buffer,
115 * and may not be modified externally.
116 *
117 * @param self RecognizerResult handler
118 * @param waveform [out] Waveform buffer
119 * @param size [out] Size of waveform buffer (in bytes)
120 * @return ESR_INVALID_ARGUMENT if self, or waveform are null
121 */
122SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerResultGetWaveform(const SR_RecognizerResult* self,
123    const asr_int16_t** waveform, size_t* size);
124/**
125 * Returns number of entries in the n-best list.
126 *
127 * @param self RecognizerResult handler
128 * @param resultSize [out] Number of entries
129 * @return ESR_INVALID_ARGUMENT if self is null
130 */
131SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerResultGetSize(const SR_RecognizerResult* self,
132    size_t* resultSize);
133/**
134 * Returns number of [key, value] pairs in the current results.
135 *
136 * @param nbest Index of n-best list element (0-based)
137 * @param self SemanticResult handler
138 * @param count The number keys
139 * @return ESR_INVALID_ARGUMENT if self is null
140 */
141SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerResultGetKeyCount(const SR_RecognizerResult* self,
142    const size_t nbest,
143    size_t* count);
144/**
145 * Given an array of pointers to <code>LCHAR*</code>, populates that array with pointers
146 * to the keys used internally by the recognition result. These keys should not be modified!
147 *
148 * @param self SemanticResult handler
149 * @param nbest Index of n-best list element (0-based)
150 * @param list [out] List of keys associated with n-best list entry.
151 * @param listSize [in/out] Size of list. If the return code is ESR_BUFFER_OVERFLOW, the required size
152 *                 is returned in this variable.
153 * @return ESR_INVALID_ARGUMENT if self or list are null; ESR_OUT_OF_BOUNDS if nbest entry does not exist;
154 * ESR_BUFFER_OVERFLOW if the list that was passed in was too small
155 */
156SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerResultGetKeyList(const SR_RecognizerResult* self,
157    const size_t nbest,
158    LCHAR** list,
159    size_t* listSize);
160/**
161 * Returns copy of semantic value.
162 *
163 * @param self SemanticResult handler
164 * @param nbest Index of n-best list element (0-based)
165 * @param key The key to look up
166 * @param value [out] The buffer used to hold the resulting value
167 * @param len [in/out] Length of value argument. If the return code is ESR_BUFFER_OVERFLOW,
168 *            the required length is returned in this variable.
169 * @return ESR_INVALID_ARGUMENT if self or list are null; ESR_OUT_OF_BOUNDS if nbest entry does not exist;
170 * ESR_BUFFER_OVERFLOW if the buffer that was passed in was too small
171 */
172SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerResultGetValue(const SR_RecognizerResult* self,
173    const size_t nbest,
174    const LCHAR* key,
175    LCHAR* value, size_t* len);
176
177/**
178 * Returns locale of grammar that produced this result
179 *
180 * @param self SR_RecognizerResult handle
181 * @param locale The locale associated with the result
182 * @return ESR_INVALID_ARGUMENT if self is null
183 */
184SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerResultGetLocale(const SR_RecognizerResult* self,
185    ESR_Locale* locale);
186
187/**
188 * @}
189 */
190
191
192#endif /* __SR_RECOGNIZERRESULT_H */
193