NAME

Win32::API::Prototype - easily manage Win32::API calls

SYNOPSIS

        use Win32::API::Prototype;

DESCRIPTION

This module mimicks calling the Win32 API from C by allowing a script to specify a C function prototype.

FUNCTIONS

ApiLink( $Module, $Prototype, [\@ParameterTypes, $ReturnType] )

Declares a Win32 API prototype. There are two ways to call this:

a) Traditional Win32::API

The $Prototype is the name of the Win32 API function and the second and third parameters are traditional Win32::API parameter and return types such as:

    ApiLink( 'kernel32.dll', 'FindFirstVolume', [P,N], N ) || die;

b) Prototype style

The $Prototype is the actual C prototype of the function as in:

    ApiLink( 'kernel32.dll', 'HANDLE FindFirstVolume(LPTSTR lpszVolumeName, DWORD chBufferLength)' ) || die;

This will create a global function by the same name of the Win32 API function. Therefore a script can call it as a C program would call the function.

Example:

    use Win32::API::Prototype;
    @Days = qw(
        Sun
        Mon
        Tue
        Wed
        Thu
        Fri
        Sat
    );
    ApiLink( 'kernel32.dll', 'void GetLocalTime( LPSYSTEM  lpSystemTime )' ) || die;
    $lpSystemTime = pack( "S8", 0,0,0,0,0,0,0,0 );
    
    # This function does not return any value
    GetLocalTime( $lpSystemTime );
    
    @Time{ year, month, dow, day, hour, min, sec, mil } = unpack( "S*", $lpSystemTime );
    printf( "The time is: %d:%02d:%02d %s %04d.%02d.%02d\n", $Time{hour}, $Time{min}, $Time{sec}, $Days[$Time{dow}], $Time{year}, $Time{month}, $Time{day} );

AllocMemory( $Size )

This function will allocate a buffer of $String bytes. The string will be filled with NULL charcters. This is the equivilent of the C++ code:

    LPBYTE pBuffer = new BYTE [ dwSize ];
    if( NULL != pBuffer )
    {
        ZeroMemory( pBuffer, dwSize );
    }

Example:

    use Win32::API::Prototype;
    $pBuffer = AllocMemory( 256 );

NewString( $String | $Size )

This function will create either a string containing $String or create an empty string $Size characters in length. Regardless of what type of string is created it will be created for UNICODE or ANSI depending on what the Win32 API function will expect.

Example:

    use Win32::API::Prototype;
    
    ApiLink( 'kernel32.dll', 'DWORD GetCurrentDirectory( DWORD nBufferLength, LPTSTR lpBuffer )' ) || die;
    $nBufferLength = 256;
    $lpBuffer = NewString( $nBufferLength );
    # GetCurrentDirectory() returns the length of the directory string
    $Result = GetCurrentDirectory( $nBufferLength, $lpBuffer );
    print "The current directory is: " . CleanString( $lpBuffer ) . "\n";

CleanString( $String )

This function will clean up and return the passed in $String. This means that the any trailing NULL characters will be removed and if the string is UNICODE it will be converted to ANSI.

Example:

Refer to the NewString() example.