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 */ 127typedef 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} 243SR_EventLog; 244 245/** 246 * Create a new EventLog 247 * 248 * @param self EventLog handle 249 */ 250SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogCreate(SR_EventLog** self); 251 252/** 253 * Destroys a EventLog. 254 * 255 * @param self EventLog handle 256 */ 257SREC_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 */ 266SREC_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 */ 275SREC_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 */ 284SREC_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 */ 293SREC_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 */ 302SREC_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 */ 311SREC_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 */ 318SREC_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 */ 326SREC_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 */ 337SREC_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 */ 344SREC_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 */ 353SREC_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 */ 362SREC_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