tracelog.h@ 76421

Last change on this file since 76421 was 76351, checked in by vboxsync, 6 years ago
iprt/*.h: Avoid including err.h when possible. bugref:9344
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 22.3 KB

Line
1	/** @file
2	* IPRT - Binary trace log API.
3	*/
4
5	/*
6	* Copyright (C) 2018 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___iprt_tracelog_h
27	#define ___iprt_tracelog_h
28
29	#include <iprt/sg.h>
30	#include <iprt/types.h>
31
32	RT_C_DECLS_BEGIN
33
34
35	/** @defgroup grp_tracelog RTTraceLog - Binary trace log API
36	* @ingroup grp_rt
37	* @{
38	*/
39
40	/**
41	* Trace log item type.
42	*/
43	typedef enum RTTRACELOGTYPE
44	{
45	/** Invalid first value. */
46	RTTRACELOGTYPE_INVALID = 0,
47	/** Boolean item type. */
48	RTTRACELOGTYPE_BOOL,
49	/** Unsigned 8bit integer type. */
50	RTTRACELOGTYPE_UINT8,
51	/** Signed 8bit integer type. */
52	RTTRACELOGTYPE_INT8,
53	/** Unsigned 16bit integer type. */
54	RTTRACELOGTYPE_UINT16,
55	/** Signed 16bit integer type. */
56	RTTRACELOGTYPE_INT16,
57	/** Unsigned 32bit integer type. */
58	RTTRACELOGTYPE_UINT32,
59	/** Signed 32bit integer type. */
60	RTTRACELOGTYPE_INT32,
61	/** Unsigned 64bit integer type. */
62	RTTRACELOGTYPE_UINT64,
63	/** Signed 64bit integer type. */
64	RTTRACELOGTYPE_INT64,
65	/** 32bit floating point type. */
66	RTTRACELOGTYPE_FLOAT32,
67	/** 64bit floating point type. */
68	RTTRACELOGTYPE_FLOAT64,
69	/** Raw binary data type. */
70	RTTRACELOGTYPE_RAWDATA,
71	/** Pointer data type. */
72	RTTRACELOGTYPE_POINTER,
73	/** size_t data type. */
74	RTTRACELOGTYPE_SIZE,
75	/** 32-bit hack. */
76	RTTRACELOGTYPE_32BIT_HACK = 0x7fffffff
77	} RTTRACELOGTYPE;
78	/** Pointer to a trace log item type. */
79	typedef RTTRACELOGTYPE *PRTTRACELOGTYPE;
80	/** Pointer to a const trace log item type. */
81	typedef const RTTRACELOGTYPE *PCRTTRACELOGTYPE;
82
83
84	/**
85	* Trace log event severity.
86	*/
87	typedef enum RTTRACELOGEVTSEVERITY
88	{
89	/** Invalid severity. */
90	RTTRACELOGEVTSEVERITY_INVALID = 0,
91	/** Informational event. */
92	RTTRACELOGEVTSEVERITY_INFO,
93	/** Warning event. */
94	RTTRACELOGEVTSEVERITY_WARNING,
95	/** Error event. */
96	RTTRACELOGEVTSEVERITY_ERROR,
97	/** Fatal event. */
98	RTTRACELOGEVTSEVERITY_FATAL,
99	/** Debug event. */
100	RTTRACELOGEVTSEVERITY_DEBUG,
101	/** 32bit hack.*/
102	RTTRACELOGEVTSEVERITY_32BIT_HACK = 0x7fffffff
103	} RTTRACELOGEVTSEVERITY;
104	/** Pointer to a event severity class. */
105	typedef RTTRACELOGEVTSEVERITY *PRTTRACELOGEVTSEVERITY;
106	/** Pointer to a const event severiy class. */
107	typedef RTTRACELOGEVTSEVERITY *PCRTTRACELOGEVTSEVERITY;
108
109
110	/**
111	* Trace log reader event.
112	*/
113	typedef enum RTTRACELOGRDRPOLLEVT
114	{
115	/** Invalid event. */
116	RTTRACELOGRDRPOLLEVT_INVALID = 0,
117	/** The header was received and valid. */
118	RTTRACELOGRDRPOLLEVT_HDR_RECVD,
119	/** Event data was fetched. */
120	RTTRACELOGRDRPOLLEVT_TRACE_EVENT_RECVD,
121	/** 32bit hack. */
122	RTTRACELOGRDRPOLLEVT_32BIT_HACK = 0x7fffffff
123	} RTTRACELOGRDRPOLLEVT;
124	/** Pointer to a trace log reader event. */
125	typedef RTTRACELOGRDRPOLLEVT *PRTTRACELOGRDRPOLLEVT;
126
127
128	/**
129	* Trace log event item descriptor.
130	*/
131	typedef struct RTTRACELOGEVTITEMDESC
132	{
133	/** Event item name. */
134	const char *pszName;
135	/** Event item description. */
136	const char *pszDesc;
137	/** Event item type. */
138	RTTRACELOGTYPE enmType;
139	/** The size of the raw data if static for the item,
140	* 0 otherwise (and given when the event is logged).
141	* Only valid for the RTTRACELOGTYPE_RAWDATA type,
142	* ignored otherwise. */
143	size_t cbRawData;
144	} RTTRACELOGEVTITEMDESC;
145	/** Pointer to an trace log event item descriptor. */
146	typedef RTTRACELOGEVTITEMDESC *PRTTRACELOGEVTITEMDESC;
147	/** Pointer to a const trace log event item descriptor. */
148	typedef const RTTRACELOGEVTITEMDESC *PCRTTRACELOGEVTITEMDESC;
149	/** Pointer to a trace log event item descriptor pointer. */
150	typedef PRTTRACELOGEVTITEMDESC *PPRTTRACELOGEVTITEMDESC;
151	/** Pointer to a const trace log event item descriptor pointer. */
152	typedef PCRTTRACELOGEVTITEMDESC *PPCRTTRACELOGEVTITEMDESC;
153
154
155	/**
156	* Trace log event descriptor.
157	*/
158	typedef struct RTTRACELOGEVTDESC
159	{
160	/** Event identifier. */
161	const char *pszId;
162	/** Event description. */
163	const char *pszDesc;
164	/** Severity class of the event. */
165	RTTRACELOGEVTSEVERITY enmSeverity;
166	/** Number of items recorded for an event. */
167	uint32_t cEvtItems;
168	/** Pointer to array of event item descriptors. */
169	PCRTTRACELOGEVTITEMDESC paEvtItemDesc;
170	} RTTRACELOGEVTDESC;
171	/** Pointer to a trace log event descriptor. */
172	typedef RTTRACELOGEVTDESC *PRTTRACELOGEVTDESC;
173	/** Pointer to a const trace log event descriptor. */
174	typedef const RTTRACELOGEVTDESC *PCRTTRACELOGEVTDESC;
175
176
177	/**
178	* Trace log event item value.
179	*/
180	typedef struct RTTRACELOGEVTVAL
181	{
182	/** Pointer to the corresponding event item descriptor. */
183	PCRTTRACELOGEVTITEMDESC pItemDesc;
184	/** Value union. */
185	union
186	{
187	bool f;
188	uint8_t u8;
189	int8_t i8;
190	uint16_t u16;
191	int16_t i16;
192	uint32_t u32;
193	int32_t i32;
194	uint64_t u64;
195	int64_t i64;
196	uint64_t sz;
197	uint64_t uPtr;
198	float f32;
199	double f64;
200	struct
201	{
202	size_t cb;
203	const uint8_t *pb;
204	} RawData;
205	} u;
206	} RTTRACELOGEVTVAL;
207	/** Pointer to trace log event item value. */
208	typedef RTTRACELOGEVTVAL *PRTTRACELOGEVTVAL;
209	/** Pointer to a const trace log event item value. */
210	typedef const RTTRACELOGEVTVAL *PCRTTRACELOGEVTVAL;
211
212
213	/** Event group ID. */
214	typedef uint64_t RTTRACELOGEVTGRPID;
215	/** Pointer to the event group ID. */
216	typedef RTTRACELOGEVTGRPID *PRTTRACELOGEVTGRPID;
217	/** Trace log event handle. */
218	typedef uint64_t RTRACELOGEVT;
219	/** Pointer to a trace log event handle. */
220	typedef RTRACELOGEVT *PRTRACELOGEVT;
221	/** Trace log writer handle. */
222	typedef struct RTTRACELOGWRINT *RTTRACELOGWR;
223	/** Pointer to a trace log writer handle. */
224	typedef RTTRACELOGWR *PRTTRACELOGWR;
225	/** NIL trace log writer handle value. */
226	#define NIL_RTTRACELOGWR ((RTTRACELOGWR)0)
227	/** Trace log reader handle. */
228	typedef struct RTTRACELOGRDRINT *RTTRACELOGRDR;
229	/** Pointer to a trace log reader handle. */
230	typedef RTTRACELOGRDR *PRTTRACELOGRDR;
231	/** NIL trace log reader handle value. */
232	#define NIL_RTTRACELOGRDR ((RTTRACELOGRDR)0)
233	/** Trace log reader iterator handle. */
234	typedef struct RTTRACELOGRDRITINT *RTTRACELOGRDRIT;
235	/** Pointer to a trace log reader iterator handle. */
236	typedef RTTRACELOGRDRIT *PRTTRACELOGRDRIT;
237	/** NIL trace log reader iterator handle. */
238	#define NIL_RTTRACELOGRDRIT ((RTTRACELOGRDRIT)0)
239	/** Trace log reader event handle. */
240	typedef struct RTTRACELOGRDREVTINT *RTTRACELOGRDREVT;
241	/** Pointer to a trace log reader event handle. */
242	typedef RTTRACELOGRDREVT *PRTTRACELOGRDREVT;
243	/** NIL trace log reader event handle. */
244	#define NIL_RTTRACELOGRDREVT ((RTTRACELOGRDREVT)0)
245
246	/** A new grouped event is started. */
247	#define RTTRACELOG_WR_ADD_EVT_F_GRP_START RT_BIT_32(0)
248	/** A grouped event is finished. */
249	#define RTTRACELOG_WR_ADD_EVT_F_GRP_FINISH RT_BIT_32(1)
250
251	/**
252	* Callback to stream out data from the trace log writer.
253	*
254	* @returns IPRT status code.
255	* @param pvUser Opaque user data passed on trace log writer creation.
256	* @param pvBuf Pointer to the buffer to stream out.
257	* @param cbBuf Number of bytes to stream.
258	* @param pcbWritten Where to store the number of bytes written on success, optional.
259	*/
260	typedef DECLCALLBACK(int) FNRTTRACELOGWRSTREAM(void pvUser, const void pvBuf, size_t cbBuf, size_t *pcbWritten);
261	/** Pointer to a writer stream callback. */
262	typedef FNRTTRACELOGWRSTREAM *PFNRTTRACELOGWRSTREAM;
263
264
265	/**
266	* Callback to stream int data to the trace log reader.
267	*
268	* @returns IPRT status code.
269	* @retval VERR_EOF if the stream reached the end.
270	* @retval VERR_INTERRUPTED if waiting for something to arrive was interrupted.
271	* @retval VERR_TIMEOUT if the timeout was reached.
272	* @param pvUser Opaque user data passed on trace log reader creation.
273	* @param pvBuf Where to store the read data.
274	* @param cbBuf Number of bytes the buffer can hold.
275	* @param pcbRead Where to store the number of bytes read on success.
276	* @param cMsTimeout How long to wait for something to arrive
277	*/
278	typedef DECLCALLBACK(int) FNRTTRACELOGRDRSTREAM(void pvUser, void pvBuf, size_t cbBuf, size_t *pcbRead,
279	RTMSINTERVAL cMsTimeout);
280	/** Pointer to a writer stream callback. */
281	typedef FNRTTRACELOGRDRSTREAM *PFNRTTRACELOGRDRSTREAM;
282
283
284	/**
285	* Callback to close the stream.
286	*
287	* @returns IPRT status code.
288	* @param pvUser Opaque user data passed on trace log writer creation.
289	*/
290	typedef DECLCALLBACK(int) FNRTTRACELOGSTREAMCLOSE(void *pvUser);
291	/** Pointer to a stream close callback. */
292	typedef FNRTTRACELOGSTREAMCLOSE *PFNRTTRACELOGSTREAMCLOSE;
293
294
295	/**
296	* Creates a new trace log writer.
297	*
298	* @returns IPRT status code.
299	* @param phTraceLogWr Where to store the handle to the trace log writer on success.
300	* @param pszDesc Optional description to store in the header.
301	* @param pfnStreamOut The callback to use for streaming the trace log data.
302	* @param pfnStreamClose The callback to use for closing the stream.
303	* @param pvUser Opaque user data to pass to the streaming callback.
304	*/
305	RTDECL(int) RTTraceLogWrCreate(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
306	PFNRTTRACELOGWRSTREAM pfnStreamOut,
307	PFNRTTRACELOGSTREAMCLOSE pfnStreamClose, void *pvUser);
308
309
310	/**
311	* Creates a new trace log writer streaming data to the given file.
312	*
313	* @returns IPRT status code.
314	* @param phTraceLogWr Where to store the handle to the trace log writer on success.
315	* @param pszDesc Optional description to store in the header.
316	* @param pszFilename The filename to stream the data to.
317	*/
318	RTDECL(int) RTTraceLogWrCreateFile(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
319	const char *pszFilename);
320
321
322	/**
323	* Creates a new TCP server style trace log writer waiting for the other end to connect to it.
324	*
325	* @returns IPRT status code.
326	* @param phTraceLogWr Where to store the handle to the trace log writer on success.
327	* @param pszDesc Optional description to store in the header.
328	* @param pszListen The address to listen on, NULL to listen on all interfaces.
329	* @param uPort The port to listen on.
330	*
331	* @note The writer will block here until a client has connected.
332	*/
333	RTDECL(int) RTTraceLogWrCreateTcpServer(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
334	const char *pszListen, unsigned uPort);
335
336
337	/**
338	* Creates a new TCP client style trace log writer connecting to the other end.
339	*
340	* @returns IPRT status code.
341	* @param phTraceLogWr Where to store the handle to the trace log writer on success.
342	* @param pszDesc Optional description to store in the header.
343	* @param pszAddress The address to connect to.
344	* @param uPort The port to connect to.
345	*
346	* @note An error is returned if no connection can be established.
347	*/
348	RTDECL(int) RTTraceLogWrCreateTcpClient(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
349	const char *pszAddress, unsigned uPort);
350
351
352	/**
353	* Destroys the given trace log writer instance.
354	*
355	* @returns IPRT status code.
356	* @param hTraceLogWr The trace log writer instance handle.
357	*/
358	RTDECL(int) RTTraceLogWrDestroy(RTTRACELOGWR hTraceLogWr);
359
360
361	/**
362	* Adds a given event structure descriptor to the given trace log writer instance
363	* (for prepopulation).
364	*
365	* @returns IPRT status code.
366	* @param hTraceLogWr The trace log writer instance handle.
367	* @param pEvtDesc The event structure descriptor to add.
368	*
369	* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
370	* so don't free after this method finishes.
371	*/
372	RTDECL(int) RTTraceLogWrAddEvtDesc(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc);
373
374
375	/**
376	* Adds a new event to the trace log.
377	*
378	* @returns IPRT status code.
379	* @param hTraceLogWr The trace log writer instance handle.
380	* @param pEvtDesc The event descriptor to use for formatting.
381	* @param fFlags Flags to use for this event.y
382	* @param uGrpId A unique group ID for grouped events.
383	* @param uParentGrpId A parent group ID this event originated from.
384	* @param pvEvtData Pointer to the raw event data.
385	* @param pacbRawData Pointer to the array of size indicators for non static raw data in the event data stream.
386	*
387	* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
388	* so don't free after this method finishes.
389	*/
390	RTDECL(int) RTTraceLogWrEvtAdd(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
391	RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId,
392	const void pvEvtData, size_t pacbRawData);
393
394
395	/**
396	* Adds a new event to the trace log.
397	*
398	* @returns IPRT status code.
399	* @param hTraceLogWr The trace log writer instance handle.
400	* @param pEvtDesc The event descriptor used for formatting the data.
401	* @param fFlags Flags to use for this event.
402	* @param uGrpId A unique group ID for grouped events.
403	* @param uParentGrpId A parent group ID this event originated from.
404	* @param pSgBufEvtData S/G buffer holding the raw event data.
405	* @param pacbRawData Pointer to the array of size indicators for non static raw data in the event data stream.
406	*
407	* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
408	* so don't free after this method finishes.
409	*/
410	RTDECL(int) RTTraceLogWrEvtAddSg(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
411	RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId,
412	PRTSGBUF pSgBufEvtData, size_t pacbRawData);
413
414
415	/**
416	* Adds a new event to the trace log - list variant.
417	*
418	* @returns IPRT status code.
419	* @param hTraceLogWr The trace log writer instance handle.
420	* @param pEvtDesc The event descriptor used for formatting the data.
421	* @param fFlags Flags to use for this event.
422	* @param uGrpId A unique group ID for grouped events.
423	* @param uParentGrpId A parent group ID this event originated from.
424	* @param va The event data as single items as described by the descriptor.
425	*
426	* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
427	* so don't free after this method finishes.
428	*/
429	RTDECL(int) RTTraceLogWrEvtAddLV(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
430	RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId, va_list va);
431
432
433	/**
434	* Adds a new event to the trace log - list variant.
435	*
436	* @returns IPRT status code.
437	* @param hTraceLogWr The trace log writer instance handle.
438	* @param pEvtDesc The event descriptor used for formatting the data.
439	* @param fFlags Flags to use for this event.
440	* @param uGrpId A unique group ID for grouped events.
441	* @param uParentGrpId A parent group ID this event originated from.
442	* @param ... The event data as single items as described by the descriptor.
443	*
444	* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
445	* so don't free after this method finishes.
446	*/
447	RTDECL(int) RTTraceLogWrEvtAddL(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
448	RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId, ...);
449
450
451	/**
452	* Creates a new trace log reader instance.
453	*
454	* @returns IPRT status code.
455	* @param phTraceLogRdr Where to store the handle to the trace log reader instance on success.
456	* @param pfnStreamIn Callback to stream the data into the reader.
457	* @param pfnStreamClose The callback to use for closing the stream.
458	* @param pvUser Opaque user data passed to the stream callback.
459	*/
460	RTDECL(int) RTTraceLogRdrCreate(PRTTRACELOGRDR phTraceLogRdr, PFNRTTRACELOGRDRSTREAM pfnStreamIn,
461	PFNRTTRACELOGSTREAMCLOSE pfnStreamClose, void *pvUser);
462
463
464	/**
465	* Creates a new trace log reader for the given file.
466	*
467	* @returns IPRT status code.
468	* @param phTraceLogRdr Where to store the handle to the trace log reader instance on success.
469	* @param pszFilename The file to read the trace log data from.
470	*/
471	RTDECL(int) RTTraceLogRdrCreateFromFile(PRTTRACELOGRDR phTraceLogRdr, const char *pszFilename);
472
473
474	/**
475	* Destroys the given trace log reader instance.
476	*
477	* @returns IPRT status code.
478	* @param hTraceLogRdr The trace log reader instance handle.
479	*/
480	RTDECL(int) RTTraceLogRdrDestroy(RTTRACELOGRDR hTraceLogRdr);
481
482
483	/**
484	* Polls for an event on the trace log reader instance.
485	*
486	* @returns IPRT status code.
487	* @retval VERR_TIMEOUT if the timeout was reached.
488	* @retval VERR_INTERRUPTED if the poll was interrupted.
489	* @param hTraceLogRdr The trace log reader instance handle.
490	* @param penmEvt Where to store the event identifier.
491	* @param cMsTimeout How long to poll for an event.
492	*/
493	RTDECL(int) RTTraceLogRdrEvtPoll(RTTRACELOGRDR hTraceLogRdr, RTTRACELOGRDRPOLLEVT *penmEvt, RTMSINTERVAL cMsTimeout);
494
495	/**
496	* Queries the last received event from the trace log read instance.
497	*
498	* @returns IPRT status code.
499	* @retval VERR_NOT_FOUND if no event was received so far.
500	* @param hTraceLogRdr The trace log reader instance handle.
501	* @param phRdrEvt Where to store the event handle on success.
502	*/
503	RTDECL(int) RTTraceLogRdrQueryLastEvt(RTTRACELOGRDR hTraceLogRdr, PRTTRACELOGRDREVT phRdrEvt);
504
505	/**
506	* Queries a new iterator for walking received events.
507	*
508	* @returns IPRT status code
509	* @param hTraceLogRdr The trace log reader instance handle.
510	* @param phIt Where to store the handle to iterator on success.
511	*/
512	RTDECL(int) RTTraceLogRdrQueryIterator(RTTRACELOGRDR hTraceLogRdr, PRTTRACELOGRDRIT phIt);
513
514
515	/**
516	* Frees a previously created iterator.
517	*
518	* @returns nothing.
519	* @param hIt The iterator handle to free.
520	*/
521	RTDECL(void) RTTraceLogRdrIteratorFree(RTTRACELOGRDRIT hIt);
522
523
524	/**
525	* Advances to the next event.
526	*
527	* @returns IPRT status code
528	* @retval VERR_TRACELOG_READER_ITERATOR_END if the iterator reached the end.
529	* @param hIt The iterator handle.
530	*/
531	RTDECL(int) RTTraceLogRdrIteratorNext(RTTRACELOGRDRIT hIt);
532
533
534	/**
535	* Queries the event at the current iterator position.
536	*
537	* @returns IPRT status code.
538	* @param hIt The iterator handle.
539	* @param phRdrEvt Where to store the event handle on success.
540	*/
541	RTDECL(int) RTTraceLogRdrIteratorQueryEvent(RTTRACELOGRDRIT hIt, PRTTRACELOGRDREVT phRdrEvt);
542
543
544	/**
545	* Returns the sequence number of the given event.
546	*
547	* @returns Sequence number of the given event.
548	* @param hRdrEvt The reader event handle.
549	*/
550	RTDECL(uint64_t) RTTraceLogRdrEvtGetSeqNo(RTTRACELOGRDREVT hRdrEvt);
551
552
553	/**
554	* Gets the timestamp of the given event.
555	*
556	* @returns Timestamp of the given event.
557	* @param hRdrEvt The reader event handle.
558	*/
559	RTDECL(uint64_t) RTTraceLogRdrEvtGetTs(RTTRACELOGRDREVT hRdrEvt);
560
561
562	/**
563	* Returns whether the given event is part of an event group.
564	*
565	* @returns Flag whether the event is part of a group.
566	* @param hRdrEvt The reader event handle.
567	*/
568	RTDECL(bool) RTTraceLogRdrEvtIsGrouped(RTTRACELOGRDREVT hRdrEvt);
569
570
571	/**
572	* Returns the event descriptor associated with the given event.
573	*
574	* @returns The trace log event descriptor associated with this event.
575	* @param hRdrEvt The reader event handle.
576	*/
577	RTDECL(PCRTTRACELOGEVTDESC) RTTraceLogRdrEvtGetDesc(RTTRACELOGRDREVT hRdrEvt);
578
579
580	/**
581	* Queries an event item by its name returning the value in the supplied buffer.
582	*
583	* @returns IPRT status code.
584	* @retval VERR_NOT_FOUND if the item name was not found for the given event.
585	* @param hRdrEvt The reader event handle.
586	* @param pszName The item name to query.
587	* @param pVal The item value buffer to initialise.
588	*/
589	RTDECL(int) RTTraceLogRdrEvtQueryVal(RTTRACELOGRDREVT hRdrEvt, const char *pszName, PRTTRACELOGEVTVAL pVal);
590
591
592	/**
593	* Fills the given value array using the values from the given event.
594	*
595	* @returns IPRT status code
596	* @param hRdrEvt The reader event handle.
597	* @param idxItemStart The index of the item to start filling the value in.
598	* @param paVals Array of values to fill.
599	* @param cVals Number of values the array is able to hold.
600	* @param pcVals Where to store the number of values filled on success.
601	*/
602	RTDECL(int) RTTraceLogRdrEvtFillVals(RTTRACELOGRDREVT hRdrEvt, unsigned idxItemStart, PRTTRACELOGEVTVAL paVals,
603	unsigned cVals, unsigned *pcVals);
604
605	RT_C_DECLS_END
606
607	/** @} */
608
609	#endif
610

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/iprt/tracelog.h@ 76421

Download in other formats: