NAME

Win32::Exe - Manipulate Win32 executable files

VERSION

This document describes version 0.17 of Win32::Exe, released July 19, 2011.

SYNOPSIS

use Win32::Exe;
my $exe = Win32::Exe->new('c:/windows/notepad.exe');

# add a default resource structure if none exists
# create_resource_section only works on MSWin and
# does not work on Windows XP - requires Vista or
# above

$exe = $exe->create_resource_section if $exe->can_create_resource_section;

# Get version information
my $info = $exe->get_version_info;
print qq($_ = $info->{$_}\n) for (sort keys(%$info));

# Extract icons from an executable
my @iconnames = $exe->get_group_icon_names;
for ( my $i = 0; $i < @iconnames; $i++ ) {
    my $filename = 'icon' . $i . '.ico';
    my $iconname = $iconnames[$i];
    $exe->extract_group_icon($iconname,$filename);
}

# Import icons from a .exe or .ico file and write back the file
$exe->update( icon => '/c/windows/taskman.exe' );
$exe->update( icon => 'myicon.ico' );

# Change it to a console application, then save to another .exe
$exe->set_subsystem_console;
$exe->write('c:/windows/another.exe');

# Add a manifest section
$exe->update( manifest => $mymanifestxml );
# or a default
$exe->update( defaultmanifest => 1 );

# or specify manifest args
$exe->update( manifestargs => { ExecLevel => 'requireAdministrator' } );

# Get manifest object
$manifest = $exe->get_manifest if $exe->has_manifest;

# change execution level
$manifest->set_execution_level('requireAdministrator');
$exe->set_manifest($manifest);
$exe->write;

DESCRIPTION

This module parses and manipulating Win32 PE/COFF executable headers, including version information, icons, manifest and other resources. The module Win32::Exe::Manifest can be used for manifest handling.

A script exe_update.pl is provided for simple file updates.

Also, please see the test files in the source distributions t/ directory for examples of using this module.

METHODS

new

my $exe = Win32::Exe->new($filename);

Create a Win32::Exe object from $filename. Filename can be an executable or a DLL.

update

$exe->update( icon         => 'c:/my/icon.ico',
              gui          => 1,
              info         => [ 'FileDescription=My File', 'FileVersion=1.4.3.3567' ],
              manifest     => 'c:/my/manifest.xml',
              manifestargs => [ 'ExecLevel=asInvoker', 'CommonControls=1' ],
              );

The update method provides a convenience method for the most common actions. It writes the information you provide to the file opened by Win32::Exe->new($filename). You do not have to call $exe->write - the method automatically updates the opened file.

Param detail:

icon Pass the name of an executable, dll or ico file to extract the icon and make it the main icon for the Win32 executable.

info Pass a reference to an array of strings containing key - value pairs separated by '='.

e.g. info => [ 'FileDescription=My File', 'FileVersion=1.4.3.3567' ]

Recognised keys are

Comments        CompanyName     FileDescription FileVersion
InternalName    LegalCopyright  LegalTrademarks OriginalFilename
ProductName     ProductVersion

gui or console Use parameter 'gui' or 'console' to set the executable subsystem to Windows or Console. You can, of course, only use one or the other of gui / console, not both.

manifest Specify a manifest file to add to the executable resources.

manifestargs As an alternative to specifying a manifest file, pass a reference to an array of strings containing key - value pairs separated by '='.

e.g. manifestargs => [ 'ExecLevel=asInvoker', 'CommonControls=1' ]

Recognised keys are

ExecutionLevel  UIAccess     ExecName   Description
CommonControls  Version

create_resource_section

$exe = $exe->create_resource_section if $exe->can_create_resource_section;

If an executable file does not have an existing resource section, you must create one before attempting to add version, icon or manifest resources. The method create_resource_section is only available on MSWin platforms. Also, the method will fail if your windows version is Windows XP or below. You can check if it is possible to call create_resource_section by calling $exe->can_create_resource_section. After calling create_resource_section, the original Win32::Exe object does not reference the updated data. The method therefore returns a reference to a new Win32::Exe object that references the updated data.

Always call as :

$exe = $exe->create_resource_section if $exe->can_create_resource_section;

if the $exe already has a resource section, this call will safely return a reference to the original object without updating the original exe.

can_create_resource_section

$exe = $exe->create_resource_section if $exe->can_create_resource_section;

Check if the operating system and version allow addition of a resource section when none exists in the target executable.

get_manifest

my $manifest = $exe->get_manifest;

Retrieves a Win32::Exe::Manifest object. (See docs for Win32::Exe::Manifest)

set_manifest

$exe->set_manifest($manifest);
$exe->write;

Takes a Win32::Exe::Manifest object. You must explicitly call 'write' to commit changes to file. Also takes a filepath to an xml file containing raw manifest information.

set_manifest_args

$exe->set_manifest_args($argref);
$exe->write;

Accepts a reference to a hash with one or more of the the keys

ExecutionLevel  UIAccess     ExecName   Description
CommonControls  Version

Also accepts a reference to an array of strings of the format: [ 'key1=value1', 'key2=value2' ]

Example Values:

ExecutionLevel=asInvoker
UIAccess=false
CommonControls=1
Version=6.8.67.334534
ExecName=My.Application
Description=My Application

The CommonControls argument can be specified to add a dependency on Common Controls Library version 6.0.0.0

get_version_info

my $inforef = $exe->get_version_info;

Returns a reference to a hash with the keys:

Comments        CompanyName     FileDescription FileVersion
InternalName    LegalCopyright  LegalTrademarks OriginalFilename
ProductName     ProductVersion

set_version_info

$exe->set_version_info($inforef);
$exe->write;

Accepts a reference to a hash with one or more of the the keys

Comments        CompanyName     FileDescription FileVersion
InternalName    LegalCopyright  LegalTrademarks OriginalFilename
ProductName     ProductVersion

Also accepts a reference to an array of strings of the format: [ 'key1=value1', 'key2=value2' ]

set_subsystem_windows

$exe->set_subsystem_windows;
$exe->write;

Sets the executable system as 'windows'. (GUI). You may also call $exe->SetSubsystem('windows); This is the equivalent of $exe->update( gui => 1);

set_subsystem_console

$exe->set_subsystem_console;
$exe->write;

Sets the executable system as 'console'. You may also call $exe->SetSubsystem('console); This is the equivalent of $exe->update( console => 1);

get_subsystem

my $subsys = $exe->get_subsystem;

Returns a descriptive string for the subsystem. Possible values: windows | console | posix | windowsce | native You can usefully update executables with the windows or console subsystem

set_single_group_icon

$exe->set_single_group_icon($iconfile);
$exe->write;

Accepts the path to an icon file. Replaces all the icons in the exec with the icons from the file.

get_group_icon_names

my @iconnames = $exe->get_group_icon_names;

Returns a list of the names of all the group icons in the executable or dll. If there are no group icons, returns an empty list. The names returned can be used as parameters to other icon handling methods.

get_group_icon

$exe->get_group_icon($groupiconname);

Accepts a group icon name as returned by get_group_icon_names. Returns the Wx::Exe::Resource::GroupIcon object for the named GroupIcon

add_group_icon

$exe->add_group_icon($groupiconname, $iconfilepath);
$exe->write;

Accepts a group icon name and a path to an icon file. Adds the icon to the exec without affecting existing icons. The group icon name must not already exist.

replace_group_icon

$exe->replace_group_icon($groupiconname, $iconfilepath);
$exe->write;

Accepts a group icon name and a path to an icon file. Replaces the groupicon named with the contents of the icon file.

remove_group_icon

$exe->remove_group_icon($groupiconname);
$exe->write;

Accepts a group icon name. Removes the group icon with that name from the exec or dll.

export_group_icon

$exe->export_group_icon($groupiconname, $iconfilepath);

Accepts a group icon name and a .ico filepath. Writes the named icon group to the file in filepath.

AUTHORS

Audrey Tang <cpan@audreyt.org>

Mark Dootson <mdootson@cpan.org>

Steffen Mueller <smueller@cpan.org>

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

To install Win32::Exe, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Win32::Exe

CPAN shell

perl -MCPAN -e shell
install Win32::Exe

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)