Struct pmw1::object::Pmw1Object

pub struct Pmw1Object { /* fields omitted */ }

A struct representing an object in a PMW1 executable, and containing its associated relocation blocks.

Implementations

impl Pmw1Object

pub fn new(
    data: &[u8],
    reloc_blocks: &mut dyn Iterator<Item = Pmw1RelocBlock>,
    virtual_size: u32,
    flags: u32
) -> Self

Create a new object - can be used to (re-)build an entire PMW1 EXE from scratch.

Details:

This function allows you to specify:

• The object's raw data, as a slice of bytes.
• The relocation blocks, by passing a mutable iterator over Pmw1RelocBlocks.
• The object's virtual_size, in bytes (i.e. how much memory is mapped at runtime for this object).
• The object's flags, as a 32-bit-string. I don't know if any of these flags is used at all by PMODE/W.

pub fn from_tabentry_byteslice(
    table_entry: &[u8],
    relocation_buf: &[u8],
    data_iter: &mut dyn Iterator<Item = &u8>
) -> Result<Self>

Turn an entry from a PMW1 EXE file's object table into an actual object, including its data and relocation blocks.

Details:

This function facilitates building an object from data scattered at various locations in an EXE file. As such, you need to pass three different things:

• The table_entry itself, as a slice of bytes as they are read from the EXE file's object table.
• A buffer containing all the bytes in the EXE that are designated as relocation data. The data stored in the table entry indicates where exactly to look in the buffer for this object's relocation blocks.
• An iterator over the bytes in the data-pages block of the EXE, with its current position at the start of this object's data.

Requirements:

• The length of table_entry must be exactly four times PMW1_OBJTABLE_ENTRY_LENGTH, otherwise you will get a std::io::Error of kind InvalidData.
• relocation_buf and data_iter must be able to supply as much data as is specified in table_entry - see the requirements on from_tabentry for more details.

pub fn from_tabentry_slice(
    table_entry: &[u32],
    relocation_buf: &[u8],
    data_iter: &mut dyn Iterator<Item = &u8>
) -> Result<Self>

Turn an entry from a PMW1 EXE file's object table into an actual object, including its data and relocation blocks. This function assumes you have already converted the entry into 32-bit integers.

Details:

This function facilitates building an object from data scattered at various locations in an EXE file. As such, you need to pass three different things:

• The table_entry itself, as a slice of 32-bit integers as they are encoded in the EXE file's object table.
• A buffer containing all the bytes in the EXE that are designated as relocation data. The data stored in the table entry indicates where exactly to look in the buffer for this object's relocation blocks.
• An iterator over the bytes in the data-pages block of the EXE, with its current position at the start of this object's data.

Requirements:

• The length of table_entry must be exactly PMW1_OBJTABLE_ENTRY_LENGTH, otherwise you will get a std::io::Error of kind InvalidData.
• relocation_buf and data_iter must be able to supply as much data as is specified in table_entry - see the requirements on from_tabentry for more details.

pub fn from_tabentry(
    table_entry: &[u32; 6],
    relocation_buf: &[u8],
    data_iter: &mut dyn Iterator<Item = &u8>
) -> Result<Self>

Turn an entry from a PMW1 EXE file's object table into an actual object, including its data and relocation blocks. This function assumes you have already converted the entry into 32-bit integers, and that you're in a position to pass them as a fixed-size array.

Details:

This function facilitates building an object from data scattered at various locations in an EXE file. As such, you need to pass three different things:

• The table_entry itself, as an array of PMW1_OBJTABLE_ENTRY_LENGTH 32-bit integers as they are encoded in the EXE file's object table.
• A buffer containing all the bytes in the EXE that are designated as relocation data. The data stored in the table entry indicates where exactly to look in the buffer for this object's relocation blocks.
• An iterator over the bytes in the data-pages block of the EXE, with its current position at the start of this object's data.

Requirements:

• The relocation_buf must be at least table_entry[3] bytes long, and contain as much data beyond that as is needed to construct table_entry[4] Pmw1RelocBlocks.
• data_iter must be able to supply at least table_entry[1] bytes.

pub fn to_tabentry(&self, relocation_pos: u32) -> [u32; 6]

Creates a PMW1 EXE file object table entry (i.e. PMW1_OBJTABLE_ENTRY_LENGTH 32-bit integers) to represent this object.

Requirements:

• When using this function to re-construct a PMW1 EXE file, you must know where exactly this object's relocation blocks will be inserted into the file's relocation data section. This position needs to be passed as relocation_pos.

pub fn flag(&self, n: u8) -> Result<bool>

Returns this object's nth flag, as a bool.

Requirements:

• n must be less than 32, since there are only 32 flag bits in total.

pub fn set_flag(&mut self, n: u8, val: bool) -> Result<()>

Sets this object's nth flag according to val (1 if true, 0 if false).

Requirements:

• n must be less than 32, since there are only 32 flag bits in total.

pub fn decompress(self) -> Result<Self>

Consumes this object and returns an uncompressed version (or the same thing if it's already uncompressed).

Requirements:

• If this object is compressed, the data contained in it must be valid input for the PMW1 decompression algorithm.
• self.uncompressed_size must match the actual size produced by the decompression algorithm. This is a private field, but it can be updated by update_data_raw.
• The same must apply to each of this object's relocation blocks.

If any of these is violated, this will fail with a std::io::Error of kind InvalidData.

pub fn compress(self) -> Result<Self>

Consumes this object and returns a compressed version (or the same thing if it's already compressed).

Requirements:

• The object's data must be at least two bytes long. Otherwise, this will fail with a std::io::Error of kind InvalidData.
• Each of this object's relocation blocks must similarly be compressible.

pub fn actual_size(&self) -> usize

Returns the current physical size of this object's data, in bytes.

pub fn virtual_size(&self) -> usize

Returns the virtual size in bytes of this object, i.e. how much memory is mapped for it at runtime.

pub fn set_virtual_size(&mut self, new_size: u32)

Sets the virtual size in bytes of the object, i.e. how much memory is mapped for it at runtime.

I don't know if there are legitimate use-cases for this, but I might as well include it. Caveat programmer.

pub fn uncompressed_size(&self) -> usize

Returns the size in bytes that this object currently believes its data will occupy when uncompressed.

I say "believes" because careless use of update_data_raw can cause this to go out of sync.

pub fn compressed(&self) -> bool

Returns true if this object is compressed, false otherwise.

pub fn data_raw(&self) -> &[u8]

Returns a slice of bytes containing the data currently stored in this object, regardless of whether it's compressed or not.

pub fn data(&self) -> Result<Vec<u8>>

Returns a Vec of bytes containing this object's actual code/data, decompressing it if necessary.

pub fn update_data_raw<F>(&mut self, f: F, new_uncompressed_size: u32) where
    F: FnOnce(&[u8]) -> Vec<u8>, 

Applies a closure f to the data currently stored in this object, regardless of whether it's compressed or not.

WARNING:

This function is not unsafe, in that it can't cause undefined behaviour in Rust itself, but it can mess up the state of your object if you're not careful! If you know what you're doing, calling this function on a compressed object with a carefully-crafted closure may be faster than update_data, which would decompress, apply the closure and then recompress the data. However, it is your responsibility to make sure that you know exactly what the uncompressed size of the updated data will be! If new_uncompressed_size is mis-specified here, then you can no longer trust the compressed method, or any other method that relies on it, and your EXE file will likely malfunction when you run it!

You have been warned!

pub fn update_data<F>(&mut self, f: F) -> Result<()> where
    F: FnOnce(&[u8]) -> Vec<u8>, 

Applies a closure f to the actual code/data of this object, decompressing and recompressing it if necessary. The uncompressed_size field is updated automatically.

pub fn iter_reloc_blocks(&self) -> Iter<'_, Pmw1RelocBlock>

Iterate over this object's relocation blocks.

pub fn iter_reloc_blocks_mut(&mut self) -> IterMut<'_, Pmw1RelocBlock>

Iterate mutably over this object's relocation blocks.

Trait Implementations

impl Clone for Pmw1Object

fn clone(&self) -> Pmw1Object

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Pmw1Object

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Pmw1Object

impl Hash for Pmw1Object

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl PartialEq<Pmw1Object> for Pmw1Object

fn eq(&self, other: &Pmw1Object) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Pmw1Object) -> bool

This method tests for !=.

impl StructuralEq for Pmw1Object

impl StructuralPartialEq for Pmw1Object