<HTML>
<HEAD>
<TITLE>Win32::kernel32 - Experimental interface to some of the KERNEL32.DLL functions
</TITLE>
</HEAD>
<BODY>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#NAME">NAME</A>
<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
<LI><A HREF="#FUNCTIONS">FUNCTIONS</A>
<UL>
<LI><A HREF="#Beep">Beep</A>
<LI><A HREF="#CopyFile">CopyFile</A>
<LI><A HREF="#GetBinaryType">GetBinaryType</A>
<LI><A HREF="#GetCompressedFileSize">GetCompressedFileSize</A>
<LI><A HREF="#GetCommandLine">GetCommandLine</A>
<LI><A HREF="#GetCurrencyFormat">GetCurrencyFormat</A>
<LI><A HREF="#GetDiskFreeSpace">GetDiskFreeSpace</A>
<LI><A HREF="#GetDriveType">GetDriveType</A>
<LI><A HREF="#GetTempPath">GetTempPath</A>
<LI><A HREF="#GetVolumeInformation">GetVolumeInformation</A>
<LI><A HREF="#MultiByteToWideChar">MultiByteToWideChar</A>
<LI><A HREF="#QueryPerformanceCounter">QueryPerformanceCounter</A>
<LI><A HREF="#QueryPerformanceFrequency">QueryPerformanceFrequency</A>
<LI><A HREF="#SearchPath">SearchPath</A>
<LI><A HREF="#SetLastError">SetLastError</A>
<LI><A HREF="#Sleep">Sleep</A>
<LI><A HREF="#VerLanguageName">VerLanguageName</A>
<LI><A HREF="#WideCharToMultiByte">WideCharToMultiByte</A>
<LI><A HREF="#Yet_to_be_documented">Yet to be documented</A>
</UL>
<LI><A HREF="#AUTHOR">AUTHOR</A>
</UL>
<!-- INDEX END -->
<HR>
<P>
<H1><A NAME="NAME">NAME
</A></H1>
Win32::kernel32 - Experimental interface to some of the KERNEL32.DLL
functions
<P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS
</A></H1>
<PRE> use Win32::kernel32;
</PRE>
<P>
<PRE> # or
</PRE>
<P>
<PRE> use Win32::kernel32 qw( Sleep CopyFile GetVolumeInformation );
</PRE>
<P>
<P>
<HR>
<H1><A NAME="FUNCTIONS">FUNCTIONS
</A></H1>
<P>
<HR>
<H4><A NAME="Beep">Beep
</A></H4>
Syntax:
<P>
<PRE> Win32::Beep ( [FREQUENCY, DURATION] )
</PRE>
<P>
Plays a simple tone on the speaker; <CODE>FREQUENCY</CODE> is expressed in hertz and ranges from 37 to 32767, <CODE>DURATION</CODE> 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).
<P>
Example:
<P>
<PRE> Win32::Beep(440, 1000);
</PRE>
<P>
<P>
<HR>
<H4><A NAME="CopyFile">CopyFile
</A></H4>
Syntax:
<P>
<PRE> Win32::CopyFile ( SOURCE, TARGET, [SAFE] )
</PRE>
<P>
Copies the <CODE>SOURCE</CODE> file to <CODE>TARGET</CODE>. By default, it fails if <CODE>TARGET</CODE> already exists; to overwrite the already existing file, the <CODE>SAFE</CODE> flag must be set to 0. Returns a true value if the operation was
successfull, a false one if it failed.
<P>
Example:
<P>
<PRE> 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";
}
}
</PRE>
<P>
<P>
<HR>
<H4><A NAME="GetBinaryType">GetBinaryType
</A></H4>
Syntax:
<P>
<PRE> Win32::GetBinaryType ( FILENAME )
</PRE>
<P>
Returns the type ot the executable file <CODE>FILENAME</CODE>. Possible values are:
<P>
<PRE> 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
</PRE>
<P>
If the function fails, <CODE>undef</CODE> is returned.
<P>
<STRONG>Note</STRONG>: this function is available on Windows NT only.
<P>
Example:
<P>
<PRE> print "Notepad is a type ", Win32::GetBinaryType("c:\\winnt\\notepad.exe"), "\n";
</PRE>
<P>
<P>
<HR>
<H4><A NAME="GetCompressedFileSize">GetCompressedFileSize
</A></H4>
Syntax:
<P>
<PRE> Win32::GetCompressedFileSize ( FILENAME )
</PRE>
<P>
Returns the compressed size of the specified <CODE>FILENAME</CODE>, if the file is compressed; if it's not compressed, it returns the normal
file size (eg. same as <CODE>-s</CODE>).
<P>
<STRONG>Note</STRONG>: this function is available on Windows NT only.
<P>
Example:
<P>
<PRE> print Win32::GetCompressedFileSize("c:\\documents\\longlog.txt");
</PRE>
<P>
<P>
<HR>
<H4><A NAME="GetCommandLine">GetCommandLine
</A></H4>
Syntax:
<P>
<PRE> Win32::GetCommandLine ( )
</PRE>
<P>
Returns the complete command line string, including the full path to the
program name and its arguments.
<P>
Example:
<P>
<PRE> print Win32::GetCommandLine();
</PRE>
<P>
<P>
<HR>
<H4><A NAME="GetCurrencyFormat">GetCurrencyFormat
</A></H4>
Syntax:
<P>
<PRE> Win32::GetCurrencyFormat ( NUMBER, [LOCALE] )
</PRE>
<P>
Returns <CODE>NUMBER</CODE> formatted to your locale's currency settings. You can optionally supply a
different <CODE>LOCALE</CODE> for foreign currencies.
<P>
Example:
<P>
<PRE> print "You owe me ", Win32::GetCurrencyFormat(rand()*10000), "\n";
</PRE>
<P>
<PRE> # ten millions italian lires...
$LotOfMoney = Win32::GetCurrencyFormat(10000000, 1040);
</PRE>
<P>
<PRE> # 1040 is "Italian (Standard)" (see also VerLanguageName)
# and it returns: L. 10.000.000
</PRE>
<P>
<P>
<HR>
<H4><A NAME="GetDiskFreeSpace">GetDiskFreeSpace
</A></H4>
Syntax:
<P>
<PRE> Win32::GetDiskFreeSpace ( [ROOT] )
</PRE>
<P>
Returns the amount of free disk space on the drive indicated by <CODE>ROOT</CODE>; 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.
<P>
Example:
<P>
<PRE> $free = Win32::GetDiskFreeSpace("c:\\");
($free, $total) = Win32::GetDiskFreeSpace();
</PRE>
<P>
<P>
<HR>
<H4><A NAME="GetDriveType">GetDriveType
</A></H4>
Syntax:
<P>
<PRE> Win32::GetDriveType ( [ROOT] )
</PRE>
<P>
Returns the type ot the drive indicated by <CODE>ROOT</CODE>. 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:
<P>
<PRE> 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
</PRE>
<P>
Example:
<P>
<PRE> print "C: is a type ", Win32::GetDriveType("c:\\"), "\n";
</PRE>
<P>
<P>
<HR>
<H4><A NAME="GetTempPath">GetTempPath
</A></H4>
Syntax:
<P>
<PRE> Win32::GetTempPath ( )
</PRE>
<P>
Returns the path of the directory designated for temporary files, or <CODE>undef</CODE> on errors.
<P>
Example:
<P>
<PRE> print "Please put your temp files in ", Win32::GetTempPath(), "\n";
</PRE>
<P>
<P>
<HR>
<H4><A NAME="GetVolumeInformation">GetVolumeInformation
</A></H4>
Syntax:
<P>
<PRE> Win32::GetVolumeInformation ( [ROOT] )
</PRE>
<P>
Returns a 5-elements array with some information about the drive indicated
by <CODE>ROOT</CODE>. If this is omitted, uses the current drive. Typically used as follows:
<P>
<PRE> ($label, $serial, $maxlen, $flags, $fstype) = Win32::GetVolumeInformation();
</PRE>
<P>
Here are the meaning of the fields:
<P>
<PRE> 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)
</PRE>
<P>
For more information about the <CODE>flags</CODE> field, please refer to the <CODE>GetVolumeInformation()</CODE>
documentation in the Microsoft Win32 SDK Reference.
<P>
If called in a scalar context, the function returns only the first element
(the volume label).
<P>
Example:
<P>
<PRE> $volume = Win32::GetVolumeInformation();
print "Working on $volume...";
</PRE>
<P>
<P>
<HR>
<H4><A NAME="MultiByteToWideChar">MultiByteToWideChar
</A></H4>
Syntax:
<P>
<PRE> Win32::MultiByteToWideChar ( STRING, [CODEPAGE] )
</PRE>
<P>
Converts a <CODE>STRING</CODE> in Unicode format. The additional
<CODE>CODEPAGE</CODE> parameter can have one of this values:
<P>
<PRE> 0 ANSI codepage
1 OEM codepage
2 MAC codepage
</PRE>
<P>
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 <CODE>undef</CODE> on errors.
<P>
Example:
<P>
<PRE> $UnicodeString = Win32::MultiByteToWideChar($string);
</PRE>
<P>
<P>
<HR>
<H4><A NAME="QueryPerformanceCounter">QueryPerformanceCounter
</A></H4>
Syntax:
<P>
<PRE> Win32::QueryPerformanceCounter ( )
</PRE>
<P>
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 <CODE>QueryPerformanceFrequency</CODE>.
<P>
Example:
<P>
<PRE> $freq = Win32::QueryPerformanceFrequency();
$count1 = Win32::QueryPerformanceCounter();
# do something
$count2 = Win32::QueryPerformanceCounter();
print ($count2-$count1)/$freq , " seconds elapsed.\n";
</PRE>
<P>
<P>
<HR>
<H4><A NAME="QueryPerformanceFrequency">QueryPerformanceFrequency
</A></H4>
Syntax:
<P>
<PRE> Win32::QueryPerformanceFrequency ( )
</PRE>
<P>
Returns the frequency of the high-resolution performance counter, if it
exists. Returns zero if it doesn't. See also <CODE>QueryPerformanceCounter</CODE>.
<P>
<P>
<HR>
<H4><A NAME="SearchPath">SearchPath
</A></H4>
Syntax:
<P>
<PRE> Win32::SearchPath ( FILENAME )
</PRE>
<P>
Search for the specified <CODE>FILENAME</CODE> in the path. The following directories are searched:
<P>
<PRE> 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
</PRE>
<P>
Returns the full path to the found file or <CODE>undef</CODE>
if the file was not found.
<P>
Example:
<P>
<PRE> print "Notepad exists" if -f Win32::SearchPath("notepad.exe");
</PRE>
<P>
<P>
<HR>
<H4><A NAME="SetLastError">SetLastError
</A></H4>
Syntax:
<P>
<PRE> Win32::SetLastError ( VALUE )
</PRE>
<P>
Sets the Win32 last error to the specified <CODE>VALUE</CODE>.
<P>
Example:
<P>
<PRE> # reset pending errors
Win32::SetLastError(0);
</PRE>
<P>
<P>
<HR>
<H4><A NAME="Sleep">Sleep
</A></H4>
Syntax:
<P>
<PRE> Win32::Sleep ( MILLISECONDS )
</PRE>
<P>
Sleeps for the number of <CODE>MILLISECONDS</CODE> specified.
<P>
Example:
<P>
<PRE> # sleep for 1/2 second
Win32::Sleep(500);
</PRE>
<P>
<P>
<HR>
<H4><A NAME="VerLanguageName">VerLanguageName
</A></H4>
Syntax:
<P>
<PRE> Win32::VerLanguageName ( LOCALE )
</PRE>
<P>
Returns a descriptive string for the language associated with the specified <CODE>LOCALE</CODE>.
<P>
Example:
<P>
<PRE> $ITA = Win32::VerLanguageName(1040);
$JAP = Win32::VerLanguageName(1041);
</PRE>
<P>
<P>
<HR>
<H4><A NAME="WideCharToMultiByte">WideCharToMultiByte
</A></H4>
Syntax:
<P>
<PRE> Win32::WideCharToMultiByte ( STRING, [CODEPAGE] )
</PRE>
<P>
Converts an Unicode <CODE>STRING</CODE> to a non-Unicode one. The additional
<CODE>CODEPAGE</CODE> parameter can have one of this values:
<P>
<PRE> 0 ANSI codepage
1 OEM codepage
2 MAC codepage
</PRE>
<P>
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 <CODE>undef</CODE> on errors.
<P>
Example:
<P>
<PRE> $string = Win32::WideCharToMultiByte($UnicodeString);
</PRE>
<P>
<P>
<HR>
<H4><A NAME="Yet_to_be_documented">Yet to be documented
</A></H4>
<PRE> GetSystemTime => [[P], V],
QueryDosDevice => [[P, P, N], N],
</PRE>
<P>
<P>
<HR>
<H1><A NAME="AUTHOR">AUTHOR
</A></H1>
Aldo Calpini ( <EM>dada@divinf.it</EM> ).
<P>
</DL>
</BODY>
</HTML>