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::GetFolderPath(FOLDER [, CREATE])
 116
 117 [EXT] Returns the full pathname of one of the Windows special folders.
 118 The folder will be created if it doesn't exist and the optional CREATE
 119 argument is true.  The following FOLDER constants are defined by the
 120 Win32 module, but only exported on demand:
 121
 122         CSIDL_ADMINTOOLS
 123         CSIDL_APPDATA
 124         CSIDL_CDBURN_AREA
 125         CSIDL_COMMON_ADMINTOOLS
 126         CSIDL_COMMON_APPDATA
 127         CSIDL_COMMON_DESKTOPDIRECTORY
 128         CSIDL_COMMON_DOCUMENTS
 129         CSIDL_COMMON_FAVORITES
 130         CSIDL_COMMON_MUSIC
 131         CSIDL_COMMON_PICTURES
 132         CSIDL_COMMON_PROGRAMS
 133         CSIDL_COMMON_STARTMENU
 134         CSIDL_COMMON_STARTUP
 135         CSIDL_COMMON_TEMPLATES
 136         CSIDL_COMMON_VIDEO
 137         CSIDL_COOKIES
 138         CSIDL_DESKTOP
 139         CSIDL_DESKTOPDIRECTORY
 140         CSIDL_FAVORITES
 141         CSIDL_FONTS
 142         CSIDL_HISTORY
 143         CSIDL_INTERNET_CACHE
 144         CSIDL_LOCAL_APPDATA
 145         CSIDL_MYMUSIC
 146         CSIDL_MYPICTURES
 147         CSIDL_MYVIDEO
 148         CSIDL_NETHOOD
 149         CSIDL_PERSONAL
 150         CSIDL_PRINTHOOD
 151         CSIDL_PROFILE
 152         CSIDL_PROGRAMS
 153         CSIDL_PROGRAM_FILES
 154         CSIDL_PROGRAM_FILES_COMMON
 155         CSIDL_RECENT
 156         CSIDL_RESOURCES
 157         CSIDL_RESOURCES_LOCALIZED
 158         CSIDL_SENDTO
 159         CSIDL_STARTMENU
 160         CSIDL_STARTUP
 161         CSIDL_SYSTEM
 162         CSIDL_TEMPLATES
 163         CSIDL_WINDOWS
 164
 165 Note that not all folders are defined on all versions of Windows.
 166
 167 Please refer to the MSDN documentation of the CSIDL constants,
 168 currently available at:
 169
 170 http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/enums/csidl.asp
 171
 172 =item Win32::GetFullPathName(FILENAME)
 173
 174 [CORE] GetFullPathName combines the FILENAME with the current drive
 175 and directory name and returns a fully qualified (aka, absolute)
 176 path name. In list context it returns two elements: (PATH, FILE) where
 177 PATH is the complete pathname component (including trailing backslash)
 178 and FILE is just the filename part.  Note that no attempt is made to
 179 convert 8.3 components in the supplied FILENAME to longnames or
 180 vice-versa.  Compare with Win32::GetShortPathName and
 181 Win32::GetLongPathName.
 182
 183 This function has been added for Perl 5.6.
 184
 185 =item Win32::GetLastError()
 186
 187 [CORE] Returns the last error value generated by a call to a Win32 API
 188 function.  Note that C<$^E> used in a numeric context amounts to the
 189 same value.
 190
 191 =item Win32::GetLongPathName(PATHNAME)
 192
 193 [CORE] Returns a representation of PATHNAME composed of longname
 194 components (if any).  The result may not necessarily be longer
 195 than PATHNAME.  No attempt is made to convert PATHNAME to the
 196 absolute path.  Compare with Win32::GetShortPathName and
 197 Win32::GetFullPathName.
 198
 199 This function has been added for Perl 5.6.
 200
 201 =item Win32::GetNextAvailDrive()
 202
 203 [CORE] Returns a string in the form of "<d>:" where <d> is the first
 204 available drive letter.
 205
 206 =item Win32::GetOSVersion()
 207
 208 [CORE] Returns the list (STRING, MAJOR, MINOR, BUILD, ID), where the
 209 elements are, respectively: An arbitrary descriptive string, the major
 210 version number of the operating system, the minor version number, the
 211 build number, and a digit indicating the actual operating system.
 212 For the ID, the values are 0 for Win32s, 1 for Windows 9X/Me and 2 for
 213 Windows NT/2000/XP/2003.  In scalar context it returns just the ID.
 214
 215 Currently known values for ID MAJOR and MINOR are as follows:
 216
 217     OS                    ID    MAJOR   MINOR
 218     Win32s                 0      -       -
 219     Windows 95             1      4       0
 220     Windows 98             1      4      10
 221     Windows Me             1      4      90
 222     Windows NT 3.51        2      3      51
 223     Windows NT 4           2      4       0
 224     Windows 2000           2      5       0
 225     Windows XP             2      5       1
 226     Windows Server 2003    2      5       2
 227
 228 On Windows NT 4 SP6 and later this function returns the following
 229 additional values: SPMAJOR, SPMINOR, SUITEMASK, PRODUCTTYPE.
 230
 231 SPMAJOR and SPMINOR are are the version numbers of the latest
 232 installed service pack.
 233
 234 SUITEMASK is a bitfield identifying the product suites available on
 235 the system.  Known bits are:
 236
 237     VER_SUITE_SMALLBUSINESS             0x00000001
 238     VER_SUITE_ENTERPRISE                0x00000002
 239     VER_SUITE_BACKOFFICE                0x00000004
 240     VER_SUITE_COMMUNICATIONS            0x00000008
 241     VER_SUITE_TERMINAL                  0x00000010
 242     VER_SUITE_SMALLBUSINESS_RESTRICTED  0x00000020
 243     VER_SUITE_EMBEDDEDNT                0x00000040
 244     VER_SUITE_DATACENTER                0x00000080
 245     VER_SUITE_SINGLEUSERTS              0x00000100
 246     VER_SUITE_PERSONAL                  0x00000200
 247     VER_SUITE_BLADE                     0x00000400
 248     VER_SUITE_EMBEDDED_RESTRICTED       0x00000800
 249     VER_SUITE_SECURITY_APPLIANCE        0x00001000
 250
 251 The VER_SUITE_xxx names are listed here to crossreference the Microsoft
 252 documentation.  The Win32 module does not provide symbolic names for these
 253 constants.
 254
 255 PRODUCTTYPE provides additional information about the system.  It should
 256 be one of the following integer values:
 257
 258     1 - Workstation (NT 4, 2000 Pro, XP Home, XP Pro)
 259     2 - Domaincontroller
 260     3 - Server
 261
 262 =item Win32::GetOSName()
 263
 264 [EXT] In scalar context returns the name of the Win32 operating system
 265 being used.  In list context returns a two element list of the OS name
 266 and whatever edition information is known about the particular build
 267 (for Win9x boxes) and whatever service packs have been installed.
 268 The latter is roughly equivalent to the first item returned by
 269 GetOSVersion() in list context.
 270
 271 Currently the possible values for the OS name are
 272
 273  Win32s Win95 Win98 WinMe WinNT3.51 WinNT4 Win2000 WinXP/.Net Win2003
 274
 275 This routine is just a simple interface into GetOSVersion().  More
 276 specific or demanding situations should use that instead.  Another
 277 option would be to use POSIX::uname(), however the latter appears to
 278 report only the OS family name and not the specific OS.  In scalar
 279 context it returns just the ID.
 280
 281 The name "WinXP/.Net" is used for historical reasons only, to maintain
 282 backwards compatibility of the Win32 module.  Windows .NET Server has
 283 been renamed as Windows 2003 Server before final release and uses a
 284 different major/minor version number than Windows XP.
 285
 286 =item Win32::GetShortPathName(PATHNAME)
 287
 288 [CORE] Returns a representation of PATHNAME composed only of
 289 short (8.3) path components.  The result may not necessarily be
 290 shorter than PATHNAME.  Compare with Win32::GetFullPathName and
 291 Win32::GetLongPathName.
 292
 293 =item Win32::GetProcAddress(INSTANCE, PROCNAME)
 294
 295 [EXT] Returns the address of a function inside a loaded library. The
 296 information about what you can do with this address has been lost in
 297 the mist of time. Use the Win32::API module instead of this deprecated
 298 function.
 299
 300 =item Win32::GetTickCount()
 301
 302 [CORE] Returns the number of milliseconds elapsed since the last
 303 system boot. Resolution is limited to system timer ticks (about 10ms
 304 on WinNT and 55ms on Win9X).
 305
 306 =item Win32::InitiateSystemShutdown
 307
 308 (MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT)
 309
 310 [EXT] Shutsdown the specified MACHINE, notifying users with the
 311 supplied MESSAGE, within the specified TIMEOUT interval. Forces
 312 closing of all documents without prompting the user if FORCECLOSE is
 313 true, and reboots the machine if REBOOT is true. This function works
 314 only on WinNT.
 315
 316 =item Win32::IsWinNT()
 317
 318 [CORE] Returns non zero if the Win32 subsystem is Windows NT.
 319
 320 =item Win32::IsWin95()
 321
 322 [CORE] Returns non zero if the Win32 subsystem is Windows 95.
 323
 324 =item Win32::LoadLibrary(LIBNAME)
 325
 326 [EXT] Loads a dynamic link library into memory and returns its module
 327 handle. This handle can be used with Win32::GetProcAddress and
 328 Win32::FreeLibrary. This function is deprecated. Use the Win32::API
 329 module instead.
 330
 331 =item Win32::LoginName()
 332
 333 [CORE] Returns the username of the owner of the current perl process.
 334
 335 =item Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE)
 336
 337 [EXT] Looks up ACCOUNT on SYSTEM and returns the domain name the SID and
 338 the SID type.
 339
 340 =item Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE)
 341
 342 [EXT] Looks up SID on SYSTEM and returns the account name, domain name,
 343 and the SID type.
 344
 345 =item Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]])
 346
 347 [EXT] Create a dialogbox containing MESSAGE. FLAGS specifies the
 348 required icon and buttons according to the following table:
 349
 350         0 = OK
 351         1 = OK and Cancel
 352         2 = Abort, Retry, and Ignore
 353         3 = Yes, No and Cancel
 354         4 = Yes and No
 355         5 = Retry and Cancel
 356
 357         MB_ICONSTOP          "X" in a red circle
 358         MB_ICONQUESTION      question mark in a bubble
 359         MB_ICONEXCLAMATION   exclamation mark in a yellow triangle
 360         MB_ICONINFORMATION   "i" in a bubble
 361
 362 TITLE specifies an optional window title. The default is "Perl".
 363
 364 The function returns the menu id of the selected push button:
 365
 366         0  Error
 367
 368         1  OK
 369         2  Cancel
 370         3  Abort
 371         4  Retry
 372         5  Ignore
 373         6  Yes
 374         7  No
 375
 376 =item Win32::NodeName()
 377
 378 [CORE] Returns the Microsoft Network node-name of the current machine.
 379
 380 =item Win32::RegisterServer(LIBRARYNAME)
 381
 382 [EXT] Loads the DLL LIBRARYNAME and calls the function DllRegisterServer.
 383
 384 =item Win32::SetChildShowWindow(SHOWWINDOW)
 385
 386 [CORE] Sets the I<ShowMode> of child processes started by system().
 387 By default system() will create a new console window for child
 388 processes if Perl itself is not running from a console. Calling
 389 SetChildShowWindow(0) will make these new console windows invisible.
 390 Calling SetChildShowWindow() without arguments reverts system() to the
 391 default behavior.  The return value of SetChildShowWindow() is the
 392 previous setting or C<undef>.
 393
 394 [EXT] The following symbolic constants for SHOWWINDOW are available
 395 (but not exported) from the Win32 module: SW_HIDE, SW_SHOWNORMAL,
 396 SW_SHOWMINIMIZED, SW_SHOWMAXIMIZED and SW_SHOWNOACTIVATE.
 397
 398 =item Win32::SetCwd(NEWDIRECTORY)
 399
 400 [CORE] Sets the current active drive and directory. This function does not
 401 work with UNC paths, since the functionality required to required for
 402 such a feature is not available under Windows 95.
 403
 404 =item Win32::SetLastError(ERROR)
 405
 406 [CORE] Sets the value of the last error encountered to ERROR. This is
 407 that value that will be returned by the Win32::GetLastError()
 408 function. This functions has been added for Perl 5.6.
 409
 410 =item Win32::Sleep(TIME)
 411
 412 [CORE] Pauses for TIME milliseconds. The timeslices are made available
 413 to other processes and threads.
 414
 415 =item Win32::Spawn(COMMAND, ARGS, PID)
 416
 417 [CORE] Spawns a new process using the supplied COMMAND, passing in
 418 arguments in the string ARGS. The pid of the new process is stored in
 419 PID. This function is deprecated. Please use the Win32::Process module
 420 instead.
 421
 422 =item Win32::UnregisterServer(LIBRARYNAME)
 423
 424 [EXT] Loads the DLL LIBRARYNAME and calls the function
 425 DllUnregisterServer.
 426
 427 =back
 428
 429 =cut