Win32API::File - Low-level access to Win32 system API calls for files/dirs.
use Win32API::File 0.08 qw( :ALL );
MoveFile( $Source, $Destination )
or die "Can't move $Source to $Destination: ",fileLastError(),"\n";
MoveFileEx( $Source, $Destination, MOVEFILE_REPLACE_EXISTING() )
or die "Can't move $Source to $Destination: ",fileLastError(),"\n";
[...]This provides fairly low-level access to the Win32 System API calls dealing with files and directories.
To pass in NULL as the pointer to an optional buffer, pass in an empty list reference, [].
Beyond raw access to the API calls and related constants, this module handles smart buffer allocation and translation of return codes.
All functions, unless otherwise noted, return a true value for success and a false value for failure and set $^E on failure.
WARNING: this is new code, use at your own risk.
This version of Win32API::File can be used like an IO::File object:
my $file = Win32API::File->new("+> foo");
binmode $file;
print $file "hello there\n";
seek $file, 0, 0;
my $line = <$file>;
$file->close;It also supports tying via a win32 handle (for example, from createFile()):
tie FILE, 'Win32API::File', $win32_handle;
print FILE "...";It has not been extensively tested yet and buffered I/O is not yet implemented.
Nothing is exported by default. The following tags can be used to have large sets of symbols exported: ":Func", ":FuncA", ":FuncW", ":Misc", ":DDD_", ":DRIVE_", ":FILE_", ":FILE_ATTRIBUTE_", ":FILE_FLAG_", ":FILE_SHARE_", ":FILE_TYPE_", ":FS_", ":FSCTL_", ":HANDLE_FLAG_", ":IOCTL_STORAGE_", ":IOCTL_DISK_", ":GENERIC_", ":MEDIA_TYPE", ":MOVEFILE_", ":SECURITY_", ":SEM_", and ":PARTITION_".
":Func"The basic function names: attrLetsToBits, createFile, fileConstant, fileLastError, getLogicalDrives, setFilePointer, getFileSize, CloseHandle, CopyFile, CreateFile, DefineDosDevice, DeleteFile, DeviceIoControl, FdGetOsFHandle, GetDriveType, GetFileAttributes, GetFileSize, GetFileType, GetHandleInformation, GetLogicalDrives, GetLogicalDriveStrings, GetOsFHandle, GetOverlappedResult, GetVolumeInformation, IsContainerPartition, IsRecognizedPartition, MoveFile, MoveFileEx, OsFHandleOpen, OsFHandleOpenFd, QueryDosDevice, ReadFile, SetErrorMode, SetFilePointer, SetHandleInformation, and WriteFile.
$uBits= attrLetsToBits( $sAttributeLetters )Converts a string of file attribute letters into an unsigned value with the corresponding bits set. $sAttributeLetters should contain zero or more letters from "achorst":
$hObject= createFile( $sPath )$hObject= createFile( $sPath, $rvhvOptions )$hObject= createFile( $sPath, $svAccess )$hObject= createFile( $sPath, $svAccess, $rvhvOptions )This is a Perl-friendly wrapper around CreateFile.
On failure, $hObject gets set to a false value and regLastError() and $^E are set to the reason for the failure. Otherwise, $hObject gets set to a Win32 native file handle which is always a true value [returns "0 but true" in the impossible(?) case of the handle having a value of 0].
$sPath is the path to the file [or device, etc.] to be opened. See CreateFile for more information on possible special values for $sPath.
$svAccess can be a number containing the bit mask representing the specific type(s) of access to the file that you desire. See the $uAccess parameter to CreateFile for more information on these values.
More likely, $svAccess is a string describing the generic type of access you desire and possibly the file creation options to use. In this case, $svAccess should contain zero or more characters from "qrw" [access desired], zero or one character each from "ktn" and "ce", and optional white space. These letters stand for, respectively, "Query access", "Read access", "Write access", "Keep if exists", "Truncate if exists", "New file only", "Create if none", and "Existing file only". Case is ignored.
You can pass in "?" for $svAccess to have an error message displayed summarizing its possible values. This is very handy when doing on-the-fly programming using the Perl debugger:
Win32API::File::createFile: $svAccess can use the following:
One or more of the following:
q -- Query access (same as 0)
r -- Read access (GENERIC_READ)
w -- Write access (GENERIC_WRITE)
At most one of the following:
k -- Keep if exists
t -- Truncate if exists
n -- New file only (fail if file already exists)
At most one of the following:
c -- Create if doesn't exist
e -- Existing file only (fail if doesn't exist)
'' is the same as 'q k e'
'r' is the same as 'r k e'
'w' is the same as 'w t c'
'rw' is the same as 'rw k c'
'rt' or 'rn' implies 'c'.
Or $access can be numeric.$svAccess is designed to be "do what I mean", so you can skip the rest of its explanation unless you are interested in the complex details. Note that, if you want write access to a device, you need to specify "k" [and perhaps "e", as in "w ke" or "rw ke"] since Win32 suggests OPEN_EXISTING be used when opening a device.
"q"Stands for "Query access". This is really a no-op since you always have query access when you open a file. You can specify "q" to document that you plan to query the file [or device, etc.]. This is especially helpful when you don't want read nor write access since something like "q" or "q ke" may be easier to understand than just "" or "ke".
"r"Stands for "Read access". Sets the GENERIC_READ bit(s) in the $uAccess that is passed to CreateFile. This is the default access if the $svAccess parameter is missing [or if it is undef and $rvhvOptions doesn't specify an "Access" option].
"w"Stands for "Write access". Sets the GENERIC_WRITE bit(s) in the $uAccess that is passed to CreateFile.
"k"Stands for "Keep if exists". If the requested file exists, then it is opened. This is the default unless GENERIC_WRITE access has been requested but GENERIC_READ access has not been requested. Contrast with "t" and "n".
"t"Stands for "Truncate if exists". If the requested file exists, then it is truncated to zero length and then opened. This is the default if GENERIC_WRITE access has been requested and GENERIC_READ access has not been requested. Contrast with "k" and "n".
"n"Stands for "New file only". If the requested file exists, then it is not opened and the createFile call fails. Contrast with "k" and "t". Can't be used with "e".
"c"Stands for "Create if none". If the requested file does not exist, then it is created and then opened. This is the default if GENERIC_WRITE access has been requested or if "t" or "n" was specified. Contrast with "e".