1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
//! ⚠️ **This project is a work in progress.**
//!
//! Rust-friendly bindings for Windows APIs. It is not meant to be exhaustive, only cover areas that
//! the standard library does not.
//!
//! # Quick start
//!
//! Add this to your `Cargo.toml`: `cargo add dos`
//!
//! # Features
//!
//! - `full` - Enable all features
//! - `net` - Networking
//! - `process` - Process and module enumeration
//! - `string` - String conversion utilities
//! - `security` - Security and access control
//! - `sys` - System information
//!
//! # Guiding principles
//!
//! In descending order of importance:
//!
//! - **Safety**. `unsafe` must be avoided as much as possible, particularly in public APIs.
//! - **Lightweight**. Everything is feature-gated, especially dependencies.
//! - **Zero cost**. Except when it can be justified, we try to avoid needlessly copying data or performing
//! unnecessary operations.
//! - **Escape hatch**. If higher level bindings miss anything, it should be possible to use the raw
//! bindings.
//! - **Minimalism**. APIs should if possible resemble one-to-one mappings to the underlying Windows
//! APIs, but with different naming conventions. This improves searchability. For example, the
//! underlying `GetUnicastIpAddressTable` API is called `get_unicast_ip_address_table`.
//!
//! # Examples
//!
//! ## List processes
//!
//! List all running processes in the system:
//!
//! ```no_run
//! # #[cfg(feature = "process")]
//! # {
//! use dos::process::{SnapshotFlags, create_toolhelp32_snapshot};
//!
//! let snapshot = create_toolhelp32_snapshot(SnapshotFlags::PROCESS, 0)?;
//! for process in snapshot.processes().take(5) {
//! let process = process?;
//! println!("Process ID: {}, Parent ID: {}", process.pid(), process.parent_pid());
//! }
//! # }
//! # Ok::<(), std::io::Error>(())
//! ```
//!
//! ## Networking
//!
//! Get all unicast IP addresses on the system:
//!
//! ```no_run
//! # #[cfg(feature = "net")]
//! # {
//! use dos::net::get_unicast_ip_address_table;
//!
//! for address in get_unicast_ip_address_table(None)? {
//! println!("Interface Index: {}", address.interface_index());
//! println!("Address: {}", address.address());
//! println!("Address Family: {:?}", address.family());
//! }
//! # }
//! # Ok::<(), std::io::Error>(())
//! ```
//!
//! Get the alias of a network interface using its LUID:
//!
//! ```no_run
//! # #[cfg(feature = "net")]
//! # {
//! use dos::net::convert_interface_luid_to_alias;
//! let my_luid = 1234;
//! let alias = convert_interface_luid_to_alias(my_luid)?;
//! # }
//! # Ok::<(), std::io::Error>(())
//! ```
//!
//! ## Security
//!
//! Get a security descriptor for a file:
//!
//! ```no_run
//! # #[cfg(feature = "security")]
//! # {
//! use dos::security::{get_security_info, SecurityInformation, ObjectType};
//! use std::fs::File;
//!
//! let file = File::open("example.txt")?;
//! let security_info = get_security_info(
//! &file,
//! ObjectType::File,
//! SecurityInformation::OWNER | SecurityInformation::GROUP
//! )?;
//!
//! if let Some(owner) = security_info.owner() {
//! println!("File has owner SID");
//! }
//!
//! if let Some(group) = security_info.group() {
//! println!("File has group SID");
//! }
//! # }
//! # Ok::<(), std::io::Error>(())
//! ```
//!
//! ## Strings
//!
//! Convert from various code pages to Rust strings:
//!
//! ```no_run
//! # #[cfg(feature = "string")]
//! # {
//! use dos::string::{multi_byte_to_wide_char, CodePage};
//!
//! // Convert UTF-8 encoded C string to an OsString
//! let c_str = c"Hello, World!";
//! let os_string = multi_byte_to_wide_char(c_str, CodePage::Utf8)?;
//! println!("Converted: {:?}", os_string);
//!
//! // Convert from Windows-1252 (Western European)
//! let c_str = c"Caf\xe9"; // "Café" in Windows-1252
//! let os_string = multi_byte_to_wide_char(c_str, CodePage::Windows1252)?;
//! println!("From Windows-1252: {:?}", os_string);
//! # }
//! # Ok::<(), std::io::Error>(())
//! ```
//!
//! # Platform support
//!
//! This crate is tested on Windows 10 or later. It may work on earlier Windows versions, but there
//! is no guarantee of that.
//!
//! # Contributing
//!
//! Contributions are welcome! Please open an issue or a pull request.
// Re-export windows-sys
pub use windows_sys;