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

- NAME
- SYNOPSIS
- FUNCTIONS
  - Beep
  - CopyFile
  - GetBinaryType
  - GetCompressedFileSize
  - GetCommandLine
  - GetCurrencyFormat
  - GetDiskFreeSpace
  - GetDriveType
  - GetTempPath
  - GetVolumeInformation
  - MultiByteToWideChar
  - QueryPerformanceCounter
  - QueryPerformanceFrequency
  - SearchPath
  - SetLastError
  - Sleep
  - VerLanguageName
  - WideCharToMultiByte
  - Yet to be documented
- AUTHOR

# 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 ).