[Appendix B] B.4 Win32 Extensions
Author: Randal L. Schwartz, Erik Olson & Tom Christiansen
Date: 1999-07-02T01:38:09Z

#

| Appendix B Libraries and Modules |

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

B.3 CPAN: Beyond the Standard Library |  | C. Networking Clients