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