hadris-cd 2.0.0-rc.3

Hybrid ISO+UDF optical disc image creation (UDF Bridge format)
Documentation 
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

//! # Hadris CD
//!
//! A Rust library for creating hybrid ISO+UDF optical disc images.
//!
//! ## Overview
//!
//! This crate creates "UDF Bridge" format images that contain both
//! ISO 9660 and UDF filesystems. This provides maximum compatibility:
//! - Legacy systems read ISO 9660
//! - Modern systems read UDF
//! - **Both filesystems share the same file data on disk**
//!
//! ## Quick Start
//!
//! ```rust
//! use hadris_cd::{CdWriter, CdOptions, FileTree, FileEntry};
//! # use std::io::Cursor;
//!
//! // Create a file tree
//! let mut tree = FileTree::new();
//! tree.add_file(FileEntry::from_buffer("readme.txt", b"Hello, World!".to_vec()));
//!
//! // Create the hybrid image
//! # // Use a Cursor for the doctest instead of a real file
//! # let buffer = vec![0u8; 2 * 1024 * 1024]; // 2MB buffer
//! # let file = Cursor::new(buffer);
//! let options = CdOptions::default()
//!     .volume_id("MY_DISC")
//!     .joliet(hadris_cd::JolietLevel::Level3);
//!
//! let _file = CdWriter::new(file, options)
//!     .finish(tree)
//!     .unwrap();
//! ```
//!
//! ## Disk Layout
//!
//! The UDF Bridge format interleaves ISO 9660 and UDF structures:
//!
//! ```text
//! Sector 0-15:    System area (boot code, partition tables)
//! Sector 16-...:  ISO 9660 Volume Descriptors
//! Sector 17-19:   UDF Volume Recognition Sequence (BEA01, NSR02, TEA01)
//! Sector 256:     UDF Anchor Volume Descriptor Pointer
//! Sector 257+:    UDF Volume Descriptor Sequence
//! File data:      Shared between ISO and UDF (both point to same sectors)
//! ```
//!
//! ## Features
//!
//! - ISO 9660 with Joliet (Windows long filenames) and Rock Ridge (POSIX)
//! - UDF 1.02/1.50/2.00+ support
//! - El-Torito bootable images
//! - Hybrid MBR+GPT for USB booting
//!
//! Bridge output is continuously tested by opening the completed image through
//! both the ISO 9660 and UDF readers.
//!
//! Hybrid image creation currently uses the synchronous ISO and UDF writers.
//! This crate therefore exposes a sync-only writer API; `std` selects hosted
//! platform support, while the default feature set selects `sync` explicitly.

#![allow(async_fn_in_trait)]
#![deny(missing_docs)]

// ---------------------------------------------------------------------------
// Shared types (compiled once)
// ---------------------------------------------------------------------------

#[cfg(feature = "sync")]
pub mod error;
#[cfg(feature = "sync")]
pub mod layout;
#[cfg(feature = "sync")]
pub mod options;
#[cfg(feature = "sync")]
pub mod tree;

// ---------------------------------------------------------------------------
// Sync module
// ---------------------------------------------------------------------------

#[cfg(feature = "sync")]
#[path = ""]
/// Synchronous hybrid optical-image writer API.
pub mod sync {
    pub use hadris_io::SeekFrom;
    pub use hadris_io::sync::{Borrowed, Read, Seek, Write};

    macro_rules! io_transform {
        ($($item:tt)*) => { hadris_macros::strip_async!{ $($item)* } };
    }

    #[allow(unused_macros)]
    macro_rules! sync_only {
        ($($item:tt)*) => { $($item)* };
    }

    #[allow(unused_macros)]
    macro_rules! async_only {
        ($($item:tt)*) => {};
    }

    #[path = "."]
    mod __inner {
        pub mod writer;
    }
    pub use __inner::*;

    // Convenience re-exports
    pub use __inner::writer::CdWriter;
}

// ---------------------------------------------------------------------------
// Default re-exports for backwards compatibility (sync)
// ---------------------------------------------------------------------------

#[cfg(feature = "sync")]
pub use sync::*;

// Re-exports from shared types
#[cfg(feature = "sync")]
pub use error::{CdError, CdResult};
#[cfg(feature = "sync")]
pub use layout::{LayoutInfo, LayoutManager};
#[cfg(feature = "sync")]
pub use options::{CdOptions, IsoOptions, JolietLevel, UdfOptions};
#[cfg(feature = "sync")]
pub use tree::{Directory, FileData, FileEntry, FileExtent, FileTree};

/// Canonical writer name for ISO/UDF optical images.
#[cfg(feature = "sync")]
pub type OpticalImageWriter<W> = sync::CdWriter<W>;

/// Canonical options name for ISO/UDF optical images.
#[cfg(feature = "sync")]
pub type OpticalImageOptions = CdOptions;