1/*---------------------------------------------------------------------------*
2 *  ESR_SessionType.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 __ESR_SESSIONTYPE_H
21#define __ESR_SESSIONTYPE_H
22
23
24
25#include "ESR_ReturnCode.h"
26#include "ESR_SharedPrefix.h"
27#include "ESR_VariableTypes.h"
28#include "ESR_SessionTypeListener.h"
29#include "pstdio.h"
30#include "ptypes.h"
31
32/**
33 * @addtogroup ESR_SessionTypeModule ESR_SessionType API functions
34 * ESR_Session interface functions.
35 *
36 * @{
37 */
38
39/**
40 * Hashmap with helper functions for adding primitives and add-if-empty.
41 */
42typedef struct ESR_SessionType_t
43{
44  /**
45   * Returns session property value.
46   *
47   * @param self ESR_SessionType handle
48   * @param name Property name
49   * @param value Property value
50   * @param type Expected variable type (for strong-typing purposes)
51   * @return ESR_INVALID_RESULT_TYPE if the property is not of the specified type
52   */
53  ESR_ReturnCode(*getProperty)(struct ESR_SessionType_t* self, const LCHAR* name, void** value, VariableTypes type);
54  /**
55   * Returns the type of a property value.
56   *
57   * @param self ESR_SessionType handle
58   * @param name Property name
59   * @param type [out] Value type
60   * @return ESR_INVALID_ARGUMENT if self is null or property cannot be found
61   */
62  ESR_ReturnCode(*getPropertyType)(struct ESR_SessionType_t* self, const LCHAR* name, VariableTypes* type);
63  /**
64   * Returns copy of session property value.
65   *
66   * @param self ESR_SessionType handle
67   * @param name Property name
68   * @param value Property value
69   * @return ESR_INVALID_RESULT_TYPE if the property is not a int
70   */
71  ESR_ReturnCode(*getInt)(struct ESR_SessionType_t* self, const LCHAR* name, int* value);
72  /**
73   * Returns copy of session property value.
74   *
75   * @param name Property name
76   * @param value Property value
77   * @return ESR_INVALID_RESULT_TYPE if the property is not a asr_uint16_t
78   */
79  ESR_ReturnCode(*getUint16_t)(struct ESR_SessionType_t* self, const LCHAR* name, asr_uint16_t* value);
80  /**
81   * Returns copy of session property value.
82   *
83   * @param self ESR_SessionType handle
84   * @param name Property name
85   * @param value Property value
86   * @return ESR_INVALID_RESULT_TYPE if the property is not a size_t
87   * @return ESR_INVALID_RESULT_TYPE if the property is not a size_t
88   */
89  ESR_ReturnCode(*getSize_t)(struct ESR_SessionType_t* self, const LCHAR* name, size_t* value);
90  /**
91   * Returns copy of session property value.
92   *
93   * @param self ESR_SessionType handle
94   * @param name Property name
95   * @param value Property value
96   * @return ESR_INVALID_RESULT_TYPE if the property is not a float
97   */
98  ESR_ReturnCode(*getFloat)(struct ESR_SessionType_t* self, const LCHAR* name, float* value);
99  /**
100   * Returns copy of session property value.
101   *
102   * @param self ESR_SessionType handle
103   * @param name Property name
104   * @param value Property value
105   * @return ESR_INVALID_RESULT_TYPE if the property is not a bool
106   */
107  ESR_ReturnCode(*getBool)(struct ESR_SessionType_t* self, const LCHAR* name, ESR_BOOL* value);
108  /**
109   * Returns copy of session property value.
110   *
111   * @param self ESR_SessionType handle
112   * @param name Property name
113   * @param value Property value
114   * @param len Size of value argument. If the return code is ESR_BUFFER_OVERFLOW,
115   *            the required length is returned in this variable.
116   * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*
117   */
118  ESR_ReturnCode(*getLCHAR)(struct ESR_SessionType_t* self, const LCHAR* name, LCHAR* value, size_t* len);
119  /**
120   * Indicates if key exists in the session.
121   *
122   * @param self ESR_SessionType handle
123   * @param name Property name
124   * @param exists True if key exists, false otherwise
125   * @return ESR_INVALID_ARGUMENT if self is null
126   */
127  ESR_ReturnCode(*contains)(struct ESR_SessionType_t* self, const LCHAR* name, ESR_BOOL* exists);
128  /**
129   * Sets session property value.
130   *
131   * @param self ESR_SessionType handle
132   * @param name Property name
133   * @param value Property value
134   * @param type Type of value being set
135   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
136   */
137  ESR_ReturnCode(*setProperty)(struct ESR_SessionType_t* self, const LCHAR* name, void* value, VariableTypes type);
138  /**
139   * Sets session property value, storing a copy of the value.
140   *
141   * @param self ESR_SessionType handle
142   * @param name Property name
143   * @param value Property value
144   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
145   */
146  ESR_ReturnCode(*setInt)(struct ESR_SessionType_t* self, const LCHAR* name, int value);
147  /**
148   * Sets session property value, storing a copy of the value.
149   *
150   * @param name Property name
151   * @param value Property value
152   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
153   */
154  ESR_ReturnCode(*setUint16_t)(struct ESR_SessionType_t* self, const LCHAR* name, asr_uint16_t value);
155  /**
156   * Sets session property value, storing a copy of the value.
157   *
158   * @param self ESR_SessionType handle
159   * @param name Property name
160   * @param value Property value
161   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
162   */
163  ESR_ReturnCode(*setSize_t)(struct ESR_SessionType_t* self, const LCHAR* name, size_t value);
164  /**
165   * Sets session property value, storing a copy of the value.
166   *
167   * @param self ESR_SessionType handle
168   * @param name Property name
169   * @param value Property value
170   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
171   */
172  ESR_ReturnCode(*setFloat)(struct ESR_SessionType_t* self, const LCHAR* name, float value);
173  /**
174   * Sets session property value, storing a copy of the value.
175   *
176   * @param self ESR_SessionType handle
177   * @param name Property name
178   * @param value Property value
179   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
180   */
181  ESR_ReturnCode(*setBool)(struct ESR_SessionType_t* self, const LCHAR* name, ESR_BOOL value);
182  /**
183   * Sets session property value, storing a copy of the value.
184   *
185   * @param self ESR_SessionType handle
186   * @param name Property name
187   * @param value Property value
188   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
189   */
190  ESR_ReturnCode(*setLCHAR)(struct ESR_SessionType_t* self, const LCHAR* name, LCHAR* value);
191  /**
192   * If the key does not exist in the session, calls SessionSetInt().
193   *
194   * This helper function aids implementation of "default values", overwriting
195   * session values only if they have not been set already.
196   *
197   * @param self ESR_SessionType handle
198   * @param name Property name
199   * @param value Property value
200   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
201   */
202  ESR_ReturnCode(*setIntIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, int value);
203  /**
204   * If the key does not exist in the session, calls SessionSetUint16_t().
205   *
206   * This helper function aids implementation of "default values", overwriting
207   * session values only if they have not been set already.
208   *
209   * @param name Property name
210   * @param value Property value
211   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
212   */
213  ESR_ReturnCode(*setUint16_tIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, asr_uint16_t value);
214  /**
215   * If the key does not exist in the session, calls SessionSetSize_t().
216   *
217   * This helper function aids implementation of "default values", overwriting
218   * session values only if they have not been set already.
219   *
220   * @param self ESR_SessionType handle
221   * @param name Property name
222   * @param value Property value
223   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
224   */
225  ESR_ReturnCode(*setSize_tIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, size_t value);
226  /**
227   * If the key does not exist in the session, calls SessionSetFloat().
228   *
229   * This helper function aids implementation of "default values", overwriting
230   * session values only if they have not been set already.
231   *
232   * @param self ESR_SessionType handle
233   * @param name Property name
234   * @param value Property value
235   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
236   */
237  ESR_ReturnCode(*setFloatIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, float value);
238  /**
239   * If the key does not exist in the session, calls SessionSetBool().
240   *
241   * This helper function aids implementation of "default values", overwriting
242   * session values only if they have not been set already.
243   *
244   * @param self ESR_SessionType handle
245   * @param name Property name
246   * @param value Property value
247   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
248   */
249  ESR_ReturnCode(*setBoolIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, ESR_BOOL value);
250  /**
251   * If the key does not exist in the session, calls SessionSetLCHAR().
252   *
253   * This helper function aids implementation of "default values", overwriting
254   * session values only if they have not been set already.
255   *
256   * @param self ESR_SessionType handle
257   * @param name Property name
258   * @param value Property value
259   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
260   */
261  ESR_ReturnCode(*setLCHARIfEmpty)(struct ESR_SessionType_t* self, const LCHAR* name, LCHAR* value);
262  /**
263   * Removes property from session.
264   *
265   * @param self ESR_SessionType handle
266   * @param name Property name
267   * @return ESR_INVALID_ARGUMENT if self is null; ESR_NO_MATCH_ERROR if key cannot be found
268   */
269  ESR_ReturnCode(*removeProperty)(struct ESR_SessionType_t* self, const LCHAR* name);
270  /**
271   * Removes and deallocates property from session.
272   *
273   * @param self ESR_SessionType handle
274   * @param name Property name
275   * @return ESR_INVALID_ARGUMENT if self is null; ESR_NO_MATCH_ERROR if key cannot be found
276   */
277  ESR_ReturnCode(*removeAndFreeProperty)(struct ESR_SessionType_t* self, const LCHAR* name);
278  /**
279   * Imports commandline arguments into the system session.
280   *
281   * Keys are imported as "cmdline.[name]" where [name] is the name of the command-line argument
282   * Values are set in char* format.
283   *
284   * For example, given the argument "-timer=5", the following key will be added to the session:
285   * ["cmdline.timer", "5"]
286   *
287   * Validation is left up to the application.
288   *
289   * If the session contains a key that is clobbered by the parser, the old [key, value]
290   * pair will be deallocated. For example, if the session contained
291   * ["cmdline.timer", "value"] before the aforementioned example occured, then the old
292   * [key, value] pair will be allocated by the parser.
293   *
294   * @param self ESR_SessionType handle
295   * @param argc Number of arguments
296   * @param argv Argument values
297   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if the system is out of memory;
298   */
299  ESR_ReturnCode(*importCommandLine)(struct ESR_SessionType_t* self, int argc, char* argv[]);
300  /**
301   * Returns the number of elements in the session.
302   *
303   * @param self ESR_SessionType handle
304   * @param size [out] Session size
305   * @return ESR_INVALID_ARGUMENT if self is null
306   */
307  ESR_ReturnCode(*getSize)(struct ESR_SessionType_t* self, size_t* size);
308  /**
309   * Returns the key associated with the specified index.
310   *
311   * @param self ESR_SessionType handle
312   * @param index Element index
313   * @param key [out] Key name
314   * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
315   */
316  ESR_ReturnCode(*getKeyAtIndex)(struct ESR_SessionType_t* self, size_t index, LCHAR** key);
317  /**
318   * Convert the specified argument to int.
319   *
320   * @param self ESR_SessionType handle
321   * @param key Property name
322   * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
323   * ESR_INVALID_ARGUMENT if self is null or property cannot be converted to int
324   */
325  ESR_ReturnCode(*convertToInt)(struct ESR_SessionType_t* self, const LCHAR* key);
326
327  /**
328   * Convert the specified argument to asr_uint16_t.
329   *
330   * @param self ESR_SessionType handle
331   * @param key Property name
332  * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
333  * ESR_INVALID_ARGUMENT if self is null or property cannot be converted to asr_uint16_t
334   */
335  ESR_ReturnCode(*convertToUint16_t)(struct ESR_SessionType_t* self, const LCHAR* key);
336
337  /**
338   * Convert the specified argument to size_t.
339   *
340   * @param self ESR_SessionType handle
341   * @param key Property name
342  * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
343  * ESR_INVALID_ARGUMENT if self is null or property cannot be converted to size_t
344   */
345  ESR_ReturnCode(*convertToSize_t)(struct ESR_SessionType_t* self, const LCHAR* key);
346
347  /**
348   * Convert the specified argument to float.
349   *
350   * @param self ESR_SessionType handle
351   * @param key Property name
352  * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
353  * ESR_INVALID_ARGUMENT if self is null or property cannot be converted to float
354   */
355  ESR_ReturnCode(*convertToFloat)(struct ESR_SessionType_t* self, const LCHAR* key);
356
357  /**
358   * Convert the specified argument to bool.
359   *
360   * @param self ESR_SessionType handle
361   * @param key Property name
362   * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
363   * ESR_INVALID_ARGUMENT if self is null or property cannot be converted to bool
364   */
365  ESR_ReturnCode(*convertToBool)(struct ESR_SessionType_t* self, const LCHAR* key);
366  /**
367   * Destroys the Session.
368   *
369   * @param self ESR_SessionType handle
370   * @return ESR_INVALID_ARGUMENT if self is null
371   */
372  ESR_ReturnCode(*destroy)(struct ESR_SessionType_t* self);
373  /**
374   * Import PAR file into session.
375   *
376   * @param self ESR_SessionType handle
377   * @param file File to read session from
378   * @return ESR_INVALID_STATE if self is null; ESR_OPEN_ERROR if file cannot be opened; ESR_READ_ERROR if file cannot be
379  * read; ESR_OUT_OF_MEMORY if system is out of memory
380   */
381  ESR_ReturnCode(*importParFile)(struct ESR_SessionType_t* self, const LCHAR* filename);
382  /**
383   * Import ARG file into session.
384   *
385   * @param self ESR_SessionType handle
386   * @param file File to read arguments from
387   */
388  ESR_ReturnCode(*importArgFile)(struct ESR_SessionType_t* self, const LCHAR* filename);
389
390  /**
391   * Adds an event-listener.
392   *
393   * @param self ESR_SessionType handle
394   * @param listener The event-listener to add
395    * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
396   */
397  ESR_ReturnCode(*addListener)(struct ESR_SessionType_t* self, ESR_SessionTypeListenerPair* listener);
398
399  /**
400   * Removes an event-listener.
401   *
402   * @param self ESR_SessionType handle
403   * @param listener The event-listener to remove
404    * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
405   */
406  ESR_ReturnCode(*removeListener)(struct ESR_SessionType_t* self, ESR_SessionTypeListenerPair* listener);
407
408  /**
409   * Pointer to session data.
410   */
411  void* data;
412}
413ESR_SessionType;
414
415/**
416 * Initializes the system session.
417 *
418 * @param self ESR_SessionType handle
419 * @return ESR_OUT_OF_MEMORY if system is out of memory
420 */
421ESR_SHARED_API ESR_ReturnCode ESR_SessionTypeCreate(ESR_SessionType** self);
422/**
423 * @}
424 */
425
426
427#endif /* __ESR_SESSIONTYPE_H */
428