####################################################################### # # Archive-Unrar version 2.8 - Perl wrapper for unrar.dll. # Manipulates RAR format compressed archives by using the unrar dll dynamic library # # Author: Nikos Vaggalis # ####################################################################### =head1 NAME Archive::Unrar - is a procedural module that provides manipulation (extraction and listing of embedded information) of compressed RAR format archives by interfacing with the unrar.dll dynamic library for Windows. =head1 SYNOPSIS use Archive::Unrar; Usage without password : list_files_in_archive( file=>$file, password=>$password ); process_file( file=>$file, password=>$password, output_dir_path=>$output_dir_path, selection=>$selection,callback=>$callback ); list_files_in_archive(file=>"c:\\input_dir\\test.rar",password=>"mypassword"); Optionally, provide Selection and Callback: If Selection equals ERAR_MAP_DIR_YES then 'Map directory to Archive name' process_file("c:\\input_dir\\test.rar",password=>"mypassword", output_dir_path=>"c:\\outputdir", selection=>ERAR_MAP_DIR_YES,callback=>undef ); If Selection<>ERAR_MAP_DIR_YES then 'Do not Map directory to Archive name' process_file("c:\\input_dir\\test.rar",password=>"mypassword", output_dir_path=>"c:\\outputdir", selection=>undef,callback=>undef ); =head1 DESCRIPTION Archive::Unrar is a procedural module that provides manipulation (extraction and listing of embedded information) of compressed RAR format archives by interfacing with the unrar.dll dynamic library for Windows. It exports function "list_files_in_archive" and hash structure "%donotprocess" explicitly our @EXPORT_OK = qw(list_files_in_archive %donotprocess); By default it exports function "process_file" and some default error description parameters our @EXPORT = qw(process_file ERAR_BAD_DATA ERAR_ECREATE ERAR_MULTI_BRK ERAR_ENCR_WRONG_PASS ERAR_WRONG_PASS ERAR_CHAIN_FOUND ERAR_GENERIC_ALL_ERRORS ERAR_WRONG_FORMAT ERAR_MAP_DIR_YES ERAR_MISSING_PASSWORD ERAR_READ_HEADER) ; "list_files_in_archive" lists details embedded into the archive (files bundled into the .rar archive,archive's comments and header info) It takes two parameters;the first is the file name and the second is the password required by the archive. If no password is required then just pass undef or the empty string as the second parameter "list_files_in_archive" returns $errorcode.If $errorcode is undefined it means that the function executed with no errors. If not, $errorcode will contain an error description. $errorcode=list_files_in_archive($file,$password); print "There was an error : $errorcode" if defined($errorcode); "process_file" takes five parameters;the first is the file name, the second is the password required by the archive, the third is the directory that the file's contents will be extracted to. The fourth dictates if a directory will created (pass ERAR_MAP_DIR_YES) with the same as name as the archive (Map directory to archive name). The last one refers to a callback,optionally. If no password is required then just pass undef or the empty string "process_file" returns $errorcode and $directory.If $errorcode is undefined it means that the function executed with no errors. If not, $errorcode will contain an error description. $directory is the directory where the archive was extracted to : ($errorcode,$directory) = process_file( file=>$file, password=>$password, output_dir_path=>$output_dir_path, selection=>undef,callback=>undef); print "There was an error : $errorcode" if defined($errorcode); Version 2.0 upwards includes support for custom callback while processing of files (line 312 : $callback->(@_) if defined($callback)) For an example of its usefulness take a look at the Unrar Extract and Recover open source application L The Unrar_Extract_and_Recover.pl (3.0) script uses a callback (my $callback=sub { $gui::top->update() }) for allowing the updating of GUI events while the process_file function of Unrar.pm is engaged into extracting the file (which is a long running activity), so the GUI is more responsive, minimizes the 'freezing' time and most importantly allows Pausing while the file is being processed/extracted =head2 Version 2.8 Notes Checking registry for system default non-unicode charsets and using them for transcoding, since some of unrar.dll internal functions use OEM encoding Also exporting those default OS encodings ($ANSI_CP and $OEM_CP) into callers namespace. =head1 ENCODING and INTERNAL WORKINGS "Unicode issues in Perl" article at iProgrammer L Analyzes the encoding/transcoding principles which the module follows For a complete application based on the module look at the Open Source "Unrar Extract and Recover" application L =head1 PREREQUISITES Must have unrar.dll in %SystemRoot%\System32 B<($ENV{"SYSTEMROOT"}."\\system32")> Module does not bundle unrar.dll because the dll is being updated with new features/bug fixes and the module's distribution cannot be monitoring the dll's changes.Therefore the user of the module is required to download the dll himself Get UnRAR dynamic library for Windows software developers from L This package includes the dll,samples,dll internals and error description After downloading place dll in %SystemRoot%\System32 directory B<($ENV{"SYSTEMROOT"}."\\system32")> Module comes with installation test (in "mytest.pl") that checks for dll's existence =head2 TEST AFTER INSTALLATION run "mytest.pl" script (found inside module's distribution "test" directory) as : perl mytest.pl the script runs a test that checks for "unrar.dll" existence in the %SystemRoot%\System32 directory B<($ENV{"SYSTEMROOT"}."\\system32")> and also extracts some sample archives =head2 EXPORT process_file function and most error description constants, by default. list_files_in_archive and %donotprocess explicitly. =head1 AUTHOR Nikos Vaggalis > =head1 COPYRIGHT AND LICENSE Copyright (C) 2009-2011 by Nikos Vaggalis This library and all of its earlier versions are licenced under GPL3.0 =cut