tracelog.h@ 101243

Last change on this file since 101243 was 99739, checked in by vboxsync, 19 months ago
*: doxygen corrections (mostly about removing @returns from functions returning void).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 26.0 KB

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

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

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

Download in other formats: