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 event log
• Win32::Registry
• Provides access to the Windows 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 clipboard
• Win32::Console
• Interfaces to console screen drawing; lets you do colors, boxes, etc.
• Win32::Pipe
• Provides access to named pipes on Windows

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, and two for Windows):

  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 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:

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

• Win32::IsWin95
• Returns nonzero if the operating system is Windows:

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

• 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:)