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 */ 41 typedef 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 } 111 SR_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 */ 122 SREC_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 */ 131 SREC_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 */ 141 SREC_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 */ 156 SREC_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 */ 172 SREC_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 */ 184 SREC_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