[CONUTILS] Diverse improvements: start doxygenating and add some resource messsage helper functions.

- Start to doxygenate the library, focusing in great details on the
  functions of the "outstream" module.
- Add a K32LoadStringEx function that expands (K32)LoadString by
  allowing a LanguageId parameter to be able to load strings from other
  languages than the current one.
- Add "ConResMsg*" helper functions to be able to (format and) print
  message strings with inserts that come *NOT* from a message table (as
  usual) *BUT* from resource string tables.
  Will be helpful for CORE-14265 in particular.

[CMD] Fix the call to ConMsgPrintfV().

base/shell/cmd/console.c

@@ -141,7 +141,7 @@ VOID __cdecl ConFormatMessage(PCON_STREAM Stream, DWORD MessageId, ...)
                         NULL,
                         MessageId,
                         LANG_USER_DEFAULT,
-                        arg_ptr);
+                        &arg_ptr);
     va_end(arg_ptr);
 
     if (Len <= 0)

sdk/lib/conutils/conutils.h

@@ -8,6 +8,21 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    conutils.h
+ * @ingroup ConUtils
+ *
+ * @defgroup ConUtils   ReactOS Console Utilities Library
+ *
+ * @brief   This library contains common functions used in many places inside
+ *          the ReactOS console utilities and the ReactOS Command-Line Interpreter.
+ *          Most of these functions are related with internationalisation and
+ *          the problem of correctly displaying Unicode text on the console.
+ *          Besides those, helpful functions for retrieving strings and messages
+ *          from application resources are provided, together with printf-like
+ *          functionality.
+ **/
+
 #ifndef __CONUTILS_H__
 #define __CONUTILS_H__
 

sdk/lib/conutils/instream.c

@@ -8,6 +8,13 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    instream.c
+ * @ingroup ConUtils
+ *
+ * @brief   Console I/O utility API -- Input
+ **/
+
 /*
  * Enable this define if you want to only use CRT functions to output
  * UNICODE stream to the console, as in the way explained by
@@ -42,8 +49,4 @@
 #include "stream_private.h"
 
 
-/*
- * Console I/O utility API -- Input
- */
-
 /* EOF */

sdk/lib/conutils/instream.h

@@ -8,6 +8,13 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    instream.h
+ * @ingroup ConUtils
+ *
+ * @brief   Console I/O utility API -- Input
+ **/
+
 #ifndef __INSTREAM_H__
 #define __INSTREAM_H__
 
@@ -32,10 +39,6 @@ extern "C" {
 // Shadow type, implementation-specific
 typedef struct _CON_STREAM CON_STREAM, *PCON_STREAM;
 
-/*
- * Console I/O utility API -- Input
- */
-
 
 #ifdef __cplusplus
 }

sdk/lib/conutils/outstream.h

@@ -8,6 +8,13 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    outstream.h
+ * @ingroup ConUtils
+ *
+ * @brief   Console I/O utility API -- Output
+ **/
+
 #ifndef __OUTSTREAM_H__
 #define __OUTSTREAM_H__
 
@@ -37,22 +44,18 @@ typedef struct _CON_STREAM CON_STREAM, *PCON_STREAM;
 typedef INT (__stdcall *CON_WRITE_FUNC)(IN PCON_STREAM, IN PTCHAR, IN DWORD);
 
 
-/*
- * Console I/O utility API -- Output
- */
-
 INT
 __stdcall
 ConWrite(
     IN PCON_STREAM Stream,
     IN PTCHAR szStr,
-    IN DWORD len);
+    IN DWORD  len);
 
 INT
 ConStreamWrite(
     IN PCON_STREAM Stream,
     IN PTCHAR szStr,
-    IN DWORD len);
+    IN DWORD  len);
 
 INT
 ConPuts(
@@ -63,7 +66,7 @@ INT
 ConPrintfV(
     IN PCON_STREAM Stream,
     IN LPWSTR  szStr,
-    IN va_list args); // arg_ptr
+    IN va_list args);
 
 INT
 __cdecl
@@ -76,7 +79,8 @@ INT
 ConResPutsEx(
     IN PCON_STREAM Stream,
     IN HINSTANCE hInstance OPTIONAL,
-    IN UINT uID);
+    IN UINT   uID,
+    IN LANGID LanguageId);
 
 INT
 ConResPuts(
@@ -88,20 +92,22 @@ ConResPrintfExV(
     IN PCON_STREAM Stream,
     IN HINSTANCE hInstance OPTIONAL,
     IN UINT    uID,
-    IN va_list args); // arg_ptr
+    IN LANGID  LanguageId,
+    IN va_list args);
 
 INT
 ConResPrintfV(
     IN PCON_STREAM Stream,
     IN UINT    uID,
-    IN va_list args); // arg_ptr
+    IN va_list args);
 
 INT
 __cdecl
 ConResPrintfEx(
     IN PCON_STREAM Stream,
     IN HINSTANCE hInstance OPTIONAL,
-    IN UINT uID,
+    IN UINT   uID,
+    IN LANGID LanguageId,
     ...);
 
 INT
@@ -126,7 +132,7 @@ ConMsgPrintf2V(
     IN LPCVOID lpSource OPTIONAL,
     IN DWORD   dwMessageId,
     IN DWORD   dwLanguageId,
-    IN va_list args); // arg_ptr
+    IN va_list args);
 
 INT
 ConMsgPrintfV(
@@ -135,7 +141,7 @@ ConMsgPrintfV(
     IN LPCVOID lpSource OPTIONAL,
     IN DWORD   dwMessageId,
     IN DWORD   dwLanguageId,
-    IN va_list args); // arg_ptr
+    IN va_list *Arguments OPTIONAL);
 
 INT
 __cdecl
@@ -147,6 +153,40 @@ ConMsgPrintf(
     IN DWORD   dwLanguageId,
     ...);
 
+INT
+ConResMsgPrintfExV(
+    IN PCON_STREAM Stream,
+    IN HINSTANCE hInstance OPTIONAL,
+    IN DWORD   dwFlags,
+    IN UINT    uID,
+    IN LANGID  LanguageId,
+    IN va_list *Arguments OPTIONAL);
+
+INT
+ConResMsgPrintfV(
+    IN PCON_STREAM Stream,
+    IN DWORD   dwFlags,
+    IN UINT    uID,
+    IN va_list *Arguments OPTIONAL);
+
+INT
+__cdecl
+ConResMsgPrintfEx(
+    IN PCON_STREAM Stream,
+    IN HINSTANCE hInstance OPTIONAL,
+    IN DWORD  dwFlags,
+    IN UINT   uID,
+    IN LANGID LanguageId,
+    ...);
+
+INT
+__cdecl
+ConResMsgPrintf(
+    IN PCON_STREAM Stream,
+    IN DWORD dwFlags,
+    IN UINT  uID,
+    ...);
+
 
 
 VOID

sdk/lib/conutils/pager.c

@@ -6,6 +6,13 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    pager.c
+ * @ingroup ConUtils
+ *
+ * @brief   Console/terminal paging functionality.
+ **/
+
 /* FIXME: Temporary HACK before we cleanly support UNICODE functions */
 #define UNICODE
 #define _UNICODE

sdk/lib/conutils/pager.h

@@ -6,6 +6,13 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    pager.h
+ * @ingroup ConUtils
+ *
+ * @brief   Console/terminal paging functionality.
+ **/
+
 #ifndef __PAGER_H__
 #define __PAGER_H__
 

sdk/lib/conutils/screen.c

@@ -6,6 +6,13 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    screen.c
+ * @ingroup ConUtils
+ *
+ * @brief   Console/terminal screen management.
+ **/
+
 /* FIXME: Temporary HACK before we cleanly support UNICODE functions */
 #define UNICODE
 #define _UNICODE

sdk/lib/conutils/screen.h

@@ -6,6 +6,13 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    screen.h
+ * @ingroup ConUtils
+ *
+ * @brief   Console/terminal screen management.
+ **/
+
 #ifndef __SCREEN_H__
 #define __SCREEN_H__
 

sdk/lib/conutils/stream.c

@@ -8,6 +8,13 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    stream.c
+ * @ingroup ConUtils
+ *
+ * @brief   Console I/O streams
+ **/
+
 /*
  * Enable this define if you want to only use CRT functions to output
  * UNICODE stream to the console, as in the way explained by
@@ -37,10 +44,6 @@
 #include "stream_private.h"
 
 
-/*
- * Console I/O streams
- */
-
 /*
  * Standard console streams, initialized by
  * calls to ConStreamInit/ConInitStdStreams.

sdk/lib/conutils/stream.h

@@ -8,6 +8,13 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    stream.h
+ * @ingroup ConUtils
+ *
+ * @brief   Console I/O streams
+ **/
+
 #ifndef __STREAM_H__
 #define __STREAM_H__
 
@@ -29,10 +36,6 @@
 extern "C" {
 #endif
 
-/*
- * Console I/O streams
- */
-
 /*
  * See http://archives.miloush.net/michkap/archive/2009/08/14/9869928.html
  * for more information.

sdk/lib/conutils/utils.c

@@ -7,6 +7,14 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    utils.c
+ * @ingroup ConUtils
+ *
+ * @brief   General-purpose utility functions (wrappers around
+ *          or reimplementations of Win32 APIs).
+ **/
+
 /* FIXME: Temporary HACK before we cleanly support UNICODE functions */
 #define UNICODE
 #define _UNICODE
@@ -24,11 +32,6 @@
 // #include "conutils.h"
 #include "utils.h"
 
-/*
- * General-purpose utility functions (wrappers around,
- * or reimplementations of, Win32 APIs).
- */
-
 #if 0 // The following function may be useful in the future...
 
 // Performs MultiByteToWideChar then WideCharToMultiByte .
@@ -55,9 +58,10 @@ MultiByteToMultiByte(
  */
 INT
 WINAPI
-K32LoadStringW(
+K32LoadStringExW(
     IN  HINSTANCE hInstance OPTIONAL,
     IN  UINT   uID,
+    IN  LANGID LanguageId,
     OUT LPWSTR lpBuffer,
     IN  INT    nBufferMax)
 {
@@ -71,11 +75,10 @@ K32LoadStringW(
 
     /* Use LOWORD (incremented by 1) as ResourceID */
     /* There are always blocks of 16 strings */
-    // FindResourceExW(hInstance, RT_STRING, name, MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL));
+    hrsrc = FindResourceExW(hInstance,
-    // NOTE: Instead of using LANG_NEUTRAL, one might use LANG_USER_DEFAULT...
+                            (LPCWSTR)RT_STRING,
-    hrsrc = FindResourceW(hInstance,
+                            MAKEINTRESOURCEW((LOWORD(uID) >> 4) + 1),
-                          MAKEINTRESOURCEW((LOWORD(uID) >> 4) + 1),
+                            LanguageId);
-                          (LPWSTR)RT_STRING);
     if (!hrsrc) return 0;
 
     hmem = LoadResource(hInstance, hrsrc);
@@ -118,6 +121,20 @@ K32LoadStringW(
     return i;
 }
 
+INT
+WINAPI
+K32LoadStringW(
+    IN  HINSTANCE hInstance OPTIONAL,
+    IN  UINT   uID,
+    OUT LPWSTR lpBuffer,
+    IN  INT    nBufferMax)
+{
+    // NOTE: Instead of using LANG_NEUTRAL, one might use LANG_USER_DEFAULT...
+    return K32LoadStringExW(hInstance, uID,
+                            MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL),
+                            lpBuffer, nBufferMax);
+}
+
 /*
  * "Safe" version of FormatMessageW, that does not crash if a malformed
  * source string is retrieved and then being used for formatting.
@@ -194,18 +211,50 @@ FormatMessageSafeW(
     return dwLength;
 }
 
+/**
+ * @name IsTTYHandle
+ *     Checks whether a handle refers to a valid TTY object.
+ *     A TTY object may be a console or a "communications" (e.g. serial) port.
+ *
+ * @param[in]   hHandle
+ *     Handle to the TTY object to check for.
+ *
+ * @return
+ *     @b@c TRUE when the handle refers to a valid TTY object,
+ *     @b@c FALSE if it does not.
+ *
+ * @remark
+ *     This test is more general than IsConsoleHandle() as it is not limited
+ *     to Win32 console objects only.
+ *
+ * @see IsConsoleHandle()
+ **/
 BOOL
 IsTTYHandle(IN HANDLE hHandle)
 {
     /*
-     * More general test than IsConsoleHandle. Consoles, as well as
+     * More general test than IsConsoleHandle(). Consoles, as well as serial
-     * serial ports, etc... verify this test, but only consoles verify
+     * (communications) ports, etc... verify this test, but only consoles
-     * the IsConsoleHandle test: indeed the latter checks whether
+     * verify the IsConsoleHandle() test: indeed the latter checks whether
      * the handle is really handled by the console subsystem.
      */
     return ((GetFileType(hHandle) & ~FILE_TYPE_REMOTE) == FILE_TYPE_CHAR);
 }
 
+/**
+ * @name IsConsoleHandle
+ *     Checks whether a handle refers to a valid Win32 console object.
+ *
+ * @param[in]   hHandle
+ *     Handle to the Win32 console object to check for:
+ *     console input buffer, console output buffer.
+ *
+ * @return
+ *     @b@c TRUE when the handle refers to a valid Win32 console object,
+ *     @b@c FALSE if it does not.
+ *
+ * @see IsTTYHandle()
+ **/
 BOOL
 IsConsoleHandle(IN HANDLE hHandle)
 {

sdk/lib/conutils/utils.h

@@ -7,6 +7,14 @@
  *              Copyright 2017-2018 Hermes Belusca-Maito
  */
 
+/**
+ * @file    utils.h
+ * @ingroup ConUtils
+ *
+ * @brief   General-purpose utility functions (wrappers around
+ *          or reimplementations of Win32 APIs).
+ **/
+
 #ifndef __UTILS_H__
 #define __UTILS_H__
 
@@ -20,10 +28,14 @@
 extern "C" {
 #endif
 
-/*
+INT
- * General-purpose utility functions (wrappers around,
+WINAPI
- * or reimplementations of, Win32 APIs).
+K32LoadStringExW(
- */
+    IN  HINSTANCE hInstance OPTIONAL,
+    IN  UINT   uID,
+    IN  LANGID LanguageId,
+    OUT LPWSTR lpBuffer,
+    IN  INT    nBufferMax);
 
 INT
 WINAPI