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