# eventlog
[](https://crates.io/crates/eventlog)
[](https://docs.rs/eventlog)
A [log](https://docs.rs/log)-compatible wrapper around the [Windows Event Log API](https://docs.microsoft.com/en-us/windows/desktop/eventlog/event-logging).
Thanks to Jeroen C. van Gelderen for creating the [winlog](https://gitlab.com/arbitrix/winlog) project from which this is forked.
## Features
* Writes Rust log messages to the Windows event log using the
[RegisterEventSourceW](https://docs.microsoft.com/en-us/windows/desktop/api/Winbase/nf-winbase-registereventsourcew)
and [ReportEventW](https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-reporteventw) APIs.
* Provides utility functions to register/unregister your
[event source](https://docs.microsoft.com/en-us/windows/desktop/eventlog/event-sources) in the Windows registry.
* Embeds a small (120-byte) message resource library containing the necessary log message templates in your executable.
* Does not panic.
The five Rust log levels are mapped to Windows [event types](https://docs.microsoft.com/en-us/windows/desktop/eventlog/event-types) as follows:
| Error | Error | 1 |
| Warn | Warning | 2 |
| Info | Informational | 3 |
| Debug | Informational | 4 |
| Trace | Informational | 5 |
## Requirements
* Rust 1.29+ on Windows with MSVC toolchain
* [Windows, optional] [mc.exe](https://docs.microsoft.com/en-us/windows/desktop/wes/message-compiler--mc-exe-) and [rc.exe](https://docs.microsoft.com/en-us/windows/desktop/menurc/resource-compiler) (only required when `eventmsgs.mc` is changed)
* [Windows, optional] PowerShell (used for the end-to-end test)
## Usage
### Cargo.toml
```toml
[dependencies]
eventlog = "0.1.0"
```
### Register log source with Windows
Register the log source in the Windows registry:
```rust
eventlog::register("Example Log").unwrap();
```
This usually requires **Administrator** permission so this is usually done during installation time.
If your MSI installer (or similar) registers your event sources you should not call this.
### Log events
```rust
eventlog::init("Example Log", log::Level::Trace).unwrap();
info!("Hello, Event Log");
trace!("This will be logged too");
```
### Deregister log source
Deregister the log source:
```rust
eventlog::deregister("Example Log").unwrap();
```
This is usually done during program uninstallation. If your MSI installer (or similar) deregisters your event sources you should not call this.
### Internals
Artifacts `eventmsgs.lib` and `eventmsgs.rs` are under source control so users
don't need to have `mc.exe` and `rc.exe` installed for a standard build.
1. If `build.rs` determines that `eventmsgs.mc` was changed then `build.rs`:
* invokes `mc.exe` (which creates `eventmsgs.h`)
* invokes `rc.exe` (which creates `eventmsgs.lib`)
* creates `eventmsgs.rs` from `eventmsgs.h`.
2. `build.rs` emits linker flags so `eventmsgs.lib` can found.
3. Standard `cargo build` follows.
## Testing
The end-to-end test requires 'Full Control' permissions on the
`HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application`
registry key.
```rust
cargo test
```
### Process:
1. Create a unique temporary event source name (`eventlog-test-###########`).
2. Register our compiled test executable as ```EventMessageFile``` for
the event source in the Windows registry. You can see a new key at
`HKLM\SYSTEM\CurrentControlSet\Services\EventLog\Application\eventlog-test-###########`.
2. Write some log messages to the event source.
3. Use PowerShell to retrieve the logged messages.
4. Deregister our event source. This removes the `eventlog-test-###########`
registry key.
5. Assert that the retrieved log messages are correct.
## License
Licensed under either of
* Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall
be dual licensed as above, without any additional terms or conditions.