| 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::SetChildShowWindow(SHOWWINDOW) |
| 257 | |
| 258 | [CORE] Sets the I<ShowMode> of child processes started by system(). |
| 259 | By default system() will create a new console window for child |
| 260 | processes if Perl itself is not running from a console. Calling |
| 261 | SetChildShowWindow(0) will make these new console windows invisible. |
| 262 | Calling SetChildShowWindow() without arguments reverts system() to the |
| 263 | default behavior. The return value of SetChildShowWindow() is the |
| 264 | previous setting or C<undef>. |
| 265 | |
| 266 | [EXT] The following symbolic constants for SHOWWINDOW are available |
| 267 | (but not exported) from the Win32 module: SW_HIDE, SW_SHOWNORMAL, |
| 268 | SW_SHOWMINIMIZED, SW_SHOWMAXIMIZED and SW_SHOWNOACTIVATE. |
| 269 | |
| 270 | =item Win32::SetCwd(NEWDIRECTORY) |
| 271 | |
| 272 | [CORE] Sets the current active drive and directory. This function does not |
| 273 | work with UNC paths, since the functionality required to required for |
| 274 | such a feature is not available under Windows 95. |
| 275 | |
| 276 | =item Win32::SetLastError(ERROR) |
| 277 | |
| 278 | [CORE] Sets the value of the last error encountered to ERROR. This is |
| 279 | that value that will be returned by the Win32::GetLastError() |
| 280 | function. This functions has been added for Perl 5.6. |
| 281 | |
| 282 | =item Win32::Sleep(TIME) |
| 283 | |
| 284 | [CORE] Pauses for TIME milliseconds. The timeslices are made available |
| 285 | to other processes and threads. |
| 286 | |
| 287 | =item Win32::Spawn(COMMAND, ARGS, PID) |
| 288 | |
| 289 | [CORE] Spawns a new process using the supplied COMMAND, passing in |
| 290 | arguments in the string ARGS. The pid of the new process is stored in |
| 291 | PID. This function is deprecated. Please use the Win32::Process module |
| 292 | instead. |
| 293 | |
| 294 | =item Win32::UnregisterServer(LIBRARYNAME) |
| 295 | |
| 296 | [EXT] Loads the DLL LIBRARYNAME and calls the function |
| 297 | DllUnregisterServer. |
| 298 | |
| 299 | =back |
| 300 | |
| 301 | =cut |