/ 
Win32-API-0.40
River stage two • 33 direct dependents • 37 total dependents
/ Win32::kernel32

NAME

Win32::kernel32 - Experimental interface to some of the KERNEL32.DLL functions

SYNOPSIS

use Win32::kernel32;

# or

use Win32::kernel32 qw( Sleep CopyFile GetVolumeInformation );

FUNCTIONS

Beep

Syntax:

Win32::Beep ( [FREQUENCY, DURATION] )

Plays a simple tone on the speaker; FREQUENCY is expressed in hertz and ranges from 37 to 32767, DURATION is expressed in milliseconds. Note that parameters are relevant only on Windows NT; on Windows 95, parameters are ignored and the system plays the default sound event (or a standard system beep on the speaker if you have no sound card).

Example:

Win32::Beep(440, 1000);

CopyFile

Syntax:

Win32::CopyFile ( SOURCE, TARGET, [SAFE] )

Copies the SOURCE file to TARGET. By default, it fails if TARGET already exists; to overwrite the already existing file, the SAFE flag must be set to 0. Returns a true value if the operation was successfull, a false one if it failed.

Example:

if(Win32::CopyFile($from, $to)) {
    print "Copy OK.\n";
} else {
    # overwrite the already existing file
    if(Win32::CopyFile($from, $to, 0)) {
        print "Copy OK, file replaced.\n";
    } else {
        print "Copy failed.\n";
    }
}

GetBinaryType

Syntax:

Win32::GetBinaryType ( FILENAME )

Returns the type ot the executable file FILENAME. Possible values are:

0   A Win32 based application
1   An MS-DOS based application
2   A 16-bit Windows based application
3   A PIF file that executes an MS-DOS based application
4   A POSIX based application
5   A 16-bit OS/2 based application

If the function fails, undef is returned.

Note: this function is available on Windows NT only.

Example:

print "Notepad is a type ", Win32::GetBinaryType("c:\\winnt\\notepad.exe"), "\n";

GetCompressedFileSize

Syntax:

Win32::GetCompressedFileSize ( FILENAME )

Returns the compressed size of the specified FILENAME, if the file is compressed; if it's not compressed, it returns the normal file size (eg. same as -s).

Note: this function is available on Windows NT only.

Example:

print Win32::GetCompressedFileSize("c:\\documents\\longlog.txt");

GetCommandLine

Syntax:

Win32::GetCommandLine ( )

Returns the complete command line string, including the full path to the program name and its arguments.

Example:

print Win32::GetCommandLine();

GetCurrencyFormat

Syntax:

Win32::GetCurrencyFormat ( NUMBER, [LOCALE] )

Returns NUMBER formatted to your locale's currency settings. You can optionally supply a different LOCALE for foreign currencies.

Example:

print "You owe me ", Win32::GetCurrencyFormat(rand()*10000), "\n";

# ten millions italian lires...
$LotOfMoney = Win32::GetCurrencyFormat(10000000, 1040);

# 1040 is "Italian (Standard)" (see also VerLanguageName)
# and it returns: L. 10.000.000

GetDiskFreeSpace

Syntax:

Win32::GetDiskFreeSpace ( [ROOT] )

Returns the amount of free disk space on the drive indicated by ROOT; if this is omitted, uses the current drive. To specify a drive, you must provide the exact root directory (eg. for drive C: it must be: "C:\"). In a scalar context, it returns the number of free bytes; in a list context, it returns the number of free bytes and the total number of bytes on the disk.

Example:

$free = Win32::GetDiskFreeSpace("c:\\");
($free, $total) = Win32::GetDiskFreeSpace();

GetDriveType

Syntax:

Win32::GetDriveType ( [ROOT] )

Returns the type ot the drive indicated by ROOT. If this is omitted, uses the current drive. To specify a drive, you must provide the exact root directory (eg. for drive C: it must be: "C:\"). Possible return values are:

0   The drive type cannot be determined
1   The root directory does not exist
2   The disk can be removed from the drive
3   The disk cannot be removed from the drive
4   The drive is a remote (network) drive
5   The drive is a CD-ROM drive
6   The drive is a RAM disk

Example:

print "C: is a type ", Win32::GetDriveType("c:\\"), "\n";

GetTempPath

Syntax:

Win32::GetTempPath ( )

Returns the path of the directory designated for temporary files, or undef on errors.

Example:

print "Please put your temp files in ", Win32::GetTempPath(), "\n";

GetVolumeInformation

Syntax:

Win32::GetVolumeInformation ( [ROOT] )

Returns a 5-elements array with some information about the drive indicated by ROOT. If this is omitted, uses the current drive. Typically used as follows:

($label, $serial, $maxlen, $flags, $fstype) = Win32::GetVolumeInformation();

Here are the meaning of the fields:

label   the volume label
serial  the volume serial number
maxlen  the maximum filename length, in chars, supported by the volume
flags   a set of flags associated with the file system
fstype  the type of the file system (such as FAT or NTFS)

For more information about the flags field, please refer to the GetVolumeInformation() documentation in the Microsoft Win32 SDK Reference.

If called in a scalar context, the function returns only the first element (the volume label).

Example:

$volume = Win32::GetVolumeInformation();
print "Working on $volume...";

MultiByteToWideChar

Syntax:

Win32::MultiByteToWideChar ( STRING, [CODEPAGE] )

Converts a STRING in Unicode format. The additional CODEPAGE parameter can have one of this values:

0   ANSI codepage
1   OEM codepage
2   MAC codepage

Or the number of a codepage installed on your system (eg. 850 for "MS-DOS Multilingual (Latin I)"). The default, if none specified, is the ANSI codepage. Returns the converted string or undef on errors.

Example:

$UnicodeString = Win32::MultiByteToWideChar($string);

QueryPerformanceCounter

Syntax:

Win32::QueryPerformanceCounter ( )

Retrieves the current value of the high-resolution performance counter, if it exists. Returns zero if it doesn't. To see how many times per second the counter is incremented, use QueryPerformanceFrequency().

Example:

$freq = Win32::QueryPerformanceFrequency();
$count1 = Win32::QueryPerformanceCounter();
# do something
$count2 = Win32::QueryPerformanceCounter();
print ($count2-$count1)/$freq , " seconds elapsed.\n";

QueryPerformanceFrequency

Syntax:

Win32::QueryPerformanceFrequency ( )

Returns the frequency of the high-resolution performance counter, if it exists. Returns zero if it doesn't. See also QueryPerformanceCounter.

SearchPath

Syntax:

Win32::SearchPath ( FILENAME )

Search for the specified FILENAME in the path. The following directories are searched:

1. the directory from which the application loaded.
2. the current directory
3. the Windows system directory
4. the Windows directory
5. the directories in the PATH environment variable

Returns the full path to the found file or undef if the file was not found.

Example:

print "Notepad exists" if -f Win32::SearchPath("notepad.exe");

SetLastError

Syntax:

Win32::SetLastError ( VALUE )

Sets the Win32 last error to the specified VALUE.

Example:

# reset pending errors
Win32::SetLastError(0);

Sleep

Syntax:

Win32::Sleep ( MILLISECONDS )

Sleeps for the number of MILLISECONDS specified.

Example:

# sleep for 1/2 second
Win32::Sleep(500);

VerLanguageName

Syntax:

Win32::VerLanguageName ( LOCALE )

Returns a descriptive string for the language associated with the specified LOCALE.

Example:

$ITA = Win32::VerLanguageName(1040);
$JAP = Win32::VerLanguageName(1041);

WideCharToMultiByte

Syntax:

Win32::WideCharToMultiByte ( STRING, [CODEPAGE] )

Converts an Unicode STRING to a non-Unicode one. The additional CODEPAGE parameter can have one of this values:

0   ANSI codepage
1   OEM codepage
2   MAC codepage

Or the number of a codepage installed on your system (eg. 850 for "MS-DOS Multilingual (Latin I)"). The default, if none specified, is the ANSI codepage. Returns the converted string or undef on errors.

Example:

$string = Win32::WideCharToMultiByte($UnicodeString);

Yet to be documented

GetSystemTime        => [[P], V],
QueryDosDevice       => [[P, P, N], N],

AUTHOR

Aldo Calpini ( dada@divinf.it ).