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 the |
---|
152 | elements are, respectively: An arbitrary descriptive string, the major |
---|
153 | version number of the operating system, the minor version number, the |
---|
154 | build number, and a digit indicating the actual operating system. |
---|
155 | For the ID, the values are 0 for Win32s, 1 for Windows 9X and 2 for |
---|
156 | Windows NT/2000/XP. In scalar context it returns just the ID. |
---|
157 | |
---|
158 | Currently known values for ID MAJOR and MINOR are as follows: |
---|
159 | |
---|
160 | OS ID MAJOR MINOR |
---|
161 | Win32s 0 - - |
---|
162 | Windows 95 1 4 0 |
---|
163 | Windows 98 1 4 10 |
---|
164 | Windows Me 1 4 90 |
---|
165 | Windows NT 3.51 2 3 51 |
---|
166 | Windows NT 4 2 4 0 |
---|
167 | Windows 2000 2 5 0 |
---|
168 | Windows XP 2 5 1 |
---|
169 | Windows .NET Server 2 5 1 |
---|
170 | |
---|
171 | Unfortunately as of June 2002 there is no way to distinguish between |
---|
172 | .NET servers and XP servers without using additional modules. |
---|
173 | |
---|
174 | =item Win32::GetOSName() |
---|
175 | |
---|
176 | [EXT] In scalar context returns the name of the Win32 operating system |
---|
177 | being used. In list context returns a two element list of the OS name |
---|
178 | and whatever edition information is known about the particular build |
---|
179 | (for Win9x boxes) and whatever service packs have been installed. |
---|
180 | The latter is roughly equivalent to the first item returned by |
---|
181 | GetOSVersion() in list context. |
---|
182 | |
---|
183 | Currently the possible values for the OS name are |
---|
184 | |
---|
185 | Win32s Win95 Win98 WinMe Win2000 WinXP/.Net WinNT3.51 WinNT4 |
---|
186 | |
---|
187 | This routine is just a simple interface into GetOSVersion(). More |
---|
188 | specific or demanding situations should use that instead. Another |
---|
189 | option would be to use POSIX::uname(), however the latter appears to |
---|
190 | report only the OS family name and not the specific OS. In scalar |
---|
191 | context it returns just the ID. |
---|
192 | |
---|
193 | =item Win32::GetShortPathName(PATHNAME) |
---|
194 | |
---|
195 | [CORE] Returns a representation of PATHNAME composed only of |
---|
196 | short (8.3) path components. The result may not necessarily be |
---|
197 | shorter than PATHNAME. Compare with Win32::GetFullPathName and |
---|
198 | Win32::GetLongPathName. |
---|
199 | |
---|
200 | =item Win32::GetProcAddress(INSTANCE, PROCNAME) |
---|
201 | |
---|
202 | [EXT] Returns the address of a function inside a loaded library. The |
---|
203 | information about what you can do with this address has been lost in |
---|
204 | the mist of time. Use the Win32::API module instead of this deprecated |
---|
205 | function. |
---|
206 | |
---|
207 | =item Win32::GetTickCount() |
---|
208 | |
---|
209 | [CORE] Returns the number of milliseconds elapsed since the last |
---|
210 | system boot. Resolution is limited to system timer ticks (about 10ms |
---|
211 | on WinNT and 55ms on Win9X). |
---|
212 | |
---|
213 | =item Win32::InitiateSystemShutdown |
---|
214 | |
---|
215 | (MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT) |
---|
216 | |
---|
217 | [EXT] Shutsdown the specified MACHINE, notifying users with the |
---|
218 | supplied MESSAGE, within the specified TIMEOUT interval. Forces |
---|
219 | closing of all documents without prompting the user if FORCECLOSE is |
---|
220 | true, and reboots the machine if REBOOT is true. This function works |
---|
221 | only on WinNT. |
---|
222 | |
---|
223 | =item Win32::IsWinNT() |
---|
224 | |
---|
225 | [CORE] Returns non zero if the Win32 subsystem is Windows NT. |
---|
226 | |
---|
227 | =item Win32::IsWin95() |
---|
228 | |
---|
229 | [CORE] Returns non zero if the Win32 subsystem is Windows 95. |
---|
230 | |
---|
231 | =item Win32::LoadLibrary(LIBNAME) |
---|
232 | |
---|
233 | [EXT] Loads a dynamic link library into memory and returns its module |
---|
234 | handle. This handle can be used with Win32::GetProcAddress and |
---|
235 | Win32::FreeLibrary. This function is deprecated. Use the Win32::API |
---|
236 | module instead. |
---|
237 | |
---|
238 | =item Win32::LoginName() |
---|
239 | |
---|
240 | [CORE] Returns the username of the owner of the current perl process. |
---|
241 | |
---|
242 | =item Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE) |
---|
243 | |
---|
244 | [EXT] Looks up ACCOUNT on SYSTEM and returns the domain name the SID and |
---|
245 | the SID type. |
---|
246 | |
---|
247 | =item Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE) |
---|
248 | |
---|
249 | [EXT] Looks up SID on SYSTEM and returns the account name, domain name, |
---|
250 | and the SID type. |
---|
251 | |
---|
252 | =item Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]]) |
---|
253 | |
---|
254 | [EXT] Create a dialogbox containing MESSAGE. FLAGS specifies the |
---|
255 | required icon and buttons according to the following table: |
---|
256 | |
---|
257 | 0 = OK |
---|
258 | 1 = OK and Cancel |
---|
259 | 2 = Abort, Retry, and Ignore |
---|
260 | 3 = Yes, No and Cancel |
---|
261 | 4 = Yes and No |
---|
262 | 5 = Retry and Cancel |
---|
263 | |
---|
264 | MB_ICONSTOP "X" in a red circle |
---|
265 | MB_ICONQUESTION question mark in a bubble |
---|
266 | MB_ICONEXCLAMATION exclamation mark in a yellow triangle |
---|
267 | MB_ICONINFORMATION "i" in a bubble |
---|
268 | |
---|
269 | TITLE specifies an optional window title. The default is "Perl". |
---|
270 | |
---|
271 | The function returns the menu id of the selected push button: |
---|
272 | |
---|
273 | 0 Error |
---|
274 | |
---|
275 | 1 OK |
---|
276 | 2 Cancel |
---|
277 | 3 Abort |
---|
278 | 4 Retry |
---|
279 | 5 Ignore |
---|
280 | 6 Yes |
---|
281 | 7 No |
---|
282 | |
---|
283 | =item Win32::NodeName() |
---|
284 | |
---|
285 | [CORE] Returns the Microsoft Network node-name of the current machine. |
---|
286 | |
---|
287 | =item Win32::RegisterServer(LIBRARYNAME) |
---|
288 | |
---|
289 | [EXT] Loads the DLL LIBRARYNAME and calls the function DllRegisterServer. |
---|
290 | |
---|
291 | =item Win32::SetChildShowWindow(SHOWWINDOW) |
---|
292 | |
---|
293 | [CORE] Sets the I<ShowMode> of child processes started by system(). |
---|
294 | By default system() will create a new console window for child |
---|
295 | processes if Perl itself is not running from a console. Calling |
---|
296 | SetChildShowWindow(0) will make these new console windows invisible. |
---|
297 | Calling SetChildShowWindow() without arguments reverts system() to the |
---|
298 | default behavior. The return value of SetChildShowWindow() is the |
---|
299 | previous setting or C<undef>. |
---|
300 | |
---|
301 | [EXT] The following symbolic constants for SHOWWINDOW are available |
---|
302 | (but not exported) from the Win32 module: SW_HIDE, SW_SHOWNORMAL, |
---|
303 | SW_SHOWMINIMIZED, SW_SHOWMAXIMIZED and SW_SHOWNOACTIVATE. |
---|
304 | |
---|
305 | =item Win32::SetCwd(NEWDIRECTORY) |
---|
306 | |
---|
307 | [CORE] Sets the current active drive and directory. This function does not |
---|
308 | work with UNC paths, since the functionality required to required for |
---|
309 | such a feature is not available under Windows 95. |
---|
310 | |
---|
311 | =item Win32::SetLastError(ERROR) |
---|
312 | |
---|
313 | [CORE] Sets the value of the last error encountered to ERROR. This is |
---|
314 | that value that will be returned by the Win32::GetLastError() |
---|
315 | function. This functions has been added for Perl 5.6. |
---|
316 | |
---|
317 | =item Win32::Sleep(TIME) |
---|
318 | |
---|
319 | [CORE] Pauses for TIME milliseconds. The timeslices are made available |
---|
320 | to other processes and threads. |
---|
321 | |
---|
322 | =item Win32::Spawn(COMMAND, ARGS, PID) |
---|
323 | |
---|
324 | [CORE] Spawns a new process using the supplied COMMAND, passing in |
---|
325 | arguments in the string ARGS. The pid of the new process is stored in |
---|
326 | PID. This function is deprecated. Please use the Win32::Process module |
---|
327 | instead. |
---|
328 | |
---|
329 | =item Win32::UnregisterServer(LIBRARYNAME) |
---|
330 | |
---|
331 | [EXT] Loads the DLL LIBRARYNAME and calls the function |
---|
332 | DllUnregisterServer. |
---|
333 | |
---|
334 | =back |
---|
335 | |
---|
336 | =cut |
---|