Module token

Commonly used metadata token type Metadata token implementation for .NET assembly analysis.

This module provides the crate::metadata::token::Token type for representing metadata table references within .NET assemblies. Tokens are fundamental to the .NET metadata system, providing a standardized way to reference entries across different metadata tables according to the ECMA-335 specification.

Architecture

The token system implements the ECMA-335 metadata addressing scheme, enabling precise and efficient referencing of metadata elements throughout .NET assemblies.

Token Structure

.NET metadata tokens are 32-bit values with a specific bit layout:

┌─────────────┬───────────────────────────────────┐
│ Table (8b)  │        Row Index (24b)            │
├─────────────┼───────────────────────────────────┤
│   31-24     │            23-0                   │
└─────────────┴───────────────────────────────────┘

• Table Identifier (bits 24-31): Identifies the metadata table type
• Row Index (bits 0-23): 1-based index within the specified table

Key Components

• crate::metadata::token::Token - Core token implementation with table and row addressing
• Table Identification - 8-bit table IDs according to ECMA-335 specification
• Row Addressing - 24-bit 1-based indexing supporting up to 16M entries per table
• Null References - Special token value (0) indicating absent references

Usage Examples

Creating and Inspecting Tokens

use dotscope::metadata::token::Token;

// Create a MethodDef token (table 0x06, row 1)
let method_token = Token::new(0x06000001);

println!("Token: {}", method_token);        // Displays: 0x06000001
println!("Table: 0x{:02x}", method_token.table()); // Table: 0x06
println!("Row: {}", method_token.row());           // Row: 1

// Check for null references
let null_token = Token::new(0);
assert!(null_token.is_null());

Working with Different Token Types

use dotscope::metadata::token::Token;

// Common .NET metadata token types
let typedef_token = Token::new(0x02000001);     // TypeDef
let typeref_token = Token::new(0x01000001);     // TypeRef  
let methoddef_token = Token::new(0x06000001);   // MethodDef
let memberref_token = Token::new(0x0A000001);   // MemberRef
let fielddef_token = Token::new(0x04000001);    // FieldDef

// Convert between Token and u32
let raw_value: u32 = methoddef_token.into();
let token_from_raw = Token::from(raw_value);
assert_eq!(methoddef_token, token_from_raw);

Common Token Types

Table ID	Name	Description	Example
0x01	TypeRef	External type references	0x01000001
0x02	TypeDef	Type definitions	0x02000001
0x04	FieldDef	Field definitions	0x04000001
0x06	MethodDef	Method definitions	0x06000001
0x08	Param	Parameter definitions	0x08000001
0x09	InterfaceImpl	Interface implementations	0x09000001
0x0A	MemberRef	External member references	0x0A000001
0x1B	TypeSpec	Type specifications	0x1B000001
0x2B	MethodSpec	Generic method instantiations	0x2B000001

Integration

This module integrates with:

• crate::metadata::tables - Metadata table implementations using tokens for addressing
• crate::disassembler - IL instruction analysis requiring token resolution
• crate::metadata::typesystem - Type resolution through token-based references
• crate::metadata::method - Method analysis using MethodDef and MemberRef tokens

Usage in .NET Metadata

Tokens serve multiple purposes in the .NET metadata system:

• IL Instructions: Many IL opcodes reference metadata through tokens
• Cross-References: Tables reference entries in other tables via tokens
• Debugging: Debug information uses tokens to reference metadata
• Reflection: The .NET reflection API uses tokens internally

Standards Compliance

• ECMA-335: Full compliance with metadata token specification (§II.24.2.6)
• Bit Layout: Exact implementation of 8-bit table + 24-bit row format
• Addressing: Support for 1-based indexing with null reference semantics
• Type Safety: Strong typing prevents misuse of raw integer values

References

• ECMA-335 §II.22 - Metadata Logical Format
• ECMA-335 §II.24.2.6 - Token

Structs

Token

A metadata token representing a reference to a specific entry within a metadata table.