Win32::FileOp

Unless mentioned otherwise all functions work both under WinNT and Win95.

Version 0.10.1

Functions

Copy CopyConfirm CopyConfirmEach CopyEx

Move MoveConfirm MoveConfirmEach MoveEx

MoveFile MoveFileEx CopyFile MoveAtReboot

Recycle RecycleConfirm RecycleConfirmEach RecycleEx

Delete DeleteConfirm DeleteConfirmEach DeleteEx DeleteAtReboot

UpdateDir FillInDir

Compress Uncompress Compressed SetCompression GetCompression CompressDir UncompressDir

AddToRecentDocs EmptyRecentDocs

WriteToINI WriteToWININI ReadINI ReadWININI

DeleteFromINI DeleteFromWININI

OpenDialog SaveAsDialog BrowseForFolder

Map Unmap Disconnect Mapped

GetDesktopHandle

use Win32::FileOp $handle = GetDesktopHandle()

Same as: $handle = $Win32::FileOp::DesktopHandle

Used to get desktop window handle when confirmation is used. The value of the handle can be gotten from $Win32::FileOp::DesktopHandle.

Returns the Desktop Window handle.

GetWindowHandle

use Win32::FileOp $handle = GetWindowHandle()

Same as: $handle = $Win32::FileOp::WindowHandle

Used to get the console window handle when confirmation is used. The value of the handle can be gotten from $Win32::FileOp::WindowHandle.

Returns the Console Window handle.

Copy

Copy ($FileName => $FileOrDirectoryName [, ...]) Copy (\@FileNames => $DirectoryName [, ...] ) Copy (\@FileNames => \@FileOrDirectoryNames [, ...])

Copies the specified files. Doesn't show any confirmation nor progress dialogs.

It may show an error message dialog, because I had to omit FOF_NOERRORUI from its call to allow for autocreating directories.

You should end the directory names by backslash so that they are not mistaken for filenames. It is not necessary if the directory already exists or if you use Copy \@filenames => $dirname.

Returns true if successful.

CopyConfirm

CopyConfirm ($FileName => $FileOrDirectoryName [, ...]) CopyConfirm (\@FileNames => $DirectoryName [, ...] ) CopyConfirm (\@FileNames => \@FileOrDirectoryNames [, ...])

Copies the specified files. In case of a collision, shows a confirmation dialog. Shows progress dialogs.

Returns true if successful.

CopyConfirmEach

The same as CopyConfirm.

CopyEx

CopyEx ($FileName => $FileOrDirectoryName, [...], $options) CopyEx (\@FileNames => $DirectoryName, [...], $options) CopyEx (\@FileNames => \@FileOrDirectoryNames, [...], $options)

Copies the specified files. See below for the available options ( FOF_ constants).

Returns true if successful.

Move

Moves the specified files. Parameters as Copy

It may show an error message dialog, because I had to omit FOF_NOERRORUI from its call to allow for autocreating directories.

MoveConfirm

Moves the specified files. Parameters as CopyConfirm

MoveConfirmEach

The same as MoveConfirm

MoveEx

Moves the specified files. Parameters as CopyEx

MoveAtReboot

MoveAtReboot ($FileName => $DestFileName, [...])

This function moves the file during the next start of the system.

MoveFile

MoveFile ($FileName => $DestFileName [, ...])

Move files. This function uses API function MoveFileEx as well as MoveAtReboot. It may be a little quicker than Move , but it doesn't understand wildcards and the $DestFileName may not be a directory.

MoveFileEx

MoveFileEx ($FileName => $DestFileName [, ...], $options)

This is a simple wrapper around the API function MoveFileEx, it calls the function for every pair of files with the $options you specify. See below for the available options ( FOF_ ... constants).

CopyFile

CopyFile ($FileName => $DestFileName [, $FileName2 => $DestFileName2 [, ...]])

Copy a file somewhere. This function is not able to copy directories!

Recycle

Recycle @filenames

Send the files into the recycle bin. You will not get any confirmation dialogs.

Returns true if successful.

RecycleConfirm

RecycleConfirm @filenames

Send the files into the recycle bin. You will get a confirmation dialog if you have ``Display delete confirmation dialog'' turned on in your recycle bin. You will confirm the deletion of all the files at once.

Returns true if successful. Please remember that this function is successful even if the user chose [No] on the confirmation dialog!

RecycleConfirmEach

RecycleConfirmEach @filenames

Send the files into the recycle bin. You will get a separate confirmation dialog for each file if you have ``Display delete confirmation dialog'' turned on in your recycle bin. You will confirm the deletion of all the files at once.

Returns the number of files that were successfully deleted.

RecycleEx

RecycleEx @filenames, $options

Send the files into the recycle bin. You may specify the options for deleting, see below. You may get a confirmation dialog if you have "Display delete confirmation dialog" turned on in your recycle bin, if so, you will confirm the deletion of all the files at once.

Returns true if successful. Please remember that this function is successful even if the user chose [No] on the confirmation dialog!

The $options may be constructed from FOF_ ... constants.

Delete

Delete @filenames

Deletes the files. You will not get any confirmation dialogs.

Returns true if successful.

DeleteConfirm

DeleteConfirm @filenames

Deletes the the files. You will get a confirmation dialog to confirm the deletion of all the files at once.

Returns true if successful. Please remember that this function is successful even if the user selected [No] on the confirmation dialog!

DeleteConfirmEach

DeleteConfirmEach @filenames

Deletes the files. You will get a separate confirmation dialog for each file.

Returns the number of files that were successfully deleted.

DeleteEx

DeleteEx @filenames, $options

Deletes the files. You may specify the options for deleting, see below. You may get a confirmation dialog if you have "Display delete confirmation dialog" turned on in your recycle bin.

Returns true if successful. Please remember that this function is successful even if the user selected [No] on the confirmation dialog!

DeleteAtReboot

DeleteAtReboot @files

This function moves the file during the next start of the system.

UpdateDir

UpdateDir $SourceDirectory, $DestDirectory [, \&callback]

Copy the newer or updated files from $SourceDir to $DestDir. Processes subdirectories! The &callback function is called for each file to be copied. The parameters it gets are exactly the same as the callback function in File::Find. That is $_, $File::Find::dir and $File::Find::name.

If this function returns a false value, the file is skipped.

Ex. UpdateDir 'c:\dir' => 'e:\dir', sub {print '.'}; UpdateDir 'c:\dir' => 'e:\dir', sub {if (/^s/i) {print '.'}};

FillInDir

FillInDir $SourceDirectory, $DestDirectory [, \&callback]

Copy the files from $SourceDir not present in $DestDir. Processes subdirectories! The &callback works the same as in UpdateDir.

Compress

Compress $filename [, ...]

Compresses the file(s) or directories using the transparent WinNT compression (The same as checking the ``Compressed'' checkbox in Explorer properties fo the file).

It doesn't compress all files and subdirectories in a directory you specify. Use ComressDir for that. Compress($directory) only sets the compression flag for the directory so that the new files are compressed by default.

WinNT only!

Uncompress

Uncompress $filename [, ...]

Uncompresses the file(s) using the transparent WinNT compression (The same as unchecking the ``Compressed'' checkbox in Explorer properties fo the file).

WinNT only!

Compressed

Compressed $filename

Checks the compression status for a file.

SetCompression

SetCompression $filename [, $filename], $value

Sets the compression status for file(s). The $value should be either 1 or 0.

GetCompression

GetCompression $filename

Checks the compression status for a file.

CompressDir

CompressDir $directory, ... [, \&callback]

Recursively descends the directory(ies) specified and compresses all files and directories within. If you specify the \&callback, the specified function gets executed for each of the files and directories. If the callback returns false, no compression is done on the file/directory.

The parameters the callback gets are exactly the same as the callback function in File::Find. That is $_, $File::Find::dir and $File::Find::name.

UncompressDir

UncompressDir $directory, ... [, \&callback]

The counterpart of CompressDir.

AddToRecentDocs

AddToRecentDocs $filename [, ...]

Add a shortcut(s) to the file(s) into the Recent Documents folder. The shortcuts will appear in the Documents submenu of Start Menu.

The paths may be relative.

EmptyRecentDocs

EmptyRecentDocs;

Deletes all shortcuts from the Recent Documents folder.

WriteToINI

WriteToINI $INIfile, $section, $name1 => $value [, $name2 => $value2 [, ...]]

Copies a string into the specified section of the specified initialization file. You may pass several name/value pairs at once.

Returns 1 if successful, undef otherwise. See Win32::GetLastError & Win32::FormatMessage(Win32::GetLastError) if failed for the error code and message.

WriteToWININI

WriteToWININI $section, $name1 => $value1 [, $name2 => $value2 [, ...]]

Copies a string into the specified section of WIN.INI. You may pass several name/value pairs at once.

Please note that some values or sections of WIN.INI and some other INI files are mapped to registry so they do not show up in the INI file even if they were successfully written!

ReadINI

$value = ReadINI $INIfile, $section, $name [, $defaultvalue]

Reads a value from an INI file. If you do not specify the default and the value is not found you'll get undef.

ReadWININI

$value = ReadWININI $section, $name [, $defaultvalue]

Reads a value from WIN.INI file. If you do not specify the default and the value is not found you'll get undef.

Please note that some values or sections of WIN.INI and some other INI files are mapped to registry so even that they do not show up in the INI file this function will find and read them!

DeleteFromINI

DeleteFromINI $INIfile, $section, @names_to_delete

Delete a value from an INI file.

DeleteFromWININI

DeleteFromWININI $section, @names_to_delete

Delete a value from WIN.INI.

ReadINISections

@sections = ReadINISections($inifile); \@sections = ReadINISections($inifile); ReadINISections($inifile,\@sections);

Enumerate the sections in a INI file. If you do not specify the INI file, it enumerates the contents of win.ini.

ReadINISectionKeys

@sections = ReadINISectionKeys($inifile, $section); \@sections = ReadINISectionKeys($inifile, $section); ReadINISectionKeys($inifile, $section, \@sections);

Enumerate the keys in a section of a INI file. If you do not specify the INI file, it enumerates the contents of win.ini.

OpenDialog

$filename = OpenDialog \%parameters [, $defaultfilename] @filenames = OpenDialog \%parameters [, $defaultfilename] $filename = OpenDialog %parameters [, $defaultfilename] @filenames = OpenDialog %parameters [, $defaultfilename]

Creates the standard Open dialog allowing you to select some files.

Returns a list of selected files or undef if the user pressed [Escape]. It also sets two global variables :

$Win32::FileOp::ReadOnly = the user requested a readonly access. $Win32::FileOp::SelectedFilter = the id of filter selected in the dialogbox %parameters title => the title for the dialog, default is 'Open' 'Open file' filters => definition of file filters { 'Filter 1' => '*.txt;*.doc', 'Filter 2' => '*.pl;*.pm'} [ 'Filter 1' => '*.txt;*.doc', 'Filter 2' => '*.pl;*.pm'] [ 'Filter 1' => '*.txt;*.doc', 'Filter 2' => '*.pl;*.pm' , $default] "Filter 1\0*.txt;*.doc\0Filter 2\0*.pl;*.pm" defaultfilter => the number of the default filter counting from 1. Please keep in mind that hashes do not preserve ordering! dir => the initial directory for the dialog, default is the current directory filename => the default filename to be showed in the dialog extension => the default extension, this function appends this extension to the filename if the user fails to type an extension. This string can be any length, but only the first three characters are appended. The string should not contain a period (.). handle => the handle to the window which will own this dialog Default is the console of the perl script. If you do not want to tie the dialog to any window use handle => 0 options => options for the dialog, see bellow OFN_... constants

SaveAsDialog

Creates the Save As dialog box, parameters are the same as for OpenDialog.

BrowseForFolder

BrowseForFolder [$title [, $rootFolder [, $options]]]

Creates the standard ``Browse For Folder'' dialog. The $title specifies the text to be displayed below the title of the dialog. The $rootFolder may be one of the CSIDL_ ... constants. For $options you should use the BIF_ ... constants. Description of the constants is bellow.

Map

Map $drive => $share; $drive = Map $share; Map $drive => $share, \%options; $drive = Map $share, \%options;

Map a drive letter or LTPx to a network resource. If successfull returns the drive letter/LPTx.

If you do not specify the drive letter, the function uses the last free letter. Since the function doesn't require the ':' in the drive name you may use the function like this:

Map H => '\\\\server\share'; as well as Map 'H:' => '\\\\server\share'; Options: persistent = 0/1, should the connection be restored on next logon? user = username to be used to connect the device passwd = password to be used to connect the device overwrite = 0/1, should the drive be remapped if it was already connected? Example: Map I => '\\\\servername\share', {persistent=>1,overwrite=>1};

Disconnect

Disconnect $drive_or_share; Disconnect $drive_or_share, \%options;

Breaks an existing network connection. It can also be used to remove remembered network connections that are not currently connected.

$drive_or_share specifies the name of either the redirected local device or the remote network resource to disconnect from. If this parameter specifies a redirected local resource, only the specified redirection is broken; otherwise, all connections to the remote network resource are broken.

Options: persistent = 0/1, if you do not use persistent=>1, the connection will be closed, but the drive letter will still be mapped to the device force = 0/1, disconnect even if there are some open files See also: Unmap

Unmap

Unmap $drive_or_share; Unmap $drive_or_share, \%options;

The only difference from Disconnect is that persistent=>1 is the default.

Mapped

%drives = Mapped; $share = Mapped $drive; $drive = Mapped $share; # currently not implemented !!!

This function retrieves the name of the network resource associated with a local device. Or vice versa.

If you do not specify any parameter, you get a hash of drives and shares.

To get the error message from most of these functions, you should not use $!, but Win32::FormatMessage(Win32::GetLastError())!

Options

FOF_

FOF_SILENT = do not show the progress dialog FOF_RENAMEONCOLLISION = rename the file in case of collision ('file.txt' -> 'Copy of file.txt') FOF_NOCONFIRMATION = do not show the confirmation dialog FOF_ALLOWUNDO = send file(s) to RecycleBin instead of deleting FOF_FILESONLY = skip directories FOF_SIMPLEPROGRESS = do not show the filenames in the process dialog FOF_NOCONFIRMMKDIR = do not confirm creating directories FOF_NOERRORUI = do not report errors FOF_NOCOPYSECURITYATTRIBS = do not copy security attributes

OFN_

OFN_ALLOWMULTISELECT

Specifies that the File Name list box allows multiple selections. If you also set the OFN_EXPLORER flag, the dialog box uses the Explorer-style user interface; otherwise, it uses the old-style user interface.

OFN_CREATEPROMPT

If the user specifies a file that does not exist, this flag causes the dialog box to prompt the user for permission to create the file. If the user chooses to create the file, the dialog box closes and the function returns the specified name; otherwise, the dialog box remains open.

OFN_EXPLORER

Since I cannot implement hook procedures through Win32::API (AFAIK), this option in not necessary.

OFN_FILEMUSTEXIST

Specifies that the user can type only names of existing files in the File Name entry field. If this flag is specified and the user enters an invalid name, the dialog box procedure displays a warning in a message box. If this flag is specified, the OFN_PATHMUSTEXIST flag is also used.

OFN_HIDEREADONLY

Hides the Read Only check box.

OFN_LONGNAMES

For old-style dialog boxes, this flag causes the dialog box to use long filenames. If this flag is not specified, or if the OFN_ALLOWMULTISELECT flag is also set, old-style dialog boxes use short filenames (8.3 format) for filenames with spaces. Explorer-style dialog boxes ignore this flag and always display long filenames.

OFN_NOCHANGEDIR

Restores the current directory to its original value if the user changed the directory while searching for files.

OFN_NODEREFERENCELINKS

Directs the dialog box to return the path and filename of the selected shortcut (.LNK) file. If this value is not given, the dialog box returns the path and filename of the file referenced by the shortcut

OFN_NOLONGNAMES

For old-style dialog boxes, this flag causes the dialog box to use short filenames (8.3 format). Explorer-style dialog boxes ignore this flag and always display long filenames.

OFN_NONETWORKBUTTON

Hides and disables the Network button.

OFN_NOREADONLYRETURN

Specifies that the returned file does not have the Read Only check box checked and is not in a write-protected directory.

OFN_NOTESTFILECREATE

Specifies that the file is not created before the dialog box is closed. This flag should be specified if the application saves the file on a create-nonmodify network sharepoint. When an application specifies this flag, the library does not check for write protection, a full disk, an open drive door, or network protection. Applications using this flag must perform file operations carefully, because a file cannot be reopened once it is closed.

OFN_NOVALIDATE

Specifies that the dialog boxes allow invalid characters in the returned filename.

OFN_OVERWRITEPROMPT

Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.

OFN_PATHMUSTEXIST

Specifies that the user can type only valid paths and filenames. If this flag is used and the user types an invalid path and filename in the File Name entry field, the dialog box function displays a warning in a message box.

OFN_READONLY

Causes the Read Only check box to be checked initially when the dialog box is created. If the check box is checked when the dialog box is closed $Win32::FileOp::ReadOnly is set to true.

OFN_SHAREAWARE

Specifies that if a call to the OpenFile function fails because of a network sharing violation, the error is ignored and the dialog box returns the selected filename.

OFN_SHOWHELP

Causes the dialog box to display the Help button. The hwndOwner member must specify the window to receive the HELPMSGSTRING registered messages that the dialog box sends when the user clicks the Help button.

BIF_

BIF_DONTGOBELOWDOMAIN

Does not include network folders below the domain level in the tree view control.

BIF_RETURNONLYFSDIRS

Only returns file system directories. If the user selects folders that are not part of the file system, the OK button is grayed.

BIF_RETURNFSANCESTORS

Only returns file system ancestors. If the user selects anything other than a file system ancestor, the OK button is grayed.

This option is strange, cause it seems to allow you to select only computers. I don't know the definition of a filesystem ancestor, but I didn't think it would be a computer. ?-|

BIF_BROWSEFORCOMPUTER

Only returns computers. If the user selects anything other than a computer, the OK button is grayed.

BIF_BROWSEFORPRINTER

Only returns printers. If the user selects anything other than a printer, the OK button is grayed.

BIF_STATUSTEXT

Since it is currently impossible to define callbacks, this options is useless.

CSIDL_

CSIDL_BITBUCKET

Recycle bin --- file system directory containing file objects in the user's recycle bin. The location of this directory is not in the registry; it is marked with the hidden and system attributes to prevent the user from moving or deleting it.

CSIDL_CONTROLS

Control Panel --- virtual folder containing icons for the control panel applications.

CSIDL_DESKTOP

Windows desktop --- virtual folder at the root of the name space.

CSIDL_DESKTOPDIRECTORY

File system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself).

CSIDL_DRIVES

My Computer --- virtual folder containing everything on the local computer: storage devices, printers, and Control Panel. The folder may also contain mapped network drives.

CSIDL_FONTS

Virtual folder containing fonts.

CSIDL_NETHOOD

File system directory containing objects that appear in the network neighborhood.

CSIDL_NETWORK

Network Neighborhood --- virtual folder representing the top level of the network hierarchy.

CSIDL_PERSONAL

File system directory that serves as a common repository for documents.

CSIDL_PRINTERS

Printers folder --- virtual folder containing installed printers.

CSIDL_PROGRAMS

File system directory that contains the user's program groups (which are also file system directories).

CSIDL_RECENT

File system directory that contains the user's most recently used documents.

CSIDL_SENDTO

File system directory that contains Send To menu items.

CSIDL_STARTMENU

File system directory containing Start menu items.

CSIDL_STARTUP

File system directory that corresponds to the user's Startup program group.

CSIDL_TEMPLATES

File system directory that serves as a common repository for document templates.

Not all options make sense in all functions!

Variables

$Win32::FileOp::ProgressTitle

This variable (if defined) contains the text to be displayed on the progress dialog if using FOF_SIMPLEPROGRESS. This allows you to present the user with your own message about what is happening to his computer.

If the options for the call do not contain FOF_SIMPLEPROGRESS, this variable is ignored.

Examples

use Win32::FileOp; CopyConfirm ('c:\temp\kinter.pl' => 'c:\temp\copy\\', ['\temp\kinter1.pl', 'temp\kinter2.pl'] => ['c:\temp\copy1.pl', 'c:\temp\copy2.pl']); $Win32::FileOp::ProgressTitle = "Moving the temporary files ..."; MoveEx 'c:\temp\file.txt' => 'd:\temp\\', ['c:\temp\file1.txt','c:\temp\file2.txt'] => 'd:\temp', FOF_RENAMEONCOLLISION | FOF_SIMPLEPROGRESS; undef $Win32::FileOp::ProgressTitle; Recycle 'c:\temp\kinter.pl';

Handles

All the functions keep Win32::API handles between calls. If you want to free the handles you may undefine them, but NEVER EVER set them to anything else than undef !!! Even ``$handlename = $handlename;'' would destroy the handle without repair! See docs for Lazy.pm for explanation.

List of handles and functions that use them:

$Win32::FileOp::fileop : Copy, CopyEx, CopyConfirm, Move, MoveEx, MoveConfirm Delete, DeleteEx, DeleteConfirm, Recycle, RecycleEx, RecycleConfirm $Win32::FileOp::movefileex : MoveFileEx MoveFile MoveAtReboot $Win32::FileOp::movefileexDel : DeleteAtReboot $Win32::FileOp::copyfile : CopyFile $Win32::FileOp::writeINI : WriteToINI MoveAtReboot DeleteAtReboot $Win32::FileOp::writeWININI : WriteToWININI $Win32::FileOp::deleteINI : DeleteFromINI $Win32::FileOp::deleteWININI : DeleteFromWININI $Win32::FileOp::readINI : ReadINI $Win32::FileOp::readWININI : ReadWININI $Win32::FileOp::GetOpenFileName : OpenDialog $Win32::FileOp::GetSaveFileName : SaveAsDialog $Win32::FileOp::SHAddToRecentDocs : AddToRecentDocs EmptyRecentDocs $Win32::FileOp::DesktopHandle $Win32::FileOp::WindowHandle : OpenDialog SaveDialog $Win32::FileOp::WNetAddConnection3 : Map $Win32::FileOp::WNetGetConnection : Mapped $Win32::FileOp::WNetCancelConnection2 : Unmap Disconnect Map $Win32::FileOp::GetLogicalDrives : FreeDriveLetters Map

Notes

By default all functions are exported! If you do not want to polute your namespace too much import only the functions you need. You may import either single functions or whole groups.

The available groups are :

BASIC = Move..., Copy..., Recycle... and Delete... functions plus constants _BASIC = FOF_... constants only HANDLES = DesktopHandle GetDesktopHandle WindowHandle GetWindowHandle INI = WriteToINI WriteToWININI ReadINI ReadWININI ReadINISectionKeys DeleteFromINI DeleteFromWININI DIALOGS = OpenDialog SaveAsDialog plus OFN_... constants _DIALOGS = only OFN_... constants RECENT = AddToRecentDocs, EmptyRecentDocs DIRECTORY = UpdateDir, FillInDir COMPRESS => Compress Uncompress Compressed SetCompression GetCompression MAP => Map Unmap Disconnect Mapped

Examples:

use Win32::FileOp qw(:BASIC GetDesktopHandle); use Win32::FileOp qw(:_BASIC MoveEx CopyEx); use Win32::FileOp qw(:INI :_DIALOGS SaveAsDialog);

This module contains all methods from Win32::RecycleBin. The only change you have to do is to use this module instead of the old Win32::RecycleBin. Win32:RecycleBin is not supported anymore!

AUTHORS

Module built by : Jan Krynicky <Jenda@Krynicky.cz> $Bill Luebkert <dbe@wgn.net> Mike Blazer <blazer@mail.nevalink.ru> Aldo Calpini <a.calpini@romagiubileo.it> Michael Yamada <myamada@gj.com>