1b39c5158Smillert# File.pm -- Low-level access to Win32 file/dir functions/constants. 2b39c5158Smillert 3b39c5158Smillertpackage Win32API::File; 4b39c5158Smillert 5b39c5158Smillertuse strict; 6b39c5158Smillertuse integer; 7b39c5158Smillertuse Carp; 8b39c5158Smillertuse Config qw( %Config ); 9b39c5158Smillertuse Fcntl qw( O_RDONLY O_RDWR O_WRONLY O_APPEND O_BINARY O_TEXT ); 10b39c5158Smillertuse vars qw( $VERSION @ISA ); 11b39c5158Smillertuse vars qw( @EXPORT @EXPORT_OK @EXPORT_FAIL %EXPORT_TAGS ); 12b39c5158Smillert 13*56d68f1eSafresh1$VERSION= '0.1203_01'; 14b39c5158Smillert 15b39c5158Smillertuse base qw( Exporter DynaLoader Tie::Handle IO::File ); 16b39c5158Smillert 17b39c5158Smillert# Math::BigInt optimizations courtesy of Tels 18b39c5158Smillertmy $_64BITINT; 19b39c5158SmillertBEGIN { 20b39c5158Smillert $_64BITINT = defined($Config{use64bitint}) && 21b39c5158Smillert ($Config{use64bitint} eq 'define'); 22b39c5158Smillert 23b39c5158Smillert require Math::BigInt unless $_64BITINT; 24b39c5158Smillert} 25b39c5158Smillert 26b39c5158Smillertmy $THIRTY_TWO = $_64BITINT ? 32 : Math::BigInt->new(32); 27b39c5158Smillert 28b39c5158Smillertmy $FFFFFFFF = $_64BITINT ? 0xFFFFFFFF : Math::BigInt->new(0xFFFFFFFF); 29b39c5158Smillert 30b39c5158Smillert@EXPORT= qw(); 31b39c5158Smillert%EXPORT_TAGS= ( 32b39c5158Smillert Func => [qw( attrLetsToBits createFile 33b39c5158Smillert fileConstant fileLastError getLogicalDrives 34b39c5158Smillert CloseHandle CopyFile CreateFile 35b39c5158Smillert DefineDosDevice DeleteFile DeviceIoControl 36b39c5158Smillert FdGetOsFHandle GetDriveType GetFileAttributes GetFileType 37b39c5158Smillert GetHandleInformation GetLogicalDrives GetLogicalDriveStrings 38b39c5158Smillert GetOsFHandle GetVolumeInformation IsRecognizedPartition 39b39c5158Smillert IsContainerPartition MoveFile MoveFileEx 40b39c5158Smillert OsFHandleOpen OsFHandleOpenFd QueryDosDevice 41b39c5158Smillert ReadFile SetErrorMode SetFilePointer 42b39c5158Smillert SetHandleInformation WriteFile GetFileSize 43b39c5158Smillert getFileSize setFilePointer GetOverlappedResult)], 44b39c5158Smillert FuncA => [qw( 45b39c5158Smillert CopyFileA CreateFileA DefineDosDeviceA 46b39c5158Smillert DeleteFileA GetDriveTypeA GetFileAttributesA GetLogicalDriveStringsA 47b39c5158Smillert GetVolumeInformationA MoveFileA MoveFileExA 48b39c5158Smillert QueryDosDeviceA )], 49b39c5158Smillert FuncW => [qw( 50b39c5158Smillert CopyFileW CreateFileW DefineDosDeviceW 51b39c5158Smillert DeleteFileW GetDriveTypeW GetFileAttributesW GetLogicalDriveStringsW 52b39c5158Smillert GetVolumeInformationW MoveFileW MoveFileExW 53b39c5158Smillert QueryDosDeviceW )], 54b39c5158Smillert Misc => [qw( 55b39c5158Smillert CREATE_ALWAYS CREATE_NEW FILE_BEGIN 56b39c5158Smillert FILE_CURRENT FILE_END INVALID_HANDLE_VALUE 57b39c5158Smillert OPEN_ALWAYS OPEN_EXISTING TRUNCATE_EXISTING )], 58b39c5158Smillert DDD_ => [qw( 59b39c5158Smillert DDD_EXACT_MATCH_ON_REMOVE DDD_RAW_TARGET_PATH 60b39c5158Smillert DDD_REMOVE_DEFINITION )], 61b39c5158Smillert DRIVE_ => [qw( 62b39c5158Smillert DRIVE_UNKNOWN DRIVE_NO_ROOT_DIR DRIVE_REMOVABLE 63b39c5158Smillert DRIVE_FIXED DRIVE_REMOTE DRIVE_CDROM 64b39c5158Smillert DRIVE_RAMDISK )], 65b39c5158Smillert FILE_ => [qw( 66b39c5158Smillert FILE_READ_DATA FILE_LIST_DIRECTORY 67b39c5158Smillert FILE_WRITE_DATA FILE_ADD_FILE 68b39c5158Smillert FILE_APPEND_DATA FILE_ADD_SUBDIRECTORY 69b39c5158Smillert FILE_CREATE_PIPE_INSTANCE FILE_READ_EA 70b39c5158Smillert FILE_WRITE_EA FILE_EXECUTE 71b39c5158Smillert FILE_TRAVERSE FILE_DELETE_CHILD 72b39c5158Smillert FILE_READ_ATTRIBUTES FILE_WRITE_ATTRIBUTES 73b39c5158Smillert FILE_ALL_ACCESS FILE_GENERIC_READ 74b39c5158Smillert FILE_GENERIC_WRITE FILE_GENERIC_EXECUTE )], 75b39c5158Smillert FILE_ATTRIBUTE_ => [qw( 76b39c5158Smillert INVALID_FILE_ATTRIBUTES 77b39c5158Smillert FILE_ATTRIBUTE_DEVICE FILE_ATTRIBUTE_DIRECTORY 78b39c5158Smillert FILE_ATTRIBUTE_ENCRYPTED FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 79b39c5158Smillert FILE_ATTRIBUTE_REPARSE_POINT FILE_ATTRIBUTE_SPARSE_FILE 80b39c5158Smillert FILE_ATTRIBUTE_ARCHIVE FILE_ATTRIBUTE_COMPRESSED 81b39c5158Smillert FILE_ATTRIBUTE_HIDDEN FILE_ATTRIBUTE_NORMAL 82b39c5158Smillert FILE_ATTRIBUTE_OFFLINE FILE_ATTRIBUTE_READONLY 83b39c5158Smillert FILE_ATTRIBUTE_SYSTEM FILE_ATTRIBUTE_TEMPORARY )], 84b39c5158Smillert FILE_FLAG_ => [qw( 85b39c5158Smillert FILE_FLAG_BACKUP_SEMANTICS FILE_FLAG_DELETE_ON_CLOSE 86b39c5158Smillert FILE_FLAG_NO_BUFFERING FILE_FLAG_OVERLAPPED 87b39c5158Smillert FILE_FLAG_POSIX_SEMANTICS FILE_FLAG_RANDOM_ACCESS 88b39c5158Smillert FILE_FLAG_SEQUENTIAL_SCAN FILE_FLAG_WRITE_THROUGH 89b39c5158Smillert FILE_FLAG_OPEN_REPARSE_POINT )], 90b39c5158Smillert FILE_SHARE_ => [qw( 91b39c5158Smillert FILE_SHARE_DELETE FILE_SHARE_READ FILE_SHARE_WRITE )], 92b39c5158Smillert FILE_TYPE_ => [qw( 93b39c5158Smillert FILE_TYPE_CHAR FILE_TYPE_DISK FILE_TYPE_PIPE 94b39c5158Smillert FILE_TYPE_UNKNOWN )], 95b39c5158Smillert FS_ => [qw( 96b39c5158Smillert FS_CASE_IS_PRESERVED FS_CASE_SENSITIVE 97b39c5158Smillert FS_UNICODE_STORED_ON_DISK FS_PERSISTENT_ACLS 98b39c5158Smillert FS_FILE_COMPRESSION FS_VOL_IS_COMPRESSED )], 99b39c5158Smillert FSCTL_ => [qw( 100b39c5158Smillert FSCTL_SET_REPARSE_POINT FSCTL_GET_REPARSE_POINT 101b39c5158Smillert FSCTL_DELETE_REPARSE_POINT )], 102b39c5158Smillert HANDLE_FLAG_ => [qw( 103b39c5158Smillert HANDLE_FLAG_INHERIT HANDLE_FLAG_PROTECT_FROM_CLOSE )], 104b39c5158Smillert IOCTL_STORAGE_ => [qw( 105b39c5158Smillert IOCTL_STORAGE_CHECK_VERIFY IOCTL_STORAGE_MEDIA_REMOVAL 106b39c5158Smillert IOCTL_STORAGE_EJECT_MEDIA IOCTL_STORAGE_LOAD_MEDIA 107b39c5158Smillert IOCTL_STORAGE_RESERVE IOCTL_STORAGE_RELEASE 108b39c5158Smillert IOCTL_STORAGE_FIND_NEW_DEVICES IOCTL_STORAGE_GET_MEDIA_TYPES 109b39c5158Smillert )], 110b39c5158Smillert IOCTL_DISK_ => [qw( 111b39c5158Smillert IOCTL_DISK_FORMAT_TRACKS IOCTL_DISK_FORMAT_TRACKS_EX 112b39c5158Smillert IOCTL_DISK_GET_DRIVE_GEOMETRY IOCTL_DISK_GET_DRIVE_LAYOUT 113b39c5158Smillert IOCTL_DISK_GET_MEDIA_TYPES IOCTL_DISK_GET_PARTITION_INFO 114b39c5158Smillert IOCTL_DISK_HISTOGRAM_DATA IOCTL_DISK_HISTOGRAM_RESET 115b39c5158Smillert IOCTL_DISK_HISTOGRAM_STRUCTURE IOCTL_DISK_IS_WRITABLE 116b39c5158Smillert IOCTL_DISK_LOGGING IOCTL_DISK_PERFORMANCE 117b39c5158Smillert IOCTL_DISK_REASSIGN_BLOCKS IOCTL_DISK_REQUEST_DATA 118b39c5158Smillert IOCTL_DISK_REQUEST_STRUCTURE IOCTL_DISK_SET_DRIVE_LAYOUT 119b39c5158Smillert IOCTL_DISK_SET_PARTITION_INFO IOCTL_DISK_VERIFY )], 120b39c5158Smillert GENERIC_ => [qw( 121b39c5158Smillert GENERIC_ALL GENERIC_EXECUTE 122b39c5158Smillert GENERIC_READ GENERIC_WRITE )], 123b39c5158Smillert MEDIA_TYPE => [qw( 124b39c5158Smillert Unknown F5_1Pt2_512 F3_1Pt44_512 125b39c5158Smillert F3_2Pt88_512 F3_20Pt8_512 F3_720_512 126b39c5158Smillert F5_360_512 F5_320_512 F5_320_1024 127b39c5158Smillert F5_180_512 F5_160_512 RemovableMedia 128b39c5158Smillert FixedMedia F3_120M_512 )], 129b39c5158Smillert MOVEFILE_ => [qw( 130b39c5158Smillert MOVEFILE_COPY_ALLOWED MOVEFILE_DELAY_UNTIL_REBOOT 131b39c5158Smillert MOVEFILE_REPLACE_EXISTING MOVEFILE_WRITE_THROUGH )], 132b39c5158Smillert SECURITY_ => [qw( 133b39c5158Smillert SECURITY_ANONYMOUS SECURITY_CONTEXT_TRACKING 134b39c5158Smillert SECURITY_DELEGATION SECURITY_EFFECTIVE_ONLY 135b39c5158Smillert SECURITY_IDENTIFICATION SECURITY_IMPERSONATION 136b39c5158Smillert SECURITY_SQOS_PRESENT )], 137b39c5158Smillert SEM_ => [qw( 138b39c5158Smillert SEM_FAILCRITICALERRORS SEM_NOGPFAULTERRORBOX 139b39c5158Smillert SEM_NOALIGNMENTFAULTEXCEPT SEM_NOOPENFILEERRORBOX )], 140b39c5158Smillert PARTITION_ => [qw( 141b39c5158Smillert PARTITION_ENTRY_UNUSED PARTITION_FAT_12 142b39c5158Smillert PARTITION_XENIX_1 PARTITION_XENIX_2 143b39c5158Smillert PARTITION_FAT_16 PARTITION_EXTENDED 144b39c5158Smillert PARTITION_HUGE PARTITION_IFS 145b39c5158Smillert PARTITION_FAT32 PARTITION_FAT32_XINT13 146b39c5158Smillert PARTITION_XINT13 PARTITION_XINT13_EXTENDED 147b39c5158Smillert PARTITION_PREP PARTITION_UNIX 148b39c5158Smillert VALID_NTFT PARTITION_NTFT )], 14991f110e0Safresh1 STD_HANDLE_ => [qw( 15091f110e0Safresh1 STD_INPUT_HANDLE STD_OUTPUT_HANDLE 15191f110e0Safresh1 STD_ERROR_HANDLE )], 152b39c5158Smillert); 153b39c5158Smillert@EXPORT_OK= (); 154b39c5158Smillert{ 155b39c5158Smillert my $key; 156b39c5158Smillert foreach $key ( keys(%EXPORT_TAGS) ) { 157b39c5158Smillert push( @EXPORT_OK, @{$EXPORT_TAGS{$key}} ); 158b39c5158Smillert #push( @EXPORT_FAIL, @{$EXPORT_TAGS{$key}} ) unless $key =~ /^Func/; 159b39c5158Smillert } 160b39c5158Smillert} 161b39c5158Smillert$EXPORT_TAGS{ALL}= \@EXPORT_OK; 162b39c5158Smillert 163b39c5158Smillertbootstrap Win32API::File $VERSION; 164b39c5158Smillert 165b39c5158Smillert# Preloaded methods go here. 166b39c5158Smillert 167b39c5158Smillert# To convert C constants to Perl code in cFile.pc 168b39c5158Smillert# [instead of C or C++ code in cFile.h]: 169b39c5158Smillert# * Modify F<Makefile.PL> to add WriteMakeFile() => 170b39c5158Smillert# CONST2PERL/postamble => [[ "Win32API::File" => ]] WRITE_PERL => 1. 171b39c5158Smillert# * Either comment out C<#include "cFile.h"> from F<File.xs> 172b39c5158Smillert# or make F<cFile.h> an empty file. 173b39c5158Smillert# * Make sure the following C<if> block is not commented out. 174b39c5158Smillert# * "nmake clean", "perl Makefile.PL", "nmake" 175b39c5158Smillert 176b39c5158Smillertif( ! defined &GENERIC_READ ) { 177b39c5158Smillert require "Win32API/File/cFile.pc"; 178b39c5158Smillert} 179b39c5158Smillert 180b39c5158Smillertsub fileConstant 181b39c5158Smillert{ 182b39c5158Smillert my( $name )= @_; 183b39c5158Smillert if( 1 != @_ || ! $name || $name =~ /\W/ ) { 184b39c5158Smillert require Carp; 185b39c5158Smillert Carp::croak( 'Usage: ',__PACKAGE__,'::fileConstant("CONST_NAME")' ); 186b39c5158Smillert } 187b39c5158Smillert my $proto= prototype $name; 188b39c5158Smillert if( defined \&$name 189b39c5158Smillert && defined $proto 190b39c5158Smillert && "" eq $proto ) { 191b39c5158Smillert no strict 'refs'; 192b39c5158Smillert return &$name; 193b39c5158Smillert } 194b39c5158Smillert return undef; 195b39c5158Smillert} 196b39c5158Smillert 197b39c5158Smillert# We provide this for backwards compatibility: 198b39c5158Smillertsub constant 199b39c5158Smillert{ 200b39c5158Smillert my( $name )= @_; 201b39c5158Smillert my $value= fileConstant( $name ); 202b39c5158Smillert if( defined $value ) { 203b39c5158Smillert $!= 0; 204b39c5158Smillert return $value; 205b39c5158Smillert } 206b39c5158Smillert $!= 11; # EINVAL 207b39c5158Smillert return 0; 208b39c5158Smillert} 209b39c5158Smillert 210b39c5158Smillert# BEGIN { 211b39c5158Smillert# my $code= 'return _fileLastError(@_)'; 212b39c5158Smillert# local( $!, $^E )= ( 1, 1 ); 213b39c5158Smillert# if( $! ne $^E ) { 214b39c5158Smillert# $code= ' 215b39c5158Smillert# local( $^E )= _fileLastError(@_); 216b39c5158Smillert# my $ret= $^E; 217b39c5158Smillert# return $ret; 218b39c5158Smillert# '; 219b39c5158Smillert# } 220b39c5158Smillert# eval "sub fileLastError { $code }"; 221b39c5158Smillert# die "$@" if $@; 222b39c5158Smillert# } 223b39c5158Smillert 224b39c5158Smillertpackage Win32API::File::_error; 225b39c5158Smillert 226b39c5158Smillertuse overload 227b39c5158Smillert '""' => sub { 228b39c5158Smillert require Win32 unless defined &Win32::FormatMessage; 229b39c5158Smillert $_ = Win32::FormatMessage(Win32API::File::_fileLastError()); 230b39c5158Smillert tr/\r\n//d; 231b39c5158Smillert return $_; 232b39c5158Smillert }, 233b39c5158Smillert '0+' => sub { Win32API::File::_fileLastError() }, 234b39c5158Smillert 'fallback' => 1; 235b39c5158Smillert 236b39c5158Smillertsub new { return bless {}, shift } 237b39c5158Smillertsub set { Win32API::File::_fileLastError($_[1]); return $_[0] } 238b39c5158Smillert 239b39c5158Smillertpackage Win32API::File; 240b39c5158Smillert 241b39c5158Smillertmy $_error = Win32API::File::_error->new(); 242b39c5158Smillert 243b39c5158Smillertsub fileLastError { 244b39c5158Smillert croak 'Usage: ',__PACKAGE__,'::fileLastError( [$setWin32ErrCode] )' if @_ > 1; 245b39c5158Smillert $_error->set($_[0]) if defined $_[0]; 246b39c5158Smillert return $_error; 247b39c5158Smillert} 248b39c5158Smillert 249b39c5158Smillert# Since we ISA DynaLoader which ISA AutoLoader, we ISA AutoLoader so we 250b39c5158Smillert# need this next chunk to prevent Win32API::File->nonesuch() from 251b39c5158Smillert# looking for "nonesuch.al" and producing confusing error messages: 252b39c5158Smillertuse vars qw($AUTOLOAD); 253b39c5158Smillertsub AUTOLOAD { 254b39c5158Smillert require Carp; 255b39c5158Smillert Carp::croak( 256b39c5158Smillert "Can't locate method $AUTOLOAD via package Win32API::File" ); 257b39c5158Smillert} 258b39c5158Smillert 259b39c5158Smillert# Replace "&rout;" with "goto &rout;" when that is supported on Win32. 260b39c5158Smillert 261b39c5158Smillert# Aliases for non-Unicode functions: 262b39c5158Smillertsub CopyFile { &CopyFileA; } 263b39c5158Smillertsub CreateFile { &CreateFileA; } 264b39c5158Smillertsub DefineDosDevice { &DefineDosDeviceA; } 265b39c5158Smillertsub DeleteFile { &DeleteFileA; } 266b39c5158Smillertsub GetDriveType { &GetDriveTypeA; } 267b39c5158Smillertsub GetFileAttributes { &GetFileAttributesA; } 268b39c5158Smillertsub GetLogicalDriveStrings { &GetLogicalDriveStringsA; } 269b39c5158Smillertsub GetVolumeInformation { &GetVolumeInformationA; } 270b39c5158Smillertsub MoveFile { &MoveFileA; } 271b39c5158Smillertsub MoveFileEx { &MoveFileExA; } 272b39c5158Smillertsub QueryDosDevice { &QueryDosDeviceA; } 273b39c5158Smillert 274b39c5158Smillertsub OsFHandleOpen { 275b39c5158Smillert if( 3 != @_ ) { 276b39c5158Smillert croak 'Win32API::File Usage: ', 277b39c5158Smillert 'OsFHandleOpen(FILE,$hNativeHandle,"rwatb")'; 278b39c5158Smillert } 279b39c5158Smillert my( $fh, $osfh, $access )= @_; 280b39c5158Smillert if( ! ref($fh) ) { 281b39c5158Smillert if( $fh !~ /('|::)/ ) { 282b39c5158Smillert $fh= caller() . "::" . $fh; 283b39c5158Smillert } 284b39c5158Smillert no strict "refs"; 285b39c5158Smillert $fh= \*{$fh}; 286b39c5158Smillert } 287b39c5158Smillert my( $mode, $pref ); 288b39c5158Smillert if( $access =~ /r/i ) { 289b39c5158Smillert if( $access =~ /w/i ) { 290b39c5158Smillert $mode= O_RDWR; 291b39c5158Smillert $pref= "+<"; 292b39c5158Smillert } else { 293b39c5158Smillert $mode= O_RDONLY; 294b39c5158Smillert $pref= "<"; 295b39c5158Smillert } 296b39c5158Smillert } else { 297b39c5158Smillert if( $access =~ /w/i ) { 298b39c5158Smillert $mode= O_WRONLY; 299b39c5158Smillert $pref= ">"; 300b39c5158Smillert } else { 301b39c5158Smillert # croak qq<Win32API::File::OsFHandleOpen(): >, 302b39c5158Smillert # qq<Access ($access) missing both "r" and "w">; 303b39c5158Smillert $mode= O_RDONLY; 304b39c5158Smillert $pref= "<"; 305b39c5158Smillert } 306b39c5158Smillert } 307b39c5158Smillert $mode |= O_APPEND if $access =~ /a/i; 308b39c5158Smillert #$mode |= O_TEXT if $access =~ /t/i; 309b39c5158Smillert # Some versions of the Fcntl module are broken and won't autoload O_TEXT: 310b39c5158Smillert if( $access =~ /t/i ) { 311b39c5158Smillert my $o_text= eval "O_TEXT"; 312b39c5158Smillert $o_text= 0x4000 if $@; 313b39c5158Smillert $mode |= $o_text; 314b39c5158Smillert } 315b39c5158Smillert $mode |= O_BINARY if $access =~ /b/i; 316b39c5158Smillert my $fd = eval { OsFHandleOpenFd( $osfh, $mode ) }; 317b39c5158Smillert if ($@) { 318b39c5158Smillert return tie *{$fh}, __PACKAGE__, $osfh; 319b39c5158Smillert } 320b8851fccSafresh1 return undef unless $fd; 321b8851fccSafresh1 return open( $fh, $pref."&=".(0+$fd) ); 322b39c5158Smillert} 323b39c5158Smillert 324b39c5158Smillertsub GetOsFHandle { 325b39c5158Smillert if( 1 != @_ ) { 326b39c5158Smillert croak 'Win32API::File Usage: $OsFHandle= GetOsFHandle(FILE)'; 327b39c5158Smillert } 328b39c5158Smillert my( $file )= @_; 329b39c5158Smillert if( ! ref($file) ) { 330b39c5158Smillert if( $file !~ /('|::)/ ) { 331b39c5158Smillert $file= caller() . "::" . $file; 332b39c5158Smillert } 333b39c5158Smillert no strict "refs"; 334b39c5158Smillert # The eval "" is necessary in Perl 5.6, avoid it otherwise. 335b39c5158Smillert my $tied = !defined($^]) || $^] < 5.008 336b39c5158Smillert ? eval "tied *{$file}" 337b39c5158Smillert : tied *{$file}; 338b39c5158Smillert 339b39c5158Smillert if (UNIVERSAL::isa($tied => __PACKAGE__)) { 340b39c5158Smillert return $tied->win32_handle; 341b39c5158Smillert } 342b39c5158Smillert 343b39c5158Smillert $file= *{$file}; 344b39c5158Smillert } 345b39c5158Smillert my( $fd )= fileno($file); 346b39c5158Smillert if( ! defined( $fd ) ) { 347b39c5158Smillert if( $file =~ /^\d+\Z/ ) { 348b39c5158Smillert $fd= $file; 349b39c5158Smillert } else { 350b39c5158Smillert return (); # $! should be set by fileno(). 351b39c5158Smillert } 352b39c5158Smillert } 353b39c5158Smillert my $h= FdGetOsFHandle( $fd ); 354b39c5158Smillert if( INVALID_HANDLE_VALUE() == $h ) { 355b39c5158Smillert $h= ""; 356b39c5158Smillert } elsif( "0" eq $h ) { 357b39c5158Smillert $h= "0 but true"; 358b39c5158Smillert } 359b39c5158Smillert return $h; 360b39c5158Smillert} 361b39c5158Smillert 362b39c5158Smillertsub getFileSize { 363b39c5158Smillert croak 'Win32API::File Usage: $size= getFileSize($hNativeHandle)' 364b39c5158Smillert if @_ != 1; 365b39c5158Smillert 366b39c5158Smillert my $handle = shift; 367b39c5158Smillert my $high_size = 0; 368b39c5158Smillert 369b39c5158Smillert my $low_size = GetFileSize($handle, $high_size); 370b39c5158Smillert 371b39c5158Smillert my $retval = $_64BITINT ? $high_size : Math::BigInt->new($high_size); 372b39c5158Smillert 373b39c5158Smillert $retval <<= $THIRTY_TWO; 374b39c5158Smillert $retval += $low_size; 375b39c5158Smillert 376b39c5158Smillert return $retval; 377b39c5158Smillert} 378b39c5158Smillert 379b39c5158Smillertsub setFilePointer { 380b39c5158Smillert croak 'Win32API::File Usage: $pos= setFilePointer($hNativeHandle, $posl, $from_where)' 381b39c5158Smillert if @_ != 3; 382b39c5158Smillert 383b39c5158Smillert my ($handle, $pos, $from_where) = @_; 384b39c5158Smillert 385b39c5158Smillert my ($pos_low, $pos_high) = ($pos, 0); 386b39c5158Smillert 387b39c5158Smillert if ($_64BITINT) { 388b39c5158Smillert $pos_low = ($pos & $FFFFFFFF); 389b39c5158Smillert $pos_high = (($pos >> $THIRTY_TWO) & $FFFFFFFF); 390b39c5158Smillert } 391b39c5158Smillert elsif (UNIVERSAL::isa($pos => 'Math::BigInt')) { 392b39c5158Smillert $pos_low = ($pos & $FFFFFFFF)->numify(); 393b39c5158Smillert $pos_high = (($pos >> $THIRTY_TWO) & $FFFFFFFF)->numify(); 394b39c5158Smillert } 395b39c5158Smillert 396b39c5158Smillert my $retval = SetFilePointer($handle, $pos_low, $pos_high, $from_where); 397b39c5158Smillert 398b39c5158Smillert if (defined $pos_high && $pos_high != 0) { 399b39c5158Smillert if (! $_64BITINT) { 400b39c5158Smillert $retval = Math::BigInt->new($retval); 401b39c5158Smillert $pos_high = Math::BigInt->new($pos_high); 402b39c5158Smillert } 403b39c5158Smillert 404b39c5158Smillert $retval += $pos_high << $THIRTY_TWO; 405b39c5158Smillert } 406b39c5158Smillert 407b39c5158Smillert return $retval; 408b39c5158Smillert} 409b39c5158Smillert 410b39c5158Smillertsub attrLetsToBits 411b39c5158Smillert{ 412b39c5158Smillert my( $lets )= @_; 413b39c5158Smillert my( %a )= ( 414b39c5158Smillert "a"=>FILE_ATTRIBUTE_ARCHIVE(), "c"=>FILE_ATTRIBUTE_COMPRESSED(), 415b39c5158Smillert "h"=>FILE_ATTRIBUTE_HIDDEN(), "o"=>FILE_ATTRIBUTE_OFFLINE(), 416b39c5158Smillert "r"=>FILE_ATTRIBUTE_READONLY(), "s"=>FILE_ATTRIBUTE_SYSTEM(), 417b39c5158Smillert "t"=>FILE_ATTRIBUTE_TEMPORARY() ); 418b39c5158Smillert my( $bits )= 0; 419b39c5158Smillert foreach( split(//,$lets) ) { 420b39c5158Smillert croak "Win32API::File::attrLetsToBits: Unknown attribute letter ($_)" 421b39c5158Smillert unless exists $a{$_}; 422b39c5158Smillert $bits |= $a{$_}; 423b39c5158Smillert } 424b39c5158Smillert return $bits; 425b39c5158Smillert} 426b39c5158Smillert 427b39c5158Smillertuse vars qw( @_createFile_Opts %_createFile_Opts ); 428b39c5158Smillert@_createFile_Opts= qw( Access Create Share Attributes 429b39c5158Smillert Flags Security Model ); 430b39c5158Smillert@_createFile_Opts{@_createFile_Opts}= (1) x @_createFile_Opts; 431b39c5158Smillert 432b39c5158Smillertsub createFile 433b39c5158Smillert{ 434b39c5158Smillert my $opts= ""; 435b39c5158Smillert if( 2 <= @_ && "HASH" eq ref($_[$#_]) ) { 436b39c5158Smillert $opts= pop( @_ ); 437b39c5158Smillert } 438b39c5158Smillert my( $sPath, $svAccess, $svShare )= @_; 439b39c5158Smillert if( @_ < 1 || 3 < @_ ) { 440b39c5158Smillert croak "Win32API::File::createFile() usage: \$hObject= createFile(\n", 441b39c5158Smillert " \$sPath, [\$svAccess_qrw_ktn_ce,[\$svShare_rwd,]]", 442b39c5158Smillert " [{Option=>\$Value}] )\n", 443b39c5158Smillert " options: @_createFile_Opts\nCalled"; 444b39c5158Smillert } 445b39c5158Smillert my( $create, $flags, $sec, $model )= ( "", 0, [], 0 ); 446b39c5158Smillert if( ref($opts) ) { 447b39c5158Smillert my @err= grep( ! $_createFile_Opts{$_}, keys(%$opts) ); 448b39c5158Smillert @err and croak "_createFile: Invalid options (@err)"; 449b39c5158Smillert $flags= $opts->{Flags} if exists( $opts->{Flags} ); 450b39c5158Smillert $flags |= attrLetsToBits( $opts->{Attributes} ) 451b39c5158Smillert if exists( $opts->{Attributes} ); 452b39c5158Smillert $sec= $opts->{Security} if exists( $opts->{Security} ); 453b39c5158Smillert $model= $opts->{Model} if exists( $opts->{Model} ); 454b39c5158Smillert $svAccess= $opts->{Access} if exists( $opts->{Access} ); 455b39c5158Smillert $create= $opts->{Create} if exists( $opts->{Create} ); 456b39c5158Smillert $svShare= $opts->{Share} if exists( $opts->{Share} ); 457b39c5158Smillert } 458b39c5158Smillert $svAccess= "r" unless defined($svAccess); 459b39c5158Smillert $svShare= "rw" unless defined($svShare); 460b39c5158Smillert if( $svAccess =~ /^[qrw ktn ce]*$/i ) { 461b39c5158Smillert ( my $c= $svAccess ) =~ tr/qrw QRW//d; 462b39c5158Smillert $create= $c if "" ne $c && "" eq $create; 463b39c5158Smillert local( $_ )= $svAccess; 464b39c5158Smillert $svAccess= 0; 465b39c5158Smillert $svAccess |= GENERIC_READ() if /r/i; 466b39c5158Smillert $svAccess |= GENERIC_WRITE() if /w/i; 467b39c5158Smillert } elsif( "?" eq $svAccess ) { 468b39c5158Smillert croak 469b39c5158Smillert "Win32API::File::createFile: \$svAccess can use the following:\n", 470b39c5158Smillert " One or more of the following:\n", 471b39c5158Smillert "\tq -- Query access (same as 0)\n", 472b39c5158Smillert "\tr -- Read access (GENERIC_READ)\n", 473b39c5158Smillert "\tw -- Write access (GENERIC_WRITE)\n", 474b39c5158Smillert " At most one of the following:\n", 475b39c5158Smillert "\tk -- Keep if exists\n", 476b39c5158Smillert "\tt -- Truncate if exists\n", 477b39c5158Smillert "\tn -- New file only (fail if file already exists)\n", 478b39c5158Smillert " At most one of the following:\n", 479b39c5158Smillert "\tc -- Create if doesn't exist\n", 480b39c5158Smillert "\te -- Existing file only (fail if doesn't exist)\n", 481b39c5158Smillert " '' is the same as 'q k e'\n", 482b39c5158Smillert " 'r' is the same as 'r k e'\n", 483b39c5158Smillert " 'w' is the same as 'w t c'\n", 484b39c5158Smillert " 'rw' is the same as 'rw k c'\n", 485b39c5158Smillert " 'rt' or 'rn' implies 'c'.\n", 486b39c5158Smillert " Or \$svAccess can be numeric.\n", "Called from"; 487b39c5158Smillert } elsif( $svAccess == 0 && $svAccess !~ /^[-+.]*0/ ) { 488b39c5158Smillert croak "Win32API::File::createFile: Invalid \$svAccess ($svAccess)"; 489b39c5158Smillert } 490b39c5158Smillert if( $create =~ /^[ktn ce]*$/ ) { 491b39c5158Smillert local( $_ )= $create; 492b39c5158Smillert my( $k, $t, $n, $c, $e )= ( scalar(/k/i), scalar(/t/i), 493b39c5158Smillert scalar(/n/i), scalar(/c/i), scalar(/e/i) ); 494b39c5158Smillert if( 1 < $k + $t + $n ) { 495b39c5158Smillert croak "Win32API::File::createFile: \$create must not use ", 496b39c5158Smillert qq<more than one of "k", "t", and "n" ($create)>; 497b39c5158Smillert } 498b39c5158Smillert if( $c && $e ) { 499b39c5158Smillert croak "Win32API::File::createFile: \$create must not use ", 500b39c5158Smillert qq<both "c" and "e" ($create)>; 501b39c5158Smillert } 502b39c5158Smillert my $r= ( $svAccess & GENERIC_READ() ) == GENERIC_READ(); 503b39c5158Smillert my $w= ( $svAccess & GENERIC_WRITE() ) == GENERIC_WRITE(); 504b39c5158Smillert if( ! $k && ! $t && ! $n ) { 505b39c5158Smillert if( $w && ! $r ) { $t= 1; 506b39c5158Smillert } else { $k= 1; } 507b39c5158Smillert } 508b39c5158Smillert if( $k ) { 509b39c5158Smillert if( $c || $w && ! $e ) { $create= OPEN_ALWAYS(); 510b39c5158Smillert } else { $create= OPEN_EXISTING(); } 511b39c5158Smillert } elsif( $t ) { 512b39c5158Smillert if( $e ) { $create= TRUNCATE_EXISTING(); 513b39c5158Smillert } else { $create= CREATE_ALWAYS(); } 514b39c5158Smillert } else { # $n 515b39c5158Smillert if( ! $e ) { $create= CREATE_NEW(); 516b39c5158Smillert } else { 517b39c5158Smillert croak "Win32API::File::createFile: \$create must not use ", 518b39c5158Smillert qq<both "n" and "e" ($create)>; 519b39c5158Smillert } 520b39c5158Smillert } 521b39c5158Smillert } elsif( "?" eq $create ) { 522b39c5158Smillert croak 'Win32API::File::createFile: $create !~ /^[ktn ce]*$/;', 523b39c5158Smillert ' pass $svAccess as "?" for more information.'; 524b39c5158Smillert } elsif( $create == 0 && $create ne "0" ) { 525b39c5158Smillert croak "Win32API::File::createFile: Invalid \$create ($create)"; 526b39c5158Smillert } 527b39c5158Smillert if( $svShare =~ /^[drw]*$/ ) { 528b39c5158Smillert my %s= ( "d"=>FILE_SHARE_DELETE(), "r"=>FILE_SHARE_READ(), 529b39c5158Smillert "w"=>FILE_SHARE_WRITE() ); 530b39c5158Smillert my @s= split(//,$svShare); 531b39c5158Smillert $svShare= 0; 532b39c5158Smillert foreach( @s ) { 533b39c5158Smillert $svShare |= $s{$_}; 534b39c5158Smillert } 535b39c5158Smillert } elsif( $svShare == 0 && $svShare !~ /^[-+.]*0/ ) { 536b39c5158Smillert croak "Win32API::File::createFile: Invalid \$svShare ($svShare)"; 537b39c5158Smillert } 538b39c5158Smillert return CreateFileA( 539b39c5158Smillert $sPath, $svAccess, $svShare, $sec, $create, $flags, $model ); 540b39c5158Smillert} 541b39c5158Smillert 542b39c5158Smillert 543b39c5158Smillertsub getLogicalDrives 544b39c5158Smillert{ 545b39c5158Smillert my( $ref )= @_; 546b39c5158Smillert my $s= ""; 547b39c5158Smillert if( ! GetLogicalDriveStringsA( 256, $s ) ) { 548b39c5158Smillert return undef; 549b39c5158Smillert } 550b39c5158Smillert if( ! defined($ref) ) { 551b39c5158Smillert return split( /\0/, $s ); 552b39c5158Smillert } elsif( "ARRAY" ne ref($ref) ) { 553b39c5158Smillert croak 'Usage: C<@arr= getLogicalDrives()> ', 554b39c5158Smillert 'or C<getLogicalDrives(\\@arr)>', "\n"; 555b39c5158Smillert } 556b39c5158Smillert @$ref= split( /\0/, $s ); 557b39c5158Smillert return $ref; 558b39c5158Smillert} 559b39c5158Smillert 560b39c5158Smillert############################################################################### 561b39c5158Smillert# Experimental Tied Handle and Object Oriented interface. # 562b39c5158Smillert############################################################################### 563b39c5158Smillert 564b39c5158Smillertsub new { 565b39c5158Smillert my $class = shift; 566b39c5158Smillert $class = ref $class || $class; 567b39c5158Smillert 568b39c5158Smillert my $self = IO::File::new($class); 569b39c5158Smillert tie *$self, __PACKAGE__; 570b39c5158Smillert 571b39c5158Smillert $self->open(@_) if @_; 572b39c5158Smillert 573b39c5158Smillert return $self; 574b39c5158Smillert} 575b39c5158Smillert 576b39c5158Smillertsub TIEHANDLE { 577b39c5158Smillert my ($class, $win32_handle) = @_; 578b39c5158Smillert $class = ref $class || $class; 579b39c5158Smillert 580b39c5158Smillert return bless { 581b39c5158Smillert _win32_handle => $win32_handle, 582b39c5158Smillert _binmode => 0, 583b39c5158Smillert _buffered => 0, 584b39c5158Smillert _buffer => '', 585b39c5158Smillert _eof => 0, 586b39c5158Smillert _fileno => undef, 587b39c5158Smillert _access => 'r', 588b39c5158Smillert _append => 0, 589b39c5158Smillert }, $class; 590b39c5158Smillert} 591b39c5158Smillert 592b39c5158Smillert# This is called for getting the tied object from hard refs to glob refs in 593b39c5158Smillert# some cases, for reasons I don't quite grok. 594b39c5158Smillert 595b39c5158Smillertsub FETCH { return $_[0] } 596b39c5158Smillert 597b39c5158Smillert# Public accessors 598b39c5158Smillert 599b39c5158Smillertsub win32_handle{ $_[0]->{_win32_handle}||= $_[1] } 600b39c5158Smillert 601b39c5158Smillert# Protected accessors 602b39c5158Smillert 603b39c5158Smillertsub _buffer { $_[0]->{_buffer} ||= $_[1] } 604b39c5158Smillertsub _binmode { $_[0]->{_binmode} ||= $_[1] } 605b39c5158Smillertsub _fileno { $_[0]->{_fileno} ||= $_[1] } 606b39c5158Smillertsub _access { $_[0]->{_access} ||= $_[1] } 607b39c5158Smillertsub _append { $_[0]->{_append} ||= $_[1] } 608b39c5158Smillert 609b39c5158Smillert# Tie interface 610b39c5158Smillert 611b39c5158Smillertsub OPEN { 612b39c5158Smillert my $self = shift; 613b39c5158Smillert my $expr = shift; 614b39c5158Smillert croak "Only the two argument form of open is supported at this time" if @_; 615b39c5158Smillert# FIXME: this needs to parse the full Perl open syntax in $expr 616b39c5158Smillert 617b39c5158Smillert my ($mixed, $mode, $path) = 618b39c5158Smillert ($expr =~ /^\s* (\+)? \s* (<|>|>>)? \s* (.*?) \s*$/x); 619b39c5158Smillert 620b39c5158Smillert croak "Unsupported open mode" if not $path; 621b39c5158Smillert 622b39c5158Smillert my $access = 'r'; 623b39c5158Smillert my $append = $mode eq '>>' ? 1 : 0; 624b39c5158Smillert 625b39c5158Smillert if ($mixed) { 626b39c5158Smillert $access = 'rw'; 627b39c5158Smillert } elsif($mode eq '>') { 628b39c5158Smillert $access = 'w'; 629b39c5158Smillert } 630b39c5158Smillert 631b39c5158Smillert my $w32_handle = createFile($path, $access); 632b39c5158Smillert 633b39c5158Smillert $self->win32_handle($w32_handle); 634b39c5158Smillert 635b39c5158Smillert $self->seek(1,2) if $append; 636b39c5158Smillert 637b39c5158Smillert $self->_access($access); 638b39c5158Smillert $self->_append($append); 639b39c5158Smillert 640b39c5158Smillert return 1; 641b39c5158Smillert} 642b39c5158Smillert 643b39c5158Smillertsub BINMODE { 644b39c5158Smillert $_[0]->_binmode(1); 645b39c5158Smillert} 646b39c5158Smillert 647b39c5158Smillertsub WRITE { 648b39c5158Smillert my ($self, $buf, $len, $offset, $overlap) = @_; 649b39c5158Smillert 650b39c5158Smillert if ($offset) { 651b39c5158Smillert $buf = substr($buf, $offset); 652b39c5158Smillert $len = length($buf); 653b39c5158Smillert } 654b39c5158Smillert 655b39c5158Smillert $len = length($buf) if not defined $len; 656b39c5158Smillert 657b39c5158Smillert $overlap = [] if not defined $overlap;; 658b39c5158Smillert 659b39c5158Smillert my $bytes_written = 0; 660b39c5158Smillert 661b39c5158Smillert WriteFile ( 662b39c5158Smillert $self->win32_handle, $buf, $len, 663b39c5158Smillert $bytes_written, $overlap 664b39c5158Smillert ); 665b39c5158Smillert 666b39c5158Smillert return $bytes_written; 667b39c5158Smillert} 668b39c5158Smillert 669b39c5158Smillertsub PRINT { 670b39c5158Smillert my $self = shift; 671b39c5158Smillert 672b39c5158Smillert my $buf = join defined $, ? $, : "" => @_; 673b39c5158Smillert 674b39c5158Smillert $buf =~ s/\012/\015\012/sg unless $self->_binmode(); 675b39c5158Smillert 676b39c5158Smillert $buf .= $\ if defined $\; 677b39c5158Smillert 678b39c5158Smillert $self->WRITE($buf, length($buf), 0); 679b39c5158Smillert} 680b39c5158Smillert 681b39c5158Smillertsub READ { 682b39c5158Smillert my $self = shift; 683b39c5158Smillert my $into = \$_[0]; shift; 684b39c5158Smillert my ($len, $offset, $overlap) = @_; 685b39c5158Smillert 686b39c5158Smillert my $buffer = defined $self->_buffer ? $self->_buffer : ""; 687b39c5158Smillert my $buf_length = length($buffer); 688b39c5158Smillert my $bytes_read = 0; 689b39c5158Smillert my $data; 690b39c5158Smillert $offset = 0 if not defined $offset; 691b39c5158Smillert 692b39c5158Smillert if ($buf_length >= $len) { 693b39c5158Smillert $data = substr($buffer, 0, $len => ""); 694b39c5158Smillert $bytes_read = $len; 695b39c5158Smillert $self->_buffer($buffer); 696b39c5158Smillert } else { 697b39c5158Smillert if ($buf_length > 0) { 698b39c5158Smillert $len -= $buf_length; 699b39c5158Smillert substr($$into, $offset) = $buffer; 700b39c5158Smillert $offset += $buf_length; 701b39c5158Smillert } 702b39c5158Smillert 703b39c5158Smillert $overlap ||= []; 704b39c5158Smillert 705b39c5158Smillert ReadFile ( 706b39c5158Smillert $self->win32_handle, $data, $len, 707b39c5158Smillert $bytes_read, $overlap 708b39c5158Smillert ); 709b39c5158Smillert } 710b39c5158Smillert 711b39c5158Smillert $$into = "" if not defined $$into; 712b39c5158Smillert 713b39c5158Smillert substr($$into, $offset) = $data; 714b39c5158Smillert 715b39c5158Smillert return $bytes_read; 716b39c5158Smillert} 717b39c5158Smillert 718b39c5158Smillertsub READLINE { 719b39c5158Smillert my $self = shift; 720b39c5158Smillert my $line = ""; 721b39c5158Smillert 722898184e3Ssthen while ((index $line, $/) == -1) { # read until end of line marker 723b39c5158Smillert my $char = $self->GETC(); 724b39c5158Smillert 725b39c5158Smillert last if !defined $char || $char eq ''; 726b39c5158Smillert 727b39c5158Smillert $line .= $char; 728b39c5158Smillert } 729b39c5158Smillert 730b39c5158Smillert return undef if $line eq ''; 731b39c5158Smillert 732b39c5158Smillert return $line; 733b39c5158Smillert} 734b39c5158Smillert 735b39c5158Smillert 736b39c5158Smillertsub FILENO { 737b39c5158Smillert my $self = shift; 738b39c5158Smillert 739b39c5158Smillert return $self->_fileno() if defined $self->_fileno(); 740b39c5158Smillert 741b39c5158Smillert return -1 if $^O eq 'cygwin'; 742b39c5158Smillert 743b39c5158Smillert# FIXME: We don't always open the handle, better to query the handle or to set 744b39c5158Smillert# the right access info at TIEHANDLE time. 745b39c5158Smillert 746b39c5158Smillert my $access = $self->_access(); 747b39c5158Smillert my $mode = $access eq 'rw' ? O_RDWR : 748b39c5158Smillert $access eq 'w' ? O_WRONLY : O_RDONLY; 749b39c5158Smillert 750b39c5158Smillert $mode |= O_APPEND if $self->_append(); 751b39c5158Smillert 752b39c5158Smillert $mode |= O_TEXT if not $self->_binmode(); 753b39c5158Smillert 754b39c5158Smillert return $self->_fileno ( OsfHandleOpenFd ( 755b39c5158Smillert $self->win32_handle, $mode 756b39c5158Smillert )); 757b39c5158Smillert} 758b39c5158Smillert 759b39c5158Smillertsub SEEK { 760b39c5158Smillert my ($self, $pos, $whence) = @_; 761b39c5158Smillert 762b39c5158Smillert $whence = 0 if not defined $whence; 763b39c5158Smillert my @file_consts = map { 764b39c5158Smillert fileConstant($_) 765b39c5158Smillert } qw(FILE_BEGIN FILE_CURRENT FILE_END); 766b39c5158Smillert 767b39c5158Smillert my $from_where = $file_consts[$whence]; 768b39c5158Smillert 769b39c5158Smillert return setFilePointer($self->win32_handle, $pos, $from_where); 770b39c5158Smillert} 771b39c5158Smillert 772b39c5158Smillertsub TELL { 773b39c5158Smillert# SetFilePointer with position 0 at FILE_CURRENT will return position. 774b39c5158Smillert return $_[0]->SEEK(0, 1); 775b39c5158Smillert} 776b39c5158Smillert 777b39c5158Smillertsub EOF { 778b39c5158Smillert my $self = shift; 779b39c5158Smillert 780b39c5158Smillert my $current = $self->TELL() + 0; 781b39c5158Smillert my $end = getFileSize($self->win32_handle) + 0; 782b39c5158Smillert 783b39c5158Smillert return $current == $end; 784b39c5158Smillert} 785b39c5158Smillert 786b39c5158Smillertsub CLOSE { 787b39c5158Smillert my $self = shift; 788b39c5158Smillert 789b39c5158Smillert my $retval = 1; 790b39c5158Smillert 791b39c5158Smillert if (defined $self->win32_handle) { 792b39c5158Smillert $retval = CloseHandle($self->win32_handle); 793b39c5158Smillert 794b39c5158Smillert $self->win32_handle(undef); 795b39c5158Smillert } 796b39c5158Smillert 797b39c5158Smillert return $retval; 798b39c5158Smillert} 799b39c5158Smillert 800b39c5158Smillert# Only close the handle on explicit close, too many problems otherwise. 801b39c5158Smillertsub UNTIE {} 802b39c5158Smillert 803b39c5158Smillertsub DESTROY {} 804b39c5158Smillert 805b39c5158Smillert# End of Tie/OO Interface 806b39c5158Smillert 807b39c5158Smillert# Autoload methods go after =cut, and are processed by the autosplit program. 808b39c5158Smillert 809b39c5158Smillert1; 810b39c5158Smillert__END__ 811b39c5158Smillert 812b39c5158Smillert=head1 NAME 813b39c5158Smillert 814b39c5158SmillertWin32API::File - Low-level access to Win32 system API calls for files/dirs. 815b39c5158Smillert 816b39c5158Smillert=head1 SYNOPSIS 817b39c5158Smillert 818b39c5158Smillert use Win32API::File 0.08 qw( :ALL ); 819b39c5158Smillert 820b39c5158Smillert MoveFile( $Source, $Destination ) 821b39c5158Smillert or die "Can't move $Source to $Destination: ",fileLastError(),"\n"; 822b39c5158Smillert MoveFileEx( $Source, $Destination, MOVEFILE_REPLACE_EXISTING() ) 823b39c5158Smillert or die "Can't move $Source to $Destination: ",fileLastError(),"\n"; 824b39c5158Smillert [...] 825b39c5158Smillert 826b39c5158Smillert=head1 DESCRIPTION 827b39c5158Smillert 828b39c5158SmillertThis provides fairly low-level access to the Win32 System API 829b39c5158Smillertcalls dealing with files and directories. 830b39c5158Smillert 831b39c5158SmillertTo pass in C<NULL> as the pointer to an optional buffer, pass in 832b39c5158Smillertan empty list reference, C<[]>. 833b39c5158Smillert 834b39c5158SmillertBeyond raw access to the API calls and related constants, this module 835b39c5158Smillerthandles smart buffer allocation and translation of return codes. 836b39c5158Smillert 837b39c5158SmillertAll functions, unless otherwise noted, return a true value for success 838b39c5158Smillertand a false value for failure and set C<$^E> on failure. 839b39c5158Smillert 840b39c5158Smillert=head2 Object Oriented/Tied Handle Interface 841b39c5158Smillert 842b39c5158SmillertWARNING: this is new code, use at your own risk. 843b39c5158Smillert 844b39c5158SmillertThis version of C<Win32API::File> can be used like an C<IO::File> object: 845b39c5158Smillert 846b39c5158Smillert my $file = Win32API::File->new("+> foo"); 847b39c5158Smillert binmode $file; 848b39c5158Smillert print $file "hello there\n"; 849b39c5158Smillert seek $file, 0, 0; 850b39c5158Smillert my $line = <$file>; 851b39c5158Smillert $file->close; 852b39c5158Smillert 853b39c5158SmillertIt also supports tying via a win32 handle (for example, from C<createFile()>): 854b39c5158Smillert 855b39c5158Smillert tie FILE, 'Win32API::File', $win32_handle; 856b39c5158Smillert print FILE "..."; 857b39c5158Smillert 858b39c5158SmillertIt has not been extensively tested yet and buffered I/O is not yet implemented. 859b39c5158Smillert 860b39c5158Smillert=head2 Exports 861b39c5158Smillert 862b39c5158SmillertNothing is exported by default. The following tags can be used to 863b39c5158Smillerthave large sets of symbols exported: C<":Func">, C<":FuncA">, 864b39c5158SmillertC<":FuncW">, C<":Misc">, C<":DDD_">, C<":DRIVE_">, C<":FILE_">, 865b39c5158SmillertC<":FILE_ATTRIBUTE_">, C<":FILE_FLAG_">, C<":FILE_SHARE_">, 866b39c5158SmillertC<":FILE_TYPE_">, C<":FS_">, C<":FSCTL_">, C<":HANDLE_FLAG_">, 867b39c5158SmillertC<":IOCTL_STORAGE_">, C<":IOCTL_DISK_">, C<":GENERIC_">, 868b39c5158SmillertC<":MEDIA_TYPE">, C<":MOVEFILE_">, C<":SECURITY_">, C<":SEM_">, 869b39c5158Smillertand C<":PARTITION_">. 870b39c5158Smillert 871b39c5158Smillert=over 872b39c5158Smillert 873b39c5158Smillert=item C<":Func"> 874b39c5158Smillert 875b39c5158SmillertThe basic function names: C<attrLetsToBits>, C<createFile>, 876b39c5158SmillertC<fileConstant>, C<fileLastError>, C<getLogicalDrives>, 877b39c5158SmillertC<setFilePointer>, C<getFileSize>, 878b39c5158SmillertC<CloseHandle>, C<CopyFile>, C<CreateFile>, 879b39c5158SmillertC<DefineDosDevice>, C<DeleteFile>, C<DeviceIoControl>, 880b39c5158SmillertC<FdGetOsFHandle>, C<GetDriveType>, C<GetFileAttributes>, 881b39c5158SmillertC<GetFileSize>, C<GetFileType>, C<GetHandleInformation>, 882b39c5158SmillertC<GetLogicalDrives>, C<GetLogicalDriveStrings>, C<GetOsFHandle>, 883b39c5158SmillertC<GetOverlappedResult>, C<GetVolumeInformation>, C<IsContainerPartition>, 884b39c5158SmillertC<IsRecognizedPartition>, C<MoveFile>, C<MoveFileEx>, 885b39c5158SmillertC<OsFHandleOpen>, C<OsFHandleOpenFd>, C<QueryDosDevice>, 886b39c5158SmillertC<ReadFile>, C<SetErrorMode>, C<SetFilePointer>, 887b39c5158SmillertC<SetHandleInformation>, and C<WriteFile>. 888b39c5158Smillert 889b39c5158Smillert=over 890b39c5158Smillert 891b39c5158Smillert=item attrLetsToBits 892b39c5158Smillert 893b39c5158Smillert=item C<$uBits= attrLetsToBits( $sAttributeLetters )> 894b39c5158Smillert 895b39c5158SmillertConverts a string of file attribute letters into an unsigned value with 896b39c5158Smillertthe corresponding bits set. C<$sAttributeLetters> should contain zero 897b39c5158Smillertor more letters from C<"achorst">: 898b39c5158Smillert 899b39c5158Smillert=over 900b39c5158Smillert 901b39c5158Smillert=item C<"a"> 902b39c5158Smillert 903b39c5158SmillertC<FILE_ATTRIBUTE_ARCHIVE> 904b39c5158Smillert 905b39c5158Smillert=item C<"c"> 906b39c5158Smillert 907b39c5158SmillertC<FILE_ATTRIBUTE_COMPRESSED> 908b39c5158Smillert 909b39c5158Smillert=item C<"h"> 910b39c5158Smillert 911b39c5158SmillertC<FILE_ATTRIBUTE_HIDDEN> 912b39c5158Smillert 913b39c5158Smillert=item C<"o"> 914b39c5158Smillert 915b39c5158SmillertC<FILE_ATTRIBUTE_OFFLINE> 916b39c5158Smillert 917b39c5158Smillert=item C<"r"> 918b39c5158Smillert 919b39c5158SmillertC<FILE_ATTRIBUTE_READONLY> 920b39c5158Smillert 921b39c5158Smillert=item C<"s"> 922b39c5158Smillert 923b39c5158SmillertC<FILE_ATTRIBUTE_SYSTEM> 924b39c5158Smillert 925b39c5158Smillert=item C<"t"> 926b39c5158Smillert 927b39c5158SmillertC<FILE_ATTRIBUTE_TEMPORARY> 928b39c5158Smillert 929b39c5158Smillert=back 930b39c5158Smillert 931b39c5158Smillert=item createFile 932b39c5158Smillert 933b39c5158Smillert=item C<$hObject= createFile( $sPath )> 934b39c5158Smillert 935b39c5158Smillert=item C<$hObject= createFile( $sPath, $rvhvOptions )> 936b39c5158Smillert 937b39c5158Smillert=item C<$hObject= createFile( $sPath, $svAccess )> 938b39c5158Smillert 939b39c5158Smillert=item C<$hObject= createFile( $sPath, $svAccess, $rvhvOptions )> 940b39c5158Smillert 941b39c5158Smillert=item C<$hObject= createFile( $sPath, $svAccess, $svShare )> 942b39c5158Smillert 943b39c5158Smillert=item C<$hObject= createFile( $sPath, $svAccess, $svShare, $rvhvOptions )> 944b39c5158Smillert 945b39c5158SmillertThis is a Perl-friendly wrapper around C<CreateFile>. 946b39c5158Smillert 947b39c5158SmillertOn failure, C<$hObject> gets set to a false value and C<regLastError()> 948b39c5158Smillertand C<$^E> are set to the reason for the failure. Otherwise, 949b8851fccSafresh1C<$hObject> gets set to a Win32 native file handle which is always 950b39c5158Smillerta true value [returns C<"0 but true"> in the impossible(?) case of 951b39c5158Smillertthe handle having a value of C<0>]. 952b39c5158Smillert 953b39c5158SmillertC<$sPath> is the path to the file [or device, etc.] to be opened. See 954b39c5158SmillertC<CreateFile> for more information on possible special values for 955b39c5158SmillertC<$sPath>. 956b39c5158Smillert 957b39c5158SmillertC<$svAccess> can be a number containing the bit mask representing 958b39c5158Smillertthe specific type(s) of access to the file that you desire. See the 959b39c5158SmillertC<$uAccess> parameter to C<CreateFile> for more information on these 960b39c5158Smillertvalues. 961b39c5158Smillert 962b39c5158SmillertMore likely, C<$svAccess> is a string describing the generic type of 963b39c5158Smillertaccess you desire and possibly the file creation options to use. In 964b39c5158Smillertthis case, C<$svAccess> should contain zero or more characters from 965b39c5158SmillertC<"qrw"> [access desired], zero or one character each from C<"ktn"> 966b39c5158Smillertand C<"ce">, and optional white space. These letters stand for, 967b39c5158Smillertrespectively, "Query access", "Read access", "Write access", "Keep if 968b39c5158Smillertexists", "Truncate if exists", "New file only", "Create if none", and 969b39c5158Smillert"Existing file only". Case is ignored. 970b39c5158Smillert 971b39c5158SmillertYou can pass in C<"?"> for C<$svAccess> to have an error message 972b39c5158Smillertdisplayed summarizing its possible values. This is very handy when 973b39c5158Smillertdoing on-the-fly programming using the Perl debugger: 974b39c5158Smillert 975b39c5158Smillert Win32API::File::createFile: $svAccess can use the following: 976b39c5158Smillert One or more of the following: 977b39c5158Smillert q -- Query access (same as 0) 978b39c5158Smillert r -- Read access (GENERIC_READ) 979b39c5158Smillert w -- Write access (GENERIC_WRITE) 980b39c5158Smillert At most one of the following: 981b39c5158Smillert k -- Keep if exists 982b39c5158Smillert t -- Truncate if exists 983b39c5158Smillert n -- New file only (fail if file already exists) 984b39c5158Smillert At most one of the following: 985b39c5158Smillert c -- Create if doesn't exist 986b39c5158Smillert e -- Existing file only (fail if doesn't exist) 987b39c5158Smillert '' is the same as 'q k e' 988b39c5158Smillert 'r' is the same as 'r k e' 989b39c5158Smillert 'w' is the same as 'w t c' 990b39c5158Smillert 'rw' is the same as 'rw k c' 991b39c5158Smillert 'rt' or 'rn' implies 'c'. 992b39c5158Smillert Or $access can be numeric. 993b39c5158Smillert 994b39c5158SmillertC<$svAccess> is designed to be "do what I mean", so you can skip 995b39c5158Smillertthe rest of its explanation unless you are interested in the complex 996b39c5158Smillertdetails. Note that, if you want write access to a device, you need 997b39c5158Smillertto specify C<"k"> [and perhaps C<"e">, as in C<"w ke"> or C<"rw ke">] 998b39c5158Smillertsince Win32 suggests C<OPEN_EXISTING> be used when opening a device. 999b39c5158Smillert 1000b39c5158Smillert=over 1001b39c5158Smillert 1002b39c5158Smillert=item C<"q"> 1003b39c5158Smillert 1004b39c5158SmillertStands for "Query access". This is really a no-op since you always have 1005b39c5158Smillertquery access when you open a file. You can specify C<"q"> to document 1006b39c5158Smillertthat you plan to query the file [or device, etc.]. This is especially 1007b39c5158Smillerthelpful when you don't want read nor write access since something like 1008b39c5158SmillertC<"q"> or C<"q ke"> may be easier to understand than just C<""> or C<"ke">. 1009b39c5158Smillert 1010b39c5158Smillert=item C<"r"> 1011b39c5158Smillert 1012b39c5158SmillertStands for "Read access". Sets the C<GENERIC_READ> bit(s) in the 1013b39c5158SmillertC<$uAccess> that is passed to C<CreateFile>. This is the default 1014b39c5158Smillertaccess if the C<$svAccess> parameter is missing [or if it is C<undef> 1015b39c5158Smillertand C<$rvhvOptions> doesn't specify an C<"Access"> option]. 1016b39c5158Smillert 1017b39c5158Smillert=item C<"w"> 1018b39c5158Smillert 1019b39c5158SmillertStands for "Write access". Sets the C<GENERIC_WRITE> bit(s) in the 1020b39c5158SmillertC<$uAccess> that is passed to C<CreateFile>. 1021b39c5158Smillert 1022b39c5158Smillert=item C<"k"> 1023b39c5158Smillert 1024b39c5158SmillertStands for "Keep if exists". If the requested file exists, then it is 1025b39c5158Smillertopened. This is the default unless C<GENERIC_WRITE> access has been 1026b39c5158Smillertrequested but C<GENERIC_READ> access has not been requested. Contrast 1027b39c5158Smillertwith C<"t"> and C<"n">. 1028b39c5158Smillert 1029b39c5158Smillert=item C<"t"> 1030b39c5158Smillert 1031b39c5158SmillertStands for "Truncate if exists". If the requested file exists, then 1032b39c5158Smillertit is truncated to zero length and then opened. This is the default if 1033b39c5158SmillertC<GENERIC_WRITE> access has been requested and C<GENERIC_READ> access 1034b39c5158Smillerthas not been requested. Contrast with C<"k"> and C<"n">. 1035b39c5158Smillert 1036b39c5158Smillert=item C<"n"> 1037b39c5158Smillert 1038b39c5158SmillertStands for "New file only". If the requested file exists, then it is 1039b39c5158Smillertnot opened and the C<createFile> call fails. Contrast with C<"k"> and 1040b39c5158SmillertC<"t">. Can't be used with C<"e">. 1041b39c5158Smillert 1042b39c5158Smillert=item C<"c"> 1043b39c5158Smillert 1044b39c5158SmillertStands for "Create if none". If the requested file does not 1045b39c5158Smillertexist, then it is created and then opened. This is the default 1046b39c5158Smillertif C<GENERIC_WRITE> access has been requested or if C<"t"> or 1047b39c5158SmillertC<"n"> was specified. Contrast with C<"e">. 1048b39c5158Smillert 1049b39c5158Smillert=item C<"e"> 1050b39c5158Smillert 1051b39c5158SmillertStands for "Existing file only". If the requested file does not 1052b39c5158Smillertexist, then nothing is opened and the C<createFile> call fails. This 1053b39c5158Smillertis the default unless C<GENERIC_WRITE> access has been requested or 1054b39c5158SmillertC<"t"> or C<"n"> was specified. Contrast with C<"c">. Can't be 1055b39c5158Smillertused with C<"n">. 1056b39c5158Smillert 1057b39c5158Smillert=back 1058b39c5158Smillert 1059b39c5158SmillertThe characters from C<"ktn"> and C<"ce"> are combined to determine the 1060b39c5158Smillertwhat value for C<$uCreate> to pass to C<CreateFile> [unless overridden 1061b39c5158Smillertby C<$rvhvOptions>]: 1062b39c5158Smillert 1063b39c5158Smillert=over 1064b39c5158Smillert 1065b39c5158Smillert=item C<"kc"> 1066b39c5158Smillert 1067b39c5158SmillertC<OPEN_ALWAYS> 1068b39c5158Smillert 1069b39c5158Smillert=item C<"ke"> 1070b39c5158Smillert 1071b39c5158SmillertC<OPEN_EXISTING> 1072b39c5158Smillert 1073b39c5158Smillert=item C<"tc"> 1074b39c5158Smillert 1075b39c5158SmillertC<TRUNCATE_EXISTING> 1076b39c5158Smillert 1077b39c5158Smillert=item C<"te"> 1078b39c5158Smillert 1079b39c5158SmillertC<CREATE_ALWAYS> 1080b39c5158Smillert 1081b39c5158Smillert=item C<"nc"> 1082b39c5158Smillert 1083b39c5158SmillertC<CREATE_NEW> 1084b39c5158Smillert 1085b39c5158Smillert=item C<"ne"> 1086b39c5158Smillert 1087b39c5158SmillertIllegal. 1088b39c5158Smillert 1089b39c5158Smillert=back 1090b39c5158Smillert 1091b39c5158SmillertC<$svShare> controls how the file is shared, that is, whether other 1092b39c5158Smillertprocesses can have read, write, and/or delete access to the file while 1093b39c5158Smillertwe have it opened. C<$svShare> will usually be a string containing zero 1094b39c5158Smillertor more characters from C<"rwd"> but can also be a numeric bit mask. 1095b39c5158Smillert 1096b39c5158SmillertC<"r"> sets the C<FILE_SHARE_READ> bit which allows other processes to have 1097b39c5158Smillertread access to the file. C<"w"> sets the C<FILE_SHARE_WRITE> bit which 1098b39c5158Smillertallows other processes to have write access to the file. C<"d"> sets the 1099b39c5158SmillertC<FILE_SHARE_DELETE> bit which allows other processes to have delete access 1100b39c5158Smillertto the file [ignored under Windows 95]. 1101b39c5158Smillert 1102b39c5158SmillertThe default for C<$svShare> is C<"rw"> which provides the same sharing as 1103b39c5158Smillertusing regular perl C<open()>. 1104b39c5158Smillert 1105b39c5158SmillertIf another process currently has read, write, and/or delete access to 1106b39c5158Smillertthe file and you don't allow that level of sharing, then your call to 1107b39c5158SmillertC<createFile> will fail. If you requested read, write, and/or delete 1108b39c5158Smillertaccess and another process already has the file open but doesn't allow 1109b39c5158Smillertthat level of sharing, then your call to C<createFile> will fail. Once 1110b39c5158Smillertyou have the file open, if another process tries to open it with read, 1111b39c5158Smillertwrite, and/or delete access and you don't allow that level of sharing, 1112b39c5158Smillertthen that process won't be allowed to open the file. 1113b39c5158Smillert 1114b39c5158SmillertC<$rvhvOptions> is a reference to a hash where any keys must be from 1115b39c5158Smillertthe list C<qw( Access Create Share Attributes Flags Security Model )>. 1116b39c5158SmillertThe meaning of the value depends on the key name, as described below. 1117b39c5158SmillertAny option values in C<$rvhvOptions> override the settings from 1118b39c5158SmillertC<$svAccess> and C<$svShare> if they conflict. 1119b39c5158Smillert 1120b39c5158Smillert=over 1121b39c5158Smillert 1122b39c5158Smillert=item Flags => $uFlags 1123b39c5158Smillert 1124b39c5158SmillertC<$uFlags> is an unsigned value having any of the C<FILE_FLAG_*> or 1125b39c5158SmillertC<FILE_ATTRIBUTE_*> bits set. Any C<FILE_ATTRIBUTE_*> bits set via the 1126b39c5158SmillertC<Attributes> option are logically C<or>ed with these bits. Defaults 1127b39c5158Smillertto C<0>. 1128b39c5158Smillert 1129b39c5158SmillertIf opening the client side of a named pipe, then you can also specify 1130b39c5158SmillertC<SECURITY_SQOS_PRESENT> along with one of the other C<SECURITY_*> 1131b39c5158Smillertconstants to specify the security quality of service to be used. 1132b39c5158Smillert 1133b39c5158Smillert=item Attributes => $sAttributes 1134b39c5158Smillert 1135b39c5158SmillertA string of zero or more characters from C<"achorst"> [see C<attrLetsToBits> 1136b39c5158Smillertfor more information] which are converted to C<FILE_ATTRIBUTE_*> bits to 1137b39c5158Smillertbe set in the C<$uFlags> argument passed to C<CreateFile>. 1138b39c5158Smillert 1139b39c5158Smillert=item Security => $pSecurityAttributes 1140b39c5158Smillert 1141b39c5158SmillertC<$pSecurityAttributes> should contain a C<SECURITY_ATTRIBUTES> structure 1142b39c5158Smillertpacked into a string or C<[]> [the default]. 1143b39c5158Smillert 1144b39c5158Smillert=item Model => $hModelFile 1145b39c5158Smillert 1146b39c5158SmillertC<$hModelFile> should contain a handle opened with C<GENERIC_READ> 1147b39c5158Smillertaccess to a model file from which file attributes and extended attributes 1148b39c5158Smillertare to be copied. Or C<$hModelFile> can be C<0> [the default]. 1149b39c5158Smillert 1150b39c5158Smillert=item Access => $sAccess 1151b39c5158Smillert 1152b39c5158Smillert=item Access => $uAccess 1153b39c5158Smillert 1154b39c5158SmillertC<$sAccess> should be a string of zero or more characters from 1155b39c5158SmillertC<"qrw"> specifying the type of access desired: "query" or C<0>, 1156b39c5158Smillert"read" or C<GENERIC_READ> [the default], or "write" or 1157b39c5158SmillertC<GENERIC_WRITE>. 1158b39c5158Smillert 1159b39c5158SmillertC<$uAccess> should be an unsigned value containing bits set to 1160b39c5158Smillertindicate the type of access desired. C<GENERIC_READ> is the default. 1161b39c5158Smillert 1162b39c5158Smillert=item Create => $sCreate 1163b39c5158Smillert 1164b39c5158Smillert=item Create => $uCreate 1165b39c5158Smillert 1166b8851fccSafresh1C<$sCreate> should be a string containing zero or one character from 1167b39c5158SmillertC<"ktn"> and zero or one character from C<"ce">. These stand for 1168b39c5158Smillert"Keep if exists", "Truncate if exists", "New file only", "Create if 1169b39c5158Smillertnone", and "Existing file only". These are translated into a 1170b39c5158SmillertC<$uCreate> value. 1171b39c5158Smillert 1172b39c5158SmillertC<$uCreate> should be one of C<OPEN_ALWAYS>, C<OPEN_EXISTING>, 1173b39c5158SmillertC<TRUNCATE_EXISTING>, C<CREATE_ALWAYS>, or C<CREATE_NEW>. 1174b39c5158Smillert 1175b39c5158Smillert=item Share => $sShare 1176b39c5158Smillert 1177b39c5158Smillert=item Share => $uShare 1178b39c5158Smillert 1179b39c5158SmillertC<$sShare> should be a string with zero or more characters from 1180b39c5158SmillertC<"rwd"> that is translated into a C<$uShare> value. C<"rw"> is 1181b39c5158Smillertthe default. 1182b39c5158Smillert 1183b39c5158SmillertC<$uShare> should be an unsigned value having zero or more of the 1184b39c5158Smillertfollowing bits set: C<FILE_SHARE_READ>, C<FILE_SHARE_WRITE>, and 1185b39c5158SmillertC<FILE_SHARE_DELETE>. C<FILE_SHARE_READ|FILE_SHARE_WRITE> is the 1186b39c5158Smillertdefault. 1187b39c5158Smillert 1188b39c5158Smillert=back 1189b39c5158Smillert 1190b39c5158SmillertExamples: 1191b39c5158Smillert 1192b39c5158Smillert $hFlop= createFile( "//./A:", "r", "r" ) 1193b39c5158Smillert or die "Can't prevent others from writing to floppy: $^E\n"; 1194b39c5158Smillert $hDisk= createFile( "//./C:", "rw ke", "" ) 1195b39c5158Smillert or die "Can't get exclusive access to C: $^E\n"; 1196b39c5158Smillert $hDisk= createFile( $sFilePath, "ke", 1197b39c5158Smillert { Access=>FILE_READ_ATTRIBUTES } ) 1198b39c5158Smillert or die "Can't read attributes of $sFilePath: $^E\n"; 1199b39c5158Smillert $hTemp= createFile( "$ENV{Temp}/temp.$$", "wn", "", 1200b39c5158Smillert { Attributes=>"hst", Flags=>FILE_FLAG_DELETE_ON_CLOSE() } ) 1201b39c5158Smillert or die "Can't create temporary file, temp.$$: $^E\n"; 1202b39c5158Smillert 1203b39c5158Smillert=item getLogicalDrives 1204b39c5158Smillert 1205b39c5158Smillert=item C<@roots= getLogicalDrives()> 1206b39c5158Smillert 1207b39c5158SmillertReturns the paths to the root directories of all logical drives 1208b8851fccSafresh1currently defined. This includes all types of drive letters, such 1209b39c5158Smillertas floppies, CD-ROMs, hard disks, and network shares. A typical 1210b39c5158Smillertreturn value on a poorly equipped computer would be C<("A:\\","C:\\")>. 1211b39c5158Smillert 1212b39c5158Smillert=item CloseHandle 1213b39c5158Smillert 1214b39c5158Smillert=item C<CloseHandle( $hObject )> 1215b39c5158Smillert 1216b39c5158SmillertCloses a Win32 native handle, such as one opened via C<CreateFile>. 1217b39c5158SmillertLike most routines, returns a true value if successful and a false 1218b39c5158Smillertvalue [and sets C<$^E> and C<regLastError()>] on failure. 1219b39c5158Smillert 1220b39c5158Smillert=item CopyFile 1221b39c5158Smillert 1222b39c5158Smillert=item C<CopyFile( $sOldFileName, $sNewFileName, $bFailIfExists )> 1223b39c5158Smillert 1224b39c5158SmillertC<$sOldFileName> is the path to the file to be copied. 1225b39c5158SmillertC<$sNewFileName> is the path to where the file should be copied. 1226b39c5158SmillertNote that you can B<NOT> just specify a path to a directory in 1227b39c5158SmillertC<$sNewFileName> to copy the file to that directory using the 1228b39c5158Smillertsame file name. 1229b39c5158Smillert 1230b39c5158SmillertIf C<$bFailIfExists> is true and C<$sNewFileName> is the path to 1231b39c5158Smillerta file that already exists, then C<CopyFile> will fail. If 1232b8851fccSafresh1C<$bFailIfExists> is false, then the copy of the C<$sOldFileNmae> 1233b39c5158Smillertfile will overwrite the C<$sNewFileName> file if it already exists. 1234b39c5158Smillert 1235b39c5158SmillertLike most routines, returns a true value if successful and a false 1236b39c5158Smillertvalue [and sets C<$^E> and C<regLastError()>] on failure. 1237b39c5158Smillert 1238b39c5158Smillert=item CreateFile 1239b39c5158Smillert 1240b39c5158Smillert=item C<$hObject= CreateFile( $sPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )> 1241b39c5158Smillert 1242b39c5158SmillertOn failure, C<$hObject> gets set to a false value and C<$^E> and 1243b39c5158SmillertC<fileLastError()> are set to the reason for the failure. Otherwise, 1244b39c5158SmillertC<$hObject> gets set to a Win32 native file handle which is always a 1245b39c5158Smillerttrue value [returns C<"0 but true"> in the impossible(?) case of the 1246b39c5158Smillerthandle having a value of C<0>]. 1247b39c5158Smillert 1248b39c5158SmillertC<$sPath> is the path to the file [or device, etc.] to be opened. 1249b39c5158Smillert 1250b39c5158SmillertC<$sPath> can use C<"/"> or C<"\\"> as path delimiters and can even 1251b39c5158Smillertmix the two. We will usually only use C<"/"> in our examples since 1252b39c5158Smillertusing C<"\\"> is usually harder to read. 1253b39c5158Smillert 1254b39c5158SmillertUnder Windows NT, C<$sPath> can start with C<"//?/"> to allow the use 1255b39c5158Smillertof paths longer than C<MAX_PATH> [for UNC paths, replace the leading 1256b39c5158SmillertC<"//"> with C<"//?/UNC/">, as in C<"//?/UNC/Server/Share/Dir/File.Ext">]. 1257b39c5158Smillert 1258b39c5158SmillertC<$sPath> can start with C<"//./"> to indicate that the rest of the 1259b39c5158Smillertpath is the name of a "DOS device." You can use C<QueryDosDevice> 1260b39c5158Smillertto list all current DOS devices and can add or delete them with 1261b39c5158SmillertC<DefineDosDevice>. If you get the source-code distribution of this 1262b39c5158Smillertmodule from CPAN, then it includes an example script, F<ex/ListDevs.plx> 1263b39c5158Smillertthat will list all current DOS devices and their "native" definition. 1264b39c5158SmillertAgain, note that this doesn't work under Win95 nor Win98. 1265b39c5158Smillert 1266b39c5158SmillertThe most common such DOS devices include: 1267b39c5158Smillert 1268b39c5158Smillert=over 1269b39c5158Smillert 1270b39c5158Smillert=item C<"//./PhysicalDrive0"> 1271b39c5158Smillert 1272b39c5158SmillertYour entire first hard disk. Doesn't work under Windows 95. This 1273b39c5158Smillertallows you to read or write raw sectors of your hard disk and to use 1274b39c5158SmillertC<DeviceIoControl> to perform miscellaneous queries and operations 1275b39c5158Smillertto the hard disk. Writing raw sectors and certain other operations 1276b39c5158Smillertcan seriously damage your files or the function of your computer. 1277b39c5158Smillert 1278b39c5158SmillertLocking this for exclusive access [by specifying C<0> for C<$uShare>] 1279b39c5158Smillertdoesn't prevent access to the partitions on the disk nor their file 1280b39c5158Smillertsystems. So other processes can still access any raw sectors within 1281b39c5158Smillerta partition and can use the file system on the disk as usual. 1282b39c5158Smillert 1283b39c5158Smillert=item C<"//./C:"> 1284b39c5158Smillert 1285b39c5158SmillertYour F<C:> partition. Doesn't work under Windows 95. This allows 1286b39c5158Smillertyou to read or write raw sectors of that partition and to use 1287b39c5158SmillertC<DeviceIoControl> to perform miscellaneous queries and operations 1288b39c5158Smillertto the partition. Writing raw sectors and certain other operations 1289b39c5158Smillertcan seriously damage your files or the function of your computer. 1290b39c5158Smillert 1291b39c5158SmillertLocking this for exclusive access doesn't prevent access to the 1292b39c5158Smillertphysical drive that the partition is on so other processes can 1293b39c5158Smillertstill access the raw sectors that way. Locking this for exclusive 1294b39c5158Smillertaccess B<does> prevent other processes from opening the same raw 1295b39c5158Smillertpartition and B<does> prevent access to the file system on it. It 1296b39c5158Smillerteven prevents the current process from accessing the file system 1297b39c5158Smillerton that partition. 1298b39c5158Smillert 1299b39c5158Smillert=item C<"//./A:"> 1300b39c5158Smillert 1301b39c5158SmillertThe raw floppy disk. Doesn't work under Windows 95. This allows 1302b39c5158Smillertyou to read or write raw sectors of the floppy disk and to use 1303b39c5158SmillertC<DeviceIoControl> to perform miscellaneous queries and operations 1304b8851fccSafresh1to the floppy disk or drive. 1305b39c5158Smillert 1306b39c5158SmillertLocking this for exclusive access prevents all access to the floppy. 1307b39c5158Smillert 1308b39c5158Smillert=item C<"//./PIPE/PipeName"> 1309b39c5158Smillert 1310b39c5158SmillertA named pipe, created via C<CreateNamedPipe>. 1311b39c5158Smillert 1312b39c5158Smillert=back 1313b39c5158Smillert 1314b39c5158SmillertC<$uAccess> is an unsigned value with bits set indicating the 1315b39c5158Smillerttype of access desired. Usually either C<0> ["query" access], 1316b39c5158SmillertC<GENERIC_READ>, C<GENERIC_WRITE>, C<GENERIC_READ|GENERIC_WRITE>, 1317b39c5158Smillertor C<GENERIC_ALL>. More specific types of access can be specified, 1318b39c5158Smillertsuch as C<FILE_APPEND_DATA> or C<FILE_READ_EA>. 1319b39c5158Smillert 1320b39c5158SmillertC<$uShare> controls how the file is shared, that is, whether other 1321b39c5158Smillertprocesses can have read, write, and/or delete access to the file while 1322b39c5158Smillertwe have it opened. C<$uShare> is an unsigned value with zero or more 1323b39c5158Smillertof these bits set: C<FILE_SHARE_READ>, C<FILE_SHARE_WRITE>, and 1324b39c5158SmillertC<FILE_SHARE_DELETE>. 1325b39c5158Smillert 1326b39c5158SmillertIf another process currently has read, write, and/or delete access to 1327b39c5158Smillertthe file and you don't allow that level of sharing, then your call to 1328b39c5158SmillertC<CreateFile> will fail. If you requested read, write, and/or delete 1329b39c5158Smillertaccess and another process already has the file open but doesn't allow 1330b8851fccSafresh1that level of sharing, then your call to C<createFile> will fail. Once 1331b39c5158Smillertyou have the file open, if another process tries to open it with read, 1332b39c5158Smillertwrite, and/or delete access and you don't allow that level of sharing, 1333b39c5158Smillertthen that process won't be allowed to open the file. 1334b39c5158Smillert 1335b39c5158SmillertC<$pSecAttr> should either be C<[]> [for C<NULL>] or a 1336b39c5158SmillertC<SECURITY_ATTRIBUTES> data structure packed into a string. 1337b39c5158SmillertFor example, if C<$pSecDesc> contains a C<SECURITY_DESCRIPTOR> 1338b39c5158Smillertstructure packed into a string, perhaps via: 1339b39c5158Smillert 1340b39c5158Smillert RegGetKeySecurity( $key, 4, $pSecDesc, 1024 ); 1341b39c5158Smillert 1342b39c5158Smillertthen you can set C<$pSecAttr> via: 1343b39c5158Smillert 1344b39c5158Smillert $pSecAttr= pack( "L P i", 12, $pSecDesc, $bInheritHandle ); 1345b39c5158Smillert 1346b39c5158SmillertC<$uCreate> is one of the following values: C<OPEN_ALWAYS>, 1347b39c5158SmillertC<OPEN_EXISTING>, C<TRUNCATE_EXISTING>, C<CREATE_ALWAYS>, and 1348b39c5158SmillertC<CREATE_NEW>. 1349b39c5158Smillert 1350b39c5158SmillertC<$uFlags> is an unsigned value with zero or more bits set indicating 1351b39c5158Smillertattributes to associate with the file [C<FILE_ATTRIBUTE_*> values] or 1352b39c5158Smillertspecial options [C<FILE_FLAG_*> values]. 1353b39c5158Smillert 1354b39c5158SmillertIf opening the client side of a named pipe, then you can also set 1355b39c5158SmillertC<$uFlags> to include C<SECURITY_SQOS_PRESENT> along with one of the 1356b39c5158Smillertother C<SECURITY_*> constants to specify the security quality of 1357b39c5158Smillertservice to be used. 1358b39c5158Smillert 1359b39c5158SmillertC<$hModel> is C<0> [or C<[]>, both of which mean C<NULL>] or a Win32 1360b39c5158Smillertnative handle opened with C<GENERIC_READ> access to a model file from 1361b39c5158Smillertwhich file attributes and extended attributes are to be copied if a 1362b39c5158Smillertnew file gets created. 1363b39c5158Smillert 1364b39c5158SmillertExamples: 1365b39c5158Smillert 1366b39c5158Smillert $hFlop= CreateFile( "//./A:", GENERIC_READ(), 1367b39c5158Smillert FILE_SHARE_READ(), [], OPEN_EXISTING(), 0, [] ) 1368b39c5158Smillert or die "Can't prevent others from writing to floppy: $^E\n"; 1369b39c5158Smillert $hDisk= CreateFile( $sFilePath, FILE_READ_ATTRIBUTES(), 1370b39c5158Smillert FILE_SHARE_READ()|FILE_SHARE_WRITE(), [], OPEN_EXISTING(), 0, [] ) 1371b39c5158Smillert or die "Can't read attributes of $sFilePath: $^E\n"; 1372b39c5158Smillert $hTemp= CreateFile( "$ENV{Temp}/temp.$$", GENERIC_WRITE(), 0, 1373b39c5158Smillert CREATE_NEW(), FILE_FLAG_DELETE_ON_CLOSE()|attrLetsToBits("hst"), [] ) 1374b39c5158Smillert or die "Can't create temporary file, temp.$$: $^E\n"; 1375b39c5158Smillert 1376b39c5158Smillert=item DefineDosDevice 1377b39c5158Smillert 1378b39c5158Smillert=item C<DefineDosDevice( $uFlags, $sDosDeviceName, $sTargetPath )> 1379b39c5158Smillert 1380b39c5158SmillertDefines a new DOS device, overrides the current definition of a DOS 1381b39c5158Smillertdevice, or deletes a definition of a DOS device. Like most routines, 1382b39c5158Smillertreturns a true value if successful and a false value [and sets C<$^E> 1383b39c5158Smillertand C<regLastError()>] on failure. 1384b39c5158Smillert 1385b39c5158SmillertC<$sDosDeviceName> is the name of a DOS device for which we'd like 1386b39c5158Smillertto add or delete a definition. 1387b39c5158Smillert 1388b39c5158SmillertC<$uFlags> is an unsigned value with zero or more of the following 1389b39c5158Smillertbits set: 1390b39c5158Smillert 1391b39c5158Smillert=over 1392b39c5158Smillert 1393b39c5158Smillert=item C<DDD_RAW_TARGET_PATH> 1394b39c5158Smillert 1395b39c5158SmillertIndicates that C<$sTargetPath> will be a raw Windows NT object name. 1396b39c5158SmillertThis usually means that C<$sTargetPath> starts with C<"\\Device\\">. 1397b39c5158SmillertNote that you cannot use C<"/"> in place of C<"\\"> in raw target path 1398b39c5158Smillertnames. 1399b39c5158Smillert 1400b39c5158Smillert=item C<DDD_REMOVE_DEFINITION> 1401b39c5158Smillert 1402b39c5158SmillertRequests that a definition be deleted. If C<$sTargetPath> is 1403b39c5158SmillertC<[]> [for C<NULL>], then the most recently added definition for 1404b39c5158SmillertC<$sDosDeviceName> is removed. Otherwise the most recently added 1405b39c5158Smillertdefinition matching C<$sTargetPath> is removed. 1406b39c5158Smillert 1407b39c5158SmillertIf the last definition is removed, then the DOS device name is 1408b39c5158Smillertalso deleted. 1409b39c5158Smillert 1410b39c5158Smillert=item C<DDD_EXACT_MATCH_ON_REMOVE> 1411b39c5158Smillert 1412b39c5158SmillertWhen deleting a definition, this bit causes each C<$sTargetPath> to 1413b39c5158Smillertbe compared to the full-length definition when searching for the most 1414b39c5158Smillertrecently added match. If this bit is not set, then C<$sTargetPath> 1415b39c5158Smillertonly needs to match a prefix of the definition. 1416b39c5158Smillert 1417b39c5158Smillert=back 1418b39c5158Smillert 1419b39c5158SmillertC<$sTargetPath> is the DOS device's specific definition that you 1420b39c5158Smillertwish to add or delete. For C<DDD_RAW_TARGET_PATH>, these usually 1421b39c5158Smillertstart with C<"\\Device\\">. If the C<DDD_RAW_TARGET_PATH> bit is 1422b39c5158Smillertnot set, then C<$sTargetPath> is just an ordinary path to some file 1423b39c5158Smillertor directory, providing the functionality of the B<subst> command. 1424b39c5158Smillert 1425b39c5158Smillert=item DeleteFile 1426b39c5158Smillert 1427b39c5158Smillert=item C<DeleteFile( $sFileName )> 1428b39c5158Smillert 1429b39c5158SmillertDeletes the named file. Compared to Perl's C<unlink>, C<DeleteFile> 1430b39c5158Smillerthas the advantage of not deleting read-only files. For B<some> 1431b39c5158Smillertversions of Perl, C<unlink> silently calls C<chmod> whether it needs 1432b39c5158Smillertto or not before deleting the file so that files that you have 1433b39c5158Smillertprotected by marking them as read-only are not always protected from 1434b39c5158SmillertPerl's C<unlink>. 1435b39c5158Smillert 1436b39c5158SmillertLike most routines, returns a true value if successful and a false 1437b39c5158Smillertvalue [and sets C<$^E> and C<regLastError()>] on failure. 1438b39c5158Smillert 1439b39c5158Smillert=item DeviceIoControl 1440b39c5158Smillert 1441b39c5158Smillert=item C<DeviceIoControl( $hDevice, $uIoControlCode, $pInBuf, $lInBuf, $opOutBuf, $lOutBuf, $olRetBytes, $pOverlapped )> 1442b39c5158Smillert 1443b39c5158SmillertRequests a special operation on an I/O [input/output] device, such 1444b39c5158Smillertas ejecting a tape or formatting a disk. Like most routines, returns 1445b39c5158Smillerta true value if successful and a false value [and sets C<$^E> and 1446b39c5158SmillertC<regLastError()>] on failure. 1447b39c5158Smillert 1448b39c5158SmillertC<$hDevice> is a Win32 native file handle to a device [return value 1449b39c5158Smillertfrom C<CreateFile>]. 1450b39c5158Smillert 1451b39c5158SmillertC<$uIoControlCode> is an unsigned value [a C<IOCTL_*> or C<FSCTL_*> 1452b39c5158Smillertconstant] indicating the type query or other operation to be performed. 1453b39c5158Smillert 1454b39c5158SmillertC<$pInBuf> is C<[]> [for C<NULL>] or a data structure packed into a 1455b39c5158Smillertstring. The type of data structure depends on the C<$uIoControlCode> 1456b39c5158Smillertvalue. C<$lInBuf> is C<0> or the length of the structure in 1457b39c5158SmillertC<$pInBuf>. If C<$pInBuf> is not C<[]> and C<$lInBuf> is C<0>, then 1458b39c5158SmillertC<$lInBuf> will automatically be set to C<length($pInBuf)> for you. 1459b39c5158Smillert 1460b39c5158SmillertC<$opOutBuf> is C<[]> [for C<NULL>] or will be set to contain a 1461b39c5158Smillertreturned data structure packed into a string. C<$lOutBuf> indicates 1462b39c5158Smillerthow much space to allocate in C<$opOutBuf> for C<DeviceIoControl> to 1463b39c5158Smillertstore the data structure. If C<$lOutBuf> is a number and C<$opOutBuf> 1464b39c5158Smillertalready has a buffer allocated for it that is larger than C<$lOutBuf> 1465b39c5158Smillertbytes, then this larger buffer size will be passed to C<DeviceIoControl>. 1466b39c5158SmillertHowever, you can force a specific buffer size to be passed to 1467b39c5158SmillertC<DeviceIoControl> by prepending a C<"="> to the front of C<$lOutBuf>. 1468b39c5158Smillert 1469b39c5158SmillertC<$olRetBytes> is C<[]> or is a scalar to receive the number of bytes 1470b39c5158Smillertwritten to C<$opOutBuf>. Even when C<$olRetBytes> is C<[]>, a valid 1471b39c5158Smillertpointer to a C<DWORD> [and not C<NULL>] is passed to C<DeviceIoControl>. 1472b39c5158SmillertIn this case, C<[]> just means that you don't care about the value 1473b39c5158Smillertthat might be written to C<$olRetBytes>, which is usually the case 1474b39c5158Smillertsince you can usually use C<length($opOutBuf)> instead. 1475b39c5158Smillert 1476b39c5158SmillertC<$pOverlapped> is C<[]> or is a C<OVERLAPPED> structure packed into 1477b39c5158Smillerta string. This is only useful if C<$hDevice> was opened with the 1478b39c5158SmillertC<FILE_FLAG_OVERLAPPED> flag set. 1479b39c5158Smillert 1480b39c5158Smillert=item FdGetOsFHandle 1481b39c5158Smillert 1482b39c5158Smillert=item C<$hNativeHandle= FdGetOsFHandle( $ivFd )> 1483b39c5158Smillert 1484b39c5158SmillertC<FdGetOsFHandle> simply calls C<_get_osfhandle()>. It was renamed 1485b39c5158Smillertto better fit in with the rest the function names of this module, 1486b39c5158Smillertin particular to distinguish it from C<GetOsFHandle>. It takes an 1487b39c5158Smillertinteger file descriptor [as from Perl's C<fileno>] and returns the 1488b39c5158SmillertWin32 native file handle associated with that file descriptor or 1489b39c5158SmillertC<INVALID_HANDLE_VALUE> if C<$ivFd> is not an open file descriptor. 1490b39c5158Smillert 1491b39c5158SmillertWhen you call Perl's C<open> to set a Perl file handle [like C<STDOUT>], 1492b39c5158SmillertPerl calls C's C<fopen> to set a stdio C<FILE *>. C's C<fopen> calls 1493b39c5158Smillertsomething like Unix's C<open>, that is, Win32's C<_sopen>, to get an 1494b39c5158Smillertinteger file descriptor [where 0 is for C<STDIN>, 1 for C<STDOUT>, etc.]. 1495b39c5158SmillertWin32's C<_sopen> calls C<CreateFile> to set a C<HANDLE>, a Win32 native 1496b39c5158Smillertfile handle. So every Perl file handle [like C<STDOUT>] has an integer 1497b39c5158Smillertfile descriptor associated with it that you can get via C<fileno>. And, 1498b39c5158Smillertunder Win32, every file descriptor has a Win32 native file handle 1499b39c5158Smillertassociated with it. C<FdGetOsFHandle> lets you get access to that. 1500b39c5158Smillert 1501b39c5158SmillertC<$hNativeHandle> is set to C<INVALID_HANDLE_VALUE> [and 1502b39c5158SmillertC<lastFileError()> and C<$^E> are set] if C<FdGetOsFHandle> fails. 1503b39c5158SmillertSee also C<GetOsFHandle> which provides a friendlier interface. 1504b39c5158Smillert 1505b39c5158Smillert=item fileConstant 1506b39c5158Smillert 1507b39c5158Smillert=item C<$value= fileConstant( $sConstantName )> 1508b39c5158Smillert 1509b39c5158SmillertFetch the value of a constant. Returns C<undef> if C<$sConstantName> 1510b39c5158Smillertis not the name of a constant supported by this module. Never sets 1511b39c5158SmillertC<$!> nor C<$^E>. 1512b39c5158Smillert 1513b39c5158SmillertThis function is rarely used since you will usually get the value of a 1514b39c5158Smillertconstant by having that constant imported into your package by listing 1515b39c5158Smillertthe constant name in the C<use Win32API::File> statement and then 1516b39c5158Smillertsimply using the constant name in your code [perhaps followed by 1517b39c5158SmillertC<()>]. This function is useful for verifying constant names not in 1518b39c5158SmillertPerl code, for example, after prompting a user to type in a constant 1519b39c5158Smillertname. 1520b39c5158Smillert 1521b39c5158Smillert=item fileLastError 1522b39c5158Smillert 1523b39c5158Smillert=item C<$svError= fileLastError();> 1524b39c5158Smillert 1525b39c5158Smillert=item C<fileLastError( $uError );> 1526b39c5158Smillert 1527b39c5158SmillertReturns the last error encountered by a routine from this module. 1528b39c5158SmillertIt is just like C<$^E> except it isn't changed by anything except 1529b39c5158Smillertroutines from this module. Ideally you could just use C<$^E>, but 1530b39c5158Smillertcurrent versions of Perl often overwrite C<$^E> before you get a 1531b39c5158Smillertchance to check it and really old versions of Perl don't really 1532b39c5158Smillertsupport C<$^E> under Win32. 1533b39c5158Smillert 1534b39c5158SmillertJust like C<$^E>, in a numeric context C<fileLastError()> returns 1535b39c5158Smillertthe numeric error value while in a string context it returns a 1536b39c5158Smillerttext description of the error [actually it returns a Perl scalar 1537b39c5158Smillertthat contains both values so C<$x= fileLastError()> causes C<$x> 1538b39c5158Smillertto give different values in string vs. numeric contexts]. 1539b39c5158Smillert 1540b39c5158SmillertThe last form sets the error returned by future calls to 1541b39c5158SmillertC<fileLastError()> and should not be used often. C<$uError> must 1542b39c5158Smillertbe a numeric error code. Also returns the dual-valued version 1543b39c5158Smillertof C<$uError>. 1544b39c5158Smillert 1545b39c5158Smillert=item GetDriveType 1546b39c5158Smillert 1547b39c5158Smillert=item C<$uDriveType= GetDriveType( $sRootPath )> 1548b39c5158Smillert 1549b39c5158SmillertTakes a string giving the path to the root directory of a file system 1550b39c5158Smillert[called a "drive" because every file system is assigned a "drive letter"] 1551b39c5158Smillertand returns an unsigned value indicating the type of drive the file 1552b39c5158Smillertsystem is on. The return value should be one of: 1553b39c5158Smillert 1554b39c5158Smillert=over 1555b39c5158Smillert 1556b39c5158Smillert=item C<DRIVE_UNKNOWN> 1557b39c5158Smillert 1558b39c5158SmillertNone of the following. 1559b39c5158Smillert 1560b39c5158Smillert=item C<DRIVE_NO_ROOT_DIR> 1561b39c5158Smillert 1562b39c5158SmillertA "drive" that does not have a file system. This can be a drive letter 1563b39c5158Smillertthat hasn't been defined or a drive letter assigned to a partition 1564b39c5158Smillertthat hasn't been formatted yet. 1565b39c5158Smillert 1566b39c5158Smillert=item C<DRIVE_REMOVABLE> 1567b39c5158Smillert 1568b39c5158SmillertA floppy diskette drive or other removable media drive, but not a CD-ROM 1569b39c5158Smillertdrive. 1570b39c5158Smillert 1571b39c5158Smillert=item C<DRIVE_FIXED> 1572b39c5158Smillert 1573b39c5158SmillertAn ordinary hard disk partition. 1574b39c5158Smillert 1575b39c5158Smillert=item C<DRIVE_REMOTE> 1576b39c5158Smillert 1577b39c5158SmillertA network share. 1578b39c5158Smillert 1579b39c5158Smillert=item C<DRIVE_CDROM> 1580b39c5158Smillert 1581b39c5158SmillertA CD-ROM drive. 1582b39c5158Smillert 1583b39c5158Smillert=item C<DRIVE_RAMDISK> 1584b39c5158Smillert 1585b39c5158SmillertA "ram disk" or memory-resident virtual file system used for high-speed 1586b39c5158Smillertaccess to small amounts of temporary file space. 1587b39c5158Smillert 1588b39c5158Smillert=back 1589b39c5158Smillert 1590b39c5158Smillert=item GetFileAttributes 1591b39c5158Smillert 1592b39c5158Smillert=item C<$uAttrs = GetFileAttributes( $sPath )> 1593b39c5158Smillert 1594b39c5158SmillertTakes a path string and returns an unsigned value with attribute flags. 1595b39c5158SmillertIf it fails, it returns INVALID_FILE_ATTRIBUTES, otherwise it can be 1596b39c5158Smillertone or more of the following values: 1597b39c5158Smillert 1598b39c5158Smillert=over 1599b39c5158Smillert 1600b39c5158Smillert=item C<FILE_ATTRIBUTE_ARCHIVE> 1601b39c5158Smillert 1602b39c5158SmillertThe file or directory is an archive file or directory. Applications use 1603b39c5158Smillertthis attribute to mark files for backup or removal. 1604b39c5158Smillert 1605b39c5158Smillert=item C<FILE_ATTRIBUTE_COMPRESSED> 1606b39c5158Smillert 1607b39c5158SmillertThe file or directory is compressed. For a file, this means that all of 1608b39c5158Smillertthe data in the file is compressed. For a directory, this means that 1609b39c5158Smillertcompression is the default for newly created files and subdirectories. 1610b39c5158Smillert 1611b39c5158Smillert=item C<FILE_ATTRIBUTE_DEVICE> 1612b39c5158Smillert 1613b39c5158SmillertReserved; do not use. 1614b39c5158Smillert 1615b39c5158Smillert=item C<FILE_ATTRIBUTE_DIRECTORY> 1616b39c5158Smillert 1617b39c5158SmillertThe handle identifies a directory. 1618b39c5158Smillert 1619b39c5158Smillert=item C<FILE_ATTRIBUTE_ENCRYPTED> 1620b39c5158Smillert 1621b39c5158SmillertThe file or directory is encrypted. For a file, this means that all data 1622b39c5158Smillertstreams in the file are encrypted. For a directory, this means that 1623b39c5158Smillertencryption is the default for newly created files and subdirectories. 1624b39c5158Smillert 1625b39c5158Smillert=item C<FILE_ATTRIBUTE_HIDDEN> 1626b39c5158Smillert 1627b39c5158SmillertThe file or directory is hidden. It is not included in an ordinary directory 1628b39c5158Smillertlisting. 1629b39c5158Smillert 1630b39c5158Smillert=item C<FILE_ATTRIBUTE_NORMAL> 1631b39c5158Smillert 1632b39c5158SmillertThe file or directory has no other attributes set. This attribute is valid 1633b39c5158Smillertonly if used alone. 1634b39c5158Smillert 1635b39c5158Smillert=item C<FILE_ATTRIBUTE_NOT_CONTENT_INDEXED> 1636b39c5158Smillert 1637b39c5158SmillertThe file will not be indexed by the content indexing service. 1638b39c5158Smillert 1639b39c5158Smillert=item C<FILE_ATTRIBUTE_OFFLINE> 1640b39c5158Smillert 1641b39c5158SmillertThe data of the file is not immediately available. This attribute indicates 1642b39c5158Smillertthat the file data has been physically moved to offline storage. This 1643b39c5158Smillertattribute is used by Remote Storage, the hierarchical storage management 1644b39c5158Smillertsoftware. Applications should not arbitrarily change this attribute. 1645b39c5158Smillert 1646b39c5158Smillert=item C<FILE_ATTRIBUTE_READONLY> 1647b39c5158Smillert 1648b39c5158SmillertThe file or directory is read-only. Applications can read the file but cannot 1649b39c5158Smillertwrite to it or delete it. In the case of a directory, applications cannot 1650b39c5158Smillertdelete it. 1651b39c5158Smillert 1652b39c5158Smillert=item C<FILE_ATTRIBUTE_REPARSE_POINT> 1653b39c5158Smillert 1654b39c5158SmillertThe file or directory has an associated reparse point. 1655b39c5158Smillert 1656b39c5158Smillert=item C<FILE_ATTRIBUTE_SPARSE_FILE> 1657b39c5158Smillert 1658b39c5158SmillertThe file is a sparse file. 1659b39c5158Smillert 1660b39c5158Smillert=item C<FILE_ATTRIBUTE_SYSTEM> 1661b39c5158Smillert 1662b39c5158SmillertThe file or directory is part of, or is used exclusively by, the operating 1663b39c5158Smillertsystem. 1664b39c5158Smillert 1665b39c5158Smillert=item C<FILE_ATTRIBUTE_TEMPORARY> 1666b39c5158Smillert 1667b39c5158SmillertThe file is being used for temporary storage. File systems avoid writing 1668b39c5158Smillertdata back to mass storage if sufficient cache memory is available, because 1669b39c5158Smillertoften the application deletes the temporary file shortly after the handle is 1670b39c5158Smillertclosed. In that case, the system can entirely avoid writing the data. 1671b39c5158SmillertOtherwise, the data will be written after the handle is closed. 1672b39c5158Smillert 1673b39c5158Smillert=back 1674b39c5158Smillert 1675b39c5158Smillert=item GetFileType 1676b39c5158Smillert 1677b39c5158Smillert=item C<$uFileType= GetFileType( $hFile )> 1678b39c5158Smillert 1679b39c5158SmillertTakes a Win32 native file handle and returns a C<FILE_TYPE_*> constant 1680b39c5158Smillertindicating the type of the file opened on that handle: 1681b39c5158Smillert 1682b39c5158Smillert=over 1683b39c5158Smillert 1684b39c5158Smillert=item C<FILE_TYPE_UNKNOWN> 1685b39c5158Smillert 1686b39c5158SmillertNone of the below. Often a special device. 1687b39c5158Smillert 1688b39c5158Smillert=item C<FILE_TYPE_DISK> 1689b39c5158Smillert 1690b39c5158SmillertAn ordinary disk file. 1691b39c5158Smillert 1692b39c5158Smillert=item C<FILE_TYPE_CHAR> 1693b39c5158Smillert 1694b39c5158SmillertWhat Unix would call a "character special file", that is, a device that 1695b39c5158Smillertworks on character streams such as a printer port or a console. 1696b39c5158Smillert 1697b39c5158Smillert=item C<FILE_TYPE_PIPE> 1698b39c5158Smillert 1699b39c5158SmillertEither a named or anonymous pipe. 1700b39c5158Smillert 1701b39c5158Smillert=back 1702b39c5158Smillert 1703b39c5158Smillert=item getFileSize 1704b39c5158Smillert 1705b39c5158Smillert=item C<$size= getFileSize( $hFile )> 1706b39c5158Smillert 1707b39c5158SmillertThis is a Perl-friendly wrapper for the C<GetFileSize> (below) API call. 1708b39c5158Smillert 1709b39c5158SmillertIt takes a Win32 native file handle and returns the size in bytes. Since the 1710b39c5158Smillertsize can be a 64 bit value, on non 64 bit integer Perls the value returned will 1711b39c5158Smillertbe an object of type C<Math::BigInt>. 1712b39c5158Smillert 1713b39c5158Smillert=item GetFileSize 1714b39c5158Smillert 1715b39c5158Smillert=item C<$iSizeLow= GetFileSize($win32Handle, $iSizeHigh)> 1716b39c5158Smillert 1717b39c5158SmillertReturns the size of a file pointed to by C<$win32Handle>, optionally storing 1718b39c5158Smillertthe high order 32 bits into C<$iSizeHigh> if it is not C<[]>. If $iSizeHigh is 1719b39c5158SmillertC<[]>, a non-zero value indicates success. Otherwise, on failure the return 1720b39c5158Smillertvalue will be C<0xffffffff> and C<fileLastError()> will not be C<NO_ERROR>. 1721b39c5158Smillert 1722b39c5158Smillert=item GetOverlappedResult 1723b39c5158Smillert 1724b39c5158Smillert=item C<$bRetval= GetOverlappedResult( $win32Handle, $pOverlapped, 1725b39c5158Smillert $numBytesTransferred, $bWait )> 1726b39c5158Smillert 1727b39c5158SmillertUsed for asynchronous IO in Win32 to get the result of a pending IO operation, 1728b39c5158Smillertsuch as when a file operation returns C<ERROR_IO_PENDING>. Returns a false 1729b39c5158Smillertvalue on failure. The C<$overlapped> structure and C<$numBytesTransferred> 1730b39c5158Smillertwill be modified with the results of the operation. 1731b39c5158Smillert 1732b39c5158SmillertAs far as creating the C<$pOverlapped> structure, you are currently on your own. 1733b39c5158Smillert 1734b39c5158SmillertSee L<http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/getoverlappedresult.asp> for more information. 1735b39c5158Smillert 1736b39c5158Smillert=item GetLogicalDrives 1737b39c5158Smillert 1738b39c5158Smillert=item C<$uDriveBits= GetLogicalDrives()> 1739b39c5158Smillert 1740b39c5158SmillertReturns an unsigned value with one bit set for each drive letter currently 1741b39c5158Smillertdefined. If "A:" is currently a valid drive letter, then the C<1> bit 1742b39c5158Smillertwill be set in C<$uDriveBits>. If "B:" is valid, then the C<2> bit will 1743b39c5158Smillertbe set. If "Z:" is valid, then the C<2**26> [C<0x4000000>] bit will be 1744b39c5158Smillertset. 1745b39c5158Smillert 1746b39c5158Smillert=item GetLogicalDriveStrings 1747b39c5158Smillert 1748b39c5158Smillert=item C<$olOutLength= GetLogicalDriveStrings( $lBufSize, $osBuffer )> 1749b39c5158Smillert 1750b39c5158SmillertFor each currently defined drive letter, a C<'\0'>-terminated string 1751b39c5158Smillertof the path to the root of its file system is constructed. All of 1752b39c5158Smillertthese strings are concatenated into a single larger string and an 1753b39c5158Smillertextra terminating C<'\0'> is added. This larger string is returned 1754b39c5158Smillertin C<$osBuffer>. Note that this includes drive letters that have 1755b39c5158Smillertbeen defined but that have no file system, such as drive letters 1756b39c5158Smillertassigned to unformatted partitions. 1757b39c5158Smillert 1758b39c5158SmillertC<$lBufSize> is the size of the buffer to allocate to store this 1759b39c5158Smillertlist of strings. C<26*4+1> is always sufficient and should usually 1760b39c5158Smillertbe used. 1761b39c5158Smillert 1762b39c5158SmillertC<$osBuffer> is a scalar to be set to contain the constructed string. 1763b39c5158Smillert 1764b39c5158SmillertC<$olOutLength> is the number of bytes actually written to C<$osBuffer> 1765b39c5158Smillertbut C<length($osBuffer)> can also be used to determine this. 1766b39c5158Smillert 1767b39c5158SmillertFor example, on a poorly equipped computer, 1768b39c5158Smillert 1769b39c5158Smillert GetLogicalDriveStrings( 4*26+1, $osBuffer ); 1770b39c5158Smillert 1771b39c5158Smillertmight set C<$osBuffer> to the 9-character string, C<"A:\\\0C:\\\0\0">. 1772b39c5158Smillert 1773b39c5158Smillert=item GetHandleInformation 1774b39c5158Smillert 1775b39c5158Smillert=item C<GetHandleInformation( $hObject, $ouFlags )> 1776b39c5158Smillert 1777b39c5158SmillertRetrieves the flags associated with a Win32 native file handle or object 1778b39c5158Smillerthandle. 1779b39c5158Smillert 1780b39c5158SmillertC<$hObject> is an open Win32 native file handle or an open Win32 native 1781b39c5158Smillerthandle to some other type of object. 1782b39c5158Smillert 1783b39c5158SmillertC<$ouFlags> will be set to an unsigned value having zero or more of 1784b39c5158Smillertthe bits C<HANDLE_FLAG_INHERIT> and C<HANDLE_FLAG_PROTECT_FROM_CLOSE> 1785b39c5158Smillertset. See the C<":HANDLE_FLAG_"> export class for the meanings of these 1786b39c5158Smillertbits. 1787b39c5158Smillert 1788b39c5158Smillert=item GetOsFHandle 1789b39c5158Smillert 1790b39c5158Smillert=item C<$hNativeHandle= GetOsFHandle( FILE )> 1791b39c5158Smillert 1792b39c5158SmillertTakes a Perl file handle [like C<STDIN>] and returns the Win32 native 1793b39c5158Smillertfile handle associated with it. See C<FdGetOsFHandle> for more 1794b39c5158Smillertinformation about Win32 native file handles. 1795b39c5158Smillert 1796b39c5158SmillertC<$hNativeHandle> is set to a false value [and C<lastFileError()> and 1797b39c5158SmillertC<$^E> are set] if C<GetOsFHandle> fails. C<GetOsFHandle> returns 1798b39c5158SmillertC<"0 but true"> in the impossible(?) case of the handle having a value 1799b39c5158Smillertof C<0>. 1800b39c5158Smillert 1801b39c5158Smillert=item GetVolumeInformation 1802b39c5158Smillert 1803b39c5158Smillert=item C<GetVolumeInformation( $sRootPath, $osVolName, $lVolName, $ouSerialNum, $ouMaxNameLen, $ouFsFlags, $osFsType, $lFsType )> 1804b39c5158Smillert 1805b39c5158SmillertGets information about a file system volume, returning a true 1806b39c5158Smillertvalue if successful. On failure, returns a false value and sets 1807b39c5158SmillertC<fileLastError()> and C<$^E>. 1808b39c5158Smillert 1809b39c5158SmillertC<$sRootPath> is a string specifying the path to the root of the file system, 1810b39c5158Smillertfor example, C<"C:/">. 1811b39c5158Smillert 1812b39c5158SmillertC<$osVolName> is a scalar to be set to the string representing the 1813b39c5158Smillertvolume name, also called the file system label. C<$lVolName> is the 1814b39c5158Smillertnumber of bytes to allocate for the C<$osVolName> buffer [see 1815b39c5158SmillertL<Buffer Sizes> for more information]. 1816b39c5158Smillert 1817b39c5158SmillertC<$ouSerialNum> is C<[]> [for C<NULL>] or will be set to the numeric 1818b39c5158Smillertvalue of the volume's serial number. 1819b39c5158Smillert 1820b39c5158SmillertC<$ouMaxNameLen> is C<[]> [for C<NULL>] or will be set to the maximum 1821b39c5158Smillertlength allowed for a file name or directory name within the file system. 1822b39c5158Smillert 1823b39c5158SmillertC<$osFsType> is a scalar to be set to the string representing the 1824b39c5158Smillertfile system type, such as C<"FAT"> or C<"NTFS">. C<$lFsType> is the 1825b39c5158Smillertnumber of bytes to allocate for the C<$osFsType> buffer [see 1826b39c5158SmillertL<Buffer Sizes> for more information]. 1827b39c5158Smillert 1828b39c5158SmillertC<$ouFsFlags> is C<[]> [for C<NULL>] or will be set to an unsigned integer 1829b39c5158Smillertwith bits set indicating properties of the file system: 1830b39c5158Smillert 1831b39c5158Smillert=over 1832b39c5158Smillert 1833b39c5158Smillert=item C<FS_CASE_IS_PRESERVED> 1834b39c5158Smillert 1835b39c5158SmillertThe file system preserves the case of file names [usually true]. 1836b39c5158SmillertThat is, it doesn't change the case of file names such as forcing 1837b39c5158Smillertthem to upper- or lower-case. 1838b39c5158Smillert 1839b39c5158Smillert=item C<FS_CASE_SENSITIVE> 1840b39c5158Smillert 1841b39c5158SmillertThe file system supports the ability to not ignore the case of file 1842b39c5158Smillertnames [but might ignore case the way you are using it]. That is, the 1843b39c5158Smillertfile system has the ability to force you to get the letter case of a 1844b39c5158Smillertfile's name exactly right to be able to open it. This is true for 1845b39c5158Smillert"NTFS" file systems, even though case in file names is usually still 1846b39c5158Smillertignored. 1847b39c5158Smillert 1848b39c5158Smillert=item C<FS_UNICODE_STORED_ON_DISK> 1849b39c5158Smillert 1850b39c5158SmillertThe file system preserves Unicode in file names [true for "NTFS"]. 1851b39c5158Smillert 1852b39c5158Smillert=item C<FS_PERSISTENT_ACLS> 1853b39c5158Smillert 1854b39c5158SmillertThe file system supports setting Access Control Lists on files [true 1855b39c5158Smillertfor "NTFS"]. 1856b39c5158Smillert 1857b39c5158Smillert=item C<FS_FILE_COMPRESSION> 1858b39c5158Smillert 1859b39c5158SmillertThe file system supports compression on a per-file basis [true for 1860b39c5158Smillert"NTFS"]. 1861b39c5158Smillert 1862b39c5158Smillert=item C<FS_VOL_IS_COMPRESSED> 1863b39c5158Smillert 1864b39c5158SmillertThe entire file system is compressed such as via "DoubleSpace". 1865b39c5158Smillert 1866b39c5158Smillert=back 1867b39c5158Smillert 1868b39c5158Smillert=item IsRecognizedPartition 1869b39c5158Smillert 1870b39c5158Smillert=item C<IsRecognizedPartition( $ivPartitionType )> 1871b39c5158Smillert 1872b39c5158SmillertTakes a partition type and returns whether that partition type is 1873b39c5158Smillertsupported under Win32. C<$ivPartitonType> is an integer value as from 1874b39c5158Smillertthe operating system byte of a hard disk's DOS-compatible partition 1875b39c5158Smillerttable [that is, a partition table for x86-based Win32, not, for 1876b39c5158Smillertexample, one used with Windows NT for Alpha processors]. For example, 1877b39c5158Smillertthe C<PartitionType> member of the C<PARTITION_INFORMATION> structure. 1878b39c5158Smillert 1879b39c5158SmillertCommon values for C<$ivPartitionType> include C<PARTITION_FAT_12==1>, 1880b39c5158SmillertC<PARTITION_FAT_16==4>, C<PARTITION_EXTENDED==5>, C<PARTITION_FAT32==0xB>. 1881b39c5158Smillert 1882b39c5158Smillert=item IsContainerPartition 1883b39c5158Smillert 1884b39c5158Smillert=item C<IsContainerPartition( $ivPartitionType )> 1885b39c5158Smillert 1886b39c5158SmillertTakes a partition type and returns whether that partition is a 1887b39c5158Smillert"container" partition that is supported under Win32, that is, whether 1888b39c5158Smillertit is an "extended" partition that can contain "logical" partitions. 1889b39c5158SmillertC<$ivPartitonType> is as for C<IsRecognizedPartition>. 1890b39c5158Smillert 1891b39c5158Smillert=item MoveFile 1892b39c5158Smillert 1893b39c5158Smillert=item C<MoveFile( $sOldName, $sNewName )> 1894b39c5158Smillert 1895b39c5158SmillertRenames a file or directory. C<$sOldName> is the name of the existing 1896b39c5158Smillertfile or directory that is to be renamed. C<$sNewName> is the new name 1897b39c5158Smillertto give the file or directory. Returns a true value if the move 1898b39c5158Smillertsucceeds. For failure, returns a false value and sets 1899b39c5158SmillertC<fileLastErorr()> and C<$^E> to the reason for the failure. 1900b39c5158Smillert 1901b39c5158SmillertFiles can be "renamed" between file systems and the file contents and 1902b39c5158Smillertsome attributes will be moved. Directories can only be renamed within 1903b39c5158Smillertone file system. If there is already a file or directory named 1904b39c5158SmillertC<$sNewName>, then C<MoveFile> will fail. 1905b39c5158Smillert 1906b39c5158Smillert=item MoveFileEx 1907b39c5158Smillert 1908b39c5158Smillert=item C<MoveFileEx( $sOldName, $sNewName, $uFlags )> 1909b39c5158Smillert 1910b39c5158SmillertRenames a file or directory. C<$sOldName> is the name of the existing 1911b39c5158Smillertfile or directory that is to be renamed. C<$sNewName> is the new name 1912b39c5158Smillertto give the file or directory. Returns a true value if the move 1913b39c5158Smillertsucceeds. For failure, returns a false value and sets 1914b39c5158SmillertC<fileLastErorr()> and C<$^E> to the reason for the failure. 1915b39c5158Smillert 1916b39c5158SmillertC<$uFlags> is an unsigned value with zero or more of the following bits set: 1917b39c5158Smillert 1918b39c5158Smillert=over 1919b39c5158Smillert 1920b39c5158Smillert=item C<MOVEFILE_REPLACE_EXISTING> 1921b39c5158Smillert 1922b39c5158SmillertIf this bit is set and a file [but not a directory] named C<$sNewName> 1923b39c5158Smillertalready exists, then it will be replaced by C<$sOldName>. If this bit 1924b39c5158Smillertis not set then C<MoveFileEx> will fail rather than replace an existing 1925b39c5158SmillertC<$sNewName>. 1926b39c5158Smillert 1927b39c5158Smillert=item C<MOVEFILE_COPY_ALLOWED> 1928b39c5158Smillert 1929b39c5158SmillertAllows files [but not directories] to be moved between file systems 1930b39c5158Smillertby copying the C<$sOldName> file data and some attributes to 1931b39c5158SmillertC<$sNewName> and then deleting C<$sOldName>. If this bit is not set 1932b39c5158Smillert[or if C<$sOldName> denotes a directory] and C<$sNewName> refers to a 1933b39c5158Smillertdifferent file system than C<$sOldName>, then C<MoveFileEx> will fail. 1934b39c5158Smillert 1935b39c5158Smillert=item C<MOVEFILE_DELAY_UNTIL_REBOOT> 1936b39c5158Smillert 1937b39c5158SmillertPreliminary verifications are made and then an entry is added to the 1938b39c5158SmillertRegistry to cause the rename [or delete] operation to be done the 1939b39c5158Smillertnext time this copy of the operating system is booted [right after 1940b39c5158Smillertany automatic file system checks have completed]. This is not 1941b39c5158Smillertsupported under Windows 95. 1942b39c5158Smillert 1943b39c5158SmillertWhen this bit is set, C<$sNewName> can be C<[]> [for C<NULL>] to 1944b39c5158Smillertindicate that C<$sOldName> should be deleted during the next boot 1945b39c5158Smillertrather than renamed. 1946b39c5158Smillert 1947b39c5158SmillertSetting both the C<MOVEFILE_COPY_ALLOWED> and 1948b39c5158SmillertC<MOVEFILE_DELAY_UNTIL_REBOOT> bits will cause C<MoveFileEx> to fail. 1949b39c5158Smillert 1950b39c5158Smillert=item C<MOVEFILE_WRITE_THROUGH> 1951b39c5158Smillert 1952b39c5158SmillertEnsures that C<MoveFileEx> won't return until the operation has 1953b39c5158Smillertfinished and been flushed to disk. This is not supported under 1954b39c5158SmillertWindows 95. Only affects file renames to another file system, 1955b39c5158Smillertforcing a buffer flush at the end of the copy operation. 1956b39c5158Smillert 1957b39c5158Smillert=back 1958b39c5158Smillert 1959b39c5158Smillert=item OsFHandleOpen 1960b39c5158Smillert 1961b39c5158Smillert=item C<OsFHandleOpen( FILE, $hNativeHandle, $sMode )> 1962b39c5158Smillert 1963b39c5158SmillertOpens a Perl file handle based on an already open Win32 native 1964b39c5158Smillertfile handle [much like C's C<fdopen()> does with a file descriptor]. 1965b39c5158SmillertReturns a true value if the open operation succeeded. For failure, 1966b39c5158Smillertreturns a false value and sets C<$!> [and possibly C<fileLastError()> 1967b39c5158Smillertand C<$^E>] to the reason for the failure. 1968b39c5158Smillert 1969b39c5158SmillertC<FILE> is a Perl file handle [in any of the supported forms, a 1970b39c5158Smillertbareword, a string, a typeglob, or a reference to a typeglob] that 1971b39c5158Smillertwill be opened. If C<FILE> is already open, it will automatically 1972b39c5158Smillertbe closed before it is reopened. 1973b39c5158Smillert 1974b39c5158SmillertC<$hNativeHandle> is an open Win32 native file handle, probably the 1975b39c5158Smillertreturn value from C<CreateFile> or C<createFile>. 1976b39c5158Smillert 1977b39c5158SmillertC<$sMode> is string of zero or more letters from C<"rwatb">. These 1978b39c5158Smillertare translated into a combination C<O_RDONLY> [C<"r">], C<O_WRONLY> 1979b39c5158Smillert[C<"w">], C<O_RDWR> [C<"rw">], C<O_APPEND> [C<"a">], C<O_TEXT> 1980b39c5158Smillert[C<"t">], and C<O_BINARY> [C<"b">] flags [see the L<Fcntl> module] 1981b39c5158Smillertthat is passed to C<OsFHandleOpenFd>. Currently only C<O_APPEND> 1982b39c5158Smillertand C<O_TEXT> have any significance. 1983b39c5158Smillert 1984b39c5158SmillertAlso, a C<"r"> and/or C<"w"> in C<$sMode> is used to decide how the 1985b39c5158Smillertfile descriptor is converted into a Perl file handle, even though this 1986b39c5158Smillertdoesn't appear to make a difference. One of the following is used: 1987b39c5158Smillert 1988b39c5158Smillert open( FILE, "<&=".$ivFd ) # "r" w/o "w" 1989b39c5158Smillert open( FILE, ">&=".$ivFd ) # "w" w/o "r" 1990b39c5158Smillert open( FILE, "+<&=".$ivFd ) # both "r" and "w" 1991b39c5158Smillert 1992b39c5158SmillertC<OsFHandleOpen> eventually calls the Win32-specific C routine 1993b39c5158SmillertC<_open_osfhandle()> or Perl's "improved" version called 1994b39c5158SmillertC<win32_open_osfhandle()>. Prior to Perl5.005, C's 1995b39c5158SmillertC<_open_osfhandle()> is called which will fail if 1996b39c5158SmillertC<GetFileType($hNativeHandle)> would return C<FILE_TYPE_UNKNOWN>. For 1997b39c5158SmillertPerl5.005 and later, C<OsFHandleOpen> calls C<win32_open_osfhandle()> 1998b39c5158Smillertfrom the Perl DLL which doesn't have this restriction. 1999b39c5158Smillert 2000b39c5158Smillert=item OsFHandleOpenFd 2001b39c5158Smillert 2002b39c5158Smillert=item C<$ivFD= OsFHandleOpenFd( $hNativeHandle, $uMode )> 2003b39c5158Smillert 2004b39c5158SmillertOpens a file descriptor [C<$ivFD>] based on an already open Win32 2005b39c5158Smillertnative file handle, C<$hNativeHandle>. This just calls the 2006b39c5158SmillertWin32-specific C routine C<_open_osfhandle()> or Perl's "improved" 2007b39c5158Smillertversion called C<win32_open_osfhandle()>. Prior to Perl5.005 and in Cygwin 2008b39c5158SmillertPerl, C's C<_open_osfhandle()> is called which will fail if 2009b39c5158SmillertC<GetFileType($hNativeHandle)> would return C<FILE_TYPE_UNKNOWN>. For 2010b39c5158SmillertPerl5.005 and later, C<OsFHandleOpenFd> calls C<win32_open_osfhandle()> from 2011b39c5158Smillertthe Perl DLL which doesn't have this restriction. 2012b39c5158Smillert 2013b39c5158SmillertC<$uMode> the logical combination of zero or more C<O_*> constants 2014b39c5158Smillertexported by the C<Fcntl> module. Currently only C<O_APPEND> and 2015b39c5158SmillertC<O_TEXT> have any significance. 2016b39c5158Smillert 2017b39c5158SmillertC<$ivFD> will be non-negative if the open operation was successful. 2018b39c5158SmillertFor failure, C<-1> is returned and C<$!> [and possibly 2019b39c5158SmillertC<fileLastError()> and C<$^E>] is set to the reason for the failure. 2020b39c5158Smillert 2021b39c5158Smillert=item QueryDosDevice 2022b39c5158Smillert 2023b39c5158Smillert=item C<$olTargetLen= QueryDosDevice( $sDosDeviceName, $osTargetPath, $lTargetBuf )> 2024b39c5158Smillert 2025b39c5158SmillertLooks up the definition of a given "DOS" device name, yielding the 2026b39c5158Smillertactive Windows NT native device name along with any currently dormant 2027b39c5158Smillertdefinitions. 2028b39c5158Smillert 2029b39c5158SmillertC<$sDosDeviceName> is the name of the "DOS" device whose definitions 2030b39c5158Smillertwe want. For example, C<"C:">, C<"COM1">, or C<"PhysicalDrive0">. 2031b39c5158SmillertIf C<$sDosDeviceName> is C<[]> [for C<NULL>], the list of all DOS 2032b39c5158Smillertdevice names is returned instead. 2033b39c5158Smillert 2034b39c5158SmillertC<$osTargetPath> will be assigned a string containing the list of 2035b39c5158Smillertdefinitions. The definitions are each C<'\0'>-terminate and are 2036b39c5158Smillertconcatenated into the string, most recent first, with an extra C<'\0'> 2037b39c5158Smillertat the end of the whole string [see C<GetLogicalDriveStrings> for 2038b39c5158Smillerta sample of this format]. 2039b39c5158Smillert 2040b39c5158SmillertC<$lTargetBuf> is the size [in bytes] of the buffer to allocate for 2041b39c5158SmillertC<$osTargetPath>. See L<Buffer Sizes> for more information. 2042b39c5158Smillert 2043b39c5158SmillertC<$olTargetLen> is set to the number of bytes written to 2044b39c5158SmillertC<$osTargetPath> but you can also use C<length($osTargetPath)> 2045b39c5158Smillertto determine this. 2046b39c5158Smillert 2047b39c5158SmillertFor failure, C<0> is returned and C<fileLastError()> and C<$^E> are 2048b39c5158Smillertset to the reason for the failure. 2049b39c5158Smillert 2050b39c5158Smillert=item ReadFile 2051b39c5158Smillert 2052b39c5158Smillert=item C<ReadFile( $hFile, $opBuffer, $lBytes, $olBytesRead, $pOverlapped )> 2053b39c5158Smillert 2054b39c5158SmillertReads bytes from a file or file-like device. Returns a true value if 2055b39c5158Smillertthe read operation was successful. For failure, returns a false value 2056b39c5158Smillertand sets C<fileLastError()> and C<$^E> for the reason for the failure. 2057b39c5158Smillert 2058b39c5158SmillertC<$hFile> is a Win32 native file handle that is already open to the 2059b39c5158Smillertfile or device to read from. 2060b39c5158Smillert 2061b39c5158SmillertC<$opBuffer> will be set to a string containing the bytes read. 2062b39c5158Smillert 2063b39c5158SmillertC<$lBytes> is the number of bytes you would like to read. 2064b39c5158SmillertC<$opBuffer> is automatically initialized to have a buffer large 2065b39c5158Smillertenough to hold that many bytes. Unlike other buffer sizes, C<$lBytes> 2066b39c5158Smillertdoes not need to have a C<"="> prepended to it to prevent a larger 2067b39c5158Smillertvalue to be passed to the underlying Win32 C<ReadFile> API. However, 2068b39c5158Smillerta leading C<"="> will be silently ignored, even if Perl warnings are 2069b39c5158Smillertenabled. 2070b39c5158Smillert 2071b39c5158SmillertIf C<$olBytesRead> is not C<[]>, it will be set to the actual number 2072b39c5158Smillertof bytes read, though C<length($opBuffer)> can also be used to 2073b39c5158Smillertdetermine this. 2074b39c5158Smillert 2075b39c5158SmillertC<$pOverlapped> is C<[]> or is a C<OVERLAPPED> structure packed 2076b39c5158Smillertinto a string. This is only useful if C<$hFile> was opened with 2077b39c5158Smillertthe C<FILE_FLAG_OVERLAPPED> flag set. 2078b39c5158Smillert 2079b39c5158Smillert=item SetErrorMode 2080b39c5158Smillert 2081b39c5158Smillert=item C<$uOldMode= SetErrorMode( $uNewMode )> 2082b39c5158Smillert 2083b39c5158SmillertSets the mode controlling system error handling B<and> returns the 2084b39c5158Smillertprevious mode value. Both C<$uOldMode> and C<$uNewMode> will have 2085b39c5158Smillertzero or more of the following bits set: 2086b39c5158Smillert 2087b39c5158Smillert=over 2088b39c5158Smillert 2089b39c5158Smillert=item C<SEM_FAILCRITICALERRORS> 2090b39c5158Smillert 2091b39c5158SmillertIf set, indicates that when a critical error is encountered, the call 2092b39c5158Smillertthat triggered the error fails immediately. Normally this bit is not 2093b39c5158Smillertset, which means that a critical error causes a dialogue box to appear 2094b39c5158Smillertnotifying the desktop user that some application has triggered a 2095b39c5158Smillertcritical error. The dialogue box allows the desktop user to decide 2096b39c5158Smillertwhether the critical error is returned to the process, is ignored, or 2097b39c5158Smillertthe offending operation is retried. 2098b39c5158Smillert 2099b39c5158SmillertThis affects the C<CreateFile> and C<GetVolumeInformation> calls. 2100b39c5158Smillert 2101b39c5158SmillertSetting this bit is useful for allowing you to check whether a floppy 2102b39c5158Smillertdiskette is in the floppy drive. 2103b39c5158Smillert 2104b39c5158Smillert=item C<SEM_NOALIGNMENTFAULTEXCEPT> 2105b39c5158Smillert 2106b39c5158SmillertIf set, this causes memory access misalignment faults to be 2107b39c5158Smillertautomatically fixed in a manner invisible to the process. This flag 2108b39c5158Smillertis ignored on x86-based versions of Windows NT. This flag is not 2109b39c5158Smillertsupported on Windows 95. 2110b39c5158Smillert 2111b39c5158Smillert=item C<SEM_NOGPFAULTERRORBOX> 2112b39c5158Smillert 2113b39c5158SmillertIf set, general protection faults do not generate a dialogue box but 2114b39c5158Smillertcan instead be handled by the process via an exception handler. This 2115b39c5158Smillertbit should not be set by programs that don't know how to handle such 2116b39c5158Smillertfaults. 2117b39c5158Smillert 2118b39c5158Smillert=item C<SEM_NOOPENFILEERRORBOX> 2119b39c5158Smillert 2120b39c5158SmillertIf set, then when an attempt to continue reading from or writing to 2121b39c5158Smillertan already open file [usually on a removable medium like a floppy 2122b39c5158Smillertdiskette] finds the file no longer available, the call will 2123b39c5158Smillertimmediately fail. Normally this bit is not set, which means that 2124b39c5158Smillertinstead a dialogue box will appear notifying the desktop user that 2125b39c5158Smillertsome application has run into this problem. The dialogue box allows 2126b39c5158Smillertthe desktop user to decide whether the failure is returned to the 2127b39c5158Smillertprocess, is ignored, or the offending operation is retried. 2128b39c5158Smillert 2129b39c5158SmillertThis affects the C<ReadFile> and C<WriteFile> calls. 2130b39c5158Smillert 2131b39c5158Smillert=back 2132b39c5158Smillert 2133b39c5158Smillert=item setFilePointer 2134b39c5158Smillert 2135b39c5158Smillert=item C<$uNewPos = setFilePointer( $hFile, $ivOffset, $uFromWhere )> 2136b39c5158Smillert 2137b39c5158SmillertThis is a perl-friendly wrapper for the SetFilePointer API (below). 2138b39c5158SmillertC<$ivOffset> can be a 64 bit integer or C<Math::BigInt> object if your Perl 2139b39c5158Smillertdoesn't have 64 bit integers. The return value is the new offset and will 2140b39c5158Smillertlikewise be a 64 bit integer or a C<Math::BigInt> object. 2141b39c5158Smillert 2142b39c5158Smillert=item SetFilePointer 2143b39c5158Smillert 2144b39c5158Smillert=item C<$uNewPos = SetFilePointer( $hFile, $ivOffset, $ioivOffsetHigh, $uFromWhere )> 2145b39c5158Smillert 2146b39c5158SmillertThe native Win32 version of C<seek()>. C<SetFilePointer> sets the 2147b39c5158Smillertposition within a file where the next read or write operation will 2148b39c5158Smillertstart from. 2149b39c5158Smillert 2150b39c5158SmillertC<$hFile> is a Win32 native file handle. 2151b39c5158Smillert 2152b39c5158SmillertC<$uFromWhere> is either C<FILE_BEGIN>, C<FILE_CURRENT>, or 2153b39c5158SmillertC<FILE_END>, indicating that the new file position is being specified 2154b39c5158Smillertrelative to the beginning of the file, the current file pointer, or 2155b39c5158Smillertthe end of the file, respectively. 2156b39c5158Smillert 2157b39c5158SmillertC<$ivOffset> is [if C<$ioivOffsetHigh> is C<[]>] the offset [in bytes] 2158b39c5158Smillertto the new file position from the position specified via 2159b39c5158SmillertC<$uFromWhere>. If C<$ioivOffsetHigh> is not C<[]>, then C<$ivOffset> 2160b39c5158Smillertis converted to an unsigned value to be used as the low-order 4 bytes 2161b39c5158Smillertof the offset. 2162b39c5158Smillert 2163b39c5158SmillertC<$ioivOffsetHigh> can be C<[]> [for C<NULL>] to indicate that you are 2164b39c5158Smillertonly specifying a 4-byte offset and the resulting file position will 2165b39c5158Smillertbe 0xFFFFFFFE or less [just under 4GB]. Otherwise C<$ioivOfffsetHigh> 2166b39c5158Smillertstarts out with the high-order 4 bytes [signed] of the offset and gets 2167b39c5158Smillertset to the [unsigned] high-order 4 bytes of the resulting file position. 2168b39c5158Smillert 2169b39c5158SmillertThe underlying C<SetFilePointer> returns C<0xFFFFFFFF> to indicate 2170b39c5158Smillertfailure, but if C<$ioivOffsetHigh> is not C<[]>, you would also have 2171b39c5158Smillertto check C<$^E> to determine whether C<0xFFFFFFFF> indicates an error 2172b39c5158Smillertor not. C<Win32API::File::SetFilePointer> does this checking for you 2173b39c5158Smillertand returns a false value if and only if the underlying 2174b39c5158SmillertC<SetFilePointer> failed. For this reason, C<$uNewPos> is set to 2175b39c5158SmillertC<"0 but true"> if you set the file pointer to the beginning of the 2176b39c5158Smillertfile [or any position with 0 for the low-order 4 bytes]. 2177b39c5158Smillert 2178b39c5158SmillertSo the return value will be true if the seek operation was successful. 2179b39c5158SmillertFor failure, a false value is returned and C<fileLastError()> and 2180b39c5158SmillertC<$^E> are set to the reason for the failure. 2181b39c5158Smillert 2182b39c5158Smillert=item SetHandleInformation 2183b39c5158Smillert 2184b39c5158Smillert=item C<SetHandleInformation( $hObject, $uMask, $uFlags )> 2185b39c5158Smillert 2186b39c5158SmillertSets the flags associated with a Win32 native file handle or object 2187b39c5158Smillerthandle. Returns a true value if the operation was successful. For 2188b39c5158Smillertfailure, returns a false value and sets C<fileLastError()> and C<$^E> 2189b39c5158Smillertfor the reason for the failure. 2190b39c5158Smillert 2191b39c5158SmillertC<$hObject> is an open Win32 native file handle or an open Win32 native 2192b39c5158Smillerthandle to some other type of object. 2193b39c5158Smillert 2194b39c5158SmillertC<$uMask> is an unsigned value having one or more of the bits 2195b39c5158SmillertC<HANDLE_FLAG_INHERIT> and C<HANDLE_FLAG_PROTECT_FROM_CLOSE> set. 2196b39c5158SmillertOnly bits set in C<$uMask> will be modified by C<SetHandleInformation>. 2197b39c5158Smillert 2198b39c5158SmillertC<$uFlags> is an unsigned value having zero or more of the bits 2199b39c5158SmillertC<HANDLE_FLAG_INHERIT> and C<HANDLE_FLAG_PROTECT_FROM_CLOSE> set. 2200b8851fccSafresh1For each bit set in C<$uMask>, the corresponding bit in the handle's 2201898184e3Ssthenflags is set to the value of the corresponding bit in C<$uFlags>. 2202b39c5158Smillert 2203b39c5158SmillertIf C<$uOldFlags> were the value of the handle's flags before the 2204b39c5158Smillertcall to C<SetHandleInformation>, then the value of the handle's 2205b39c5158Smillertflags afterward would be: 2206b39c5158Smillert 2207b39c5158Smillert ( $uOldFlags & ~$uMask ) | ( $uFlags & $uMask ) 2208b39c5158Smillert 2209b39c5158Smillert[at least as far as the C<HANDLE_FLAG_INHERIT> and 2210b39c5158SmillertC<HANDLE_FLAG_PROTECT_FROM_CLOSE> bits are concerned.] 2211b39c5158Smillert 2212b39c5158SmillertSee the C<":HANDLE_FLAG_"> export class for the meanings of these bits. 2213b39c5158Smillert 2214b39c5158Smillert=item WriteFile 2215b39c5158Smillert 2216b39c5158Smillert=item C<WriteFile( $hFile, $pBuffer, $lBytes, $ouBytesWritten, $pOverlapped )> 2217b39c5158Smillert 2218b39c5158SmillertWrite bytes to a file or file-like device. Returns a true value if 2219b39c5158Smillertthe operation was successful. For failure, returns a false value and 2220b39c5158Smillertsets C<fileLastError()> and C<$^E> for the reason for the failure. 2221b39c5158Smillert 2222b39c5158SmillertC<$hFile> is a Win32 native file handle that is already open to the 2223b39c5158Smillertfile or device to be written to. 2224b39c5158Smillert 2225b39c5158SmillertC<$pBuffer> is a string containing the bytes to be written. 2226b39c5158Smillert 2227b39c5158SmillertC<$lBytes> is the number of bytes you would like to write. If 2228b39c5158SmillertC<$pBuffer> is not at least C<$lBytes> long, C<WriteFile> croaks. You 2229b39c5158Smillertcan specify C<0> for C<$lBytes> to write C<length($pBuffer)> bytes. 2230b39c5158SmillertA leading C<"="> on C<$lBytes> will be silently ignored, even if Perl 2231b39c5158Smillertwarnings are enabled. 2232b39c5158Smillert 2233b39c5158SmillertC<$ouBytesWritten> will be set to the actual number of bytes written 2234b39c5158Smillertunless you specify it as C<[]>. 2235b39c5158Smillert 2236b39c5158SmillertC<$pOverlapped> is C<[]> or is an C<OVERLAPPED> structure packed 2237b39c5158Smillertinto a string. This is only useful if C<$hFile> was opened with 2238b39c5158Smillertthe C<FILE_FLAG_OVERLAPPED> flag set. 2239b39c5158Smillert 2240b39c5158Smillert=back 2241b39c5158Smillert 2242b39c5158Smillert=item C<":FuncA"> 2243b39c5158Smillert 2244b39c5158SmillertThe ASCII-specific functions. Each of these is just the same as the 2245b39c5158Smillertversion without the trailing "A". 2246b39c5158Smillert 2247b39c5158Smillert CopyFileA 2248b39c5158Smillert CreateFileA 2249b39c5158Smillert DefineDosDeviceA 2250b39c5158Smillert DeleteFileA 2251b39c5158Smillert GetDriveTypeA 2252b39c5158Smillert GetFileAttributesA 2253b39c5158Smillert GetLogicalDriveStringsA 2254b39c5158Smillert GetVolumeInformationA 2255b39c5158Smillert MoveFileA 2256b39c5158Smillert MoveFileExA 2257b39c5158Smillert QueryDosDeviceA 2258b39c5158Smillert 2259b39c5158Smillert=item C<":FuncW"> 2260b39c5158Smillert 2261b39c5158SmillertThe wide-character-specific (Unicode) functions. Each of these is 2262b39c5158Smillertjust the same as the version without the trailing "W" except that 2263b39c5158Smillertstrings are expected in Unicode and some lengths are measured as 2264b39c5158Smillertnumber of C<WCHAR>s instead of number of bytes, as indicated below. 2265b39c5158Smillert 2266b39c5158Smillert=over 2267b39c5158Smillert 2268b39c5158Smillert=item CopyFileW 2269b39c5158Smillert 2270b39c5158Smillert=item C<CopyFileW( $swOldFileName, $swNewFileName, $bFailIfExists )> 2271b39c5158Smillert 2272b39c5158SmillertC<$swOldFileName> and C<$swNewFileName> are Unicode strings. 2273b39c5158Smillert 2274b39c5158Smillert=item CreateFileW 2275b39c5158Smillert 2276b39c5158Smillert=item C<$hObject= CreateFileW( $swPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )> 2277b39c5158Smillert 2278b39c5158SmillertC<$swPath> is Unicode. 2279b39c5158Smillert 2280b39c5158Smillert=item DefineDosDeviceW 2281b39c5158Smillert 2282b39c5158Smillert=item C<DefineDosDeviceW( $uFlags, $swDosDeviceName, $swTargetPath )> 2283b39c5158Smillert 2284b39c5158SmillertC<$swDosDeviceName> and C<$swTargetPath> are Unicode. 2285b39c5158Smillert 2286b39c5158Smillert=item DeleteFileW 2287b39c5158Smillert 2288b39c5158Smillert=item C<DeleteFileW( $swFileName )> 2289b39c5158Smillert 2290b39c5158SmillertC<$swFileName> is Unicode. 2291b39c5158Smillert 2292b39c5158Smillert=item GetDriveTypeW 2293b39c5158Smillert 2294b39c5158Smillert=item C<$uDriveType= GetDriveTypeW( $swRootPath )> 2295b39c5158Smillert 2296b39c5158SmillertC<$swRootPath> is Unicode. 2297b39c5158Smillert 2298b39c5158Smillert=item GetFileAttributesW 2299b39c5158Smillert 2300b39c5158Smillert=item C<$uAttrs= GetFileAttributesW( $swPath )> 2301b39c5158Smillert 2302b39c5158SmillertC<$swPath> is Unicode. 2303b39c5158Smillert 2304b39c5158Smillert=item GetLogicalDriveStringsW 2305b39c5158Smillert 2306b39c5158Smillert=item C<$olwOutLength= GetLogicalDriveStringsW( $lwBufSize, $oswBuffer )> 2307b39c5158Smillert 2308b39c5158SmillertUnicode is stored in C<$oswBuffer>. C<$lwBufSize> and C<$olwOutLength> 2309b39c5158Smillertare measured as number of C<WCHAR>s. 2310b39c5158Smillert 2311b39c5158Smillert=item GetVolumeInformationW 2312b39c5158Smillert 2313b39c5158Smillert=item C<GetVolumeInformationW( $swRootPath, $oswVolName, $lwVolName, $ouSerialNum, $ouMaxNameLen, $ouFsFlags, $oswFsType, $lwFsType )> 2314b39c5158Smillert 2315b39c5158SmillertC<$swRootPath> is Unicode and Unicode is written to C<$oswVolName> and 2316b39c5158SmillertC<$oswFsType>. C<$lwVolName> and C<$lwFsType> are measures as number 2317b39c5158Smillertof C<WCHAR>s. 2318b39c5158Smillert 2319b39c5158Smillert=item MoveFileW 2320b39c5158Smillert 2321b39c5158Smillert=item C<MoveFileW( $swOldName, $swNewName )> 2322b39c5158Smillert 2323b39c5158SmillertC<$swOldName> and C<$swNewName> are Unicode. 2324b39c5158Smillert 2325b39c5158Smillert=item MoveFileExW 2326b39c5158Smillert 2327b39c5158Smillert=item C<MoveFileExW( $swOldName, $swNewName, $uFlags )> 2328b39c5158Smillert 2329b39c5158SmillertC<$swOldName> and C<$swNewName> are Unicode. 2330b39c5158Smillert 2331b39c5158Smillert=item QueryDosDeviceW 2332b39c5158Smillert 2333b39c5158Smillert=item C<$olwTargetLen= QueryDosDeviceW( $swDeviceName, $oswTargetPath, $lwTargetBuf )> 2334b39c5158Smillert 2335b39c5158SmillertC<$swDeviceName> is Unicode and Unicode is written to 2336b39c5158SmillertC<$oswTargetPath>. C<$lwTargetBuf> and C<$olwTargetLen> are measured 2337b39c5158Smillertas number of C<WCHAR>s. 2338b39c5158Smillert 2339b39c5158Smillert=back 2340b39c5158Smillert 2341b39c5158Smillert=item C<":Misc"> 2342b39c5158Smillert 2343b39c5158SmillertMiscellaneous constants. Used for the C<$uCreate> argument of 2344b39c5158SmillertC<CreateFile> or the C<$uFromWhere> argument of C<SetFilePointer>. 2345b39c5158SmillertPlus C<INVALID_HANDLE_VALUE>, which you usually won't need to check 2346b39c5158Smillertfor since most routines translate it into a false value. 2347b39c5158Smillert 2348b39c5158Smillert CREATE_ALWAYS CREATE_NEW OPEN_ALWAYS 2349b39c5158Smillert OPEN_EXISTING TRUNCATE_EXISTING INVALID_HANDLE_VALUE 2350b39c5158Smillert FILE_BEGIN FILE_CURRENT FILE_END 2351b39c5158Smillert 2352b39c5158Smillert=item C<":DDD_"> 2353b39c5158Smillert 2354b39c5158SmillertConstants for the C<$uFlags> argument of C<DefineDosDevice>. 2355b39c5158Smillert 2356b39c5158Smillert DDD_EXACT_MATCH_ON_REMOVE 2357b39c5158Smillert DDD_RAW_TARGET_PATH 2358b39c5158Smillert DDD_REMOVE_DEFINITION 2359b39c5158Smillert 2360b39c5158Smillert=item C<":DRIVE_"> 2361b39c5158Smillert 2362b39c5158SmillertConstants returned by C<GetDriveType>. 2363b39c5158Smillert 2364b39c5158Smillert DRIVE_UNKNOWN DRIVE_NO_ROOT_DIR DRIVE_REMOVABLE 2365b39c5158Smillert DRIVE_FIXED DRIVE_REMOTE DRIVE_CDROM 2366b39c5158Smillert DRIVE_RAMDISK 2367b39c5158Smillert 2368b39c5158Smillert=item C<":FILE_"> 2369b39c5158Smillert 2370b39c5158SmillertSpecific types of access to files that can be requested via the 2371b39c5158SmillertC<$uAccess> argument to C<CreateFile>. 2372b39c5158Smillert 2373b39c5158Smillert FILE_READ_DATA FILE_LIST_DIRECTORY 2374b39c5158Smillert FILE_WRITE_DATA FILE_ADD_FILE 2375b39c5158Smillert FILE_APPEND_DATA FILE_ADD_SUBDIRECTORY 2376b39c5158Smillert FILE_CREATE_PIPE_INSTANCE FILE_READ_EA 2377b39c5158Smillert FILE_WRITE_EA FILE_EXECUTE 2378b39c5158Smillert FILE_TRAVERSE FILE_DELETE_CHILD 2379b39c5158Smillert FILE_READ_ATTRIBUTES FILE_WRITE_ATTRIBUTES 2380b39c5158Smillert FILE_ALL_ACCESS FILE_GENERIC_READ 2381b39c5158Smillert FILE_GENERIC_WRITE FILE_GENERIC_EXECUTE )], 2382b39c5158Smillert 2383b39c5158Smillert=item C<":FILE_ATTRIBUTE_"> 2384b39c5158Smillert 2385b39c5158SmillertFile attribute constants. Returned by C<attrLetsToBits> and used in 2386b39c5158Smillertthe C<$uFlags> argument to C<CreateFile>. 2387b39c5158Smillert 2388b39c5158Smillert FILE_ATTRIBUTE_ARCHIVE FILE_ATTRIBUTE_COMPRESSED 2389b39c5158Smillert FILE_ATTRIBUTE_HIDDEN FILE_ATTRIBUTE_NORMAL 2390b39c5158Smillert FILE_ATTRIBUTE_OFFLINE FILE_ATTRIBUTE_READONLY 2391b39c5158Smillert FILE_ATTRIBUTE_SYSTEM FILE_ATTRIBUTE_TEMPORARY 2392b39c5158Smillert 2393b39c5158SmillertIn addition, C<GetFileAttributes> can return these constants (or 2394b39c5158SmillertINVALID_FILE_ATTRIBUTES in case of an error). 2395b39c5158Smillert 2396b39c5158Smillert FILE_ATTRIBUTE_DEVICE FILE_ATTRIBUTE_DIRECTORY 2397b39c5158Smillert FILE_ATTRIBUTE_ENCRYPTED FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 2398b39c5158Smillert FILE_ATTRIBUTE_REPARSE_POINT FILE_ATTRIBUTE_SPARSE_FILE 2399b39c5158Smillert 2400b39c5158Smillert=item C<":FILE_FLAG_"> 2401b39c5158Smillert 2402b39c5158SmillertFile option flag constants. Used in the C<$uFlags> argument to 2403b39c5158SmillertC<CreateFile>. 2404b39c5158Smillert 2405b39c5158Smillert FILE_FLAG_BACKUP_SEMANTICS FILE_FLAG_DELETE_ON_CLOSE 2406b39c5158Smillert FILE_FLAG_NO_BUFFERING FILE_FLAG_OVERLAPPED 2407b39c5158Smillert FILE_FLAG_POSIX_SEMANTICS FILE_FLAG_RANDOM_ACCESS 2408b39c5158Smillert FILE_FLAG_SEQUENTIAL_SCAN FILE_FLAG_WRITE_THROUGH 2409b39c5158Smillert FILE_FLAG_OPEN_REPARSE_POINT 2410b39c5158Smillert 2411b39c5158Smillert=item C<":FILE_SHARE_"> 2412b39c5158Smillert 2413b39c5158SmillertFile sharing constants. Used in the C<$uShare> argument to 2414b39c5158SmillertC<CreateFile>. 2415b39c5158Smillert 2416b39c5158Smillert FILE_SHARE_DELETE FILE_SHARE_READ FILE_SHARE_WRITE 2417b39c5158Smillert 2418b39c5158Smillert=item C<":FILE_TYPE_"> 2419b39c5158Smillert 2420b39c5158SmillertFile type constants. Returned by C<GetFileType>. 2421b39c5158Smillert 2422b39c5158Smillert FILE_TYPE_CHAR FILE_TYPE_DISK 2423b39c5158Smillert FILE_TYPE_PIPE FILE_TYPE_UNKNOWN 2424b39c5158Smillert 2425b39c5158Smillert=item C<":FS_"> 2426b39c5158Smillert 2427b39c5158SmillertFile system characteristics constants. Placed in the C<$ouFsFlags> 2428b39c5158Smillertargument to C<GetVolumeInformation>. 2429b39c5158Smillert 2430b39c5158Smillert FS_CASE_IS_PRESERVED FS_CASE_SENSITIVE 2431b39c5158Smillert FS_UNICODE_STORED_ON_DISK FS_PERSISTENT_ACLS 2432b39c5158Smillert FS_FILE_COMPRESSION FS_VOL_IS_COMPRESSED 2433b39c5158Smillert 2434b39c5158Smillert=item C<":HANDLE_FLAG_"> 2435b39c5158Smillert 2436b39c5158SmillertFlag bits modifying the behavior of an object handle and accessed via 2437b39c5158SmillertC<GetHandleInformation> and C<SetHandleInformation>. 2438b39c5158Smillert 2439b39c5158Smillert=over 2440b39c5158Smillert 2441b39c5158Smillert=item HANDLE_FLAG_INHERIT 2442b39c5158Smillert 2443b39c5158SmillertIf this bit is set, then children of this process who inherit handles 2444b39c5158Smillert[that is, processes created by calls to the Win32 C<CreateProcess> API 2445b39c5158Smillertwith the C<bInheritHandles> parameter specified as C<TRUE>], will inherit 2446b39c5158Smillertthis particular object handle. 2447b39c5158Smillert 2448b39c5158Smillert=item HANDLE_FLAG_PROTECT_FROM_CLOSE 2449b39c5158Smillert 2450b39c5158SmillertIf this bit is set, then calls to C<CloseHandle> against this handle 2451b39c5158Smillertwill be ignored, leaving the handle open and usable. 2452b39c5158Smillert 2453b39c5158Smillert=back 2454b39c5158Smillert 2455b39c5158Smillert=item C<":IOCTL_STORAGE_"> 2456b39c5158Smillert 2457b39c5158SmillertI/O control operations for generic storage devices. Used in the 2458b39c5158SmillertC<$uIoControlCode> argument to C<DeviceIoControl>. Includes 2459b39c5158SmillertC<IOCTL_STORAGE_CHECK_VERIFY>, C<IOCTL_STORAGE_MEDIA_REMOVAL>, 2460b39c5158SmillertC<IOCTL_STORAGE_EJECT_MEDIA>, C<IOCTL_STORAGE_LOAD_MEDIA>, 2461b39c5158SmillertC<IOCTL_STORAGE_RESERVE>, C<IOCTL_STORAGE_RELEASE>, 2462b39c5158SmillertC<IOCTL_STORAGE_FIND_NEW_DEVICES>, and 2463b39c5158SmillertC<IOCTL_STORAGE_GET_MEDIA_TYPES>. 2464b39c5158Smillert 2465b39c5158Smillert=over 2466b39c5158Smillert 2467b39c5158Smillert=item C<IOCTL_STORAGE_CHECK_VERIFY> 2468b39c5158Smillert 2469b39c5158SmillertVerify that a device's media is accessible. C<$pInBuf> and C<$opOutBuf> 2470b39c5158Smillertshould both be C<[]>. If C<DeviceIoControl> returns a true value, then 2471b39c5158Smillertthe media is currently accessible. 2472b39c5158Smillert 2473b39c5158Smillert=item C<IOCTL_STORAGE_MEDIA_REMOVAL> 2474b39c5158Smillert 2475b39c5158SmillertAllows the device's media to be locked or unlocked. C<$opOutBuf> should 2476b39c5158Smillertbe C<[]>. C<$pInBuf> should be a C<PREVENT_MEDIA_REMOVAL> data structure, 2477898184e3Ssthenwhich is simply an integer containing a boolean value: 2478b39c5158Smillert 2479b39c5158Smillert $pInBuf= pack( "i", $bPreventMediaRemoval ); 2480b39c5158Smillert 2481b39c5158Smillert=item C<IOCTL_STORAGE_EJECT_MEDIA> 2482b39c5158Smillert 2483b39c5158SmillertRequests that the device eject the media. C<$pInBuf> and C<$opOutBuf> 2484b39c5158Smillertshould both be C<[]>. 2485b39c5158Smillert 2486b39c5158Smillert=item C<IOCTL_STORAGE_LOAD_MEDIA> 2487b39c5158Smillert 2488b39c5158SmillertRequests that the device load the media. C<$pInBuf> and C<$opOutBuf> 2489b39c5158Smillertshould both be C<[]>. 2490b39c5158Smillert 2491b39c5158Smillert=item C<IOCTL_STORAGE_RESERVE> 2492b39c5158Smillert 2493b39c5158SmillertRequests that the device be reserved. C<$pInBuf> and C<$opOutBuf> 2494b39c5158Smillertshould both be C<[]>. 2495b39c5158Smillert 2496b39c5158Smillert=item C<IOCTL_STORAGE_RELEASE> 2497b39c5158Smillert 2498b39c5158SmillertReleases a previous device reservation. C<$pInBuf> and C<$opOutBuf> 2499b39c5158Smillertshould both be C<[]>. 2500b39c5158Smillert 2501b39c5158Smillert=item C<IOCTL_STORAGE_FIND_NEW_DEVICES> 2502b39c5158Smillert 2503b39c5158SmillertNo documentation on this IOCTL operation was found. 2504b39c5158Smillert 2505b39c5158Smillert=item C<IOCTL_STORAGE_GET_MEDIA_TYPES> 2506b39c5158Smillert 2507b39c5158SmillertRequests information about the type of media supported by the device. 2508b39c5158SmillertC<$pInBuf> should be C<[]>. C<$opOutBuf> will be set to contain a 2509b39c5158Smillertvector of C<DISK_GEOMETRY> data structures, which can be decoded via: 2510b39c5158Smillert 2511b39c5158Smillert # Calculate the number of DISK_GEOMETRY structures returned: 2512b39c5158Smillert my $cStructs= length($opOutBuf)/(4+4+4+4+4+4); 2513b39c5158Smillert my @fields= unpack( "L l I L L L" x $cStructs, $opOutBuf ) 2514b39c5158Smillert my( @ucCylsLow, @ivcCylsHigh, @uMediaType, @uTracksPerCyl, 2515b39c5158Smillert @uSectsPerTrack, @uBytesPerSect )= (); 2516b39c5158Smillert while( @fields ) { 2517b39c5158Smillert push( @ucCylsLow, unshift @fields ); 2518b39c5158Smillert push( @ivcCylsHigh, unshift @fields ); 2519b39c5158Smillert push( @uMediaType, unshift @fields ); 2520b39c5158Smillert push( @uTracksPerCyl, unshift @fields ); 2521b39c5158Smillert push( @uSectsPerTrack, unshift @fields ); 2522b39c5158Smillert push( @uBytesPerSect, unshift @fields ); 2523b39c5158Smillert } 2524b39c5158Smillert 2525b39c5158SmillertFor the C<$i>th type of supported media, the following variables will 2526b39c5158Smillertcontain the following data. 2527b39c5158Smillert 2528b39c5158Smillert=over 2529b39c5158Smillert 2530b39c5158Smillert=item C<$ucCylsLow[$i]> 2531b39c5158Smillert 2532b39c5158SmillertThe low-order 4 bytes of the total number of cylinders. 2533b39c5158Smillert 2534b39c5158Smillert=item C<$ivcCylsHigh[$i]> 2535b39c5158Smillert 2536b39c5158SmillertThe high-order 4 bytes of the total number of cylinders. 2537b39c5158Smillert 2538b39c5158Smillert=item C<$uMediaType[$i]> 2539b39c5158Smillert 2540b39c5158SmillertA code for the type of media. See the C<":MEDIA_TYPE"> export class. 2541b39c5158Smillert 2542b39c5158Smillert=item C<$uTracksPerCyl[$i]> 2543b39c5158Smillert 2544b39c5158SmillertThe number of tracks in each cylinder. 2545b39c5158Smillert 2546b39c5158Smillert=item C<$uSectsPerTrack[$i]> 2547b39c5158Smillert 2548b39c5158SmillertThe number of sectors in each track. 2549b39c5158Smillert 2550b39c5158Smillert=item C<$uBytesPerSect[$i]> 2551b39c5158Smillert 2552b39c5158SmillertThe number of bytes in each sector. 2553b39c5158Smillert 2554b39c5158Smillert=back 2555b39c5158Smillert 2556b39c5158Smillert=back 2557b39c5158Smillert 2558b39c5158Smillert=item C<":IOCTL_DISK_"> 2559b39c5158Smillert 2560b39c5158SmillertI/O control operations for disk devices. Used in the C<$uIoControlCode> 2561b39c5158Smillertargument to C<DeviceIoControl>. Most of these are to be used on 2562b39c5158Smillertphysical drive devices like C<"//./PhysicalDrive0">. However, 2563b39c5158SmillertC<IOCTL_DISK_GET_PARTITION_INFO> and C<IOCTL_DISK_SET_PARTITION_INFO> 2564b39c5158Smillertshould only be used on a single-partition device like C<"//./C:">. Also, 2565898184e3SsthenC<IOCTL_DISK_GET_MEDIA_TYPES> is documented as having been superseded but 2566b39c5158Smillertis still useful when used on a floppy device like C<"//./A:">. 2567b39c5158Smillert 2568b39c5158SmillertIncludes C<IOCTL_DISK_FORMAT_TRACKS>, C<IOCTL_DISK_FORMAT_TRACKS_EX>, 2569b39c5158SmillertC<IOCTL_DISK_GET_DRIVE_GEOMETRY>, C<IOCTL_DISK_GET_DRIVE_LAYOUT>, 2570b39c5158SmillertC<IOCTL_DISK_GET_MEDIA_TYPES>, C<IOCTL_DISK_GET_PARTITION_INFO>, 2571b39c5158SmillertC<IOCTL_DISK_HISTOGRAM_DATA>, C<IOCTL_DISK_HISTOGRAM_RESET>, 2572b39c5158SmillertC<IOCTL_DISK_HISTOGRAM_STRUCTURE>, C<IOCTL_DISK_IS_WRITABLE>, 2573b39c5158SmillertC<IOCTL_DISK_LOGGING>, C<IOCTL_DISK_PERFORMANCE>, 2574b39c5158SmillertC<IOCTL_DISK_REASSIGN_BLOCKS>, C<IOCTL_DISK_REQUEST_DATA>, 2575b39c5158SmillertC<IOCTL_DISK_REQUEST_STRUCTURE>, C<IOCTL_DISK_SET_DRIVE_LAYOUT>, 2576b39c5158SmillertC<IOCTL_DISK_SET_PARTITION_INFO>, and C<IOCTL_DISK_VERIFY>. 2577b39c5158Smillert 2578b39c5158Smillert=over 2579b39c5158Smillert 2580b39c5158Smillert=item C<IOCTL_DISK_GET_DRIVE_GEOMETRY> 2581b39c5158Smillert 2582b39c5158SmillertRequest information about the size and geometry of the disk. C<$pInBuf> 2583b39c5158Smillertshould be C<[]>. C<$opOutBuf> will be set to a C<DISK_GEOMETRY> data 2584b39c5158Smillertstructure which can be decode via: 2585b39c5158Smillert 2586b39c5158Smillert ( $ucCylsLow, $ivcCylsHigh, $uMediaType, $uTracksPerCyl, 2587b39c5158Smillert $uSectsPerTrack, $uBytesPerSect )= unpack( "L l I L L L", $opOutBuf ); 2588b39c5158Smillert 2589b39c5158Smillert=over 2590b39c5158Smillert 2591b39c5158Smillert=item C<$ucCylsLow> 2592b39c5158Smillert 2593b39c5158SmillertThe low-order 4 bytes of the total number of cylinders. 2594b39c5158Smillert 2595b39c5158Smillert=item C<$ivcCylsHigh> 2596b39c5158Smillert 2597b39c5158SmillertThe high-order 4 bytes of the total number of cylinders. 2598b39c5158Smillert 2599b39c5158Smillert=item C<$uMediaType> 2600b39c5158Smillert 2601b39c5158SmillertA code for the type of media. See the C<":MEDIA_TYPE"> export class. 2602b39c5158Smillert 2603b39c5158Smillert=item C<$uTracksPerCyl> 2604b39c5158Smillert 2605b39c5158SmillertThe number of tracks in each cylinder. 2606b39c5158Smillert 2607b39c5158Smillert=item C<$uSectsPerTrack> 2608b39c5158Smillert 2609b39c5158SmillertThe number of sectors in each track. 2610b39c5158Smillert 2611b39c5158Smillert=item C<$uBytesPerSect> 2612b39c5158Smillert 2613b39c5158SmillertThe number of bytes in each sector. 2614b39c5158Smillert 2615b39c5158Smillert=back 2616b39c5158Smillert 2617b39c5158Smillert=item C<IOCTL_DISK_GET_PARTITION_INFO> 2618b39c5158Smillert 2619b39c5158SmillertRequest information about the size and geometry of the partition. 2620b39c5158SmillertC<$pInBuf> should be C<[]>. C<$opOutBuf> will be set to a 2621b39c5158SmillertC<PARTITION_INFORMATION> data structure which can be decode via: 2622b39c5158Smillert 2623b39c5158Smillert ( $uStartLow, $ivStartHigh, $ucHiddenSects, $uPartitionSeqNumber, 2624b39c5158Smillert $uPartitionType, $bActive, $bRecognized, $bToRewrite )= 2625b39c5158Smillert unpack( "L l L L C c c c", $opOutBuf ); 2626b39c5158Smillert 2627b39c5158Smillert=over 2628b39c5158Smillert 2629b39c5158Smillert=item C<$uStartLow> and C<$ivStartHigh> 2630b39c5158Smillert 2631b39c5158SmillertThe low-order and high-order [respectively] 4 bytes of the starting 2632b39c5158Smillertoffset of the partition, measured in bytes. 2633b39c5158Smillert 2634b39c5158Smillert=item C<$ucHiddenSects> 2635b39c5158Smillert 2636b39c5158SmillertThe number of "hidden" sectors for this partition. Actually this is 2637898184e3Ssthenthe number of sectors found prior to this partition, that is, the 2638b39c5158Smillertstarting offset [as found in C<$uStartLow> and C<$ivStartHigh>] 2639b39c5158Smillertdivided by the number of bytes per sector. 2640b39c5158Smillert 2641b39c5158Smillert=item C<$uPartitionSeqNumber> 2642b39c5158Smillert 2643b39c5158SmillertThe sequence number of this partition. Partitions are numbered 2644b39c5158Smillertstarting as C<1> [with "partition 0" meaning the entire disk]. 2645b39c5158SmillertSometimes this field may be C<0> and you'll have to infer the 2646898184e3Ssthenpartition sequence number from how many partitions precede it on 2647b39c5158Smillertthe disk. 2648b39c5158Smillert 2649b39c5158Smillert=item C<$uPartitionType> 2650b39c5158Smillert 2651b39c5158SmillertThe type of partition. See the C<":PARTITION_"> export class for a 2652b39c5158Smillertlist of known types. See also C<IsRecognizedPartition> and 2653b39c5158SmillertC<IsContainerPartition>. 2654b39c5158Smillert 2655b39c5158Smillert=item C<$bActive> 2656b39c5158Smillert 2657b39c5158SmillertC<1> for the active [boot] partition, C<0> otherwise. 2658b39c5158Smillert 2659b39c5158Smillert=item C<$bRecognized> 2660b39c5158Smillert 2661b39c5158SmillertWhether this type of partition is support under Win32. 2662b39c5158Smillert 2663b39c5158Smillert=item C<$bToRewrite> 2664b39c5158Smillert 2665b39c5158SmillertWhether to update this partition information. This field is not used 2666b39c5158Smillertby C<IOCTL_DISK_GET_PARTITION_INFO>. For 2667b39c5158SmillertC<IOCTL_DISK_SET_DRIVE_LAYOUT>, you must set this field to a true 2668b39c5158Smillertvalue for any partitions you wish to have changed, added, or deleted. 2669b39c5158Smillert 2670b39c5158Smillert=back 2671b39c5158Smillert 2672b39c5158Smillert=item C<IOCTL_DISK_SET_PARTITION_INFO> 2673b39c5158Smillert 2674b39c5158SmillertChange the type of the partition. C<$opOutBuf> should be C<[]>. 2675b39c5158SmillertC<$pInBuf> should be a C<SET_PARTITION_INFORMATION> data structure 2676b8851fccSafresh1which is just a single byte containing the new partition type [see 2677b39c5158Smillertthe C<":PARTITION_"> export class for a list of known types]: 2678b39c5158Smillert 2679b39c5158Smillert $pInBuf= pack( "C", $uPartitionType ); 2680b39c5158Smillert 2681b39c5158Smillert=item C<IOCTL_DISK_GET_DRIVE_LAYOUT> 2682b39c5158Smillert 2683b39c5158SmillertRequest information about the disk layout. C<$pInBuf> should be C<[]>. 2684b39c5158SmillertC<$opOutBuf> will be set to contain C<DRIVE_LAYOUT_INFORMATION> 2685b39c5158Smillertstructure including several C<PARTITION_INFORMATION> structures: 2686b39c5158Smillert 2687b39c5158Smillert my( $cPartitions, $uDiskSignature )= unpack( "L L", $opOutBuf ); 2688b39c5158Smillert my @fields= unpack( "x8" . ( "L l L L C c c c" x $cPartitions ), 2689b39c5158Smillert $opOutBuf ); 2690b39c5158Smillert my( @uStartLow, @ivStartHigh, @ucHiddenSects, 2691b39c5158Smillert @uPartitionSeqNumber, @uPartitionType, @bActive, 2692b39c5158Smillert @bRecognized, @bToRewrite )= (); 2693b39c5158Smillert for( 1..$cPartition ) { 2694b39c5158Smillert push( @uStartLow, unshift @fields ); 2695b39c5158Smillert push( @ivStartHigh, unshift @fields ); 2696b39c5158Smillert push( @ucHiddenSects, unshift @fields ); 2697b39c5158Smillert push( @uPartitionSeqNumber, unshift @fields ); 2698b39c5158Smillert push( @uPartitionType, unshift @fields ); 2699b39c5158Smillert push( @bActive, unshift @fields ); 2700b39c5158Smillert push( @bRecognized, unshift @fields ); 2701b39c5158Smillert push( @bToRewrite, unshift @fields ); 2702b39c5158Smillert } 2703b39c5158Smillert 2704b39c5158Smillert=over 2705b39c5158Smillert 2706b39c5158Smillert=item C<$cPartitions> 2707b39c5158Smillert 2708b39c5158SmillertIf the number of partitions on the disk. 2709b39c5158Smillert 2710b39c5158Smillert=item C<$uDiskSignature> 2711b39c5158Smillert 2712b39c5158SmillertIs the disk signature, a unique number assigned by Disk Administrator 2713b39c5158Smillert[F<WinDisk.exe>] and used to identify the disk. This allows drive 2714b39c5158Smillertletters for partitions on that disk to remain constant even if the 2715b39c5158SmillertSCSI Target ID of the disk gets changed. 2716b39c5158Smillert 2717b39c5158Smillert=back 2718b39c5158Smillert 2719b39c5158SmillertSee C<IOCTL_DISK_GET_PARTITION_INFORMATION> for information on the 2720b39c5158Smillertremaining these fields. 2721b39c5158Smillert 2722b39c5158Smillert=item C<IOCTL_DISK_GET_MEDIA_TYPES> 2723b39c5158Smillert 2724b39c5158SmillertIs supposed to be superseded by C<IOCTL_STORAGE_GET_MEDIA_TYPES> but 2725b39c5158Smillertis still useful for determining the types of floppy diskette formats 2726b39c5158Smillertthat can be produced by a given floppy drive. See 2727b39c5158SmillertF<ex/FormatFloppy.plx> for an example. 2728b39c5158Smillert 2729b39c5158Smillert=item C<IOCTL_DISK_SET_DRIVE_LAYOUT> 2730b39c5158Smillert 2731b39c5158SmillertChange the partition layout of the disk. C<$pOutBuf> should be C<[]>. 2732b39c5158SmillertC<$pInBuf> should be a C<DISK_LAYOUT_INFORMATION> data structure 2733b39c5158Smillertincluding several C<PARTITION_INFORMATION> data structures. 2734b39c5158Smillert 2735b39c5158Smillert # Already set: $cPartitions, $uDiskSignature, @uStartLow, @ivStartHigh, 2736b39c5158Smillert # @ucHiddenSects, @uPartitionSeqNumber, @uPartitionType, @bActive, 2737b39c5158Smillert # @bRecognized, and @bToRewrite. 2738b39c5158Smillert my( @fields, $prtn )= (); 2739b39c5158Smillert for $prtn ( 1..$cPartition ) { 2740b39c5158Smillert push( @fields, $uStartLow[$prtn-1], $ivStartHigh[$prtn-1], 2741b39c5158Smillert $ucHiddenSects[$prtn-1], $uPartitionSeqNumber[$prtn-1], 2742b39c5158Smillert $uPartitionType[$prtn-1], $bActive[$prtn-1], 2743b39c5158Smillert $bRecognized[$prtn-1], $bToRewrite[$prtn-1] ); 2744b39c5158Smillert } 2745b39c5158Smillert $pInBuf= pack( "L L" . ( "L l L L C c c c" x $cPartitions ), 2746b39c5158Smillert $cPartitions, $uDiskSignature, @fields ); 2747b39c5158Smillert 2748b39c5158SmillertTo delete a partition, zero out all fields except for C<$bToRewrite> 2749b39c5158Smillertwhich should be set to C<1>. To add a partition, increment 2750b39c5158SmillertC<$cPartitions> and add the information for the new partition 2751b39c5158Smillertinto the arrays, making sure that you insert C<1> into @bToRewrite. 2752b39c5158Smillert 2753b39c5158SmillertSee C<IOCTL_DISK_GET_DRIVE_LAYOUT> and 2754b39c5158SmillertC<IOCTL_DISK_GET_PARITITON_INFORMATION> for descriptions of the 2755b39c5158Smillertfields. 2756b39c5158Smillert 2757b39c5158Smillert=item C<IOCTL_DISK_VERIFY> 2758b39c5158Smillert 2759b39c5158SmillertPerforms a logical format of [part of] the disk. C<$opOutBuf> should 2760b39c5158Smillertbe C<[]>. C<$pInBuf> should contain a C<VERIFY_INFORMATION> data 2761b39c5158Smillertstructure: 2762b39c5158Smillert 2763b39c5158Smillert $pInBuf= pack( "L l L", 2764b39c5158Smillert $uStartOffsetLow, $ivStartOffsetHigh, $uLength ); 2765b39c5158Smillert 2766b39c5158Smillert=over 2767b39c5158Smillert 2768b39c5158Smillert=item C<$uStartOffsetLow> and C<$ivStartOffsetHigh> 2769b39c5158Smillert 2770b39c5158SmillertThe low-order and high-order [respectively] 4 bytes of the offset [in 2771b39c5158Smillertbytes] where the formatting should begin. 2772b39c5158Smillert 2773b39c5158Smillert=item C<$uLength> 2774b39c5158Smillert 2775b39c5158SmillertThe length [in bytes] of the section to be formatted. 2776b39c5158Smillert 2777b39c5158Smillert=back 2778b39c5158Smillert 2779b39c5158Smillert=item C<IOCTL_DISK_FORMAT_TRACKS> 2780b39c5158Smillert 2781b39c5158SmillertFormat a range of tracks on the disk. C<$opOutBuf> should be C<[]>. 2782b39c5158SmillertC<$pInBuf> should contain a C<FORMAT_PARAMETERS> data structure: 2783b39c5158Smillert 2784b39c5158Smillert $pInBuf= pack( "L L L L L", $uMediaType, 2785b39c5158Smillert $uStartCyl, $uEndCyl, $uStartHead, $uEndHead ); 2786b39c5158Smillert 2787b39c5158SmillertC<$uMediaType> if the type of media to be formatted. Mostly used to 2788b39c5158Smillertspecify the density to use when formatting a floppy diskette. See the 2789b39c5158SmillertC<":MEDIA_TYPE"> export class for more information. 2790b39c5158Smillert 2791b39c5158SmillertThe remaining fields specify the starting and ending cylinder and 2792b39c5158Smillerthead of the range of tracks to be formatted. 2793b39c5158Smillert 2794b39c5158Smillert=item C<IOCTL_DISK_REASSIGN_BLOCKS> 2795b39c5158Smillert 2796b39c5158SmillertReassign a list of disk blocks to the disk's spare-block pool. 2797b39c5158SmillertC<$opOutBuf> should be C<[]>. C<$pInBuf> should be a 2798b39c5158SmillertC<REASSIGN_BLOCKS> data structure: 2799b39c5158Smillert 2800b39c5158Smillert $pInBuf= pack( "S S L*", 0, $cBlocks, @uBlockNumbers ); 2801b39c5158Smillert 2802b39c5158Smillert=item C<IOCTL_DISK_PERFORMANCE> 2803b39c5158Smillert 2804b39c5158SmillertRequest information about disk performance. C<$pInBuf> should be C<[]>. 2805b39c5158SmillertC<$opOutBuf> will be set to contain a C<DISK_PERFORMANCE> data structure: 2806b39c5158Smillert 2807b39c5158Smillert my( $ucBytesReadLow, $ivcBytesReadHigh, 2808b39c5158Smillert $ucBytesWrittenLow, $ivcBytesWrittenHigh, 2809b39c5158Smillert $uReadTimeLow, $ivReadTimeHigh, 2810b39c5158Smillert $uWriteTimeLow, $ivWriteTimeHigh, 2811b39c5158Smillert $ucReads, $ucWrites, $uQueueDepth )= 2812b39c5158Smillert unpack( "L l L l L l L l L L L", $opOutBuf ); 2813b39c5158Smillert 2814b39c5158Smillert=item C<IOCTL_DISK_IS_WRITABLE> 2815b39c5158Smillert 2816b39c5158SmillertNo documentation on this IOCTL operation was found. 2817b39c5158Smillert 2818b39c5158Smillert=item C<IOCTL_DISK_LOGGING> 2819b39c5158Smillert 2820b39c5158SmillertControl disk logging. Little documentation for this IOCTL operation 2821b39c5158Smillertwas found. It makes use of a C<DISK_LOGGING> data structure: 2822b39c5158Smillert 2823b39c5158Smillert=over 2824b39c5158Smillert 2825b39c5158Smillert=item DISK_LOGGING_START 2826b39c5158Smillert 2827b39c5158SmillertStart logging each disk request in a buffer internal to the disk device 2828b39c5158Smillertdriver of size C<$uLogBufferSize>: 2829b39c5158Smillert 2830b39c5158Smillert $pInBuf= pack( "C L L", 0, 0, $uLogBufferSize ); 2831b39c5158Smillert 2832b39c5158Smillert=item DISK_LOGGING_STOP 2833b39c5158Smillert 2834b8851fccSafresh1Stop logging each disk request: 2835b39c5158Smillert 2836b39c5158Smillert $pInBuf= pack( "C L L", 1, 0, 0 ); 2837b39c5158Smillert 2838b39c5158Smillert=item DISK_LOGGING_DUMP 2839b39c5158Smillert 2840898184e3SsthenCopy the internal log into the supplied buffer: 2841b39c5158Smillert 2842b39c5158Smillert $pLogBuffer= ' ' x $uLogBufferSize 2843b39c5158Smillert $pInBuf= pack( "C P L", 2, $pLogBuffer, $uLogBufferSize ); 2844b39c5158Smillert 2845b39c5158Smillert ( $uByteOffsetLow[$i], $ivByteOffsetHigh[$i], 2846b39c5158Smillert $uStartTimeLow[$i], $ivStartTimeHigh[$i], 2847b39c5158Smillert $uEndTimeLog[$i], $ivEndTimeHigh[$i], 2848b39c5158Smillert $hVirtualAddress[$i], $ucBytes[$i], 2849b39c5158Smillert $uDeviceNumber[$i], $bWasReading[$i] )= 2850b39c5158Smillert unpack( "x".(8+8+8+4+4+1+1+2)." L l L l L l L L C c x2", $pLogBuffer ); 2851b39c5158Smillert 2852b39c5158Smillert=item DISK_LOGGING_BINNING 2853b39c5158Smillert 2854b39c5158SmillertKeep statics grouped into bins based on request sizes. 2855b39c5158Smillert 2856b39c5158Smillert $pInBuf= pack( "C P L", 3, $pUnknown, $uUnknownSize ); 2857b39c5158Smillert 2858b39c5158Smillert=back 2859b39c5158Smillert 2860b39c5158Smillert=item C<IOCTL_DISK_FORMAT_TRACKS_EX> 2861b39c5158Smillert 2862b39c5158SmillertNo documentation on this IOCTL is included. 2863b39c5158Smillert 2864b39c5158Smillert=item C<IOCTL_DISK_HISTOGRAM_STRUCTURE> 2865b39c5158Smillert 2866b39c5158SmillertNo documentation on this IOCTL is included. 2867b39c5158Smillert 2868b39c5158Smillert=item C<IOCTL_DISK_HISTOGRAM_DATA> 2869b39c5158Smillert 2870b39c5158SmillertNo documentation on this IOCTL is included. 2871b39c5158Smillert 2872b39c5158Smillert=item C<IOCTL_DISK_HISTOGRAM_RESET> 2873b39c5158Smillert 2874b39c5158SmillertNo documentation on this IOCTL is included. 2875b39c5158Smillert 2876b39c5158Smillert=item C<IOCTL_DISK_REQUEST_STRUCTURE> 2877b39c5158Smillert 2878b39c5158SmillertNo documentation on this IOCTL operation was found. 2879b39c5158Smillert 2880b39c5158Smillert=item C<IOCTL_DISK_REQUEST_DATA> 2881b39c5158Smillert 2882b39c5158SmillertNo documentation on this IOCTL operation was found. 2883b39c5158Smillert 2884b39c5158Smillert=back 2885b39c5158Smillert 2886b39c5158Smillert=item C<":FSCTL_"> 2887b39c5158Smillert 2888b39c5158SmillertFile system control operations. Used in the C<$uIoControlCode> 2889b39c5158Smillertargument to C<DeviceIoControl>. 2890b39c5158Smillert 2891b39c5158SmillertIncludes C<FSCTL_SET_REPARSE_POINT>, C<FSCTL_GET_REPARSE_POINT>, 2892b39c5158SmillertC<FSCTL_DELETE_REPARSE_POINT>. 2893b39c5158Smillert 2894b39c5158Smillert=over 2895b39c5158Smillert 2896b39c5158Smillert=item C<FSCTL_SET_REPARSE_POINT> 2897b39c5158Smillert 2898b39c5158SmillertSets reparse point data to be associated with $hDevice. 2899b39c5158Smillert 2900b39c5158Smillert=item C<FSCTL_GET_REPARSE_POINT> 2901b39c5158Smillert 2902b39c5158SmillertRetrieves the reparse point data associated with $hDevice. 2903b39c5158Smillert 2904b39c5158Smillert=item C<FSCTL_DELETE_REPARSE_POINT> 2905b39c5158Smillert 2906b39c5158SmillertDeletes the reparse point data associated with $hDevice. 2907b39c5158Smillert 2908b39c5158Smillert=back 2909b39c5158Smillert 2910b39c5158Smillert=item C<":GENERIC_"> 2911b39c5158Smillert 2912b39c5158SmillertConstants specifying generic access permissions that are not specific 2913b39c5158Smillertto one type of object. 2914b39c5158Smillert 2915b39c5158Smillert GENERIC_ALL GENERIC_EXECUTE 2916b39c5158Smillert GENERIC_READ GENERIC_WRITE 2917b39c5158Smillert 2918b39c5158Smillert=item C<":MEDIA_TYPE"> 2919b39c5158Smillert 2920b39c5158SmillertDifferent classes of media that a device can support. Used in the 2921b39c5158SmillertC<$uMediaType> field of a C<DISK_GEOMETRY> structure. 2922b39c5158Smillert 2923b39c5158Smillert=over 2924b39c5158Smillert 2925b39c5158Smillert=item C<Unknown> 2926b39c5158Smillert 2927b39c5158SmillertFormat is unknown. 2928b39c5158Smillert 2929b39c5158Smillert=item C<F5_1Pt2_512> 2930b39c5158Smillert 2931b39c5158Smillert5.25" floppy, 1.2MB [really 1,200KB] total space, 512 bytes/sector. 2932b39c5158Smillert 2933b39c5158Smillert=item C<F3_1Pt44_512> 2934b39c5158Smillert 2935b39c5158Smillert3.5" floppy, 1.44MB [really 1,440KB] total space, 512 bytes/sector. 2936b39c5158Smillert 2937b39c5158Smillert=item C<F3_2Pt88_512> 2938b39c5158Smillert 2939b39c5158Smillert3.5" floppy, 2.88MB [really 2,880KB] total space, 512 bytes/sector. 2940b39c5158Smillert 2941b39c5158Smillert=item C<F3_20Pt8_512> 2942b39c5158Smillert 2943b39c5158Smillert3.5" floppy, 20.8MB total space, 512 bytes/sector. 2944b39c5158Smillert 2945b39c5158Smillert=item C<F3_720_512> 2946b39c5158Smillert 2947b39c5158Smillert3.5" floppy, 720KB total space, 512 bytes/sector. 2948b39c5158Smillert 2949b39c5158Smillert=item C<F5_360_512> 2950b39c5158Smillert 2951b39c5158Smillert5.25" floppy, 360KB total space, 512 bytes/sector. 2952b39c5158Smillert 2953b39c5158Smillert=item C<F5_320_512> 2954b39c5158Smillert 2955b39c5158Smillert5.25" floppy, 320KB total space, 512 bytes/sector. 2956b39c5158Smillert 2957b39c5158Smillert=item C<F5_320_1024> 2958b39c5158Smillert 2959b39c5158Smillert5.25" floppy, 320KB total space, 1024 bytes/sector. 2960b39c5158Smillert 2961b39c5158Smillert=item C<F5_180_512> 2962b39c5158Smillert 2963b39c5158Smillert5.25" floppy, 180KB total space, 512 bytes/sector. 2964b39c5158Smillert 2965b39c5158Smillert=item C<F5_160_512> 2966b39c5158Smillert 2967b39c5158Smillert5.25" floppy, 160KB total space, 512 bytes/sector. 2968b39c5158Smillert 2969b39c5158Smillert=item C<RemovableMedia> 2970b39c5158Smillert 2971b39c5158SmillertSome type of removable media other than a floppy diskette. 2972b39c5158Smillert 2973b39c5158Smillert=item C<FixedMedia> 2974b39c5158Smillert 2975b39c5158SmillertA fixed hard disk. 2976b39c5158Smillert 2977b39c5158Smillert=item C<F3_120M_512> 2978b39c5158Smillert 2979b39c5158Smillert3.5" floppy, 120MB total space. 2980b39c5158Smillert 2981b39c5158Smillert=back 2982b39c5158Smillert 2983b39c5158Smillert=item C<":MOVEFILE_"> 2984b39c5158Smillert 2985b39c5158SmillertConstants for use in C<$uFlags> arguments to C<MoveFileEx>. 2986b39c5158Smillert 2987b39c5158Smillert MOVEFILE_COPY_ALLOWED MOVEFILE_DELAY_UNTIL_REBOOT 2988b39c5158Smillert MOVEFILE_REPLACE_EXISTING MOVEFILE_WRITE_THROUGH 2989b39c5158Smillert 2990b39c5158Smillert=item C<":SECURITY_"> 2991b39c5158Smillert 2992b39c5158SmillertSecurity quality of service values that can be used in the C<$uFlags> 2993b39c5158Smillertargument to C<CreateFile> if opening the client side of a named pipe. 2994b39c5158Smillert 2995b39c5158Smillert SECURITY_ANONYMOUS SECURITY_CONTEXT_TRACKING 2996b39c5158Smillert SECURITY_DELEGATION SECURITY_EFFECTIVE_ONLY 2997b39c5158Smillert SECURITY_IDENTIFICATION SECURITY_IMPERSONATION 2998b39c5158Smillert SECURITY_SQOS_PRESENT 2999b39c5158Smillert 3000b39c5158Smillert=item C<":SEM_"> 3001b39c5158Smillert 3002b39c5158SmillertConstants to be used with C<SetErrorMode>. 3003b39c5158Smillert 3004b39c5158Smillert SEM_FAILCRITICALERRORS SEM_NOGPFAULTERRORBOX 3005b39c5158Smillert SEM_NOALIGNMENTFAULTEXCEPT SEM_NOOPENFILEERRORBOX 3006b39c5158Smillert 3007b39c5158Smillert=item C<":PARTITION_"> 3008b39c5158Smillert 3009b39c5158SmillertConstants describing partition types. 3010b39c5158Smillert 3011b39c5158Smillert PARTITION_ENTRY_UNUSED PARTITION_FAT_12 3012b39c5158Smillert PARTITION_XENIX_1 PARTITION_XENIX_2 3013b39c5158Smillert PARTITION_FAT_16 PARTITION_EXTENDED 3014b39c5158Smillert PARTITION_HUGE PARTITION_IFS 3015b39c5158Smillert PARTITION_FAT32 PARTITION_FAT32_XINT13 3016b39c5158Smillert PARTITION_XINT13 PARTITION_XINT13_EXTENDED 3017b39c5158Smillert PARTITION_PREP PARTITION_UNIX 3018b39c5158Smillert VALID_NTFT PARTITION_NTFT 3019b39c5158Smillert 302091f110e0Safresh1=item C<":STD_HANDLE_"> 302191f110e0Safresh1 302291f110e0Safresh1Constants for GetStdHandle and SetStdHandle 302391f110e0Safresh1 302491f110e0Safresh1 STD_ERROR_HANDLE 302591f110e0Safresh1 STD_INPUT_HANDLE 302691f110e0Safresh1 STD_OUTPUT_HANDLE 302791f110e0Safresh1 3028b39c5158Smillert=item C<":ALL"> 3029b39c5158Smillert 3030b39c5158SmillertAll of the above. 3031b39c5158Smillert 3032b39c5158Smillert=back 3033b39c5158Smillert 3034b39c5158Smillert=head1 BUGS 3035b39c5158Smillert 3036b39c5158SmillertNone known at this time. 3037b39c5158Smillert 3038b39c5158Smillert=head1 AUTHOR 3039b39c5158Smillert 3040898184e3SsthenTye McQueen, tye@metronet.com, http://perlmonks.org/?node=tye. 3041b39c5158Smillert 3042b39c5158Smillert=head1 SEE ALSO 3043b39c5158Smillert 3044b39c5158SmillertThe pyramids. 3045b39c5158Smillert 3046b39c5158Smillert=cut 3047