Adding `dos` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add dos

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

dos = "0.0.3"

The dos library will be automatically available globally. Read the dos library documentation.

Back to the crate overview.

Readme

dos

⚠️ 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:

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());
}

Networking

Get all unicast IP addresses on the system:

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());
}

Get the alias of a network interface using its LUID:

use dos::net::convert_interface_luid_to_alias;
let my_luid = 1234;
let alias = convert_interface_luid_to_alias(my_luid)?;

Security

Get a security descriptor for a file:

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");
}

Strings

Convert from various code pages to Rust strings:

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);

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.

License: MIT

Adding dos library as a dependency

Adding `dos` library as a dependency