285 lines
9.3 KiB
Plaintext
285 lines
9.3 KiB
Plaintext
=head1 NAME
|
|
|
|
Win32 - Interfaces to some Win32 API Functions
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
Perl on Win32 contains several functions to access Win32 APIs. Some
|
|
are included in Perl itself (on Win32) and some are only available
|
|
after explicitly requesting the Win32 module with:
|
|
|
|
use Win32;
|
|
|
|
The builtin functions are marked as [CORE] and the other ones
|
|
as [EXT] in the following alphabetical listing. The C<Win32> module
|
|
is not part of the Perl source distribution; it is distributed in
|
|
the libwin32 bundle of Win32::* modules on CPAN. The module is
|
|
already preinstalled in binary distributions like ActivePerl.
|
|
|
|
=head2 Alphabetical Listing of Win32 Functions
|
|
|
|
=over
|
|
|
|
=item Win32::AbortSystemShutdown(MACHINE)
|
|
|
|
[EXT] Aborts a system shutdown (started by the
|
|
InitiateSystemShutdown function) on the specified MACHINE.
|
|
|
|
=item Win32::BuildNumber()
|
|
|
|
[CORE] Returns the ActivePerl build number. This function is
|
|
only available in the ActivePerl binary distribution.
|
|
|
|
=item Win32::CopyFile(FROM, TO, OVERWRITE)
|
|
|
|
[CORE] The Win32::CopyFile() function copies an existing file to a new
|
|
file. All file information like creation time and file attributes will
|
|
be copied to the new file. However it will B<not> copy the security
|
|
information. If the destination file already exists it will only be
|
|
overwritten when the OVERWRITE parameter is true. But even this will
|
|
not overwrite a read-only file; you have to unlink() it first
|
|
yourself.
|
|
|
|
=item Win32::DomainName()
|
|
|
|
[CORE] Returns the name of the Microsoft Network domain that the
|
|
owner of the current perl process is logged into.
|
|
|
|
=item Win32::ExpandEnvironmentStrings(STRING)
|
|
|
|
[EXT] Takes STRING and replaces all referenced environment variable
|
|
names with their defined values. References to environment variables
|
|
take the form C<%VariableName%>. Case is ignored when looking up the
|
|
VariableName in the environment. If the variable is not found then the
|
|
original C<%VariableName%> text is retained. Has the same effect
|
|
as the following:
|
|
|
|
$string =~ s/%([^%]*)%/$ENV{$1} || "%$1%"/eg
|
|
|
|
=item Win32::FormatMessage(ERRORCODE)
|
|
|
|
[CORE] Converts the supplied Win32 error number (e.g. returned by
|
|
Win32::GetLastError()) to a descriptive string. Analogous to the
|
|
perror() standard-C library function. Note that C<$^E> used
|
|
in a string context has much the same effect.
|
|
|
|
C:\> perl -e "$^E = 26; print $^E;"
|
|
The specified disk or diskette cannot be accessed
|
|
|
|
=item Win32::FsType()
|
|
|
|
[CORE] Returns the name of the filesystem of the currently active
|
|
drive (like 'FAT' or 'NTFS'). In list context it returns three values:
|
|
(FSTYPE, FLAGS, MAXCOMPLEN). FSTYPE is the filesystem type as
|
|
before. FLAGS is a combination of values of the following table:
|
|
|
|
0x00000001 supports case-sensitive filenames
|
|
0x00000002 preserves the case of filenames
|
|
0x00000004 supports Unicode in filenames
|
|
0x00000008 preserves and enforces ACLs
|
|
0x00000010 supports file-based compression
|
|
0x00000020 supports disk quotas
|
|
0x00000040 supports sparse files
|
|
0x00000080 supports reparse points
|
|
0x00000100 supports remote storage
|
|
0x00008000 is a compressed volume (e.g. DoubleSpace)
|
|
0x00010000 supports object identifiers
|
|
0x00020000 supports the Encrypted File System (EFS)
|
|
|
|
MAXCOMPLEN is the maximum length of a filename component (the part
|
|
between two backslashes) on this file system.
|
|
|
|
=item Win32::FreeLibrary(HANDLE)
|
|
|
|
[EXT] Unloads a previously loaded dynamic-link library. The HANDLE is
|
|
no longer valid after this call. See L<LoadLibrary|Win32::LoadLibrary(LIBNAME)>
|
|
for information on dynamically loading a library.
|
|
|
|
=item Win32::GetArchName()
|
|
|
|
[EXT] Use of this function is deprecated. It is equivalent with
|
|
$ENV{PROCESSOR_ARCHITECTURE}. This might not work on Win9X.
|
|
|
|
=item Win32::GetChipName()
|
|
|
|
[EXT] Returns the processor type: 386, 486 or 586 for Intel processors,
|
|
21064 for the Alpha chip.
|
|
|
|
=item Win32::GetCwd()
|
|
|
|
[CORE] Returns the current active drive and directory. This function
|
|
does not return a UNC path, since the functionality required for such
|
|
a feature is not available under Windows 95.
|
|
|
|
=item Win32::GetFullPathName(FILENAME)
|
|
|
|
[CORE] GetFullPathName combines the FILENAME with the current drive
|
|
and directory name and returns a fully qualified (aka, absolute)
|
|
path name. In list context it returns two elements: (PATH, FILE) where
|
|
PATH is the complete pathname component (including trailing backslash)
|
|
and FILE is just the filename part. Note that no attempt is made to
|
|
convert 8.3 components in the supplied FILENAME to longnames or
|
|
vice-versa. Compare with Win32::GetShortPathName and
|
|
Win32::GetLongPathName.
|
|
|
|
This function has been added for Perl 5.6.
|
|
|
|
=item Win32::GetLastError()
|
|
|
|
[CORE] Returns the last error value generated by a call to a Win32 API
|
|
function. Note that C<$^E> used in a numeric context amounts to the
|
|
same value.
|
|
|
|
=item Win32::GetLongPathName(PATHNAME)
|
|
|
|
[CORE] Returns a representaion of PATHNAME composed of longname
|
|
components (if any). The result may not necessarily be longer
|
|
than PATHNAME. No attempt is made to convert PATHNAME to the
|
|
absolute path. Compare with Win32::GetShortPathName and
|
|
Win32::GetFullPathName.
|
|
|
|
This function has been added for Perl 5.6.
|
|
|
|
=item Win32::GetNextAvailDrive()
|
|
|
|
[CORE] Returns a string in the form of "<d>:" where <d> is the first
|
|
available drive letter.
|
|
|
|
=item Win32::GetOSVersion()
|
|
|
|
[CORE] Returns the array (STRING, MAJOR, MINOR, BUILD, ID), where
|
|
the elements are, respectively: An arbitrary descriptive string, the
|
|
major version number of the operating system, the minor version
|
|
number, the build number, and a digit indicating the actual operating
|
|
system. For ID, the values are 0 for Win32s, 1 for Windows 9X and 2
|
|
for Windows NT. In scalar context it returns just the ID.
|
|
|
|
=item Win32::GetShortPathName(PATHNAME)
|
|
|
|
[CORE] Returns a representation of PATHNAME composed only of
|
|
short (8.3) path components. The result may not necessarily be
|
|
shorter than PATHNAME. Compare with Win32::GetFullPathName and
|
|
Win32::GetLongPathName.
|
|
|
|
=item Win32::GetProcAddress(INSTANCE, PROCNAME)
|
|
|
|
[EXT] Returns the address of a function inside a loaded library. The
|
|
information about what you can do with this address has been lost in
|
|
the mist of time. Use the Win32::API module instead of this deprecated
|
|
function.
|
|
|
|
=item Win32::GetTickCount()
|
|
|
|
[CORE] Returns the number of milliseconds elapsed since the last
|
|
system boot. Resolution is limited to system timer ticks (about 10ms
|
|
on WinNT and 55ms on Win9X).
|
|
|
|
=item Win32::InitiateSystemShutdown(MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT)
|
|
|
|
[EXT] Shutsdown the specified MACHINE, notifying users with the
|
|
supplied MESSAGE, within the specified TIMEOUT interval. Forces
|
|
closing of all documents without prompting the user if FORCECLOSE is
|
|
true, and reboots the machine if REBOOT is true. This function works
|
|
only on WinNT.
|
|
|
|
=item Win32::IsWinNT()
|
|
|
|
[CORE] Returns non zero if the Win32 subsystem is Windows NT.
|
|
|
|
=item Win32::IsWin95()
|
|
|
|
[CORE] Returns non zero if the Win32 subsystem is Windows 95.
|
|
|
|
=item Win32::LoadLibrary(LIBNAME)
|
|
|
|
[EXT] Loads a dynamic link library into memory and returns its module
|
|
handle. This handle can be used with Win32::GetProcAddress and
|
|
Win32::FreeLibrary. This function is deprecated. Use the Win32::API
|
|
module instead.
|
|
|
|
=item Win32::LoginName()
|
|
|
|
[CORE] Returns the username of the owner of the current perl process.
|
|
|
|
=item Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE)
|
|
|
|
[EXT] Looks up ACCOUNT on SYSTEM and returns the domain name the SID and
|
|
the SID type.
|
|
|
|
=item Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE)
|
|
|
|
[EXT] Looks up SID on SYSTEM and returns the account name, domain name,
|
|
and the SID type.
|
|
|
|
=item Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]])
|
|
|
|
[EXT] Create a dialogbox containing MESSAGE. FLAGS specifies the
|
|
required icon and buttons according to the following table:
|
|
|
|
0 = OK
|
|
1 = OK and Cancel
|
|
2 = Abort, Retry, and Ignore
|
|
3 = Yes, No and Cancel
|
|
4 = Yes and No
|
|
5 = Retry and Cancel
|
|
|
|
MB_ICONSTOP "X" in a red circle
|
|
MB_ICONQUESTION question mark in a bubble
|
|
MB_ICONEXCLAMATION exclamation mark in a yellow triangle
|
|
MB_ICONINFORMATION "i" in a bubble
|
|
|
|
TITLE specifies an optional window title. The default is "Perl".
|
|
|
|
The function returns the menu id of the selected push button:
|
|
|
|
0 Error
|
|
|
|
1 OK
|
|
2 Cancel
|
|
3 Abort
|
|
4 Retry
|
|
5 Ignore
|
|
6 Yes
|
|
7 No
|
|
|
|
=item Win32::NodeName()
|
|
|
|
[CORE] Returns the Microsoft Network node-name of the current machine.
|
|
|
|
=item Win32::RegisterServer(LIBRARYNAME)
|
|
|
|
[EXT] Loads the DLL LIBRARYNAME and calls the function DllRegisterServer.
|
|
|
|
=item Win32::SetCwd(NEWDIRECTORY)
|
|
|
|
[CORE] Sets the current active drive and directory. This function does not
|
|
work with UNC paths, since the functionality required to required for
|
|
such a feature is not available under Windows 95.
|
|
|
|
=item Win32::SetLastError(ERROR)
|
|
|
|
[CORE] Sets the value of the last error encountered to ERROR. This is
|
|
that value that will be returned by the Win32::GetLastError()
|
|
function. This functions has been added for Perl 5.6.
|
|
|
|
=item Win32::Sleep(TIME)
|
|
|
|
[CORE] Pauses for TIME milliseconds. The timeslices are made available
|
|
to other processes and threads.
|
|
|
|
=item Win32::Spawn(COMMAND, ARGS, PID)
|
|
|
|
[CORE] Spawns a new process using the supplied COMMAND, passing in
|
|
arguments in the string ARGS. The pid of the new process is stored in
|
|
PID. This function is deprecated. Please use the Win32::Process module
|
|
instead.
|
|
|
|
=item Win32::UnregisterServer(LIBRARYNAME)
|
|
|
|
[EXT] Loads the DLL LIBRARYNAME and calls the function
|
|
DllUnregisterServer.
|
|
|
|
=back
|
|
|
|
=cut
|