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
 179
 180 (MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT)
 181
 182 [EXT] Shutsdown the specified MACHINE, notifying users with the
 183 supplied MESSAGE, within the specified TIMEOUT interval. Forces
 184 closing of all documents without prompting the user if FORCECLOSE is
 185 true, and reboots the machine if REBOOT is true. This function works
 186 only on WinNT.
 187
 188 =item Win32::IsWinNT()
 189
 190 [CORE] Returns non zero if the Win32 subsystem is Windows NT.
 191
 192 =item Win32::IsWin95()
 193
 194 [CORE] Returns non zero if the Win32 subsystem is Windows 95.
 195
 196 =item Win32::LoadLibrary(LIBNAME)
 197
 198 [EXT] Loads a dynamic link library into memory and returns its module
 199 handle. This handle can be used with Win32::GetProcAddress and
 200 Win32::FreeLibrary. This function is deprecated. Use the Win32::API
 201 module instead.
 202
 203 =item Win32::LoginName()
 204
 205 [CORE] Returns the username of the owner of the current perl process.
 206
 207 =item Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE)
 208
 209 [EXT] Looks up ACCOUNT on SYSTEM and returns the domain name the SID and
 210 the SID type.
 211
 212 =item Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE)
 213
 214 [EXT] Looks up SID on SYSTEM and returns the account name, domain name,
 215 and the SID type.
 216
 217 =item Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]])
 218
 219 [EXT] Create a dialogbox containing MESSAGE. FLAGS specifies the
 220 required icon and buttons according to the following table:
 221
 222         0 = OK
 223         1 = OK and Cancel
 224         2 = Abort, Retry, and Ignore
 225         3 = Yes, No and Cancel
 226         4 = Yes and No
 227         5 = Retry and Cancel
 228
 229         MB_ICONSTOP          "X" in a red circle
 230         MB_ICONQUESTION      question mark in a bubble
 231         MB_ICONEXCLAMATION   exclamation mark in a yellow triangle
 232         MB_ICONINFORMATION   "i" in a bubble
 233
 234 TITLE specifies an optional window title. The default is "Perl".
 235
 236 The function returns the menu id of the selected push button:
 237
 238         0  Error
 239
 240         1  OK
 241         2  Cancel
 242         3  Abort
 243         4  Retry
 244         5  Ignore
 245         6  Yes
 246         7  No
 247
 248 =item Win32::NodeName()
 249
 250 [CORE] Returns the Microsoft Network node-name of the current machine.
 251
 252 =item Win32::RegisterServer(LIBRARYNAME)
 253
 254 [EXT] Loads the DLL LIBRARYNAME and calls the function DllRegisterServer.
 255
 256 =item Win32::SetCwd(NEWDIRECTORY)
 257
 258 [CORE] Sets the current active drive and directory. This function does not
 259 work with UNC paths, since the functionality required to required for
 260 such a feature is not available under Windows 95.
 261
 262 =item Win32::SetLastError(ERROR)
 263
 264 [CORE] Sets the value of the last error encountered to ERROR. This is
 265 that value that will be returned by the Win32::GetLastError()
 266 function. This functions has been added for Perl 5.6.
 267
 268 =item Win32::Sleep(TIME)
 269
 270 [CORE] Pauses for TIME milliseconds. The timeslices are made available
 271 to other processes and threads.
 272
 273 =item Win32::Spawn(COMMAND, ARGS, PID)
 274
 275 [CORE] Spawns a new process using the supplied COMMAND, passing in
 276 arguments in the string ARGS. The pid of the new process is stored in
 277 PID. This function is deprecated. Please use the Win32::Process module
 278 instead.
 279
 280 =item Win32::UnregisterServer(LIBRARYNAME)
 281
 282 [EXT] Loads the DLL LIBRARYNAME and calls the function
 283 DllUnregisterServer.
 284
 285 =back
 286
 287 =cut