1 /*---------------------------------------------------------------------------* 2 * SR_Vocabulary.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_VOCABULARY_H 21 #define __SR_VOCABULARY_H 22 23 24 25 #include "ESR_Locale.h" 26 #include "ESR_ReturnCode.h" 27 #include "pstdio.h" 28 #include "SR_VocabularyPrefix.h" 29 30 31 /** 32 * @addtogroup SR_VocabularyModule SR_Vocabulary API functions 33 * A vocabulary maps words to their phonetic representation. 34 * 35 * @{ 36 */ 37 38 /** 39 * A vocabulary maps words to their phonetic representation. 40 */ 41 typedef struct SR_Vocabulary_t 42 { 43 /** 44 * Saves a vocabulary to file. 45 * 46 * @param self SR_Vocabulary handle 47 * @param filename File to write to 48 */ 49 ESR_ReturnCode(*save)(struct SR_Vocabulary_t* self, const LCHAR* filename); 50 51 /** 52 * Returns phonetic representation of word. 53 * 54 * @param self SR_Vocabulary handle 55 * @param word Word to check for 56 * @param pronunciation [out] Phonetic representation of word 57 * @param len [in/out] Length of value argument. If the return code is 58 * ESR_BUFFER_OVERFLOW, the required length is returned in this variable. 59 */ 60 ESR_ReturnCode(*getPronunciation)(struct SR_Vocabulary_t* self, const LCHAR* word, LCHAR* pronunciation, size_t* len); 61 62 /** 63 * Returns vocabulary locale. 64 * 65 * @param self SR_Vocabulary handle 66 * @param locale [out] Vocabulary locale 67 */ 68 ESR_ReturnCode(*getLanguage)(struct SR_Vocabulary_t* self, ESR_Locale* locale); 69 70 /** 71 * Destroys a Vocabulary. 72 * 73 * @param self SR_Vocabulary handle 74 */ 75 ESR_ReturnCode(*destroy)(struct SR_Vocabulary_t* self); 76 } 77 SR_Vocabulary; 78 79 /** 80 * @name Vocabulary creation 81 * 82 * There are two ways to generate a vocabulary: 83 * 84 * 1. Load a vocabulary from disk. Phonemes are retrieved from a lookup table, 85 * and fall back on a TTP engine if necessary. 86 * 2. Create an empty vocabulary. Phonemes are retrieved exclusively from a TTP engine. 87 * 88 * @{ 89 */ 90 91 /** 92 * Creates an empty Vocabulary using the specified language. 93 * 94 * @param locale 95 * @param self SR_Vocabulary handle 96 */ 97 SREC_VOCABULARY_API ESR_ReturnCode SR_VocabularyCreate(ESR_Locale locale, SR_Vocabulary** self); 98 99 /** 100 * Loads a vocabulary from file. 101 * 102 * @param self SR_Vocabulary handle 103 * @param filename File to read from 104 * @todo In the future, read language from the underlying vocabulary file 105 */ 106 SREC_VOCABULARY_API ESR_ReturnCode SR_VocabularyLoad(const LCHAR* filename, SR_Vocabulary** self); 107 108 /** 109 * @} 110 */ 111 112 /** 113 * Saves a vocabulary to file. 114 * 115 * @param self SR_Vocabulary handle 116 * @param filename File to write to 117 */ 118 SREC_VOCABULARY_API ESR_ReturnCode SR_VocabularySave(SR_Vocabulary* self, const LCHAR* filename); 119 120 /** 121 * Adds word to vocabulary. 122 * 123 * @param self SR_Vocabulary handle 124 * @param word Word to be added 125 * @todo Function purpose is unclear 126 */ 127 SREC_VOCABULARY_API ESR_ReturnCode SR_VocabularyAddWord(SR_Vocabulary* self, const LCHAR* word); 128 129 130 /** 131 * Returns vocabulary locale. 132 * 133 * @param self SR_Vocabulary handle 134 * @param locale [out] Vocabulary locale 135 */ 136 SREC_VOCABULARY_API ESR_ReturnCode SR_VocabularyGetLanguage(SR_Vocabulary* self, ESR_Locale* locale); 137 138 /** 139 * Destroys a Vocabulary. 140 * 141 * @param self SR_Vocabulary handle 142 */ 143 SREC_VOCABULARY_API ESR_ReturnCode SR_VocabularyDestroy(SR_Vocabulary* self); 144 145 /** 146 * Looks up a word to vocabulary. 147 * 148 * @param self SR_Vocabulary handle 149 * @param word Word to be added 150 * @param pronunciation resulting pronunication 151 * @param len [in/out] Length of phoeme argument. If the return code is ESR_BUFFER_OVERFLOW, 152 * the required length is returned in this variable. 153 */ 154 SREC_VOCABULARY_API ESR_ReturnCode SR_VocabularyGetPronunciation(SR_Vocabulary* self, const LCHAR* word, LCHAR* pronunciation, size_t* len); 155 156 /** 157 * @} 158 */ 159 160 /* To-Do: the following functions need to be removed. The functions are still used in SR_NameTag.dll */ 161 SREC_VOCABULARY_API ESR_ReturnCode SR_Vocabulary_etiinf_conv_multichar(ESR_Locale locale, const LCHAR* input, LCHAR* output, size_t max_len); 162 SREC_VOCABULARY_API ESR_ReturnCode SR_Vocabulary_etiinf_conv_from_multichar(ESR_Locale locale, const LCHAR* input, LCHAR* output); 163 164 #endif /* __SR_VOCABULARY_H */ 165