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 */
134typedef 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}
259SR_EventLog;
260
261/**
262 * Create a new EventLog
263 *
264 * @param self EventLog handle
265 */
266SREC_EVENTLOG_API ESR_ReturnCode SR_EventLogCreate(SR_EventLog** self);
267
268/**
269 * Destroys a EventLog.
270 *
271 * @param self EventLog handle
272 */
273SREC_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 */
282SREC_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 */
291SREC_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 */
300SREC_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 */
309SREC_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 */
318SREC_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 */
327SREC_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 */
336SREC_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 */
343SREC_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 */
351SREC_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 */
362SREC_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 */
369SREC_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 */
378SREC_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 */
387SREC_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