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