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 */
41typedef 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}
77SR_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 */
97SREC_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 */
106SREC_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 */
118SREC_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 */
127SREC_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 */
136SREC_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 */
143SREC_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 */
154SREC_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  */
161SREC_VOCABULARY_API ESR_ReturnCode SR_Vocabulary_etiinf_conv_multichar(ESR_Locale locale, const LCHAR* input, LCHAR* output, size_t max_len);
162SREC_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