Commit | Line | Data |
---|---|---|
b4ad57f4 NC |
1 | package Win32; |
2 | ||
3 | BEGIN { | |
4 | use strict; | |
34f7f30d | 5 | use vars qw|$VERSION $XS_VERSION @ISA @EXPORT @EXPORT_OK|; |
b4ad57f4 NC |
6 | |
7 | require Exporter; | |
8 | require DynaLoader; | |
9 | ||
10 | @ISA = qw|Exporter DynaLoader|; | |
a7aed572 | 11 | $VERSION = '0.38'; |
34f7f30d SH |
12 | $XS_VERSION = $VERSION; |
13 | $VERSION = eval $VERSION; | |
b4ad57f4 NC |
14 | |
15 | @EXPORT = qw( | |
16 | NULL | |
17 | WIN31_CLASS | |
18 | OWNER_SECURITY_INFORMATION | |
19 | GROUP_SECURITY_INFORMATION | |
20 | DACL_SECURITY_INFORMATION | |
21 | SACL_SECURITY_INFORMATION | |
22 | MB_ICONHAND | |
23 | MB_ICONQUESTION | |
24 | MB_ICONEXCLAMATION | |
25 | MB_ICONASTERISK | |
26 | MB_ICONWARNING | |
27 | MB_ICONERROR | |
28 | MB_ICONINFORMATION | |
29 | MB_ICONSTOP | |
30 | ); | |
31 | @EXPORT_OK = qw( | |
32 | GetOSName | |
33 | SW_HIDE | |
34 | SW_SHOWNORMAL | |
35 | SW_SHOWMINIMIZED | |
36 | SW_SHOWMAXIMIZED | |
37 | SW_SHOWNOACTIVATE | |
38 | ||
39 | CSIDL_DESKTOP | |
40 | CSIDL_PROGRAMS | |
41 | CSIDL_PERSONAL | |
42 | CSIDL_FAVORITES | |
43 | CSIDL_STARTUP | |
44 | CSIDL_RECENT | |
45 | CSIDL_SENDTO | |
46 | CSIDL_STARTMENU | |
47 | CSIDL_MYMUSIC | |
48 | CSIDL_MYVIDEO | |
49 | CSIDL_DESKTOPDIRECTORY | |
50 | CSIDL_NETHOOD | |
51 | CSIDL_FONTS | |
52 | CSIDL_TEMPLATES | |
53 | CSIDL_COMMON_STARTMENU | |
54 | CSIDL_COMMON_PROGRAMS | |
55 | CSIDL_COMMON_STARTUP | |
56 | CSIDL_COMMON_DESKTOPDIRECTORY | |
57 | CSIDL_APPDATA | |
58 | CSIDL_PRINTHOOD | |
59 | CSIDL_LOCAL_APPDATA | |
60 | CSIDL_COMMON_FAVORITES | |
61 | CSIDL_INTERNET_CACHE | |
62 | CSIDL_COOKIES | |
63 | CSIDL_HISTORY | |
64 | CSIDL_COMMON_APPDATA | |
65 | CSIDL_WINDOWS | |
66 | CSIDL_SYSTEM | |
67 | CSIDL_PROGRAM_FILES | |
68 | CSIDL_MYPICTURES | |
69 | CSIDL_PROFILE | |
70 | CSIDL_PROGRAM_FILES_COMMON | |
71 | CSIDL_COMMON_TEMPLATES | |
72 | CSIDL_COMMON_DOCUMENTS | |
73 | CSIDL_COMMON_ADMINTOOLS | |
74 | CSIDL_ADMINTOOLS | |
75 | CSIDL_COMMON_MUSIC | |
76 | CSIDL_COMMON_PICTURES | |
77 | CSIDL_COMMON_VIDEO | |
78 | CSIDL_RESOURCES | |
79 | CSIDL_RESOURCES_LOCALIZED | |
80 | CSIDL_CDBURN_AREA | |
81 | ); | |
82 | } | |
83 | ||
b4ad57f4 NC |
84 | # We won't bother with the constant stuff, too much of a hassle. Just hard |
85 | # code it here. | |
86 | ||
87 | sub NULL { 0 } | |
88 | sub WIN31_CLASS { &NULL } | |
89 | ||
90 | sub OWNER_SECURITY_INFORMATION { 0x00000001 } | |
91 | sub GROUP_SECURITY_INFORMATION { 0x00000002 } | |
92 | sub DACL_SECURITY_INFORMATION { 0x00000004 } | |
93 | sub SACL_SECURITY_INFORMATION { 0x00000008 } | |
94 | ||
95 | sub MB_ICONHAND { 0x00000010 } | |
96 | sub MB_ICONQUESTION { 0x00000020 } | |
97 | sub MB_ICONEXCLAMATION { 0x00000030 } | |
98 | sub MB_ICONASTERISK { 0x00000040 } | |
99 | sub MB_ICONWARNING { 0x00000030 } | |
100 | sub MB_ICONERROR { 0x00000010 } | |
101 | sub MB_ICONINFORMATION { 0x00000040 } | |
102 | sub MB_ICONSTOP { 0x00000010 } | |
103 | ||
104 | # | |
105 | # Newly added constants. These have an empty prototype, unlike the | |
106 | # the ones above, which aren't prototyped for compatibility reasons. | |
107 | # | |
108 | sub SW_HIDE () { 0 } | |
109 | sub SW_SHOWNORMAL () { 1 } | |
110 | sub SW_SHOWMINIMIZED () { 2 } | |
111 | sub SW_SHOWMAXIMIZED () { 3 } | |
112 | sub SW_SHOWNOACTIVATE () { 4 } | |
113 | ||
114 | sub CSIDL_DESKTOP () { 0x0000 } # <desktop> | |
115 | sub CSIDL_PROGRAMS () { 0x0002 } # Start Menu\Programs | |
116 | sub CSIDL_PERSONAL () { 0x0005 } # "My Documents" folder | |
117 | sub CSIDL_FAVORITES () { 0x0006 } # <user name>\Favorites | |
118 | sub CSIDL_STARTUP () { 0x0007 } # Start Menu\Programs\Startup | |
119 | sub CSIDL_RECENT () { 0x0008 } # <user name>\Recent | |
120 | sub CSIDL_SENDTO () { 0x0009 } # <user name>\SendTo | |
121 | sub CSIDL_STARTMENU () { 0x000B } # <user name>\Start Menu | |
122 | sub CSIDL_MYMUSIC () { 0x000D } # "My Music" folder | |
123 | sub CSIDL_MYVIDEO () { 0x000E } # "My Videos" folder | |
124 | sub CSIDL_DESKTOPDIRECTORY () { 0x0010 } # <user name>\Desktop | |
125 | sub CSIDL_NETHOOD () { 0x0013 } # <user name>\nethood | |
126 | sub CSIDL_FONTS () { 0x0014 } # windows\fonts | |
127 | sub CSIDL_TEMPLATES () { 0x0015 } | |
128 | sub CSIDL_COMMON_STARTMENU () { 0x0016 } # All Users\Start Menu | |
129 | sub CSIDL_COMMON_PROGRAMS () { 0x0017 } # All Users\Start Menu\Programs | |
130 | sub CSIDL_COMMON_STARTUP () { 0x0018 } # All Users\Startup | |
131 | sub CSIDL_COMMON_DESKTOPDIRECTORY () { 0x0019 } # All Users\Desktop | |
132 | sub CSIDL_APPDATA () { 0x001A } # Application Data, new for NT4 | |
133 | sub CSIDL_PRINTHOOD () { 0x001B } # <user name>\PrintHood | |
134 | sub CSIDL_LOCAL_APPDATA () { 0x001C } # non roaming, user\Local Settings\Application Data | |
135 | sub CSIDL_COMMON_FAVORITES () { 0x001F } | |
136 | sub CSIDL_INTERNET_CACHE () { 0x0020 } | |
137 | sub CSIDL_COOKIES () { 0x0021 } | |
138 | sub CSIDL_HISTORY () { 0x0022 } | |
139 | sub CSIDL_COMMON_APPDATA () { 0x0023 } # All Users\Application Data | |
140 | sub CSIDL_WINDOWS () { 0x0024 } # GetWindowsDirectory() | |
141 | sub CSIDL_SYSTEM () { 0x0025 } # GetSystemDirectory() | |
142 | sub CSIDL_PROGRAM_FILES () { 0x0026 } # C:\Program Files | |
143 | sub CSIDL_MYPICTURES () { 0x0027 } # "My Pictures", new for Win2K | |
144 | sub CSIDL_PROFILE () { 0x0028 } # USERPROFILE | |
145 | sub CSIDL_PROGRAM_FILES_COMMON () { 0x002B } # C:\Program Files\Common | |
146 | sub CSIDL_COMMON_TEMPLATES () { 0x002D } # All Users\Templates | |
147 | sub CSIDL_COMMON_DOCUMENTS () { 0x002E } # All Users\Documents | |
148 | sub CSIDL_COMMON_ADMINTOOLS () { 0x002F } # All Users\Start Menu\Programs\Administrative Tools | |
149 | sub CSIDL_ADMINTOOLS () { 0x0030 } # <user name>\Start Menu\Programs\Administrative Tools | |
150 | sub CSIDL_COMMON_MUSIC () { 0x0035 } # All Users\My Music | |
151 | sub CSIDL_COMMON_PICTURES () { 0x0036 } # All Users\My Pictures | |
152 | sub CSIDL_COMMON_VIDEO () { 0x0037 } # All Users\My Video | |
153 | sub CSIDL_RESOURCES () { 0x0038 } # %windir%\Resources\, For theme and other windows resources. | |
154 | sub CSIDL_RESOURCES_LOCALIZED () { 0x0039 } # %windir%\Resources\<LangID>, for theme and other windows specific resources. | |
155 | sub CSIDL_CDBURN_AREA () { 0x003B } # <user name>\Local Settings\Application Data\Microsoft\CD Burning | |
156 | ||
157 | ### This method is just a simple interface into GetOSVersion(). More | |
158 | ### specific or demanding situations should use that instead. | |
159 | ||
160 | my ($found_os, $found_desc); | |
161 | ||
162 | sub GetOSName { | |
163 | my ($os,$desc,$major, $minor, $build, $id)=("",""); | |
164 | unless (defined $found_os) { | |
165 | # If we have a run this already, we have the results cached | |
166 | # If so, return them | |
167 | ||
168 | # Use the standard API call to determine the version | |
169 | ($desc, $major, $minor, $build, $id) = Win32::GetOSVersion(); | |
170 | ||
171 | # If id==0 then its a win32s box -- Meaning Win3.11 | |
172 | unless($id) { | |
173 | $os = 'Win32s'; | |
174 | } | |
175 | else { | |
176 | # Magic numbers from MSDN documentation of OSVERSIONINFO | |
177 | # Most version names can be parsed from just the id and minor | |
178 | # version | |
179 | $os = { | |
180 | 1 => { | |
181 | 0 => "95", | |
182 | 10 => "98", | |
183 | 90 => "Me" | |
184 | }, | |
185 | 2 => { | |
b76aa5af | 186 | 0 => "NT4", |
b4ad57f4 | 187 | 1 => "XP/.Net", |
b76aa5af | 188 | 2 => "2003", |
b4ad57f4 NC |
189 | 51 => "NT3.51" |
190 | } | |
191 | }->{$id}->{$minor}; | |
192 | } | |
193 | ||
194 | # This _really_ shouldnt happen. At least not for quite a while | |
195 | # Politely warn and return undef | |
196 | unless (defined $os) { | |
197 | warn qq[Windows version [$id:$major:$minor] unknown!]; | |
198 | return undef; | |
199 | } | |
200 | ||
201 | my $tag = ""; | |
202 | ||
b76aa5af JD |
203 | # But distinguising W2k and Vista from NT4 requires looking at the major version |
204 | if ($os eq "NT4") { | |
205 | $os = {5 => "2000", 6 => "Vista"}->{$major} || "NT4"; | |
b4ad57f4 NC |
206 | } |
207 | ||
208 | # For the rest we take a look at the build numbers and try to deduce | |
209 | # the exact release name, but we put that in the $desc | |
210 | elsif ($os eq "95") { | |
211 | if ($build eq '67109814') { | |
212 | $tag = '(a)'; | |
213 | } | |
214 | elsif ($build eq '67306684') { | |
215 | $tag = '(b1)'; | |
216 | } | |
217 | elsif ($build eq '67109975') { | |
218 | $tag = '(b2)'; | |
219 | } | |
220 | } | |
221 | elsif ($os eq "98" && $build eq '67766446') { | |
222 | $tag = '(2nd ed)'; | |
223 | } | |
224 | ||
225 | if (length $tag) { | |
226 | if (length $desc) { | |
227 | $desc = "$tag $desc"; | |
228 | } | |
229 | else { | |
230 | $desc = $tag; | |
231 | } | |
232 | } | |
233 | ||
234 | # cache the results, so we dont have to do this again | |
235 | $found_os = "Win$os"; | |
236 | $found_desc = $desc; | |
237 | } | |
238 | ||
239 | return wantarray ? ($found_os, $found_desc) : $found_os; | |
240 | } | |
241 | ||
34f7f30d SH |
242 | # "no warnings 'redefine';" doesn't work for 5.8.7 and earlier |
243 | local $^W = 0; | |
b4ad57f4 NC |
244 | bootstrap Win32; |
245 | ||
246 | 1; | |
247 | ||
248 | __END__ | |
249 | ||
1674ad2b JD |
250 | =head1 NAME |
251 | ||
252 | Win32 - Interfaces to some Win32 API Functions | |
253 | ||
254 | =head1 DESCRIPTION | |
255 | ||
82adc83d | 256 | The Win32 module contains functions to access Win32 APIs. |
1674ad2b JD |
257 | |
258 | =head2 Alphabetical Listing of Win32 Functions | |
259 | ||
82adc83d YST |
260 | It is recommended to C<use Win32;> before any of these functions; |
261 | however, for backwards compatibility, those marked as [CORE] will | |
262 | automatically do this for you. | |
263 | ||
34f7f30d SH |
264 | In the function descriptions below the term I<Unicode string> is used |
265 | to indicate that the string may contain characters outside the system | |
266 | codepage. The caveat I<If supported by the core Perl version> | |
267 | generally means Perl 5.8.9 and later, though some Unicode pathname | |
268 | functionality may work on earlier versions. | |
269 | ||
1674ad2b JD |
270 | =over |
271 | ||
272 | =item Win32::AbortSystemShutdown(MACHINE) | |
273 | ||
82adc83d | 274 | Aborts a system shutdown (started by the |
1674ad2b JD |
275 | InitiateSystemShutdown function) on the specified MACHINE. |
276 | ||
277 | =item Win32::BuildNumber() | |
278 | ||
b4ad57f4 | 279 | [CORE] Returns the ActivePerl build number. This function is |
1674ad2b JD |
280 | only available in the ActivePerl binary distribution. |
281 | ||
282 | =item Win32::CopyFile(FROM, TO, OVERWRITE) | |
283 | ||
625a29bd | 284 | [CORE] The Win32::CopyFile() function copies an existing file to a new |
b4ad57f4 NC |
285 | file. All file information like creation time and file attributes will |
286 | be copied to the new file. However it will B<not> copy the security | |
287 | information. If the destination file already exists it will only be | |
288 | overwritten when the OVERWRITE parameter is true. But even this will | |
625a29bd GS |
289 | not overwrite a read-only file; you have to unlink() it first |
290 | yourself. | |
1674ad2b | 291 | |
34f7f30d SH |
292 | =item Win32::CreateDirectory(DIRECTORY) |
293 | ||
294 | Creates the DIRECTORY and returns a true value on success. Check $^E | |
295 | on failure for extended error information. | |
296 | ||
297 | DIRECTORY may contain Unicode characters outside the system codepage. | |
298 | Once the directory has been created you can use | |
299 | Win32::GetANSIPathName() to get a name that can be passed to system | |
300 | calls and external programs. | |
301 | ||
302 | =item Win32::CreateFile(FILE) | |
303 | ||
304 | Creates the FILE and returns a true value on success. Check $^E on | |
305 | failure for extended error information. | |
306 | ||
307 | FILE may contain Unicode characters outside the system codepage. Once | |
308 | the file has been created you can use Win32::GetANSIPathName() to get | |
309 | a name that can be passed to system calls and external programs. | |
310 | ||
1674ad2b JD |
311 | =item Win32::DomainName() |
312 | ||
166cd87e SH |
313 | [CORE] Returns the name of the Microsoft Network domain or workgroup |
314 | that the owner of the current perl process is logged into. The | |
315 | "Workstation" service must be running to determine this | |
316 | information. This function does B<not> work on Windows 9x. | |
1674ad2b JD |
317 | |
318 | =item Win32::ExpandEnvironmentStrings(STRING) | |
319 | ||
82adc83d | 320 | Takes STRING and replaces all referenced environment variable |
b4ad57f4 NC |
321 | names with their defined values. References to environment variables |
322 | take the form C<%VariableName%>. Case is ignored when looking up the | |
323 | VariableName in the environment. If the variable is not found then the | |
1674ad2b JD |
324 | original C<%VariableName%> text is retained. Has the same effect |
325 | as the following: | |
326 | ||
327 | $string =~ s/%([^%]*)%/$ENV{$1} || "%$1%"/eg | |
328 | ||
34f7f30d SH |
329 | However, this function may return a Unicode string if the environment |
330 | variable being expanded hasn't been assigned to via %ENV. Access | |
331 | to %ENV is currently always using byte semantics. | |
332 | ||
1674ad2b JD |
333 | =item Win32::FormatMessage(ERRORCODE) |
334 | ||
335 | [CORE] Converts the supplied Win32 error number (e.g. returned by | |
336 | Win32::GetLastError()) to a descriptive string. Analogous to the | |
337 | perror() standard-C library function. Note that C<$^E> used | |
338 | in a string context has much the same effect. | |
339 | ||
340 | C:\> perl -e "$^E = 26; print $^E;" | |
341 | The specified disk or diskette cannot be accessed | |
342 | ||
343 | =item Win32::FsType() | |
344 | ||
345 | [CORE] Returns the name of the filesystem of the currently active | |
b4ad57f4 NC |
346 | drive (like 'FAT' or 'NTFS'). In list context it returns three values: |
347 | (FSTYPE, FLAGS, MAXCOMPLEN). FSTYPE is the filesystem type as | |
348 | before. FLAGS is a combination of values of the following table: | |
1674ad2b JD |
349 | |
350 | 0x00000001 supports case-sensitive filenames | |
351 | 0x00000002 preserves the case of filenames | |
352 | 0x00000004 supports Unicode in filenames | |
353 | 0x00000008 preserves and enforces ACLs | |
354 | 0x00000010 supports file-based compression | |
355 | 0x00000020 supports disk quotas | |
356 | 0x00000040 supports sparse files | |
357 | 0x00000080 supports reparse points | |
358 | 0x00000100 supports remote storage | |
359 | 0x00008000 is a compressed volume (e.g. DoubleSpace) | |
360 | 0x00010000 supports object identifiers | |
361 | 0x00020000 supports the Encrypted File System (EFS) | |
362 | ||
363 | MAXCOMPLEN is the maximum length of a filename component (the part | |
364 | between two backslashes) on this file system. | |
365 | ||
366 | =item Win32::FreeLibrary(HANDLE) | |
367 | ||
82adc83d | 368 | Unloads a previously loaded dynamic-link library. The HANDLE is |
b4ad57f4 | 369 | no longer valid after this call. See L<LoadLibrary|Win32::LoadLibrary(LIBNAME)> |
4a4eefd0 | 370 | for information on dynamically loading a library. |
1674ad2b | 371 | |
34f7f30d SH |
372 | =item Win32::GetANSIPathName(FILENAME) |
373 | ||
374 | Returns an ANSI version of FILENAME. This may be the short name | |
375 | if the long name cannot be represented in the system codepage. | |
376 | ||
377 | While not currently implemented, it is possible that in the future | |
378 | this function will convert only parts of the path to FILENAME to a | |
379 | short form. | |
380 | ||
381 | If FILENAME doesn't exist on the filesystem, or if the filesystem | |
382 | doesn't support short ANSI filenames, then this function will | |
383 | translate the Unicode name into the system codepage using replacement | |
384 | characters. | |
385 | ||
1674ad2b JD |
386 | =item Win32::GetArchName() |
387 | ||
82adc83d | 388 | Use of this function is deprecated. It is equivalent with |
b4ad57f4 | 389 | $ENV{PROCESSOR_ARCHITECTURE}. This might not work on Win9X. |
1674ad2b JD |
390 | |
391 | =item Win32::GetChipName() | |
392 | ||
82adc83d | 393 | Returns the processor type: 386, 486 or 586 for Intel processors, |
1674ad2b JD |
394 | 21064 for the Alpha chip. |
395 | ||
396 | =item Win32::GetCwd() | |
397 | ||
b4ad57f4 | 398 | [CORE] Returns the current active drive and directory. This function |
1674ad2b JD |
399 | does not return a UNC path, since the functionality required for such |
400 | a feature is not available under Windows 95. | |
401 | ||
34f7f30d SH |
402 | If supported by the core Perl version, this function will return an |
403 | ANSI path name for the current directory if the long pathname cannot | |
404 | be represented in the system codepage. | |
405 | ||
280cf07e SH |
406 | =item Win32::GetCurrentProcessId() |
407 | ||
408 | Returns the process identifier of the current process. Until the | |
409 | process terminates, the process identifier uniquely identifies the | |
410 | process throughout the system. | |
411 | ||
412 | The current process identifier is normally also available via the | |
413 | predefined $$ variable. Under fork() emulation however $$ may contain | |
414 | a pseudo-process identifier that is only meaningful to the Perl | |
415 | kill(), wait() and waitpid() functions. The | |
416 | Win32::GetCurrentProcessId() function will always return the regular | |
417 | Windows process id, even when called from inside a pseudo-process. | |
418 | ||
34f7f30d SH |
419 | =item Win32::GetCurrentThreadId() |
420 | ||
421 | Returns the thread identifier of the calling thread. Until the thread | |
422 | terminates, the thread identifier uniquely identifies the thread | |
423 | throughout the system. | |
424 | ||
e364e11c JD |
425 | =item Win32::GetFileVersion(FILENAME) |
426 | ||
82adc83d | 427 | Returns the file version number from the VERSIONINFO resource of |
e364e11c JD |
428 | the executable file or DLL. This is a tuple of four 16 bit numbers. |
429 | In list context these four numbers will be returned. In scalar context | |
430 | they are concatenated into a string, separated by dots. | |
431 | ||
87755fa7 GS |
432 | =item Win32::GetFolderPath(FOLDER [, CREATE]) |
433 | ||
82adc83d | 434 | Returns the full pathname of one of the Windows special folders. |
87755fa7 GS |
435 | The folder will be created if it doesn't exist and the optional CREATE |
436 | argument is true. The following FOLDER constants are defined by the | |
437 | Win32 module, but only exported on demand: | |
438 | ||
439 | CSIDL_ADMINTOOLS | |
440 | CSIDL_APPDATA | |
441 | CSIDL_CDBURN_AREA | |
442 | CSIDL_COMMON_ADMINTOOLS | |
443 | CSIDL_COMMON_APPDATA | |
444 | CSIDL_COMMON_DESKTOPDIRECTORY | |
445 | CSIDL_COMMON_DOCUMENTS | |
446 | CSIDL_COMMON_FAVORITES | |
447 | CSIDL_COMMON_MUSIC | |
448 | CSIDL_COMMON_PICTURES | |
449 | CSIDL_COMMON_PROGRAMS | |
450 | CSIDL_COMMON_STARTMENU | |
451 | CSIDL_COMMON_STARTUP | |
452 | CSIDL_COMMON_TEMPLATES | |
453 | CSIDL_COMMON_VIDEO | |
454 | CSIDL_COOKIES | |
455 | CSIDL_DESKTOP | |
456 | CSIDL_DESKTOPDIRECTORY | |
457 | CSIDL_FAVORITES | |
458 | CSIDL_FONTS | |
459 | CSIDL_HISTORY | |
460 | CSIDL_INTERNET_CACHE | |
461 | CSIDL_LOCAL_APPDATA | |
462 | CSIDL_MYMUSIC | |
463 | CSIDL_MYPICTURES | |
464 | CSIDL_MYVIDEO | |
465 | CSIDL_NETHOOD | |
466 | CSIDL_PERSONAL | |
467 | CSIDL_PRINTHOOD | |
468 | CSIDL_PROFILE | |
469 | CSIDL_PROGRAMS | |
470 | CSIDL_PROGRAM_FILES | |
471 | CSIDL_PROGRAM_FILES_COMMON | |
472 | CSIDL_RECENT | |
473 | CSIDL_RESOURCES | |
474 | CSIDL_RESOURCES_LOCALIZED | |
475 | CSIDL_SENDTO | |
476 | CSIDL_STARTMENU | |
477 | CSIDL_STARTUP | |
478 | CSIDL_SYSTEM | |
479 | CSIDL_TEMPLATES | |
480 | CSIDL_WINDOWS | |
481 | ||
482 | Note that not all folders are defined on all versions of Windows. | |
483 | ||
484 | Please refer to the MSDN documentation of the CSIDL constants, | |
485 | currently available at: | |
486 | ||
487 | http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/shell/reference/enums/csidl.asp | |
488 | ||
34f7f30d SH |
489 | This function will return an ANSI folder path if the long name cannot |
490 | be represented in the system codepage. Use Win32::GetLongPathName() | |
491 | on the result of Win32::GetFolderPath() if you want the Unicode | |
492 | version of the folder name. | |
493 | ||
1674ad2b JD |
494 | =item Win32::GetFullPathName(FILENAME) |
495 | ||
496 | [CORE] GetFullPathName combines the FILENAME with the current drive | |
497 | and directory name and returns a fully qualified (aka, absolute) | |
b4ad57f4 | 498 | path name. In list context it returns two elements: (PATH, FILE) where |
1674ad2b JD |
499 | PATH is the complete pathname component (including trailing backslash) |
500 | and FILE is just the filename part. Note that no attempt is made to | |
501 | convert 8.3 components in the supplied FILENAME to longnames or | |
34f7f30d SH |
502 | vice-versa. Compare with Win32::GetShortPathName() and |
503 | Win32::GetLongPathName(). | |
504 | ||
505 | If supported by the core Perl version, this function will return an | |
506 | ANSI path name if the full pathname cannot be represented in the | |
507 | system codepage. | |
1674ad2b JD |
508 | |
509 | =item Win32::GetLastError() | |
510 | ||
511 | [CORE] Returns the last error value generated by a call to a Win32 API | |
512 | function. Note that C<$^E> used in a numeric context amounts to the | |
513 | same value. | |
514 | ||
515 | =item Win32::GetLongPathName(PATHNAME) | |
516 | ||
4375e838 | 517 | [CORE] Returns a representation of PATHNAME composed of longname |
da2094fd | 518 | components (if any). The result may not necessarily be longer |
1674ad2b | 519 | than PATHNAME. No attempt is made to convert PATHNAME to the |
34f7f30d SH |
520 | absolute path. Compare with Win32::GetShortPathName() and |
521 | Win32::GetFullPathName(). | |
522 | ||
523 | This function may return the pathname in Unicode if it cannot be | |
524 | represented in the system codepage. Use Win32::GetANSIPathName() | |
525 | before passing the path to a system call or another program. | |
1674ad2b | 526 | |
1674ad2b JD |
527 | =item Win32::GetNextAvailDrive() |
528 | ||
529 | [CORE] Returns a string in the form of "<d>:" where <d> is the first | |
530 | available drive letter. | |
531 | ||
532 | =item Win32::GetOSVersion() | |
533 | ||
3e526985 | 534 | [CORE] Returns the list (STRING, MAJOR, MINOR, BUILD, ID), where the |
d10f8d7a YO |
535 | elements are, respectively: An arbitrary descriptive string, the major |
536 | version number of the operating system, the minor version number, the | |
537 | build number, and a digit indicating the actual operating system. | |
3e526985 | 538 | For the ID, the values are 0 for Win32s, 1 for Windows 9X/Me and 2 for |
b69c7e13 | 539 | Windows NT/2000/XP/2003/Vista. In scalar context it returns just the ID. |
d10f8d7a YO |
540 | |
541 | Currently known values for ID MAJOR and MINOR are as follows: | |
542 | ||
543 | OS ID MAJOR MINOR | |
544 | Win32s 0 - - | |
545 | Windows 95 1 4 0 | |
546 | Windows 98 1 4 10 | |
547 | Windows Me 1 4 90 | |
548 | Windows NT 3.51 2 3 51 | |
549 | Windows NT 4 2 4 0 | |
550 | Windows 2000 2 5 0 | |
551 | Windows XP 2 5 1 | |
3e526985 | 552 | Windows Server 2003 2 5 2 |
b76aa5af | 553 | Windows Vista 2 6 0 |
3e526985 JD |
554 | |
555 | On Windows NT 4 SP6 and later this function returns the following | |
556 | additional values: SPMAJOR, SPMINOR, SUITEMASK, PRODUCTTYPE. | |
557 | ||
558 | SPMAJOR and SPMINOR are are the version numbers of the latest | |
559 | installed service pack. | |
560 | ||
561 | SUITEMASK is a bitfield identifying the product suites available on | |
562 | the system. Known bits are: | |
563 | ||
564 | VER_SUITE_SMALLBUSINESS 0x00000001 | |
565 | VER_SUITE_ENTERPRISE 0x00000002 | |
566 | VER_SUITE_BACKOFFICE 0x00000004 | |
567 | VER_SUITE_COMMUNICATIONS 0x00000008 | |
568 | VER_SUITE_TERMINAL 0x00000010 | |
569 | VER_SUITE_SMALLBUSINESS_RESTRICTED 0x00000020 | |
570 | VER_SUITE_EMBEDDEDNT 0x00000040 | |
571 | VER_SUITE_DATACENTER 0x00000080 | |
572 | VER_SUITE_SINGLEUSERTS 0x00000100 | |
573 | VER_SUITE_PERSONAL 0x00000200 | |
574 | VER_SUITE_BLADE 0x00000400 | |
575 | VER_SUITE_EMBEDDED_RESTRICTED 0x00000800 | |
576 | VER_SUITE_SECURITY_APPLIANCE 0x00001000 | |
577 | ||
578 | The VER_SUITE_xxx names are listed here to crossreference the Microsoft | |
579 | documentation. The Win32 module does not provide symbolic names for these | |
580 | constants. | |
581 | ||
582 | PRODUCTTYPE provides additional information about the system. It should | |
583 | be one of the following integer values: | |
584 | ||
b69c7e13 | 585 | 1 - Workstation (NT 4, 2000 Pro, XP Home, XP Pro, Vista) |
3e526985 JD |
586 | 2 - Domaincontroller |
587 | 3 - Server | |
d10f8d7a YO |
588 | |
589 | =item Win32::GetOSName() | |
590 | ||
82adc83d | 591 | In scalar context returns the name of the Win32 operating system |
d10f8d7a YO |
592 | being used. In list context returns a two element list of the OS name |
593 | and whatever edition information is known about the particular build | |
b4ad57f4 | 594 | (for Win9X boxes) and whatever service packs have been installed. |
d10f8d7a YO |
595 | The latter is roughly equivalent to the first item returned by |
596 | GetOSVersion() in list context. | |
597 | ||
598 | Currently the possible values for the OS name are | |
599 | ||
b69c7e13 | 600 | Win32s Win95 Win98 WinMe WinNT3.51 WinNT4 Win2000 WinXP/.Net Win2003 WinVista |
d10f8d7a YO |
601 | |
602 | This routine is just a simple interface into GetOSVersion(). More | |
603 | specific or demanding situations should use that instead. Another | |
604 | option would be to use POSIX::uname(), however the latter appears to | |
605 | report only the OS family name and not the specific OS. In scalar | |
606 | context it returns just the ID. | |
1674ad2b | 607 | |
3e526985 JD |
608 | The name "WinXP/.Net" is used for historical reasons only, to maintain |
609 | backwards compatibility of the Win32 module. Windows .NET Server has | |
610 | been renamed as Windows 2003 Server before final release and uses a | |
611 | different major/minor version number than Windows XP. | |
612 | ||
1674ad2b JD |
613 | =item Win32::GetShortPathName(PATHNAME) |
614 | ||
eb6bfc3a GA |
615 | [CORE] Returns a representation of PATHNAME that is composed of short |
616 | (8.3) path components where available. For path components where the | |
617 | file system has not generated the short form the returned path will | |
618 | use the long form, so this function might still for instance return a | |
b3eb56ab SH |
619 | path containing spaces. Returns C<undef> when the PATHNAME does not |
620 | exist. Compare with Win32::GetFullPathName() and | |
34f7f30d | 621 | Win32::GetLongPathName(). |
1674ad2b JD |
622 | |
623 | =item Win32::GetProcAddress(INSTANCE, PROCNAME) | |
624 | ||
82adc83d | 625 | Returns the address of a function inside a loaded library. The |
1674ad2b | 626 | information about what you can do with this address has been lost in |
b4ad57f4 | 627 | the mist of time. Use the Win32::API module instead of this deprecated |
1674ad2b JD |
628 | function. |
629 | ||
630 | =item Win32::GetTickCount() | |
631 | ||
632 | [CORE] Returns the number of milliseconds elapsed since the last | |
b4ad57f4 | 633 | system boot. Resolution is limited to system timer ticks (about 10ms |
1674ad2b JD |
634 | on WinNT and 55ms on Win9X). |
635 | ||
e364e11c JD |
636 | =item Win32::GuidGen() |
637 | ||
82adc83d | 638 | Creates a globally unique 128 bit integer that can be used as a |
e364e11c JD |
639 | persistent identifier in a distributed setting. To a very high degree |
640 | of certainty this function returns a unique value. No other | |
641 | invocation, on the same or any other system (networked or not), should | |
642 | return the same value. | |
643 | ||
644 | The return value is formatted according to OLE conventions, as groups | |
645 | of hex digits with surrounding braces. For example: | |
646 | ||
647 | {09531CF1-D0C7-4860-840C-1C8C8735E2AD} | |
648 | ||
cb49b31f | 649 | =item Win32::InitiateSystemShutdown |
551e1d92 | 650 | |
cb49b31f | 651 | (MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT) |
1674ad2b | 652 | |
82adc83d | 653 | Shutsdown the specified MACHINE, notifying users with the |
b4ad57f4 | 654 | supplied MESSAGE, within the specified TIMEOUT interval. Forces |
1674ad2b | 655 | closing of all documents without prompting the user if FORCECLOSE is |
b4ad57f4 | 656 | true, and reboots the machine if REBOOT is true. This function works |
1674ad2b JD |
657 | only on WinNT. |
658 | ||
b4ad57f4 NC |
659 | =item Win32::IsAdminUser() |
660 | ||
82adc83d | 661 | Returns non zero if the account in whose security context the |
b4ad57f4 NC |
662 | current process/thread is running belongs to the local group of |
663 | Administrators in the built-in system domain; returns 0 if not. | |
34f7f30d | 664 | On Windows Vista it will only return non-zero if the process is |
b3eb56ab SH |
665 | actually running with elevated privileges. Returns C<undef> |
666 | and prints a warning if an error occurred. This function always | |
34f7f30d | 667 | returns 1 on Win9X. |
b4ad57f4 | 668 | |
1674ad2b JD |
669 | =item Win32::IsWinNT() |
670 | ||
671 | [CORE] Returns non zero if the Win32 subsystem is Windows NT. | |
672 | ||
673 | =item Win32::IsWin95() | |
674 | ||
675 | [CORE] Returns non zero if the Win32 subsystem is Windows 95. | |
676 | ||
677 | =item Win32::LoadLibrary(LIBNAME) | |
678 | ||
82adc83d | 679 | Loads a dynamic link library into memory and returns its module |
34f7f30d SH |
680 | handle. This handle can be used with Win32::GetProcAddress() and |
681 | Win32::FreeLibrary(). This function is deprecated. Use the Win32::API | |
1674ad2b JD |
682 | module instead. |
683 | ||
684 | =item Win32::LoginName() | |
685 | ||
686 | [CORE] Returns the username of the owner of the current perl process. | |
34f7f30d | 687 | The return value may be a Unicode string. |
1674ad2b JD |
688 | |
689 | =item Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE) | |
690 | ||
82adc83d | 691 | Looks up ACCOUNT on SYSTEM and returns the domain name the SID and |
1674ad2b JD |
692 | the SID type. |
693 | ||
694 | =item Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE) | |
695 | ||
82adc83d | 696 | Looks up SID on SYSTEM and returns the account name, domain name, |
1674ad2b JD |
697 | and the SID type. |
698 | ||
699 | =item Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]]) | |
700 | ||
82adc83d | 701 | Create a dialogbox containing MESSAGE. FLAGS specifies the |
1674ad2b JD |
702 | required icon and buttons according to the following table: |
703 | ||
704 | 0 = OK | |
705 | 1 = OK and Cancel | |
706 | 2 = Abort, Retry, and Ignore | |
707 | 3 = Yes, No and Cancel | |
708 | 4 = Yes and No | |
709 | 5 = Retry and Cancel | |
710 | ||
711 | MB_ICONSTOP "X" in a red circle | |
712 | MB_ICONQUESTION question mark in a bubble | |
713 | MB_ICONEXCLAMATION exclamation mark in a yellow triangle | |
714 | MB_ICONINFORMATION "i" in a bubble | |
715 | ||
b4ad57f4 | 716 | TITLE specifies an optional window title. The default is "Perl". |
1674ad2b JD |
717 | |
718 | The function returns the menu id of the selected push button: | |
719 | ||
720 | 0 Error | |
721 | ||
722 | 1 OK | |
723 | 2 Cancel | |
724 | 3 Abort | |
725 | 4 Retry | |
726 | 5 Ignore | |
727 | 6 Yes | |
728 | 7 No | |
729 | ||
730 | =item Win32::NodeName() | |
731 | ||
732 | [CORE] Returns the Microsoft Network node-name of the current machine. | |
733 | ||
34f7f30d SH |
734 | =item Win32::OutputDebugString(STRING) |
735 | ||
736 | Sends a string to the application or system debugger for display. | |
737 | The function does nothing if there is no active debugger. | |
738 | ||
739 | Alternatively one can use the I<Debug Viewer> application to | |
740 | watch the OutputDebugString() output: | |
741 | ||
742 | http://www.microsoft.com/technet/sysinternals/utilities/debugview.mspx | |
743 | ||
1674ad2b JD |
744 | =item Win32::RegisterServer(LIBRARYNAME) |
745 | ||
82adc83d | 746 | Loads the DLL LIBRARYNAME and calls the function DllRegisterServer. |
1674ad2b | 747 | |
02637f4c JD |
748 | =item Win32::SetChildShowWindow(SHOWWINDOW) |
749 | ||
750 | [CORE] Sets the I<ShowMode> of child processes started by system(). | |
751 | By default system() will create a new console window for child | |
b4ad57f4 | 752 | processes if Perl itself is not running from a console. Calling |
02637f4c JD |
753 | SetChildShowWindow(0) will make these new console windows invisible. |
754 | Calling SetChildShowWindow() without arguments reverts system() to the | |
755 | default behavior. The return value of SetChildShowWindow() is the | |
34f7f30d | 756 | previous setting or C<undef>. |
02637f4c | 757 | |
82adc83d | 758 | The following symbolic constants for SHOWWINDOW are available |
02637f4c JD |
759 | (but not exported) from the Win32 module: SW_HIDE, SW_SHOWNORMAL, |
760 | SW_SHOWMINIMIZED, SW_SHOWMAXIMIZED and SW_SHOWNOACTIVATE. | |
761 | ||
1674ad2b JD |
762 | =item Win32::SetCwd(NEWDIRECTORY) |
763 | ||
b4ad57f4 | 764 | [CORE] Sets the current active drive and directory. This function does not |
1674ad2b JD |
765 | work with UNC paths, since the functionality required to required for |
766 | such a feature is not available under Windows 95. | |
767 | ||
768 | =item Win32::SetLastError(ERROR) | |
769 | ||
b4ad57f4 | 770 | [CORE] Sets the value of the last error encountered to ERROR. This is |
1674ad2b | 771 | that value that will be returned by the Win32::GetLastError() |
b4ad57f4 | 772 | function. |
1674ad2b JD |
773 | |
774 | =item Win32::Sleep(TIME) | |
775 | ||
b4ad57f4 | 776 | [CORE] Pauses for TIME milliseconds. The timeslices are made available |
1674ad2b JD |
777 | to other processes and threads. |
778 | ||
779 | =item Win32::Spawn(COMMAND, ARGS, PID) | |
780 | ||
781 | [CORE] Spawns a new process using the supplied COMMAND, passing in | |
b4ad57f4 NC |
782 | arguments in the string ARGS. The pid of the new process is stored in |
783 | PID. This function is deprecated. Please use the Win32::Process module | |
1674ad2b JD |
784 | instead. |
785 | ||
786 | =item Win32::UnregisterServer(LIBRARYNAME) | |
787 | ||
82adc83d | 788 | Loads the DLL LIBRARYNAME and calls the function |
1674ad2b JD |
789 | DllUnregisterServer. |
790 | ||
791 | =back | |
792 | ||
793 | =cut |