v0.3.1

Author: brickpool

Changes

@@ -1,5 +1,9 @@
 Revision history for Win32API::Console
 
+0.3.1  2025-12-02
+    - Add limitations to POD
+    - Fix tests with CP_UTF8, use alternative code page for old systems
+
 0.3.0  2025-12-01
     - Add Get/SetConsoleScreenBufferInfoEx functions
     - Fix use of 'S' instead of 's' for COORD and SMALL_RECT

lib/Win32API/Console.pm

@@ -20,7 +20,7 @@ use version;
 
 # version '...'
 our $version = '0.10';
-our $VERSION = 'v0.3.0';
+our $VERSION = 'v0.3.1';
 $VERSION = eval $VERSION;
 
 # authority '...'

lib/Win32API/Console.pod

@@ -14,11 +14,11 @@ this module was created, which uses most of the XS functions of
 L<Win32::Console>, but also provides additional ones (e.g., for wide char 
 support). 
 
-Further details can be found in the included PM or directly at MSDN. The API 
+Further details can be found in the source code or directly at MSDN. The API 
 interface was modeled on the classic Windows API, so that the original 
 documentation from Microsoft can be used in most cases. 
 
-=head1 FUNCTIONS
+=head1 SUBROUTINES
 
 Many Windows API functions exist in multiple variants that differ by the 
 character encoding they expect. The naming convention typically uses suffixes:
@@ -75,8 +75,11 @@ Example:
   use utf8;
   FunctionName("Text");
 
-B<Note>: The wrapper provides a compatibility layer, but depends on the 
-internal XS compilation settings of L<Win32::Console>.
+B<Note>: The wrapper provides a compatibility layer, but its behavior depends 
+on the internal XS build configuration of L<Win32::Console>.
+
+Please also refer to the Windows-specific L</CAVEATS> section for important 
+details when using these wrapper functions.
 
 =back
 
@@ -2137,6 +2140,33 @@ Constants for L</GetStdHandle> and L</SetStdHandle>
 
   All of the above.
 
+=head1 CAVEATS
+
+Not all functions listed here are supported on every version of Windows. 
+Where possible, the platform support is detected, and if there are limitations, 
+a Windows error code (C<$^E>) is set accordingly. In some cases, a workaround 
+is available to circumvent these limitations. Please refer to the official 
+MSDN documentation to verify whether a specific function is supported on your 
+Windows version.
+
+=head2 Known limitations
+
+On Windows 7 and 8, C<WideCharToMultiByte> with C<CP_UTF8> sometimes returns 
+incorrect results when the system locale is not UTF-8. This is a platform 
+limitation, not an issue in the Perl code. Typical symptoms include corrupted 
+characters (e.g., double-encoded UTF-8 sequences).
+
+L<MSDN - WideCharToMultiByte function|https://learn.microsoft.com/en-us/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte>:
+
+  UTF-8 (CP_UTF8) is supported starting with Windows XP, but full support for 
+  UTF-8 as a system locale was added in later versions of Windows 10
+
+L<MSDN - Unicode in the Windows API|https://learn.microsoft.com/en-us/windows/win32/intl/unicode-in-the-windows-api>:
+
+  Prior to Windows 10 version 1903, UTF-8 was not available as a system code 
+  page. Applications using CP_UTF8 may experience inconsistent behavior if the 
+  system locale is not UTF-8.
+
 =head1 REQUIRES
 
 L<Exporter> 

t/00-begin.t

@@ -24,6 +24,7 @@ terms as the Perl 5 programming language system itself.
 use 5.014;
 use warnings;
 
+use Win32;
 use Test::More;
 
 sub UNICODE () {
@@ -103,10 +104,11 @@ sub banner {
   diag( ' ' );
   diag( '# ' x 36 );
   diag( ' ' );
-  diag( "  OS:            $^O" );
-  diag( "  PERL:          $]" );
-  diag( "  UNICODE:       ", UNICODE      ? "detected" : "not detected" );
-  diag( "  MANUAL_TESTS:  ", MANUAL_TESTS ? "enabled"  : "not enabled"  );
+  diag( "  OS:           $^O" );
+  diag( "  PERL:         $]" );
+  diag( "  CP:           ", Win32::GetConsoleOutputCP() );
+  diag( "  UNICODE:      ", UNICODE      ? "detected" : "not detected" );
+  diag( "  MANUAL_TESTS: ", MANUAL_TESTS ? "enabled"  : "not enabled"  );
   diag( ' ' );
   diag( '# ' x 36 );
 }

t/02-helper.t

@@ -4,6 +4,7 @@ use utf8;
 
 use Test::More tests => 6;
 require bytes;
+use version;
 
 BEGIN {
   use_ok 'Win32';
@@ -14,6 +15,7 @@ BEGIN {
 
 BEGIN { subtest "Import private helper's" => sub {
   can_ok('Win32API::Console' =>
+    'CP_ACP', 
     'CP_UTF8', 
     'ERROR_SUCCESS',
     'ERROR_INVALID_HANDLE',
@@ -28,6 +30,7 @@ BEGIN { subtest "Import private helper's" => sub {
     '__HRESULT_FROM_WIN32',
   );
   no warnings;
+  *CP_ACP                 = Win32API::Console->can('CP_ACP');
   *CP_UTF8                = Win32API::Console->can('CP_UTF8');
   *ERROR_SUCCESS          = Win32API::Console->can('ERROR_SUCCESS');
   *ERROR_INVALID_HANDLE   = Win32API::Console->can('ERROR_INVALID_HANDLE');
@@ -42,6 +45,7 @@ BEGIN { subtest "Import private helper's" => sub {
   *__HRESULT_FROM_WIN32   = Win32API::Console->can('__HRESULT_FROM_WIN32');
 }}
 
+my $os;
 subtest 'GetOSVersion' => sub {
   my $id = GetOSVersion();
   diag "$^E" if $^E;
@@ -51,23 +55,34 @@ subtest 'GetOSVersion' => sub {
   diag "$^E" if $^E;
   cmp_ok(@ver, '>=', 5, 'GetOSVersion() array context');
   note join(", " => @ver);
+  $os = version->declare(sprintf('v%2$d.%3$d.%4$d', @ver));
 };
 
 subtest 'WideCharToMultiByte and back' => sub {
-  my $original = "Viele Grüße";
+  my ($cp, $original);
+  if ($os < v10.0.1903) {
+    # Before Windows 10, there was no native UTF-8 system locale.
+    $cp = CP_ACP;
+    $original = "Hello";
+  } 
+  else {
+    # Starting with Windows 10 (1903), there is beta support for UTF-8.
+    $cp = CP_UTF8;
+    $original = "Viele Grüße";
+  }
 
-  # Convert multibyte to wide string (UTF-8 codepage)
-  my $wide = MultiByteToWideChar($original, CP_UTF8);
+  # Convert multibyte to wide string
+  my $wide = MultiByteToWideChar($original, $cp);
   ok(defined $wide, 'MultiByteToWideChar returned a value');
   ok($wide, 'wide string is not empty');
 
   # Convert back to multibyte string
-  my $mb = WideCharToMultiByte($wide, CP_UTF8);
+  my $mb = WideCharToMultiByte($wide, $cp);
   ok(defined $mb, 'WideCharToMultiByte returned a value');
   ok($mb, 'Multibyte string is not empty');
   is(
-    bytes::substr($original, 0), 
-    bytes::substr($mb, 0), 
+    bytes::substr($mb, 0),
+    bytes::substr($original, 0),
     'Round-trip conversion preserved string'
   );
 };