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 the
 152 elements are, respectively: An arbitrary descriptive string, the major
 153 version number of the operating system, the minor version number, the
 154 build number, and a digit indicating the actual operating system.
 155 For the ID, the values are 0 for Win32s, 1 for Windows 9X and 2 for
 156 Windows NT/2000/XP.  In scalar context it returns just the ID.
 157
 158 Currently known values for ID MAJOR and MINOR are as follows:
 159
 160     OS                    ID    MAJOR   MINOR
 161     Win32s                 0      -       -
 162     Windows 95             1      4       0
 163     Windows 98             1      4      10
 164     Windows Me             1      4      90
 165     Windows NT 3.51        2      3      51
 166     Windows NT 4           2      4       0
 167     Windows 2000           2      5       0
 168     Windows XP             2      5       1
 169     Windows .NET Server    2      5       1
 170
 171 Unfortunately as of June 2002 there is no way to distinguish between
 172 .NET servers and XP servers without using additional modules.
 173
 174 =item Win32::GetOSName()
 175
 176 [EXT] In scalar context returns the name of the Win32 operating system
 177 being used.  In list context returns a two element list of the OS name
 178 and whatever edition information is known about the particular build
 179 (for Win9x boxes) and whatever service packs have been installed.
 180 The latter is roughly equivalent to the first item returned by
 181 GetOSVersion() in list context.
 182
 183 Currently the possible values for the OS name are
 184
 185   Win32s Win95 Win98 WinMe Win2000 WinXP/.Net WinNT3.51 WinNT4
 186
 187 This routine is just a simple interface into GetOSVersion().  More
 188 specific or demanding situations should use that instead.  Another
 189 option would be to use POSIX::uname(), however the latter appears to
 190 report only the OS family name and not the specific OS.  In scalar
 191 context it returns just the ID.
 192
 193 =item Win32::GetShortPathName(PATHNAME)
 194
 195 [CORE] Returns a representation of PATHNAME composed only of
 196 short (8.3) path components.  The result may not necessarily be
 197 shorter than PATHNAME.  Compare with Win32::GetFullPathName and
 198 Win32::GetLongPathName.
 199
 200 =item Win32::GetProcAddress(INSTANCE, PROCNAME)
 201
 202 [EXT] Returns the address of a function inside a loaded library. The
 203 information about what you can do with this address has been lost in
 204 the mist of time. Use the Win32::API module instead of this deprecated
 205 function.
 206
 207 =item Win32::GetTickCount()
 208
 209 [CORE] Returns the number of milliseconds elapsed since the last
 210 system boot. Resolution is limited to system timer ticks (about 10ms
 211 on WinNT and 55ms on Win9X).
 212
 213 =item Win32::InitiateSystemShutdown
 214
 215 (MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT)
 216
 217 [EXT] Shutsdown the specified MACHINE, notifying users with the
 218 supplied MESSAGE, within the specified TIMEOUT interval. Forces
 219 closing of all documents without prompting the user if FORCECLOSE is
 220 true, and reboots the machine if REBOOT is true. This function works
 221 only on WinNT.
 222
 223 =item Win32::IsWinNT()
 224
 225 [CORE] Returns non zero if the Win32 subsystem is Windows NT.
 226
 227 =item Win32::IsWin95()
 228
 229 [CORE] Returns non zero if the Win32 subsystem is Windows 95.
 230
 231 =item Win32::LoadLibrary(LIBNAME)
 232
 233 [EXT] Loads a dynamic link library into memory and returns its module
 234 handle. This handle can be used with Win32::GetProcAddress and
 235 Win32::FreeLibrary. This function is deprecated. Use the Win32::API
 236 module instead.
 237
 238 =item Win32::LoginName()
 239
 240 [CORE] Returns the username of the owner of the current perl process.
 241
 242 =item Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE)
 243
 244 [EXT] Looks up ACCOUNT on SYSTEM and returns the domain name the SID and
 245 the SID type.
 246
 247 =item Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE)
 248
 249 [EXT] Looks up SID on SYSTEM and returns the account name, domain name,
 250 and the SID type.
 251
 252 =item Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]])
 253
 254 [EXT] Create a dialogbox containing MESSAGE. FLAGS specifies the
 255 required icon and buttons according to the following table:
 256
 257         0 = OK
 258         1 = OK and Cancel
 259         2 = Abort, Retry, and Ignore
 260         3 = Yes, No and Cancel
 261         4 = Yes and No
 262         5 = Retry and Cancel
 263
 264         MB_ICONSTOP          "X" in a red circle
 265         MB_ICONQUESTION      question mark in a bubble
 266         MB_ICONEXCLAMATION   exclamation mark in a yellow triangle
 267         MB_ICONINFORMATION   "i" in a bubble
 268
 269 TITLE specifies an optional window title. The default is "Perl".
 270
 271 The function returns the menu id of the selected push button:
 272
 273         0  Error
 274
 275         1  OK
 276         2  Cancel
 277         3  Abort
 278         4  Retry
 279         5  Ignore
 280         6  Yes
 281         7  No
 282
 283 =item Win32::NodeName()
 284
 285 [CORE] Returns the Microsoft Network node-name of the current machine.
 286
 287 =item Win32::RegisterServer(LIBRARYNAME)
 288
 289 [EXT] Loads the DLL LIBRARYNAME and calls the function DllRegisterServer.
 290
 291 =item Win32::SetChildShowWindow(SHOWWINDOW)
 292
 293 [CORE] Sets the I<ShowMode> of child processes started by system().
 294 By default system() will create a new console window for child
 295 processes if Perl itself is not running from a console. Calling
 296 SetChildShowWindow(0) will make these new console windows invisible.
 297 Calling SetChildShowWindow() without arguments reverts system() to the
 298 default behavior.  The return value of SetChildShowWindow() is the
 299 previous setting or C<undef>.
 300
 301 [EXT] The following symbolic constants for SHOWWINDOW are available
 302 (but not exported) from the Win32 module: SW_HIDE, SW_SHOWNORMAL,
 303 SW_SHOWMINIMIZED, SW_SHOWMAXIMIZED and SW_SHOWNOACTIVATE.
 304
 305 =item Win32::SetCwd(NEWDIRECTORY)
 306
 307 [CORE] Sets the current active drive and directory. This function does not
 308 work with UNC paths, since the functionality required to required for
 309 such a feature is not available under Windows 95.
 310
 311 =item Win32::SetLastError(ERROR)
 312
 313 [CORE] Sets the value of the last error encountered to ERROR. This is
 314 that value that will be returned by the Win32::GetLastError()
 315 function. This functions has been added for Perl 5.6.
 316
 317 =item Win32::Sleep(TIME)
 318
 319 [CORE] Pauses for TIME milliseconds. The timeslices are made available
 320 to other processes and threads.
 321
 322 =item Win32::Spawn(COMMAND, ARGS, PID)
 323
 324 [CORE] Spawns a new process using the supplied COMMAND, passing in
 325 arguments in the string ARGS. The pid of the new process is stored in
 326 PID. This function is deprecated. Please use the Win32::Process module
 327 instead.
 328
 329 =item Win32::UnregisterServer(LIBRARYNAME)
 330
 331 [EXT] Loads the DLL LIBRARYNAME and calls the function
 332 DllUnregisterServer.
 333
 334 =back
 335
 336 =cut