dotscope 0.6.0

A high-performance, cross-platform framework for analyzing and reverse engineering .NET PE executables
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

//! Owned `AssemblyRefOS` table representation.
//!
//! This module provides the [`crate::metadata::tables::assemblyrefos::owned::AssemblyRefOs`] struct
//! which contains fully resolved operating system compatibility information for external assembly
//! references. This is the primary data structure for representing OS requirements for referenced
//! assemblies in a usable form after the dual variant resolution phase.
//!
//! # Architecture
//!
//! The owned representation stores fully resolved data from the `AssemblyRefOS` metadata table,
//! including resolved references to assembly dependencies. This eliminates the need for table
//! lookups during runtime access, providing immediate access to OS compatibility metadata.
//!
//! # Key Components
//!
//! - [`crate::metadata::tables::assemblyrefos::owned::AssemblyRefOs`] - Main owned OS compatibility structure
//! - [`crate::metadata::tables::assemblyref::AssemblyRefRc`] - Referenced assembly dependency
//!
//! # Integration
//!
//! This module integrates with:
//! - [`crate::metadata::tables::assemblyrefos::raw`] - Raw table representation
//! - [`crate::metadata::tables::assemblyref`] - Assembly reference table entries
//! - [`crate::metadata::token`] - Token-based metadata references

use std::sync::atomic::Ordering;

use crate::{
    metadata::{tables::AssemblyRefRc, token::Token},
    Result,
};

/// Represents operating system compatibility information for an external assembly reference
///
/// This structure contains OS targeting information from the `AssemblyRefOS` metadata table (0x25),
/// with all references resolved to owned data. Unlike [`crate::metadata::tables::assemblyrefos::raw::AssemblyRefOsRaw`],
/// this provides immediate access to the referenced assembly without requiring table lookups.
///
/// # Operating System Targeting
///
/// The `AssemblyRefOS` table allows specifying explicit OS requirements for external assemblies:
/// - **Platform ID**: Operating system family identifier
/// - **Major Version**: Target OS major version number  
/// - **Minor Version**: Target OS minor version number
/// - **Assembly Reference**: The external assembly these requirements apply to
///
/// # Historical Context
///
/// This table is rarely used in modern .NET assemblies and is considered legacy. It was designed
/// for early .NET Framework scenarios where assemblies might need explicit OS compatibility
/// declarations. Modern .NET relies on runtime platform abstraction instead.
///
/// # Thread Safety
///
/// This type is [`Send`] and [`Sync`]. All fields are read-only after construction and safe
/// for concurrent access. The `apply` method uses atomic operations when updating assembly
/// reference data.
///
/// # References
/// - [ECMA-335 II.22.7](https://ecma-international.org/wp-content/uploads/ECMA-335_6th_edition_june_2012.pdf) - `AssemblyRefOS` table specification
pub struct AssemblyRefOs {
    /// Row identifier within the `AssemblyRefOS` metadata table
    ///
    /// The 1-based index of this `AssemblyRefOS` row within the table.
    pub rid: u32,

    /// Metadata token for this `AssemblyRefOS` entry
    ///
    /// Combines the table identifier (0x25 for `AssemblyRefOS`) with the row ID to create
    /// a unique token that can be used to reference this entry from other metadata.
    pub token: Token,

    /// Byte offset of this `AssemblyRefOS` row within the metadata tables stream
    ///
    /// Physical location of the raw `AssemblyRefOS` data within the metadata binary format.
    /// Used for debugging and low-level metadata analysis.
    pub offset: usize,

    /// Operating system platform identifier
    ///
    /// Specifies the target operating system family. Common values include:
    /// - 1: Windows 32-bit
    /// - 2: Windows 64-bit
    /// - Other values for various platform types
    pub os_platform_id: u32,

    /// Major version number of the target operating system
    ///
    /// The major version component of the required OS version (e.g., 6 for Windows Vista/7/8).
    pub os_major_version: u32,

    /// Minor version number of the target operating system  
    ///
    /// The minor version component of the required OS version (e.g., 1 for Windows 7).
    pub os_minor_version: u32,

    /// Reference to the external assembly that these OS requirements apply to
    ///
    /// Points to the corresponding [`crate::metadata::tables::assemblyref::AssemblyRef`]
    /// entry that represents the external assembly dependency.
    pub assembly_ref: AssemblyRefRc,
}

impl AssemblyRefOs {
    /// Apply operating system compatibility information to the referenced assembly
    ///
    /// Updates the referenced assembly with OS platform and version information from this
    /// `AssemblyRefOS` entry. The assembly reference already contains atomic fields for storing
    /// OS data, allowing thread-safe updates without additional synchronization.
    ///
    /// # Returns
    ///
    /// * `Ok(())` - OS information successfully applied to assembly reference
    ///
    /// # Errors
    ///
    /// This function never returns an error as atomic operations cannot fail.
    ///
    /// # Thread Safety
    ///
    /// This method is thread-safe as it uses atomic operations to update the assembly
    /// reference. Multiple threads can safely call this method concurrently.
    pub fn apply(&self) -> Result<()> {
        self.assembly_ref
            .os_major_version
            .store(self.os_major_version, Ordering::Relaxed);
        self.assembly_ref
            .os_minor_version
            .store(self.os_minor_version, Ordering::Relaxed);
        self.assembly_ref
            .os_platform_id
            .store(self.os_platform_id, Ordering::Relaxed);
        Ok(())
    }
}