| Win32 - Interfaces to some Win32 API Functions |
Win32 - Interfaces to some Win32 API Functions
The Win32 module contains functions to access Win32 APIs.
It is recommended to use Win32; before any of these functions;
however, for backwards compatibility, those marked as [CORE] will
automatically do this for you.
In the function descriptions below the term Unicode string is used to indicate that the string may contain characters outside the system codepage. The caveat If supported by the core Perl version generally means Perl 5.8.9 and later, though some Unicode pathname functionality may work on earlier versions.
unlink() it first
yourself.
DIRECTORY may contain Unicode characters outside the system codepage. Once the directory has been created you can use Win32::GetANSIPathName() to get a name that can be passed to system calls and external programs.
FILE may contain Unicode characters outside the system codepage. Once the file has been created you can use Win32::GetANSIPathName() to get a name that can be passed to system calls and external programs.
%VariableName%. Case is ignored when looking up the
VariableName in the environment. If the variable is not found then the
original %VariableName% text is retained. Has the same effect
as the following:
$string =~ s/%([^%]*)%/$ENV{$1} || "%$1%"/eg
However, this function may return a Unicode string if the environment variable being expanded hasn't been assigned to via %ENV. Access to %ENV is currently always using byte semantics.
perror() standard-C library function. Note that $^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
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.
GetConsoleCP() and GetConsoleOutputCP().
While not currently implemented, it is possible that in the future this function will convert only parts of the path to FILENAME to a short form.
If FILENAME doesn't exist on the filesystem, or if the filesystem doesn't support short ANSI filenames, then this function will translate the Unicode name into the system codepage using replacement characters.
GetACP() and
GetOEMCP().
If supported by the core Perl version, this function will return an ANSI path name for the current directory if the long pathname cannot be represented in the system codepage.
The current process identifier is normally also available via the
predefined $$ variable. Under fork() emulation however $$ may contain
a pseudo-process identifier that is only meaningful to the Perl
kill(), wait() and waitpid() functions. The
Win32::GetCurrentProcessId() function will always return the regular
Windows process id, even when called from inside a pseudo-process.
CSIDL_ADMINTOOLS
CSIDL_APPDATA
CSIDL_CDBURN_AREA
CSIDL_COMMON_ADMINTOOLS
CSIDL_COMMON_APPDATA
CSIDL_COMMON_DESKTOPDIRECTORY
CSIDL_COMMON_DOCUMENTS
CSIDL_COMMON_FAVORITES
CSIDL_COMMON_MUSIC
CSIDL_COMMON_PICTURES
CSIDL_COMMON_PROGRAMS
CSIDL_COMMON_STARTMENU
CSIDL_COMMON_STARTUP
CSIDL_COMMON_TEMPLATES
CSIDL_COMMON_VIDEO
CSIDL_COOKIES
CSIDL_DESKTOP
CSIDL_DESKTOPDIRECTORY
CSIDL_FAVORITES
CSIDL_FONTS
CSIDL_HISTORY
CSIDL_INTERNET_CACHE
CSIDL_LOCAL_APPDATA
CSIDL_MYMUSIC
CSIDL_MYPICTURES
CSIDL_MYVIDEO
CSIDL_NETHOOD
CSIDL_PERSONAL
CSIDL_PRINTHOOD
CSIDL_PROFILE
CSIDL_PROGRAMS
CSIDL_PROGRAM_FILES
CSIDL_PROGRAM_FILES_COMMON
CSIDL_RECENT
CSIDL_RESOURCES
CSIDL_RESOURCES_LOCALIZED
CSIDL_SENDTO
CSIDL_STARTMENU
CSIDL_STARTUP
CSIDL_SYSTEM
CSIDL_TEMPLATES
CSIDL_WINDOWS
Note that not all folders are defined on all versions of Windows.
Please refer to the MSDN documentation of the CSIDL constants, currently available at:
This function will return an ANSI folder path if the long name cannot be represented in the system codepage. Use Win32::GetLongPathName() on the result of Win32::GetFolderPath() if you want the Unicode version of the folder name.
If supported by the core Perl version, this function will return an ANSI path name if the full pathname cannot be represented in the system codepage.
$^E used in a numeric context amounts to the
same value.
This function may return the pathname in Unicode if it cannot be represented in the system codepage. Use Win32::GetANSIPathName() before passing the path to a system call or another program.
GetConsoleCP()
and GetConsoleOutputCP().
Windows 2000 Datacenter Server Windows XP Professional Windows XP Tablet PC Edition Windows Home Server Windows Server 2003 Enterprise Edition for Itanium-based Systems Windows Vista Ultimate (32-bit) Windows Small Business Server 2008 R2 (64-bit)
The display name describes the native Windows version, so even on a 32-bit Perl this function may return a ``Windows ... (64-bit)'' name when running on a 64-bit Windows.
This function should only be used to display the actual OS name to the user; it should not be used to determine the class of operating systems this system belongs to. The Win32::GetOSName(), Win32::GetOSVersion, Win32::GetProductInfo() and Win32::GetSystemMetrics() functions provide the base information to check for certain capabilities, or for families of OS releases.
GetOSVersion() in list context.
The description will also include tags for other special editions, like ``R2'', ``Media Center'', ``Tablet PC'', or ``Starter Edition''.
Currently the possible values for the OS name are
WinWin32s
Win95
Win98
WinMe
WinNT3.51
WinNT4
Win2000
WinXP/.Net
Win2003
WinHomeSvr
WinVista
Win2008
Win7
This routine is just a simple interface into GetOSVersion(). More specific or demanding situations should use that instead. Another option would be to use POSIX::uname(), however the latter appears to report only the OS family name and not the specific OS. In scalar context it returns just the ID.
The name ``WinXP/.Net'' is used for historical reasons only, to maintain backwards compatibility of the Win32 module. Windows .NET Server has been renamed as Windows 2003 Server before final release and uses a different major/minor version number than Windows XP.
Similarly the name ``WinWin32s'' should have been ``Win32s'' but has been kept as-is for backwards compatibility reasons too.
Currently known values for ID MAJOR and MINOR are as follows:
OS ID MAJOR MINOR
Win32s 0 - -
Windows 95 1 4 0
Windows 98 1 4 10
Windows Me 1 4 90
Windows NT 3.51 2 3 51
Windows NT 4 2 4 0
Windows 2000 2 5 0
Windows XP 2 5 1
Windows Server 2003 2 5 2
Windows Server 2003 R2 2 5 2
Windows Home Server 2 5 2
Windows Vista 2 6 0
Windows Server 2008 2 6 0
Windows 7 2 6 1
Windows Server 2008 R2 2 6 1
Windows 8 2 6 2
Windows Server 2012 2 6 2
On Windows NT 4 SP6 and later this function returns the following additional values: SPMAJOR, SPMINOR, SUITEMASK, PRODUCTTYPE.
The version numbers for Windows 2003 and Windows Home Server are identical; the SUITEMASK field must be used to differentiate between them.
The version numbers for Windows Vista and Windows Server 2008 are identical; the PRODUCTTYPE field must be used to differentiate between them.
The version numbers for Windows 7 and Windows Server 2008 R2 are identical; the PRODUCTTYPE field must be used to differentiate between them.
The version numbers for Windows 8 and Windows Server 2012 are identical; the PRODUCTTYPE field must be used to differentiate between them.
SPMAJOR and SPMINOR are the version numbers of the latest installed service pack.
SUITEMASK is a bitfield identifying the product suites available on the system. Known bits are:
VER_SUITE_SMALLBUSINESS 0x00000001
VER_SUITE_ENTERPRISE 0x00000002
VER_SUITE_BACKOFFICE 0x00000004
VER_SUITE_COMMUNICATIONS 0x00000008
VER_SUITE_TERMINAL 0x00000010
VER_SUITE_SMALLBUSINESS_RESTRICTED 0x00000020
VER_SUITE_EMBEDDEDNT 0x00000040
VER_SUITE_DATACENTER 0x00000080
VER_SUITE_SINGLEUSERTS 0x00000100
VER_SUITE_PERSONAL 0x00000200
VER_SUITE_BLADE 0x00000400
VER_SUITE_EMBEDDED_RESTRICTED 0x00000800
VER_SUITE_SECURITY_APPLIANCE 0x00001000
VER_SUITE_STORAGE_SERVER 0x00002000
VER_SUITE_COMPUTE_SERVER 0x00004000
VER_SUITE_WH_SERVER 0x00008000
The VER_SUITE_xxx names are listed here to cross reference the Microsoft documentation. The Win32 module does not provide symbolic names for these constants.
PRODUCTTYPE provides additional information about the system. It should be one of the following integer values:
1 - Workstation (NT 4, 2000 Pro, XP Home, XP Pro, Vista, etc)
2 - Domaincontroller
3 - Server (2000 Server, Server 2003, Server 2008, etc)
Note that a server that is also a domain controller is reported as PRODUCTTYPE 2 (Domaincontroller) and not PRODUCTTYPE 3 (Server).
undef when the PATHNAME does not
exist. Compare with Win32::GetFullPathName() and
Win32::GetLongPathName().
GetSystemMetrics()
function for a reference of available INDEX values. All system
metrics return integer values.
GetProductInfo() function for more information
about the parameters and return value. This function requires Windows
Vista or later.
See also the Win32::GetOSName() and Win32::GetOSDisplayName() functions which provide a higher level abstraction of the data returned by this function.
The return value is formatted according to OLE conventions, as groups of hex digits with surrounding braces. For example:
{09531CF1-D0C7-4860-840C-1C8C8735E2AD}
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.
undef
and prints a warning if an error occurred. This function always
returns 1 on Win9X.
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
Alternatively one can use the Debug Viewer application to
watch the OutputDebugString() output:
http://www.microsoft.com/technet/sysinternals/utilities/debugview.mspx
system() will create a new console window for child
processes if Perl itself is not running from a console. Calling
SetChildShowWindow(0) will make these new console windows invisible.
Calling SetChildShowWindow() without arguments reverts system() to the
default behavior. The return value of SetChildShowWindow() is the
previous setting or undef.
The following symbolic constants for SHOWWINDOW are available (but not exported) from the Win32 module: SW_HIDE, SW_SHOWNORMAL, SW_SHOWMINIMIZED, SW_SHOWMAXIMIZED and SW_SHOWNOACTIVATE.
SetConsoleCP() is nonzero on
success or zero on failure. To get the console's input code page, see
GetConsoleCP().
SetConsoleOutputCP() is nonzero on
success or zero on failure. To get the console's output code page, see
GetConsoleOutputCP().
| Win32 - Interfaces to some Win32 API Functions |