Win32 Extensions (Perl in a Nutshell, 2nd Edition)

22.19. Win32 Extensions

In addition to the modules listed previously, 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 return the value (or values) of the requested information, unless otherwise noted.

Win32::CopyFile(from, to, overwrite)

Copies an existing file to a new file, while preserving all attributes of the original file, except the security information. If to exists, overwriting will take place only if overwrite is true. Read-only files will never be overwritten; they will need to be unlink ed first.

Win32::FreeLibrary(handle)

Unloads a previously loaded DLL. handle is no longer valid after FreeLibrary( ) is called.

Win32::GetArchName( )

Has been deprecated in favor of $ENV{PROCESSOR_ARCHITECTURE}.

Win32::GetChipName( )

Returns the processor type of the machine under which the perl process is running. This string will be represented as 386, 486, 586, etc.

Win32::GetFullPathName(filename)

Combines filename with drive number and directory name. In a list context, GetFulllPathName( ) returns path and file.

Win32::GetLastError( )

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

Win32::GetLongPathName(pathname)

Returns pathname as composed of longname components.

Win32::GetProcAddress(instance, procname)

Returns the address of a function inside of a loaded library. Since GetProcAddress( ) is deprecated, you should use Win32::API instead.

Win32::LoadLibrary(libname)

Loads a DLL into memory and returns its module handle. You can then use the returned module handle with Win32::GetProcAddress and Win32::FreeLibrary.

Win32::MsgBox(message, [, flags, [, title]])

Creates a dialog box that contains message. title specifies an optional window title. FLAGS specifies the required icons according to the following:

0 = OK
1 = OK and Cancel
2 = Abort, Retry, and Ignore
3 = Yes, No and Cancel
4 = Yes and No
5 = Retry and Cancel
MB_ICONSTOP creates an "X" in a red circle
MB_ICONQUESTION creates a question mark in a bubble
MB_ICONEXCLAMATION creates an exclamation mark in a yellow triangle
MB_ICONINFORMATION creates an "i" in a bubble

MsgBox( ) returns the menu ID of the selected pushbutton:

0  Error
1  OK
2  Cancel
3  Abort
4  Retry
5  Ignore
6  Yes
7  No

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::SetLastError(error)

Sets the value of the last error encountered to error. Does not work 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 errorinto 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 is 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 (nonzero) if the Win32 subsystem is Windows NT.

Win32::IsWin95( )

Returns true (nonzero) 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) pathname of longpathname.

Win32::GetNextAvailDrive( )

Returns a string in the form of d:\, in which 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.