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