Stronger types

Cargo.toml

@@ -9,6 +9,10 @@ repository = "https://github.com/n4r1b/ferrisetw"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
+[features]
+# Enable the conversion of timestamps to time::OffsetDateTime
+time_rs = ["time"]
+
 [dependencies]
 windows = { version = "0.39", features = [
     "Win32_Foundation",
@@ -30,6 +34,7 @@ num-derive = "0.3"
 bitflags = "1.3.2"
 widestring = "1.0"
 zerocopy = "0.6"
+time = { version = "0.3", features = ["large-dates"], optional = true }
 # thiserror = "~1.0"
 # anyhow = "~1.0"
 

examples/dns.rs

@@ -9,7 +9,6 @@ use ferrisetw::schema_locator::SchemaLocator;
 use ferrisetw::native::etw_types::EventRecord;
 use ferrisetw::trace::UserTrace;
 use ferrisetw::parser::TryParse;
-use ferrisetw::trace::TraceBaseTrait;
 use ferrisetw::schema::Schema;
 
 
@@ -74,16 +73,16 @@ fn main() {
         .trace_flags(TraceFlags::EVENT_ENABLE_PROPERTY_PROCESS_START_KEY)
         .build();
 
-    let mut trace = UserTrace::new()
+    let trace = UserTrace::new()
         .enable(dns_provider)
-        .start()
+        .start_and_process()
         .unwrap();
 
     println!("ID   Status Options         Ty Name       Results");
 
-    std::thread::sleep(Duration::new(120, 0));
-    trace.stop();
+    std::thread::sleep(Duration::new(20, 0));
 
+    trace.stop().unwrap(); // This is not required, as it will automatically be stopped on Drop
     println!("Done: {:?} events", N_EVENTS);
 }
 

examples/kernel_trace.rs

@@ -31,12 +31,12 @@ fn main() {
         .add_callback(image_load_callback)
         .build();
 
-    let mut trace = KernelTrace::new()
+    let kernel_trace = KernelTrace::new()
         .named(String::from("MyKernelProvider"))
         .enable(provider)
-        .start()
+        .start_and_process()
         .unwrap();
 
     std::thread::sleep(Duration::new(20, 0));
-    trace.stop();
+    kernel_trace.stop().unwrap(); // This is not required, as it will automatically be stopped on Drop
 }

examples/multiple_providers.rs

@@ -60,12 +60,13 @@ fn main() {
         .add_callback(registry_callback)
         .build();
 
-    let mut trace = UserTrace::new()
+    let user_trace = UserTrace::new()
         .enable(process_provider)
         .enable(tcpip_provider)
-        .start()
+        .start_and_process()
         .unwrap();
 
     std::thread::sleep(Duration::new(10, 0));
-    trace.stop();
+
+    user_trace.stop().unwrap(); // optional. Simply dropping user_trace has the same effect
 }

examples/user_trace.rs

@@ -33,12 +33,22 @@ fn main() {
         .add_callback(process_callback)
         .build();
 
-    let mut trace = UserTrace::new()
+    let (_user_trace, handle) = UserTrace::new()
         .named(String::from("MyProvider"))
         .enable(process_provider)
         .start()
         .unwrap();
 
+    // This example uses `process_from_handle` rather than the more convient `start_and_process`, because why not.
+    std::thread::spawn(move || {
+        let status = UserTrace::process_from_handle(handle);
+        // This code will be executed when the trace stops. Examples:
+        // * when it is dropped
+        // * when it is manually stopped (either by user_trace.stop, or by the `logman stop -ets MyProvider` command)
+        println!("Trace ended with status {:?}", status);
+    });
+
     std::thread::sleep(Duration::new(20, 0));
-    trace.stop();
+
+    // user_trace will be dropped (and stopped) here
 }

src/lib.rs

@@ -50,7 +50,7 @@
 //! use ferrisetw::parser::Parser;
 //! use ferrisetw::parser::TryParse;
 //! use ferrisetw::provider::Provider;
-//! use ferrisetw::trace::{UserTrace, TraceTrait, TraceBaseTrait};
+//! use ferrisetw::trace::{UserTrace, TraceTrait};
 //!
 //! fn process_callback(record: &EventRecord, schema_locator: &SchemaLocator) {
 //!     // Within the callback we first locate the proper Schema for the event
@@ -84,12 +84,14 @@
 //!         .build();
 //!
 //!     // We start a trace session for the previously registered provider
-//!     // This call will spawn a new thread which listens to the events
+//!     // Callbacks will be run in a separate thread.
 //!     let mut trace = UserTrace::new()
 //!         .named(String::from("MyProvider"))
 //!         .enable(process_provider)
-//!         // .enable(other_provider) // it is possible to enable multiple providers on the same trace
-//!         .start()
+//!         // .enable(other_provider) // It is possible to enable multiple providers on the same trace.
+//!         .start_and_process()       // This call will spawn the thread for you.
+//!                                    // See the doc for alternative ways of processing the trace,
+//!                                    // with more or less flexibility regarding this spawned thread.
 //!         .unwrap();
 //!
 //!     std::thread::sleep(std::time::Duration::from_secs(3));