1/*---------------------------------------------------------------------------*
2 *  ESR_Session.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_SESSION_H
21#define __ESR_SESSION_H
22
23
24
25#include "ESR_ReturnCode.h"
26#include "ESR_SharedPrefix.h"
27#include "pstdio.h"
28#include "ptypes.h"
29#include "ESR_SessionType.h"
30
31/**
32 * @addtogroup ESR_SessionModule ESR_Session API functions
33 * Manages ESR session information.
34 *
35 * @{
36 */
37
38/**
39 * Hashmap with helper functions for adding primitives and add-if-empty.
40 */
41typedef struct ESR_SessionSingleton_t
42{
43  /**
44   * Returns session property value.
45   *
46   * @param name Property name
47   * @param value Property value
48   * @param type Expected variable type (for strong-typing purposes)
49   */
50  ESR_ReturnCode(*getProperty)(const LCHAR* name, void** value, VariableTypes type);
51  /**
52   * Returns the type of a property value.
53   *
54   * @param name Property name
55   * @param type [out] Value type
56   */
57  ESR_ReturnCode(*getPropertyType)(const LCHAR* name, VariableTypes* type);
58  /**
59   * Returns copy of session property value.
60   *
61   * @param name Property name
62   * @param value Property value
63   */
64  ESR_ReturnCode(*getInt)(const LCHAR* name, int* value);
65  /**
66   * Returns copy of session property value.
67   *
68   * @param name Property name
69   * @param value Property value
70   */
71  ESR_ReturnCode(*getUint16_t)(const LCHAR* name, asr_uint16_t* value);
72  /**
73   * Returns copy of session property value.
74   *
75   * @param name Property name
76   * @param value Property value
77   */
78  ESR_ReturnCode(*getSize_t)(const LCHAR* name, size_t* value);
79  /**
80   * Returns copy of session property value.
81   *
82   * @param name Property name
83   * @param value Property value
84   */
85  ESR_ReturnCode(*getFloat)(const LCHAR* name, float* value);
86  /**
87   * Returns copy of session property value.
88   *
89   * @param name Property name
90   * @param value Property value
91   */
92  ESR_ReturnCode(*getBool)(const LCHAR* name, ESR_BOOL* value);
93  /**
94   * Returns copy of session property value.
95   *
96   * @param name Property name
97   * @param value Property value
98   * @param len Length of value argument. If the return code is ESR_BUFFER_OVERFLOW,
99   *            the required length is returned in this variable.
100   */
101  ESR_ReturnCode(*getLCHAR)(const LCHAR* name, LCHAR* value, size_t* len);
102  /**
103   * Indicates if key exists in the session.
104   *
105   * @param name Property name
106   * @param exists True if key exists, false otherwise
107   */
108  ESR_ReturnCode(*contains)(const LCHAR* name, ESR_BOOL* exists);
109  /**
110   * Sets session property value.
111   *
112   * @param name Property name
113   * @param value Property value
114   * @param type Type of value being set
115   */
116  ESR_ReturnCode(*setProperty)(const LCHAR* name, void* value, VariableTypes type);
117  /**
118   * Sets session property value, storing a copy of the value.
119   *
120   * @param name Property name
121   * @param value Property value
122   */
123  ESR_ReturnCode(*setInt)(const LCHAR* name, int value);
124  /**
125   * Sets session property value, storing a copy of the value.
126   *
127   * @param name Property name
128   * @param value Property value
129   */
130  ESR_ReturnCode(*setUint16_t)(const LCHAR* name, asr_uint16_t value);
131  /**
132   * Sets session property value, storing a copy of the value.
133   *
134   * @param name Property name
135   * @param value Property value
136   */
137  ESR_ReturnCode(*setSize_t)(const LCHAR* name, size_t value);
138  /**
139   * Sets session property value, storing a copy of the value.
140   *
141   * @param name Property name
142   * @param value Property value
143   */
144  ESR_ReturnCode(*setFloat)(const LCHAR* name, float value);
145  /**
146   * Sets session property value, storing a copy of the value.
147   *
148   * @param name Property name
149   * @param value Property value
150   */
151  ESR_ReturnCode(*setBool)(const LCHAR* name, ESR_BOOL value);
152  /**
153   * Sets session property value, storing a copy of the value.
154   *
155   * @param name Property name
156   * @param value Property value
157   */
158  ESR_ReturnCode(*setLCHAR)(const LCHAR* name, LCHAR* value);
159  /**
160   * If the key does not exist in the session, calls SessionSetInt().
161   *
162   * This helper function aids implementation of "default values", overwriting
163   * session values only if they have not been set already.
164   *
165   * @param name Property name
166   * @param value Property value
167   */
168  ESR_ReturnCode(*setIntIfEmpty)(const LCHAR* name, int value);
169  /**
170   * If the key does not exist in the session, calls SessionSetUint16_t().
171   *
172   * This helper function aids implementation of "default values", overwriting
173   * session values only if they have not been set already.
174   *
175   * @param name Property name
176   * @param value Property value
177   */
178  ESR_ReturnCode(*setUint16_tIfEmpty)(const LCHAR* name, asr_uint16_t value);
179  /**
180   * If the key does not exist in the session, calls SessionSetSize_t().
181   *
182   * This helper function aids implementation of "default values", overwriting
183   * session values only if they have not been set already.
184   *
185   * @param name Property name
186   * @param value Property value
187   */
188  ESR_ReturnCode(*setSize_tIfEmpty)(const LCHAR* name, size_t value);
189  /**
190   * If the key does not exist in the session, calls SessionSetFloat().
191   *
192   * This helper function aids implementation of "default values", overwriting
193   * session values only if they have not been set already.
194   *
195   * @param name Property name
196   * @param value Property value
197   */
198  ESR_ReturnCode(*setFloatIfEmpty)(const LCHAR* name, float value);
199  /**
200   * If the key does not exist in the session, calls SessionSetBool().
201   *
202   * This helper function aids implementation of "default values", overwriting
203   * session values only if they have not been set already.
204   *
205   * @param name Property name
206   * @param value Property value
207   */
208  ESR_ReturnCode(*setBoolIfEmpty)(const LCHAR* name, ESR_BOOL value);
209  /**
210   * If the key does not exist in the session, calls SessionSetLCHAR().
211   *
212   * This helper function aids implementation of "default values", overwriting
213   * session values only if they have not been set already.
214   *
215   * @param name Property name
216   * @param value Property value
217   */
218  ESR_ReturnCode(*setLCHARIfEmpty)(const LCHAR* name, LCHAR* value);
219  /**
220   * Removes property from session.
221   *
222   * @param name Property name
223   */
224  ESR_ReturnCode(*removeProperty)(const LCHAR* name);
225  /**
226   * Removes and deallocates property from session.
227   *
228   * @param name Property name
229   */
230  ESR_ReturnCode(*removeAndFreeProperty)(const LCHAR* name);
231  /**
232   * Imports commandline arguments into the system session.
233   *
234   * Keys are imported as "cmdline.[name]" where [name] is the name of the command-line argument
235   * Values are set in char* format.
236   *
237   * For example, given the argument "-timer=5", the following key will be added to the session:
238   * ["cmdline.timer", "5"]
239   *
240   * Validation is left up to the application.
241   *
242   * If the session contains a key that is clobbered by the parser, the old [key, value]
243   * pair will be deallocated. For example, if the session contained
244   * ["cmdline.timer", "value"] before the aforementioned example occured, then the old
245   * [key, value] pair will be allocated by the parser.
246   *
247   * @param argc Number of arguments
248   * @param argv Argument values
249   */
250  ESR_ReturnCode(*importCommandLine)(int argc, char* argv[]);
251  /**
252   * Returns the number of elements in the session.
253   *
254   * @param size [out] Session size
255   */
256  ESR_ReturnCode(*getSize)(size_t* size);
257  /**
258   * Returns the key associated with the specified index.
259   *
260   * @param index Element index
261   * @param key [out] Key name
262   */
263  ESR_ReturnCode(*getKeyAtIndex)(size_t index, LCHAR** key);
264  /**
265   * Convert the specified argument to int.
266   *
267   * @param key Property name
268   */
269  ESR_ReturnCode(*convertToInt)(const LCHAR* key);
270  /**
271   * Convert the specified argument to asr_uint16_t.
272   *
273   * @param key Property name
274   */
275  ESR_ReturnCode(*convertToUint16_t)(const LCHAR* key);
276
277  /**
278   * Convert the specified argument to size_t.
279   *
280   * @param key Property name
281   */
282  ESR_ReturnCode(*convertToSize_t)(const LCHAR* key);
283
284  /**
285   * Convert the specified argument to float.
286   *
287   * @param key Property name
288   */
289  ESR_ReturnCode(*convertToFloat)(const LCHAR* key);
290
291  /**
292   * Convert the specified argument to bool.
293   *
294   * @param key Property name
295   */
296  ESR_ReturnCode(*convertToBool)(const LCHAR* key);
297  /**
298   * Destroys the system session.
299   */
300  ESR_ReturnCode(*destroy)(void);
301  /**
302   * Import PAR file into session.
303   *
304   * @param file File to read session from
305   */
306  ESR_ReturnCode(*importParFile)(const LCHAR* filename);
307  /**
308   * Import ARG file into session.
309   *
310   * @param file File to read arguments from
311   */
312  ESR_ReturnCode(*importArgFile)(const LCHAR* filename);
313
314  /**
315   * Pointer to session data.
316   */
317  void* data;
318}
319ESR_SessionSingleton;
320
321/**
322 * Initializes the system session.
323 *
324 * @param filename File to read session information from
325 * @return ESR_OPEN_ERROR if file cannot be opened; ESR_READ_ERROR if file cannot be read;
326 * ESR_OUT_OF_MEMORY if system is out of memory
327 */
328ESR_SHARED_API ESR_ReturnCode ESR_SessionCreate(const LCHAR* filename);
329/**
330 * Returns session property value.
331 *
332 * @param name Property name
333 * @param value Property value
334 * @param type Expected variable type (for strong-typing purposes)
335 * @return ESR_INVALID_RESULT_TYPE if the property is not of the specified type
336 */
337ESR_SHARED_API ESR_ReturnCode ESR_SessionGetProperty(const LCHAR* name, void** value,
338    VariableTypes type);
339/**
340 * Returns copy of session property value.
341 *
342 * @param name Property name
343 * @param value Property value
344 * @return ESR_INVALID_RESULT_TYPE if the property is not an int
345 */
346ESR_SHARED_API ESR_ReturnCode ESR_SessionGetInt(const LCHAR* name, int* value);
347/**
348 * Returns copy of session property value.
349 *
350 * @param name Property name
351 * @param value Property value
352 * @return ESR_INVALID_RESULT_TYPE if the property is not a asr_uint16_t
353 */
354ESR_SHARED_API ESR_ReturnCode ESR_SessionGetUint16_t(const LCHAR* name, asr_uint16_t* value);
355/**
356 * Returns copy of session property value.
357 *
358 * @param name Property name
359 * @param value Property value
360 * @return ESR_INVALID_RESULT_TYPE if the property is not a size_t
361 */
362ESR_SHARED_API ESR_ReturnCode ESR_SessionGetSize_t(const LCHAR* name, size_t* value);
363/**
364 * Returns copy of session property value.
365 *
366 * @param name Property name
367 * @param value Property value
368 * @return ESR_INVALID_RESULT_TYPE if the property is not a float
369 */
370ESR_SHARED_API ESR_ReturnCode ESR_SessionGetFloat(const LCHAR* name, float* value);
371/**
372 * Returns copy of session property value.
373 *
374 * @param name Property name
375 * @param value Property value
376 * @return ESR_INVALID_RESULT_TYPE if the property is not a bool
377 */
378ESR_SHARED_API ESR_ReturnCode ESR_SessionGetBool(const LCHAR* name, ESR_BOOL* value);
379/**
380 * Returns copy of session property value.
381 *
382 * @param name Property name
383 * @param value Property value
384 * @param len Length of value argument. If the return code is ESR_BUFFER_OVERFLOW,
385 *            the required length is returned in this variable.
386 * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*
387 */
388ESR_SHARED_API ESR_ReturnCode ESR_SessionGetLCHAR(const LCHAR* name, LCHAR* value, size_t* len);
389/**
390 * Indicates if key exists in the session.
391 *
392 * @param name Property name
393 * @param exists True if key exists, false otherwise
394 * @return ESR_SUCCESS
395 */
396ESR_SHARED_API ESR_ReturnCode ESR_SessionContains(const LCHAR* name, ESR_BOOL* exists);
397/**
398 * Sets session property value.
399 *
400 * @param name Property name
401 * @param value Property value
402 * @param type Type of value being set
403 * @return ESR_OUT_OF_MEMORY if system is out of memory
404 */
405ESR_SHARED_API ESR_ReturnCode ESR_SessionSetProperty(const LCHAR* name, void* value,
406    VariableTypes type);
407/**
408 * Sets session property value, storing a copy of the value.
409 *
410 * @param name Property name
411 * @param value Property value
412 * @return ESR_OUT_OF_MEMORY if system is out of memory
413 */
414ESR_SHARED_API ESR_ReturnCode ESR_SessionSetInt(const LCHAR* name, int value);
415/**
416 * Sets session property value, storing a copy of the value.
417 *
418 * @param name Property name
419 * @param value Property value
420 * @return ESR_OUT_OF_MEMORY if system is out of memory
421 */
422ESR_SHARED_API ESR_ReturnCode ESR_SessionSetUint16_t(const LCHAR* name, asr_uint16_t value);
423/**
424 * Sets session property value, storing a copy of the value.
425 *
426 * @param name Property name
427 * @param value Property value
428 * @return ESR_OUT_OF_MEMORY if system is out of memory
429 */
430ESR_SHARED_API ESR_ReturnCode ESR_SessionSetSize_t(const LCHAR* name, size_t value);
431/**
432 * Sets session property value, storing a copy of the value.
433 *
434 * @param name Property name
435 * @param value Property value
436 * @return ESR_OUT_OF_MEMORY if system is out of memory
437 */
438ESR_SHARED_API ESR_ReturnCode ESR_SessionSetFloat(const LCHAR* name, float value);
439/**
440 * Sets session property value, storing a copy of the value.
441 *
442 * @param name Property name
443 * @param value Property value
444 * @return ESR_OUT_OF_MEMORY if system is out of memory
445 */
446ESR_SHARED_API ESR_ReturnCode ESR_SessionSetBool(const LCHAR* name, ESR_BOOL value);
447/**
448 * Sets session property value, storing a copy of the value.
449 *
450 * @param name Property name
451 * @param value Property value
452 * @return ESR_OUT_OF_MEMORY if system is out of memory
453 */
454ESR_SHARED_API ESR_ReturnCode ESR_SessionSetLCHAR(const LCHAR* name, LCHAR* value);
455/**
456 * If the key does not exist in the session, calls SessionSetInt().
457 *
458 * @param name Property name
459 * @param value Property value
460 * @return ESR_OUT_OF_MEMORY if system is out of memory
461 */
462ESR_SHARED_API ESR_ReturnCode ESR_SessionSetIntIfEmpty(const LCHAR* name, int value);
463/**
464 * If the key does not exist in the session, calls SessionSetSize_t().
465 *
466 * @param name Property name
467 * @param value Property value
468 * @return ESR_OUT_OF_MEMORY if system is out of memory
469 */
470ESR_SHARED_API ESR_ReturnCode ESR_SessionSetUint16_tIfEmpty(const LCHAR* name, asr_uint16_t value);
471/**
472 * If the key does not exist in the session, calls SessionSetSize_t().
473 *
474 * @param name Property name
475 * @param value Property value
476 * @return ESR_OUT_OF_MEMORY if system is out of memory
477 */
478ESR_SHARED_API ESR_ReturnCode ESR_SessionSetSize_tIfEmpty(const LCHAR* name, size_t value);
479/**
480 * If the key does not exist in the session, calls SessionSetFloat().
481 *
482 * @param name Property name
483 * @param value Property value
484 * @return ESR_OUT_OF_MEMORY if system is out of memory
485 */
486ESR_SHARED_API ESR_ReturnCode ESR_SessionSetFloatIfEmpty(const LCHAR* name, float value);
487/**
488 * If the key does not exist in the session, calls SessionSetBool().
489 *
490 * @param name Property name
491 * @param value Property value
492 * @return ESR_OUT_OF_MEMORY if system is out of memory
493 */
494ESR_SHARED_API ESR_ReturnCode ESR_SessionSetBoolIfEmpty(const LCHAR* name, ESR_BOOL value);
495/**
496 * If the key does not exist in the session, calls SessionSetLCHAR().
497 *
498 * @param name Property name
499 * @param value Property value
500 * @return ESR_OUT_OF_MEMORY if system is out of memory
501 */
502ESR_SHARED_API ESR_ReturnCode ESR_SessionSetLCHARIfEmpty(const LCHAR* name, LCHAR* value);
503/**
504 * Removes property from session.
505 *
506 * @param name Property name
507 * @return ESR_OUT_OF_MEMORY if system is out of memory
508 */
509ESR_SHARED_API ESR_ReturnCode ESR_SessionRemoveProperty(const LCHAR* name);
510/**
511 * Removes and deallocates property from session.
512 *
513 * @param name Property name
514 * @return ESR_OUT_OF_MEMORY if system is out of memory
515 */
516ESR_SHARED_API ESR_ReturnCode ESR_SessionRemoveAndFreeProperty(const LCHAR* name);
517/**
518 * Destroys the system session.
519 *
520 * @return ESR_SUCCESS
521 */
522ESR_SHARED_API ESR_ReturnCode ESR_SessionDestroy(void);
523/**
524 * Imports commandline arguments into the system session.
525 *
526 * Keys are imported as "cmdline.[name]" where [name] is the name of the command-line argument
527 * Values are set in char* format.
528 *
529 * For example, given the argument "-timer=5", the following key will be added to the session:
530 * ["cmdline.timer", "5"]
531 *
532 * Validation is left up to the application.
533 *
534 * If the session contains a key that is clobbered by the parser, the old [key, value]
535 * pair will be deallocated. For example, if the session contained
536 * ["cmdline.timer", "value"] before the aforementioned example occured, then the old
537 * [key, value] pair will be allocated by the parser.
538 *
539 * @param argc Number of arguments
540 * @param argv Argument values
541 * @return ESR_OUT_OF_MEMORY if the system is out of memory
542 */
543ESR_SHARED_API ESR_ReturnCode ESR_SessionImportCommandLine(int argc, LCHAR* argv[]);
544
545/**
546 * Returns the number of elements in the session.
547 *
548 * @param size [out] Session size
549 * @return ESR_SUCCESS
550 */
551ESR_SHARED_API ESR_ReturnCode ESR_SessionGetSize(size_t* size);
552
553/**
554 * Returns the key associated with the specified index.
555 *
556 * @param index Element index
557 * @param key [out] Key name
558 * @return ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
559 */
560ESR_SHARED_API ESR_ReturnCode ESR_SessionGetKeyAtIndex(size_t index, LCHAR** key);
561
562/**
563 * Convert the specified argument to int.
564 *
565 * @param key Property name
566 * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
567 * ESR_INVALID_ARGUMENT if property cannot be converted to int
568 */
569ESR_SHARED_API ESR_ReturnCode ESR_SessionConvertToInt(const LCHAR* key);
570
571/**
572 * Convert the specified argument to int.
573 *
574 * @param key Property name
575 * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
576 * ESR_INVALID_ARGUMENT if property cannot be converted to asr_uint16_t
577 */
578ESR_SHARED_API ESR_ReturnCode ESR_SessionConvertToUint16_t(const LCHAR* key);
579
580/**
581 * Convert the specified argument to size_t.
582 *
583 * @param key Property name
584 * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
585 * ESR_INVALID_ARGUMENT if property cannot be converted to size_t
586 */
587ESR_SHARED_API ESR_ReturnCode ESR_SessionConvertToSize_t(const LCHAR* key);
588
589/**
590 * Convert the specified argument to float.
591 *
592 * @param key Property name
593 * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
594 * ESR_INVALID_ARGUMENT if property cannot be converted to float
595 */
596ESR_SHARED_API ESR_ReturnCode ESR_SessionConvertToFloat(const LCHAR* key);
597
598/**
599 * Convert the specified argument to bool.
600 *
601 * @param key Property name
602 * @return ESR_INVALID_RESULT_TYPE if the property is not a LCHAR*; ESR_OUT_OF_MEMORY if system is out of memory;
603 * ESR_INVALID_ARGUMENT if property cannot be converted to bool
604 */
605ESR_SHARED_API ESR_ReturnCode ESR_SessionConvertToBool(const LCHAR* key);
606/**
607 * Returns the type of a property value.
608 *
609 * @param name Property name
610 * @param type [out] Value type
611 * @return ESR_INVALID_ARGUMENT if property cannot be found
612 */
613ESR_SHARED_API ESR_ReturnCode ESR_SessionGetPropertyType(const LCHAR* name, VariableTypes* type);
614/**
615 * Import PAR file into session.
616 *
617 * @param filename File to read session from
618 * @return ESR_OPEN_ERROR if file cannot be opened; ESR_READ_ERROR if file cannot be read;
619 * ESR_OUT_OF_MEMORY if system is out of memory
620 */
621ESR_SHARED_API ESR_ReturnCode ESR_SessionImportParFile(const LCHAR* filename);
622/**
623 * Sets val to true if a session object exists (non-null), FALSE otherwise.
624 *
625 * @param val True if session is non-null, false otherwise
626 * @return ESR_SUCCESS
627 */
628ESR_SHARED_API ESR_ReturnCode ESR_SessionExists(ESR_BOOL* val);
629/**
630 * Prefixes relative paths with the PAR-file base directory. If the path is not relative,
631 * it is not changed.
632 *
633 * @param path Path to be prefixed
634 * @param len Length of path argument. If the return code is ESR_BUFFER_OVERFLOW,
635 *            the required length is returned in this variable.
636 * @return ESR_INVALID_ARGUMENT if path is null;
637 * ESR_NO_MATCH_ERROR if session property "parFile.baseDirectory" is undefined
638 */
639ESR_SHARED_API ESR_ReturnCode ESR_SessionPrefixWithBaseDirectory(LCHAR* path, size_t* len);
640/**
641 * Adds an event-listener.
642 *
643 * @param self ESR_SessionType handle
644 * @param listener The event-listener to add
645 * @return ESR_OUT_OF_MEMORY if system is out of memory
646 */
647ESR_SHARED_API ESR_ReturnCode ESR_SessionAddListener(ESR_SessionType* self, ESR_SessionTypeListenerPair* listener);
648
649/**
650 * Removes an event-listener.
651 *
652 * @param self ESR_SessionType handle
653 * @param listener The event-listener to remove
654 * @return ESR_SUCCESS
655 */
656ESR_SHARED_API ESR_ReturnCode ESR_SessionRemoveListener(ESR_SessionType* self, ESR_SessionTypeListenerPair* listener);
657
658
659
660/**
661 * @}
662 */
663
664
665
666#endif /* __ESR_SESSION_H */
667