tracelog.h@ 84341

Last change on this file since 84341 was 82968, checked in by vboxsync, 5 years ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 22.4 KB

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

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

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

Download in other formats: