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