NAME

Win32API::Resources - Use Win32::API to retrieve popular resources from Kernel32.dll and others

SYNOPSIS

  use Win32API::Resources;

  my $file = "c:\\winnt\\system32\\cmd.exe";
  my %DSpace = Win32API::Resources::GetDiskFreeSpace("C:\\");
  my %DRVSpace = Win32API::Resources::GetDriveSpace("C:\\");
  my %File = Win32API::Resources::GetFileVersion($file, 1);
  my %Mem = Win32API::Resources::GlobalMemoryStatus();
  my $Notes = Win32API::Resources::LoadString("c:\\notes\\nstrings.dll", 1);
  my @list = Win32API::Resources::EnumString("c:\\notes\\nstrings.dll");
  my $type = Win32API::Resources::ExeType($file);
  my @drives = Win32API::Resources::GetDrives(DRIVE_CDROM);
  my $Connections = Win32API::Resources::RasEnumConnections();

  if (Win32API::Resources::IsEXE16($file))
	{
	print "The file $file is 16-bit - ($type)\n";
	}
  elsif (Win32API::Resources::IsEXE32($file))
	{
	print "The file $file is 32-bit - ($type)\n";
	}
  print "There are $Connections open RAS Connections\n";
  print "The following are valid CD-Rom drives: @drives\n";
  Win32API::Resources::ShowKeys("File Information:", 1, \%File);
  Win32API::Resources::ShowKeys("Disk Space:", 0, \%DSpace);
  Win32API::Resources::ShowKeys("Drive Space:", 1, \%DRVSpace);
  Win32API::Resources::ShowKeys("Memory Stats:", 1, \%Mem);

ABSTRACT

With this module you can access a series of Win32 API's directly or via provided wrappers that are exported from KERNEL32.DLL, SHELL32.DLL, USER32.DLL & VERSION.DLL.

The current version of Win32API::Resources is available at:

http://home.earthlink.net/~bsturner/perl/index.html

CREDITS

Thanks go to Aldo Calpini for making the Win32::API module accessible as well as some help with GetBinaryType and ExeType functions and to Dave Roth and Jens Helberg for providing direction on the GetFileVersion function. Thanks to Mike Blazer and Aldo Calpini for fixes to the GetFileVersion function and the UnpackLargeInt function that fixes a bug in the GetDiskFreeSpaceEx function

HISTORY

0.06	Fixed bug with GetDiskFreeSpaceEx that reported drives over 4GB incorrectly
	Fixed and extended functionality of GetFileVersion function to correctly 
	view and return all available information
	Now runs with 'use strict qw(vars)'
	Added two new internal helper subroutines - UnpackLargeInt and DWORD_NULL
0.05	Added RasEnumConnections function and fixed bug with GetDrives on Win95
0.04	Added GetDrives function
0.03	Cleaned up and fixed bug with GetDiskFreeSpaceEx
0.02	Added some new EXEType functions
0.01	First release

INSTALLATION

This module is shipped as a basic PM file that should be installed in your Perl\site\lib\Win32API dir. Written and tested for the ActivePerl 5xx distribution, but should work in any Win32 capable port that has Win32::API.

REQUIRES Win32::API be installed

DESCRIPTION

To use this module put the following line at the beginning of your script:

use Win32API::Resources;

Any one of the functions can be referenced by:

var = Win32API::Resources::function

except for Win32API::Resources::ShowKeys() which does not return a value.

RETURN VALUES

Unless otherwise specified, all functions return 0 if unsuccessful and non-zero data if successful.

FUNCTIONS

Win32API::Resources::GetDiskFreeSpace

%Hash = Win32API::Resources::GetDiskFreeSpace($drive);

$drive must refer to the root of a target drive and be followed by \\

$drive = "C:\\";
$drive = "$ENV{SystemDrive}\\";

Windows 95: The GetDiskFreeSpace function returns incorrect values for volumes that are larger than 2 gigabytes. Even on volumes that are smaller than 2 gigabytes, the values may be incorrect. That is because the operating system manipulates the values so that computations with them yield the correct volume size.

Windows 95 OSR2 and later: The GetDiskFreeSpaceEx function is available on Windows 95 systems beginning with OEM Service Release 2 (OSR2). The GetDiskFreeSpaceEx function returns correct values for all volumes, including those that are greater than 2 gigabytes.

Win32API::Resources::GetDiskFreeSpaceEx

%Hash = Win32API::Resources::GetDiskFreeSpaceEx($drive);

GetDiskFreeSpaceEx will not work on Win95 OSR1. This function is provided for direct access, however it is safer to use the Win32API::Resources::GetDriveSpace wrapper instead.

$drive must refer to the root of a target drive and be followed by \\

$drive = "C:\\";
$drive = "$ENV{SystemDrive}\\";

Windows 95 OSR2: The GetDiskFreeSpaceEx function is available on Windows 95 systems beginning with OEM Service Release 2 (OSR2).

Win32API::Resources::GetDriveSpace

%Hash = Win32API::Resources::GetDriveSpace($drive);

$drive must refer to the root of a target drive and be followed by \\

$drive = "C:\\";
$drive = "$ENV{SystemDrive}\\";

Wrapper around GetDiskFreeSpace and GetDiskFreeSpaceEx - GetDriveSpace will always call the correct function depending on which version of the OS you have.

Win32API::Resources::GetFileVersion

%Hash = Win32API::Resources::GetFileVersion($file, $return);

GetFileVersion will return all available information in both Win95 and WinNT.

$file is the full path to the EXE or DLL to be examined
$return is an optional boolean switch to return the array as zero valued keys

Returns a hash with the following keys:

CharacterSet		The character set the Language is based on
Comments 		Comments, from the StringFileInfo block
CompanyName		Company Name, from the StringFileInfo block
FileDescription 	File Description, from the StringFileInfo block
FileFlags		<see table>
FileOS			<see table>
FileType		<see table>
FileSubtype		<see table>
FileVersion 		File Version, from the StringFileInfo block
FileVersionMS		Specifies the most significant 32 bits of the file's binary version number. 
			This member is used with FileVersionLS to form a 64-bit value used for numeric 
			comparisons. From FixedFileInfo block
FileVersionLS		Specifies the least significant 32 bits of the file's binary version number. 
			This member is used with FileVersionMS to form a 64-bit value used for numeric 
			comparisons. From FixedFileInfo block
FileVersion64		The 64-bit File Version representation, from FileVersionMS & LS
InternalName 		Internal Name, from the StringFileInfo block
Language		The internal Language version
LegalCopyright 		Legal Copyright, from the StringFileInfo block
LegalTrademarks 	Legal Trademarks, from the StringFileInfo block
OriginalFilename 	Original Filename, from the StringFileInfo block
PrivateBuild 		Private Build, from the StringFileInfo block
ProductName 		Product Name, from the StringFileInfo block
ProductVersion 		Produc Version, from the StringFileInfo block
ProductVersionMS	Specifies the most significant 32 bits of the binary version number of the 
			product with which this file was distributed. This member is used with 
			ProductVersionLS to form a 64-bit value used for numeric comparisons. 
			From the FixedFileInfo block
ProductVersionLS	Specifies the least significant 32 bits of the binary version number of the 
			product with which this file was distributed. This member is used with 
			ProductVersionMS to form a 64-bit value used for numeric comparisons. 
			From FixedFileInfo block
ProductVersion64	The 64-bit Product Version representation, from ProductVersionMS & LS
SpecialBuild		Special Build, from the StringFileInfo block

FileFlags Table

Contains a bitmask that specifies the Boolean attributes of the file. This member can include one or more of the following values:

Flag 			Description 
VS_FF_DEBUG 		The file contains debugging information or is compiled with debugging features enabled. 
VS_FF_INFOINFERRED	The file's version structure was created dynamically; therefore, some of the members 
			in this structure may be empty or incorrect. This flag should never be set in a file's 
			VS_VERSIONINFO data. 
VS_FF_PATCHED 		The file has been modified and is not identical to the original shipping file of the 
			same version number. 
VS_FF_PRERELEASE 	The file is a development version, not a commercially released product. 
VS_FF_PRIVATEBUILD 	The file was not built using standard release procedures. If this flag is set, the 
			StringFileInfo structure should contain a PrivateBuild entry. 
VS_FF_SPECIALBUILD 	The file was built by the original company using standard release procedures but is 
			a variation of the normal file of the same version number. If this flag is set, the 
			StringFileInfo structure should contain a SpecialBuild entry.

FileOS Table

Specifies the operating system for which this file was designed. This member can be one of the following values:

Flag 			Description 
VOS_DOS 		The file was designed for MS-DOS. 
VOS_NT 			The file was designed for Windows NT. 
VOS__WINDOWS16 		The file was designed for 16-bit Windows. 
VOS__WINDOWS32 		The file was designed for the Win32 API. 
VOS_OS216 		The file was designed for 16-bit OS/2. 
VOS_OS232 		The file was designed for 32-bit OS/2. 
VOS__PM16 		The file was designed for 16-bit Presentation Manager. 
VOS__PM32 		The file was designed for 32-bit Presentation Manager. 
VOS_UNKNOWN 		The operating system for which the file was designed is unknown to the system.

An application can combine these values to indicate that the file was designed for one operating system running on another. The following FileOS values are examples of this, but are not a complete list:

Flag 			Description 
VOS_DOS_WINDOWS16 	The file was designed for 16-bit Windows running on MS-DOS. 
VOS_DOS_WINDOWS32 	The file was designed for the Win32 API running on MS-DOS. 
VOS_NT_WINDOWS32 	The file was designed for the Win32 API running on Windows NT. 
VOS_OS216_PM16 		The file was designed for 16-bit Presentation Manager running on 16-bit OS/2. 
VOS_OS232_PM32 		The file was designed for 32-bit Presentation Manager running on 32-bit OS/2.

FileType Table

Specifies the general type of file. This member can be one of the following values:

Flag 			Description 
VFT_UNKNOWN 		The file type is unknown to the system. 
VFT_APP 		The file contains an application. 
VFT_DLL 		The file contains a dynamic-link library (DLL). 
VFT_DRV 		The file contains a device driver. If FileType is VFT_DRV, FileSubtype contains a 
			more specific description of the driver. 
VFT_FONT 		The file contains a font. If FileType is VFT_FONT, FileSubtype contains a 
			more specific description of the font file. 
VFT_VXD 		The file contains a virtual device. If FileType is VFT_VXD, FileSubtype contains 
			the virtual device identifier included in the virtual device control block. 
VFT_STATIC_LIB 		The file contains a static-link library.

FileSubtype Table

Specifies the function of the file. The possible values depend on the value of FileType. For all values of FileType not described in the following list, FileSubtype is undefined.

If FileType is VFT_DRV, FileSubtype can be one of the following values:

Flag 			Description 
VFT2_UNKNOWN 		The driver type is unknown by the system. 
VFT2_DRV_COMM 		The file contains a communications driver. 
VFT2_DRV_PRINTER 	The file contains a printer driver. 
VFT2_DRV_KEYBOARD 	The file contains a keyboard driver. 
VFT2_DRV_LANGUAGE 	The file contains a language driver. 
VFT2_DRV_DISPLAY 	The file contains a display driver. 
VFT2_DRV_MOUSE 		The file contains a mouse driver. 
VFT2_DRV_NETWORK 	The file contains a network driver. 
VFT2_DRV_SYSTEM 	The file contains a system driver. 
VFT2_DRV_INSTALLABLE 	The file contains an installable driver. 
VFT2_DRV_SOUND 		The file contains a sound driver.

If FileType is VFT_FONT, FileSubtype can be one of the following values:

Flag 			Description 
VFT2_UNKNOWN 		The font type is unknown by the system. 
VFT2_FONT_RASTER 	The file contains a raster font. 
VFT2_FONT_VECTOR 	The file contains a vector font. 
VFT2_FONT_TRUETYPE 	The file contains a TrueType font.

If the function fails and the optional switch is not specified, then it returns undef. If the function fails and the optional switch is specified, then the same hash is returned but the key values will be set to 0.

Win32API::Resources::GlobalMemoryStatus

%Hash = Win32API::Resources::GlobalMemoryStatus();

Returns a hash filled with memory information from the current system. The structure of the hash is the same as Win32::AdminMisc::GetMemoryInfo:

Load		Specifies a number between 0 and 100 that gives a general 
		idea of current memory utilization
RAMTotal 	Indicates the total number of bytes of physical memory
RAMAvail 	Indicates the number of bytes of physical memory available
PageTotal 	Indicates the total number of bytes that can be stored in the 
		paging file. Note that this number does not represent the actual 
		physical size of the paging file on disk.
PageAvail 	Indicates the number of bytes available in the paging file
VirtTotal 	Indicates the total number of bytes that can be described in the 
		user mode portion of the virtual address space of the calling process
VirtAvail 	Indicates the number of bytes of unreserved and uncommitted memory in 
		the user mode portion of the virtual address space of the calling process

Win32API::Resources::LoadString

$Scalar = Win32API::Resources::LoadString($file, $rid);

$file is full path to the EXE or DLL to examine
$rid is the resource element to query where 1 is the first element in the table

Some EXE's and DLL's have a Resource Table that lists strings that are referenced for various purposes. These sometimes contain version information or error messages. In the case of Lotus Notes the first element of NSTRINGS.DLL contains the version of Notes installed.

By default all strings are limited to 64 character wide.

To Enumerate the table, use Win32API::Resources::EnumString

Win32API::Resources::EnumString

@List = Win32API::Resources::EnumString($file);

Just as Win32API::Resources::LoadString will load a specific element from the resource table of a file, EnumString uses the same method but returns an enumerated list of the contents of the resource table.

By default all strings are limited to 64 character wide.

Win32API::Resources::ExeType

$Scalar = Win32API::Resources::ExeType($file);

ExeType is a wrapper around the SHGetFileInfo API. This will return:

16-bit Windows based application, NE <OS Version>
32-bit Windows based application, PE <OS Version>
32-bit Win32 console based application, PE <NULL>
MS-DOS based application, MZ <NULL>
Unknown, <Type> <OS Version>

NE designates 16 bit applications
PE designates 32 bit applications
MZ designates MS-DOS applications
<OS Version> is the version of the OS it was compiled to run on (3.0, 3.1, 3.51, etc)

SHGetFileInfo will work on both WinNT and Win95a systems

Thanks to Aldo Calpini for the code!

Win32API::Resources::IsEXE16

Win32API::Resources::IsEXE16($file);

IsEXE16 is a wrapper around the SHGetFileInfo API. It is provided as a simple file test that returns a true (1) or false (0) based on the target file.

$file is the full path to the EXE in question

Win32API::Resources::IsEXE32

Win32API::Resources::IsEXE32($file);

IsEXE32 is a wrapper around the SHGetFileInfo API. It is provided as a simple file test that returns a true (1) or false (0) based on the target file.

$file is the full path to the EXE in question

Win32API::Resources::GetBinaryType

Win32API::Resources::GetBinaryType($title, 1, \%File);

GetBinary type only works in Windows NT. It does, however, have the added benefit over SHGetFileInfo in that it will also reveal EXE types based on other NT subsystems. It will return:

Win32 based application
MS-DOS based application
16-bit Windows based application
PIF file that executes an MS-DOS based application
POSIX based application
16-bit OS/2 based application

Thanks to Aldo Calpini for the code!

Win32API::Resources::GetDrives

[$Scalar] or [@List] = Win32API::Resources::GetDrives($type);

In List context GetDrives returns a list of drive assignments on the local system In Scalar context GetDrives returns the number of valid drive assignments Passing GetDrives one of the Drive Type Constants will return: In List context, a list of drive assignments that match the passed constant In Scalar context, the number of valid drive assignments that match the passed constant

$type is one of the following constants - optional

DRIVE_NO_ROOT_DIR 	The root directory does not exist. 
DRIVE_REMOVABLE 	The disk can be removed from the drive. 
DRIVE_FIXED 		The disk cannot be removed from the drive. 
DRIVE_REMOTE 		The drive is a remote (network) drive. 
DRIVE_CDROM 		The drive is a CD-ROM drive. 
DRIVE_RAMDISK 		The drive is a RAM disk.

Win32API::Resources::RasEnumConnections

$Scalar = Win32API::Resources::RasEnumConnections();

RasEnumConnections returns the number of active RAS/Dial-Up connections on the local machine.

$Scalar is the number of open connections

Returns undef on a failure (RAS is not installed), or 0-x for the number of connections.

Win32API::Resources::DWORD_NULL

$Scalar = Win32API::Resources::DWORD_NULL();

DWORD_NULL is a way to pack a null string easily. Based on code by Mike Blazer.

$Scalar is the packed value

Win32API::Resources::UnpackLargeInt

$Scalar = Win32API::Resources::UnpackLargeInt($PackedLargeInteger);

UnpackLargeInt is a way to unpack a LARGE_INTEGER easily. Based on code by Mike Blazer.

$Scalar is the unpacked value

Win32API::Resources::ShowKeys

Win32API::Resources::ShowKeys($title, $sort, \%Hash);

ShowKeys is provided as a simple way to show the contents of a hash with optional sorting.

$title is a printed title to the hash
$sort is a boolean switch that will optionally sort the Keys
\%Hash is a Hash reference that you wish to display

AUTHOR

Brad Turner ( bsturner@sprintparanet.com ).

To install Win32API::Resources, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Win32API::Resources

CPAN shell

perl -MCPAN -e shell
install Win32API::Resources

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

ABSTRACT

CREDITS

HISTORY

INSTALLATION

DESCRIPTION

RETURN VALUES

FUNCTIONS

Win32API::Resources::GetDiskFreeSpace

Win32API::Resources::GetDiskFreeSpaceEx

Win32API::Resources::GetDriveSpace

Win32API::Resources::GetFileVersion

FileFlags Table

FileOS Table

FileType Table

FileSubtype Table

Win32API::Resources::GlobalMemoryStatus

Win32API::Resources::LoadString

Win32API::Resources::EnumString

Win32API::Resources::ExeType

Win32API::Resources::IsEXE16

Win32API::Resources::IsEXE32

Win32API::Resources::GetBinaryType

Win32API::Resources::GetDrives

Win32API::Resources::RasEnumConnections

Win32API::Resources::DWORD_NULL

Win32API::Resources::UnpackLargeInt

Win32API::Resources::ShowKeys

AUTHOR

Module Install Instructions