The Official Win32::API::Prototype Home Page

What is Win32::API::Prototype?

Win32::API::Prototype is a wrapper around Aldo Calpini's powerful Win32::API Win32 Perl extension. His extension enables a Perl script to load any DLL and call into arbitrary functions. This grants Perl an awesome power enabling the language to do almost anything that a programmer may need it to.
However, Win32::API is difficult to use, even for seasoned programmers. Win32::API::Prototype was designed to make Aldo's extension a bit easier to use.

Back to the top

The latest version

The latest version of Win32::API::Prototype is:

Back to the top

How do you get Win32::API::Prototype?

There are two ways to obtain Win32::API Prototype. You can either download and install it manually from our FTP site:

ftp://ftp.roth.net/pub/ntperl/Prototype/

If you have ActivePerl (aka Perl from ActiveState Tool Corp. version 5.005 or higher) or if you have Core Perl 5.005 compiled with the PERL_OBJECT macro defined you can auto download and install the extension. You need to run the Perl Package Manager script which comes with Perl in the perl\bin directory:

perl ppm.pl install http://www.roth.net/perl/packages/win32-api-prototype.ppd

This will automatically download and install the latest version.

Back to the top

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.

HISTORY

v20001128

  -Initial release.

v20000613

  -Slight modification and clean up code.

v20020928

  -Fixed problem with parsing LPARAM parameters. This was parsed as a long pointer. Thanks to Alon Swartz [alon@datasourcing.co.il]
  -Added additional recognized types.
  -Added support for floating point types.

v20021217

  -Fixed pointer parsing logic to accept Type* Foo. Thanks to Glenn Phillips [Glenn.Phillips@simpl.co.nz]