* Copyright 2017-2018 Hermes Belusca-Maito
*/
+/**
+ * @file outstream.c
+ * @ingroup ConUtils
+ *
+ * @brief Console I/O utility API -- Output
+ **/
+
/*
* Enable this define if you want to only use CRT functions to output
* UNICODE stream to the console, as in the way explained by
// #define MAX_MESSAGE_SIZE 512 // See shutdown...
-/*
- * Console I/O utility API -- Output
- */
-
-// NOTE: Should be called with the stream locked.
+/**
+ * @name ConWrite
+ * Writes a counted string to a stream.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] szStr
+ * Pointer to the counted string to write.
+ *
+ * @param[in] len
+ * Length of the string pointed by @p szStr, specified
+ * in number of characters.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @note
+ * This function is used as an internal function.
+ * Use the ConStreamWrite() function instead.
+ *
+ * @remark
+ * Should be called with the stream locked.
+ **/
INT
__stdcall
ConWrite(
IN PCON_STREAM Stream,
IN PTCHAR szStr,
- IN DWORD len)
+ IN DWORD len)
{
#ifndef USE_CRT
DWORD TotalLen = len, dwNumBytes = 0;
#endif
+/**
+ * @name ConStreamWrite
+ * Writes a counted string to a stream.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] szStr
+ * Pointer to the counted string to write.
+ *
+ * @param[in] len
+ * Length of the string pointed by @p szStr, specified
+ * in number of characters.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ **/
INT
ConStreamWrite(
IN PCON_STREAM Stream,
IN PTCHAR szStr,
- IN DWORD len)
+ IN DWORD len)
{
INT Len;
CON_STREAM_WRITE2(Stream, szStr, len, Len);
return Len;
}
+/**
+ * @name ConPuts
+ * Writes a NULL-terminated string to a stream.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] szStr
+ * Pointer to the NULL-terminated string to write.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @remark
+ * Contrary to the CRT puts() function, ConPuts() does not append
+ * a terminating new-line character. In this way it behaves more like
+ * the CRT fputs() function.
+ **/
INT
ConPuts(
IN PCON_STREAM Stream,
return Len;
}
+/**
+ * @name ConPrintfV
+ * Formats and writes a NULL-terminated string to a stream.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] szStr
+ * Pointer to the NULL-terminated format string, that follows the same
+ * specifications as the @a szStr format string in ConPrintf().
+ *
+ * @param[in] args
+ * Parameter describing a variable number of arguments,
+ * initialized with va_start(), that can be expected by the function,
+ * depending on the @p szStr format string. Each argument is used to
+ * replace a <em>format specifier</em> in the format string.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintf(), printf(), vprintf()
+ **/
INT
ConPrintfV(
IN PCON_STREAM Stream,
IN LPWSTR szStr,
- IN va_list args) // arg_ptr
+ IN va_list args)
{
INT Len;
WCHAR bufSrc[CON_RC_STRING_MAX_SIZE];
return Len;
}
+/**
+ * @name ConPrintf
+ * Formats and writes a NULL-terminated string to a stream.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] szStr
+ * Pointer to the NULL-terminated format string, that follows the same
+ * specifications as the @a format string in printf(). This string can
+ * optionally contain embedded <em>format specifiers</em> that are
+ * replaced by the values specified in subsequent additional arguments
+ * and formatted as requested.
+ *
+ * @param[in] ...
+ * Additional arguments that can be expected by the function, depending
+ * on the @p szStr format string. Each argument is used to replace a
+ * <em>format specifier</em> in the format string.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintfV(), printf(), vprintf()
+ **/
INT
__cdecl
ConPrintf(
return Len;
}
+/**
+ * @name ConResPutsEx
+ * Writes a string resource to a stream.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] hInstance
+ * Optional handle to an instance of the module whose executable file
+ * contains the string resource. Can be set to NULL to get the handle
+ * to the application itself.
+ *
+ * @param[in] uID
+ * The identifier of the string to be written.
+ *
+ * @param[in] LanguageId
+ * The language identifier of the resource. If this parameter is
+ * <tt>MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL)</tt>, the current language
+ * associated with the calling thread is used. To specify a language other
+ * than the current language, use the @c MAKELANGID macro to create this
+ * parameter.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @remark
+ * Similarly to ConPuts(), no terminating new-line character is appended.
+ *
+ * @see ConPuts(), ConResPuts()
+ **/
INT
ConResPutsEx(
IN PCON_STREAM Stream,
IN HINSTANCE hInstance OPTIONAL,
- IN UINT uID)
+ IN UINT uID,
+ IN LANGID LanguageId)
{
INT Len;
PWCHAR szStr = NULL;
- Len = K32LoadStringW(hInstance, uID, (PWSTR)&szStr, 0);
+ Len = K32LoadStringExW(hInstance, uID, LanguageId, (PWSTR)&szStr, 0);
if (szStr && Len)
// Len = ConPuts(Stream, szStr);
CON_STREAM_WRITE2(Stream, szStr, Len, Len);
return Len;
}
+/**
+ * @name ConResPuts
+ * Writes a string resource contained in the current application
+ * to a stream.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] uID
+ * The identifier of the string to be written.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @remark
+ * Similarly to ConPuts(), no terminating new-line character is appended.
+ *
+ * @see ConPuts(), ConResPutsEx()
+ **/
INT
ConResPuts(
IN PCON_STREAM Stream,
IN UINT uID)
{
- return ConResPutsEx(Stream, NULL /*GetModuleHandleW(NULL)*/, uID);
+ return ConResPutsEx(Stream, NULL /*GetModuleHandleW(NULL)*/,
+ uID, MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL));
}
+/**
+ * @name ConResPrintfExV
+ * Formats and writes a string resource to a stream.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] hInstance
+ * Optional handle to an instance of the module whose executable file
+ * contains the string resource. Can be set to NULL to get the handle
+ * to the application itself.
+ *
+ * @param[in] uID
+ * The identifier of the format string. The format string follows the
+ * same specifications as the @a szStr format string in ConPrintf().
+ *
+ * @param[in] LanguageId
+ * The language identifier of the resource. If this parameter is
+ * <tt>MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL)</tt>, the current language
+ * associated with the calling thread is used. To specify a language other
+ * than the current language, use the @c MAKELANGID macro to create this
+ * parameter.
+ *
+ * @param[in] args
+ * Parameter describing a variable number of arguments,
+ * initialized with va_start(), that can be expected by the function,
+ * depending on the @p szStr format string. Each argument is used to
+ * replace a <em>format specifier</em> in the format string.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintf(), ConResPrintfEx(), ConResPrintfV(), ConResPrintf()
+ **/
INT
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 Len;
WCHAR bufSrc[CON_RC_STRING_MAX_SIZE];
// NOTE: We may use the special behaviour where nBufMaxSize == 0
- Len = K32LoadStringW(hInstance, uID, bufSrc, ARRAYSIZE(bufSrc));
+ Len = K32LoadStringExW(hInstance, uID, LanguageId, bufSrc, ARRAYSIZE(bufSrc));
if (Len)
Len = ConPrintfV(Stream, bufSrc, args);
return Len;
}
+/**
+ * @name ConResPrintfV
+ * Formats and writes a string resource contained in the
+ * current application to a stream.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] uID
+ * The identifier of the format string. The format string follows the
+ * same specifications as the @a szStr format string in ConPrintf().
+ *
+ * @param[in] args
+ * Parameter describing a variable number of arguments,
+ * initialized with va_start(), that can be expected by the function,
+ * depending on the @p szStr format string. Each argument is used to
+ * replace a <em>format specifier</em> in the format string.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintf(), ConResPrintfExV(), ConResPrintfEx(), ConResPrintf()
+ **/
INT
ConResPrintfV(
IN PCON_STREAM Stream,
IN UINT uID,
- IN va_list args) // arg_ptr
+ IN va_list args)
{
- return ConResPrintfExV(Stream, NULL /*GetModuleHandleW(NULL)*/, uID, args);
+ return ConResPrintfExV(Stream, NULL /*GetModuleHandleW(NULL)*/,
+ uID, MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL),
+ args);
}
+/**
+ * @name ConResPrintfEx
+ * Formats and writes a string resource to a stream.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] hInstance
+ * Optional handle to an instance of the module whose executable file
+ * contains the string resource. Can be set to NULL to get the handle
+ * to the application itself.
+ *
+ * @param[in] uID
+ * The identifier of the format string. The format string follows the
+ * same specifications as the @a szStr format string in ConPrintf().
+ *
+ * @param[in] LanguageId
+ * The language identifier of the resource. If this parameter is
+ * <tt>MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL)</tt>, the current language
+ * associated with the calling thread is used. To specify a language other
+ * than the current language, use the @c MAKELANGID macro to create this
+ * parameter.
+ *
+ * @param[in] ...
+ * Additional arguments that can be expected by the function, depending
+ * on the @p szStr format string. Each argument is used to replace a
+ * <em>format specifier</em> in the format string.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintf(), ConResPrintfExV(), ConResPrintfV(), ConResPrintf()
+ **/
INT
__cdecl
ConResPrintfEx(
IN PCON_STREAM Stream,
IN HINSTANCE hInstance OPTIONAL,
- IN UINT uID,
+ IN UINT uID,
+ IN LANGID LanguageId,
...)
{
INT Len;
va_list args;
- va_start(args, uID);
- Len = ConResPrintfExV(Stream, hInstance, uID, args);
+ va_start(args, LanguageId);
+ Len = ConResPrintfExV(Stream, hInstance, uID, LanguageId, args);
va_end(args);
return Len;
}
+/**
+ * @name ConResPrintf
+ * Formats and writes a string resource contained in the
+ * current application to a stream.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] uID
+ * The identifier of the format string. The format string follows the
+ * same specifications as the @a szStr format string in ConPrintf().
+ *
+ * @param[in] ...
+ * Additional arguments that can be expected by the function, depending
+ * on the @p szStr format string. Each argument is used to replace a
+ * <em>format specifier</em> in the format string.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintf(), ConResPrintfExV(), ConResPrintfEx(), ConResPrintfV()
+ **/
INT
__cdecl
ConResPrintf(
return Len;
}
+/**
+ * @name ConMsgPuts
+ * Writes a message string to a stream without formatting. The function
+ * requires a message definition as input. The message definition can come
+ * from a buffer passed to the function. It can come from a message table
+ * resource in an already-loaded module, or the caller can ask the function
+ * to search the system's message table resource(s) for the message definition.
+ * Please refer to the Win32 FormatMessage() function for more details.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] dwFlags
+ * The formatting options, and how to interpret the @p lpSource parameter.
+ * See FormatMessage() for more details. The @b@c FORMAT_MESSAGE_ALLOCATE_BUFFER
+ * and @b@c FORMAT_MESSAGE_ARGUMENT_ARRAY flags are always ignored.
+ * The function implicitly uses the @b@c FORMAT_MESSAGE_IGNORE_INSERTS and
+ * @b@c FORMAT_MESSAGE_MAX_WIDTH_MASK flags to implement its behaviour.
+ *
+ * @param[in] lpSource
+ * The location of the message definition. The type of this parameter
+ * depends upon the settings in the @p dwFlags parameter.
+ *
+ * @param[in] dwMessageId
+ * The message identifier for the requested message. This parameter
+ * is ignored if @p dwFlags includes @b@c FORMAT_MESSAGE_FROM_STRING.
+ *
+ * @param[in] dwLanguageId
+ * The language identifier for the requested message. This parameter
+ * is ignored if @p dwFlags includes @b@c FORMAT_MESSAGE_FROM_STRING.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @remark
+ * Similarly to ConPuts(), no terminating new-line character is appended.
+ *
+ * @see ConPuts(), ConResPuts() and associated functions,
+ * <a href="FormatMessage() (on MSDN)">https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx</a>
+ **/
INT
ConMsgPuts(
IN PCON_STREAM Stream,
/*
* Sanitize dwFlags. This version always ignore explicitely the inserts
- * as we emulate the behaviour of the *puts function.
+ * as we emulate the behaviour of the (f)puts function.
*/
dwFlags |= FORMAT_MESSAGE_ALLOCATE_BUFFER; // Always allocate an internal buffer.
dwFlags |= FORMAT_MESSAGE_IGNORE_INSERTS; // Ignore inserts for FormatMessage.
dwMessageId,
dwLanguageId,
(LPWSTR)&lpMsgBuf,
- 0, NULL);
+ 0,
+ NULL);
}
_SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
{
return Len;
}
+/**
+ * @name ConMsgPrintf2V
+ * Formats and writes a message string to a stream.
+ *
+ * @remark For internal use only.
+ *
+ * @see ConMsgPrintfV()
+ **/
INT
ConMsgPrintf2V(
IN PCON_STREAM Stream,
IN LPCVOID lpSource OPTIONAL,
IN DWORD dwMessageId,
IN DWORD dwLanguageId,
- IN va_list args) // arg_ptr
+ IN va_list args)
{
INT Len;
DWORD dwLength = 0;
dwMessageId,
dwLanguageId,
(LPWSTR)&lpMsgBuf,
- 0, NULL);
+ 0,
+ NULL);
}
_SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
{
return Len;
}
+/**
+ * @name ConMsgPrintfV
+ * Formats and writes a message string to a stream. The function requires
+ * a message definition as input. The message definition can come from a
+ * buffer passed to the function. It can come from a message table resource
+ * in an already-loaded module, or the caller can ask the function to search
+ * the system's message table resource(s) for the message definition.
+ * Please refer to the Win32 FormatMessage() function for more details.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] dwFlags
+ * The formatting options, and how to interpret the @p lpSource parameter.
+ * See FormatMessage() for more details. The @b@c FORMAT_MESSAGE_ALLOCATE_BUFFER
+ * flags is always ignored. The function implicitly uses the
+ * @b@c FORMAT_MESSAGE_MAX_WIDTH_MASK flag to implement its behaviour.
+ *
+ * @param[in] lpSource
+ * The location of the message definition. The type of this parameter
+ * depends upon the settings in the @p dwFlags parameter.
+ *
+ * @param[in] dwMessageId
+ * The message identifier for the requested message. This parameter
+ * is ignored if @p dwFlags includes @b@c FORMAT_MESSAGE_FROM_STRING.
+ *
+ * @param[in] dwLanguageId
+ * The language identifier for the requested message. This parameter
+ * is ignored if @p dwFlags includes @b@c FORMAT_MESSAGE_FROM_STRING.
+ *
+ * @param[in] Arguments
+ * Optional pointer to an array of values describing a variable number of
+ * arguments, depending on the message string. Each argument is used to
+ * replace an <em>insert sequence</em> in the message string.
+ * By default, the @p Arguments parameter is of type @c va_list*, initialized
+ * with va_start(). The state of the @c va_list argument is undefined upon
+ * return from the function. To use the @c va_list again, destroy the variable
+ * argument list pointer using va_end() and reinitialize it with va_start().
+ * If you do not have a pointer of type @c va_list*, then specify the
+ * @b@c FORMAT_MESSAGE_ARGUMENT_ARRAY flag and pass a pointer to an array
+ * of @c DWORD_PTR values; those values are input to the message formatted
+ * as the insert values. Each insert must have a corresponding element in
+ * the array.
+ *
+ * @remark
+ * Contrary to printf(), ConPrintf(), ConResPrintf() and associated functions,
+ * the ConMsg* functions work on format strings that contain <em>insert sequences</em>.
+ * These sequences extend the standard <em>format specifiers</em> as they
+ * allow to specify an <em>insert number</em> referring which precise value
+ * given in arguments to use.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintf(), ConResPrintf() and associated functions, ConMsgPrintf(),
+ * <a href="FormatMessage() (on MSDN)">https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx</a>
+ **/
INT
ConMsgPrintfV(
IN PCON_STREAM Stream,
IN LPCVOID lpSource OPTIONAL,
IN DWORD dwMessageId,
IN DWORD dwLanguageId,
- IN va_list args) // arg_ptr
+ IN va_list *Arguments OPTIONAL)
{
INT Len;
DWORD dwLength = 0;
/* Sanitize dwFlags */
dwFlags |= FORMAT_MESSAGE_ALLOCATE_BUFFER; // Always allocate an internal buffer.
-// dwFlags &= ~FORMAT_MESSAGE_IGNORE_INSERTS; // We always use arguments.
- dwFlags &= ~FORMAT_MESSAGE_ARGUMENT_ARRAY; // We always use arguments of type 'va_list'.
-
//
// NOTE: Technique taken from eventvwr.c!GetMessageStringFromDll()
//
-
dwFlags |= FORMAT_MESSAGE_MAX_WIDTH_MASK;
/*
dwMessageId,
dwLanguageId,
(LPWSTR)&lpMsgBuf,
- 0, &args);
+ 0,
+ Arguments);
Len = (INT)dwLength;
{
// ASSERT(dwLength != 0);
- // Len = ConPrintfV(Stream, lpMsgBuf, args);
CON_STREAM_WRITE2(Stream, lpMsgBuf, dwLength, Len);
/* Fixup returned length in case of errors */
return Len;
}
+/**
+ * @name ConMsgPrintf
+ * Formats and writes a message string to a stream. The function requires
+ * a message definition as input. The message definition can come from a
+ * buffer passed to the function. It can come from a message table resource
+ * in an already-loaded module, or the caller can ask the function to search
+ * the system's message table resource(s) for the message definition.
+ * Please refer to the Win32 FormatMessage() function for more details.
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] dwFlags
+ * The formatting options, and how to interpret the @p lpSource parameter.
+ * See FormatMessage() for more details. The @b@c FORMAT_MESSAGE_ALLOCATE_BUFFER
+ * and @b@c FORMAT_MESSAGE_ARGUMENT_ARRAY flags are always ignored.
+ * The function implicitly uses the @b@c FORMAT_MESSAGE_MAX_WIDTH_MASK flag
+ * to implement its behaviour.
+ *
+ * @param[in] lpSource
+ * The location of the message definition. The type of this parameter
+ * depends upon the settings in the @p dwFlags parameter.
+ *
+ * @param[in] dwMessageId
+ * The message identifier for the requested message. This parameter
+ * is ignored if @p dwFlags includes @b@c FORMAT_MESSAGE_FROM_STRING.
+ *
+ * @param[in] dwLanguageId
+ * The language identifier for the requested message. This parameter
+ * is ignored if @p dwFlags includes @b@c FORMAT_MESSAGE_FROM_STRING.
+ *
+ * @param[in] ...
+ * Additional arguments that can be expected by the function, depending
+ * on the message string. Each argument is used to replace an
+ * <em>insert sequence</em> in the message string.
+ *
+ * @remark
+ * Contrary to printf(), ConPrintf(), ConResPrintf() and associated functions,
+ * the ConMsg* functions work on format strings that contain <em>insert sequences</em>.
+ * These sequences extend the standard <em>format specifiers</em> as they
+ * allow to specify an <em>insert number</em> referring which precise value
+ * given in arguments to use.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintf(), ConResPrintf() and associated functions, ConMsgPrintfV(),
+ * <a href="FormatMessage() (on MSDN)">https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx</a>
+ **/
INT
__cdecl
ConMsgPrintf(
INT Len;
va_list args;
+ /* Sanitize dwFlags */
+ dwFlags &= ~FORMAT_MESSAGE_ARGUMENT_ARRAY;
+
va_start(args, dwLanguageId);
- // ConMsgPrintf2V
Len = ConMsgPrintfV(Stream,
dwFlags,
lpSource,
dwMessageId,
dwLanguageId,
- args);
+ &args);
+ va_end(args);
+
+ return Len;
+}
+
+/**
+ * @name ConResMsgPrintfExV
+ * Formats and writes a message string to a stream. The function requires
+ * a message definition as input. Contrary to the ConMsg* or the Win32
+ * FormatMessage() functions, the message definition comes from a resource
+ * string table, much like the strings for ConResPrintf(), but is formatted
+ * according to the rules of ConMsgPrintf().
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] hInstance
+ * Optional handle to an instance of the module whose executable file
+ * contains the string resource. Can be set to NULL to get the handle
+ * to the application itself.
+ *
+ * @param[in] dwFlags
+ * The formatting options, see FormatMessage() for more details.
+ * The only valid flags are @b@c FORMAT_MESSAGE_ARGUMENT_ARRAY and
+ * @b@c FORMAT_MESSAGE_IGNORE_INSERTS. All the other flags are internally
+ * overridden by the function to implement its behaviour.
+ *
+ * @param[in] uID
+ * The identifier of the message string. The format string follows the
+ * same specifications as the @a lpSource format string in ConMsgPrintf().
+ *
+ * @param[in] LanguageId
+ * The language identifier of the resource. If this parameter is
+ * <tt>MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL)</tt>, the current language
+ * associated with the calling thread is used. To specify a language other
+ * than the current language, use the @c MAKELANGID macro to create this
+ * parameter.
+ *
+ * @param[in] args
+ * Parameter describing a variable number of arguments, initialized
+ * with va_start(), that can be expected by the function, depending
+ * on the message string. Each argument is used to replace an
+ * <em>insert sequence</em> in the message string.
+ *
+ * @remark
+ * Contrary to printf(), ConPrintf(), ConResPrintf() and associated functions,
+ * the ConMsg* functions work on format strings that contain <em>insert sequences</em>.
+ * These sequences extend the standard <em>format specifiers</em> as they
+ * allow to specify an <em>insert number</em> referring which precise value
+ * given in arguments to use.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintf(), ConResPrintf() and associated functions, ConMsgPrintf(),
+ * <a href="FormatMessage() (on MSDN)">https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx</a>
+ **/
+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 Len;
+ DWORD dwLength = 0;
+ LPWSTR lpMsgBuf = NULL;
+ WCHAR bufSrc[CON_RC_STRING_MAX_SIZE];
+
+ /* Retrieve the string from the resource string table */
+ // NOTE: We may use the special behaviour where nBufMaxSize == 0
+ Len = K32LoadStringExW(hInstance, uID, LanguageId, bufSrc, ARRAYSIZE(bufSrc));
+ if (Len == 0)
+ return Len;
+
+ /* Sanitize dwFlags */
+ dwFlags |= FORMAT_MESSAGE_ALLOCATE_BUFFER; // Always allocate an internal buffer.
+ //
+ // NOTE: Technique taken from eventvwr.c!GetMessageStringFromDll()
+ //
+ dwFlags |= FORMAT_MESSAGE_MAX_WIDTH_MASK;
+
+ /* The string has already been manually loaded */
+ dwFlags &= ~(FORMAT_MESSAGE_FROM_HMODULE | FORMAT_MESSAGE_FROM_SYSTEM);
+ dwFlags |= FORMAT_MESSAGE_FROM_STRING;
+
+ /*
+ * Retrieve the message string without appending extra newlines.
+ * Use the "safe" FormatMessage version (SEH-protected) to protect
+ * from invalid string parameters.
+ */
+ dwLength = FormatMessageSafeW(dwFlags,
+ bufSrc,
+ 0, 0,
+ (LPWSTR)&lpMsgBuf,
+ 0,
+ Arguments);
+
+ Len = (INT)dwLength;
+
+ if (!lpMsgBuf)
+ {
+ // ASSERT(dwLength == 0);
+ }
+ else
+ {
+ // ASSERT(dwLength != 0);
+
+ CON_STREAM_WRITE2(Stream, lpMsgBuf, dwLength, Len);
+
+ /* Fixup returned length in case of errors */
+ if (Len < 0)
+ Len = 0;
+
+ /* Free the buffer allocated by FormatMessage */
+ LocalFree(lpMsgBuf);
+ }
+
+ return Len;
+}
+
+/**
+ * @name ConResMsgPrintfV
+ * Formats and writes a message string to a stream. The function requires
+ * a message definition as input. Contrary to the ConMsg* or the Win32
+ * FormatMessage() functions, the message definition comes from a resource
+ * string table, much like the strings for ConResPrintf(), but is formatted
+ * according to the rules of ConMsgPrintf().
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] dwFlags
+ * The formatting options, see FormatMessage() for more details.
+ * The only valid flags are @b@c FORMAT_MESSAGE_ARGUMENT_ARRAY and
+ * @b@c FORMAT_MESSAGE_IGNORE_INSERTS. All the other flags are internally
+ * overridden by the function to implement its behaviour.
+ *
+ * @param[in] uID
+ * The identifier of the message string. The format string follows the
+ * same specifications as the @a lpSource format string in ConMsgPrintf().
+ *
+ * @param[in] Arguments
+ * Optional pointer to an array of values describing a variable number of
+ * arguments, depending on the message string. Each argument is used to
+ * replace an <em>insert sequence</em> in the message string.
+ * By default, the @p Arguments parameter is of type @c va_list*, initialized
+ * with va_start(). The state of the @c va_list argument is undefined upon
+ * return from the function. To use the @c va_list again, destroy the variable
+ * argument list pointer using va_end() and reinitialize it with va_start().
+ * If you do not have a pointer of type @c va_list*, then specify the
+ * @b@c FORMAT_MESSAGE_ARGUMENT_ARRAY flag and pass a pointer to an array
+ * of @c DWORD_PTR values; those values are input to the message formatted
+ * as the insert values. Each insert must have a corresponding element in
+ * the array.
+ *
+ * @remark
+ * Contrary to printf(), ConPrintf(), ConResPrintf() and associated functions,
+ * the ConMsg* functions work on format strings that contain <em>insert sequences</em>.
+ * These sequences extend the standard <em>format specifiers</em> as they
+ * allow to specify an <em>insert number</em> referring which precise value
+ * given in arguments to use.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintf(), ConResPrintf() and associated functions, ConMsgPrintf(),
+ * <a href="FormatMessage() (on MSDN)">https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx</a>
+ **/
+INT
+ConResMsgPrintfV(
+ IN PCON_STREAM Stream,
+ IN DWORD dwFlags,
+ IN UINT uID,
+ IN va_list *Arguments OPTIONAL)
+{
+ return ConResMsgPrintfExV(Stream, NULL /*GetModuleHandleW(NULL)*/,
+ dwFlags, uID,
+ MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL),
+ Arguments);
+}
+
+/**
+ * @name ConResMsgPrintfEx
+ * Formats and writes a message string to a stream. The function requires
+ * a message definition as input. Contrary to the ConMsg* or the Win32
+ * FormatMessage() functions, the message definition comes from a resource
+ * string table, much like the strings for ConResPrintf(), but is formatted
+ * according to the rules of ConMsgPrintf().
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] hInstance
+ * Optional handle to an instance of the module whose executable file
+ * contains the string resource. Can be set to NULL to get the handle
+ * to the application itself.
+ *
+ * @param[in] dwFlags
+ * The formatting options, see FormatMessage() for more details.
+ * The only valid flag is @b@c FORMAT_MESSAGE_IGNORE_INSERTS.
+ * All the other flags are internally overridden by the function
+ * to implement its behaviour.
+ *
+ * @param[in] uID
+ * The identifier of the message string. The format string follows the
+ * same specifications as the @a lpSource format string in ConMsgPrintf().
+ *
+ * @param[in] LanguageId
+ * The language identifier of the resource. If this parameter is
+ * <tt>MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL)</tt>, the current language
+ * associated with the calling thread is used. To specify a language other
+ * than the current language, use the @c MAKELANGID macro to create this
+ * parameter.
+ *
+ * @param[in] ...
+ * Additional arguments that can be expected by the function, depending
+ * on the message string. Each argument is used to replace an
+ * <em>insert sequence</em> in the message string.
+ *
+ * @remark
+ * Contrary to printf(), ConPrintf(), ConResPrintf() and associated functions,
+ * the ConMsg* functions work on format strings that contain <em>insert sequences</em>.
+ * These sequences extend the standard <em>format specifiers</em> as they
+ * allow to specify an <em>insert number</em> referring which precise value
+ * given in arguments to use.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintf(), ConResPrintf() and associated functions, ConMsgPrintf(),
+ * <a href="FormatMessage() (on MSDN)">https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx</a>
+ **/
+INT
+__cdecl
+ConResMsgPrintfEx(
+ IN PCON_STREAM Stream,
+ IN HINSTANCE hInstance OPTIONAL,
+ IN DWORD dwFlags,
+ IN UINT uID,
+ IN LANGID LanguageId,
+ ...)
+{
+ INT Len;
+ va_list args;
+
+ /* Sanitize dwFlags */
+ dwFlags &= ~FORMAT_MESSAGE_ARGUMENT_ARRAY;
+
+ va_start(args, LanguageId);
+ Len = ConResMsgPrintfExV(Stream,
+ hInstance,
+ dwFlags,
+ uID,
+ LanguageId,
+ &args);
+ va_end(args);
+
+ return Len;
+}
+
+/**
+ * @name ConResMsgPrintf
+ * Formats and writes a message string to a stream. The function requires
+ * a message definition as input. Contrary to the ConMsg* or the Win32
+ * FormatMessage() functions, the message definition comes from a resource
+ * string table, much like the strings for ConResPrintf(), but is formatted
+ * according to the rules of ConMsgPrintf().
+ *
+ * @param[in] Stream
+ * Stream to which the write operation is issued.
+ *
+ * @param[in] dwFlags
+ * The formatting options, see FormatMessage() for more details.
+ * The only valid flag is @b@c FORMAT_MESSAGE_IGNORE_INSERTS.
+ * All the other flags are internally overridden by the function
+ * to implement its behaviour.
+ *
+ * @param[in] uID
+ * The identifier of the message string. The format string follows the
+ * same specifications as the @a lpSource format string in ConMsgPrintf().
+ *
+ * @param[in] ...
+ * Additional arguments that can be expected by the function, depending
+ * on the message string. Each argument is used to replace an
+ * <em>insert sequence</em> in the message string.
+ *
+ * @remark
+ * Contrary to printf(), ConPrintf(), ConResPrintf() and associated functions,
+ * the ConMsg* functions work on format strings that contain <em>insert sequences</em>.
+ * These sequences extend the standard <em>format specifiers</em> as they
+ * allow to specify an <em>insert number</em> referring which precise value
+ * given in arguments to use.
+ *
+ * @return
+ * Numbers of characters successfully written to @p Stream.
+ *
+ * @see ConPrintf(), ConResPrintf() and associated functions, ConMsgPrintf(),
+ * <a href="FormatMessage() (on MSDN)">https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx</a>
+ **/
+INT
+__cdecl
+ConResMsgPrintf(
+ IN PCON_STREAM Stream,
+ IN DWORD dwFlags,
+ IN UINT uID,
+ ...)
+{
+ INT Len;
+ va_list args;
+
+ /* Sanitize dwFlags */
+ dwFlags &= ~FORMAT_MESSAGE_ARGUMENT_ARRAY;
+
+ va_start(args, uID);
+ Len = ConResMsgPrintfV(Stream, dwFlags, uID, &args);
va_end(args);
return Len;
projects / reactos.git / commitdiff