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

Copyright 2004-2007, 2010 by Audrey Tang <cpan@audreyt.org>.

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