[Appendix B] B.4 Win32 Extensions

B.4 Win32 Extensions

We've said that extensions consist of a module written in Perl, and a library written in C or C++. Win32 extensions are valuable tools because they provide Windows-specific functionality that otherwise wouldn't be present in the base language. The following list details the extensions included with the ActiveState distribution (these are also available for the standard distribution via the libwin32 distribution, available from CPAN).

OLE (Win32::OLE in the libwin32 distribution): Access to OLE automation and OLE variants
Win32::Process: Access to extended Win32 process creation and management; includes methods to kill, suspend, resume, and set the priorities of processes
Win32::Semaphore: Provides access to Win32 semaphores and synchronization
Win32::IPC: Provides sychronization for objects of type Semaphore, Mutex, Process, or ChangeNotify
Win32::Mutex: Provides access to Win32 mutex objects
Win32::ChangeNotify: Provides access to Win32 change-notification objects, letting you do things like monitor changes to directory trees
Win32::EventLog: Provides access to the Windows NT event log
Win32::Registry: Provides access to the Windows NT registry
Win32::NetAdmin: Lets you manipulate users and groups
Win32::File: Lets you get and set file attributes
Win32::Service: Provides a service control interface: lets you start, pause, resume, and stop services
Win32::NetResource: Lets you work with shares, both as a client and a server
Win32::FileSecurity: Lets you work with file permissions on NTFS
Win32::Error: Provides an interface to the system error codes and messages

The following Win32 extensions are not included in (but are readily available for) the ActiveState distribution, and are included with the libwin32 distribution.

Win32::Internet: Provides an interface to HTTP and FTP
Win32::ODBC: Provides an interface to ODBC data sources
Win32::Shortcut: Lets you create Explorer (shell) shortcuts
Win32::Sound: Plays .wav files or uses system sounds
Win32::AdminMisc: Provides an extension of Win32::NetAdmin that adds user impersonation, password manipulation, and DNS administration
Win32::Clipboard: Accesses the Windows NT clipboard
Win32::Console: Interfaces to console screen drawing; lets you do colors, boxes, etc.
Win32::Pipe: Provides access to named pipes on Windows NT

In addition to these extensions, a Win32 extension is included with the ActiveState distribution, and is available as part of libwin32. The Win32 extension provides the following list functions (we've given a brief code snippet to illustrate how you might code each one):

Win32::GetLastError

Returns the last error value generated by a call to a Win32 API function:

use Win32;
$err = Win32::GetLastError();

Win32::BuildNumber

Returns the build number of Perl for Win32:

use Win32:
$build = Win32::BuildNumber(); # $build has 306 (or whatever it is)

Win32::LoginName

Returns the username of the owner of the current perl process:

use Win32;
$user = Win32::LoginName();   # $user has eriko (account name of 
    current user)

Win32::NodeName

Returns the Microsoft Network node name of the current machine:

use Win32;
$node = Win32::NodeName(); # $node has machine name

Win32::DomainName

Returns the name of the Microsoft Network domain that the owner of the current perl process is logged into:

use Win32;
$domain = Win32::Domain();  # $domain has network domain name (not 
    TCP/IP domain name)

Win32::FsType

Returns a string naming the filesystem type of the currently active drive:

use Win32;
$fs = Win32::FsType();     # $fs contains fs type, like NTFS or FAT

Win32::GetCwd

Returns the current active drive and directory; this function does not return a UNC path:

use Win32;
$cwd = Win32::GetCwd();      # $cwd has current working directory

Win32::SetCwd NEW_DIRECTORY

Sets the current active drive and directory; this function does not work with UNC paths:

use Win32;
Win32::SetCwd("c:/temp") || die "SetCwd: $!";

Win32::GetOSVersion

Returns an array ($string, $major, $minor, $build, and $id). $string is a descriptive string, $major is the major version of the operating system, $minor is the minor version of the operating system, $build is the build number of the OS, and $id is a digit that denotes the operating system variety (zero for Win32s, one for Windows 95, and two for Windows NT):

use Win32;
($string, $major, $minor, $build, $id) = Win32::GetOSVersion();
@os = qw(Win32s, Win95, WinNT);
print "$os[$id] $major\.$minor $string (Build $build)\n";

The output on a Windows NT 4.0 system is:

WinNT 4.0 Service Pack 3 (Build 1381)

Win32::FormatMessage ERROR_CODE

Converts the supplied Win32 error bitmap (returned by GetLastError) to a descriptive string:

use Win32;
use Win32::WinError;  # for error constants
$msg = Win32::FormatMessage(ERROR_INTERNAL_ERROR);
# $msg contains the string: There is not enough space on disk

Win32::Spawn COMMAND, ARGS, PID

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:

use Win32;
Win32::Spawn('c:/nt/system32/notepad.exe', undef, $pid); # $pid has
    new pid of notepad

Win32::LookupAccountName SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE

Looks up ACCOUNT on SYSTEM and returns the domain name, SID, and SID type

Win32::LookupAccountSID SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE

Looks up SID (Security ID) on SYSTEM and returns the account name, domain name, and SID type:

use Win32;
Win32::LookupAccountSID(undef, $some_sid, $acct, $domain, $sidtype);

Win32::InitiateSystemShutdown MACHINE, MESSAGE, TIMEOUT, FORCECLOSE, REBOOT

Shuts down the specified MACHINE (undef means local machine), notifying users with the supplied MESSAGE, within the specified TIMEOUT (in seconds) interval. Forces closing of all documents without prompting the user if FORCECLOSE is true, and reboots the machine if REBOOT is true (be careful experimenting with this one):

use Win32;
Win32::InitiateSystemShutdown(undef, "Bye",  15, undef, 1);
# try to shut down local machine

Win32::AbortSystemShutdown MACHINE

Aborts a shutdown on the specified MACHINE:

use Win32;
Win32::AbortSystemShutdown(undef);  
# stop a shutdown on local machine

Win32::GetTickCount

Returns the Win32 tick count, which is the number of milliseconds that have elasped since the system started:

use Win32;
$tick = Win32::GetTickCount();  
# tick has number of milliseconds since system start

Win32::IsWinNT

Returns nonzero if the operating system is Windows NT:

use Win32;
$winnt = Win32::IsWinNT();  # true if running on Windows NT

Win32::IsWin95

Returns nonzero if the operating system is Windows 95:

use Win32;
$win95 = Win32::IsWin95(); # true if running on Windows 95

Win32::ExpandEnvironmentStrings STRING

Takes the STRING and builds a return string that has environment-variable strings replaced with their defined values:

use Win32;
$path = Win32::ExpandEnvironmentStrings('%PATH%'); # $path contains expanded PATH

Win32::GetShortPathName LONGPATHNAME

Returns the short (8.3) pathname for LONGPATHNAME:

use Win32;
$short = Win32::GetShortPathName('words.secret');   # $short now has 8.3 name (WORDS~1.SEC)

Win32::GetNextAvailDrive

Returns a string in the form of <d>:\ where <d> is the first available drive letter:

use Win32;
$drive = Win32::GetNextAvailDrive();  # $drive has first drive (e.g,. B:)