FFI::P...:Win32(3pm)

🦋 NAME 🦋

So you're out here reading FFI::Platypus::Lang::Win32 (that's the manual page name, bestie — the header line said FFI::P...:Win32(3pm) but we don't need to read that twice 💅). This one is the documentation and the tools for using Platypus with the Windows API. Iconic. Let's go.

✨ VERSION ✨

version 2.11 — yes queen, that's the one. 🎀

🌸 SYNOPSIS 🌸

Okay so here's the whole vibe in code form. Look at it, love it:

 use utf8;
 use FFI::Platypus 2.00;

 my $ffi = FFI::Platypus->new(
   api  => 2,
   lib  => [undef],
 );

 # load this plugin
 $ffi->lang('Win32');

 # Pass two double word integer values to the Windows API Beep function.
 $ffi->attach( Beep => ['DWORD','DWORD'] => 'BOOL');
 Beep(262, 300);

 # Send a Unicode string to the Windows API MessageBoxW function.
 use constant MB_OK                   => 0x00000000;
 use constant MB_DEFAULT_DESKTOP_ONLY => 0x00020000;
 $ffi->attach( [MessageBoxW => 'MessageBox'] => [ 'HWND', 'LPCWSTR', 'LPCWSTR', 'UINT'] => 'int' );
 MessageBox(undef, "I ❤️ Platypus", "Confession", MB_OK|MB_DEFAULT_DESKTOP_ONLY);

 # Get a Unicode string from the Windows API GetCurrentDirectoryW function.
 $ffi->attach( [GetCurrentDirectoryW => 'GetCurrentDirectory'] => ['DWORD', 'LPWSTR'] => 'DWORD');
 my $buf_size = GetCurrentDirectory(0,undef);
 my $dir = "\0\0" x $buf_size;
 GetCurrentDirectory($buf_size, \$dir) or die $^E;
 print "$dir\n";

Literally a whole personality in 24 lines. 🫶

💖 DESCRIPTION 💖

This module hands you the Windows datatypes that the Windows API actually uses. Which means you can write stuff like DWORD as an alias for uint32. Slay.

The full list of type aliases is not documented here — because it might change over time, or it might be dynamic. So the list for your current environment? Grab it with this one-liner:

 perl -MFFI::Platypus::Lang::Win32 -E "say for sort keys %{ FFI::Platypus::Lang::Win32->native_type_map }"

This plugin also sets 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 is exactly what you want — but say you need functions that use the standard C calling convention while still needing the Win32 types? You can do that, just set the ABI back immediately after loading the language plugin:

 $ffi->lang('Win32');
 $ffi->abi('default_abi');

Most of the types are pretty self-explanatory, or at least they're in the Microsoft documentation on the internet. But the Unicode strings? Bestie, those need a little more detail. 👀

[version 1.35]

This plugin also provides LPCWSTR and LPWSTR "wide" string types, 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. 💅

LPCWSTR is handled fairly transparently by the plugin. But when you're 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 up there. They're 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 you're 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. 💀 (math is real)

🌈 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. 🤷‍♀️

---

👑 METHODS 👑

⭐ abi

 my $abi = FFI::Platypus::Lang::Win32->abi;

This is called internally when the type plugin is loaded by Platypus. It selects the appropriate ABI to make Win32 API function calls. 🛠️

⭐ native_type_map

 my $hashref = FFI::Platypus::Lang::Win32->native_type_map;

This is called internally when the type plugin is loaded by Platypus. It provides types aliases useful on the Windows platform, so it may also be useful for introspection. 🔍

This returns a hash reference containing the native aliases for the Windows API. That is, the keys are native Windows API C types and the values are libffi native types.

This will includes types like DWORD and HWND, and others. The full list may be adjusted over time and may be computed dynamically. To get the full list for your install you can use this one-liner:

 perl -MFFI::Platypus::Lang::Win32 -E "say for sort keys %{ FFI::Platypus::Lang::Win32->native_type_map }"

⭐ load_custom_types

 FFI::Platypus::Lang::Win32->load_custom_types($ffi);

This is called internally when the type plugin is loaded by Platypus. It provides custom types useful on the Windows platform. For now that means the LPWSTR and LPCWSTR types. 🎁

---

💀 CAVEATS 💀

The Win32 API isn't a different computer language in the same sense that the other language plugins (those for Fortran or Rust for example). But implementing these types as a language plugin is the most convenient way to do it. No cap. 🫡

Prior to version 1.35, this plugin didn't provide an implementation for LPWSTR or LPCWSTR, so in the likely event that you need those types, make sure you also require at least that version of Platypus. ⚠️

---

🧚 SEE ALSO 🧚

• FFI::Platypus — the Core Platypus documentation. The main character. 👑
• FFI::Platypus::Lang — includes a list of other language plugins for Platypus. The whole friend group. 🫶
• FFI::Platypus::Type::WideString — the wide string type plugin use for LPCWSTR and LPWSTR types. 🎀
• Win32::API — another FFI, but for Windows only. 🪟

---

🌟 AUTHOR 🌟

Author: Graham Ollis <plicease@cpan.org>

Contributors:

• Bakkiaraj Murugesan (bakkiaraj)
• Dylan Cali (calid)
• pipcet
• Zaki Mughal (zmughal)
• Fitz Elliott (felliott)
• Vickenty Fesunov (vyf)
• Gregor Herrmann (gregoa)
• Shlomi Fish (shlomif)
• Damyan Ivanov
• Ilya Pavlov (Ilya33)
• Petr Písař (ppisar)
• Mohammad S Anwar (MANWAR)
• Håkon Hægland (hakonhagland, HAKONH)
• Meredith (merrilymeredith, MHOWARD)
• Diab Jerius (DJERIUS)
• Eric Brine (IKEGAMI)
• szTheory
• José Joaquín Atria (JJATRIA)
• Pete Houston (openstrike, HOUSTON)
• Lukas Mai (MAUKE)

Give them all their flowers, fr fr. 💐

---

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2015-2022 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 💖

---

And that's the whole page, bestie — generated from the Perl manual, perl v5.42.3, dated 2026-08-20, page FFI::P...:Win32(3pm). Go forth and call your Windows APIs with correct ABIs and appropriately sized buffers. Periodt. 💅✨🦋