windows_erg/file/
mod.rs

1//! Raw file operations.
2//!
3//! This module provides low-level file copying using raw disk reads,
4//! which can bypass some filesystem-level filters.
5//!
6//! # Permissions
7//!
8//! Raw reads typically require elevated privileges (administrator).
9//! Without sufficient privileges, operations usually fail with
10//! [`crate::Error::FileOperation`].
11//!
12//! # Path Requirements
13//!
14//! Source paths must be absolute Windows drive paths (for example `C:\\path\\file.txt`).
15//! Paths without a drive prefix are rejected as invalid parameters.
16//!
17//! # Examples
18//!
19//! ```no_run
20//! use windows_erg::file;
21//!
22//! file::raw_copy(
23//!     r"C:\\Windows\\System32\\drivers\\etc\\hosts",
24//!     r"C:\\Temp\\hosts.copy"
25//! )?;
26//! # Ok::<(), windows_erg::Error>(())
27//! ```
28//!
29//! ```no_run
30//! use windows_erg::file::RawFile;
31//!
32//! let mut raw = RawFile::builder()
33//!     .path(r"C:\\Windows\\System32\\drivers\\etc\\hosts")
34//!     .clusters_per_read(8)
35//!     .open()?;
36//!
37//! raw.copy_to(r"C:\\Temp\\hosts.builder.copy")?;
38//! # Ok::<(), windows_erg::Error>(())
39//! ```
40
41mod builder;
42mod raw;
43mod win;
44
45pub use builder::RawFileBuilder;
46pub use raw::RawFile;
47
48use std::path::Path;
49
50use crate::Result;
51use crate::security::{
52    ApplyMode, DescriptorEditResult, PermissionEditPlan, PermissionTarget, SecurityDescriptor,
53};
54
55/// Copy a file using raw disk reads.
56///
57/// This operation may require elevated privileges.
58///
59/// # Errors
60///
61/// Returns an error when:
62/// - the source path is invalid for raw reads,
63/// - the process lacks privileges for raw volume access,
64/// - the destination cannot be created or written,
65/// - retrieval pointer metadata cannot be read from the source file.
66pub fn raw_copy<P: AsRef<Path>, Q: AsRef<Path>>(source: P, destination: Q) -> Result<()> {
67    let raw = RawFile::open(source)?;
68    raw.copy_to(destination)
69}
70
71/// Create a raw file builder.
72///
73/// Use this for advanced tuning such as cluster read size and metadata buffer sizing.
74pub fn builder() -> RawFileBuilder {
75    RawFileBuilder::new()
76}
77
78/// Read a file security descriptor.
79pub fn read_security_descriptor<P: AsRef<Path>>(path: P) -> Result<SecurityDescriptor> {
80    let target = PermissionTarget::file(path.as_ref().to_string_lossy().to_string());
81    target.read_descriptor()
82}
83
84/// Write a file security descriptor.
85pub fn write_security_descriptor<P: AsRef<Path>>(
86    path: P,
87    descriptor: &SecurityDescriptor,
88) -> Result<()> {
89    let target = PermissionTarget::file(path.as_ref().to_string_lossy().to_string());
90    target.write_descriptor(descriptor)
91}
92
93/// Apply a permission edit plan to a file target.
94pub fn apply_permissions<P: AsRef<Path>>(
95    path: P,
96    plan: &PermissionEditPlan,
97    mode: ApplyMode,
98) -> Result<DescriptorEditResult> {
99    let target = PermissionTarget::file(path.as_ref().to_string_lossy().to_string());
100    plan.execute_against_target(&target, mode)
101}
windows_erg/file/mod.rs

windows_erg/file/
mod.rs
