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 */ 41 typedef 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 } 319 ESR_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 */ 328 ESR_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 */ 337 ESR_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 */ 346 ESR_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 */ 354 ESR_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 */ 362 ESR_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 */ 370 ESR_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 */ 378 ESR_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 */ 388 ESR_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 */ 396 ESR_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 */ 405 ESR_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 */ 414 ESR_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 */ 422 ESR_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 */ 430 ESR_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 */ 438 ESR_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 */ 446 ESR_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 */ 454 ESR_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 */ 462 ESR_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 */ 470 ESR_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 */ 478 ESR_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 */ 486 ESR_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 */ 494 ESR_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 */ 502 ESR_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 */ 509 ESR_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 */ 516 ESR_SHARED_API ESR_ReturnCode ESR_SessionRemoveAndFreeProperty(const LCHAR* name); 517 /** 518 * Destroys the system session. 519 * 520 * @return ESR_SUCCESS 521 */ 522 ESR_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 */ 543 ESR_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 */ 551 ESR_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 */ 560 ESR_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 */ 569 ESR_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 */ 578 ESR_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 */ 587 ESR_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 */ 596 ESR_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 */ 605 ESR_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 */ 613 ESR_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 */ 621 ESR_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 */ 628 ESR_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 */ 639 ESR_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 */ 647 ESR_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 */ 656 ESR_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