tracelog.h@ 94817

Last change on this file since 94817 was 93115, checked in by vboxsync, 3 years ago
scm --update-copyright-year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 25.7 KB

Line
1	/** @file
2	* IPRT - Binary trace log API.
3	*/
4
5	/*
6	* Copyright (C) 2018-2022 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	/**
217	* Item mapping descriptor.
218	*/
219	typedef struct RTTRACELOGRDRMAPITEM
220	{
221	/** The item name. */
222	const char *pszName;
223	/** The value type to map the item to. */
224	RTTRACELOGTYPE enmType;
225	} RTTRACELOGRDRMAPITEM;
226	/** Pointer to a mapping item descriptor. */
227	typedef RTTRACELOGRDRMAPITEM *PRTTRACELOGRDRMAPITEM;
228	/** Pointer to a const mapping item descriptor. */
229	typedef const RTTRACELOGRDRMAPITEM *PCRTTRACELOGRDRMAPITEM;
230
231
232	/**
233	* Event item to value mapping descriptor for RTTraceLogRdrEvtMapToStruct().
234	*/
235	typedef struct RTTRACELOGRDRMAPDESC
236	{
237	/** The event ID this mapping describes. */
238	const char *pszEvtId;
239	/** Number of event items to extract. */
240	uint32_t cEvtItems;
241	/** Pointer to the event items to extract (in the given order). */
242	PCRTTRACELOGRDRMAPITEM paMapItems;
243	} RTTRACELOGRDRMAPDESC;
244	/** Pointer to a event mapping descriptor. */
245	typedef RTTRACELOGRDRMAPDESC *PRTTRACELOGRDRMAPDESC;
246	/** Pointer to a const event mapping descriptor. */
247	typedef const RTTRACELOGRDRMAPDESC *PCRTTRACELOGRDRMAPDESC;
248
249
250	/**
251	* Header for an event mapped to a binary.
252	*/
253	typedef struct RTTRACELOGRDREVTHDR
254	{
255	/** The mapping descriptor this event was mapped to. */
256	PCRTTRACELOGRDRMAPDESC pEvtMapDesc;
257	/** The event descriptor as extracted from the event log. */
258	PCRTTRACELOGEVTDESC pEvtDesc;
259	/** Sequence number of the descriptor. */
260	uint64_t idSeqNo;
261	/** The timestamp of the event. */
262	uint64_t tsEvt;
263	/** Pointer to the event data items. */
264	PCRTTRACELOGEVTVAL paEvtItems;
265	} RTTRACELOGRDREVTHDR;
266	/** Pointer to an event header. */
267	typedef RTTRACELOGRDREVTHDR *PRTTRACELOGRDREVTHDR;
268	/** Pointer to a const event header. */
269	typedef const RTTRACELOGRDREVTHDR *PCRTTRACELOGRDREVTHDR;
270
271
272	/** Event group ID. */
273	typedef uint64_t RTTRACELOGEVTGRPID;
274	/** Pointer to the event group ID. */
275	typedef RTTRACELOGEVTGRPID *PRTTRACELOGEVTGRPID;
276	/** Trace log event handle. */
277	typedef uint64_t RTRACELOGEVT;
278	/** Pointer to a trace log event handle. */
279	typedef RTRACELOGEVT *PRTRACELOGEVT;
280	/** Trace log writer handle. */
281	typedef struct RTTRACELOGWRINT *RTTRACELOGWR;
282	/** Pointer to a trace log writer handle. */
283	typedef RTTRACELOGWR *PRTTRACELOGWR;
284	/** NIL trace log writer handle value. */
285	#define NIL_RTTRACELOGWR ((RTTRACELOGWR)0)
286	/** Trace log reader handle. */
287	typedef struct RTTRACELOGRDRINT *RTTRACELOGRDR;
288	/** Pointer to a trace log reader handle. */
289	typedef RTTRACELOGRDR *PRTTRACELOGRDR;
290	/** NIL trace log reader handle value. */
291	#define NIL_RTTRACELOGRDR ((RTTRACELOGRDR)0)
292	/** Trace log reader iterator handle. */
293	typedef struct RTTRACELOGRDRITINT *RTTRACELOGRDRIT;
294	/** Pointer to a trace log reader iterator handle. */
295	typedef RTTRACELOGRDRIT *PRTTRACELOGRDRIT;
296	/** NIL trace log reader iterator handle. */
297	#define NIL_RTTRACELOGRDRIT ((RTTRACELOGRDRIT)0)
298	/** Trace log reader event handle. */
299	typedef struct RTTRACELOGRDREVTINT *RTTRACELOGRDREVT;
300	/** Pointer to a trace log reader event handle. */
301	typedef RTTRACELOGRDREVT *PRTTRACELOGRDREVT;
302	/** NIL trace log reader event handle. */
303	#define NIL_RTTRACELOGRDREVT ((RTTRACELOGRDREVT)0)
304
305	/** A new grouped event is started. */
306	#define RTTRACELOG_WR_ADD_EVT_F_GRP_START RT_BIT_32(0)
307	/** A grouped event is finished. */
308	#define RTTRACELOG_WR_ADD_EVT_F_GRP_FINISH RT_BIT_32(1)
309
310	/**
311	* Callback to stream out data from the trace log writer.
312	*
313	* @returns IPRT status code.
314	* @param pvUser Opaque user data passed on trace log writer creation.
315	* @param pvBuf Pointer to the buffer to stream out.
316	* @param cbBuf Number of bytes to stream.
317	* @param pcbWritten Where to store the number of bytes written on success, optional.
318	*/
319	typedef DECLCALLBACKTYPE(int, FNRTTRACELOGWRSTREAM,(void pvUser, const void pvBuf, size_t cbBuf, size_t *pcbWritten));
320	/** Pointer to a writer stream callback. */
321	typedef FNRTTRACELOGWRSTREAM *PFNRTTRACELOGWRSTREAM;
322
323
324	/**
325	* Callback to stream int data to the trace log reader.
326	*
327	* @returns IPRT status code.
328	* @retval VERR_EOF if the stream reached the end.
329	* @retval VERR_INTERRUPTED if waiting for something to arrive was interrupted.
330	* @retval VERR_TIMEOUT if the timeout was reached.
331	* @param pvUser Opaque user data passed on trace log reader creation.
332	* @param pvBuf Where to store the read data.
333	* @param cbBuf Number of bytes the buffer can hold.
334	* @param pcbRead Where to store the number of bytes read on success.
335	* @param cMsTimeout How long to wait for something to arrive
336	*/
337	typedef DECLCALLBACKTYPE(int, FNRTTRACELOGRDRSTREAM,(void pvUser, void pvBuf, size_t cbBuf, size_t *pcbRead,
338	RTMSINTERVAL cMsTimeout));
339	/** Pointer to a writer stream callback. */
340	typedef FNRTTRACELOGRDRSTREAM *PFNRTTRACELOGRDRSTREAM;
341
342
343	/**
344	* Callback to close the stream.
345	*
346	* @returns IPRT status code.
347	* @param pvUser Opaque user data passed on trace log writer creation.
348	*/
349	typedef DECLCALLBACKTYPE(int, FNRTTRACELOGSTREAMCLOSE,(void *pvUser));
350	/** Pointer to a stream close callback. */
351	typedef FNRTTRACELOGSTREAMCLOSE *PFNRTTRACELOGSTREAMCLOSE;
352
353
354	/**
355	* Creates a new trace log writer.
356	*
357	* @returns IPRT status code.
358	* @param phTraceLogWr Where to store the handle to the trace log writer on success.
359	* @param pszDesc Optional description to store in the header.
360	* @param pfnStreamOut The callback to use for streaming the trace log data.
361	* @param pfnStreamClose The callback to use for closing the stream.
362	* @param pvUser Opaque user data to pass to the streaming callback.
363	*/
364	RTDECL(int) RTTraceLogWrCreate(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
365	PFNRTTRACELOGWRSTREAM pfnStreamOut,
366	PFNRTTRACELOGSTREAMCLOSE pfnStreamClose, void *pvUser);
367
368
369	/**
370	* Creates a new trace log writer streaming data to the given file.
371	*
372	* @returns IPRT status code.
373	* @param phTraceLogWr Where to store the handle to the trace log writer on success.
374	* @param pszDesc Optional description to store in the header.
375	* @param pszFilename The filename to stream the data to.
376	*/
377	RTDECL(int) RTTraceLogWrCreateFile(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
378	const char *pszFilename);
379
380
381	/**
382	* Creates a new TCP server style trace log writer waiting for the other end to connect to it.
383	*
384	* @returns IPRT status code.
385	* @param phTraceLogWr Where to store the handle to the trace log writer on success.
386	* @param pszDesc Optional description to store in the header.
387	* @param pszListen The address to listen on, NULL to listen on all interfaces.
388	* @param uPort The port to listen on.
389	*
390	* @note The writer will block here until a client has connected.
391	*/
392	RTDECL(int) RTTraceLogWrCreateTcpServer(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
393	const char *pszListen, unsigned uPort);
394
395
396	/**
397	* Creates a new TCP client style trace log writer connecting to the other end.
398	*
399	* @returns IPRT status code.
400	* @param phTraceLogWr Where to store the handle to the trace log writer on success.
401	* @param pszDesc Optional description to store in the header.
402	* @param pszAddress The address to connect to.
403	* @param uPort The port to connect to.
404	*
405	* @note An error is returned if no connection can be established.
406	*/
407	RTDECL(int) RTTraceLogWrCreateTcpClient(PRTTRACELOGWR phTraceLogWr, const char *pszDesc,
408	const char *pszAddress, unsigned uPort);
409
410
411	/**
412	* Destroys the given trace log writer instance.
413	*
414	* @returns IPRT status code.
415	* @param hTraceLogWr The trace log writer instance handle.
416	*/
417	RTDECL(int) RTTraceLogWrDestroy(RTTRACELOGWR hTraceLogWr);
418
419
420	/**
421	* Adds a given event structure descriptor to the given trace log writer instance
422	* (for prepopulation).
423	*
424	* @returns IPRT status code.
425	* @param hTraceLogWr The trace log writer instance handle.
426	* @param pEvtDesc The event structure descriptor to add.
427	*
428	* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
429	* so don't free after this method finishes.
430	*/
431	RTDECL(int) RTTraceLogWrAddEvtDesc(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc);
432
433
434	/**
435	* Adds a new event to the trace log.
436	*
437	* @returns IPRT status code.
438	* @param hTraceLogWr The trace log writer instance handle.
439	* @param pEvtDesc The event descriptor to use for formatting.
440	* @param fFlags Flags to use for this event.y
441	* @param uGrpId A unique group ID for grouped events.
442	* @param uParentGrpId A parent group ID this event originated from.
443	* @param pvEvtData Pointer to the raw event data.
444	* @param pacbRawData Pointer to the array of size indicators for non static raw data in the event data stream.
445	*
446	* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
447	* so don't free after this method finishes.
448	*/
449	RTDECL(int) RTTraceLogWrEvtAdd(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
450	RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId,
451	const void pvEvtData, size_t pacbRawData);
452
453
454	/**
455	* Adds a new event to the trace log.
456	*
457	* @returns IPRT status code.
458	* @param hTraceLogWr The trace log writer instance handle.
459	* @param pEvtDesc The event descriptor used for formatting the data.
460	* @param fFlags Flags to use for this event.
461	* @param uGrpId A unique group ID for grouped events.
462	* @param uParentGrpId A parent group ID this event originated from.
463	* @param pSgBufEvtData S/G buffer holding the raw event data.
464	* @param pacbRawData Pointer to the array of size indicators for non static raw data in the event data stream.
465	*
466	* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
467	* so don't free after this method finishes.
468	*/
469	RTDECL(int) RTTraceLogWrEvtAddSg(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
470	RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId,
471	PRTSGBUF pSgBufEvtData, size_t pacbRawData);
472
473
474	/**
475	* Adds a new event to the trace log - list variant.
476	*
477	* @returns IPRT status code.
478	* @param hTraceLogWr The trace log writer instance handle.
479	* @param pEvtDesc The event descriptor used for formatting the data.
480	* @param fFlags Flags to use for this event.
481	* @param uGrpId A unique group ID for grouped events.
482	* @param uParentGrpId A parent group ID this event originated from.
483	* @param va The event data as single items as described by the descriptor.
484	*
485	* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
486	* so don't free after this method finishes.
487	*/
488	RTDECL(int) RTTraceLogWrEvtAddLV(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
489	RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId, va_list va);
490
491
492	/**
493	* Adds a new event to the trace log - list variant.
494	*
495	* @returns IPRT status code.
496	* @param hTraceLogWr The trace log writer instance handle.
497	* @param pEvtDesc The event descriptor used for formatting the data.
498	* @param fFlags Flags to use for this event.
499	* @param uGrpId A unique group ID for grouped events.
500	* @param uParentGrpId A parent group ID this event originated from.
501	* @param ... The event data as single items as described by the descriptor.
502	*
503	* @note The event descriptor is keyed by the pointer for faster lookup in subsequent calls,
504	* so don't free after this method finishes.
505	*/
506	RTDECL(int) RTTraceLogWrEvtAddL(RTTRACELOGWR hTraceLogWr, PCRTTRACELOGEVTDESC pEvtDesc, uint32_t fFlags,
507	RTTRACELOGEVTGRPID uGrpId, RTTRACELOGEVTGRPID uParentGrpId, ...);
508
509
510	/**
511	* Creates a new trace log reader instance.
512	*
513	* @returns IPRT status code.
514	* @param phTraceLogRdr Where to store the handle to the trace log reader instance on success.
515	* @param pfnStreamIn Callback to stream the data into the reader.
516	* @param pfnStreamClose The callback to use for closing the stream.
517	* @param pvUser Opaque user data passed to the stream callback.
518	*/
519	RTDECL(int) RTTraceLogRdrCreate(PRTTRACELOGRDR phTraceLogRdr, PFNRTTRACELOGRDRSTREAM pfnStreamIn,
520	PFNRTTRACELOGSTREAMCLOSE pfnStreamClose, void *pvUser);
521
522
523	/**
524	* Creates a new trace log reader for the given file.
525	*
526	* @returns IPRT status code.
527	* @param phTraceLogRdr Where to store the handle to the trace log reader instance on success.
528	* @param pszFilename The file to read the trace log data from.
529	*/
530	RTDECL(int) RTTraceLogRdrCreateFromFile(PRTTRACELOGRDR phTraceLogRdr, const char *pszFilename);
531
532
533	/**
534	* Destroys the given trace log reader instance.
535	*
536	* @returns IPRT status code.
537	* @param hTraceLogRdr The trace log reader instance handle.
538	*/
539	RTDECL(int) RTTraceLogRdrDestroy(RTTRACELOGRDR hTraceLogRdr);
540
541
542	/**
543	* Polls for an event on the trace log reader instance.
544	*
545	* @returns IPRT status code.
546	* @retval VERR_TIMEOUT if the timeout was reached.
547	* @retval VERR_INTERRUPTED if the poll was interrupted.
548	* @param hTraceLogRdr The trace log reader instance handle.
549	* @param penmEvt Where to store the event identifier.
550	* @param cMsTimeout How long to poll for an event.
551	*/
552	RTDECL(int) RTTraceLogRdrEvtPoll(RTTRACELOGRDR hTraceLogRdr, RTTRACELOGRDRPOLLEVT *penmEvt, RTMSINTERVAL cMsTimeout);
553
554	/**
555	* Queries the last received event from the trace log read instance.
556	*
557	* @returns IPRT status code.
558	* @retval VERR_NOT_FOUND if no event was received so far.
559	* @param hTraceLogRdr The trace log reader instance handle.
560	* @param phRdrEvt Where to store the event handle on success.
561	*/
562	RTDECL(int) RTTraceLogRdrQueryLastEvt(RTTRACELOGRDR hTraceLogRdr, PRTTRACELOGRDREVT phRdrEvt);
563
564	/**
565	* Queries a new iterator for walking received events.
566	*
567	* @returns IPRT status code
568	* @param hTraceLogRdr The trace log reader instance handle.
569	* @param phIt Where to store the handle to iterator on success.
570	*/
571	RTDECL(int) RTTraceLogRdrQueryIterator(RTTRACELOGRDR hTraceLogRdr, PRTTRACELOGRDRIT phIt);
572
573
574	/**
575	* Extracts the given number of events from the given trace log reader instance returning
576	* and array of events with the values filled in from the mapping descriptor.
577	*
578	* @returns IPRT status code.
579	* @param hTraceLogRdr The trace log reader instance handle.
580	* @param fFlags Flags controlling the behavior, MBZ.
581	* @param cEvts Number of events to extract, UINT32_MAX to map all immediately available events.
582	* @param paMapDesc Pointer to an array of mapping descriptors describing how to map events.
583	* @param ppaEvtHdr Where to return the pointer to the allocated array of event headers on success.
584	* @param pcEvts Where to store the returned number of events on success.
585	*/
586	RTDECL(int) RTTraceLogRdrEvtMapToStruct(RTTRACELOGRDR hTraceLogRdr, uint32_t fFlags, uint32_t cEvts,
587	PCRTTRACELOGRDRMAPDESC paMapDesc, PCRTTRACELOGRDREVTHDR *ppaEvtHdr,
588	uint32_t *pcEvts);
589
590
591	/**
592	* Frees all resources of the given array of event headers as allocated by RTTraceLogRdrEvtMapToStruct().
593	*
594	* @returns nothing.
595	* @param paEvtHdr Pointer to the array of events as returned by RTTraceLogRdrEvtMapToStruct().
596	* @param cEvts Number of events as returned by RTTraceLogRdrEvtMapToStruct().
597	*/
598	RTDECL(void) RTTraceLogRdrEvtMapFree(PCRTTRACELOGRDREVTHDR paEvtHdr, uint32_t cEvts);
599
600
601	/**
602	* Frees a previously created iterator.
603	*
604	* @returns nothing.
605	* @param hIt The iterator handle to free.
606	*/
607	RTDECL(void) RTTraceLogRdrIteratorFree(RTTRACELOGRDRIT hIt);
608
609
610	/**
611	* Advances to the next event.
612	*
613	* @returns IPRT status code
614	* @retval VERR_TRACELOG_READER_ITERATOR_END if the iterator reached the end.
615	* @param hIt The iterator handle.
616	*/
617	RTDECL(int) RTTraceLogRdrIteratorNext(RTTRACELOGRDRIT hIt);
618
619
620	/**
621	* Queries the event at the current iterator position.
622	*
623	* @returns IPRT status code.
624	* @param hIt The iterator handle.
625	* @param phRdrEvt Where to store the event handle on success.
626	*/
627	RTDECL(int) RTTraceLogRdrIteratorQueryEvent(RTTRACELOGRDRIT hIt, PRTTRACELOGRDREVT phRdrEvt);
628
629
630	/**
631	* Returns the sequence number of the given event.
632	*
633	* @returns Sequence number of the given event.
634	* @param hRdrEvt The reader event handle.
635	*/
636	RTDECL(uint64_t) RTTraceLogRdrEvtGetSeqNo(RTTRACELOGRDREVT hRdrEvt);
637
638
639	/**
640	* Gets the timestamp of the given event.
641	*
642	* @returns Timestamp of the given event.
643	* @param hRdrEvt The reader event handle.
644	*/
645	RTDECL(uint64_t) RTTraceLogRdrEvtGetTs(RTTRACELOGRDREVT hRdrEvt);
646
647
648	/**
649	* Returns whether the given event is part of an event group.
650	*
651	* @returns Flag whether the event is part of a group.
652	* @param hRdrEvt The reader event handle.
653	*/
654	RTDECL(bool) RTTraceLogRdrEvtIsGrouped(RTTRACELOGRDREVT hRdrEvt);
655
656
657	/**
658	* Returns the event descriptor associated with the given event.
659	*
660	* @returns The trace log event descriptor associated with this event.
661	* @param hRdrEvt The reader event handle.
662	*/
663	RTDECL(PCRTTRACELOGEVTDESC) RTTraceLogRdrEvtGetDesc(RTTRACELOGRDREVT hRdrEvt);
664
665
666	/**
667	* Queries an event item by its name returning the value in the supplied buffer.
668	*
669	* @returns IPRT status code.
670	* @retval VERR_NOT_FOUND if the item name was not found for the given event.
671	* @param hRdrEvt The reader event handle.
672	* @param pszName The item name to query.
673	* @param pVal The item value buffer to initialise.
674	*/
675	RTDECL(int) RTTraceLogRdrEvtQueryVal(RTTRACELOGRDREVT hRdrEvt, const char *pszName, PRTTRACELOGEVTVAL pVal);
676
677
678	/**
679	* Fills the given value array using the values from the given event.
680	*
681	* @returns IPRT status code
682	* @param hRdrEvt The reader event handle.
683	* @param idxItemStart The index of the item to start filling the value in.
684	* @param paVals Array of values to fill.
685	* @param cVals Number of values the array is able to hold.
686	* @param pcVals Where to store the number of values filled on success.
687	*/
688	RTDECL(int) RTTraceLogRdrEvtFillVals(RTTRACELOGRDREVT hRdrEvt, unsigned idxItemStart, PRTTRACELOGEVTVAL paVals,
689	unsigned cVals, unsigned *pcVals);
690
691	RT_C_DECLS_END
692
693	/** @} */
694
695	#endif /* !IPRT_INCLUDED_tracelog_h */
696

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

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

Download in other formats: