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 .