Class PEFile
- Namespace
- AsmResolver.PE.File
- Assembly
- AsmResolver.PE.File.dll
Models a file using the portable executable (PE) file format. It provides access to various PE headers, as well as the raw contents of each section present in the file.
public class PEFile : ISegmentReferenceFactory, IOffsetConverter
- Inheritance
-
PEFile
- Implements
- Derived
- Inherited Members
Constructors
PEFile()
Creates a new empty portable executable file.
public PEFile()
PEFile(DosHeader, FileHeader, OptionalHeader)
Creates a new portable executable file.
public PEFile(DosHeader dosHeader, FileHeader fileHeader, OptionalHeader optionalHeader)
Parameters
dosHeader
DosHeaderThe DOS header to add.
fileHeader
FileHeaderThe COFF header to add.
optionalHeader
OptionalHeaderThe optional header to add.
Fields
ValidPESignature
Indicates a valid NT header signature.
public const uint ValidPESignature = 17744
Field Value
Properties
DosHeader
Gets or sets the DOS header of the PE file.
public DosHeader DosHeader { get; set; }
Property Value
EofData
Gets or sets the data appended to the end of the file (EoF), if available.
public ISegment? EofData { get; set; }
Property Value
ExtraSectionData
Gets or sets the padding data in between the last section header and the first section.
public ISegment? ExtraSectionData { get; set; }
Property Value
FileHeader
Gets or sets the COFF file header of the portable executable (PE) file.
public FileHeader FileHeader { get; set; }
Property Value
FilePath
When this PE file was read from the disk, gets the file path to the PE file.
public string? FilePath { get; protected set; }
Property Value
MappingMode
Gets a value indicating the mapping mode of the PE file. If the PE file is in its mapped form, then every offset of all segments in the PE file will be equal to the physical memory address. If the file is in its unmapped form, the offsets will be equal to the file offset.
public PEMappingMode MappingMode { get; protected set; }
Property Value
OptionalHeader
Gets or sets the optional header of the portable executable (PE) file.
public OptionalHeader OptionalHeader { get; set; }
Property Value
Sections
Gets a collection of sections present in the portable executable (PE) file.
public IList<PESection> Sections { get; }
Property Value
Methods
AlignDataDirectoryEntries(IList<SectionHeader>)
Aligns all data directories' virtual address according to the section header's ones.
public void AlignDataDirectoryEntries(IList<SectionHeader> oldHeaders)
Parameters
oldHeaders
IList<SectionHeader>
AlignSections()
Aligns all sections according to the file and section alignment properties in the optional header.
public void AlignSections()
CreateDataDirectoryReader(DataDirectory)
Obtains a reader that spans the provided data directory.
public BinaryStreamReader CreateDataDirectoryReader(DataDirectory dataDirectory)
Parameters
dataDirectory
DataDirectoryThe data directory to read.
Returns
- BinaryStreamReader
The reader.
CreateReaderAtFileOffset(uint)
Creates a new reader at the provided file offset.
public BinaryStreamReader CreateReaderAtFileOffset(uint fileOffset)
Parameters
fileOffset
uintThe file offset to start reading at.
Returns
- BinaryStreamReader
The reader.
CreateReaderAtFileOffset(uint, uint)
Creates a new reader of a chunk of data at the provided file offset.
public BinaryStreamReader CreateReaderAtFileOffset(uint fileOffset, uint size)
Parameters
Returns
- BinaryStreamReader
The reader.
CreateReaderAtRva(uint)
Creates a new reader at the provided virtual address.
public BinaryStreamReader CreateReaderAtRva(uint rva)
Parameters
rva
uintThe virtual address to start reading at.
Returns
- BinaryStreamReader
The reader.
CreateReaderAtRva(uint, uint)
Creates a new reader of a chunk of data at the provided virtual address.
public BinaryStreamReader CreateReaderAtRva(uint rva, uint size)
Parameters
Returns
- BinaryStreamReader
The reader.
FileOffsetToRva(ulong)
Converts a file offset to the virtual address when it is loaded into memory.
public uint FileOffsetToRva(ulong fileOffset)
Parameters
fileOffset
ulongThe file offset to convert.
Returns
- uint
The virtual address, relative to the image base.
Exceptions
- ArgumentOutOfRangeException
Occurs when the file offset falls outside of the range of the convertible file offsets.
FromBytes(byte[])
Reads an unmapped PE file from memory.
public static PEFile FromBytes(byte[] raw)
Parameters
raw
byte[]The raw bytes representing the contents of the PE file to read.
Returns
- PEFile
The PE file that was read.
Exceptions
- BadImageFormatException
Occurs when the file does not follow the PE file format.
FromDataSource(IDataSource, PEMappingMode)
Reads a PE file from the provided data source.
public static PEFile FromDataSource(IDataSource dataSource, PEMappingMode mode = PEMappingMode.Unmapped)
Parameters
dataSource
IDataSourceThe data source to read from.
mode
PEMappingModeIndicates how the input PE file is mapped.
Returns
- PEFile
The PE file that was read.
Exceptions
- BadImageFormatException
Occurs when the file does not follow the PE file format.
FromFile(IInputFile)
Reads an unmapped PE file.
public static PEFile FromFile(IInputFile file)
Parameters
file
IInputFileThe file representing the PE.
Returns
- PEFile
The PE file that was read.
Exceptions
- BadImageFormatException
Occurs when the file does not follow the PE file format.
FromFile(string)
Reads an unmapped PE file from the disk.
public static PEFile FromFile(string path)
Parameters
path
stringThe file path to the PE file.
Returns
- PEFile
The PE file that was read.
Exceptions
- BadImageFormatException
Occurs when the file does not follow the PE file format.
FromModuleBaseAddress(nint)
Reads a mapped PE file starting at the provided module base address (HINSTANCE).
public static PEFile FromModuleBaseAddress(nint hInstance)
Parameters
hInstance
nintThe HINSTANCE or base address of the module.
Returns
- PEFile
The PE file that was read.
Exceptions
- BadImageFormatException
Occurs when the file does not follow the PE file format.
FromModuleBaseAddress(nint, PEMappingMode)
Reads a PE file starting at the provided module base address (HINSTANCE).
public static PEFile FromModuleBaseAddress(nint hInstance, PEMappingMode mode)
Parameters
hInstance
nintThe HINSTANCE or base address of the module.
mode
PEMappingModeIndicates how the input PE file is mapped.
Returns
- PEFile
The PE file that was read.
Exceptions
- BadImageFormatException
Occurs when the file does not follow the PE file format.
FromReader(in BinaryStreamReader, PEMappingMode)
Reads a PE file from the provided input stream.
public static PEFile FromReader(in BinaryStreamReader reader, PEMappingMode mode = PEMappingMode.Unmapped)
Parameters
reader
BinaryStreamReaderThe input stream to read from.
mode
PEMappingModeIndicates how the input PE file is mapped.
Returns
- PEFile
The PE file that was read.
Exceptions
- BadImageFormatException
Occurs when the file does not follow the PE file format.
GetEofData()
Obtains any data appended to the end of the file (EoF).
protected virtual ISegment? GetEofData()
Returns
- ISegment
The extra data.
Remarks
This method is called upon the initialization of the EofData property.
GetExtraSectionData()
Obtains the padding data in between the last section header and the first section.
protected virtual ISegment? GetExtraSectionData()
Returns
- ISegment
The extra padding data.
Remarks
This method is called upon the initialization of the ExtraSectionData property.
GetReferenceToRva(uint)
Resolves the provided virtual address to a segment reference.
public ISegmentReference GetReferenceToRva(uint rva)
Parameters
rva
uintThe virtual address of the segment.
Returns
- ISegmentReference
The reference to the segment.
GetSectionContainingOffset(ulong)
Finds the section containing the provided file offset.
public PESection GetSectionContainingOffset(ulong fileOffset)
Parameters
fileOffset
ulongThe file offset.
Returns
- PESection
The section containing the file offset.
Exceptions
- ArgumentOutOfRangeException
Occurs when the file offset does not fall within any of the sections.
GetSectionContainingRva(uint)
Finds the section containing the provided virtual address.
public PESection GetSectionContainingRva(uint rva)
Parameters
rva
uintThe virtual address.
Returns
- PESection
The section containing the virtual address.
Exceptions
- ArgumentOutOfRangeException
Occurs when the virtual address does not fall within any of the sections.
GetSections()
Obtains the sections in the portable executable file.
protected virtual IList<PESection> GetSections()
Returns
Remarks
This method is called upon the initialization of the Sections property.
RvaToFileOffset(uint)
Converts a virtual address to the physical file offset.
public ulong RvaToFileOffset(uint rva)
Parameters
rva
uintThe virtual address, relative to the image base, to convert.
Returns
- ulong
The file offset.
Exceptions
- ArgumentOutOfRangeException
Occurs when the virtual address falls outside of the range of the convertible addresses.
TryCreateDataDirectoryReader(DataDirectory, out BinaryStreamReader)
Attempts to create a reader that spans the provided data directory.
public bool TryCreateDataDirectoryReader(DataDirectory dataDirectory, out BinaryStreamReader reader)
Parameters
dataDirectory
DataDirectoryThe data directory to read.
reader
BinaryStreamReaderThe reader that was created.
Returns
- bool
true
if the reader was created successfully,false
otherwise.
TryCreateReaderAtFileOffset(uint, out BinaryStreamReader)
Attempts to create a new reader at the provided file offset.
public bool TryCreateReaderAtFileOffset(uint fileOffset, out BinaryStreamReader reader)
Parameters
fileOffset
uintThe file offset to start reading at.
reader
BinaryStreamReaderThe reader that was created.
Returns
- bool
true
if the reader was created successfully,false
otherwise.
TryCreateReaderAtFileOffset(uint, uint, out BinaryStreamReader)
Attempts to create a new reader of a chunk of data at the provided file offset.
public bool TryCreateReaderAtFileOffset(uint fileOffset, uint size, out BinaryStreamReader reader)
Parameters
fileOffset
uintThe file offset to start reading at.
size
uintThe number of bytes in the chunk.
reader
BinaryStreamReaderThe reader that was created.
Returns
- bool
true
if the reader was created successfully,false
otherwise.
TryCreateReaderAtRva(uint, out BinaryStreamReader)
Attempts to create a new reader at the provided virtual address.
public bool TryCreateReaderAtRva(uint rva, out BinaryStreamReader reader)
Parameters
rva
uintThe virtual address to start reading at.
reader
BinaryStreamReaderThe reader that was created.
Returns
- bool
true
if the reader was created successfully,false
otherwise.
TryCreateReaderAtRva(uint, uint, out BinaryStreamReader)
Attempts to create a new reader of a chunk of data at the provided virtual address.
public bool TryCreateReaderAtRva(uint rva, uint size, out BinaryStreamReader reader)
Parameters
rva
uintThe virtual address to start reading at.
size
uintThe number of bytes in the chunk.
reader
BinaryStreamReaderThe reader that was created.
Returns
- bool
true
if the reader was created successfully,false
otherwise.
TryGetSectionContainingOffset(ulong, out PESection?)
Attempts to find the section containing the provided file offset.
public bool TryGetSectionContainingOffset(ulong fileOffset, out PESection? section)
Parameters
Returns
- bool
true
if the section was found,false
otherwise.
TryGetSectionContainingRva(uint, out PESection?)
Attempts to find the section containing the provided virtual address.
public bool TryGetSectionContainingRva(uint rva, out PESection? section)
Parameters
Returns
- bool
true
if the section was found,false
otherwise.
UpdateHeaders()
Recomputes file offsets and sizes in the file, optional and section headers.
public void UpdateHeaders()
Remarks
Affected fields in the file header include:
- SizeOfOptionalHeader
- SizeOfHeadersSizeOfImageData directories
- VirtualAddressVirtualSizePointerToRawDataSizeOfRawData
Write(BinaryStreamWriter)
Writes the PE file to the provided output stream.
public void Write(BinaryStreamWriter writer)
Parameters
writer
BinaryStreamWriterThe output stream to write to.
Write(Stream)
Writes the PE file to the provided output stream.
public void Write(Stream stream)
Parameters
stream
StreamThe output stream to write to.
Write(string)
Writes the PE file to a file on the disk.
public void Write(string filePath)
Parameters
filePath
stringThe path of the file.