This module provides the Windows datatypes used by the Windows API. This means that you can use things
like "DWORD" as an alias for "uint32". The full list of type aliases is not documented here as it may
change over time or be dynamic. You can get the list for your current environment with this one-liner:
perl -MFFI::Platypus::Lang::Win32 -E "say for sort keys %{ FFI::Platypus::Lang::Win32->native_type_map }"
This plugin will also set the correct ABI for use with Win32 API functions. (On 32 bit systems a
different ABI is used for Win32 API than what is used by the C library, on 32 bit systems the same ABI is
used). Most of the time this exactly what you want, but if you need to use functions that are using the
standard C calling convention, but need the Win32 types, you can do that by setting the ABI back
immediately after loading the language plugin:
$ffi->lang('Win32');
$ffi->abi('default_abi');
Most of the types should be pretty self-explanatory or at least provided in the Microsoft documentation
on the internet, but the use of Unicode strings probably requires some more detail:
[version 1.35]
This plugin also provides "LPCWSTR" and "LPWSTR" "wide" string types which are implemented using
FFI::Platypus::Type::WideString. For full details, please see the documentation for that module, and
note that "LPCWSTR" is a wide string in the read-only string mode and "LPWSTR" is a wide string in the
read-write buffer mode.
The "LPCWSTR" is handled fairly transparently by the plugin, but for when using read-write buffers
("LPWSTR") with the Win32 API you typically need to allocate a buffer string of the right size. These
examples will use "GetCurrentDirectoryW" attached as "GetCurrentDirectory" as in the synopsis above.
These are illustrative only, you would normally want to use the Cwd module to get the current working
directory.
default buffer size 2048
The simplest way is to fallback on the rather arbitrary default buffer size of 2048.
my $dir;
GetCurrentDirectory(1024, \$dir);
print "I am in the directory: $dir\n";
Discussion: This only works if you know the API that you are using will not ever use more than 2048
bytes. The author believes this to be the case for "GetCurrentDirectoryW" since directory paths in
windows have a maximum of 260 characters. If every character was outside the Basic Multilingual
Plane (BMP) they would take up exactly 4 characters each. (This is probably not ever the case since
the disk volume at least will be a Latin letter). Taking account of the "NULL" termination you would
need 260 * 4 + 2 bytes or 1048 bytes.
We pass in a reference to our scalar so that the Win32 API can write into it.
We are passing in half the number of bytes as the first argument because the API expects the number
of "WCHAR" (or "wchar_t"), not the number of bytes or the technically the number of characters since
characters can take up either 2 or 4 bytes in UTF-16.
allocate your buffer to your own size.
If possible it is of course always best to allocate exactly the size of buffer that you need.
my $size = GetCurrentDirectory(0, undef);
my $dir = "\0\0" x $size;
GetCurrentDirectory($size, \$dir);
print "I am in the directory: $dir\n";
Discussion: In this case the API provides a way of getting the exact size of buffer that you need.
We allocate this in Perl by creating a string of "NULLs" of the right length. The Perl string "\0"
is exactly on byte, so we double that before using the "x" operator to multiple that by the size
returned by the API.
Now, somewhat unexpectedly what is returned is not the same buffer, but a new string in new UTF-8
encoded Perl string. This is what you want most of the time.
initialize your read-write buffer
Some APIs might be modifying an existing string rather than just writing an entirely new one. In
that case you still want to allocate a buffer, but you want to initialize it with a value. You can
do this by passing an array reference instead of a scalar reference. The firs element of the array
is the buffer, and the second is the initialization.
my $dir;
GetCurrentDirectory($size, [ \$dir, "I ❤ Perl + Platypus" ]);
Discussion: Note that this particular API ignores the string passed in and writes over it, but this
demonstrates how you would initialize a buffer string. Once again, if $dir is not initialized (is
"undef"), then a buffer of the default size of 2048 bytes will be created internally. You can also
allocate a specific number of bytes as in the previous example.
allocate memory using "malloc" etc.
You can also allocate memory using "malloc" (see FFI::Platypus::Memory) and encode your string using
Encode and copy it using "wcscpy". This may be appropriate in some cases, but it is beyond the scope
of this document.
Install Now
PNG Icons
