NAME

Win32::API::Callback - Callback support for Win32::API

SYNOPSIS

  use Win32::API;
  use Win32::API::Callback;

  my $callback = Win32::API::Callback->new(
    sub { my($a, $b) = @_; return $a+$b; },
    "NN", "N",
  );

  Win32::API->Import(
      'mydll', 'two_integers_cb', 'KNN', 'N',
  );

  $sum = two_integers_cb( $callback, 3, 2 );

FOREWORDS

• Support for this module is highly experimental at this point.

• I won't be surprised if it doesn't work for you.

• Feedback is very appreciated.

• Documentation is in the work. Either see the SYNOPSIS above or the samples in the samples or the tests in the t directory.

USAGE

Win32::API::Callback uses a subset of the type letters of Win32::API. C Prototype interface isn't supported. Not all the type letters of Win32::API are supported in Win32::API::Callback.

I: value is an unsigned integer (unsigned int)

i: value is an signed integer (signed int or int)

N: value is a unsigned pointer sized number (unsigned long)

n: value is a signed pointer sized number (signed long or long)

Q: value is a unsigned 64 bit integer number (unsigned long long, unsigned __int64) See next item for details.

q: value is a signed 64 bit integer number (long long, __int64) If your perl has 'Q'/'q' quads support for pack then Win32::API's 'q' is a normal perl numeric scalar. All 64 bit Perls have quad support. Almost no 32 bit Perls have quad support. On 32 bit Perls, without quad support, Win32::API::Callback's 'q'/'Q' letter is a packed 8 byte string. So 0x8000000050000000 from a perl with native Quad support would be written as "\x00\x00\x00\x50\x00\x00\x00\x80" on a 32 bit Perl without Quad support. To improve the use of 64 bit integers with Win32::API::Callback on a 32 bit Perl without Quad support, there is a per Win32::API::Callback object setting called "UseMI64" in Win32::API that causes all quads to be accepted as, and returned as Math::Int64 objects. 4 to 8 byte long pass by copy/return type C aggregate types are very rare in Windows, but they are supported as "in" and return types by using 'q'/'Q' on 32 and 64 bits. Converting between the C aggregate and its representation as a quad is up to the reader. For "out" in Win32::API::Callback (not "in"), if the argument is a reference, it will automatically be treated as a Math::Int64 object without having to previously call this function.

F: value is a floating point number (float)

D: value is a double precision number (double)

Unimplemented types: Unimplemented in Win32::API::Callback types such as shorts, chars, and smaller than "machine word size" (32/64bit) numbers can be processed by specifying N, then masking off the high bytes. For example, to get a char, specify N, then do $numeric_char = $_[2] & 0xFF; in your Perl callback sub. To get a short, specify N, then do $numeric_char = $_[2] & 0xFFFF; in your Perl callback sub.

FUNCTIONS

new

    $CallbackObj = Win32::API::Callback->new( sub { print "hello world";},
                                            'NDF', 'Q', '__cdecl');
    $CallbackObj = Win32::API::Callback->new( sub { print "hello world";},
                                            $in, $out);

Creates and returns a new Win32::API::Callback object. Calling convention parameter is optional. Calling convention parameter has same behaviour as Win32::API's calling convention parameter. C prototype parsing of Win32::API is not available with Win32::API::Callback. If the C caller assumes the callback has vararg parameters, and the platform is 64 bits/x64, in the first 4 parameters, if they are floats or doubles they will be garbage. Note there is no way to create a Win32::API::Callback callback with a vararg prototype. A workaround is to put "enough" Ns as the in types, and stop looking at the @_ slices in your Perl sub callback after a certain count. Usually the first parameter will somehow indicate how many additional stack parameters you are receiving. The Ns in @_ will eventually become garbage, technically they are the return address, saved registers, and C stack allocated variables of the caller. They are effectivly garbage for your vararg callback. All vararg callbacks on 32 bits must supply a calling convention, and it must be '__cdecl' or 'WINAPIV'.

METHODS

UseMI64

See "UseMI64" in Win32::API.

KNOWN ISSUES

• Callback is safe across a Win32 psuedo-fork. Callback is not safe across a Cygwin fork. On Cygwin, in the child process of the fork, a Segmentation Fault will happen if the Win32::API::Callback callback is is called.

SEE ALSO

Win32::API::Callback::IATPatch

AUTHOR

Aldo Calpini ( dada@perl.it ). Daniel Dragan ( bulkdd@cpan.org ).

MAINTAINER

Cosimo Streppone ( cosimo@cpan.org ).