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 */ 42 typedef 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 } 413 ESR_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 */ 421 ESR_SHARED_API ESR_ReturnCode ESR_SessionTypeCreate(ESR_SessionType** self); 422 /** 423 * @} 424 */ 425 426 427 #endif /* __ESR_SESSIONTYPE_H */ 428
