[Chapter 19] 19.17 Win32 Extensions
Author: Ellen Siever, Stephen Spainhour & Nathan Patwardhan
Date: 1999-07-02T02:00:21Z

#

| Chapter 19 Win32 Modules and Extensions |

## 19.17 Win32 Extensions

In addition to the modules listed above, Perl for Win32 can use an additional set of functions from the Win32 extension. These functions provide useful tools for some Windows-specific tasks that don't require their own modules. They are exported from the Win32 package with:

>     use Win32;

Many of these functions do not take arguments, and they return the value (or values) of the requested information, unless otherwise noted.

`Win32::GetLastError()`

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

`Win32::OLELastError()`

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

`Win32::BuildNumber()`

  Returns the build number of Perl for Win32.

`Win32::LoginName()`

  Returns the username of the owner of the current Perl process.

`Win32::NodeName()`

  Returns the Microsoft network node-name of the current machine.

`Win32::DomainName()`

  Returns the name of the Microsoft network domain that the owner of the current Perl process is logged into.

`Win32::FsType()`

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

`Win32::GetCwd()`

  Returns the current active drive and directory. This function does not return a UNC path, since the functionality required for such a feature is not available under Windows 95.

`Win32::SetCwd(`newdir`)`

  Sets the current active drive and directory to `newdir`. This function does not work with UNC paths, since the functionality required for such a feature is not available under Windows 95.

`Win32::GetOSVersion()`

  Returns a list of elements describing the version of the operating system. The elements of the list are: an arbitrary descriptive string, the major version number of the operating system, the minor version number, the build number, and a digit indicating the actual operating system, which will be `0` for Win32s, `1` for Windows 95, and `2` for Windows NT. For example:

  >     use Win32;
  >     ($string, $major, $minor, $build, $id) = Win32::GetOSVersion();

`Win32::FormatMessage(`error`)`

  Converts the Win32 error number supplied by `error` into a descriptive string. The error number can be retrieved using `Win32::GetLastError` or `Win32::OLELastError`.

`Win32::Spawn(`command`, `args`, `$pid`)`

  Spawns a new process for the given `command`, passing the arguments in `args`. The ID of the new process in saved in the variable named by `pid`.

`Win32::LookupAccountName(`sys`, `acct`, `$domain`, `$sid`, `$type`)`

  Returns the domain name, SID, and SID type to the specified variables for the account `acct` on system `sys`.

`Win32::LookupAccountSID(`sys`, `sid`, `$acct`, `$domain`, `$type`)`

  Returns the account name, domain name, and SID type to the specified variables for the SID `sid` on system `sys`.

`Win32::InitiateSystemShutdown(`machine`, `message`, `timeout`, `forceclose`, `reboot`)`

  Shuts down the specified `machine` in the specified `timeout` interval. `message` is broadcast to all users. If `forceclose` is true, all documents are closed (forcefully) without prompting the user. If `reboot` is true, the machine is rebooted.

`Win32::AbortSystemShutdown(`machine`)`

  Aborts a shutdown on the specified `machine`.

`Win32::GetTickCount()`

  Returns the Win32 tick count.

`Win32::IsWinNT()`

  Returns true (non-zero) if the Win32 subsystem is Windows NT.

`Win32::IsWin95()`

  Returns true (non-zero) if the Win32 subsystem is Windows 95.

`Win32::ExpandEnvironmentStrings(`envstring`)`

  Returns a string in which any environment variables in the given `envstring` are replaced with their values.

`Win32::GetShortPathName(`longpathname`)`

  Returns the short (8.3) path name of `longpathname`.

`Win32::GetNextAvailDrive()`

  Returns a string in the form of `"`d`:\"`, where `d` is the first available drive letter.

`Win32::RegisterServer(`libraryname`)`

  Loads the DLL `libraryname` and calls the function `DllRegisterServer`.

`Win32::UnregisterServer(`libraryname`)`

  Loads the DLL `libraryname` and calls the function `DllUnregisterServer`.

`Win32::Sleep(`time`)`

  Pauses for the number of milliseconds specified by `time`.

19.16 Win32::Shortcut |  | 19.18 OLE Automation