Skip to main content

Crate icoextract_rs

Crate icoextract_rs 

Source
Expand description

§icoextract_rs

Cross-platform extraction of icon resources from PE executables.

icoextract_rs reads file-layout PE32 and PE32+ .exe, .dll, and .mun files without Windows APIs. It lists group icons, selects a group by index or resource ID, and emits a standard ICO stream. Win16/NE headers are recognized but their resource tables are intentionally unsupported.

IconExtractor::from_path maps files read-only on Unix and Windows, so opening a large executable does not eagerly allocate or copy its complete contents. IconExtractor::from_bytes deliberately copies its input so the extractor remains independent of the caller’s buffer.

§Quick start

Add the default, library-only feature set to your application:

[dependencies]
icoextract_rs = "0.1"

Extract the first group icon and write it to a file:

The default crate parses PE32 and PE32+ group-icon resources and writes standard ICO data. Enable the thumbnail feature for PNG thumbnail generation, and the cli feature for the optional command-line tools. Win16/NE headers are recognized only to report an unsupported format; their resources are not parsed.

use icoextract_rs::{IconExtractor, IconSelector};

let extractor = IconExtractor::from_path("program.exe")?;
let icon = extractor.get_icon(IconSelector::Index(0))?;
icon.write_ico(std::fs::File::create("program.ico")?)?;

§Selecting and inspecting icons

IconExtractor::list_group_icons returns metadata without copying image payloads. Select an extracted group with IconSelector::Index or a numeric/named ResourceSelector, then obtain its bytes with ExtractedIcon::to_ico_bytes or write directly with ExtractedIcon::write_ico.

use icoextract_rs::{IconExtractor, ResourceSelector};

let extractor = IconExtractor::from_path("shell32.dll")?;
for group in extractor.list_group_icons()? {
    println!("{}: {} frames", group.resource_id(), group.images().len());
}

let named_icon = extractor.icon_by_resource_id(ResourceSelector::name("MAIN_ICON"))?;
std::fs::write("main.ico", named_icon.to_ico_bytes()?)?;

§Optional features

  • thumbnail enables the thumbnail module, including ICO decoding and PNG output.
  • cli enables the icoextract and icolist binaries. Combine it with thumbnail to build exe-thumbnailer.
[dependencies]
icoextract_rs = { version = "0.1", features = ["thumbnail"] }
use icoextract_rs::thumbnail::{ThumbnailOptions, generate_thumbnail};

generate_thumbnail("program.exe", "program.png", ThumbnailOptions::default())?;

§Errors and compatibility

Public fallible operations return Result. Error distinguishes I/O, invalid executable headers, unsupported NE input, absent icons, selector misses, malformed resource data, and invalid ICO output. Parsing is bounds checked: malformed input returns an error instead of panicking.

PE resources with overlapping or oversized section records are normalized before traversal, so a malformed earlier overlay section does not hide a later .rsrc section.

Modules§

thumbnailthumbnail
PNG thumbnail generation for the first icon in a PE executable.

Structs§

ExtractedIcon
A fully extracted group icon ready for ICO serialization.
ExtractedImage
One extracted icon image and its group-entry metadata.
GroupIcon
Metadata for one PE group-icon resource.
IconExtractor
Opens a PE executable and exposes its group-icon resources.
IconImageInfo
Metadata for one image referenced by a PE group-icon resource.

Enums§

Error
An error encountered while locating, extracting, or serializing an icon.
ExecutableType
An executable format understood by the extractor factory.
IconSelector
A selection of a group icon by zero-based position or resource identifier.
ResourceId
A resource identifier as it appears in a PE resource directory.
ResourceSelector
A resource identifier supplied by a caller.

Functions§

detect_executable_type
Detects an executable type from its DOS header and real-header signature.

Type Aliases§

Result
A specialized result type for this crate.