1 /*---------------------------------------------------------------------------* 2 * SR_EventLog.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_EventLog_H 21 #define __SR_EventLog_H 22 23 24 25 #include "SR_EventLogPrefix.h" 26 #include "ptypes.h" 27 #include "ESR_ReturnCode.h" 28 29 30 /** 31 * @addtogroup SR_EventLogModule SR_EventLog API functions 32 * Provides OSI logging. 33 * 34 * @{ 35 */ 36 37 /** 38 * OSI Event Log levels 39 */ 40 41 /** 42 * Basic logging level. 43 */ 44 #define OSI_LOG_LEVEL_BASIC 0x01 45 /** 46 * Log audio data. 47 */ 48 #define OSI_LOG_LEVEL_AUDIO 0x02 49 /** 50 * Log ADDWORD commands. 51 */ 52 #define OSI_LOG_LEVEL_ADDWD 0x04 53 54 /** 55 * Log a string token using the basic logging level. 56 */ 57 #define SR_EventLogToken_BASIC(log, loglevel, tokenName, value) \ 58 ((loglevel & OSI_LOG_LEVEL_BASIC) ? \ 59 log->token(log, tokenName, value) : ESR_SUCCESS ) \ 60 61 /** 62 * Log an integer token using the basic logging level. 63 */ 64 #define SR_EventLogTokenInt_BASIC(log, loglevel, tokenName, value) \ 65 ((loglevel & OSI_LOG_LEVEL_BASIC) ? \ 66 log->tokenInt(log, tokenName, value) : ESR_SUCCESS ) \ 67 68 /** 69 * Log a pointer token using the basic logging level. 70 */ 71 #define SR_EventLogTokenPointer_BASIC(log, loglevel, tokenName, value) \ 72 ((loglevel & OSI_LOG_LEVEL_BASIC) ? \ 73 log->tokenPointer(log, tokenName, value) : ESR_SUCCESS ) \ 74 75 /** 76 * Log a uint16 token using the basic logging level. 77 */ 78 #define SR_EventLogTokenUint16_t_BASIC(log, loglevel, tokenName, value) \ 79 ((loglevel & OSI_LOG_LEVEL_BASIC) ? \ 80 log->tokenUint16_t(log, tokenName, value) : ESR_SUCCESS ) \ 81 82 /** 83 * Log a size_t token using the basic logging level. 84 */ 85 #define SR_EventLogTokenSize_t_BASIC(log, loglevel, tokenName, value) \ 86 ((loglevel & OSI_LOG_LEVEL_BASIC) ? \ 87 log->tokenSize_t(log, tokenName, value) : ESR_SUCCESS ) \ 88 89 /** 90 * Log a boolean token using the basic logging level. 91 */ 92 #define SR_EventLogTokenBool_BASIC(log, loglevel, tokenName, value) \ 93 ((loglevel & OSI_LOG_LEVEL_BASIC) ? \ 94 log->tokenBool(log, tokenName, value) : ESR_SUCCESS ) \ 95 96 /** 97 * Log a float token using the basic logging level. 98 */ 99 #define SR_EventLogTokenFloat_BASIC(log, loglevel, tokenName, value) \ 100 ((loglevel & OSI_LOG_LEVEL_BASIC) ? \ 101 log->tokenFloat(log, tokenName, value) : ESR_SUCCESS ) \ 102 103 /** 104 * Log an event using the basic logging level. 105 */ 106 #define SR_EventLogEvent_BASIC(log, loglevel, eventName) \ 107 ((loglevel & OSI_LOG_LEVEL_BASIC) ? \ 108 log->event(log, eventName) : ESR_SUCCESS ) \ 109 110 /** 111 * Log a string token using the audio logging level. 112 */ 113 #define SR_EventLogToken_AUDIO(log, loglevel, tokenName, value) \ 114 ((loglevel & OSI_LOG_LEVEL_AUDIO) ? \ 115 log->token(log, tokenName, value) : ESR_SUCCESS ) \ 116 117 /** 118 * Log an integer token using the audio logging level. 119 */ 120 #define SR_EventLogTokenInt_AUDIO(log, loglevel, tokenName, value) \ 121 ((loglevel & OSI_LOG_LEVEL_AUDIO) ? \ 122 log->tokenInt(log, tokenName, value) : ESR_SUCCESS ) \ 123 124 /** 125 * Log an event using the audio logging level. 126 */ 127 #define SR_EventLogEvent_AUDIO(log, loglevel, eventName) \ 128 ((loglevel & OSI_LOG_LEVEL_AUDIO) ? \ 129 log->event(log, eventName) : ESR_SUCCESS ) \ 130 131 /** 132 * Represents a EventLog. 133 */ 134 typedef struct SR_EventLog_t 135 { 136 /** 137 * Destroys a EventLog. 138 * 139 * @param self EventLog handle 140 */ 141 ESR_ReturnCode(*destroy)(struct SR_EventLog_t* self); 142 143 /** 144 * Logs an OSI log token. 145 * 146 * @param self SR_EventLog handle 147 * @param token Token name 148 * @param value Token value 149 */ 150 ESR_ReturnCode(*token)(struct SR_EventLog_t* self, const LCHAR* token, const LCHAR *value); 151 152 /** 153 * Logs an OSI log token. 154 * 155 * @param self SR_EventLog handle 156 * @param token Token name 157 * @param value Token value 158 */ 159 ESR_ReturnCode(*tokenInt)(struct SR_EventLog_t* self, const LCHAR* token, int value); 160 161 /** 162 * Logs an OSI log token. 163 * 164 * @param self SR_EventLog handle 165 * @param token Token name 166 * @param value Token value 167 */ 168 ESR_ReturnCode(*tokenPointer)(struct SR_EventLog_t* self, const LCHAR* token, void* value); 169 170 /** 171 * Logs an OSI log token. 172 * 173 * @param self SR_EventLog handle 174 * @param token Token name 175 * @param value Token value 176 */ 177 ESR_ReturnCode(*tokenUint16_t)(struct SR_EventLog_t* self, const LCHAR* token, asr_uint16_t value); 178 179 /** 180 * Logs an OSI log token. 181 * 182 * @param self SR_EventLog handle 183 * @param token Token name 184 * @param value Token value 185 */ 186 ESR_ReturnCode(*tokenSize_t)(struct SR_EventLog_t* self, const LCHAR* token, size_t value); 187 188 /** 189 * Logs an OSI log token. 190 * 191 * @param self SR_EventLog handle 192 * @param token Token name 193 * @param value Token value 194 */ 195 ESR_ReturnCode(*tokenBool)(struct SR_EventLog_t* self, const LCHAR* token, ESR_BOOL value); 196 197 /** 198 * Logs an OSI log token. 199 * 200 * @param self SR_EventLog handle 201 * @param token Token name 202 * @param value Token value 203 */ 204 ESR_ReturnCode(*tokenFloat)(struct SR_EventLog_t* self, const LCHAR* token, float value); 205 206 /** 207 * Commits all previously accumulated log tokens. 208 * 209 * @param self SR_EventLog handle 210 * @param eventName Name of the event associated with the tokens 211 */ 212 ESR_ReturnCode(*event)(struct SR_EventLog_t* self, const LCHAR* eventName); 213 214 215 /** 216 * Log the contents of the ESR_Session. 217 * 218 * @param self SR_EventLog handle 219 */ 220 ESR_ReturnCode(*eventSession)(struct SR_EventLog_t* self); 221 222 /** 223 * Opens a new file for recording a waveform of audio. Filename is automatically generated. Opened file 224 * becomes the current one where data is written to until closed. 225 * 226 * @param self SR_EventLog handle 227 * @param audio_type String identifying type of audio e.g. L("audio/L16") 228 * @param sample_rate Sampling rate 229 * @param sample_size Size of sampling in bytes. 230 */ 231 ESR_ReturnCode(*audioOpen)(struct SR_EventLog_t* self, const LCHAR* audio_type, size_t sample_rate, size_t sample_size); 232 233 /** 234 * Closes the current file. 235 * 236 * @param self SR_EventLog handle 237 * @param eventName Name of the event associated with the tokens 238 */ 239 ESR_ReturnCode(*audioClose)(struct SR_EventLog_t* self); 240 241 /** 242 * Writes datat to the current audio file. 243 * 244 * @param self SR_EventLog handle 245 * @param buffer Buffer holding the data to write 246 * @param num_bytes The number of bytes in the buffer. 247 */ 248 ESR_ReturnCode(*audioWrite)(struct SR_EventLog_t* self, void* buffer, size_t num_bytes); 249 250 /** 251 * Returns the filename of the current audio file used for logging. 252 * 253 * @param self SR_EventLog handle 254 * @param waveformFilename Name of the current audio file. 255 * @param len Length of buffer. 256 */ 257 ESR_ReturnCode(*audioGetFilename)(struct SR_EventLog_t* self, LCHAR* waveformFilename, size_t* len); 258 } 259 SR_EventLog; 260 261 /** 262 * Create a new EventLog 263 * 264 * @param self EventLog handle 265 */ 266 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogCreate(SR_EventLog** self); 267 268 /** 269 * Destroys a EventLog. 270 * 271 * @param self EventLog handle 272 */ 273 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogDestroy(SR_EventLog* self); 274 275 /** 276 * Logs an OSI log token. 277 * 278 * @param self SR_EventLog handle 279 * @param token Token name 280 * @param value Token value 281 */ 282 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogToken(SR_EventLog* self, const LCHAR* token, const LCHAR *value); 283 284 /** 285 * Logs an OSI log token. 286 * 287 * @param self SR_EventLog handle 288 * @param token Token name 289 * @param value Token value 290 */ 291 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogTokenInt(SR_EventLog* self, const LCHAR* token, int value); 292 293 /** 294 * Logs an OSI log token. 295 * 296 * @param self SR_EventLog handle 297 * @param token Token name 298 * @param value Token value 299 */ 300 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogTokenPointer(SR_EventLog* self, const LCHAR* token, void* value); 301 302 /** 303 * Logs an OSI log token. 304 * 305 * @param self SR_EventLog handle 306 * @param token Token name 307 * @param value Token value 308 */ 309 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogTokenUint16_t(SR_EventLog* self, const LCHAR* token, asr_uint16_t value); 310 311 /** 312 * Logs an OSI log token. 313 * 314 * @param self SR_EventLog handle 315 * @param token Token name 316 * @param value Token value 317 */ 318 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogTokenSize_t(SR_EventLog* self, const LCHAR* token, size_t value); 319 320 /** 321 * Logs an OSI log token. 322 * 323 * @param self SR_EventLog handle 324 * @param token Token name 325 * @param value Token value 326 */ 327 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogTokenBool(SR_EventLog* self, const LCHAR* token, ESR_BOOL value); 328 329 /** 330 * Logs an OSI log token. 331 * 332 * @param self SR_EventLog handle 333 * @param token Token name 334 * @param value Token value 335 */ 336 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogTokenFloat(SR_EventLog* self, const LCHAR* token, float value); 337 338 /** 339 * Log the contents of the ESR_Session. 340 * 341 * @param self SR_EventLog handle 342 */ 343 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogEventSession(SR_EventLog* self); 344 345 /** 346 * Commits all previously accumulated log tokens. 347 * 348 * @param self SR_EventLog handle 349 * @param eventName Name of the event associated with the tokens 350 */ 351 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogEvent(SR_EventLog* self, const LCHAR* eventName); 352 353 /** 354 * Opens a new file for recording a waveform of audio. Filename is automatically generated. Opened file 355 * becomes the current one where data is written to until closed. 356 * 357 * @param self SR_EventLog handle 358 * @param audio_type String identifying type of audio e.g. L("audio/L16") 359 * @param sample_rate Sampling rate 360 * @param sample_size Size of sampling in bytes. 361 */ 362 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogAudioOpen(SR_EventLog* self, const LCHAR* audio_type, size_t sample_rate, size_t sample_size); 363 364 /** 365 * Closes the current file. 366 * 367 * @param self SR_EventLog handle 368 */ 369 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogAudioClose(SR_EventLog* self); 370 371 /** 372 * Writes datat to the current audio file. 373 * 374 * @param self SR_EventLog handle 375 * @param buffer Buffer holding the data to write 376 * @param num_bytes The number of bytes in the buffer. 377 */ 378 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogAudioWrite(SR_EventLog* self, void* buffer, size_t num_bytes); 379 380 /** 381 * Returns the filename of the current audio file used for logging. 382 * 383 * @param self SR_EventLog handle 384 * @param waveformFilename Name of the current audio file. 385 * @param len Length of buffer. 386 */ 387 SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogAudioGetFilename(SR_EventLog* self, LCHAR* waveformFilename, size_t* len); 388 389 /** 390 * @} 391 */ 392 393 394 #endif /* __SR_EventLog_H */ 395
