Win32::Exe - Manipulate Win32 executable files

       Audrey Tang <cpan@audreyt.org>

       Mark Dootson <mdootson@cpan.org>

       Steffen Mueller <smueller@cpan.org>

       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>

perl v5.34.0                                       2022-08-14                                    Win32::Exe(3pm)

       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.

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

       guiorconsole 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.

       Win32::Exe - Manipulate Win32 executable files

           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;

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