Um, I'm afraid that is too many words for me :) but

#!/usr/bin/perl --
use strict; use warnings;
use Data::Dump;
use Win32::API;
#~ $Win32::API::DEBUG = 666;

#~ http://cpansearch.perl.org/src/COSIMO/Win32-API-0.68/samples/GetCur
+sorPos.pl

use Win32::API;

Win32::API::Struct->typedef(
    POINT => qw(
        LONG x;
        LONG y;
        )
);

Win32::API->Import('user32' => 'BOOL GetCursorPos(LPPOINT pt)');

#### using OO semantics
my $pt = Win32::API::Struct->new('POINT');
GetCursorPos($pt) or die "GetCursorPos failed: $^E";
print "Cursor is at: $pt->{x}, $pt->{y}\n";

#### using tie semantics
my %pt;
tie %pt, 'Win32::API::Struct' => 'POINT';
GetCursorPos(\%pt) or die "GetCursorPos failed: $^E";
print "Cursor is at: $pt{x}, $pt{y}\n";

{
    my $pt = Win32::API::Struct->new('POINT');
    my $lpt = Win32::API::Struct->new('LPPOINT');
    dd [ $pt, $lpt ];
    
    GetCursorPos($pt) or die "GetCursorPos failed: $^E";
    dd ['winner', $pt ];
    
    GetCursorPos($lpt) or die "GetCursorPos failed: $^E";
    dd [ 'dud', $lpt ];
    print "Cursor is at: $pt->{x}, $pt->{y}\n";

}

__END__
Cursor is at: 266, 336
Cursor is at: 266, 336
[
  bless({
    __typedef__ => "POINT",
    typedef => [["x", "l", "LONG"], ["y", "l", "LONG"]],
  }, "Win32::API::Struct"),
  bless({ __typedef__ => "LPPOINT", typedef => [] }, "Win32::API::Stru
+ct"),
]
do {
  my $a = [
    "winner",
    bless({
      __typedef__ => "POINT",
      buffer => "\n\1\0\0P\1\0\0",
      buffer_recipients => ['fix', 'fix'],
      typedef => [["x", "l", "LONG"], ["y", "l", "LONG"]],
      x => 266,
      y => 336,
    }, "Win32::API::Struct"),
  ];
  $a->[1]{buffer_recipients}[0] = $a->[1];
  $a->[1]{buffer_recipients}[1] = $a->[1];
  $a;
}
[
  "dud",
  bless({
    __typedef__ => "LPPOINT",
    buffer => "",
    buffer_recipients => [],
    typedef => [],
  }, "Win32::API::Struct"),
]
Cursor is at: 266, 336
[download]

So I'm not sure what the docs are talking about if its a bug or whatever :)

update: Win32::API says

Note that this works only when the function wants a pointer to a structure: as you can see, our structure is named 'POINT', but the API used 'LPPOINT'. 'LP' is automatically added at the beginning of the structure name when feeding it to a Win32::API call.

update: See http://cpansearch.perl.org/src/COSIMO/Win32-API-0.68/Callback/t/03_Jim_Shaw.t

    my $pid_raw_value = "\x0" x Win32::API::Type->sizeof("LPDWORD");
    GetWindowThreadProcessId($hwnd, $pid_raw_value);

    my $window_pid = Win32::API::Type::Unpack("LPDWORD", $pid_raw_valu
+e);
[download]

So now I think this is leftover documentation of a feature that was never implemented ( a more complete OO interface, because the tie is cumbersome). Documentation definitely needs improvement.

Up to always i've been using pack/unpack myself but I don't use Win32::API too much

And that Jim Shaw test is using the internal/undocumented API of Win32::API, which will break your scripts one day.

And that Jim Shaw test is using the internal/undocumented API of Win32::API, which will break your scripts one day.

Do you really believe that?

I fairly confident that cosimo plans on documenting that oficially -- its been there since 2003