1/*---------------------------------------------------------------------------*
2 *  SR_Nametags.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_NAMETAGS_H
21#define __SR_NAMETAGS_H
22
23
24
25#include "SR_NametagsPrefix.h"
26#include "ptypes.h"
27#include "pstdio.h"
28//#include "SR_Recognizer.h"
29#include "SR_NametagDefs.h"
30#include "ESR_ReturnCode.h"
31
32
33/**
34 * @addtogroup SR_NametagsModule SR_Nametags API functions
35 * Represents a Nametag collection.
36 *
37 * @{
38 */
39
40/**
41 * Represents a Nametag collection.
42 */
43typedef struct SR_Nametags_t
44{
45  /**
46   * Loads a nametag collection.
47   *
48   * @param self Nametags handle
49   * @param filename File to read from
50   */
51  ESR_ReturnCode(*load)(struct SR_Nametags_t* self, const LCHAR* filename);
52
53  /**
54   * Saves a nametag collection.
55   *
56   * @param self Nametags handle
57   * @param filename File to write to
58   */
59  ESR_ReturnCode(*save)(struct SR_Nametags_t* self, const LCHAR* filename);
60
61  /**
62   * Adds nametag to collection.
63   *
64   * @param self Nametags handle
65   * @param nametag Nametag to be added
66   */
67  ESR_ReturnCode(*add)(struct SR_Nametags_t* self, SR_Nametag* nametag);
68
69  /**
70   * Removes nametag from collection.
71   *
72   * @param self Nametags handle
73   * @param id ID of nametag to be removed
74   */
75  ESR_ReturnCode(*remove)(struct SR_Nametags_t* self, const LCHAR* id);
76
77  /**
78   * Returns the number of nametags within the collection.
79   *
80   * @param self Nametags handle
81   * @param result Resulting value
82   */
83  ESR_ReturnCode(*getSize)(struct SR_Nametags_t* self, size_t* result);
84
85  /**
86   * Returns Nametag with the specified ID. It is illegal to destroy the returned Nametag
87   * until it is removed from the Nametags collection.
88   *
89   * @param self Nametags handle
90   * @param ud Nametag id
91   * @param nametag Nametag at index
92   */
93  ESR_ReturnCode(*get)(struct SR_Nametags_t* self, const LCHAR* id, SR_Nametag** nametag);
94
95  /**
96   * Returns Nametag at the specified index. It is illegal to destroy the returned Nametag
97   * until it is removed from the Nametags collection.
98   *
99   * @param self Nametags handle
100   * @param index Nametag index
101   * @param nametag Nametag at index
102   */
103  ESR_ReturnCode(*getAtIndex)(struct SR_Nametags_t* self, size_t index, SR_Nametag** nametag);
104
105  /**
106   * Indicates if collection contains specified nametag.
107   *
108   * @param self Nametags handle
109   * @param id Nametag ID to search for
110    * @param result True if nametag was found
111   */
112  ESR_ReturnCode(*contains)(struct SR_Nametags_t* self, const LCHAR* id, ESR_BOOL* result);
113
114  /**
115  * Destroys a nametag collection.
116  *
117  * @param self Nametags handle
118  */
119  ESR_ReturnCode(*destroy)(struct SR_Nametags_t* self);
120}
121SR_Nametags;
122
123/**
124 * @name Nametags operations
125 *
126 * @{
127 */
128
129/**
130 * Create a new Nametag collection.
131 *
132 * @param self Nametags handle
133 */
134SREC_NAMETAG_API ESR_ReturnCode SR_NametagsCreate(SR_Nametags** self);
135
136/**
137 * Loads a nametag collection.
138 *
139 * @param self Nametags handle
140 * @param filename File to read from
141 */
142SREC_NAMETAG_API ESR_ReturnCode SR_NametagsLoad(SR_Nametags* self, const LCHAR* filename);
143
144/**
145 * Saves a nametag collection.
146 *
147 * @param self Nametags handle
148 * @param filename File to write to
149 */
150SREC_NAMETAG_API ESR_ReturnCode SR_NametagsSave(SR_Nametags* self, const LCHAR* filename);
151
152/**
153 * Adds nametag to collection.
154 *
155 * @param self Nametags handle
156 * @param nametag Nametag to be added
157 */
158SREC_NAMETAG_API ESR_ReturnCode SR_NametagsAdd(SR_Nametags* self, SR_Nametag* nametag);
159
160/**
161 * Removes nametag from collection.
162 *
163 * @param self Nametags handle
164 * @param id ID of nametag to be removed
165 */
166SREC_NAMETAG_API ESR_ReturnCode SR_NametagsRemove(SR_Nametags* self, const LCHAR* id);
167
168/**
169 * Returns the number of nametags within the collection.
170 *
171 * @param self Nametags handle
172 * @param result Resulting value
173 */
174SREC_NAMETAG_API ESR_ReturnCode SR_NametagsGetSize(SR_Nametags* self, size_t* result);
175
176/**
177 * Returns Nametag with the specified ID. It is illegal to destroy the returned Nametag
178 * until it is removed from the Nametags collection.
179 *
180 * @param self Nametags handle
181 * @param id Nametag ID
182 * @param nametag Nametag at index
183 */
184SREC_NAMETAG_API ESR_ReturnCode SR_NametagsGet(SR_Nametags* self, const LCHAR* id, SR_Nametag** nametag);
185
186/**
187 * Returns Nametag at the specified index. It is illegal to destroy the returned Nametag
188 * until it is removed from the Nametags collection.
189 *
190 * @param self Nametags handle
191 * @param index Nametag index
192 * @param nametag Nametag at index
193 */
194SREC_NAMETAG_API ESR_ReturnCode SR_NametagsGetAtIndex(SR_Nametags* self, size_t index, SR_Nametag** nametag);
195
196/**
197 * Indicates if collection contains specified nametag.
198 *
199 * @param self Nametags handle
200 * @param id Nametag ID to search for
201 * @param result True if nametag was found
202 */
203SREC_NAMETAG_API ESR_ReturnCode SR_NametagsContains(SR_Nametags* self, const LCHAR* id, ESR_BOOL* result);
204
205/**
206 * Destroys a Nametag collection.
207 *
208 * @param self Nametag handle
209 */
210SREC_NAMETAG_API ESR_ReturnCode SR_NametagsDestroy(SR_Nametags* self);
211
212/**
213 * @}
214 */
215
216/**
217 * @}
218 */
219
220#endif /* __SR_NAMETAGS_H */
221