### Basic FerrisETW Provider and Trace Example

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/index.html

This example demonstrates how to set up an ETW provider for kernel process events, define a callback function to process incoming events, and start a trace session. Ensure you have the necessary permissions to run ETW traces.

```rust
use ferrisetw::EventRecord;
use ferrisetw::schema_locator::SchemaLocator;
use ferrisetw::parser::Parser;
use ferrisetw::provider::Provider;
use ferrisetw::trace::{UserTrace, TraceTrait};

fn process_callback(record: &EventRecord, schema_locator: &SchemaLocator) {
    // Basic event scrutinizing can be done directly from the `EventRecord`
    if record.event_id() == 2 {
        // More advanced info can be retrieved from the event schema
        // (the SchemaLocator caches the schema for a given kind of event, so this call is cheap in case you've already encountered the same event kind previously)
        match schema_locator.event_schema(record) {
            Err(err) => println!("Error {:?}", err),
            Ok(schema) => {
                println!("Received an event from provider {}", schema.provider_name());

                // Finally, properties for a given event can be retrieved using a Parser
                let parser = Parser::create(record, &schema);

                // You'll need type inference to tell ferrisetw what type you want to parse into
                // In actual code, be sure to correctly handle Err values!
                let process_id: u32 = parser.try_parse("ProcessID").unwrap();
                let image_name: String = parser.try_parse("ImageName").unwrap();
                println!("PID: {} ImageName: {}", process_id, image_name);
            }
        }
    }
}

fn main() {
    // First we build a Provider
    let process_provider = Provider
        ::by_guid("22fb2cd6-0e7b-422b-40c7-2fad1fd0e716") // Microsoft-Windows-Kernel-Process
        .add_callback(process_callback)
        // .add_callback(process_callback) // it is possible to add multiple callbacks for a given provider
        // .add_filter(event_filters)      // it is possible to filter by event ID, process ID, etc.
        .build();

    // We start a real-time trace session for the previously registered provider
    // Callbacks will be run in a separate thread.
    let mut trace = UserTrace::new()
        .named(String::from("MyTrace"))
        .enable(process_provider)
        // .enable(other_provider) // It is possible to enable multiple providers on the same trace.
        // .set_etl_dump_file(...) // It is possible to dump the events that the callbacks are processing into a file
        .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));

    // We stop the trace
    trace.stop();
}
```

--------------------------------

### Build a provider and start a trace

Source: https://docs.rs/ferrisetw

Demonstrates how to define a provider with a callback, start a real-time trace session, and process events.

```rust
use ferrisetw::EventRecord;
use ferrisetw::schema_locator::SchemaLocator;
use ferrisetw::parser::Parser;
use ferrisetw::provider::Provider;
use ferrisetw::trace::{UserTrace, TraceTrait};

fn process_callback(record: &EventRecord, schema_locator: &SchemaLocator) {
    // Basic event scrutinizing can be done directly from the `EventRecord`
    if record.event_id() == 2 {
        // More advanced info can be retrieved from the event schema
        // (the SchemaLocator caches the schema for a given kind of event, so this call is cheap in case you've already encountered the same event kind previously)
        match schema_locator.event_schema(record) {
            Err(err) => println!("Error {:?}", err),
            Ok(schema) => {
                println!("Received an event from provider {}", schema.provider_name());

                // Finally, properties for a given event can be retrieved using a Parser
                let parser = Parser::create(record, &schema);

                // You'll need type inference to tell ferrisetw what type you want to parse into
                // In actual code, be sure to correctly handle Err values!
                let process_id: u32 = parser.try_parse("ProcessID").unwrap();
                let image_name: String = parser.try_parse("ImageName").unwrap();
                println!("PID: {} ImageName: {}", process_id, image_name);
            }
        }
    }
}

fn main() {
    // First we build a Provider
    let process_provider = Provider
        ::by_guid("22fb2cd6-0e7b-422b-a0c7-2fad1fd0e716") // Microsoft-Windows-Kernel-Process
        .add_callback(process_callback)
        // .add_callback(process_callback) // it is possible to add multiple callbacks for a given provider
        // .add_filter(event_filters)      // it is possible to filter by event ID, process ID, etc.
        .build();

    // We start a real-time trace session for the previously registered provider
    // Callbacks will be run in a separate thread.
    let mut trace = UserTrace::new()
        .named(String::from("MyTrace"))
        .enable(process_provider)
        // .enable(other_provider) // It is possible to enable multiple providers on the same trace.
        // .set_etl_dump_file(...) // It is possible to dump the events that the callbacks are processing into a file
        .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));

    // We stop the trace
    trace.stop();
}
```

--------------------------------

### Start FileTrace Session

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.FileTraceBuilder.html

Builds the `FileTrace` and starts the trace session. Refer to `TraceBuilder::start` for more information.

```rust
pub fn start(self) -> Result<(FileTrace, TraceHandle), TraceError>
```

--------------------------------

### Example: Create Provider by Name

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Demonstrates how to create a Provider using its string name. This example shows the typical usage pattern for `by_name` followed by `build`.

```rust
let my_provider = Provider::by_name("Microsoft-Windows-WinINet").unwrap().build();
```

--------------------------------

### Create Provider by GUID

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Creates a Provider instance using its globally unique identifier (GUID). Many types can be converted into a GUID, such as `GUID` itself or `&str`.

```rust
pub fn by_guid<G: Into<GUID>>(guid: G) -> ProviderBuilder
```

--------------------------------

### GUID Creation and Conversion Methods

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/struct.GUID.html

Provides methods for creating and converting GUID values.

```APIDOC
## impl GUID

### Methods
* **pub fn new() -> Result<GUID, Error>** - Creates a unique `GUID` value.
* **pub const fn zeroed() -> GUID** - Creates a `GUID` represented by the all-zero byte-pattern.
* **pub const fn from_values(data1: u32, data2: u16, data3: u16, data4: [u8; 8]) -> GUID** - Creates a `GUID` with the given constant values.
* **pub const fn from_u128(uuid: u128) -> GUID** - Creates a `GUID` from a `u128` value.
* **pub const fn to_u128(&self) -> u128** - Converts a `GUID` to a `u128` value.
* **pub const fn from_signature(signature: ConstBuffer) -> GUID** - Creates a `GUID` for a “generic” WinRT type.
```

--------------------------------

### Create Provider by Name

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Creates a Provider instance by looking up its GUID using the ITraceDataProviderCollection interface. This method is slower than `by_guid` and should be preferred only when the GUID is unknown.

```rust
pub fn by_name(name: &str) -> Result<ProviderBuilder, PlaError>
```

--------------------------------

### TraceBuilder Configuration and Execution

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.TraceBuilder.html

Methods for configuring a trace session and starting the execution of the ETW trace.

```APIDOC
## TraceBuilder Configuration

### Description
Methods to configure the trace session properties and start the trace.

### Methods
- **named(name: String)**: Sets the trace name. Note: Truncated if too long; ignored for kernel traces on Windows versions older than Win8.
- **set_trace_properties(props: TraceProperties)**: Defines low-level EVENT_TRACE_PROPERTIES.
- **set_etl_dump_file(params: DumpFileParams)**: Configures a file path for dumping events (usually .etl).
- **enable(provider: Provider)**: Enables a specific ETW provider for the trace.
- **start() -> Result<(T, TraceHandle), TraceError>**: Starts the trace session and returns the trace object and handle.
- **start_and_process() -> Result<T, TraceError>**: Convenience method that starts the trace and processes events on a spawned thread.
```

--------------------------------

### Start and Process FileTrace Session

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.FileTraceBuilder.html

A convenience method that calls `TraceBuilder::start` followed by `process`. The `process` method is executed on a spawned thread, and errors from `process` cannot be retrieved by this method.

```rust
pub fn start_and_process(self) -> Result<FileTrace, TraceError>
```

--------------------------------

### Create KernelTrace Builder

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.KernelTrace.html

Initializes a builder for creating a KernelTrace session. This builder is used to configure and start the trace.

```rust
pub fn new() -> TraceBuilder<KernelTrace>
```

--------------------------------

### Create UserTrace Builder

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.UserTrace.html

Creates a builder for a UserTrace session. Use this to configure and start a new trace.

```rust
pub fn new() -> TraceBuilder<UserTrace>
```

--------------------------------

### GUID Trait Implementations

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/struct.GUID.html

Details the trait implementations for the GUID struct, including Clone, Debug, Default, From, Hash, PartialEq, Copy, Eq, and StructuralPartialEq.

```APIDOC
## Trait Implementations for GUID

### impl Clone for GUID
* **fn clone(&self) -> GUID** - Returns a duplicate of the value.
* **fn clone_from(&mut self, source: &Self)** - Performs copy-assignment from `source`.

### impl Debug for GUID
* **fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>** - Formats the value using the given formatter.

### impl Default for GUID
* **fn default() -> GUID** - Returns the “default value” for a type.

### impl From<&str> for GUID
* **fn from(value: &str) -> GUID** - Converts to this type from the input type.

### impl From<u128> for GUID
* **fn from(value: u128) -> GUID** - Converts to this type from the input type.

### impl Hash for GUID
* **fn hash<__H>(&self, state: &mut __H)** - Feeds this value into the given `Hasher`.
* **fn hash_slice<H>(data: &[Self], state: &mut H)** - Feeds a slice of this type into the given `Hasher`.

### impl PartialEq for GUID
* **fn eq(&self, other: &GUID) -> bool** - Tests for `self` and `other` values to be equal, and is used by `==`.
* **fn ne(&self, other: &Rhs) -> bool** - Tests for `!=`.

### impl Copy for GUID

### impl Eq for GUID

### impl StructuralPartialEq for GUID
```

--------------------------------

### FileTraceBuilder Methods

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.FileTraceBuilder.html

Methods available for the FileTraceBuilder struct to start trace sessions.

```APIDOC
## pub fn start(self) -> Result<(FileTrace, TraceHandle), TraceError>

### Description
Builds the FileTrace and starts the trace session.

### Response
- **Result<(FileTrace, TraceHandle), TraceError>** - Returns a tuple containing the FileTrace and TraceHandle on success, or a TraceError on failure.

---

## pub fn start_and_process(self) -> Result<FileTrace, TraceError>

### Description
Convenience method that calls start then process. The process method is called on a spawned thread.

### Response
- **Result<FileTrace, TraceError>** - Returns the FileTrace on success, or a TraceError on failure.
```

--------------------------------

### FileTrace::process

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.FileTrace.html

Starts processing events from the trace session. This method is blocking and triggers the registered callbacks for each event.

```APIDOC
## FileTrace::process

### Description
This is blocking and starts triggering the callbacks.

### Method
`pub fn process(&mut self) -> Result<(), TraceError>`

### Returns
`Ok(())` if the trace was processed successfully, or a `TraceError` if an error occurred during processing.
```

--------------------------------

### Get Trace Handle

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.FileTrace.html

Retrieves the handle for the current trace session.

```rust
fn trace_handle(&self) -> TraceHandle
```

--------------------------------

### Create Empty Flags Set

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.DumpFileLoggingMode.html

Returns an empty set of flags, useful for starting with no logging modes enabled.

```rust
pub const fn empty() -> Self
```

--------------------------------

### Define KernelProvider struct

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/kernel_providers/struct.KernelProvider.html

The structure definition for KernelProvider, containing the GUID and flags.

```rust
pub struct KernelProvider {
    pub guid: GUID,
    pub flags: u32,
}
```

--------------------------------

### Process Trace Events

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.FileTrace.html

This method is blocking and starts triggering the provided callbacks for each event read from the trace file.

```rust
fn process(&mut self) -> Result<(), TraceError>
```

--------------------------------

### Get Provider GUID

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Retrieves the GUID associated with this Provider instance.

```rust
pub fn guid(&self) -> GUID
```

--------------------------------

### Get Trace GUID

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.UserTrace.html

Returns the unique identifier (GUID) for the trace type.

```rust
fn trace_guid() -> GUID
```

--------------------------------

### GUID Struct Definition

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/struct.GUID.html

Defines the structure of a GUID, including its data fields.

```APIDOC
## Struct GUID

### Description
Re-exported `GUID` from `windows-rs`, which is used in return values for some functions of this crate. A globally unique identifier (GUID) used to identify COM and WinRT interfaces.

### Fields
* **data1** (u32) - Specifies the first 8 hexadecimal digits.
* **data2** (u16) - Specifies the first group of 4 hexadecimal digits.
* **data3** (u16) - Specifies the second group of 4 hexadecimal digits.
* **data4** ([u8; 8]) - The first 2 bytes contain the third group of 4 hexadecimal digits. The remaining 6 bytes contain the final 12 hexadecimal digits.
```

--------------------------------

### DISK_IO_INIT_PROVIDER

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/kernel_providers/static.DISK_IO_INIT_PROVIDER.html

Documentation for the static DISK_IO_INIT_PROVIDER constant.

```APIDOC
## DISK_IO_INIT_PROVIDER

### Description
Represents the Disk IO Init Kernel Provider within the ferrisetw::provider::kernel_providers module.

### Definition
`pub static DISK_IO_INIT_PROVIDER: KernelProvider`
```

--------------------------------

### Create Parser Instance

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/parser/struct.Parser.html

Shows how to create a `Parser` instance using the `create` function, which requires an `EventRecord` and its corresponding `Schema`. This is the initial step before parsing event properties.

```rust
let my_callback = |record: &EventRecord, schema_locator: &SchemaLocator| {
    let schema = schema_locator.event_schema(record).unwrap();
    let parser = Parser::create(record, &schema);
};
```

--------------------------------

### FILE_INIT_IO_PROVIDER

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/kernel_providers/static.FILE_INIT_IO_PROVIDER.html

Documentation for the static FILE_INIT_IO_PROVIDER constant.

```APIDOC
## FILE_INIT_IO_PROVIDER

### Description
Represents the File Init IO Kernel Provider.

### Definition
`pub static FILE_INIT_IO_PROVIDER: KernelProvider`
```

--------------------------------

### GUID Struct Definition

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/struct.GUID.html

The structure definition for the GUID type, representing a 128-bit identifier as a C-compatible struct.

```rust
#[repr(C)]
pub struct GUID {
    pub data1: u32,
    pub data2: u16,
    pub data3: u16,
    pub data4: [u8; 8],
}
```

--------------------------------

### Statics

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/all.html

List of all available static items in the ferrisetw crate, primarily kernel providers.

```APIDOC
## Statics

### provider::kernel_providers::ALPC_PROVIDER
Static for ALPC kernel provider.

### provider::kernel_providers::CONTEXT_SWITCH_PROVIDER
Static for context switch kernel provider.

### provider::kernel_providers::DEBUG_PRINT_PROVIDER
Static for debug print kernel provider.

### provider::kernel_providers::DISK_FILE_IO_PROVIDER
Static for disk file I/O kernel provider.

### provider::kernel_providers::DISK_IO_INIT_PROVIDER
Static for disk I/O initialization kernel provider.

### provider::kernel_providers::DISK_IO_PROVIDER
Static for disk I/O kernel provider.

### provider::kernel_providers::DPC_PROVIDER
Static for DPC kernel provider.

### provider::kernel_providers::DRIVER_PROVIDER
Static for driver kernel provider.

### provider::kernel_providers::FILE_INIT_IO_PROVIDER
Static for file I/O initialization kernel provider.

### provider::kernel_providers::FILE_IO_PROVIDER
Static for file I/O kernel provider.

### provider::kernel_providers::IMAGE_LOAD_PROVIDER
Static for image load kernel provider.

### provider::kernel_providers::INTERRUPT_PROVIDER
Static for interrupt kernel provider.

### provider::kernel_providers::MEMORY_HARD_FAULT_PROVIDER
Static for memory hard fault kernel provider.

### provider::kernel_providers::MEMORY_PAGE_FAULT_PROVIDER
Static for memory page fault kernel provider.

### provider::kernel_providers::PROCESS_COUNTER_PROVIDER
Static for process counter kernel provider.

### provider::kernel_providers::PROCESS_PROVIDER
Static for process kernel provider.

### provider::kernel_providers::PROFILE_PROVIDER
Static for profile kernel provider.

### provider::kernel_providers::REGISTRY_PROVIDER
Static for registry kernel provider.

### provider::kernel_providers::SPLIT_IO_PROVIDER
Static for split I/O kernel provider.

### provider::kernel_providers::SYSTEM_CALL_PROVIDER
Static for system call kernel provider.

### provider::kernel_providers::TCP_IP_PROVIDER
Static for TCP/IP kernel provider.

### provider::kernel_providers::THREAD_DISPATCHER_PROVIDER
Static for thread dispatcher kernel provider.

### provider::kernel_providers::THREAD_PROVIDER
Static for thread kernel provider.

### provider::kernel_providers::VAMAP_PROVIDER
Static for VAMAP kernel provider.

### provider::kernel_providers::VIRTUAL_ALLOC_PROVIDER
Static for virtual allocation kernel provider.
```

--------------------------------

### Build Provider instance

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.ProviderBuilder.html

Finalizes the configuration and constructs the Provider.

```rust
Provider::by_guid("22fb2cd6-0e7b-422b-a0c7-2fad1fd0e716") // Microsoft-Windows-Kernel-Process
  .add_callback(process_callback)
  .build();
```

--------------------------------

### KernelProvider Struct and Statics

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/kernel_providers/index.html

Overview of the KernelProvider structure and the available static provider instances.

```APIDOC
## Struct: KernelProvider

### Description
Contains kernel provider identifiers used for ETW tracing.

## Available Statics

The following static instances are available for use:
- ALPC_PROVIDER: ALPC Kernel Provider
- CONTEXT_SWITCH_PROVIDER: Context Switch Kernel Provider
- DEBUG_PRINT_PROVIDER: Dbg Print Kernel Provider
- DISK_FILE_IO_PROVIDER: Disk File IO Kernel Provider
- DISK_IO_INIT_PROVIDER: Disk IO Init Kernel Provider
- DISK_IO_PROVIDER: Disk IO Kernel Provider
- DPC_PROVIDER: DPC Kernel Provider
- DRIVER_PROVIDER: Driver Kernel Provider
- FILE_INIT_IO_PROVIDER: File Init IO Kernel Provider
- FILE_IO_PROVIDER: File IO Kernel Provider
- IMAGE_LOAD_PROVIDER: Image Load Kernel Provider
- INTERRUPT_PROVIDER: Interrupt Kernel Provider
- MEMORY_HARD_FAULT_PROVIDER: Memory Hard Fault Kernel Provider
- MEMORY_PAGE_FAULT_PROVIDER: Memory Page Fault Kernel Provider
- PROCESS_COUNTER_PROVIDER: Process Counter Kernel Provider
- PROCESS_PROVIDER: Process Kernel Provider
- PROFILE_PROVIDER: Profile Kernel Provider
- REGISTRY_PROVIDER: Registry Kernel Provider
- SPLIT_IO_PROVIDER: Split IO Kernel Provider
- SYSTEM_CALL_PROVIDER: SystemCall Kernel Provider
- TCP_IP_PROVIDER: TCP-IP Kernel Provider
- THREAD_DISPATCHER_PROVIDER: Thread Dispatcher Kernel Provider
- THREAD_PROVIDER: Thread Kernel Provider
- VAMAP_PROVIDER: VA Map Kernel Provider
- VIRTUAL_ALLOC_PROVIDER: VirtualAlloc Kernel Provider
```

--------------------------------

### Initialize KernelProvider

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/kernel_providers/struct.KernelProvider.html

Constructor for creating a new KernelProvider instance.

```rust
pub const fn new(guid: GUID, flags: u32) -> KernelProvider
```

--------------------------------

### Get Trace Name

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.UserTrace.html

Returns the OS-specific name of the trace.

```rust
fn trace_name(&self) -> OsString
```

--------------------------------

### Get Provider Filters

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Retrieves the event filters applied to this Provider.

```rust
pub fn filters(&self) -> &[EventFilter]
```

--------------------------------

### Provider Creation Methods

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Methods to initialize a Provider instance using different identification strategies.

```APIDOC
## Provider::by_guid

### Description
Creates a Provider defined by its GUID.

### Parameters
#### Path Parameters
- **guid** (G: Into<GUID>) - Required - The GUID of the provider.

### Response
- **ProviderBuilder** - Returns a builder instance for further configuration.

## Provider::kernel

### Description
Creates a Kernel Provider.

### Parameters
#### Path Parameters
- **kernel_provider** (&KernelProvider) - Required - The kernel provider instance.

### Response
- **ProviderBuilder** - Returns a builder instance.

## Provider::by_name

### Description
Creates a Provider defined by its name by looking up the GUID via ITraceDataProviderCollection.

### Parameters
#### Path Parameters
- **name** (&str) - Required - The name of the provider.

### Response
- **Result<ProviderBuilder, PlaError>** - Returns a builder or an error if the lookup fails.
```

--------------------------------

### Create Kernel Provider

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Creates a Provider instance for a kernel event tracing session. You can provide a custom `KernelProvider` or use predefined ones from `crate::provider::kernel_providers`.

```rust
pub fn kernel(kernel_provider: &KernelProvider) -> ProviderBuilder
```

--------------------------------

### Get Provider Kernel Flags

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Retrieves the kernel-specific flags for this Provider.

```rust
pub fn kernel_flags(&self) -> u32
```

--------------------------------

### Structs

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/all.html

List of all available structs in the ferrisetw crate.

```APIDOC
## Structs

### EventRecord
Represents a single event record.

### GUID
Represents a Globally Unique Identifier.

### SID
Represents a Security Identifier.

### native::EVENT_EXTENDED_ITEM_INSTANCE
Extended item for instance data.

### native::EVENT_EXTENDED_ITEM_STACK_TRACE32
Extended item for 32-bit stack traces.

### native::EVENT_EXTENDED_ITEM_STACK_TRACE64
Extended item for 64-bit stack traces.

### native::EventHeaderExtendedDataItem
Extended data item in the event header.

### native::time::FileTime
Represents a Windows file time.

### native::time::SystemTime
Represents a system time.

### parser::Parser
Represents a trace data parser.

### parser::Pointer
Represents a pointer in trace data.

### provider::Provider
Represents an event provider.

### provider::ProviderBuilder
Builder for creating event providers.

### provider::TraceFlags
Flags for trace configuration.

### provider::kernel_providers::KernelProvider
Represents a kernel event provider.

### query::SessionlessInfo
Information for sessionless queries.

### schema::Schema
Represents an event schema.

### schema_locator::SchemaLocator
Locates event schemas.

### trace::DumpFileLoggingMode
Logging mode for dump files.

### trace::DumpFileParams
Parameters for dump file tracing.

### trace::FileTrace
Represents a file trace.

### trace::FileTraceBuilder
Builder for creating file traces.

### trace::KernelTrace
Represents a kernel trace.

### trace::LoggingMode
General logging mode.

### trace::TraceBuilder
Builder for creating traces.

### trace::TraceProperties
Properties of a trace.

### trace::UserTrace
Represents a user-mode trace.
```

--------------------------------

### Get Provider Level

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Retrieves the logging level configured for this Provider.

```rust
pub fn level(&self) -> u8
```

--------------------------------

### Functions

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/all.html

List of all available functions in the ferrisetw crate.

```APIDOC
## Functions

### trace::stop_trace_by_name
Stops a trace by its name.
```

--------------------------------

### Create FileTrace Instance

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.FileTrace.html

Creates a new trace session that reads events from a specified file. Requires a mutable callback function that processes each event.

```rust
pub fn new<T>(path: PathBuf, callback: T) -> FileTraceBuilder
where T: FnMut(&EventRecord, &SchemaLocator) + Send + Sync + 'static,
```

--------------------------------

### Get Provider Trace Flags

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Retrieves the trace flags associated with this Provider.

```rust
pub fn trace_flags(&self) -> TraceFlags
```

--------------------------------

### Define RealTimeTraceTrait

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/trait.RealTimeTraceTrait.html

The trait definition requiring TraceTrait and PrivateRealTimeTraceTrait, with methods for GUID and name retrieval.

```rust
pub trait RealTimeTraceTrait: TraceTrait + PrivateRealTimeTraceTrait {
    // Required methods
    fn trace_guid() -> GUID;
    fn trace_name(&self) -> OsString;
}
```

--------------------------------

### Get Events Handled Count

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.FileTrace.html

Returns the total number of events that have been processed by the trace session.

```rust
fn events_handled(&self) -> usize
```

--------------------------------

### Get Provider Name from Schema

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/schema/struct.Schema.html

Use the `provider_name` function to obtain the Provider name from the TRACE_EVENT_INFO.

```rust
let my_callback = |record: &EventRecord, schema_locator: &SchemaLocator| {
    let schema = schema_locator.event_schema(record).unwrap();
    let provider_name = schema.provider_name();
};
```

--------------------------------

### FileTrace::new

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.FileTrace.html

Creates a new trace session that reads events from a specified ETL file. It takes a file path and a callback function that will be executed for each event.

```APIDOC
## FileTrace::new

### Description
Create a trace that will read events from a file.

### Method
`pub fn new<T>(path: PathBuf, callback: T) -> FileTraceBuilder`

### Parameters
* **path** (`PathBuf`) - The path to the ETL file.
* **callback** (`T`) - A closure that takes `&EventRecord` and `&SchemaLocator` and is executed for each event. It must satisfy `FnMut(&EventRecord, &SchemaLocator) + Send + Sync + 'static`.

### Returns
A `FileTraceBuilder` instance, which can be used to further configure and build the `FileTrace`.
```

--------------------------------

### Set any flag in ProviderBuilder

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.ProviderBuilder.html

Configures the 'any' keyword mask for the provider.

```rust
let my_provider = Provider::by_guid("1EDEEE53-0AFE-4609-B846-D8C0B2075B1F").any(0xf0010000000003ff).build();
```

--------------------------------

### Set all flag in ProviderBuilder

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.ProviderBuilder.html

Configures the 'all' keyword mask for the provider.

```rust
let my_provider = Provider::by_guid("1EDEEE53-0AFE-4609-B846-D8C0B2075B1F").all(0x4000000000000000).build();
```

--------------------------------

### Get Provider All Flag

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Retrieves the 'all' flag value for the Provider. This flag is used in filtering or configuration.

```rust
pub fn all(&self) -> u64
```

--------------------------------

### Get Provider Any Flag

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/struct.Provider.html

Retrieves the 'any' flag value for the Provider. This flag is used in filtering or configuration.

```rust
pub fn any(&self) -> u64
```

--------------------------------

### Enums

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/all.html

List of all available enums in the ferrisetw crate.

```APIDOC
## Enums

### native::DecodingSource
Source of decoding for native events.

### native::EvntraceNativeError
Native errors from the Evntrace API.

### native::ExtendedDataItem
Types of extended data items.

### native::PlaError
Platform Abstraction Layer errors.

### native::SddlNativeError
SDDL related native errors.

### native::TdhNativeError
TDH related native errors.

### parser::ParserError
Errors that can occur during parsing.

### provider::EventFilter
Filters for events.

### provider::ProviderError
Errors related to event providers.

### query::ProfileSource
Source of profiling data.

### schema_locator::SchemaError
Errors during schema location.

### trace::TraceError
Errors related to trace operations.
```

--------------------------------

### CONTEXT_SWITCH_PROVIDER

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/kernel_providers/static.CONTEXT_SWITCH_PROVIDER.html

Access the static KernelProvider instance for context switching.

```APIDOC
## Static Variable: CONTEXT_SWITCH_PROVIDER

### Description
Represents the Context Switch Kernel Provider within the ferrisetw::provider::kernel_providers module.

### Definition
`pub static CONTEXT_SWITCH_PROVIDER: KernelProvider`
```

--------------------------------

### Clone to Uninit (Nightly)

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/native/time/struct.FileTime.html

Nightly-only experimental API to perform copy-assignment from `self` to an uninitialized memory location `dest`. Requires `T: Clone`.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### From and Into Traits

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.TraceBuilder.html

Standard traits for value-to-value conversions.

```APIDOC
## From<T>

### Method
fn from(t: T) -> T

### Description
Returns the argument unchanged.

## Into<U>

### Method
fn into(self) -> U

### Description
Calls U::from(self). This conversion is defined by the implementation of From<T> for U.
```

--------------------------------

### Ferrisetw Module Overview

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/query/index.html

Provides an overview of the ferrisetw crate, its purpose as an ETW information classes wrapper, and key components like structs and enums.

```APIDOC
## Module: query

### Description
This module provides an ETW information classes wrapper.

### Structs

#### SessionlessInfo
Represents sessionless ETW information.

### Enums

#### ProfileSource
Defines the source of a profile.
```

--------------------------------

### Schema Blanket Implementations

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/schema/struct.Schema.html

Details the blanket implementations for the Schema struct, including Any, Borrow, BorrowMut, From, Into, TryFrom, TryInto, and VZip.

```APIDOC
## Blanket Implementations

### impl<T> Any for T

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`.

### impl<T> Borrow<T> for T

#### fn borrow(&self) -> &T

Immutably borrows from an owned value.

### impl<T> BorrowMut<T> for T

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value.

### impl<T> From<T> for T

#### fn from(t: T) -> T

Returns the argument unchanged.

### impl<T, U> Into<U> for T

#### fn into(self) -> U

Calls `U::from(self)`.

### impl<T, U> TryFrom<U> for T

#### type Error = Infallible

The type returned in the event of a conversion error.

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.

### impl<T, U> TryInto<U> for T

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.

### impl<V, T> VZip<V> for T

#### fn vzip(self) -> V
```

--------------------------------

### Get Opcode Name from Schema

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/schema/struct.Schema.html

Use the `opcode_name` function to obtain the Opcode name from the TRACE_EVENT_INFO. See: OpcodeType.

```rust
let my_callback = |record: &EventRecord, schema_locator: &SchemaLocator| {
    let schema = schema_locator.event_schema(record).unwrap();
    let opcode_name = schema.opcode_name();
};
```

--------------------------------

### KernelTrace Initialization and Control

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.KernelTrace.html

Methods for creating a new trace session and stopping an active trace session.

```APIDOC
## KernelTrace::new

### Description
Creates a new KernelTrace builder to initialize a trace session.

### Method
Static Method

### Response
- **TraceBuilder<KernelTrace>** - A builder instance for configuring the trace session.

## KernelTrace::stop

### Description
Stops the active trace session. This consumes the instance, and the trace cannot be used afterwards.

### Method
Instance Method

### Response
- **Result<(), TraceError>** - Returns Ok(()) on success, or a TraceError if the operation fails.
```

--------------------------------

### Get Task Name from Schema

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/schema/struct.Schema.html

Use the `task_name` function to obtain the Task name from the TRACE_EVENT_INFO. See: TaskType.

```rust
let my_callback = |record: &EventRecord, schema_locator: &SchemaLocator| {
    let schema = schema_locator.event_schema(record).unwrap();
    let task_name = schema.task_name();
};
```

--------------------------------

### Implement VZip for ProfileSource

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/query/enum.ProfileSource.html

Implements the `vzip` method for the ProfileSource enum, likely related to vector operations or zipped data structures.

```rust
impl<V, T> VZip<V> for T
where V: MultiLane<T>,
{
    fn vzip(self) -> V
}

```

--------------------------------

### Access extended data in EventRecord

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/struct.EventRecord.html

Example showing how to iterate through extended data items to find a specific related activity ID.

```rust
use windows::Win32::System::Diagnostics::Etw::EVENT_HEADER_EXT_TYPE_RELATED_ACTIVITYID;

let my_callback = |record: &EventRecord, schema_locator: &SchemaLocator| {
    let schema = schema_locator.event_schema(record).unwrap();
    let activity_id = record
        .extended_data()
        .iter()
        .find(|edata| edata.data_type() as u32 == EVENT_HEADER_EXT_TYPE_RELATED_ACTIVITYID)
        .map(|edata| edata.to_extended_data_item());
};
```

--------------------------------

### Get Raw Flag Bits

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.DumpFileLoggingMode.html

Returns the underlying `u32` representation of the currently stored flags. This is useful for inspection or when interacting with lower-level APIs.

```rust
pub const fn bits(&self) -> u32
```

--------------------------------

### KernelProvider Constructor

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/kernel_providers/struct.KernelProvider.html

Creates a new instance of KernelProvider to be used with the provider system.

```APIDOC
## KernelProvider::new

### Description
Creates a new KernelProvider instance which can be tied into a Provider.

### Parameters
- **guid** (GUID) - Required - Kernel Provider GUID
- **flags** (u32) - Required - Kernel Provider Flags

### Request Example
let provider = KernelProvider::new(guid, flags);
```

--------------------------------

### SPLIT_IO_PROVIDER

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/kernel_providers/static.SPLIT_IO_PROVIDER.html

Details about the static SPLIT_IO_PROVIDER KernelProvider.

```APIDOC
## SPLIT_IO_PROVIDER

### Description
Represents the Split IO Kernel Provider.

### Type
`ferrisetw::provider::kernel_providers::KernelProvider`

### Static Item
`pub static SPLIT_IO_PROVIDER: KernelProvider`
```

--------------------------------

### Define EVENT_EXTENDED_ITEM_INSTANCE Struct

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/native/struct.EVENT_EXTENDED_ITEM_INSTANCE.html

Defines the structure for an extended item instance, including its ID, parent ID, and parent GUID. This struct is marked with #[repr(C)] for C-compatible memory layout.

```rust
#[repr(C)]
pub struct EVENT_EXTENDED_ITEM_INSTANCE {
    pub InstanceId: u32,
    pub ParentInstanceId: u32,
    pub ParentGuid: GUID,
}
```

--------------------------------

### Get Decoding Source from Schema

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/schema/struct.Schema.html

Use the `decoding_source` function to obtain the DecodingSource from the TRACE_EVENT_INFO. This getter returns the DecodingSource from the event, this value identifies the source used parse the event data.

```rust
let my_callback = |record: &EventRecord, schema_locator: &SchemaLocator| {
    let schema = schema_locator.event_schema(record).unwrap();
    let decoding_source = schema.decoding_source();
};
```

--------------------------------

### SessionlessInfo Implementations

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/query/struct.SessionlessInfo.html

Details on the implementations available for the SessionlessInfo struct.

```APIDOC
## impl SessionlessInfo

### pub fn sample_interval(source: ProfileSource) -> Result<u32, TraceError>

Gets a sample interval from a profile source.

### pub fn max_pmc() -> Result<u32, TraceError>

Gets the maximum number of Performance Monitoring Counters (PMCs) available.
```

--------------------------------

### Default SchemaLocator Implementation

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/schema_locator/struct.SchemaLocator.html

Provides a default value for SchemaLocator, allowing for easy initialization.

```rust
fn default() -> SchemaLocator
```

--------------------------------

### Stop Trace by Name

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/fn.stop_trace_by_name.html

Stops a trace given its name. This function is intended for closing traces that were not initiated by the current process. For traces started by the current process, prefer using UserTrace::stop() or KernelTrace::stop().

```APIDOC
## stop_trace_by_name

### Description
Stop a trace given its name.
This function is intended to close a trace you did not start yourself. Otherwise, you should prefer `UserTrace::stop()` or `KernelTrace::stop()`

### Method
(Not specified, likely a function call within the Rust library)

### Endpoint
(Not applicable, this is a Rust function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
(None)

### Request Example
(Not applicable, this is a Rust function)

### Response
#### Success Response (Result<(), TraceError>)
- **Ok** - Indicates the trace was successfully stopped.

#### Error Response (TraceError)
- **Err** - Indicates an error occurred while trying to stop the trace.

#### Response Example
(Not applicable, this is a Rust function)
```

--------------------------------

### Implement sample_interval for SessionlessInfo

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/query/struct.SessionlessInfo.html

This function retrieves the sampling interval from a given profile source. It returns a Result containing a u32 for the interval or a TraceError.

```rust
pub fn sample_interval(source: ProfileSource) -> Result<u32, TraceError>
```

--------------------------------

### Stop a trace by name

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/fn.stop_trace_by_name.html

Use this function to stop a trace given its name. It is intended for closing traces that were not initiated by the current process. For traces started by the current process, prefer using UserTrace::stop() or KernelTrace::stop().

```rust
pub fn stop_trace_by_name(trace_name: &str) -> Result<(), TraceError>
```

--------------------------------

### Traits

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/all.html

List of all available traits in the ferrisetw crate.

```APIDOC
## Traits

### trace::RealTimeTraceTrait
Trait for real-time trace operations.

### trace::TraceTrait
General trait for trace operations.
```

--------------------------------

### TryFrom and TryInto Trait Conversions

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/struct.GUID.html

Documentation for the conversion traits used for fallible type transformations.

```APIDOC
## TryFrom and TryInto Traits

### Description
Provides mechanisms for fallible type conversions between types T and U.

### Methods
- **try_from(value: U) -> Result<T, Error>**: Performs the conversion from U to T.
- **try_into(self) -> Result<U, Error>**: Performs the conversion from T to U.

### Associated Types
- **Error**: The type returned in the event of a conversion error.
```

--------------------------------

### Implement From for ProfileSource

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/query/enum.ProfileSource.html

Implements the `from` method for the ProfileSource enum, allowing conversion from a value of the same type.

```rust
impl<T> From<T> for T
{
    fn from(t: T) -> T
}

```

--------------------------------

### Implement TryInto for ProfileSource

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/query/enum.ProfileSource.html

Implements the `try_into` method for the ProfileSource enum, enabling fallible conversion into another type that implements `TryFrom`.

```rust
impl<T, U> TryInto<U> for T
where U: TryFrom<T>,
{
    type Error = <U as TryFrom<T>>::Error;
    fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
}

```

--------------------------------

### Implement Borrow for ProfileSource

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/query/enum.ProfileSource.html

Implements the `borrow` method for the ProfileSource enum, enabling immutable borrowing.

```rust
impl<T> Borrow<T> for T
where T: ?Sized,
{
    fn borrow(&self) -> &T
}

```

--------------------------------

### Type Aliases

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/all.html

List of all available type aliases in the ferrisetw crate.

```APIDOC
## Type Aliases

### native::ControlHandle
An alias for the control handle type.

### native::TraceHandle
An alias for the trace handle type.
```

--------------------------------

### VAMAP_PROVIDER

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/kernel_providers/static.VAMAP_PROVIDER.html

Details about the static VAMAP_PROVIDER.

```APIDOC
## VAMAP_PROVIDER

### Description
Represents the VA Map Kernel Provider.

### Static Item
`ferrisetw::provider::kernel_providers::VAMAP_PROVIDER`

### Summary
```rust
pub static VAMAP_PROVIDER: KernelProvider
```
```

--------------------------------

### DPC_PROVIDER Constant

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/provider/kernel_providers/static.DPC_PROVIDER.html

Documentation for the DPC_PROVIDER static constant.

```APIDOC
## DPC_PROVIDER

### Description
Represents the DPC Kernel Provider.

### Definition
`pub static DPC_PROVIDER: KernelProvider`
```

--------------------------------

### EVENT_TRACE_FILE_MODE_PREALLOCATE Constant

Source: https://docs.rs/ferrisetw/1.2.0/ferrisetw/trace/struct.DumpFileLoggingMode.html

Pre-allocates disk space for the log file equal to EVENT_TRACE_PROPERTIES.MaximumFileSize. This space is reserved upfront for both circular and sequential files. Not allowed for private event tracing sessions.

```rust
pub const EVENT_TRACE_FILE_MODE_PREALLOCATE: Self
```