Commit | Line | Data |
1674ad2b |
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 | |
625a29bd |
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. |
1674ad2b |
42 | |
43 | =item Win32::DomainName() |
44 | |
45 | [CORE] Returns the name of the Microsoft Network domain that the |
da147683 |
46 | owner of the current perl process is logged into. This function does |
47 | B<not> work on Windows 9x. |
1674ad2b |
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 |
4a4eefd0 |
96 | no longer valid after this call. See L<LoadLibrary|Win32::LoadLibrary(LIBNAME)> |
97 | for information on dynamically loading a library. |
1674ad2b |
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 | |
87755fa7 |
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 | |
1674ad2b |
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 | |
87275199 |
183 | This function has been added for Perl 5.6. |
1674ad2b |
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 | |
4375e838 |
193 | [CORE] Returns a representation of PATHNAME composed of longname |
da2094fd |
194 | components (if any). The result may not necessarily be longer |
1674ad2b |
195 | than PATHNAME. No attempt is made to convert PATHNAME to the |
196 | absolute path. Compare with Win32::GetShortPathName and |
197 | Win32::GetFullPathName. |
198 | |
87275199 |
199 | This function has been added for Perl 5.6. |
1674ad2b |
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 | |
3e526985 |
208 | [CORE] Returns the list (STRING, MAJOR, MINOR, BUILD, ID), where the |
d10f8d7a |
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. |
3e526985 |
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. |
d10f8d7a |
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 |
3e526985 |
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 |
d10f8d7a |
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 | |
3e526985 |
273 | Win32s Win95 Win98 WinMe WinNT3.51 WinNT4 Win2000 WinXP/.Net Win2003 |
d10f8d7a |
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. |
1674ad2b |
280 | |
3e526985 |
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 | |
1674ad2b |
286 | =item Win32::GetShortPathName(PATHNAME) |
287 | |
da2094fd |
288 | [CORE] Returns a representation of PATHNAME composed only of |
1674ad2b |
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 | |
cb49b31f |
306 | =item Win32::InitiateSystemShutdown |
551e1d92 |
307 | |
cb49b31f |
308 | (MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT) |
1674ad2b |
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 | |
625a29bd |
342 | [EXT] Looks up SID on SYSTEM and returns the account name, domain name, |
1674ad2b |
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 | |
02637f4c |
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 | |
1674ad2b |
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() |
87275199 |
408 | function. This functions has been added for Perl 5.6. |
1674ad2b |
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 |