utils.c File Reference

General-purpose utility functions (wrappers around or reimplementations of Win32 APIs). More...

#include <windef.h>
#include <winbase.h>
#include <winnls.h>
#include <winuser.h>
#include <wincon.h>
#include <strsafe.h>
#include <pseh/pseh2.h>
#include "utils.h"

Include dependency graph for utils.c:

Go to the source code of this file.

Macros
#define	UNICODE
#define	_UNICODE

Functions
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. Parameters [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. [in] uID The identifier of the string to be loaded. [in] LanguageId The language identifier of the resource. If this parameter is MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL), the current language associated with the calling thread is used. To specify a language other than the current language, use the MAKELANGID macro to create this parameter. [out] lpBuffer The buffer that receives the string. Must be of sufficient length to hold a pointer (8 bytes). [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 lpBuffer receives a read-only pointer to the resource itself. Returns 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 also LoadString(), K32LoadStringW()
INT WINAPI	K32LoadStringExW (IN HINSTANCE hInstance OPTIONAL, IN UINT uID, IN LANGID LanguageId, OUT LPWSTR lpBuffer, IN INT nBufferMax)
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 also LoadString(), K32LoadStringExW()
INT WINAPI	K32LoadStringW (IN HINSTANCE hInstance OPTIONAL, IN UINT uID, OUT LPWSTR lpBuffer, IN INT nBufferMax)
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. Parameters [in] dwFlags The formatting options, and how to interpret the lpSource parameter. See FormatMessage() for more details. [in] lpSource The location of the message definition. The type of this parameter depends upon the settings in the dwFlags parameter. [in] dwMessageId The message identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING. [in] dwLanguageId The language identifier for the requested message. This parameter is ignored if dwFlags includes FORMAT_MESSAGE_FROM_STRING. [out] lpBuffer A pointer to a buffer that receives the null-terminated string that specifies the formatted message. If dwFlags includes 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 lpBuffer. This buffer cannot be larger than 64kB. [in] nSize If the FORMAT_MESSAGE_ALLOCATE_BUFFER flag is not set, this parameter specifies the size of the output buffer, in TCHARs. If FORMAT_MESSAGE_ALLOCATE_BUFFER is set, this parameter specifies the minimum number of TCHARs to allocate for an output buffer. The output buffer cannot be larger than 64kB. [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 insert sequence in the message string. By default, the Arguments parameter is of type va_list*, initialized with va_start(). The state of the va_list argument is undefined upon return from the function. To use the 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 va_list*, then specify the FORMAT_MESSAGE_ARGUMENT_ARRAY flag and pass a pointer to an array of 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. Returns 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(). Remarks 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 also FormatMessage() (on MSDN)
DWORD WINAPI	FormatMessageSafeW (IN DWORD dwFlags, IN LPCVOID lpSource OPTIONAL, IN DWORD dwMessageId, IN DWORD dwLanguageId, OUT LPWSTR lpBuffer, IN DWORD nSize, IN va_list *Arguments OPTIONAL)
ConSetThreadUILanguage
Sets the current thread's user interface language. Mostly used by console applications for selecting a language identifier that best supports the NT Console. This function dynamically loads and calls kernel32!SetThreadUILanguage() so as to be able to work on older environments where this API is not supported. The FormatMessage() API also bases itself on the thread's current language for its default behaviour (unless an explicit language identifier has been provided). Parameters [in,opt] LangId (Vista+) A non-zero language identifier that specifies the current thread's user interface language to set. (XP/2003) Set the language identifier to 0 for selecting a language identifier that best supports the NT Console. Returns Returns LangId in case of success, or 0 in case of failure. If LangId was set to 0, the function always succeeds and returns the language identifier that best supports the NT Console. Remarks This function is thread-safe. See also SetThreadUILanguage() (on MSDN)
LANGID	ConSetThreadUILanguage (IN LANGID LangId OPTIONAL)
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. Parameters [in] hHandle Handle to the TTY object to check for. Returns TRUE when the handle refers to a valid TTY object, FALSE if it does not. Remarks This test is more general than IsConsoleHandle() as it is not limited to Win32 console objects only. See also IsConsoleHandle()
BOOL	IsTTYHandle (IN HANDLE hHandle)
IsConsoleHandle
Checks whether a handle refers to a valid Win32 console object. Parameters [in] hHandle Handle to the Win32 console object to check for: console input buffer, console output buffer. Returns TRUE when the handle refers to a valid Win32 console object, FALSE if it does not. See also IsTTYHandle()
BOOL	IsConsoleHandle (IN HANDLE hHandle)

Detailed Description

General-purpose utility functions (wrappers around or reimplementations of Win32 APIs).

Definition in file utils.c.

Macro Definition Documentation

_UNICODE

#define _UNICODE

Definition at line 20 of file utils.c.

UNICODE

#define UNICODE

Definition at line 19 of file utils.c.

Function Documentation

ConSetThreadUILanguage()

LANGID ConSetThreadUILanguage

(

IN LANGID LangId

OPTIONAL

)

Definition at line 352 of file utils.c.

{
    /* The function pointer is shared amongst all threads */
    static volatile LANGID (WINAPI *pfnSetThreadUILanguage)(LANGID) = NULL;
 
    if (!pfnSetThreadUILanguage)
    {
        /* Load the API from kernel32 */
        PVOID pFunc = (PVOID)GetProcAddress(GetModuleHandleW(L"kernel32.dll"), "SetThreadUILanguage");
        if (!pFunc)
        {
            /* Fail since the API is not available */
            return 0;
        }
        /* Set the function pointer in case it hasn't been already set by another thread */
        InterlockedCompareExchangePointer((PVOID*)&pfnSetThreadUILanguage, pFunc, NULL);
        // ASSERT(pfnSetThreadUILanguage);
    }
    return pfnSetThreadUILanguage(LangId);
}

Referenced by _tmain(), cmd_start(), Execute(), SetConsoleCPState(), and wmain().

FormatMessageSafeW()

DWORD WINAPI FormatMessageSafeW	(	IN DWORD	dwFlags,
		IN LPCVOID lpSource	OPTIONAL,
		IN DWORD	dwMessageId,
		IN DWORD	dwLanguageId,
		OUT LPWSTR	lpBuffer,
		IN DWORD	nSize,
		IN va_list *Arguments	OPTIONAL
	)

Definition at line 254 of file utils.c.

{
    DWORD dwLength = 0;
 
    _SEH2_TRY
    {
        /*
         * Retrieve the message string. Wrap in SEH
         * to protect from invalid string parameters.
         */
        _SEH2_TRY
        {
            dwLength = FormatMessageW(dwFlags,
                                      lpSource,
                                      dwMessageId,
                                      dwLanguageId,
                                      lpBuffer,
                                      nSize,
                                      Arguments);
        }
        _SEH2_EXCEPT(EXCEPTION_EXECUTE_HANDLER)
        {
            dwLength = 0;
 
            /*
             * An exception occurred while calling FormatMessage, this is usually
             * the sign that a parameter was invalid, either 'lpBuffer' was NULL
             * but we did not pass the flag FORMAT_MESSAGE_ALLOCATE_BUFFER, or the
             * array pointer 'Arguments' was NULL or did not contain enough elements,
             * and we did not pass the flag FORMAT_MESSAGE_IGNORE_INSERTS, and the
             * message string expected too many inserts.
             * In this last case only, we can call again FormatMessage but ignore
             * explicitly the inserts. The string that we will return to the user
             * will not be pre-formatted.
             */
            if (((dwFlags & FORMAT_MESSAGE_ALLOCATE_BUFFER) || lpBuffer) &&
                !(dwFlags & FORMAT_MESSAGE_IGNORE_INSERTS))
            {
                /* Remove any possible harmful flags and always ignore inserts */
                dwFlags &= ~FORMAT_MESSAGE_ARGUMENT_ARRAY;
                dwFlags |=  FORMAT_MESSAGE_IGNORE_INSERTS;
 
                /* If this call also throws an exception, we are really dead */
                dwLength = FormatMessageW(dwFlags,
                                          lpSource,
                                          dwMessageId,
                                          dwLanguageId,
                                          lpBuffer,
                                          nSize,
                                          NULL /* Arguments */);
            }
        }
        _SEH2_END;
    }
    _SEH2_FINALLY
    {
    }
    _SEH2_END;
 
    return dwLength;
}

Referenced by ConMsgPrintfV(), and ConResMsgPrintfExV().

IsConsoleHandle()

BOOL IsConsoleHandle

(

IN HANDLE

hHandle

)

Definition at line 419 of file utils.c.

{
    DWORD dwMode;
 
    /* Check whether the handle may be that of a console... */
    if ((GetFileType(hHandle) & ~FILE_TYPE_REMOTE) != FILE_TYPE_CHAR)
        return FALSE;
 
    /*
     * It may be. Perform another test. The idea comes from the
     * MSDN description of the WriteConsole API:
     *
     * "WriteConsole fails if it is used with a standard handle
     *  that is redirected to a file. If an application processes
     *  multilingual output that can be redirected, determine whether
     *  the output handle is a console handle (one method is to call
     *  the GetConsoleMode function and check whether it succeeds).
     *  If the handle is a console handle, call WriteConsole. If the
     *  handle is not a console handle, the output is redirected and
     *  you should call WriteFile to perform the I/O."
     */
    return GetConsoleMode(hHandle, &dwMode);
}

IsTTYHandle()

BOOL IsTTYHandle

(

IN HANDLE

hHandle

)

Definition at line 393 of file utils.c.

{
    /*
     * More general test than IsConsoleHandle(). Consoles, as well as serial
     * (communications) ports, etc... verify this test, but only consoles
     * 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);
}

Referenced by ConClearLine(), ConClearScreen(), ConGetScreenInfo(), and ConRingBell().

K32LoadStringExW()

INT WINAPI K32LoadStringExW	(	IN HINSTANCE hInstance	OPTIONAL,
		IN UINT	uID,
		IN LANGID	LanguageId,
		OUT LPWSTR	lpBuffer,
		IN INT	nBufferMax
	)

Definition at line 99 of file utils.c.

{
    HRSRC hrsrc;
    HGLOBAL hmem;
    WCHAR *p;
    UINT i;
 
    if (!lpBuffer)
        return 0;
 
    /* Use LOWORD (incremented by 1) as ResourceID */
    /* There are always blocks of 16 strings */
    hrsrc = FindResourceExW(hInstance,
                            (LPCWSTR)RT_STRING,
                            MAKEINTRESOURCEW((LOWORD(uID) >> 4) + 1),
                            LanguageId);
    if (!hrsrc) return 0;
 
    hmem = LoadResource(hInstance, hrsrc);
    if (!hmem) return 0;
 
    p = LockResource(hmem);
    // FreeResource(hmem);
 
    /* Find the string we're looking for */
    uID &= 0x000F; /* Position in the block, same as % 16 */
    for (i = 0; i < uID; i++)
        p += *p + 1;
 
    /*
     * If nBufferMax == 0, then return a read-only pointer
     * to the resource itself in lpBuffer it is assumed that
     * lpBuffer is actually a (LPWSTR*).
     */
    if (nBufferMax == 0)
    {
        *((LPWSTR*)lpBuffer) = p + 1;
        return *p;
    }
 
    i = min(nBufferMax - 1, *p);
    if (i > 0)
    {
        memcpy(lpBuffer, p + 1, i * sizeof(WCHAR));
        lpBuffer[i] = L'\0';
    }
    else
    {
        if (nBufferMax > 1)
        {
            lpBuffer[0] = L'\0';
            return 0;
        }
    }
 
    return i;
}

Referenced by ConResMsgPrintfExV(), ConResPrintfExV(), ConResPutsEx(), and K32LoadStringW().

K32LoadStringW()

INT WINAPI K32LoadStringW	(	IN HINSTANCE hInstance	OPTIONAL,
		IN UINT	uID,
		OUT LPWSTR	lpBuffer,
		IN INT	nBufferMax
	)

Definition at line 173 of file utils.c.

{
    // NOTE: Instead of using LANG_NEUTRAL, one might use LANG_USER_DEFAULT...
    return K32LoadStringExW(hInstance, uID,
                            MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL),
                            lpBuffer, nBufferMax);
}

Referenced by ConResPagingEx(), HelpCommand(), HelpCommandList(), PagePrompt(), Usage(), WlanPrintCurrentStatus(), WlanScan(), and wmain().