https://git.reactos.org/?p=reactos.git;a=commitdiff;h=ce044cf80e6a45e0c3d4eb1b695a8c8ccd3e58f7
commit ce044cf80e6a45e0c3d4eb1b695a8c8ccd3e58f7 Author: Hermès Bélusca-Maïto <hermes.belusca-ma...@reactos.org> AuthorDate: Fri Feb 2 21:48:18 2018 +0100 Commit: Hermès Bélusca-Maïto <hermes.belusca-ma...@reactos.org> CommitDate: Fri Feb 2 22:19:54 2018 +0100 [CONUTILS] Fix and improve the documentation for "outstream" and "utils", addendum to f982d77. --- sdk/lib/conutils/outstream.c | 78 ++++++++++++++----------- sdk/lib/conutils/utils.c | 135 ++++++++++++++++++++++++++++++++++++++----- 2 files changed, 165 insertions(+), 48 deletions(-) diff --git a/sdk/lib/conutils/outstream.c b/sdk/lib/conutils/outstream.c index ce25d51c1d..580269cf1e 100644 --- a/sdk/lib/conutils/outstream.c +++ b/sdk/lib/conutils/outstream.c @@ -795,10 +795,10 @@ ConResPrintf( * * @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. + * See FormatMessage() for more details. The @b FORMAT_MESSAGE_ALLOCATE_BUFFER + * and @b FORMAT_MESSAGE_ARGUMENT_ARRAY flags are always ignored. + * The function implicitly uses the @b FORMAT_MESSAGE_IGNORE_INSERTS and + * @b FORMAT_MESSAGE_MAX_WIDTH_MASK flags to implement its behaviour. * * @param[in] lpSource * The location of the message definition. The type of this parameter @@ -806,11 +806,11 @@ ConResPrintf( * * @param[in] dwMessageId * The message identifier for the requested message. This parameter - * is ignored if @p dwFlags includes @b@c FORMAT_MESSAGE_FROM_STRING. + * is ignored if @p dwFlags includes @b 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. + * is ignored if @p dwFlags includes @b FORMAT_MESSAGE_FROM_STRING. * * @return * Numbers of characters successfully written to @p Stream. @@ -819,7 +819,7 @@ ConResPrintf( * 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> + * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx">FormatMessage() (on MSDN)</a> **/ INT ConMsgPuts( @@ -976,9 +976,9 @@ ConMsgPrintf2V( * * @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 + * See FormatMessage() for more details. The @b 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. + * @b FORMAT_MESSAGE_MAX_WIDTH_MASK flag to implement its behaviour. * * @param[in] lpSource * The location of the message definition. The type of this parameter @@ -986,11 +986,11 @@ ConMsgPrintf2V( * * @param[in] dwMessageId * The message identifier for the requested message. This parameter - * is ignored if @p dwFlags includes @b@c FORMAT_MESSAGE_FROM_STRING. + * is ignored if @p dwFlags includes @b 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. + * is ignored if @p dwFlags includes @b FORMAT_MESSAGE_FROM_STRING. * * @param[in] Arguments * Optional pointer to an array of values describing a variable number of @@ -1001,7 +1001,7 @@ ConMsgPrintf2V( * 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 + * @b 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. @@ -1017,7 +1017,7 @@ ConMsgPrintf2V( * 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> + * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx">FormatMessage() (on MSDN)</a> **/ INT ConMsgPrintfV( @@ -1089,9 +1089,9 @@ ConMsgPrintfV( * * @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 + * See FormatMessage() for more details. The @b FORMAT_MESSAGE_ALLOCATE_BUFFER + * and @b FORMAT_MESSAGE_ARGUMENT_ARRAY flags are always ignored. + * The function implicitly uses the @b FORMAT_MESSAGE_MAX_WIDTH_MASK flag * to implement its behaviour. * * @param[in] lpSource @@ -1100,11 +1100,11 @@ ConMsgPrintfV( * * @param[in] dwMessageId * The message identifier for the requested message. This parameter - * is ignored if @p dwFlags includes @b@c FORMAT_MESSAGE_FROM_STRING. + * is ignored if @p dwFlags includes @b 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. + * is ignored if @p dwFlags includes @b FORMAT_MESSAGE_FROM_STRING. * * @param[in] ... * Additional arguments that can be expected by the function, depending @@ -1122,7 +1122,7 @@ ConMsgPrintfV( * 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> + * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx">FormatMessage() (on MSDN)</a> **/ INT __cdecl @@ -1170,8 +1170,8 @@ ConMsgPrintf( * * @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 + * The only valid flags are @b FORMAT_MESSAGE_ARGUMENT_ARRAY and + * @b FORMAT_MESSAGE_IGNORE_INSERTS. All the other flags are internally * overridden by the function to implement its behaviour. * * @param[in] uID @@ -1185,11 +1185,19 @@ ConMsgPrintf( * 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. + * @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 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, @@ -1202,7 +1210,7 @@ ConMsgPrintf( * 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> + * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx">FormatMessage() (on MSDN)</a> **/ INT ConResMsgPrintfExV( @@ -1283,8 +1291,8 @@ ConResMsgPrintfExV( * * @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 + * The only valid flags are @b FORMAT_MESSAGE_ARGUMENT_ARRAY and + * @b FORMAT_MESSAGE_IGNORE_INSERTS. All the other flags are internally * overridden by the function to implement its behaviour. * * @param[in] uID @@ -1300,7 +1308,7 @@ ConResMsgPrintfExV( * 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 + * @b 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. @@ -1316,7 +1324,7 @@ ConResMsgPrintfExV( * 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> + * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx">FormatMessage() (on MSDN)</a> **/ INT ConResMsgPrintfV( @@ -1349,7 +1357,7 @@ ConResMsgPrintfV( * * @param[in] dwFlags * The formatting options, see FormatMessage() for more details. - * The only valid flag is @b@c FORMAT_MESSAGE_IGNORE_INSERTS. + * The only valid flag is @b FORMAT_MESSAGE_IGNORE_INSERTS. * All the other flags are internally overridden by the function * to implement its behaviour. * @@ -1380,7 +1388,7 @@ ConResMsgPrintfV( * 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> + * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx">FormatMessage() (on MSDN)</a> **/ INT __cdecl @@ -1423,7 +1431,7 @@ ConResMsgPrintfEx( * * @param[in] dwFlags * The formatting options, see FormatMessage() for more details. - * The only valid flag is @b@c FORMAT_MESSAGE_IGNORE_INSERTS. + * The only valid flag is @b FORMAT_MESSAGE_IGNORE_INSERTS. * All the other flags are internally overridden by the function * to implement its behaviour. * @@ -1447,7 +1455,7 @@ ConResMsgPrintfEx( * 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> + * <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx">FormatMessage() (on MSDN)</a> **/ INT __cdecl diff --git a/sdk/lib/conutils/utils.c b/sdk/lib/conutils/utils.c index e6e6fb8d24..8462be06f3 100644 --- a/sdk/lib/conutils/utils.c +++ b/sdk/lib/conutils/utils.c @@ -52,10 +52,48 @@ MultiByteToMultiByte( #endif -/* - * 'LoadStringW' API ripped from user32.dll to remove - * any dependency of this library from user32.dll - */ +/** + * @name K32LoadStringExW + * Loads a string resource from the executable file associated with a + * specified module, copies the string into a buffer, and appends a + * terminating null character. + * This is basically the LoadString() API ripped from user32.dll to + * remove any dependency of ConUtils from user32.dll, and to add support + * for loading strings from other languages than the current one. + * + * @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 loaded. + * + * @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[out] lpBuffer + * The buffer that receives the string. Must be of sufficient length + * to hold a pointer (8 bytes). + * + * @param[in] nBufferMax + * The size of the buffer, in characters. The string is truncated and + * NULL-terminated if it is longer than the number of characters specified. + * If this parameter is 0, then @p lpBuffer receives a read-only pointer + * to the resource itself. + * + * @return + * If the function succeeds, the return value is the number of characters + * copied into the buffer, not including the terminating null character, + * or zero if the string resource does not exist. To get extended error + * information, call GetLastError(). + * + * @see LoadString(), K32LoadStringW() + **/ INT WINAPI K32LoadStringExW( @@ -121,6 +159,15 @@ K32LoadStringExW( return i; } +/** + * @name K32LoadStringW + * Loads a string resource from the executable file associated with a + * specified module, copies the string into a buffer, and appends a + * terminating null character. + * This is a restricted version of K32LoadStringExW(). + * + * @see LoadString(), K32LoadStringExW() + **/ INT WINAPI K32LoadStringW( @@ -135,11 +182,73 @@ K32LoadStringW( lpBuffer, nBufferMax); } -/* - * "Safe" version of FormatMessageW, that does not crash if a malformed - * source string is retrieved and then being used for formatting. - * It basically wraps calls to FormatMessageW within SEH. - */ +/** + * @name FormatMessageSafeW + * Loads and formats a message string. 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] dwFlags + * The formatting options, and how to interpret the @p lpSource parameter. + * See FormatMessage() for more details. + * + * @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 FORMAT_MESSAGE_FROM_STRING. + * + * @param[in] dwLanguageId + * The language identifier for the requested message. This parameter + * is ignored if @p dwFlags includes @b FORMAT_MESSAGE_FROM_STRING. + * + * @param[out] lpBuffer + * A pointer to a buffer that receives the null-terminated string that + * specifies the formatted message. If @p dwFlags includes + * @b FORMAT_MESSAGE_ALLOCATE_BUFFER, the function allocates a buffer + * using the LocalAlloc() function, and places the pointer to the buffer + * at the address specified in @p lpBuffer. + * This buffer cannot be larger than 64kB. + * + * @param[in] nSize + * If the @b FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set, this parameter + * specifies the size of the output buffer, in @b TCHARs. + * If @b FORMAT_MESSAGE_ALLOCATE_BUFFER is set, this parameter specifies + * the minimum number of @b TCHARs to allocate for an output buffer. + * The output buffer cannot be larger than 64kB. + * + * @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 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. + * + * @return + * If the function succeeds, the return value is the number of characters + * copied into the buffer, not including the terminating null character, + * or zero if the string resource does not exist. To get extended error + * information, call GetLastError(). + * + * @remark + * This function is a "safe" version of FormatMessage(), that does not + * crash if a malformed source string is retrieved and then being used + * for formatting. It basically wraps calls to FormatMessage() within SEH. + * + * @see <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms679351(v=vs.85).aspx">FormatMessage() (on MSDN)</a> + **/ DWORD WINAPI FormatMessageSafeW( @@ -220,8 +329,8 @@ FormatMessageSafeW( * 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. + * @b TRUE when the handle refers to a valid TTY object, + * @b FALSE if it does not. * * @remark * This test is more general than IsConsoleHandle() as it is not limited @@ -250,8 +359,8 @@ IsTTYHandle(IN HANDLE hHandle) * 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. + * @b TRUE when the handle refers to a valid Win32 console object, + * @b FALSE if it does not. * * @see IsTTYHandle() **/