Skip to main content

etw_wrapper/
lib.rs

1// On docs.rs (which sets `--cfg docsrs`) opt into the nightly `doc_cfg` feature so items gated
2// behind a Cargo feature render an "Available on crate feature ..." banner in the docs.
3#![cfg_attr(docsrs, feature(doc_cfg))]
4
5//! A strongly typed Event Tracing for Windows wrapper.
6//!
7//! The `gen_etw_wrapper!` macro turns an ETW manifest into a strongly typed provider struct.
8//! See the examples directory for a basic demonstration.
9//!
10//! ```no_run
11//! use etw_wrapper::{Result, gen_etw_wrapper};
12//!
13//! gen_etw_wrapper!("manifests/widgetservice.man", PROVIDER_WIDGETSERVICE -> WidgetLogger);
14//!
15//! fn main() -> Result<()> {
16//!     let provider = WidgetLogger::register()?;
17//!     provider.request_failed(0x12ABCDEF, 500, 42, "failed to succeed")?;
18//!     Ok(())
19//! }
20//! ```
21//!
22//! To avoid the procedural macro, call [`EtwLogger::register`], check [`EtwLogger::enabled`]
23//! before each call to [`EtwLogger::write`], and convert parameters to
24//! [`EVENT_DATA_DESCRIPTOR`] instances with the helpers in the [`field`] module.
25//!
26//! ```no_run
27//! use etw_wrapper::{EVENT_DESCRIPTOR, EtwLogger, GUID, field::*};
28//! let ctx = EtwLogger::register(&GUID::default()).unwrap();
29//! let x = 1u32;
30//! let y = to_u16cstring("hello");
31//!
32//! let descriptor = EVENT_DESCRIPTOR::default();
33//! ctx.write(&descriptor, &[scalar(&x), str16(&y)]).unwrap();
34//! ```
35
36#[cfg(feature = "macro")]
37#[cfg_attr(docsrs, doc(cfg(feature = "macro")))]
38pub use etw_wrapper_macro::gen_etw_wrapper;
39
40// Gives generated code a stable path when the macro is invoked from this package's own targets.
41extern crate self as etw_wrapper;
42
43mod context;
44pub mod field;
45
46pub use context::EtwLogger;
47
48// Re-export Windows types so callers do not need a direct windows dependency
49pub use windows::Win32::Foundation::{FILETIME, SYSTEMTIME};
50pub use windows::Win32::Security::PSID;
51pub use windows::Win32::System::Diagnostics::Etw::{EVENT_DATA_DESCRIPTOR, EVENT_DESCRIPTOR};
52pub use windows::core::{GUID, Result};