VirtualBox

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

Last change on this file since 103224 was 99739, checked in by vboxsync, 17 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
45RT_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 */
56typedef 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. */
92typedef RTTRACELOGTYPE *PRTTRACELOGTYPE;
93/** Pointer to a const trace log item type. */
94typedef const RTTRACELOGTYPE *PCRTTRACELOGTYPE;
95
96
97/**
98 * Trace log event severity.
99 */
100typedef 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. */
118typedef RTTRACELOGEVTSEVERITY *PRTTRACELOGEVTSEVERITY;
119/** Pointer to a const event severiy class. */
120typedef RTTRACELOGEVTSEVERITY *PCRTTRACELOGEVTSEVERITY;
121
122
123/**
124 * Trace log reader event.
125 */
126typedef 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. */
138typedef RTTRACELOGRDRPOLLEVT *PRTTRACELOGRDRPOLLEVT;
139
140
141/**
142 * Trace log event item descriptor.
143 */
144typedef 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. */
159typedef RTTRACELOGEVTITEMDESC *PRTTRACELOGEVTITEMDESC;
160/** Pointer to a const trace log event item descriptor. */
161typedef const RTTRACELOGEVTITEMDESC *PCRTTRACELOGEVTITEMDESC;
162/** Pointer to a trace log event item descriptor pointer. */
163typedef PRTTRACELOGEVTITEMDESC *PPRTTRACELOGEVTITEMDESC;
164/** Pointer to a const trace log event item descriptor pointer. */
165typedef PCRTTRACELOGEVTITEMDESC *PPCRTTRACELOGEVTITEMDESC;
166
167
168/**
169 * Trace log event descriptor.
170 */
171typedef 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. */
185typedef RTTRACELOGEVTDESC *PRTTRACELOGEVTDESC;
186/** Pointer to a const trace log event descriptor. */
187typedef const RTTRACELOGEVTDESC *PCRTTRACELOGEVTDESC;
188
189
190/**
191 * Trace log event item value.
192 */
193typedef 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. */
221typedef RTTRACELOGEVTVAL *PRTTRACELOGEVTVAL;
222/** Pointer to a const trace log event item value. */
223typedef const RTTRACELOGEVTVAL *PCRTTRACELOGEVTVAL;
224
225
226/**
227 * Item mapping descriptor.
228 */
229typedef 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. */
237typedef RTTRACELOGRDRMAPITEM *PRTTRACELOGRDRMAPITEM;
238/** Pointer to a const mapping item descriptor. */
239typedef const RTTRACELOGRDRMAPITEM *PCRTTRACELOGRDRMAPITEM;
240
241
242/**
243 * Event item to value mapping descriptor for RTTraceLogRdrEvtMapToStruct().
244 */
245typedef 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. */
255typedef RTTRACELOGRDRMAPDESC *PRTTRACELOGRDRMAPDESC;
256/** Pointer to a const event mapping descriptor. */
257typedef const RTTRACELOGRDRMAPDESC *PCRTTRACELOGRDRMAPDESC;
258
259
260/**
261 * Header for an event mapped to a binary.
262 */
263typedef 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. */
277typedef RTTRACELOGRDREVTHDR *PRTTRACELOGRDREVTHDR;
278/** Pointer to a const event header. */
279typedef const RTTRACELOGRDREVTHDR *PCRTTRACELOGRDREVTHDR;
280
281
282/** Event group ID. */
283typedef uint64_t RTTRACELOGEVTGRPID;
284/** Pointer to the event group ID. */
285typedef RTTRACELOGEVTGRPID *PRTTRACELOGEVTGRPID;
286/** Trace log event handle. */
287typedef uint64_t RTRACELOGEVT;
288/** Pointer to a trace log event handle. */
289typedef RTRACELOGEVT *PRTRACELOGEVT;
290/** Trace log writer handle. */
291typedef struct RTTRACELOGWRINT *RTTRACELOGWR;
292/** Pointer to a trace log writer handle. */
293typedef RTTRACELOGWR *PRTTRACELOGWR;
294/** NIL trace log writer handle value. */
295#define NIL_RTTRACELOGWR ((RTTRACELOGWR)0)
296/** Trace log reader handle. */
297typedef struct RTTRACELOGRDRINT *RTTRACELOGRDR;
298/** Pointer to a trace log reader handle. */
299typedef RTTRACELOGRDR *PRTTRACELOGRDR;
300/** NIL trace log reader handle value. */
301#define NIL_RTTRACELOGRDR ((RTTRACELOGRDR)0)
302/** Trace log reader iterator handle. */
303typedef struct RTTRACELOGRDRITINT *RTTRACELOGRDRIT;
304/** Pointer to a trace log reader iterator handle. */
305typedef RTTRACELOGRDRIT *PRTTRACELOGRDRIT;
306/** NIL trace log reader iterator handle. */
307#define NIL_RTTRACELOGRDRIT ((RTTRACELOGRDRIT)0)
308/** Trace log reader event handle. */
309typedef struct RTTRACELOGRDREVTINT *RTTRACELOGRDREVT;
310/** Pointer to a trace log reader event handle. */
311typedef 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 */
329typedef DECLCALLBACKTYPE(int, FNRTTRACELOGWRSTREAM,(void *pvUser, const void *pvBuf, size_t cbBuf, size_t *pcbWritten));
330/** Pointer to a writer stream callback. */
331typedef 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 */
347typedef DECLCALLBACKTYPE(int, FNRTTRACELOGRDRSTREAM,(void *pvUser, void *pvBuf, size_t cbBuf, size_t *pcbRead,
348 RTMSINTERVAL cMsTimeout));
349/** Pointer to a writer stream callback. */
350typedef 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 */
359typedef DECLCALLBACKTYPE(int, FNRTTRACELOGSTREAMCLOSE,(void *pvUser));
360/** Pointer to a stream close callback. */
361typedef 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 */
374RTDECL(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 */
387RTDECL(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 */
402RTDECL(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 */
417RTDECL(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 */
427RTDECL(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 */
441RTDECL(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 */
459RTDECL(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 */
479RTDECL(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 */
498RTDECL(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 */
516RTDECL(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 */
529RTDECL(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 */
540RTDECL(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 */
549RTDECL(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 */
562RTDECL(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 */
572RTDECL(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 */
581RTDECL(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 */
596RTDECL(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 */
607RTDECL(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 */
615RTDECL(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 */
625RTDECL(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 */
635RTDECL(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 */
644RTDECL(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 */
653RTDECL(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 */
662RTDECL(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 */
671RTDECL(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 */
683RTDECL(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 */
696RTDECL(int) RTTraceLogRdrEvtFillVals(RTTRACELOGRDREVT hRdrEvt, unsigned idxItemStart, PRTTRACELOGEVTVAL paVals,
697 unsigned cVals, unsigned *pcVals);
698
699RT_C_DECLS_END
700
701/** @} */
702
703#endif /* !IPRT_INCLUDED_tracelog_h */
704
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette