dos/
lib.rs

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

dos/
lib.rs
