lib/Win32.pod

   1 =head1 NAME
   2
   3 Win32 - Interfaces to some Win32 API Functions
   4
   5 =head1 DESCRIPTION
   6
   7 Perl on Win32 contains several functions to access Win32 APIs. Some
   8 are included in Perl itself (on Win32) and some are only available
   9 after explicitly requesting the Win32 module with:
  10
  11         use Win32;
  12
  13 The builtin functions are marked as [CORE] and the other ones
  14 as [EXT] in the following alphabetical listing. The C<Win32> module
  15 is not part of the Perl source distribution; it is distributed in
  16 the libwin32 bundle of Win32::* modules on CPAN. The module is
  17 already preinstalled in binary distributions like ActivePerl.
  18
  19 =head2 Alphabetical Listing of Win32 Functions
  20
  21 =over
  22
  23 =item Win32::AbortSystemShutdown(MACHINE)
  24
  25 [EXT] Aborts a system shutdown (started by the
  26 InitiateSystemShutdown function) on the specified MACHINE.
  27
  28 =item Win32::BuildNumber()
  29
  30 [CORE] Returns the ActivePerl build number. This function is
  31 only available in the ActivePerl binary distribution.
  32
  33 =item Win32::CopyFile(FROM, TO, OVERWRITE)
  34
  35 [CORE] The Win32::CopyFile() function copies an existing file to a new
  36 file. All file information like creation time and file attributes will
  37 be copied to the new file. However it will B<not> copy the security
  38 information. If the destination file already exists it will only be
  39 overwritten when the OVERWRITE parameter is true. But even this will
  40 not overwrite a read-only file; you have to unlink() it first
  41 yourself.
  42
  43 =item Win32::DomainName()
  44
  45 [CORE] Returns the name of the Microsoft Network domain that the
  46 owner of the current perl process is logged into.  This function does
  47 B<not> work on Windows 9x.
  48
  49 =item Win32::ExpandEnvironmentStrings(STRING)
  50
  51 [EXT] Takes STRING and replaces all referenced environment variable
  52 names with their defined values. References to environment variables
  53 take the form C<%VariableName%>. Case is ignored when looking up the
  54 VariableName in the environment. If the variable is not found then the
  55 original C<%VariableName%> text is retained.  Has the same effect
  56 as the following:
  57
  58         $string =~ s/%([^%]*)%/$ENV{$1} || "%$1%"/eg
  59
  60 =item Win32::FormatMessage(ERRORCODE)
  61
  62 [CORE] Converts the supplied Win32 error number (e.g. returned by
  63 Win32::GetLastError()) to a descriptive string.  Analogous to the
  64 perror() standard-C library function.  Note that C<$^E> used
  65 in a string context has much the same effect.
  66
  67         C:\> perl -e "$^E = 26; print $^E;"
  68         The specified disk or diskette cannot be accessed
  69
  70 =item Win32::FsType()
  71
  72 [CORE] Returns the name of the filesystem of the currently active
  73 drive (like 'FAT' or 'NTFS'). In list context it returns three values:
  74 (FSTYPE, FLAGS, MAXCOMPLEN). FSTYPE is the filesystem type as
  75 before. FLAGS is a combination of values of the following table:
  76
  77         0x00000001  supports case-sensitive filenames
  78         0x00000002  preserves the case of filenames
  79         0x00000004  supports Unicode in filenames
  80         0x00000008  preserves and enforces ACLs
  81         0x00000010  supports file-based compression
  82         0x00000020  supports disk quotas
  83         0x00000040  supports sparse files
  84         0x00000080  supports reparse points
  85         0x00000100  supports remote storage
  86         0x00008000  is a compressed volume (e.g. DoubleSpace)
  87         0x00010000  supports object identifiers
  88         0x00020000  supports the Encrypted File System (EFS)
  89
  90 MAXCOMPLEN is the maximum length of a filename component (the part
  91 between two backslashes) on this file system.
  92
  93 =item Win32::FreeLibrary(HANDLE)
  94
  95 [EXT] Unloads a previously loaded dynamic-link library. The HANDLE is
  96 no longer valid after this call. See L<LoadLibrary|Win32::LoadLibrary(LIBNAME)>
  97 for information on dynamically loading a library.
  98
  99 =item Win32::GetArchName()
 100
 101 [EXT] Use of this function is deprecated. It is equivalent with
 102 $ENV{PROCESSOR_ARCHITECTURE}. This might not work on Win9X.
 103
 104 =item Win32::GetChipName()
 105
 106 [EXT] Returns the processor type: 386, 486 or 586 for Intel processors,
 107 21064 for the Alpha chip.
 108
 109 =item Win32::GetCwd()
 110
 111 [CORE] Returns the current active drive and directory. This function
 112 does not return a UNC path, since the functionality required for such
 113 a feature is not available under Windows 95.
 114
 115 =item Win32::GetFullPathName(FILENAME)
 116
 117 [CORE] GetFullPathName combines the FILENAME with the current drive
 118 and directory name and returns a fully qualified (aka, absolute)
 119 path name. In list context it returns two elements: (PATH, FILE) where
 120 PATH is the complete pathname component (including trailing backslash)
 121 and FILE is just the filename part.  Note that no attempt is made to
 122 convert 8.3 components in the supplied FILENAME to longnames or
 123 vice-versa.  Compare with Win32::GetShortPathName and
 124 Win32::GetLongPathName.
 125
 126 This function has been added for Perl 5.6.
 127
 128 =item Win32::GetLastError()
 129
 130 [CORE] Returns the last error value generated by a call to a Win32 API
 131 function.  Note that C<$^E> used in a numeric context amounts to the
 132 same value.
 133
 134 =item Win32::GetLongPathName(PATHNAME)
 135
 136 [CORE] Returns a representation of PATHNAME composed of longname
 137 components (if any).  The result may not necessarily be longer
 138 than PATHNAME.  No attempt is made to convert PATHNAME to the
 139 absolute path.  Compare with Win32::GetShortPathName and
 140 Win32::GetFullPathName.
 141
 142 This function has been added for Perl 5.6.
 143
 144 =item Win32::GetNextAvailDrive()
 145
 146 [CORE] Returns a string in the form of "<d>:" where <d> is the first
 147 available drive letter.
 148
 149 =item Win32::GetOSVersion()
 150
 151 [CORE] Returns the array (STRING, MAJOR, MINOR, BUILD, ID), where
 152 the elements are, respectively: An arbitrary descriptive string, the
 153 major version number of the operating system, the minor version
 154 number, the build number, and a digit indicating the actual operating
 155 system. For ID, the values are 0 for Win32s, 1 for Windows 9X and 2
 156 for Windows NT. In scalar context it returns just the ID.
 157
 158 =item Win32::GetShortPathName(PATHNAME)
 159
 160 [CORE] Returns a representation of PATHNAME composed only of
 161 short (8.3) path components.  The result may not necessarily be
 162 shorter than PATHNAME.  Compare with Win32::GetFullPathName and
 163 Win32::GetLongPathName.
 164
 165 =item Win32::GetProcAddress(INSTANCE, PROCNAME)
 166
 167 [EXT] Returns the address of a function inside a loaded library. The
 168 information about what you can do with this address has been lost in
 169 the mist of time. Use the Win32::API module instead of this deprecated
 170 function.
 171
 172 =item Win32::GetTickCount()
 173
 174 [CORE] Returns the number of milliseconds elapsed since the last
 175 system boot. Resolution is limited to system timer ticks (about 10ms
 176 on WinNT and 55ms on Win9X).
 177
 178 =item Win32::InitiateSystemShutdown(MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT)
 179
 180 [EXT] Shutsdown the specified MACHINE, notifying users with the
 181 supplied MESSAGE, within the specified TIMEOUT interval. Forces
 182 closing of all documents without prompting the user if FORCECLOSE is
 183 true, and reboots the machine if REBOOT is true. This function works
 184 only on WinNT.
 185
 186 =item Win32::IsWinNT()
 187
 188 [CORE] Returns non zero if the Win32 subsystem is Windows NT.
 189
 190 =item Win32::IsWin95()
 191
 192 [CORE] Returns non zero if the Win32 subsystem is Windows 95.
 193
 194 =item Win32::LoadLibrary(LIBNAME)
 195
 196 [EXT] Loads a dynamic link library into memory and returns its module
 197 handle. This handle can be used with Win32::GetProcAddress and
 198 Win32::FreeLibrary. This function is deprecated. Use the Win32::API
 199 module instead.
 200
 201 =item Win32::LoginName()
 202
 203 [CORE] Returns the username of the owner of the current perl process.
 204
 205 =item Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE)
 206
 207 [EXT] Looks up ACCOUNT on SYSTEM and returns the domain name the SID and
 208 the SID type.
 209
 210 =item Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE)
 211
 212 [EXT] Looks up SID on SYSTEM and returns the account name, domain name,
 213 and the SID type.
 214
 215 =item Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]])
 216
 217 [EXT] Create a dialogbox containing MESSAGE. FLAGS specifies the
 218 required icon and buttons according to the following table:
 219
 220         0 = OK
 221         1 = OK and Cancel
 222         2 = Abort, Retry, and Ignore
 223         3 = Yes, No and Cancel
 224         4 = Yes and No
 225         5 = Retry and Cancel
 226
 227         MB_ICONSTOP          "X" in a red circle
 228         MB_ICONQUESTION      question mark in a bubble
 229         MB_ICONEXCLAMATION   exclamation mark in a yellow triangle
 230         MB_ICONINFORMATION   "i" in a bubble
 231
 232 TITLE specifies an optional window title. The default is "Perl".
 233
 234 The function returns the menu id of the selected push button:
 235
 236         0  Error
 237
 238         1  OK
 239         2  Cancel
 240         3  Abort
 241         4  Retry
 242         5  Ignore
 243         6  Yes
 244         7  No
 245
 246 =item Win32::NodeName()
 247
 248 [CORE] Returns the Microsoft Network node-name of the current machine.
 249
 250 =item Win32::RegisterServer(LIBRARYNAME)
 251
 252 [EXT] Loads the DLL LIBRARYNAME and calls the function DllRegisterServer.
 253
 254 =item Win32::SetCwd(NEWDIRECTORY)
 255
 256 [CORE] Sets the current active drive and directory. This function does not
 257 work with UNC paths, since the functionality required to required for
 258 such a feature is not available under Windows 95.
 259
 260 =item Win32::SetLastError(ERROR)
 261
 262 [CORE] Sets the value of the last error encountered to ERROR. This is
 263 that value that will be returned by the Win32::GetLastError()
 264 function. This functions has been added for Perl 5.6.
 265
 266 =item Win32::Sleep(TIME)
 267
 268 [CORE] Pauses for TIME milliseconds. The timeslices are made available
 269 to other processes and threads.
 270
 271 =item Win32::Spawn(COMMAND, ARGS, PID)
 272
 273 [CORE] Spawns a new process using the supplied COMMAND, passing in
 274 arguments in the string ARGS. The pid of the new process is stored in
 275 PID. This function is deprecated. Please use the Win32::Process module
 276 instead.
 277
 278 =item Win32::UnregisterServer(LIBRARYNAME)
 279
 280 [EXT] Loads the DLL LIBRARYNAME and calls the function
 281 DllUnregisterServer.
 282
 283 =back
 284
 285 =cut