[10948] INI ファイル読み書き用 Win32 API についての記述を調整 (ttssh2-commit) - Tera Term

Revision: 10948
          https://osdn.net/projects/ttssh2/scm/svn/commits/10948
Author:   nmaya
Date:     2023-09-26 23:52:52 +0900 (Tue, 26 Sep 2023)
Log Message:
-----------
INI ファイル読み書き用 Win32 API についての記述を調整

Modified Paths:
--------------
    trunk/doc/en/html/reference/dev/win32api.html
    trunk/doc/en/html/usage/migrate_to_5.html
    trunk/doc/ja/html/reference/dev/win32api.html
    trunk/doc/ja/html/usage/migrate_to_5.html

-------------- next part --------------
Modified: trunk/doc/en/html/reference/dev/win32api.html
===================================================================

--- trunk/doc/en/html/reference/dev/win32api.html	2023-09-23 16:26:14 UTC (rev 10947)
+++ trunk/doc/en/html/reference/dev/win32api.html	2023-09-26 14:52:52 UTC (rev 10948)
@@ -9,35 +9,86 @@
 </HEAD>
 <BODY>
 
-<h1>Win32API</h1>
+<h1>Win32 API</h1>
 
-Notes on Win32API
+Notes on Win32 API
 
 <h2 id="ini_file">ini file</h2>
 
 <p>
-  in Windows 2000(NT3?) Unicode-aware version of
-  WritePrivateProfileStringW()... were implemented.
+ini file has two type that is classified by character code, ACP (Shift_JIS in Japanese) and Unicode (UTF-16 with LE BOM).<br>
+And there are two version Win32 APIs for read/write ini file. ANSI version (GetPrivateProfileStringA, WritePrivateProfileStringA etc) with char * arguments, and wide character version (GetPrivateProfileStringW, WritePrivateProfileStringW etc) with wchar_t * arguments.<br>
+Combination of ini file (ACP, Unicode) and API (ANSI version, wide character version) makes 4 patterns.
 </p>
 
+<ul>
+  <li>ACP ini file : Get/WritePrivateProfileStringA</li>
+  <li>ACP ini file : Get/WritePrivateProfileStringW</li>
+  <li>Unicode (UTF-16LE) ini file : Get/WritePrivateProfileStringA</li>
+  <li>Unicode (UTF-16LE) ini file : Get/WritePrivateProfileStringW</li>
+</ul>
+
 <p>
-  We can't find any document about character encoding of ini files and
-  mixed use of Unicode/ANSI. We have documented the behavior.
-  In recent versions of Windows (at least Windows 10 and 11), the
-  following behavior is used to support Unicode.
+If Windows 2000 or later, conversion is automatically performed inside API, fit to character code of ini file.
 </p>
 
 <ul>
-  <li>If the file has a UTF-16LE BOM (0xff 0xfe) at the beginning, the ini file is a Unicode file.</li>
-  <li>When reading/writing Unicode/non-Unicode ini files with the ANSI/Unicode API, ACP/Unicode conversion is automatically performed.(This is not done on Windows 9x).</li>
-  <ul>
-    <li>If the file is a Unicode ini file, it is read/written as Unicode.</li>
-    <li>If the file is not a Unicode ini file, it reads and writes as Shift_JIS (ACP) in Japanese environment.</li>
-    <li>So possible to use the API transparently regardless of the character encoding of the ini file.</li>
-    <li>If Unicode characters that cannot be represented by ACP are written to a non-Unicode ini file, they are replaced by "?" and written to the file.</li>
-  </ul>
-  <li>When a file is created with the Unicode API writing, it will not be a Unicode ini file.</li>
-  <li>When a file is already exist that only included BOM (0xff 0xfe), write by Unicode API, it will be a Unicode ini file.</li>
+  <li>When ANSI API read/write a Unicode ini file, conversion is automatically performed.</li>
+  <li>When wide character API read/write a ACP ini file, conversion is automatically performed.</li>
+  <li>So possible to use the API transparently regardless of the character encoding of the ini file.</li>
+  <li>If Unicode characters that cannot be represented by ACP are written to a non-Unicode ini file, they are replaced by "?" and written to the file.</li>
+  <li>If the file has a UTF-16LE BOM (0xff 0xfe) at the beginning, the ini file is regarded as Unicode file.
+    <ul>
+      <li>When a file is not exist. When It is created with the WritePrivateProfileStringA/W, it will be written in ACP.</li>
+      <li>When a file is already exist that only included BOM (0xff 0xfe), write by WritePrivateProfileStringA/W, it will be written in Unicode.</li>
+    </ul>
+  </li>
 </ul>
 
+<p>
+If Windows NT 4, "ANSI API and ACP ini file" and "wide character API and ACP ini file" combination will works fine.<br>
+When Wide character API read/write a ACP ini file, conversion is automatically performed.
+</p>
+
+<p>
+If Windows 95, 98, Me, only "ANSI API and ACP ini file" combination will works fine.<br>
+Automatically conversion does not seem to be work.
+</p>
+
+<table border="1">
+  <tr>
+    <th></th>
+    <th colspan="2">Windows 2000-</th>
+    <th colspan="2">Windows NT 4</th>
+    <th colspan="2">Windows 95, 98, Me</th>
+  </tr>
+  <tr>
+    <th></th>
+    <th>ANSI API</th>
+    <th>Wide API</th>
+    <th>ANSI API</th>
+    <th>Wide API</th>
+    <th>ANSI API</th>
+    <th>Wide API</th>
+  </tr>
+  <tr>
+    <th>ACP ini file</th>
+    <td>OK</td>
+    <td>OK</td>
+    <td>OK</td>
+    <td>OK</td>
+    <td>OK</td>
+    <td>NG</td>
+  </tr>
+  <tr>
+    <th>Unicode (UTF-16LE) ini file</th>
+    <td>OK</td>
+    <td>OK</td>
+    <td>NG</td>
+    <td>NG</td>
+    <td>NG</td>
+    <td>NG</td>
+  </tr>
+</table>
+
 </html>

Modified: trunk/doc/en/html/usage/migrate_to_5.html
===================================================================
--- trunk/doc/en/html/usage/migrate_to_5.html	2023-09-23 16:26:14 UTC (rev 10947)
+++ trunk/doc/en/html/usage/migrate_to_5.html	2023-09-26 14:52:52 UTC (rev 10948)
@@ -87,7 +87,7 @@
       </ul>
       <li>Tera Trem 4 can read ini files saved by Tera Term 5.</li>
       <ul>
-        <li>Tera Trem 4 can read UTF-16 (with LE BOM) ini files (on Windows 10,11). cf. <a href="../reference/dev/win32api.html#ini_file">Win32API/ini file</a><br>
+        <li>Tera Trem 4 can read UTF-16 (with LE BOM) ini files (on Windows 2000 or later). cf. <a href="../reference/dev/win32api.html#ini_file">Win32API/ini file</a><br>
           Item in ini file cannot be handled correctly if non ACP characters are included.</li>
       </ul>
       <li>The default folder for configuration files has been changed.

Modified: trunk/doc/ja/html/reference/dev/win32api.html
===================================================================
--- trunk/doc/ja/html/reference/dev/win32api.html	2023-09-23 16:26:14 UTC (rev 10947)
+++ trunk/doc/ja/html/reference/dev/win32api.html	2023-09-26 14:52:52 UTC (rev 10948)
@@ -9,33 +9,86 @@
 </HEAD>
 <BODY>
 
-<h1>Win32API</h1>
+<h1>Win32 API</h1>
 
-Win32API \x82Ɋւ\xB7\x82郁\x83\x82
+Win32 API \x82Ɋւ\xB7\x82郁\x83\x82
 
-<h2 id="ini_file">ini\x83t\x83@\x83C\x83\x8B</h2>
+<h2 id="ini_file">ini \x83t\x83@\x83C\x83\x8B</h2>
 
 <p>
-  Windows 2000(NT3?) \x82\xB2\x82\xEB\x82\xC9 Unicode \x91Ή\x9E\x94\xC5 WritePrivateProfileStringW()
-  \x93\x99\x82\xAA\x8E\xC0\x91\x95\x82\xB3\x82ꂽ\x82Ǝv\x82\xED\x82\xEA\x82܂\xB7\x81B
+ini \x83t\x83@\x83C\x83\x8B\x82ɂ́A\x95\xB6\x8E\x9A\x83R\x81[\x83h\x82\xAA ACP (\x93\xFA\x96{\x8C\xEA\x8A\xAB\x82ł\xCD Shift_JIS) \x82̂\xE0\x82̂ƁAUnicode (UTF-16 with LE BOM) \x82̂\xE0\x82̂\xAA\x82\xA0\x82\xE8\x82܂\xB7\x81B<br>
+\x82܂\xBD\x81Aini \x83t\x83@\x83C\x83\x8B\x82𑀍삷\x82\xE9 Win32 API \x82ɂ́Achar * \x82\xF0\x88\xF8\x90\x94\x82Ƃ\xB7\x82\xE9 ANSI\x94\xC5 (GetPrivateProfileStringA, WritePrivateProfileStringA \x82Ȃ\xC7) \x82ƁAwchar_t * \x82\xF0\x88\xF8\x90\x94\x82Ƃ\xB7\x82\xE9 Wide\x95\xB6\x8E\x9A\x94\xC5 (GetPrivateProfileStringW, WritePrivateProfileStringW \x82Ȃ\xC7) \x82\xAA\x82\xA0\x82\xE8\x82܂\xB7\x81B<br>
+ini \x83t\x83@\x83C\x83\x8B (ACP, Unicode) \x82\xC6 API (ANSI\x94\xC5, Wide\x95\xB6\x8E\x9A\x94\xC5) \x82\xC5 4 \x83p\x83^\x81[\x83\x93\x82̑g\x82ݍ\x87\x82킹\x82\xAA\x94\xAD\x90\xB6\x82\xB5\x82܂\xB7\x81B
 </p>
 
+<ul>
+  <li>ACP ini file : Get/WritePrivateProfileStringA</li>
+  <li>ACP ini file : Get/WritePrivateProfileStringW</li>
+  <li>Unicode (UTF-16LE) ini file : Get/WritePrivateProfileStringA</li>
+  <li>Unicode (UTF-16LE) ini file : Get/WritePrivateProfileStringW</li>
+</ul>
+
 <p>
-  ini\x83t\x83@\x83C\x83\x8B\x82̕\xB6\x8E\x9A\x83R\x81[\x83h\x82\xE2 Unicode/ANSI \x82\xF0\x8D\xAC\x8D݂\xB5\x82Ďg\x97p\x82\xB5\x82Ă\xA2\x82\xBD\x8Fꍇ\x82̃h\x83L\x83\x85\x83\x81\x83\x93\x83g\x82͌\xA9\x93\x96\x82\xBD\x82\xE7\x82Ȃ\xA2\x82\xBD\x82ߓ\xAE\x8D\xEC\x82\xF0\x82܂Ƃ߂܂\xB5\x82\xBD\x81B
-  \x8Dŋ߂\xCCWindows(\x8F\xAD\x82Ȃ\xAD\x82Ƃ\xE0Windows 10,11)\x82ł́AUnicode \x82ɑΉ\x9E\x82\xB7\x82邽\x82ߎ\x9F\x82̂悤\x82ȓ\xAE\x8D\xEC\x82ƂȂ\xC1\x82Ă\xA2\x82܂\xB7\x81B
+Windows 2000 \x88ȍ~\x82\xCC API \x82́A\x93ǂݏ\x91\x82\xAB\x8E\x9E\x82ɓ\xE0\x95\x94\x82\xC5 ini \x83t\x83@\x83C\x83\x8B\x82̕\xB6\x8E\x9A\x83R\x81[\x83h\x82ɂ\xA0\x82킹\x82Ď\xA9\x93\xAE\x93I\x82ɕϊ\xB7\x82\xAA\x8Ds\x82\xED\x82\xEA\x82\xE9\x82悤\x82ɂȂ\xC1\x82Ă\xA2\x82܂\xB7\x81B
 </p>
 
 <ul>
-  <li>\x83t\x83@\x83C\x83\x8B\x82̐擪\x82\xC9 UTF-16LE BOM (0xff 0xfe) \x82\xAA\x82\xA2\x82Ă\xA2\x82\xE9\x82Ƃ\xAB\x81Aini\x83t\x83@\x83C\x83\x8B\x82\xCD Unicode \x82̃t\x83@\x83C\x83\x8B\x82Ƃ\xB5\x82Ĉ\xB5\x82\xED\x82\xEA\x82܂\xB7\x81B</li>
-  <li>ANSI/Unicode API \x82\xC5 Unicode/\x94\xF1Unicode ini\x83t\x83@\x83C\x83\x8B\x82\xF0\x93ǂݏ\x91\x82\xAB\x82\xB5\x82\xBD\x82Ƃ\xAB\x81A\x8E\xA9\x93\xAE\x82\xC5 ACP/Unicode \x95ϊ\xB7\x82\xAA\x8Ds\x82\xED\x82܂\xB7(9x\x8Cn\x82ł͍s\x82\xED\x82\xEA\x82܂\xB9\x82\xF1)\x81B</li>
-  <ul>
-    <li>Unicode ini \x83t\x83@\x83C\x83\x8B\x82̂Ƃ\xAB\x81AUnicode \x82Ƃ\xB5\x82ēǂݏ\x91\x82\xAB\x82\xB5\x82܂\xB7\x81B</li>
-    <li>Unicode ini \x83t\x83@\x83C\x83\x8B\x82ł͂Ȃ\xA2\x82Ƃ\xAB\x81A\x93\xFA\x96{\x8C\xEA\x8A\xAB\x82ł\xCD Shift_JIS(ACP) \x82Ƃ\xB5\x82ēǂݏ\x91\x82\xAB\x82\xB5\x82܂\xB7\x81B</li>
-    <li>\x82\xB1\x82̂\xBD\x82\xDF ini \x83t\x83@\x83C\x83\x8B\x82̕\xB6\x8E\x9A\x83R\x81[\x83h\x82ɂ\xE6\x82炸\x93\xA7\x89ߓI\x82\xC9 API \x82𗘗p\x82ł\xAB\x82܂\xB7\x81B</li>
-    <li>Unicode \x82ł͂Ȃ\xA2 ini \x83t\x83@\x83C\x83\x8B\x82\xC9 Shift_JIS \x82ŕ\\x8C\xBB\x82ł\xAB\x82Ȃ\xA2 Unicode \x95\xB6\x8E\x9A\x82\xF0\x8F\x91\x82\xAB\x8D\x9E\x82ނ\xC6"?"\x82ɒu\x8A\xB7\x82\xB3\x82\xEA\x82ď\x91\x82\xAB\x8D\x9E\x82܂\xEA\x82܂\xB7\x81B</li>
-  </ul>
-  <li>Unicode API \x82ŏ\x91\x82\xAB\x8D\x9E\x82\xF1\x82ŐV\x8BK\x82Ƀt\x83@\x83C\x83\x8B\x82\xAA\x8D쐬\x82\xB3\x82ꂽ\x82Ƃ\xAB\x82\xCD Unicode ini \x83t\x83@\x83C\x83\x8B\x82ɂȂ\xE8\x82܂\xB9\x82\xF1\x81B</li>
-  <li>BOM (0xff 0xfe) \x82\xBE\x82\xAF\x82̋\xF3\x83t\x83@\x83C\x83\x8B\x82\xF0\x8D\xEC\x82\xC1\x82Ă\xA8\x82\xA2\x82āA\x82\xBB\x82̃t\x83@\x83C\x83\x8B\x82\xC9 Unicode API \x82ŏ\x91\x82\xAB\x8D\x9E\x82ނ\xC6 Unicode ini \x83t\x83@\x83C\x83\x8B\x82ɂȂ\xE8\x82܂\xB7\x81B</li>
+  <li>ANSI\x94ł\xCC API \x82\xC5 Unicode ini \x83t\x83@\x83C\x83\x8B\x82\xF0\x88\xB5\x82\xA4\x82Ƃ\xAB\x82ɂ͎\xA9\x93\xAE\x93I\x82ɕϊ\xB7\x82\xB3\x82\xEA\x82܂\xB7\x81B</li>
+  <li>Wide\x95\xB6\x8E\x9A\x94ł\xCC API \x82\xC5 ACP ini \x83t\x83@\x83C\x83\x8B\x82\xF0\x88\xB5\x82\xA4\x82Ƃ\xAB\x82ɂ͎\xA9\x93\xAE\x93I\x82ɕϊ\xB7\x82\xB3\x82\xEA\x82܂\xB7\x81B</li>
+  <li>\x82\xB1\x82̂\xBD\x82\xDF ini \x83t\x83@\x83C\x83\x8B\x82̕\xB6\x8E\x9A\x83R\x81[\x83h\x82ɂ\xE6\x82炸\x93\xA7\x89ߓI\x82\xC9 API \x82𗘗p\x82ł\xAB\x82܂\xB7\x81B</li>
+  <li>Unicode \x82ł͂Ȃ\xA2 ini \x83t\x83@\x83C\x83\x8B\x82\xC9 ACP \x82ŕ\\x8C\xBB\x82ł\xAB\x82Ȃ\xA2 Unicode \x95\xB6\x8E\x9A\x82\xF0\x8F\x91\x82\xAB\x8D\x9E\x82ނ\xC6 "?" \x82ɒu\x8A\xB7\x82\xB3\x82\xEA\x82ď\x91\x82\xAB\x8D\x9E\x82܂\xEA\x82܂\xB7\x81B</li>
+  <li>\x83t\x83@\x83C\x83\x8B\x82̐擪\x82\xC9 UTF-16LE BOM (0xff 0xfe) \x82\xAA\x95t\x82\xA2\x82Ă\xA2\x82\xE9\x82Ƃ\xAB\x81Aini \x83t\x83@\x83C\x83\x8B\x82\xCD Unicode \x82Ɣ\xBB\x92肳\x82\xEA\x82܂\xB7\x81B
+    <ul>
+      <li>\x91\xB6\x8D݂\xB5\x82Ȃ\xA2\x83t\x83@\x83C\x83\x8B\x82\xC9 WritePrivateProfileStringA/W \x82ŏ\x91\x82\xAB\x8D\x9E\x82\xF1\x82\xC5 ini \x83t\x83@\x83C\x83\x8B\x82\xAA\x90V\x8BK\x8D쐬\x82\xB3\x82ꂽ\x82Ƃ\xAB\x82́AACP \x82ŏ\x91\x82\xAB\x8D\x9E\x82܂\xEA\x82܂\xB7\x81B</li>
+      <li>BOM (0xff 0xfe) \x82\xBE\x82\xAF\x82̋\xF3\x83t\x83@\x83C\x83\x8B\x82\xF0\x8D\xEC\x82\xC1\x82Ă\xA8\x82\xA2\x82āA\x82\xBB\x82̃t\x83@\x83C\x83\x8B\x82\xC9 WritePrivateProfileStringA/W \x82ŏ\x91\x82\xAB\x8D\x9E\x82񂾂Ƃ\xAB\x82́AUnicode \x82ŏ\x91\x82\xAB\x8D\x9E\x82܂\xEA\x82܂\xB7\x81B</li>
+    </ul>
+  </li>
 </ul>
 
+<p>
+Windows NT 4 \x82ł́A"ANSI\x94\xC5 API \x82\xC6 ACP ini \x83t\x83@\x83C\x83\x8B\x82̑g\x82ݍ\x87\x82킹", "Wide\x95\xB6\x8E\x9A\x94\xC5 API \x82\xC6 ACP ini \x83t\x83@\x83C\x83\x8B\x82̑g\x82ݍ\x87\x82킹" \x82\xAA\x90\xB3\x82\xB5\x82\xAD\x93\xAE\x8D삷\x82\xE9\x82悤\x82ł\xB7\x81B<br>
+Wide\x95\xB6\x8E\x9A\x94\xC5 API \x82\xC5 ACP ini \x83t\x83@\x83C\x83\x8B\x82\xF0\x88\xB5\x82\xA4\x8Fꍇ\x82̂ݎ\xA9\x93\xAE\x93I\x82ɕϊ\xB7\x82\xB3\x82\xEA\x82\xE9\x82悤\x82ł\xB7\x81B
+</p>
+
+<p>
+Windows 95, 98, Me \x82ł́AANSI\x94\xC5 API \x82\xC6 ACP ini \x83t\x83@\x83C\x83\x8B\x82̑g\x82ݍ\x87\x82킹\x82݂̂\xAA\x90\xB3\x82\xB5\x82\xAD\x93\xAE\x8D삷\x82\xE9\x82悤\x82ł\xB7\x81B<br>
+\x8E\xA9\x93\xAE\x93I\x82ȕϊ\xB7\x82͍s\x82\xED\x82\xEA\x82Ȃ\xA2\x82悤\x82ł\xB7\x81B
+</p>
+
+<table border="1">
+  <tr>
+    <th></th>
+    <th colspan="2">Windows 2000-</th>
+    <th colspan="2">Windows NT 4</th>
+    <th colspan="2">Windows 95, 98, Me</th>
+  </tr>
+  <tr>
+    <th></th>
+    <th>ANSI API</th>
+    <th>Wide API</th>
+    <th>ANSI API</th>
+    <th>Wide API</th>
+    <th>ANSI API</th>
+    <th>Wide API</th>
+  </tr>
+  <tr>
+    <th>ACP ini file</th>
+    <td>OK</td>
+    <td>OK</td>
+    <td>OK</td>
+    <td>OK</td>
+    <td>OK</td>
+    <td>NG</td>
+  </tr>
+  <tr>
+    <th>Unicode (UTF-16LE) ini file</th>
+    <td>OK</td>
+    <td>OK</td>
+    <td>NG</td>
+    <td>NG</td>
+    <td>NG</td>
+    <td>NG</td>
+  </tr>
+</table>
+
 </html>

Modified: trunk/doc/ja/html/usage/migrate_to_5.html
===================================================================
--- trunk/doc/ja/html/usage/migrate_to_5.html	2023-09-23 16:26:14 UTC (rev 10947)
+++ trunk/doc/ja/html/usage/migrate_to_5.html	2023-09-26 14:52:52 UTC (rev 10948)
@@ -87,7 +87,7 @@
       </ul>
       <li>Tera Trem 4 \x82\xCD Tera Term 5 \x82ŕۑ\xB6\x82\xB5\x82\xBD\x90ݒ\xE8\x83t\x83@\x83C\x83\x8B\x82\xF0\x93ǂݍ\x9E\x82߂܂\xB7\x81B</li>
       <ul>
-        <li>Tera Trem 4 \x82\xCD UTF-16 (with LE BOM) \x82\xCC ini\x83t\x83@\x83C\x83\x8B\x82\xF0\x93ǂݍ\x9E\x82߂܂\xB7(Windows 10,11\x82̏ꍇ)\x81Bcf. <a href="../reference/dev/win32api.html#ini_file">Win32API/ini\x83t\x83@\x83C\x83\x8B</a><br>
+        <li>Tera Trem 4 \x82\xCD UTF-16 (with LE BOM) \x82\xCC ini\x83t\x83@\x83C\x83\x8B\x82\xF0\x93ǂݍ\x9E\x82߂܂\xB7(Windows 2000 \x88ȍ~)\x81Bcf. <a href="../reference/dev/win32api.html#ini_file">Win32API/ini\x83t\x83@\x83C\x83\x8B</a><br>
             Shift_JIS\x82ŕ\\x8C\xBB\x82ł\xAB\x82Ȃ\xA2\x95\xB6\x8E\x9A\x82\xAA\x8A܂܂\xEA\x82Ă\xA2\x82\xE9\x82ƁA\x82\xBB\x82̍\x80\x96ڂ͐\xB3\x82\xB5\x82\xAD\x88\xB5\x82\xA6\x82܂\xB9\x82\xF1\x81B</li>
       </ul>
       <li>\x90ݒ\xE8\x83t\x83@\x83C\x83\x8B\x82̃f\x83t\x83H\x83\x8B\x83g\x83t\x83H\x83\x8B\x83_\x82\xAA\x95ύX\x82\xB3\x82\xEA\x82܂\xB5\x82\xBD\x81B


Tera Term

[ttssh2-commit] [10948] INI ファイル読み書き用 Win32 API についての記述を調整